Matching & fills
Scope (two rails, two matching models):
Tokens marketplace (Energy 1 MWh, Carbon 1 t, hourly attributes): price-time priority continuous book with partial fills, IOC/FOK support, and optional RFQ for block size. Fill = trade or retirement; 4% protocol fee applies at fill; 50% burns in EDM in the same tx.
Trade marketplace (commodities/CPG): RFQ→bid→award (no crossing LOB). Fill = milestone release after EMT PASS; 0.5%/milestone (capped) applies at each paid stage; 50% burns in EDM at each release.
Settlement law never changes: No EMT, no funds · Must-fund before shipping · One-Claim · Locked EDSD → Unlocked EDSD only on proof · 50% burn on every protocol fee.
A) TOKENS — Matching rules
A1. Book & priority:
Fungibility bucket: program, method, region, vintage (Carbon) or region/standard (Energy).
Price-time priority within each bucket: best price first, then earliest time.
Aggregated levels: the engine aggregates by price; individual orders keep time priority inside level.
A2. Order types & TIF:
Limit GTC/GTD: Good-Til-Cancel/Date
Immediate-or-Cancel (IOC):
Fill-or-Kill (FOK):
Block RFQ: off-book workflow; still settles on-chain at fill
Ticks & lots: per bucket (e.g., Carbon tick $0.01/t; lot 1 t; Energy tick $0.01/MWh; lot 1 MWh).
A3. Matching & partial fills:
Incoming buy: matches the best ask while price_buy ≥ price_ask; partial fills are allowed until quantity or price constraint is hit.
Incoming sell: matches the best bid while price_sell ≤ price_bid.
Partial fills: retain the order’s time priority for the remainder at original price.
Self-trade prevention: same participant cannot match against their own resting order; incoming order is reduced/canceled (IOC/FOK rules respected).
A4. Slippage controls (buyer/seller protection):
Limit price: the hard cap/floor.
Optional max slippage % per order (UI/API): translates to a derived price cap/floor around the mid or the submitted limit (configurable).
IOC+slippage: fill immediately within limit & slippage; cancel the rest.
FOK: fill entire qty within limit & slippage or cancel.
A5. Freeze handling (admissibility events):
If a listing or bucket is FROZEN (revocation/mirror issue): matching halts for impacted orders; standing orders remain in book but cannot execute.
When UNFROZEN: matching resumes with preserved time priority.
A fill cannot occur without PoV-valid state: for Retire, mirror must be ACTIVE if the program requires it.
A6. Fill & settlement sequence (atomic):
Match found: execution price = resting price (maker-taker convention; governance may allow midpoint crossing for block RFQ).
Settle or Retire tx executes: transfer or retirement finalizes; protocol fee = 4%; burn 50% in EDM in the same tx; FeeBurned emits burnHash.
Receipts for both sides (or beneficiary on retire): include PoV hash, One-Claim ref, fill price/qty, fee line, burn hash.
A7. API & webhooks (Tokens):
Orders: POST /v1/tokens/orders, DELETE /v1/tokens/orders/{id}, GET /v1/tokens/books?symbol=…
Fills: webhooks tokens.settlement.posted (price, qty, fee, burn hash), tokens.retirement.proofpack.ready
Freezes: tokens.listing.frozen/unfrozen with reason
RFQ block: POST /v1/tokens/rfq, responses from approved makers; fill settles on-chain as above
B) TRADE — Matching & “fills” (RFQ → award → milestone releases)
B1. RFQ → bids → award (matching logic):
RFQ specifies: product/spec, route, Incoterm, milestones & payout schedule (e.g., 20/60/20), and evidence checklists (schemas).
Suppliers bid: price, fillable % (10–100), ready windows, compliance notes; bids are sealed by default (transparent mode is governable).
Matching/award: buyer selects/auto-mixes suppliers to reach 100% coverage:
Manual: buyer composes award set.
Auto-mix (governed option): solver minimizes total landed cost under constraints (coverage, min/max per supplier, readiness, risk/score). Ties broken by earliest ready window then bid timestamp.
Output: a single MPA (Master Purchase Agreement) with per-supplier stage slices and top-up deadlines (must-fund before shipping). No protocol fees yet.
B2. What a “fill” is in Trade:
A “fill” is a milestone release: when a stage passes PoV → EMT and the slice pays:
Pre-Ship: production proven (PSI/COA) → slice releases
On-Board: BL + seal photo/number + containers match → slice releases
Customs / Arrival & QA: clearance and QA → slice releases
Each release charges 0.5% (capped per tranche): burns 50% in EDM now; the burn hash lands on the receipt.
B3. Partial & multi-supplier fills:
Partial pass (split containers, staggered vessels): each sub-lot mints its own EMT; the matching sub-slice pays; remainder waits.
Variance (short-shipment, damage, shelf-life): Exceptions module computes the adjusted amount per the MPA’s variance table; settlement flips and burns on the adjusted release; remainder cancels or is replaced.
B4. Slippage concepts (Trade):
Price is fixed at award: there is no price slippage at release.
Timing slippage: controlled by top-up deadlines and the Revocation SLA. If a buyer misses the top-up, release remains PENDING_FUNDS even with perfect proof.
Quality slippage: handled by variance math; releases reflect the net amount.
B5. API & webhooks (Trade):
RFQ: POST /v1/trade/rfqs, POST /v1/trade/rfqs/{id}/bids, POST /v1/trade/awards
Milestones: POST /v1/trade/proof/{order}/{stage} (Gate PASS/FAIL), POST /v1/trade/release/{order}/{stage}
Events: trade.milestone.passed → trade.release.posted (amount, fee, burn hash); trade.slice.frozen/unfrozen; sla.revocation.breached
C) Conduct, halts, and integrity controls
Self-trade / wash trade (Tokens): blocked; surveillance flags patterns; accounts may be suspended.
Halt conditions: bucket/listing FROZEN (revocation/mirror), status page anchor-guarded (DA lag); in Trade, PENDING_FUNDS halts releases downstream.
One-Claim: prevents the same evidence from filling twice; duplicate attempts revert with E_ONECLAIM_TAKEN.
Disclosure: every fill/release links to a proof page with PoV hash, claim id, and, when relevant, mirror status.
D) Maker/taker economics (Tokens) — optional, governed
Protocol fee remains 4% total: regardless of maker/taker role.
Optional maker incentives (if governance enables): budgeted only from the treasury half (never from the burn half). Any rebate shows as a separate line; burns are unchanged.
Plain recap
Last updated