Settlement contracts
What settlement contracts do
They are the pieces that move money after proof. In Trade, a settlement contract listens for a Gate PASS + EMT mint and flips the correct slice from Locked EDSD to Unlocked EDSD; in Tokens, it finalizes a buy/retire and posts the fee. Settlement never guesses, never front-runs, and never pays early—No EMT, no funds is enforced in code.
The two paths we settle
Trade (milestone releases): A release is an EMT-triggered state change for one stage and one sub-lot. The contract:
checks the Gate PASS, One-Claim reserve and must-fund precondition;
flips the pre-assigned slice Locked EDSD → Unlocked EDSD;
calls the Fee Router/Burner to apply the 0.5% stage fee (per-tranche caps) and burn 50% in EDM;
emits a human-readable receipt (amount, net, burn hash, proof links).
Tokens (settlement / retirement): A settlement is the final transfer (or retirement) of a PoV-verified unit. The contract:
re-checks PoV badge + One-Claim;
transfers or retires the token;
applies the 4% fee (default 2% buyer / 2% seller), burns 50% in EDM at that instant;
emits a receipt and proof pack pointer.
Trade release flow
Business story. A stage is ready. Attestors submit the dossier; PoV Gate passes; the EMT mints. In the same transaction, the settlement contract flips the money and records the burn. The seller sees Unlocked EDSD immediately; any funded-on-proof assignments tied to that stage settle automatically.
On-chain steps (atomic):
Gate PASS returns; One-Claim RESERVE succeeds; must-fund (Locked EDSD present) checks.
EMT mint for the stage/sub-lot.
Flip the slice: Locked EDSD → Unlocked EDSD (credited to the supplier’s balance).
Fee Router/Burner: post the stage fee (obey caps) and burn 50% in EDM; record burn_hash.
Finalize One-Claim and emit ReleasePosted(order, stage, sublot, amount, fee, burn_hash).
If any step fails, everything reverts—no cross-block holds, no partial side effects.
What the contract enforces
No EMT → no release. A PASS without an EMT cannot flip funds.
Conservation of EDSD. Per order: Locked + Unlocked = funded – refunds at all times.
Caps respected. Stage fee ≤ per-tranche cap; exactly 50% of the stage fee burns in EDM at release.
Must-fund before shipping. On-Board/Customs/Arrival cannot release unless the top-up is present as Locked EDSD.
Schedule completion gating. Off-platform cash-out remains disabled until the seller’s schedule completes (the contract exposes a boolean flag used by the cash-out module).
Idempotency. Replays with the same id are safely ignored; each release has a unique (order, stage, sublot) key.
Freeze-narrow. Revocations pause only downstream releases; already-released slices stay released.
Variance & partial pay
When the MPA’s variance math applies (short shipment, damage, shelf-life), the settlement contract accepts the adjusted amount computed by the Exceptions module:
mints the EMT for the adjusted slice;
flips only that amount Locked → Unlocked;
records the deduction reason on the receipt;
leaves the remainder canceled or bound to a replacement sub-lot.
No side negotiations—just math the two sides agreed beforehand.
Assignments and cash-out
Funded-on-proof assignments (seller → whitelisted partners). These are created earlier; the settlement contract settles them automatically when the linked stage releases, and books the 1% assignment fee (not burned).
Cash-out. Off-platform redemption runs in the cash-out module; settlement only flips the completion flag when the last stage clears. Cash-out posts the 0.5% fee (not burned).
Tokens settlement flow
Check listing PoV and One-Claim; compute fee (4%).
Transfer or retire the unit; mark retirement irreversible with a receipt URI.
Router/Burner: charge fee; burn 50% of it in EDM; emit SettlementPosted(listing, amount, fee, burn_hash).
If the listing is frozen or the serial is taken, it reverts with a clear code.
Interfaces you actually use
Trade
POST /v1/trade/release/{order}/{stage} — consumes Gate PASS; emits ReleasePosted with burn hash and net amounts.
GET /v1/trade/releases/{release_id} — returns receipt (proof links, fee lines, Locked/Unlocked deltas).
Tokens
POST /v1/tokens/settle — buy/retire; emits SettlementPosted with burn hash and the retirement proof link.
Webhooks
trade.milestone.passed → trade.release.posted
tokens.settlement.posted
fee.burn.posted (common)
All money-changing calls require an Idempotency-Key.
Security properties
Admissibility first. Settlement calls abort without a Gate PASS; the sequencer cannot force a release.
Atomic uniqueness. One-Claim reserve/finalize runs inside the release; duplicates can’t leak through.
No early leakage. Only Unlocked EDSD can pay invoices; off-platform cash-out remains disabled until completion.
Append-only history. Replacements and partials record lineage; burns remain immutable.
Audit-friendly. Receipts carry PoV hash, EMT id (or token id), fee line, and burn hash; blobs on L1 anchor the lot.
Governance knobs
Payout schedule bands (e.g., 20/60/20 vs 20/10/70 within lanes).
Review window and top-up deadline bounds.
Variance tables (tolerance bands) per lane.
Event formatting and Explorer fields.
Governance cannot: release without EMT/PASS, weaken One-Claim, skip must-fund before shipping, change Locked→Unlocked rules, or discount the 50% burn.
Plain recap
Last updated