PoV gate
What the Gate is
The PoV Gate is the contract that answers a single question every time you try to change state: “Do the submitted facts satisfy the checklist we agreed?” If yes, the Gate returns PASS, and the transaction can mint the EMT (Trade) or settle/retire (Tokens). If not, it returns FAIL with a human-readable reason. The Gate itself never pays anyone; it simply decides admissibility. No PASS → no EMT → no funds.
Inputs the Gate expects
What you claim: order/listing id, stage (Trade) or unit (Tokens), and the schema_id (the named checklist).
What you prove: a PoV hash (canonical JSON + file digests) and a set of role-signed attestations (inspector, terminal/carrier, DC/3PL, registry/oracle, sensor OEM).
Who may sign: public keys and roles from the Attestor Registry (active, non-revoked).
Uniqueness key: the minimal identity for this event/unit (e.g., {BL, seal, containers} or {serial}) used by One-Claim.
Funding precondition (Trade): for post-production gates, required Locked EDSD must be present (must-fund before shipping).
The Gate binds all of this to a single PoV hash. Filenames don’t matter; bytes and signatures do.
What the Gate checks
The Gate compares the dossier against the checklist you wrote into the MPA (Trade) or the listing (Tokens), then enforces uniqueness and funding preconditions.
Checklist match: Required fields exist and are valid for this gate: PSI/COA, BL + seal number & photo, customs EDI, DC receipt & QA, temperature ranges, method/region for tokens.
Role-diverse quorum: The right mix of roles signed within their freshness windows using active keys.
Equality: All counted attestations reference the same PoV hash and the same order/listing.
One-Claim reserve: The uniqueness key is free; the Gate atomically reserves it for this tx.
Funding present (Trade): For On-Board/Customs/Arrival, the top-up is deposited as Locked EDSD.
No revocation: None of the counted attestations is revoked/expired.
PASS returns a handle the caller uses immediately to mint the EMT or settle. FAIL returns a code and a plain explanation (e.g., E_SEAL_MISMATCH, E_PENDING_FUNDS, E_ONECLAIM_TAKEN, E_QUORUM_MISSING, E_STALE_ATTEST).
Reserve → finalize
One-Claim runs inside the Gate so races can’t leak value. In the same transaction:
Gate returns PASS and reserves the claim id;
Caller mints the EMT (or settles/retire in Tokens);
Treasury/Router flips Locked EDSD → Unlocked EDSD, posts the protocol-fee line, and burns 50% of that stage’s fee in EDM;
One-Claim marks the claim finalized.
If anything fails, the whole transaction reverts; there is no cross-block hold.
Buyer review window
Operationally, the buyer may set a short review window (e.g., up to 4h). The Gate still decides PASS/FAIL. If the buyer taps Block during the window, the release is paused and the case opens; if the buyer does nothing, auto-release proceeds. Either way, a release can’t happen on FAIL, and a success can’t be “released early” without the Gate’s PASS.
Failure modes you’ll actually see
E_PENDING_FUNDS: top-up missing; gate can’t open.
E_SEAL_MISMATCH: BL/containers don’t match the seal photo/number.
E_LOT_LIST_MISMATCH: PSI/COA lot list differs from the order.
E_TEMP_OUT_OF_RANGE: cold-chain breach beyond the contract band.
E_ONECLAIM_TAKEN: uniqueness key already finalized elsewhere.
E_QUORUM_MISSING: not enough role diversity or key not active.
E_STALE_ATTEST: attestation outside freshness window or revoked.
Each error includes a fix path (upload corrected file, re-inspect, variance rule, fund now).
Interfaces you integrate
API (Trade)
POST /v1/trade/proof/{order_id}/{stage} — submit dossier (PoV hash + attestor proofs) → returns PASS/FAIL, reason, and (on PASS) a gate_pass_id to call release.
POST /v1/trade/release/{order_id}/{stage} — consumes gate_pass_id → mints EMT, flips Locked→Unlocked EDSD, posts fee & burn hash, returns receipt.
API (Tokens)
POST /v1/tokens/settle — PoV check + One-Claim + settlement + fee & burn in one call; returns receipt + proof link.
Webhooks
pov.gate.pass / pov.gate.fail — result + reason; includes PoV hash and claim id preview.
oneclaim.finalized — uniqueness finalized; references EMT/settlement id.
trade.milestone.passed / trade.release.posted — business events downstream.
Idempotency keys are honored on all POSTs that change state.
Security properties
Determinism: The same dossier always yields the same result; canonical JSON + digests prevent filename tricks.
Atomic uniqueness: Reserve + finalize share the same transaction as EMT/settlement; duplicates are impossible.
Non-bypassable: The sequencer can’t force a release; PASS is required and comes only from the Gate.
Narrow freezes: Revocations freeze downstream slices only; paid slices remain paid; history shows the delta.
Auditability: Receipts include the PoV hash, EMT id, fee line and burn hash, and the One-Claim reference; blobs on L1 anchor it all.
Governance knobs
Add/retire schemas, adjust quorum composition, set freshness windows, and tune review window and top-up deadlines inside safe ranges.
It cannot allow release without PASS, weaken One-Claim, remove must-fund before shipping, or discount the 50% burn.
Operator checklist
Your job is to make “PASS” easy and predictable: write plain checklists, capture the exact files, and submit once. If a gate stays red, read the reason and fix that point—no email archaeology.
Keep checklists human: what counts as pass, line by line.
Use registered attestors; check their status in the Registry.
Verify the PoV hash before you submit; your attestors should see the same hash.
Fund on time; expect E_PENDING_FUNDS if you don’t.
If blocked, open the case; the Dispute Pack shows everything you need.
Plain recap
Last updated