Contract headers
Design stance: Settlement law is encoded in non-upgradeable cores (PoV Gate → EMT → Settlement flip; One-Claim; Fee burn). Tunables (checklists, clocks, splits) live behind a ParameterStore controlled by Governor+Timelock with bounds. All modules emit receipts (PoV hash, claim id, burn hash) for audit replay.
A. Common types & EIP-712
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
library Types {
// Role tags (Attestor Registry)
bytes32 constant ROLE_INSPECTOR = keccak256("INSPECTOR");
bytes32 constant ROLE_TERMINAL = keccak256("TERMINAL");
bytes32 constant ROLE_CARRIER = keccak256("CARRIER");
bytes32 constant ROLE_DC3PL = keccak256("DC_3PL");
bytes32 constant ROLE_REGISTRY = keccak256("REGISTRY");
bytes32 constant ROLE_METROLOGY = keccak256("METROLOGY");
bytes32 constant ROLE_SENSOR_OEM = keccak256("SENSOR_OEM");
// Domain tags
bytes8 constant CLM_DOMAIN = 0x45444d412f434c4d; // "EDMA/CLM"
bytes4 constant CLM_V1 = 0x00000001;
struct Attestation {
bytes32 role; // e.g. ROLE_INSPECTOR
bytes32 entityId; // registry id for the signer
bytes32 keyId; // current active key id
bytes signature; // EIP-712 / secp256k1 signature
}
struct ProofBundle {
bytes32 schemaId; // keccak256("TRADE.ON_BOARD.v1")
bytes32 povHash; // sha256(canonical_json_bytes)
bytes dossierBytes; // canonical JSON (optional echo)
bytes keyBlob; // normalized identity fields blob
Attestation[] atts; // role-signed attestations bound to povHash
}
}EIP-712 typed data (attestor side, summary): TypedData(domain="EDMA/POV", message={schemaId, orderOrListing, stageOrUnit, povHash}, roleKey).
B. PoV Gate
interface IPoVGate {
function submitProof(Types.ProofBundle calldata pb, bytes32 claimIdPreview)
external returns (bytes32 gatePassId, bytes32 claimId);
event GatePass(bytes32 indexed schemaId, bytes32 indexed claimId, bytes32 povHash, address caller);
// Errors (canonical)
error E_CANONICAL_DRIFT(); error E_FORMAT_INVALID(); error E_SET_NOT_SORTED();
error E_QUORUM_MISSING(); error E_STALE_ATTEST(); error E_HASH_MISMATCH();
error E_PENDING_FUNDS(); error E_ONECLAIM_TAKEN(); error E_KEY_REVOKED();
}Validates: schema, quorum, freshness, equality on povHash, must-fund (Trade post-production), and atomically reserves One-Claim.
Returns: a gatePassId consumed by Settlement (Trade) or Tokens (mint/settle).
C. One-Claim
interface IOneClaim {
function reserve(bytes32 claimId) external; // only Gate
function finalize(bytes32 claimId) external; // Gate/Settlement/Tokens
function status(bytes32 claimId) external view returns (uint8); // 0 FREE,1 RESERVED,2 FINAL
event ClaimFinalized(bytes32 indexed claimId);
error AlreadyTaken(); error NotReserved();
}Reserve→finalize: happens in the same tx as EMT/settle to prevent races.
D. EMT (Event/Milestone Token)
interface IEMT {
function mint(bytes32 orderId, bytes32 stageId, bytes32 subLotId,
bytes32 claimId, bytes32 povHash) external;
event EMTMinted(bytes32 indexed orderId, bytes32 indexed stageId,
bytes32 indexed subLotId, bytes32 claimId, bytes32 povHash);
error AlreadyMinted(); error InvalidStage();
}Receipt with a switch: Only Settlement flips money.
E. Trade Settlement
interface ITradeSettlement {
function release(bytes32 orderId, bytes32 stageId, bytes32 gatePassId)
external returns (uint256 amountEdsd, uint256 fee, bytes32 burnHash);
event ReleasePosted(bytes32 indexed orderId, bytes32 indexed stageId,
uint256 amountEdsd, uint256 fee, bytes32 burnHash);
// Invariants enforced: must-fund, One-Claim FINAL, fee caps, 50% burn in EDM
error E_NO_GATEPASS(); error E_NOT_FUNDED(); error E_DUP_RELEASE();
}F. Tokens
interface ITokens {
function mint(Types.ProofBundle calldata pb) external returns (uint256 tokenId, bytes32 claimId);
function settle(uint256 tokenId, address buyer) external returns (uint256 fee, bytes32 burnHash);
function retire(uint256 tokenId, address beneficiary, string calldata purpose)
external returns (uint256 fee, bytes32 burnHash);
event TokenMinted(uint256 indexed tokenId, bytes32 claimId, bytes32 povHash);
event TokenSettled(uint256 indexed tokenId, address buyer, uint256 fee, bytes32 burnHash);
event TokenRetired(uint256 indexed tokenId, address beneficiary, uint256 fee, bytes32 burnHash);
error Frozen(); error AlreadyRetired(); error NotOwner();
}Mint: binds PoV & One-Claim; settle/retire charges 4% and burns 50% in EDM.
G. Fee Router / Burner
interface IFeeRouter {
// Trade: stage fee (0.5% with per-tranche caps) — fee escrowed at award
function settleTradeFee(bytes32 orderId, bytes32 stageId, uint256 releaseAmountEdsd)
external returns (uint256 fee, bytes32 burnHash);
// Tokens: 4% per settlement/retirement
function settleTokenFee(uint256 amountEdsd)
external returns (uint256 fee, bytes32 burnHash);
event FeeBurned(bytes32 indexed ref, uint256 fee, uint256 burnedEdm, bytes32 burnTx);
error E_BURN_CONVERSION_UNAVAILABLE(); // burn-half EDM conversion failed (slippage bounds)
}If fee paid in EDSD/USD: Router converts the burn half to EDM at release, then burns; treasury-half routed to buckets. No gas burn ever.
H. Registry Mirror
interface IRegistryMirror {
function create(bytes32 programId, bytes32 serialHash, bytes32 claimId, bytes32 povHash,
bytes calldata registrySig) external returns (bytes32 mirrorId);
function replace(bytes32 mirrorId, bytes32 newSerialHash, bytes calldata registrySig) external;
event MirrorCreated(bytes32 indexed mirrorId, bytes32 indexed claimId, bytes32 programId);
event MirrorReplaced(bytes32 indexed oldId, bytes32 indexed newId);
error NotRegistry(); error Frozen();
}Mirrors: bind a serial to a single claim; later changes freeze → replace (append-only).
I. Attestor Registry
interface IAttestorRegistry {
function addAttestor(address entity, bytes32[] calldata roles, bytes32[] calldata schemaIds) external;
function setKey(address entity, bytes32 keyId, bool active) external;
function setStatus(address entity, uint8 status) external; // 0 ACTIVE,1 SUSPENDED,2 BANNED
function isActive(address entity, bytes32 role) external view returns (bool);
function keyActive(address entity, bytes32 keyId) external view returns (bool);
event AttestorAdded(address indexed entity);
event AttestorKeyRotated(address indexed entity, bytes32 keyId, bool active);
event AttestorSuspended(address indexed entity);
event AttestorBanned(address indexed entity);
}J. ParameterStore
interface IParameterStore {
function set(bytes32 key, bytes calldata value) external;
function get(bytes32 key) external view returns (bytes memory);
function bounds(bytes32 key) external view returns (bytes memory minV, bytes memory maxV, uint64 step, uint64 effectiveFrom);
event ParamChanged(bytes32 indexed key, bytes oldVal, bytes newVal, uint64 effectiveFrom);
error OutOfBounds(); error TooFast(); // rate-limits
}Examples: TRADE_REVIEW_WINDOW_HOURS (0..4), TRADE_TOPUP_DEADLINE_HOURS (12..72), payout schedules (banded), tolerance tables, treasury split (non-burn half only).
K. Governor / Timelock
interface IGovernor {
function propose(bytes calldata paramDiff) external returns (uint256 id);
function castVote(uint256 id, uint8 support, uint256 weight) external;
function queue(uint256 id) external; // into Timelock (≥72h)
function execute(uint256 id) external;
event ProposalCreated(uint256 id); event VoteCast(uint256 id, address voter, uint8 support, uint256 weight);
}
interface ITimelock {
function queue(bytes32 txHash, uint64 eta) external;
function execute(bytes32 txHash) external;
event Queued(bytes32 indexed txHash, uint64 eta); event Executed(bytes32 indexed txHash);
}Only ParameterStore/TreasurySplitter/allowlists are governed: Constitutional brakes (PoV/EMT/One-Claim/Locked→Unlocked/50% burn/fee constants) sit outside governance.
L. Treasury Splitter
interface ITreasurySplitter {
function route(bytes32 ref, uint256 amountEdsd) external; // called by FeeRouter
function setSplits(uint16 attestors, uint16 ops, uint16 builders, uint16 ecosystem, uint16 stakers) external;
event TreasuryRouted(bytes32 indexed ref, uint256 attestors, uint256 ops, uint256 builders, uint256 ecosystem, uint256 stakers);
error SplitOutOfRange();
}M. EDSD Treasury & Proof-of-Reserves
interface IProofOfReserves {
function postSnapshot(bytes32 snapshotHash, uint256 tBillNotional, uint256 cashBalance, uint64 asOf)
external; // bank/custodian attestations off-chain, hash on-chain
event PoRSnapshot(bytes32 indexed snapshotHash, uint256 tBill, uint256 cash, uint64 asOf);
}EDSD is platform-bound: mint/burn/transfer are restricted to settlement modules and whitelisted flows; cash-out after schedule completion only.
N. Bridge Gateway
interface IBridgeGateway {
function exportToken(uint256 tokenId, bytes32 dstChain) external returns (bytes32 exportRef);
function importToken(bytes32 burnProof, bytes32 claimId, bytes32 povHash) external returns (uint256 tokenId);
event ExportLocked(uint256 indexed tokenId, bytes32 dstChain, bytes32 exportRef);
event ImportMinted(uint256 indexed tokenId, bytes32 srcChain, bytes32 burnRef);
error NotCanonical(); error InvalidProof();
}Bridges: mint representations only; EDMA remains canonical for claims. EDSD and EMT are not bridged.
O. Error catalog
E_CANONICAL_DRIFT / E_FORMAT_INVALID / E_SET_NOT_SORTED / E_FILE_MISSING / E_HASH_MISMATCH: serialization & evidence hygiene
E_QUORUM_MISSING / E_STALE_ATTEST / E_KEY_REVOKED: attestor/quorum freshness
E_PENDING_FUNDS: must-fund before shipping unmet
E_ONECLAIM_TAKEN: uniqueness already finalized
E_DUP_RELEASE / AlreadyMinted / AlreadyRetired: idempotency/monotonicity
E_BURN_CONVERSION_UNAVAILABLE: burn-half conversion to EDM deferred (release waits)
P. Events you will index
GatePass(schemaId, claimId, povHash)
EMTMinted(orderId, stageId, subLotId, claimId, povHash)
ReleasePosted(orderId, stageId, amountEdsd, fee, burnHash)
TokenMinted(tokenId, claimId, povHash)
TokenSettled(tokenId, buyer, fee, burnHash)
TokenRetired(tokenId, beneficiary, fee, burnHash)
FeeBurned(ref, fee, burnedEdm, burnTx)
MirrorCreated(mirrorId, claimId, programId) / MirrorReplaced(oldId, newId)
AttestorAdded(entity) / AttestorSuspended(entity)
ParamChanged(key, oldVal, newVal, effectiveFrom)
PoRSnapshot(snapshotHash, tBill, cash, asOf)
Q. Invariants
No EMT → no release: release requires Gate PASS + EMT + One-Claim FINAL + must-fund (Trade post-production gates).
Conservation (Trade): Locked + Unlocked = funded – refunds per order at all times.
Fee constants/caps: Trade 0.5%/milestone with $5k/$25k/$50k caps; Tokens 4%; burn exact 50% in EDM at event; gas never burns.
Uniqueness: claim_id finalizes once globally; replacements are new ids with lineage; mirrors bind to exactly one claim.
Idempotency: (order, stage, subLot) or tokenId settle once; replays are no-ops.
Append-only: revocations & replacements never delete; proof pages show original + correction.
Use these headers to wire clients, index receipts, and write off-chain services (ERP/TMS/WMS/ESG). For full ABIs, event topics, and test vectors (including canonical JSON and claimId fixtures), pull the SDK or query /v1/contracts and /v1/schemas.
Last updated