Payouts & slippage
Scope & invariants:
Payouts are when money actually moves: slippage is how we bound price/timing/quantity risk so no one gets an execution they didn’t agree to. The brakes never move:
No EMT, no funds (Trade):
Must-fund before shipping: top-up after Pre-Ship EMT
One-Claim uniqueness:
Locked EDSD → Unlocked EDSD only on proof:
50% of every protocol fee burns in EDM at the event: never discounted
Gas: tiny, pass-through, and never burned.
EDSD: platform-bound; off-platform cash-out is available only after schedule completion (Trade).
A) TOKENS — Payouts & price slippage
A1. Payout sequence (atomic at fill/retire):
Match: price-time priority finds counterparty; execution price = maker’s resting price (RFQ fills follow agreed quote).
Settle or Retire: transfer or retirement finalizes; protocol fee = 4% of notional (default 2% buyer + 2% seller).
Burn: Router converts the burn half into EDM and destroys it now; FeeBurned emits the burn hash.
Credit/Debit: buyer EDSD debited; seller EDSD credited (net of seller’s 2%); receipts post and the proof page updates.
Net flows (default 2/2 split):
Buyer pays: Price × (1 + 0.02)
Seller receives: Price × (1 − 0.02)
Burn: Price × 0.02 in EDM; Treasury: Price × 0.02
A2. Price slippage controls:
Limit orders only (no blind market order): your limit is the hard bound.
Optional max slippage % (UI/API): converts to a stricter limit around your intended level.
IOC: fills what’s available within bounds and cancels the rest; FOK requires full size within bounds or cancels.
Rounding & “dust”:
Each bucket: has lot size (e.g., 1 t, 1 MWh) and tick (e.g., $0.01).
If size cannot be filled exactly: the engine fills down to the nearest lot; dust remains as resting qty or can be RFQ’d as a block.
A3. Failure codes (why a fill won’t pay):
E_LISTING_FROZEN: revocation/mirror issue
E_ONECLAIM_TAKEN: duplicate serial/claim tried elsewhere
E_KYC_BLOCKED: identity not cleared
E_FUNDS_SHORT: insufficient EDSD on buyer
E_PRICE_BOUND: limit/slippage would be exceeded
A4. Example (Tokens):
Buy 500 t @ $18.00: Gross $9,000 → fee $360 → burn $180 EDM, treasury $180.
Buyer pays: $9,180; seller receives: $8,820; receipt shows: PoV hash, One-Claim ref, fill price/qty, fee line, burn hash.
B) TRADE — Payouts (milestone releases) & “slippage” types
B1. Payout sequence (per stage Release):
Gate PASS → EMT: the dossier (PSI/COA, BL + seal photo/number, customs EDI, DC receipt & QA, temp proofs) passes; the stage EMT mints.
Buyer review (optional): 0–4 h window; Block pauses release with reason; do nothing → auto-release.
Release: Locked EDSD → Unlocked EDSD for the pre-assigned slice; assignment credits (seller→partners) auto-settle if linked to this stage.
Fee & burn: stage fee 0.5% of release (per-tranche cap) is consumed from pre-paid fee escrow; 50% burns in EDM now; receipt posts with the burn hash.
Multi-supplier / partial:
Split containers or staggered vessels: mint child EMTs; each child flips its sub-slice; remainder waits.
Variance (short-shipment/damage/shelf-life): Exceptions compute the adjusted amount; only that amount flips and burns; remainder cancels or is replaced.
Assignments & cash-out:
Funded-on-proof assignment (carrier/SGS/warehouse/OEM): settles automatically; 1% assignment fee posts (no burn).
Off-platform cash-out: available only after schedule completion; 0.5% cash-out fee posts (no burn).
B2. “Slippage” in Trade (what it is—and isn’t):
Price slippage: none. Award fixes price per unit; releases don’t re-quote.
Timing slippage: if top-up is late, releases show PENDING_FUNDS even with perfect proof; payout waits until funding lands (must-fund).
Quality/quantity slippage: handled by the contract’s variance table (deduct & release, partial, or replace); never silent.
B3. Burn-conversion guard (rare):
If the Router cannot convert the burn half to EDM within slippage bounds: it returns E_BURN_CONVERSION_UNAVAILABLE; the release is deferred with a visible flag and retried promptly (governed policy). We do not settle without burning.
B4. Example (Trade):
On-Board $3,960,000 tranche: Stage fee $19,800 (under $25k cap) → burn $9,900 EDM; treasury $9,900.
Assignments linked to On-Board (e.g., carrier $220k): settle; assignment fee $2,200 posts.
Seller now holds Unlocked EDSD: can pay in-platform; off-platform cash-out waits until schedule completion.
C) Precision, rounding & receipts
Decimals: amounts are decimal strings per schema precision (no floats).
Rounding: fee, treasury, and burn round down to atomic unit; the 1-unit remainder accrues to Ops and is logged.
Receipts: every payout includes amount, fee, burn hash, net to each party, PoV hash, claim_id (and mirror id on Tokens).
Ledgers: Trade ledgers reconcile escrow_start − Σ(stage_fees) = escrow_end; Tokens ledgers show fee/burn per fill/retire.
D) API hooks (what you wire in)
Tokens:
Orders: POST /v1/tokens/orders (limit/IOC/FOK, optional max_slippage_bps)
Fills: webhook tokens.settlement.posted { price, qty, fee, burnHash }
Retires: webhook tokens.retirement.proofpack.ready (proof links)
Trade:
Milestones: POST /v1/trade/proof/{order}/{stage} → PASS/FAIL; POST /v1/trade/release/{order}/{stage}
Events: trade.milestone.passed → trade.release.posted { amountEdsd, fee, burnHash }
Flags: trade.contract.pending_funds, trade.slice.frozen/unfrozen
Plain recap
Last updated