Escrow Types
The program implements two independent escrow shapes. They share the per-mint program vault but use different state accounts, PDAs, and instructions — pick the one that matches your trust model.
Two-party escrow
A depositor locks tokens that a claim authority can release to any recipient. The deposit is recorded in an EscrowDeposit account, keyed by the claim authority.
- Deposit — the depositor moves tokens into the vault and creates the
EscrowDeposit(deposit). - Claim — the claim authority (a required signer) releases the funds to a claimant and closes the deposit (claim).
- Reclaim — if never claimed, the depositor (or their sponsor) pulls the funds back and closes the deposit (reclaim).
Use it when one party should be able to direct a locked payment to a recipient chosen later — e.g. a sponsored transfer where the claim authority hands the tokens to whoever ultimately claims them. The depositor's escrow PDA is derived from the claim authority, so a given claim authority has one open deposit at a time.
Three-party mediated escrow
A depositor locks tokens naming a mediator and a beneficiary. The mediator decides where the funds go — to the beneficiary or back to the depositor — without ever taking custody. The deposit is recorded in a MediatedEscrowDeposit account, keyed by a caller-chosen id.
- Mediated deposit — the depositor locks funds, naming the mediator, beneficiary, an optional rent collector, and an optional expiry (mediated deposit).
- Mediated release — the mediator (a required signer) releases to the depositor or the beneficiary and closes the deposit (mediated release).
- Mediated reclaim — if an expiry was set and has passed, the depositor reclaims the funds without the mediator (mediated reclaim).
Use it for conditional settlement with a neutral third party — escrowed payments, dispute resolution, or milestone releases. Because the PDA is keyed by an arbitrary id, a depositor can have many concurrent mediated escrows. See Expiry & Reclaim for the fallback path.
Choosing between them
| Two-party | Mediated (three-party) | |
|---|---|---|
| Parties | depositor, claim authority | depositor, mediator, beneficiary |
| Who releases | claim authority → any claimant | mediator → depositor or beneficiary |
| State account | EscrowDeposit | MediatedEscrowDeposit |
| Keyed by | claim authority | arbitrary id |
| Depositor fallback | reclaim (anytime, if unclaimed) | mediated_reclaim (only after expiry) |
| Sponsor support | yes (recorded on the deposit) | rent collector + expiry instead |
Both are documented field-by-field in Account Types.