Governance contracts

What these contracts are

The governance contracts are the rails for changing parameters without touching the brakes. They let EDM holders propose, vote, and execute bounded updates to the marketplace and PoV layer—milestone templates, evidence checklists, SLAs, fee splits of the treasury half, and similar knobs. Every change is timelocked, diffed, and visible. Core settlement law remains outside governance: No EMT, no funds. One-Claim. Must-fund before shipping. Locked→Unlocked only on proof. 50% burn per event.

The pieces

• Governor: runs proposals, voting, delegation, and quorum checks.

• Timelock: queues approved actions for a 72-hour delay, then executes them.

• ParameterStore: a single source of truth for tunable settings (with bounds and rate limits).

• TreasurySplitter: routes the treasury half of protocol fees across buckets (attestors / network ops / builders / ecosystem / stakers) as governance decides.

Around these sit Registries (Attestor & Schema), InclusionList (critical-call allowlist for the sequencer), and UpgradeProxy guards (for rare, audited code upgrades).

What EDM holders can change

• Milestones & timing — default milestone sets per lane; buyer review window (0–4h); top-up deadline before On-Board (e.g., T-48h → T-12h).

• Evidence & quality — required fields per gate; tolerance bands; variance math for short-shipment, damage, shelf-life, cold-chain.

• Attestors & SLAs — role compositions and SLA targets, rotation cadence, reward weights, and penalty bands (slashing for bonded roles).

• Funded-on-proof scope — which whitelisted partner types (carrier, SGS, warehouse, OEM) can receive assignments in a lane.

• Treasury split (non-burn half) — allocation across attestors / network ops / builders / ecosystem / stakers within published bands.

• Transparency knobs — what the Explorer displays (proof fields, KPI panels), not the underlying facts.

Not vote-tunable, by design: No EMT, no funds, One-Claim, must-fund before shipping, Locked→Unlocked only on proof, and the 50% burn of each protocol fee.

Proposal flow

1. Draft: short EDIP with: what changes, why users benefit, how bounds are respected.

2. Temp check: informal signal; gather comments from buyers, sellers, attestors.

3. On-chain vote: EDM holders (or delegates) vote for/against; quorum and majority are enforced.

4. Timelock (72h): proposal sits visible in the queue; anyone can review the before/after values on the Explorer.

5. Execute: Timelock calls ParameterStore/TreasurySplitter to apply the new values. Receipts are emitted; Explorer updates.

Rate limits prevent rapid toggling. If a knob moved last week, it can move only a small additional step this week.

Security properties

• Bounds in storage. Even a passed vote cannot exceed min/max or allowed step.

• Fixed brakes. Contracts that enforce PoV/EMT/One-Claim/Locked→Unlocked/50% burn do not read from the ParameterStore for those foundations.

• Timelock visibility. Every change sits in public for 72 hours; downstream systems can pre-check effects.

• Non-reentrancy / idempotency. Each proposal has a unique id; execution can’t double-apply.

• Explorer diffs. The UI shows the exact numbers, who voted, and the block that applied the change.

Events & webhooks

• gov.proposal.created — title, diffs, bounds, voting window.

• gov.vote.cast — voter/delegate, weight, choice.

• gov.proposal.queued — enters Timelock with ETA.

• gov.proposal.executed — ParameterStore/TreasurySplitter updated (before/after values included).

• gov.proposal.canceled / gov.proposal.failed — outcome and reason.

ParameterStore

• TRADE_REVIEW_WINDOW_HOURS: min 0, max 4, step 1 → default 2

• TRADE_TOPUP_DEADLINE_HOURS: min 12, max 72, step 6 → default 48

• TRADE_PAYOUT_SCHEDULE: banded sets (20/60/20, 20/10/70) selectable per lane

• QC_TOLERANCE_DAMAGE_PCT: min 0, max 5, step 0.5 → default 1

• COLDCHAIN_TEMP_BAND: per lane; min/max per commodity

• ATT_SLA_LATENCY_SEC: min 60, max 3600, step 60 → default 600

• TREASURY_SPLIT: [attestors, ops, builders, ecosystem, stakers] within bands that sum to 100%

Each param is versioned with effective_from so audits can replay behavior by time.

TreasurySplitter

• On every settlement/release, the Fee Router/Burner sends the treasury half to the Splitter. Governance sets percentages within bands; burns stay fixed and out of scope.

• Live metrics per bucket (epoch totals, spend categories).

• Webhook fee.treasury.routed posts amounts and epoch ids.

• Changes to splits go through the same proposal → timelock path.

Interfaces

Read

• GET /v1/gov/params — current values + bounds + last change.

• GET /v1/gov/proposals/{id} — proposal text, diffs, votes, status.

• GET /v1/gov/treasury/splits — live split, epoch history.

Write

• POST /v1/gov/proposals — create proposal (EDM-signed).

• POST /v1/gov/vote — cast vote or delegate.

• Execution is on-chain via the Timelock; API returns receipts and links to the Explorer.

Emergency levers

• If a critical incident appears, a minimal pause can be applied to a specific module (e.g., “open new On-Board gates”) for ≤72h, visible on the status page with a post-mortem. Unpausing returns through normal governance. These controls cannot release money, bypass PoV, or change burns.

What this feels like for users

You vote on how the rail works day-to-day—milestone templates, evidence checklists, clocks, and how the treasury half supports the people who keep the rail honest. You never vote to move money early, reuse evidence, or skip burns. Every change is small, timelocked, and shown in plain numbers. That balance keeps the system trustworthy and lets the network improve without drama.

Your EDM, your vote, your rail—without touching the brakes.