Package deposits is a refundable security deposit with condition-gated, partially-forfeitable settlement.
The shape
A HOLDER (landlord, service provider, equipment lessor) opens an agreement naming a DEPOSITOR, an exact amount, a term, and a FORFEIT CEILING — the most the holder may ever claim out of the deposit. The depositor reads all of it, including the named arbiter, and consents by FUNDING. At the end of the term the holder may file a claim up to the ceiling; the depositor may accept it, dispute it to the arbiter, or let it stand. Whatever is not awarded to the holder is refunded to the depositor.
That makes this the first realm in the portfolio where ONE POT SPLITS PARTIALLY BETWEEN TWO RIVAL CLAIMANTS by a conditional rule, and the first where the depositor's own money is at risk of partial loss. `crowdfund` is all-or-nothing, `auction` is winner-takes, `loans` is principal-out / larger-back, `reimbursements` is approver-gated to a single claimant. See DISCOVERY.md for the §7 gate and the five candidates it killed.
Lifecycle
Example
1OpenAgreement -> open (nothing held; depositor has not consented)
2Fund -> funded (depositor attaches the exact amount)
3FileClaim -> claimed (holder, after term end, within the claim window)
4Dispute -> disputed (depositor, within the dispute window)
5ResolveDispute -> settled (arbiter awards 0..claim to the holder)
Five routes reach `settled`, and THREE OF THEM ARE PERMISSIONLESS, so no terminal state depends on a party acting:
Example
1AcceptClaim depositor agrees award = claim
2SettleUndisputed ANYONE, dispute window up award = claim
3ReleaseUnclaimed ANYONE, claim window up award = 0 (holder never claimed)
4LapseDispute ANYONE, arbiter silent award = 0 (claim unsubstantiated)
5Release holder waives early award = 0
Custody
Coins are held by the realm from Fund until settlement, then become PULL-CLAIMABLE through `p/feeledger`. Nothing is ever pushed: a settlement credits balances and the parties `Claim` them, which removes the grief and reentrancy surface a push settlement would have.
The conservation invariant carries one bucket more than the sibling realms:
Example
1Held == locked + contested + feeledger.Liabilities()
`locked` and `contested` are DISJOINT — a disputed deposit moves out of one and into the other in the same transaction. The split exists because a contested deposit is the one balance whose destination is not yet decided by this realm's own rules; keeping it separate makes "what is the arbiter deciding over" a readable number rather than an inference.
The fee
The protocol fee applies ONLY to the portion AWARDED to the holder. A refund to the depositor is returned in full at fee 0, matching `auction`'s rule that a refund is not a fee event. A fully-refunded deposit therefore costs the depositor nothing.
What the depositor is trusting, stated plainly
- The FORFEIT CEILING is the depositor's hard protection, and they consent to it by funding. Nothing can take more than the ceiling.
- If NO ARBITER is named, an unaccepted claim STANDS once the dispute window passes. That is a legitimate configuration — a deposit with a low ceiling and no arbiter — and the depositor sees `Arbiter() == ""` before funding.
- If an arbiter IS named, `LapseDispute` awards the contested amount to the DEPOSITOR. A disappeared arbiter cannot strand funds, and the holder — who chose the arbiter — bears the cost of that choice failing.
- Residual, not fixed here: a hostile depositor can dispute a legitimate claim to delay settlement by one dispute window. The delay is bounded and costs the depositor the same wait; it is disclosed rather than mitigated.
- The realm settles MONEY. Whether the damage was real is off-chain; this realm binds the ceiling, the windows, and the arbiter's authority.
Scope
Single-denom (ugnot), single depositor per agreement, flat ceiling. Graduated forfeiture over damage severity (`p/tiers`) is a deliberate v2 candidate, not an omission — see DISCOVERY.md §5.
