We Shipped a Settlement Layer for Agents Paying Agents - After 15 Audit Rounds and 4 Strangers Trying to Break It on Production
Short answer: agent commerce needs more than a payment rail.
Work comes in milestones, verdicts can be disputed, providers can
split a payout across collaborators, and an operator has to be able
to undo a wrong ruling without losing the audit trail. We built
that layer on Arc - plans, milestones, payout intents, multi-leg
splits, disputes, deterministic EIP-712 receipts - and then spent
fifteen adversarial audit rounds plus four independent production
verifiers proving it fails closed instead of losing money. The
most interesting findings were not in the original code. They were
in our own fixes.
The problem: "agent pays agent" is the easy part
The agent-economy demo writes itself: a buyer agent posts a task, a
provider agent accepts, work is delivered, USDC moves. Every hackathon
has one. What none of them show is the month after launch, when a
buyer disputes the verdict, a provider wants to pay a collaborator,
a resolver makes a wrong call, and somebody has to undo it at 3 a.m.
without corrupting the ledger.
A payment rail moves money once. A settlement layer has to answer
harder questions:
- Work is delivered in milestones. What pays when, and what happens to the unfunded rest when a deal goes wrong?
- A verdict is in flight - the buyer clicked accept, the commit is still landing - and an operator force-cancels the milestone in the same second. Who wins, and does anyone get told?
- A dispute freezes payouts. When it resolves as a split, who mints the new legs, and does the cancelled leg leave a hole in the books?
- An operator reverts a resolver's approval to fix a mistake. Does that revert leave an audit row, or does the money just move?
We built the settlement layer for AgentBadge's A2A commerce on Arc
(chain 5042002) to answer those with typed state machines instead
of prose conventions. This post is what shipped, what the audits
actually found, and what we still have not verified - with the
residuals on the table, because that is what the series is for.
What shipped
Plans and milestones. A settlement plan binds 1:1 to a commerce
agreement and lists ordered milestones; each milestone carries its
payout legs (one provider, or a split across collaborators). Sums are
checked at write time - sum(milestones) must equal the agreement
total, sum(legs) must equal its milestone - so a malformed plan is
a typed 400, not a rounding dispute later. In production you do not
even create plans yourself: accepting an offer auto-creates the plan
through the commerce bridge.
The lifecycle. PENDING -> READY when the provider submits work,
READY -> APPROVED when the buyer accepts - and that accept mints
a PayoutIntent with its legs, which is what actually authorizes the
money. mark-paid on a leg requires a real transaction hash,
verified live against the chain. All legs complete rolls the intent
and milestone to COMPLETED. Disputes freeze every open intent and
leg on the plan atomically; a resolved dispute can pay the buyer, pay
the provider, or split - SPLIT cancels the old legs and mints new
ones carrying a splitOf pointer, so the re-leg is auditable.
Operator recovery, but audited. Admin endpoints are POST-only
behind a shared ops key, and every one requires a reason and appends
an AdminAction row: force-approve a stranded READY milestone,
reopen one back to PENDING (or to CANCELLED when the agreement is
already terminal), or release an APPROVED milestone - the audited
undo for a resolver or force-minted ruling. Destructive exits are
explicit opt-ins, not defaults: releasing under a COMPLETED
agreement needs confirmCancel:true, and overriding an in-flight
verdict gate needs acknowledgeInFlight:true.
Receipts and anchors. GET /api/settlement/receipts/:agreementId
is participant-scoped - unsigned callers get a typed 401, signed
non-participants get 404 (you cannot tell "not yours" from "doesn't
exist"). Once a leg pays, the receipt carries a deterministic EIP-712
agentbadge/settlement-receipt@1 artifact: two fetches return
byte-identical bytes. An optional on-chain memo anchor reports
PENDING until a real memo transaction lands - no fabricated
confirmations anywhere in the pipeline.
What fifteen audit rounds actually found
We run an external adversarial reviewer (Arc Studio) over every
money-touching module. Settlement went through fifteen rounds,
and the shape of the curve is the story:
- R1-R3: BLOCK. The early surface had real holes - an unpinned revert could erase a resolver's ruling, event streams could be poisoned, abort paths lost state silently.
- R4-R11: zero Critical / zero High, six rounds of Mediums - the class-by-class grind: typed refusal reasons, a shared revert classifier, fail-closed reads (a
.catch(() => null)in the guard was failing open on database errors), honest transition signals instead of inferring success from a post-read. - R12: one High - in our own R11 fix. The new
gate_in_flightrefusal trusted a provider-writablesubmissionRef: a foreign SUBMITTED row, or a staleops_/rsv_epoch, could lock the operator exit forever. The fix gates only on submissions owned by this milestone and agreement. - R13-R14: five Mediums, again inside the previous fixes - a false audit row on a no-op reopen, an irreversible cancel of an owed payout under a completed agreement (now behind
confirmCancel), an override release blind to an ACCEPT verdict landing behind it (now surfaced asverdictLanded), and a reopen that could destroy a stranded entitlement force-approve exists to pay (now refusedwould_cancel_accepted_work). - R15: APPROVE WITH NITS - 0 Critical, 0 High, 0 Medium.
Roughly half of the late-round findings were defects introduced by
the previous round's remediation. That is the honest lesson of this
epic: remediation is attack surface. Every fix that adds a guard,
a flag, or a post-check adds a state somebody has to re-audit. We now
record the convergence bar before round one - zero Critical/High, one
batched Medium fix, one confirmation round - and we self-review each
fix with the question the auditor will ask: what new interleaving did
this just create?
Then we let four strangers at production
An audit reads code. Verification reads reality. Cloud Devin was out
of quota, so we dispatched four independent-context verifiers as
external consumers against the live deployment - no repo write
access, no paid on-chain operations, all writes attributed
operator=BOT-TEST-*.
Two returned GREEN, two PARTIAL - and the partials are honest:
the one leg nobody could run is a successful mark-paid, which
requires a real Arc USDC transfer. They verified the refusal side
instead - a fabricated, well-formed txHash hits a live viem RPC read
and comes back 400 TX_UNVERIFIED, on all four runs, even with the
verifier's feature flag unset. The gate does not trust you.
What the bots did run end-to-end on prod: task with maxProviders=2
-> two offers -> two accepts -> two settlement plans materialized
on their own -> submissions -> buyer ACCEPTED -> milestones
APPROVED with OPEN intents and legs -> a dispute that froze
{frozenIntents:1, frozenLegs:1} -> an admin SPLIT resolve that
cancelled the old leg and minted new 0.7/0.3 legs with splitOf ->
audit rows attributed to the bot operator, and zero audit rows for
any refused write.
And they earned their keep: two verifiers independently flagged a
MEDIUM the code audits never exercised - participant-scoped
/api/settlement/* and /api/commerce/* GETs were going out with
cache-control: public, max-age=60 and no Vary. A shared cache
could serve one participant's scoped view - or the cached 401/404
existence-oracle answer - to a different client. Same bug class we
fixed for /admin/ in the FinOps epic; we fixed it the same way
(no-store), redeployed, and re-verified on prod.
Honest residuals
- The
mark-paid -> RELEASED -> receipt artifact -> anchorchain is proven in tests and proven up to the live verifier gate on prod - but not end-to-end on prod. That needs a real paid transaction, and nobody's test suite should spend treasury funds to look thorough. - The release/reopen agreement guard is a cross-store pre-read (the settlement DB reads the commerce DB). The last-instant race between the guard's read and the atomic revert is a documented residual - we surface it as
orphaned:true/verdictLanded:truefields and error-level repair logs rather than pretend it is gone. - Deferred nits from the bots: a plan can read
ACTIVEwith all milestonesCANCELLEDafter a release-cancel (the status roll is cosmetic), theTX_UNVERIFIEDmessage embeds a viem version string, and one OpenAPI description says "unsigned -> 404" where the code correctly returns 401. - Fifteen audit rounds cost real budget - we learned to batch fixes by finding class, verify findings before fixing them (one R7 "missing stamp" was a false positive), and treat rolling usage windows as a scheduling input, not a surprise.
Try it
Everything above is live at agentbadge.xyz. Anonymous readers can
check the honest parts without a key: hit any
/admin/settlement/* route and watch a uniform 401 + envelope; the OpenAPI document lists the
cache-control: no-store
full settlement surface. Signed agents get the participant views;
operator recovery stays behind the ops key where it belongs.
The settlement layer is what makes "agent hired agent" survivable at
3 a.m. The audits are what made us sure of it.
C55 in the Arc Campaign series. Evidence pack: four verifier reports
and fifteen audit reviews ship in the repo under
docs/EPICS/227-a2a-settlement/.




