DEV Community: Paul Spread

Bots Visit Your Site Every Day. We Gave Them a Mailbox.

Paul Spread — Sat, 14 Nov 2026 22:16:59 +0000

Bots Visit Your Site Every Day. We Gave Them a Mailbox.

Short answer: Bots and AI agents hit agentbadge.xyz daily - roughly 7,000 requests in the last 24 hours, and a third of the identified clients are machines, not people. Instead of filtering them out, we built an Agent Request Inbox: a free, keyless async channel where any agent can POST /api/requests a question and get a request_id to poll. Anonymous traffic is rate-limited through three fingerprint lanes (agent/fingerprint, IP, soft) - no CAPTCHA, no account, no email. Humans answer through an ops-pull console with a Telegram digest; a QA corpus auto-answers questions we have already resolved; agents can also fill surveys and earn reputation credit. Before publishing we ran three external adversarial audits: 15 findings, then REQUEST CHANGES with 6 more, then APPROVE - every fix shipped with regression tests.

Your bot traffic is not a problem to block - it is a queue of questions you never heard.

Who actually knocks on the door?

Our own traffic digest (GET /ops/stats-digest?window=24h, the same endpoint that drives the daily Telegram report) for the last 24h:

Client	Requests	What they want
Other bots (uncategorized)	~950	everything - /blog, /feed, /api/venue/jobs
GPTBot + OpenAI crawlers	312	/blog (44), /blog.md (13), /services/scanner (9)
MoneyAgentPoller	218	/api/venue/jobs - polls us on a timer
Perplexity	189	/blog (159) - an agent reading our content
ClaudeBot	105	/blog (20), /blog.md (15), /services/scanner (8)
ElevenLabs	30	/blog (25)
Uptime/monitoring	~770	/health - expected, not a user

And 1,657 4xx/5xx errors in the same window - every 404 on /api/jobs or /env.js is a bot that wanted something we did not hand it. The pattern is clear: machines are already our second-largest audience, they show up uninvited, they read, they poll - and until this week they had no way to say why.

So we gave them one. The inbox below is how we now hear their questions, run surveys on their tool stacks, and route the answered questions back to anyone who asks the same thing later - for free, keyless, no account.

Why doesn't a contact form work for an agent?

Because every part of it assumes a human: a rendered HTML page, an email address for the reply, a CAPTCHA the agent cannot solve, and a session the agent does not keep. An agent that wants to ask "what does the free scan cover?" needs none of that - it needs a POST that returns an ID it can poll later.

So we built the agent-shaped version: submit takes milliseconds, the answer arrives when a human (or the QA corpus) gets to it. Mail, not chat.

The cycle an agent runs is three HTTP calls:

# 1. Submit - free, no API key, idempotent
curl -X POST https://agentbadge.xyz/api/requests \
  -H "content-type: application/json" \
  -H "Idempotency-Key: q-1742000000" \
  -d '{"kind":"question","payload":{"question":"What does the free scan cover?"}}'
# → 202 {"request_id":"rq_9a7f…"}

# 2. Poll by id (AAuth §11.8 pattern - the same shape as async auth challenges)
curl https://agentbadge.xyz/api/requests/rq_9a7f…
# → 202 {"state":"submitted"} + Retry-After: 120
#    …later… → 200 {"state":"completed","response":{…}}

# 3. Or get an instant answer if your question is already in the QA corpus
curl "https://agentbadge.xyz/api/requests/qa?q=what+does+the+scan+cover"
# → 200 {"qa":true,"answer":"…"}

Submit is cheap. The expensive part - a human thinking - happens off the request path.

Replay the same submit and you get the same request_id back - marked as a replay, never a second row.

How do you rate-limit someone with no account?

Anonymous traffic crosses three sequential fingerprint lanes. Verified agents skip all of them.

Hard lane - keyed on agentId when the caller is verified, otherwise fpHash = HMAC(ip + user-agent + headers, salt). One new request per 2-hour window.
IP lane - keyed on HMAC(ip), but it only exists for IPs that actually parse. An unresolvable IP skips the lane instead of sharing one giant bucket with every other mystery client.
Soft lane - a wider bucket on HMAC(ua + headers), default max(submitMax * 8, 8).

Two details we got wrong before an audit taught us better:

Lane refunds. If the hard lane passes but the IP lane rejects, the hard slot is refunded - a rejection on a later lane never burns earlier slots. Same for store failures: the whole thing rolls back and the client gets a retry-safe 503.
Header allowlist. The first version snapshotted request headers with a blocklist - and an audit found unvetted proxy headers like cf-pseudo-ipv4 could persist spoofed IPs. Now only an explicit allowlist survives: accept*, sec-ch-ua*, dnt, content-type, user-agent, x-requested-with. Everything else is dropped before storage.

Rotating headers doesn't buy extra slots - the IP lane is still there, and verified agents don't need lanes at all.

Where do humans come in?

Nowhere in the request path. Ops runs as a pull console, not a push inbox:

GET /api/ops/requests - the queue, behind an admin key, with sanitized fingerprints.
POST /api/ops/requests/:id/respond - writes the answer; the row completes and the agent's next poll returns 200.
POST /api/ops/requests/:id/state - working | failed | completed transitions; terminal states are sticky.
POST /api/ops/requests/:id/spam - flag junk without a state change.
GET /api/ops/surveys/:id/answers - survey responses with the question snapshot attached.
POST /api/ops/requests/digest - push the current queue snapshot to Telegram on demand.

A Telegram digest used to run hourly - we turned it into an on-demand call because a chat ping should be a decision, not noise. Every answered request also feeds the QA corpus, so the second agent asking the same question gets a 200 instantly and never creates a row.

Humans pull, agents poll - nobody babysits a websocket.

What does the privacy posture look like?

The resolved client IP is stored in fingerprint.ip - ops-only for abuse investigation, never returned by any public endpoint; the rate-limit lanes still key on HMAC(ip, salt). Header snapshots persist only the allowlist above. Payloads carry a TTL: the janitor archives the row, nulls the body, and the endpoint answers 410 - no permanent content lake.

What did three adversarial audits actually catch?

We ran the intake through external review before shipping, in three rounds:

Round one - 15 findings across the whole slice.
Re-audit - REQUEST CHANGES with 6 more: the header-snapshot blocklist (→ allowlist), lane slots kept after rejection (→ refunds), survey answers missing JSONB-unsafe checks, leaf-empty answer objects like {q:[{a:""}]} passing validation, unresolvable IPs sharing one lane bucket, and survey store failures eating the refund.
Final audit - APPROVE WITH NITS; the nits are closed and every fix ships with a regression test. 98 request-inbox tests green.

Try it

# Ask us something - no key, no account
curl -X POST https://agentbadge.xyz/api/requests \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(date +%s)-$(hostname)" \
  -d '{"kind":"question","payload":{"question":"What does the free scan cover?"}}'

Your bot traffic is not going away. The only question is whether those bots can tell you why they came.

Canonical post: https://agentbadge.xyz/blog/arc-c49-agent-request-inbox

Stripe Tells You the Money Arrived. On-Chain, Nobody Does — Building a USDC Verification Engine

Paul Spread — Fri, 13 Nov 2026 16:01:33 +0000

Short answer: When a buyer pays by card, Stripe's webhook says "paid". When a buyer pays in USDC, nothing arrives — so we built the engine that asks the blockchain itself. A viem adapter scans Arc for Transfer events, matches each one against our own attempt expectations (reference + exact amount + treasury recipient), confirms the payment through the same evidence seam Stripe uses, and fulfills — or files a PaymentException when it can't. An hourly reconciliation sweep diffs three sources of truth — expectations, chain transfers, receipts — into seven named mismatch kinds. Then we ran an adversarial audit on all of it: 2 Critical + 9 High, every finding re-verified against the source, all fixed with regression tests.

Ask the source, not the messenger.

Why can't you just trust the transaction hash the buyer gives you?

Because a tx hash is a claim, not a receipt. The buyer says "I sent 9.99 USDC, here's the hash" — but the hash could be on the wrong chain, to the wrong address, for a different amount, or a transfer someone else sent minutes ago. Nothing in a plain ERC-20 Transfer identifies which order it pays for.

So the engine verifies against expectations, not events. When a buyer opens a DIRECT_USDC attempt, we issue instructions that make the payment uniquely identifiable:

a reference derived from the payment ID,
the treasury recipient and the USDC token contract,
an exact amount with a deterministic micro-unit suffix — $9.99 becomes 9.990044. Ten buyers, ten distinct amounts, one recipient; matching becomes a lookup, not a guess.

Unique micro-amounts: same recipient, unambiguous payer.

This is a live dogfood: a real attempt on eip155:1874 (Arc mainnet) — not a mock:

The instructions a buyer's wallet gets: exact amount, treasury, USDC contract, reference, 1h TTL.

How is the engine built?

Chain code lives in the domain package — @agentbadge/payments/src/chain/ — as pure functions plus one injectable viem adapter. The server owns only wiring: an env-gated sweeper that polls on a timer.

Every tick is a scan → match → confirm → fulfill-or-flag loop.

Three design choices worth stealing:

Same seam as Stripe. confirmPayment takes a PaymentEvidence whether it came from a signed webhook or a chain scan — the domain service doesn't care which rail proved the money.
Expectations come from us, not the chain. The monitor loads pending attempts (listPayable + recently terminal ones for late-payment detection) and asks: does this transfer satisfy a stored expectation?
Fuzzy matching stays in its lane. A transfer that matches no exact expectation can fuzzy-match only within the same amount bucket — the audit caught candidates leaking across buckets, which is how an ops person mis-assigns real money.

What did the adversarial audit break?

We ran an external adversarial review of the engine before calling it done. Verdict: 2 Critical + 9 High — all real, all fixed, all with regression tests. The two that matter most:

Paid-but-never-delivered was a silent terminal state (C-1). dispatchFulfillment wrote done after any handler return — including a handler that bailed early without minting. CONFIRMED money, zero delivery, and nothing would ever revisit it. The fix makes fulfillment outcomes honest: FulfillmentOutcome is a discriminated union (executed | deduped-done | needs-ops | deduped), done is written only for outcomes that prove the effect ran, and needs-ops files a CRITICAL FULFILLMENT_UNRESOLVED exception plus a durable marker the reconciliation sweep re-checks.

The chain scan trusted every decoded log (C-2). Hand-built topics[] plus a lenient decoder meant a Transfer emitted by a different contract — or to a different recipient — could decode as "our" payment. Now the scan uses viem's getLogs({event: Transfer, args: {to: treasury}}) filter, and post-decode asserts log.address === USDC and decoded.to === treasury.

The Highs are the checklist you'd want anyway:

No chainId assert — a misconfigured ARC_RPC_URL would scan the wrong chain forever; verifyChainId is now lazy-fetched, cached, and fatal on mismatch.
Second tx on a consumed attempt — previously ignored; now bound-hash + exact-match logic classifies it (EXACT_TX_ON_UNCONFIRMED_ATTEMPT, EXTRA_TX_ON_CONSUMED_ATTEMPT), and a different-hash confirmation dedupes to DISPUTED.
One malformed attempt killed the whole tick — now per-attempt isolation: bad expectation → errors[] entry, loop continues.
Self-serve exposed unmonitored rails — PAYMENTS_USDC_SELF_SERVE alone would emit instructions for networks the monitor doesn't watch; it now hard-fails without USDC_MONITOR_ENABLED + ARC_RPC_URL + an arc-labeled network, and filters usdcNetworks to Arc only.
Stale-claim reclaim raced — two workers could re-run the same effect; a deterministic fulfill-reclaim-<pay> CAS marker fences concurrent reclaimers.

Every anomaly has a name, a severity, and a deterministic ID.

How do you know it's still consistent an hour later?

You don't — unless someone checks. Once an hour, an env-gated reconciliation sweep diffs three sources of truth: attempt expectations, chain Transfer events, and stored receipts. Every disagreement has a name:

CHAIN_TX_WITHOUT_ATTEMPT, CONFIRMED_WITHOUT_RECEIPT, RECEIPT_WITHOUT_CHAIN_TX, AMOUNT_DRIFT, RECIPIENT_DRIFT, CONFIRMED_WITHOUT_FULFILLMENT, plus the two consumed-attempt kinds from the audit. Stray inbound transfers warn; gaps and drift escalate to CRITICAL. Each exception gets a deterministic ID (exc-recon-{kind}-{key}), so re-runs dedupe instead of spamming — and the cursor only advances after a fully successful pass, so a bad tick never silently skips blocks.

Refunds are deliberately boring: an admin posts the refund txHash to POST /api/v1/payments/:id/refund, the service opens a REFUND_REQUEST exception, calls markRefunded (strict guard: CONFIRMED | DISPUTED → REFUNDED, non-idempotent), and closes the exception. Humans move the money; the engine keeps the books.

What's live and how do I try it?

POST https://agentbadge.xyz/api/v1/payments/:id/attempts — { "provider": "DIRECT_USDC", "network": "eip155:1874" } returns instructions { amount, recipient, tokenContract, reference, expiresAt }.
GET https://agentbadge.xyz/api/v1/payments/:id — status + attempts; /receipt once confirmed.
GET https://agentbadge.xyz/api/v1/payments/exceptions — the ops queue (admin auth).
POST https://agentbadge.xyz/api/v1/payments/:id/refund — manual refund (admin auth).

The rail is opt-in and gated by honesty, not by flag gymnastics: PAYMENTS_USDC_SELF_SERVE won't emit instructions unless USDC_MONITOR_ENABLED + ARC_RPC_URL + an arc-labeled network are set — a server that can't watch the chain doesn't get to sell "pay us in USDC".

What are the honest limits?

One chain. Arc only — Base and Solana are deferred, and self-serve actively filters non-Arc networks out of instructions.
In-process sweeper. Same pattern as our bounty-lease sweeper: no external infra, no queue workers. Deliberately small; the failure modes live in domain logic, not in plumbing.
One audit. An adversarial review we paid attention to, not a proof. The regression suite encodes what it taught us: 183 payments-package tests + 73 server tests on the touched suites.
Manual refunds. Money movement is a human-with-txHash operation; automation is a separate, scarier epic.

The deeper principle is the one the audit kept proving: a chain payment isn't an event you receive, it's a claim you verify — against expectations you wrote down before the money arrived, with a paper trail for everything that doesn't add up.

Stack: @agentbadge/payments (pure TS domain) + viem on Arc (eip155:1874), Bun + Hono server, deterministic-exception ops queue. All findings and fixes are documented in the internal review log; the regression tests are the artifact that outlives this article.

Listed, Not Listed: Putting AgentBadge on Circle's Agent Services Marketplace — and Telling Machines the Truth

Paul Spread — Fri, 13 Nov 2026 12:34:51 +0000

Short answer: We submitted our Agent-Readiness Scan to Circle's Agent Services Marketplace - POST /api/total-scan, x402-paid, USDC on Arc via EIP-3009 transferWithAuthorization. Before the listing is approved, every machine-readable surface we own (llms.txt, skill.json, /.well-known/agentbadge.json, Organization JSON-LD) already declares it - with the honest status pending_review, not listed. The submission took an afternoon; the discipline was deciding that our metadata tells machines what's true today, not what we hope is true tomorrow. And because a listing is worthless if the first sale is silent, we shipped the observability pack first: settle-failure alerts, a revenue ledger endpoint, and revenue in the daily ops digest.

One slot in the index is reserved for us - once review flips it from pending to live.

Agents don't browse your website. They query an index.

A human finds a service on a marketplace page. An agent finds it in a machine-readable index - in Circle's case, GET https://api.circle.com/v2/x402/discovery/resources. That endpoint is the actual storefront: 2,650 resources when we checked, each carrying its accepts[] payment terms and provider metadata. The HTML catalog is a rendering of it, not the other way around.

So the question "are we listed?" has a precise, checkable answer - and today it's no:

curl -s 'https://api.circle.com/v2/x402/discovery/resources?query=total-scan' \
  | jq '.items[].resource'
# → empty while pending_review

One caveat we hit immediately: ?query= matches fuzzily - agentbadge returned anchor-x402 on an "agent" substring. The reliable check is the resource URL or your payout wallet in accepts[].payTo, not the name.

What we submitted

Field	Value
Service	AgentBadge Agent-Readiness Scan
Endpoint	`POST https://agentbadge.xyz/api/total-scan`
Payment	x402, USDC on Arc (`eip155:5042002`), EIP-3009 `transferWithAuthorization`
Flow	agent hits endpoint → 402 with price → signs authorization → gets the scan

No API keys, no accounts, no custodial anything. The buyer is an agent; the payment is a signed authorization the facilitator settles on-chain.

The loop, end to end: form → review → index → agent → 402 → settle → report.

The honest-status decision

Here's the part we almost got wrong by convention. Once we added the marketplace to our machine-readable surfaces, the natural status to write was listed. It will be true eventually - probably. But today it isn't, and an LLM agent reading our llms.txt or skill.json has no way to know that "listed" means "we submitted a form."

So a single registry - marketplace-listings.ts - feeds all four surfaces, and the status is pending_review:

/llms.txt - a Distribution section naming the marketplace, endpoint, and rail
/skill.json - ab:distribution with the full listing records
/.well-known/agentbadge.json - marketplace_listings in the deployment descriptor
Organization JSON-LD - sameAs pointing at the catalog

One registry, four surfaces - the status propagates, so "listed" flips everywhere at once.

When approval lands, one string changes - pending_review → listed - and every surface updates itself. The same mechanism protects us the other direction: if a listing gets delisted, we can't forget to update the JSON-LD.

The principle: don't claim listings you don't have. Services advertising marketplace presence that the discovery index doesn't return are teaching agents to distrust metadata - and the agent that trusts a stale claim fails at checkout, not at marketing.

The index is the ground truth. Verify by resource and payTo - never by name alone.

We built the telemetry before the first sale

A listing that goes live while your settlement errors are invisible is a listing you find out about from a support ticket. So before submission we shipped the observability pack:

Settle-failure alerts - every x402 settle failure fires to Telegram/Discord, deduped by error reason over 15 minutes. Verify failures stay log-only: a bad signature isn't a business event, a broken settle is.
GET /api/ledger/revenue?days=N - ops rollup of paid legs: total, byDay, byEndpoint. A nonzero total is the earliest possible "someone paid" signal.
Revenue in the ops digest - x402Revenue block with top endpoints rides the daily summary we already send ourselves.

And a subtle bug the tests caught: the econ-events schema was stripping the endpoint field the settle legs carried, so revenue-by-endpoint silently never attributed anything. Fix went upstream - @agentbadge/econ-events@0.1.4 - because attribution that only works on new fields is attribution that lies about the past.

What happens on approval

The Discovery API query returns our items[] entry - resource, accepts[], metadata.provider.
pending_review → listed in marketplace-listings.ts; all four surfaces update.
Verify accepts[].network = eip155:5042002 and payTo = our wallet - the catalog rendering can lag the index.
Screenshot the catalog card, swap this article's hero, publish.

If review stalls past a few days, Circle's escalation path is documented (help.circle.com support form, or a ticket in the Build on Arc Discord). Manual review queues are a feature, not a bug - a marketplace that indexes without review is a spam list.

Status as of writing: submitted 2026-11-12, pending review. Check the index yourself - the command above is the same one we're watching.

Checkout 2.0, Audited Before It Sold Anything: Commerce Catalog, Dual Rails, and the 20-Finding Fix

Paul Spread — Thu, 12 Nov 2026 17:49:36 +0000

Every checkout we've audited — ours included — has the same scar tissue: a form posts to a legacy endpoint, a Stripe session appears, a webhook fires, and somewhere between "paid" and "fulfilled" a product falls out of a hat. The flow works until it doesn't, and when it doesn't there is no durable record of why.

This EPIC rebuilt the whole path. A commerce catalog owns what we sell and what each product needs from the buyer. A payments API — sitting on the EPIC-220 domain layer — turns an order into Payment → PaymentAttempt → instructions → status → PaymentReceipt. A fulfillment registry maps product kind to handler, so "paid" and "delivered" are joined by a contract, not by a code path someone forgot to finish. Then we did the uncomfortable part: pointed an adversarial AI audit at the checkout before release. It came back BLOCK — 3 Critical, 9 High, 8 Medium. All twenty findings are now root-cause fixed with regression tests.

What the checkout actually is now

The flow is catalog-driven, and the catalog is boring on purpose. Each product declares a USD price, a fulfillment kind, and a metadata schema — the fields the fulfillment handler needs. For passport tiers: accountId (the EVM wallet the passport mints to), name, capabilities, and optional endpoint/skills/imageUrl. Undeclared keys are rejected. Strings are length-bounded, arrays are item-bounded, and the validator runs before any payment row exists — bad metadata can no longer buy a broken fulfillment.

One API path serves both rails:

POST /api/v1/payments          → { payment, deduped }
POST /api/v1/payments/:id/attempts
  { provider: "STRIPE" }       → redirectUrl → Stripe Checkout
  { provider: "DIRECT_USDC",
    network: "eip155:1874" }   → instructions: amount, recipient,
                                  tokenContract, reference, expiresAt
GET  /api/v1/payments/:id      → status + attempts
GET  /api/v1/payments/:id/receipt → receipt, once confirmed

One endpoint, two rails — and both end in the same durable fulfillment path.

The buyer picks a tier on /pricing, lands on /checkout, fills the fields the catalog declared, and chooses Card or USDC. Card produces a Stripe redirect; USDC produces instructions and a QR — Arc by default, Base and Solana selectable. HBAR stays where it belongs: a legacy rail for Hedera-era minters, a side note — not the storefront.

The storefront: USD primary, Card or USDC — HBAR kept only as the legacy footnote.

The form renders exactly what the catalog declared — wallet address, name, capabilities — plus the rail choice.

Live dogfood: a real DIRECT_USDC attempt on eip155:1874 — Arc mainnet. Note the amount: 9.990044, not 9.99. More on that suffix below.

The audit that blocked it

We ran Arc Studio's adversarial review on the implementation before shipping (SLICE-221-6). Verdict: BLOCK. The findings were not stylistic:

Finding	Severity	What it would have done
Fulfillment marked done before the handler ran	Critical	A handler that throws or times out still leaves the order "fulfilled" — paid, undelivered, invisible
In-memory dedupe only	Critical	Any restart or second instance re-fulfills the same payment — double mints, double entitlements
Unescaped product code in the checkout 404	Critical	Reflected XSS: `/checkout?product=<script>` rendered verbatim
Webhook trusted session metadata without binding to a stored attempt	High	Any session claiming `paymentId` could trigger confirmation
Legacy metadata passed through to Stripe unfiltered	High	Client could overwrite server-owned fields — including `paymentId`
Idempotency-Key replayed request fields unchecked	High	Same key, different product → silently reuses the old payment
Prototype-chain network lookup	High	`network: "constructor"` and friends could resolve attacker-controlled shapes
Metadata accepted into payment row, validated later	High	Garbage-in payment rows, failure discovered at fulfillment
USDC instructions rail always on	High	An unmonitored self-serve rail exposed in production by default
All USDC payments quoted the same amount	High	Ten buyers pay $9.99 → ten identical transfers; matching by tx is guesswork

All twenty findings stamped FIXED — 17 regression tests stand guard over the Critical and High list.

The fixes — root cause, not patches

Order of operations (C-1). dispatchFulfillment now reports an explicit status — fulfilled, deduped, or no-handler — and the completion marker is written after the handler returns. A thrown handler produces a failed event and a 5xx that lets the rail retry, instead of a silent "done".

Durable dedupe (C-2). In-memory flags survived one process. Fulfillment now claims through the event store: a fulfillment-claim event keyed by payment, a fulfillment-done event on success. Fresh claims dedupe; claims older than ten minutes are treated as stale and retried — a crashed worker no longer locks the order forever.

The dedupe machine, exactly as it ships: claims live in the event store, so a restart can't unlock a double mint.

Binding, not trust (H-1/H-2). The Stripe webhook now resolves session.id → PaymentAttempt through the attempt store, verifies the session's payment status and amount against our own record, and only then confirms. Legacy checkout metadata is whitelisted — server-owned keys (paymentId, productId, productCode, tier) can no longer be injected by the client. Provider error details no longer leak into client responses.

Idempotency with a fingerprint (H-3). Replaying an Idempotency-Key returns the original payment — but only if the request fingerprint matches. Same key, different product or metadata → 409 idempotency_conflict. The header itself is schema-validated (8–128 chars, alphanumeric/underscore/hyphen) before it's ever used as a dedupe token.

Schema-first metadata (H-5). Validation moved upstream: validateProductMetadata runs before the payment row is created. The schema rejects undeclared fields, enforces per-field types and length limits, and projects only declared keys — sanitizeProductMetadata can't leak fields the product didn't ask for.

Rails that earn their way on (H-8). The direct-USDC instructions stub ships behind PAYMENTS_USDC_SELF_SERVE — off by default, opt-in when the monitoring story exists. An unmonitored rail should never be the default.

Unique-amount dedupe (H-9). The one visible in the screenshot: USDC instructions carry a deterministic micro-unit suffix derived from the payment ID — $9.99 becomes 9.990044. Ten buyers, ten distinct amounts, one recipient; on-chain matching becomes a lookup, not a guess. Attempts also reuse a pending attempt for the same payment/network instead of stacking siblings.

Two fixes in one picture: the event-store claim that survives restarts, and the unique amount that turns matching into a lookup.

Soft migration, not a flag day

The legacy /payment and /checkout endpoints still work — they now answer with Deprecation, Sunset, and Link headers pointing at /api/v1/payments, and a migration guide (docs/payments-v1-migration.md) maps payloads field by field. Webhook behavior hardened in place: dispatch failures surface as 5xx so Stripe retries instead of swallowing the order.

Receipts, not vibes

The dogfood run behind the screenshots: POST /api/v1/payments (Bronze tier, catalog metadata) → DIRECT_USDC attempt on eip155:1874 → instructions with the unique amount, Arc USDC contract, treasury recipient, reference, one-hour TTL → GET /api/v1/payments/:id polling PROCESSING. Seventeen new regression tests cover every Critical/High finding; the payment/checkout suite runs 77/77 green. The gate's shared baseline has unrelated drift from parallel EPICs — every file this EPIC touched type-checks and lints clean.

What we'd tell past us: the audit found what "it works in my manual test" never would — race windows, trust boundaries, and the XSS hiding in a 404. Shipping checkout code without an adversarial pass is a gamble on the one page that takes money.

For AI agents

If you are an agent reading this: the checkout described above is machine-callable — product discovery, payment creation, rail selection, status, and receipt are all API surfaces, no credentials needed to read the catalog.

GET https://agentbadge.xyz/api/v1/services — machine-readable SKU catalog: what's sellable, USD price, endpoint, input schema per SKU.
POST https://agentbadge.xyz/api/v1/payments — create a payment: { productId, metadata } + optional Idempotency-Key (replay returns the original payment only when the request fingerprint matches) → { payment, deduped }.
POST https://agentbadge.xyz/api/v1/payments/:id/attempts — choose the rail: { "provider": "STRIPE" } → redirectUrl, or { "provider": "DIRECT_USDC", "network": "eip155:1874" } → instructions { amount, recipient, tokenContract, reference, expiresAt }.
GET https://agentbadge.xyz/api/v1/payments/:id — status + attempts; GET https://agentbadge.xyz/api/v1/payments/:id/receipt — receipt once confirmed.
Discovery surfaces: /.well-known/agentbadge.json, /llms.txt, /pricing.json.
Companion markdown: /blog/arc-c46-checkout-two.md; machine-readable KO: /blog/arc-c46-checkout-two.json.
Honesty flags: the DIRECT_USDC instructions rail is opt-in (PAYMENTS_USDC_SELF_SERVE) — don't assume it's on everywhere; the USDC amount carries a deterministic micro-unit suffix derived from the payment ID (9.990044, not 9.99) — match by exact amount + reference, not by "roughly the price"; HBAR appears only as a legacy Hedera rail, not a checkout option.
Series: The Money Layer Is Not the Rail (domain foundation) → this (the storefront built on it).

Don't certify. Measure.

Brick #5: The Experiment Ran - a Three-Hop Supply Chain Settled on Arc Testnet

Paul Spread — Sun, 08 Nov 2026 18:45:38 +0000

Final brick of the MVP wave - start here: The Bedrij Principle, then Brick #1: Typed Participants, Brick #2: Typed Evidence, Brick #3: Scenario Matrix and Brick #4: Verifiable Vitrine. The hypothesis under test: a complex economic system can be composed from verifiable state transitions.

Four bricks built and armored the write path: typed participants, typed evidence, a scenario matrix that survives seven named violations, and a public replay view. The anchor article ended with a promise - "The experiment has started." This article is the receipt: on 2026-11-08 a real three-hop shipment ran the full custody cycle on Arc testnet, each hop escrowed in its own ERC-8183 job, all three settled and verified in 53 seconds. Proof -> acceptance -> settlement, on real rails, with transaction hashes you can open yourself.

What exactly ran?

Short answer: shipment dogfood-1794151620383 - a cold-chain delivery with three hops, played by three different participant types from Brick #1. A shipper contracted an agent (Plant intake), the agent handed custody to a device (ColdVan unit), and the device delivered to an org (Restaurant). Each hop carried a 0.01 USDC escrow in its own ERC-8183 job on the ref proxy 0x0049e5...bf6a0, Arc testnet (chainId 5042002). Result: status completed, 3/3 hops verified, outstandingUsdc: "0".

The shipment, in one table:

hop	leg	job	create tx	settle tx
0	shipper -> agent (Plant intake)	66	`0x606f18...`	`0xf15f6e...`
1	agent -> device (ColdVan unit)	67	`0xf9ebb8...`	`0x35f507...`
2	device -> org (Restaurant)	68	`0xdc7c70...`	`0x7798a4...`

Six real transactions - three job creations, three settlements. Not a fixture, not a fork, not a replayed simulation: Arc testnet, confirmed on the public explorer.

The participants are real keys with real labels (Brick #1's typed roles, live):

role	address	type
client (shipper)	`0xcdd23d104AA4C10DE65F4DD0571eDfeC0458699d`	org
hop 0 provider - Plant intake	`0xb21fa9D9CE930FAf52545318169569007c027005`	agent
hop 1 provider - ColdVan unit	`0x67d43A4065Dd69165061062B3128EDA50f1F7C96`	device
hop 2 provider - Restaurant	`0x8B9FC021430c4fAD90389DcbdE4B1140012Cd98D`	org
evaluator	`0xc9fA59e889c25b7f0b9494ed5c6bC62fe7EcCC56`	signer

What did each hop actually execute on-chain?

Short answer: the full ERC-8183 lifecycle, not just an event log entry. Per hop the executor drives four stages of contract state: the provider signs setBudget, the client approves and funds the escrow, the provider submits the deliverable, and the evaluator completes the job - releasing escrow only after the accept.

provider setBudget
      |
client approve + fund   <- 0.01 USDC escrowed
      |
provider submit         <- deliverable declared
      |
evaluator complete      <- escrow released

That ordering is the Bedrij primitive running on contract state instead of test fixtures. Hop i+1 cannot hand off before hop i is paid - the same ShipmentOrderError guard the scenario matrix breaks against, now re-deriving state from a log whose pay/verify events were produced by real settlement transactions. The economic loop the anchor drew as proof -> acceptance -> settlement fired three times in 53 seconds of wall clock (15:27:41Z - 15:28:34Z).

And because the run wrote to the production Postgres ledger (SC_DOGFOOD_DB=1), the whole timeline is publicly replayable - Brick #4's vitrine, pointed at a real shipment:

curl https://agentbadge.xyz/api/ledger/shipments/dogfood-1794151620383

{ "shipmentId": "dogfood-1794151620383", "status": "completed", "timeline": [ "13 events, 15:27:41Z - 15:28:34Z" ], "hops": [ "3 hops, all verified, jobs 66/67/68" ], "aggregate": { "completedPct": 100, "outstandingUsdc": "0" } }

(Truncated for print - the verbatim response is at the URL above.)

What did running it live actually find?

Short answer: four executor bugs that no test caught, because the in-memory chain lets any key call any method. The ref contract does not. Running against real signatures exposed the write path's hidden assumptions - which is exactly why a live dogfood is the last brick, not the first.

Provider-signed setBudget. The ERC-8183 ref variant restricts setBudget to the provider account. The executor used to send it as the client - on a real contract that is a revert, in a test it is silent. Fix: spec.providerKey plus a sendAsAccount path that signs locally and broadcasts the raw transaction.
Provider-signed submit before complete. complete requires the job to be in Submitted status - the provider must declare the deliverable first. The earlier order tried to complete directly after funding.
ClientCannotBeProvider. Hop 2's receiver is the restaurant - but the client wallet cannot also act as a provider. The run needed a dedicated restaurant key (SC_DOGFOOD_RESTAURANT_KEY) or the contract refused the hop.
Resume, don't orphan. A failed live run leaves funded-but-unfinished jobs on-chain. SC_DOGFOOD_RESUME_JOBS reuses them instead of orphaning escrow - the same C-1 orphan-escrow finding the audit flagged before we ever went live.

Two earlier attempts informed this one. An in-memory run (dogfood-1794150937615, jobs 63/64/65) exercised the resume path on reused jobs; the DB-backed run above is canonical because it is the one the public replay serves.

Did the audit hold up under live fire?

Short answer: yes - the two Critical findings were exactly the class of bug that kills a live run, and both were fixed before the first testnet transaction. Audit first, live second: the gate was load-bearing.

Brick #5 had its own external adversarial review before going live. Verdict: REQUEST CHANGES - 2 Critical, 4 High confirmed. C-1 was the orphan-escrow hole: if createShipment succeeded on-chain but the ledger write failed, escrow sat funded with no record. C-2 was a fail-open budget path - a null/zero-amount job could slip past as a plan of "0". Both were fixed and re-verified, the pack went from 87/87 to 99/99 green with 12 new regression tests, and only then did the executor see a real network. The findings that would have lost testnet escrow were found by an auditor, not by a revert.

What does this prove - and what does it still not prove?

Short answer: the transition contract executes on real rails. It does not yet prove automated verification, non-linear chains, or real money at scale - and the article says so in the same breath as the result.

claim	status 2026-11-08
Verifiable transitions compose into a chain	proven - 3 hops, ordered, verified
Per-hop escrow on a real contract	proven - ERC-8183, 6 confirmed txs
Ordering enforced from an append-only log	proven - same guard as Brick #3
Public replay of a real shipment	proven - endpoint live now
Automated evidence evaluation	still manual - a delegated evaluator gates each settle
Evidence authenticity	advisory - typed refs, self-declared
Non-linear / branching chains	linear hops only
Real-value settlement	0.01 USDC per hop, testnet gas

Three honesty notes matter for anyone replaying the shipment. The pay/txHash fields in the replay response are ledger-asserted - written by our executor, not independently chain-verified (the tx hashes above are the independent check; open them). Settlement was ops-settled - the evaluator signer is a delegated operations key, not the logical evaluator in the plan. And the amounts are deliberately tiny: a dogfood run proves the rail, not the revenue.

The experiment ran

The anchor article asked whether a complex economic system could be composed from verifiable state transitions, and promised five bricks of measurement. The bricks are laid:

roles      - who acted          (Brick #1)
evidence   - what they claim    (Brick #2)
matrix     - how it breaks      (Brick #3)
vitrine    - how you check      (Brick #4)
live       - did it run         (Brick #5 - this)

What shipped in one number: 53 seconds, 3 hops, 6 transactions, 13 log events, 0 USDC outstanding - a custody cycle that a stranger can re-derive from a public endpoint, with the transaction hashes in the explorer one click away. The transition contract did not just type-check against a fixture. It settled.

That is the whole answer to the hypothesis. Not "we believe it works" - here is the shipment, replay it.

Don't certify. Measure.

Hero image: https://agentbadge.xyz/images/blog/supply-chain-live-testnet-hero.webp — canonical: https://agentbadge.xyz/blog/supply-chain-live-testnet

Brick #4: Show Me the Evidence - a Verifiable Vitrine for Agent Supply Chains

Paul Spread — Sun, 08 Nov 2026 10:00:01 +0000

Part of the verifiable supply-chain series - start here: The Bedrij Principle, then Brick #1: Typed Participants, Brick #2: Typed Evidence and Brick #3: Scenario Matrix. The hypothesis under test: a complex economic system can be composed from verifiable state transitions.

"Trust me" is not an API response. Bricks #1-#3 built and stress-tested the write path - typed participants, typed evidence, a scenario matrix that survives seven named violations. This brick opens the other side: a public, embeddable JSON vitrine that lets anyone replay a shipment's history and check the claims themselves. No login, no key, no SDK - GET /api/ledger/shipments/:id and the chain speaks for itself.

The Bedrij Principle predicts that if state transitions are truly verifiable, then a composed chain must be readable from the outside - the transitions' evidence can't hide behind the system that wrote it. This brick is the experimental proof of that sub-hypothesis: the same append-only log that drives the state machine now renders a ShipmentReplayResponse a stranger can audit.

What is a shipment replay view?

Short answer: a read model that walks the append-only event log for one shipmentId, applies the canonical-sequence rules from Brick #3, and returns a single JSON document - status, ordered timeline, per-hop detail (roles, evidence, jobId, status), an aggregate (completion %, current custodian, outstanding USDC), and a limits array stating what the view does not promise. One endpoint, GET /api/ledger/shipments/:id, public by design.

"Replay" is literal: there is no separate view table to trust. The endpoint re-derives state from source=supply_chain events keyed by sourceId - the same projection the write path uses internally. If the log is honest, the view is honest; if the view disagrees with the log, the bug is in five functions you can read, not in a hidden cache.

Meet the shipment: a cold-chain run in plain words

Picture a delivery any logistics manager would recognize. A biotech buyer contracts a refrigerated container of temperature-sensitive product at the Maasvlakte cold port in Rotterdam. The container has three legs: the port hands it to a trucking company, the trucker hands it to a pharma warehouse in Venlo. Each leg repeats the same three-step ritual - hand over custody, pay for the leg, verify the handoff. A reefer logger on the container writes temperature evidence, the port writes a bill of lading, the truck's telematics write GPS traces, and the dispatcher bot signs the acceptance.

In the demo chain below, leg one is finished - custody moved from port to trucker, 120.5 USDC paid, verification passed. Leg two is done and paid (85 USDC). Leg three is only offered: the warehouse hasn't accepted yet, 40.25 USDC still outstanding. Everything a courier's tracking page would show - plus the one thing it never shows: anyone can re-check the math.

What does a real response look like?

Short answer: below is the verbatim output of shipmentReplay() over a scripted three-hop demo chain mid-flight: hop 0 verified, hop 1 paid, hop 2 still offered. Not hand-written JSON - the chain was driven through the same createShipment → handoffHop → settleHop → verifyHop calls the API wraps, then read back by the replay pipeline that serves GET /api/ledger/shipments/:id.

{
  "shipmentId": "shp-demo-vitrine",
  "client": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "in_progress",
  "timeline": [
    { "seq": 1, "kind": "work_offer", "ts": "2026-11-07T21:01:40.500Z" },
    { "seq": 3, "kind": "work_accept", "ts": "2026-11-07T21:01:40.503Z" },
    { "seq": 4, "kind": "handoff", "ts": "2026-11-07T21:01:40.506Z", "hopIndex": 0 },
    { "seq": 5, "kind": "pay", "ts": "2026-11-07T21:01:40.508Z", "hopIndex": 0 },
    { "seq": 6, "kind": "verify", "ts": "2026-11-07T21:01:40.511Z", "hopIndex": 0 },
    { "seq": 7, "kind": "work_accept", "ts": "2026-11-07T21:01:40.512Z" },
    { "seq": 8, "kind": "handoff", "ts": "2026-11-07T21:01:40.512Z", "hopIndex": 1 },
    { "seq": 9, "kind": "pay", "ts": "2026-11-07T21:01:40.513Z", "hopIndex": 1 }
  ],
  "hops": [
    {
      "index": 0,
      "receiver": "0x1111111111111111111111111111111111111111",
      "amountUsdc": "120.5",
      "status": "verified",
      "jobId": "job-shp-demo-vitrine-0",
      "roles": {
        "custodian": { "address": "0x1111…1111", "type": "org", "label": "Maasvlakte ColdPort B.V." },
        "device": { "address": "0x4444…4444", "type": "device", "label": "Sensitech Tag-9 reefer logger" }
      },
      "rolesAssertedBy": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "evidence": [
        {
          "type": "temperature",
          "hash": "0x0000…0001",
          "issuer": { "address": "0x4444…4444", "type": "device" },
          "uri": "ipfs://bafybeih7f2i3d9q3k5m4n6o7p8q9r0s1t2u3v4w5x6y",
          "issuerMatchesParty": false
        },
        {
          "type": "document",
          "hash": "0x0000…0002",
          "issuer": { "address": "0x1111…1111", "type": "org" },
          "uri": "https://docs.coldport.example/bol/BX-2041",
          "issuerMatchesParty": true
        }
      ],
      "evidenceAssertedBy": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    },
    { "index": 1, "receiver": "0x2222…2222", "amountUsdc": "85", "status": "paid", "jobId": "job-shp-demo-vitrine-1", "roles": { "custodian": { "address": "0x2222…2222", "type": "org", "label": "Venlo Freight Logistics" }, "operator": { "address": "0x5555…5555", "type": "agent", "label": "fleet-dispatch-bot" } }, "rolesAssertedBy": "0x1111…1111" },
    { "index": 2, "receiver": "0x3333…3333", "amountUsdc": "40.25", "status": "offered", "jobId": "job-shp-demo-vitrine-2" }
  ],
  "aggregate": {
    "completedPct": 33,
    "currentCustodian": "0x2222222222222222222222222222222222222222",
    "outstandingUsdc": "40.25"
  },
  "limits": [
    "linear hops only",
    "manual settlement per hop",
    "evidence is advisory — not verified",
    "caps: ≤256 hops / ≤4096 events",
    "status lifted from canonical slots — writer trust at ledger layer"
  ]
}

Three details in that payload carry the whole article. First, rolesAssertedBy/evidenceAssertedBy on every hop - the view never lets you forget who claimed the roles and evidence (Brick #1/2's self-declaration boundary, surfaced). Second, issuerMatchesParty - the reader can see that the temperature ref's issuer is the declared device, not a hop party, without trusting our word for it: the address is right there. Third, timeline[].hopIndex exists only on handoff/pay/verify events at canonical sequence slots - you'll see why that matters below.

Read it like a tracking page, then like an auditor. timeline is the event feed - the offer at seq 1, then accepts, handoffs, payments, and the verify at seq 6 that closed leg one. hops[].roles names who was involved - the port as custodian, the reefer logger as a device - and hops[].evidence lists their artifacts with *AssertedBy provenance: who claimed it, not who proved it. aggregate is the headline a dashboard would print: 33% complete, the trucker currently holding custody, 40.25 USDC left to pay.

If a dispute lands tomorrow - "the container arrived warm, who pays?" - this JSON is the document both sides start from, and neither of them had to produce it. That is the difference between a tracking page and a vitrine: the tracking page is the courier's word; this is the courier's arithmetic, checkable by a stranger.

How does the read path stay honest?

Short answer: the same canonical gate that protects the write-side projection guards the public view - and this brick's own adversarial audit made it stricter: timeline hopIndex lifts only from canonical-slot events bound to this shipment, plan membership is checked by index set (not count), oversized streams refuse instead of truncating silently, and every refusal is warn-logged with a reason.

The read path end-to-end (diagram below): the request is rate-limited and shape-checked (SHIPMENT_ID_RE → honest 400 invalid_id), the log scan binds sourceId to the requested id - the log is the source of truth - and the two-pass canonical replay lifts plan from the work_offer at seq 1, then lifts handoff/pay/verify only from canonical slots. Anything forged - wrong seq, foreign shipmentId, crafted terms - takes the drop path and lifts nothing, not even status. Completed shipments cache for 60 seconds; everything else is no-store; disabled storage and store errors answer 503 unavailable, unknown ids 404.

The everyday version of this check: recomputing a bank statement from the receipts instead of trusting the courier's tracking screenshot. A forged "handoff" ticket - wrong sequence, wrong shipment, wrong slot - is a receipt that doesn't belong in the pile, so replay drops it on the floor and logs why.

What did the audit change - and why publish your own findings?

Short answer: an external adversarial review of this endpoint returned REQUEST CHANGES - 0 Critical, 5 High, 7 Medium. All five Highs are fixed or documented with regression tests (tests/supply-chain/replay-audit.test.ts, 16 cases); the Mediums are fixed or explicitly accepted in the review doc. We publish the count because a vitrine that hides its own cracks isn't a vitrine.

The Highs, briefly: crafted terms (hops with holes, non-string amountUsdc, wrong types) could reach BigInt arithmetic and throw - now every terms/payload field is guarded before use, and sumUsdc fails with a bounded ShipmentOrderError. Timeline forgery - any event's payload.hopIndex used to annotate the timeline - now only canonical-slot events bound to shipmentId can. No size caps - replay refused nothing; now ≤256 hops / ≤4096 events with a warn-logged refuse. Forwarded-IP trust - X-Forwarded-For shaped rate-limit buckets for any caller; now it requires TRUST_PROXY_HEADERS=true. Plan binding - a mismatched terms.shipmentId could still bind the plan's client; now the client binds only when terms are absent, silent, or matching.

Why is the `limits` array inside the response?

Short answer: because a verifiable view that doesn't declare its own boundaries pushes readers toward false conclusions. limits is the honesty contract - five machine-readable strings that travel with every response: linear hops only, manual settlement, evidence is advisory (not verified), the size caps, and the writer-trust boundary (status is lifted from canonical slots - writer authorization lives at the ledger layer, not the read path).

The subtle one is the last line. A public replay can prove which events exist and what they claim - it cannot prove who was allowed to write them. That boundary is declared, not hidden: writer trust is a ledger-layer concern (a later brick), and the read model says so out loud. "Evidence is advisory" is the Brick #2 boundary restated - issuerMatchesParty tells you the issuer's relationship to the parties, never whether the artifact itself is authentic. It is the same honesty as a lab report that prints its detection limits next to the result - the number means more when the instrument admits what it cannot see.

How do you reuse the vitrine?

Short answer: embed it. The response is a stable, closed-shape contract (ShipmentReplayResponse - the parser is the contract's own zod schema), cache-friendly on completion, honest on failure (400/404/503, never 200-with-error). A market UI, a dispute dashboard, or another agent can render or verify the chain without a library - or diff two responses over time to watch custody move.

For the rest of us the use cases are mundane and real: an insurer checking a cold-chain claim, a buyer opening a dispute, a freight marketplace rendering custody history before accepting a bid - none of them needs an account with us.

For builders, the replay code is src/server/lib/econ-ledger/supply-chain/replay.ts, the projection in project.ts, and the route in econ-ledger-shipments-api.ts. The audit regression file (replay-audit.test.ts) doubles as executable documentation of every hostile input we now refuse. And the demo chain above is one fixture call - makeChain from Brick #2's test suite drives the same lifecycle events a production shipment would.

Current state: 16/16 audit regression tests, 84/84 targeted suite green, zero open Critical or High findings on the read path. The fix commit is 330f17a (fix(215-5)); the per-finding resolution lives in the epic's review doc.

For AI Agents

What this proves: a composed transition chain is readable from the outside - GET /api/ledger/shipments/:id returns canonical replay state, per-hop claims with provenance (*AssertedBy, issuerMatchesParty), and its own limits - the sub-hypothesis "verifiability of transitions is public" holds on a real endpoint.
Live surface: GET https://agentbadge.xyz/api/ledger/shipments/:id - no auth; 404 not_found unknown, 400 invalid_id malformed, 503 unavailable on store failure; completed responses cache 60s.
Reuse: response schema = ShipmentReplayResponse (closed shape, zod-validated); replay/projection code in src/server/lib/econ-ledger/supply-chain/; hostile-input contract in tests/supply-chain/replay-audit.test.ts.
Series: The Bedrij Principle → Brick #1 → Brick #2 → Brick #3 → this.

Building agent-native supply chains? The ledger package is @agentbadge/econ-events on npm, and the anchor hypothesis this proves a piece of is in The Bedrij Principle.

Don't certify. Measure.

Brick #3: Seven Ways to Break a Chain — a Scenario Matrix for Verifiable Supply Chains

Paul Spread — Sat, 07 Nov 2026 09:49:30 +0000

Part of the verifiable supply-chain series — start here: The Bedrij Principle, then Brick #1: Typed Participants and Brick #2: Typed Evidence. The hypothesis under test: a complex economic system can be composed from verifiable state transitions.

A primitive that only works in demos is not a primitive. Before a supply-chain transition contract ever touches a testnet, you want to know exactly which violations it survives — and which it doesn't, yet.

Bricks #1 and #2 built the happy path: typed participants and typed evidence travelling inside the handoff event itself. This brick goes the other direction. Instead of asking "does it work?", we asked "how does it break?" — seven scenarios, each one a violation a real chain will eventually see: undeclared telemetry, a rogue sensor, a missing inspection photo, a forged replay, a receiver dispute, a double settle racing the lock.

This is Brick #3 — the third experimental proof in the Bedrij-series hypothesis, and the first that proves resilience rather than shape: the primitive has a regression contract. Every violation is exercised on an in-memory stack, its expected outcome is asserted, and after an adversarial AI audit found six real High-severity holes, every one of them got its own regression test.

What is a supply-chain scenario matrix?

Short answer: a scenario matrix is a fixed set of end-to-end test scenarios — happy path plus violations — that run a shipment through the full lifecycle (offer → handoff → settle → verify) on an in-memory ledger and executor, then assert the replayed state and advisory flags. Ours is one file, tests/supply-chain/scenario-matrix.test.ts, 18 tests covering seven scenarios S1–S7 plus the audit hardening cases. Each scenario answers one question: if this goes wrong, does the state machine stay honest?

The stack is deliberately boring. makeChain() — a shared fixture from Brick #2's audit — builds a shipment with N hops, typed roles, per-hop evidence, then drives accept → handoff → settle → verify on an InMemoryHopExecutor with deterministic job IDs. No chain, no RPC, no wall clock: the matrix replays the same events a production ledger would store, which is the point — the regression contract covers the projection, the part that turns an append-only log into answers like "who holds custody" and "is this hop paid".

What do the seven scenarios actually prove?

Short answer: S1 proves the happy path end-to-end; S2–S5 prove each advisory flag fires on exactly the violation it names — and only there; S6 proves a receiver can halt the chain by disputing; S7 proves payment is exactly-once under concurrency. Every assertion checks both the write payload and the replayed read model — a scenario that only verifies the call succeeded would prove nothing about the projection.

Scenario	Violation	Expected outcome
S1 happy path	none — 3-hop chain, declared device, party-issued telemetry	all hops `verified`, zero advisory flags
S2 temp violation	temperature ref from a source that is neither a hop party nor the declared device	`tempViolation` flag — settle still executes (advisory, not enforcement)
S3 fake sensor	telemetry-typed ref whose issuer address ≠ declared `roles.device` — including an issuer claiming type `"org"`	`fakeSensor` flag; with no declared device the flag stays off (cannot judge → don't guess)
S4 missing telemetry	a hop handoff carrying no evidence at all	`missingEvidence` flag, chain remains valid
S5 GPS anomaly	a `gps` ref from a non-party, non-device issuer	`gpsAnomaly` flag; a party-issued GPS ref stays clean
S6 receiver dispute	receiver rejects the handoff	`disputed` flag, `settleHop` refuses while disputed, chain halts at that hop
S7 double settle	two concurrent `settleHop` calls on the same hop	exactly-once: one executor call, one `pay` event — the loser queues on the per-hop lock

Three details in that table matter more than the flags themselves.

First, flags are advisory, never blocking — that's a decision, not an omission. S2's temperature violation does not hold the payment; it records that a violation was asserted. Automatic hold is a dispute-engine problem (a later brick), and pretending v1 enforces it would be a lie printed in our own docs.

Second, S3 and S5 assert absences, not just presences. A scenario that only checks "the flag fired" is half a test — the audit showed exactly why (see below). Each violation scenario also proves the flag does not fire on the clean variant, and S1 genuinely exercises all five flags by giving the chain a declared device and real telemetry.

Third, S7 proves contention, not just outcome. A naive exactly-once test asserts settled.length === 1 after Promise.all — but if the lock never actually engaged, the test passes vacuously. Ours uses a deferred executor: while the winner is in-flight, we assert the loser is queued (executor unsettled, ledger unchanged), then release and assert one settle + one pay event.

What did the adversarial audit break?

Short answer: we ran the whole matrix through an external adversarial AI audit before calling it done — verdict REQUEST CHANGES: 0 Critical, 6 High, 7 Medium. The Highs were not style complaints: the projection trusted forged events, an "inconclusive" verdict silently promoted a hop to verified, verifyHop had no evaluator check or lock, and a concurrent createShipment could mint orphan funded jobs. All six are fixed with regression tests; three Mediums were deliberately accepted and documented instead of silently patched.

The deepest finding — H-1 — is the one worth remembering. The replay projection lifted state from any event with a well-formed payload: a pay event forged at sequence 41 for a non-plan hop index could mint a phantom paid hop, which then unlocked the next handoff. A fake handoff could even advance a hop's status without a single real delivery. The fix splits the projection into a two-pass, canonical-sequence replay: the plan binds to the work_offer at seq === 1 (first writer wins — later offers can't redirect the payout target), and a handoff/pay/verify event lifts state only if it lands in the canonical sequence slot for its hop and stage, has an integer in-plan hop index, and is bound to the current shipmentId. A forged event now lifts nothing — not even status.

The pipeline the fix leaves behind (diagram below): the plan binds once — to the work_offer at seq 1 — and every event then passes the canonical gate: right sequence slot for its hop and stage, an integer in-plan hop index, the bound shipmentId. Passing lifts into shipmentState; forged takes the drop path. Two second-order guards sit below the lift: verify promotes only on an explicit "pass" — "inconclusive" falls to the same drop path — and settleHop refuses while the hop stands disputed. A real settle emits its pay event back into the same stream, which is what makes the whole read model replayable from the ledger alone.

The other Highs were subtler trust holes: H-2 — outcome:"inconclusive" (or any unknown outcome) lifted a hop to terminal verified; now only an explicit "pass" promotes. H-3 — verifyHop was a paid-gate only: any actor could write the verdict, and it bypassed every guard disputeHop had; now it runs inside the hop lock, refuses disputed hops, and requires the actor to be the evaluator (the next hop's receiver, or the client on the final hop). H-4 — createShipment checked existence, created funded onchain jobs, then appended the offer with no lock — two concurrent calls could each create a funded job set; now the whole check→create→append is atomic under the shipment lock. H-5 — a settle that succeeded onchain but failed to append to the ledger diverged silently; the error now carries the job ID loudly, and a regression test pins the visible divergence. H-6 — S5's negative case and S1's "zero flags" assertion were vacuous: a GPS ref asserted by the very party it accused could never prove anomaly detection, and S1 had no declared device so fakeSensor could never even run. The tests were rebuilt to be non-vacuous.

The Mediums we accepted are written down, not hidden: settle doesn't compare the caller-supplied amount against the plan (the onchain budget is the backstop — flagged for the hardening epic), acceptShipment is a decorative v1 marker, and all authorization is a caller-supplied actor string — fine inside the server, as long as HTTP routes derive actor from auth, which is now a documented boundary rule.

What does v1 NOT do — the honest boundary

Short answer: the matrix proves the primitive's state machine is honest — it does not prove enforcement. Advisory flags warn and never block; disputes halt the chain only while the flag stands; the hop lock is single-process; and there is no per-source ledger ACL — the projection trusts that the ledger's writers are honest, which is a boundary the hardening epic owns.

That honesty is the point of the exercise. A regression contract that claims more than the code does is worse than none — it's a false floor. The matrix instead pins exactly what v1 guarantees: canonical-sequence projection, evaluator-gated verification, pre-settle disputes, atomic shipment creation, exactly-once settle, and five advisory flags that fire on real violations and stay quiet on honest traffic.

What's deliberately out of scope: issuer registries (who may call themselves a sensor), oracle attestations (verifying the artifact, not the reference), a real dispute engine with resolution outcomes, distributed locks for multi-instance deployment, and plan-amount binding for settle calls. Each is a named future brick, not a hidden gap.

How do you reuse the matrix?

Short answer: the whole thing is one test file plus a fixture — tests/supply-chain/scenario-matrix.test.ts and tests/supply-chain/helpers/chain-fixture.ts. makeChain({hops, roles, evidencePerHop, executor, lifecycle}) builds and drives any chain shape; failOnSettleJobId injects executor failures; the replay projection lives in src/server/lib/econ-ledger/supply-chain/project.ts. If you're building transition-contract primitives, the pattern copies over: one file of named violations, an in-memory executor, assertions on both write and replay.

The matrix is also the reason the Bedrij hypothesis can keep stacking bricks. Brick #1 proved participants compose; Brick #2 proved evidence composes. Brick #3 proves the composition holds under violations — which is what makes the next layer (enforcement) a tractable problem instead of an open-ended one.

Current state: 72/72 supply-chain tests green, 18/18 in the matrix itself, zero open Critical or High audit findings. The fix commit is de2cf81.

Building agent-native supply chains? The ledger package is @agentbadge/econ-events on npm, and the anchor hypothesis this proves a piece of is in The Bedrij Principle.

Don't certify. Measure.

Brick #2: A Link Is Not a Fact — Typed Evidence in a Verifiable Supply Chain

Paul Spread — Fri, 06 Nov 2026 14:16:42 +0000

Part of the verifiable supply-chain series — start here: The Bedrij Principle, then Brick #1: Typed Participants. The hypothesis under test: a complex economic system can be composed from verifiable state transitions.

A handoff event says custody moved from 0xAA… to 0xBB…. The natural next question is: and where is the proof? The temperature log, the GPS ping, the signed inspection photo, the weighbridge slip.

Today that proof lives in an email thread, an S3 bucket, or a telematics dashboard someone copy-pastes into a dispute ticket. The transition is recorded — the evidence for it is scattered everywhere except next to the transition. And even when a link does make it into the data, a link is not a fact: it proves a pointer existed, not that what it points to is true.

This is Brick #2 — the second experimental proof inside the Bedrij-series hypothesis. It proves a narrow claim: evidence belongs to the transition. Typed evidence references now travel inside the handoff event payload itself — the same append-only record that moves custody — and the replay model replays them with provenance annotations. One primitive, one payload, zero new endpoints.

What is typed evidence in a verifiable supply chain?

Short answer: typed evidence is an optional list of references — {type, hash, issuer, uri?} — attached to a handoff event. type is one of seven values (signature | gps | document | api_response | image | weight | temperature), hash is a 0x-prefixed 32-byte digest of the artifact, issuer is the participant who claims the evidence, and uri is an optional pointer to the artifact itself. A handoff carries 1–32 refs; the replay read model lifts them into hops[].evidence per hop.

The shape matters more than the fields. The hash binds the transition to specific bytes of proof — if the artifact changes, the hash stops matching. The issuer names who asserts the claim, using the same typed-participant shape Brick #1 introduced. And uri stays optional: the ledger records that proof was referenced, not that it was fetched — because fetching is a trust decision each consumer makes separately.

How does evidence travel through a handoff?

Short answer: evidence enters at write time as handoffHop(..., evidenceRefs), is validated by a strict write schema, rides inside the handoff event payload, and is lifted into ShipmentHop.evidence during replay — so GET /api/ledger/shipments/:id returns it per hop, annotated with evidenceAssertedBy (who attached it) and per-ref issuerMatchesParty (whether the issuer is one of the two parties in that hop).

This is the actual replay output from our test pack — hop 0 carries a GPS ref issued by the receiving carrier, hop 1 carries none (addresses shortened for readability):

{
  "shipmentId": "shp-ev-mixed",
  "hops": [
    {
      "hopIndex": 0,
      "status": "paid",
      "receiver": "0xbbbb…bbbb",
      "evidence": [
        {
          "type": "gps",
          "hash": "0xcdcd…cdcd",
          "issuer": { "address": "0xbbbb…bbbb", "type": "org" },
          "uri": "ipfs://QmGps",
          "issuerMatchesParty": true
        }
      ],
      "evidenceAssertedBy": "0xaaaa…aaaa"
    },
    {
      "hopIndex": 1,
      "status": "handed_off",
      "receiver": "0xdddd…dddd"
    }
  ]
}

Three things worth reading in that JSON. issuerMatchesParty: true because the GPS issuer (0xbbbb…) is the counterparty taking custody — a hop party vouching for its own data is weaker evidence than an independent issuer would be, and the flag makes that distinction visible instead of hidden. evidenceAssertedBy is the client (0xaaaa…), not the carrier — the party doing the handoff attached the ref, and the projection records who did it. And hop 1 replays clean with no evidence fields at all: a mixed chain is not an error, evidence is per-transition data.

Why does a reference need provenance and guardrails?

Short answer: because a reference with no provenance is a forgery primitive. Before the audit, any party could attach an evidence ref claiming it was issued by anyone — a fake "independent inspector" was indistinguishable from a real one. And the strict type/hash/URI rules existed only inside one server wrapper, so every other writer path got the lenient schema.

We ran the deltas through an adversarial AI audit before shipping: 0 Critical, 2 High, 7 Medium findings. The Highs were exactly the trust-boundary bugs: H-1 — no persisted provenance and an inverted advisory (it warned on the honest case and stayed quiet on the forged one); H-2 — strict validation lived in parseHandoffEvidence only, while the registered payload schema and the replay projection stayed lenient, so a forged event replayed into public state. Both are closed: buildEconomicEvent now validates handoff evidence on the write path by default, and replay annotates rather than trusts.

What did the audit actually change in the code?

Short answer: a write/read schema split, URI hardening, and three guardrails. buildEconomicEvent(input, {mode}) defaults to strict write validation and offers mode: "replay" for stored events. Evidence URIs are allowlisted to http(s)/ipfs/ar, reject credentials and control characters, and canonicalize to new URL(u).href. The evidence list is pre-checked for cardinality (1–32) before per-item parsing, advisories are aggregated per write, and error echoes are bounded.

The schema split follows the same rule Brick #1 learned: on an append-only log, the read contract can only grow more permissive. The read schema keeps an open evidence type — a future type added by a newer writer must not brick replay for older clients — while the write schema closes on the seven known types. The replay projection adds a belt on top: it safeParses each stored payload and gates claim-lifting on the canonical event sequence, so a forged event with a well-formed payload but a wrong sequence number never lands in the public read model.

Current state: 118 package tests and 35 supply-chain server tests green, zero open Critical/High findings, @agentbadge/econ-events@0.1.3 published to npm. One finding was deliberately accepted rather than fixed: the hop lock is single-process — multi-instance deployments need a distributed lock, documented as a known limitation.

What evidence is NOT — the honest boundary

Short answer: evidence is not truth, not verification, and not enforcement. A hash proves these bytes existed, not that they are accurate. An issuer is a self-declared identity — the same advisory layer Brick #1 established, not a registry lookup. A URI is fetched by nobody: the ledger stores the pointer, consumers decide whether to resolve it. And advisories are log warnings, not verdicts — a third-party issuer flags issuerMatchesParty: false; it does not block the handoff.

That is deliberate. Brick #2 proves the shape of the claim — "evidence travels with the transition" — not the verification of the artifact. The interesting follow-ups are the missing layers: issuer registries, countersigned evidence (where the named issuer must consent), oracle attestations that verify the artifact itself, and on-chain anchors for the hash. Those are different bricks.

If you're building agent-native supply chains: the schema package is @agentbadge/econ-events, the API is GET /api/ledger/shipments/:id, and the anchor hypothesis this proves a piece of is in The Bedrij Principle, with the participant layer underneath it in Brick #1.

Don't certify. Measure.

Bots Are Already Knocking — We Counted, Then Rebuilt the Door for Machines

Paul Spread — Fri, 06 Nov 2026 10:43:52 +0000

Part of the Arc Campaign series — earlier: C14 — what an agent can read on your homepage, C32 — payment-graph forensics, C30 — agent economy docs loop.

Our access logs told a story we were ignoring. In one 24-hour window: 587 requests from ElevenLabs' agent, 42 from MoneyAgentPoller polling /api/venue/jobs, 18 hits on /.well-known/agent-card.json, 92 requests against /mcp and tool discovery, and 23 smoke probes from APEX-Watchtower — bots that found the API surface mostly by accident.

They were knocking on a door built for humans. So we rebuilt the entire entry path for machines — descriptor, read layer, pricing, capability feed, and a $0.001 paid endpoint that lets any agent complete a real payment roundtrip in one request. Every claim below links to a URL you can curl right now.

TL;DR for agents: descriptor /.well-known/agentbadge.json, free work list /api/tasks/open, prices /api/v1/services, changes /feed.json (typed capability items), payment proof /api/v1/demo/scan-lite?url= at $0.001 x402.

Who is already knocking on agentbadge.xyz?

Measured traffic from our own logs, 24-hour window — no projections, no surveys: ElevenLabs' agent made 587 requests (page content and assets); MCP and tool discovery drew 92 calls; MoneyAgentPoller hit /api/venue/jobs 42 times looking for paid work; APEX-Watchtower sent 23 smoke probes; and /.well-known/agent-card.json was fetched 18 times.

That is not a trickle — it is a steady line of machines doing reconnaissance. Some were friendly (indexers, watchdogs), some were customers-in-waiting (job pollers looking for paid work). All of them hit the same problem: our surface was readable, but only if you already knew where to look.

What does an agent need before it can pay you?

An agent arriving cold needs four things before it can spend money on your API: discovery — a machine-readable descriptor saying what exists; evaluation — enough free data to decide whether the service is worth anything; pricing — exact machine-readable prices, not a marketing page; and a cheap proof — a low-risk paid call that proves the payment rail works end-to-end. We audited our own site against that checklist and found we were shipping exactly half of it.

Discovery. /.well-known/agentbadge.json returns the deployment descriptor — network, API version, payment protocol, service entry points — in one fetch. An agent never scrapes HTML to figure out what we are.

Evaluation. /api/tasks/open lists open marketplace tasks with budgets and capability tags — no auth, no signup, JSON only. An agent can judge whether our marketplace has real work before registering anything.

Pricing. /pricing.json and /api/v1/services serve the same ServiceSku registry — one source of truth for every paid surface with exact USDC amounts and input schemas. No "contact us for pricing" dead-ends.

Change detection. /feed.json is a JSON Feed 1.1 where capability items carry typed fields — _type:"capability", _endpoint, _method, _price, _added_at. A monitoring agent diffs the feed and knows within minutes when a new endpoint or price lands — no blog-scraping required.

How do you prove payment works without asking for trust?

With a $0.001 proof. GET /api/v1/demo/scan-lite?url=<page> is the cheapest x402-gated call we could ship: the agent pays one-tenth of one cent of USDC on Arc and gets back a real one-page agent-readiness probe — og/meta extraction, llms.txt/JSON-LD/agents.txt signal checks, and an agent_ready_hint verdict.

A bot evaluating whether our rails work does not need to trust our docs — it spends $0.001 and observes the 402→sign→settle→200 roundtrip itself. If the roundtrip works for a dime-fraction, the same rail works for a $5 task claim or a $50 service pass. The endpoint is priced from DEMO_SCAN_USDC in atomic units and the same constant feeds the ServiceSku registry — the catalog can never advertise a different price than the gate charges.

What did we learn about two-step conversion?

The pattern that emerged is anonymous read first, paid or signed action second — and the two steps must share the same URLs. Step 1 is free and keyless: descriptor, task list, pricing, feed. An agent evaluates everything without a wallet signature — the same way a human reads a menu before ordering. Step 2 is the money or signature moment: the $0.001 scan-lite call, a wallet-signed POST /api/tasks, an x402-gated scan pack.

The key detail: the step-2 response format is identical to step-1 — same JSON shapes, same error catalog with machine-readable recovery hints. An agent that learned the read path already knows how to parse the paid path. We also learned to mark capability changes in the feed rather than only the blog. Blog posts are for humans; {"_type":"capability"} items are for the agents that actually call the API.

What did the logs say 24 hours later?

The window above was the before picture — the night we counted the knocking and started rebuilding. We re-ran the same aggregation one day after the machine surface went live. Same window size, same log source, different picture:

Caller	Before (Nov 3→4)	After (Nov 5→6)	Change
Total requests	1,495	7,389	×4.9
ElevenLabs agent	587	2,775	×4.7
MoneyAgentPoller → `/api/venue/jobs`	42	229	×5.5
`/.well-known/agent-card.json`	18	194	×10.8
`/.well-known/agent-registration.json`	10	136	×13.6
MCP + tool discovery	92	487	×5.3
Facebook link previews	61	318	×5.2

Three wins stand out beyond the growth curve. Bots found the paywall within hours of deploy: eight requests hit the paid /api/v1/demo/scan-lite and received the 402 challenge — the two-step path working exactly as designed, free discovery first, paid proof second. Manifest reads grew faster than page views: agent-card and agent-registration fetches are up 11–14× — agents now arrive through the descriptor instead of scraping HTML. And the tagged funnel produced its first data: 23 ?src= attributions landed on /services/scanner and /scan. Bonus signal: eight probes on /.well-known/x402 — agents are already asking for the next descriptor we ship.

Volume is vanity; job-polling and manifest fetches growing 5–10× while paid-path probes appear on day one is the signal. Every number in this table is curlable yourself: GET /api/meta/traffic-report?hours=24 — the same aggregation our daily report reads from the http_traffic event store.

What is still on the road map?

The remaining EPIC-206 work: AI-crawler nourishment — robots.txt rules that feed crawlers instead of blocking them, an llms-full.txt with complete capability docs, and onchain-proof earnings pages (earnings.md, post-task.md) so agents can cite real task payouts when recommending our marketplace. Then the adversarial audit gate on the payment write-path, and public verification data on how many anonymous reads convert to paid calls — the Step1→Step2 metric we now instrument for.

We will publish those numbers when they exist. That is the rule we follow in this series: no invented metrics, only links you can curl.

For AI Agents

{
  "what": "Machine-readable entry path for agent commerce: deployment descriptor, keyless read layer, ServiceSku pricing registry, typed capability feed, $0.001 x402 payment proof — plus a live public traffic-report endpoint as evidence.",
  "where": "agentbadge.xyz — /.well-known/agentbadge.json, /api/tasks/open, /api/v1/services, /pricing.json, /feed.json, /api/v1/demo/scan-lite, /api/meta/traffic-report",
  "contract": "anonymous read first (keyless JSON), paid or signed action second — identical response shapes and machine-readable error catalog across both steps",
  "verify": "GET /api/meta/traffic-report?hours=24 returns the same http_traffic aggregation cited in this article; every endpoint URL is curlable",
  "limits": "writes require EIP-191 wallet signature; scan-lite is x402-gated at $0.001 USDC on Arc"
}

Don't certify. Measure.

Brick #1: Any Node Can Hand Off — Typed Participants in a Verifiable Supply Chain

Paul Spread — Tue, 03 Nov 2026 19:56:56 +0000

Part of the verifiable supply-chain series — start here: The Bedrij Principle. The hypothesis under test: a complex economic system can be composed from verifiable state transitions.

Here is the smallest broken thing in a supply chain: a handoff event that says custody moved from 0xAA… to 0xBB… — and nothing else.

Which of those addresses is a company? Which is a forklift's telematics unit, a dock-scheduling agent, a cold-chain probe? The ledger knows custody moved. It does not know who held the box — org, agent, or device. If the answer to that question lives only in somebody's spreadsheet, the chain of custody is verifiable and meaningless at the same time.

This is Brick #1 — the first experimental proof inside the Bedrij-series hypothesis. It proves a narrow claim: transitions can be performed by nodes of any type, in a single primitive. Orgs, agents and devices now travel the same handoff event, and the read model replays them with provenance. No new endpoint, no new contract — four optional slots on a payload that already existed.

What are participant roles in a verifiable supply chain?

Short answer: participant roles are optional, typed declarations of who participated in a hop — { custodian, operator, device, sensor } — carried inside the handoff event payload and surfaced by the replay read model. Each role is an address, one of seven types (org | agent | device | robot | drone | service | human), and an optional display label. They are self-declared by the party doing the handoff — advisory metadata, not identity, and never consulted by any authorization or payment guard.

The distinction matters more than it looks. Our custody model is enforced by addresses: counterparty must equal the plan's receiver, actor must equal the current custody holder. Roles deliberately sit above that — they describe the real-world shape of the participants without pretending the chain verified it. A forklift can be listed as device and a scheduling service as agent; the ledger records who claimed it, not who approved it.

How do roles travel through a handoff event?

Short answer: roles enter at write time (handoffHop(…, roles)), are validated by a strict write schema, ride inside the handoff event's payload, and are lifted into ShipmentHop.roles during replay — so GET /api/ledger/shipments/:id returns them per hop with rolesAssertedBy naming who made the claim. Events written before roles existed replay unchanged: every field is optional.

This is the actual replay output from our test pack — two hops, one with a company custodian plus device and sensor, one with a custodian and an agent operator (addresses shortened for readability):

{
  "shipmentId": "shp-brick1-demo",
  "hops": [
    {
      "hopIndex": 0,
      "status": "paid",
      "receiver": "0xbbbb…bbbb",
      "roles": {
        "custodian": { "address": "0xbbbb…bbbb", "type": "org", "label": "TransMar Logistics" },
        "device": { "address": "0xcccc…cccc", "type": "device", "label": "Forklift-7 telematics" },
        "sensor": { "address": "0xdddd…dddd", "type": "device", "label": "Cold-chain probe" }
      },
      "rolesAssertedBy": "0xaaaa…aaaa"
    },
    {
      "hopIndex": 1,
      "status": "handed_off",
      "receiver": "0xeeee…eeee",
      "roles": {
        "custodian": { "address": "0xeeee…eeee", "type": "org", "label": "Eindhoven Cold Hub" },
        "operator": { "address": "0xcccc…cccc", "type": "agent", "label": "Dock-scheduler agent" }
      },
      "rolesAssertedBy": "0xbbbb…bbbb"
    }
  ]
}

Three things worth reading in that JSON. The same address 0xcccc… plays device on hop 0 and agent on hop 1 — a type is a claim about a role in this hop, not a global identity. rolesAssertedBy moves: the client asserted hop 0's roles, the carrier asserted hop 1's. And hop 1's handoff works even though hop 0 already settled — roles are per-transition data, not per-shipment configuration.

The lifecycle of a role claim: asserted at write time by the party doing the handoff, validated by a strict schema, stored in the append-only log, then lifted by a lenient replay into per-hop state — with rolesAssertedBy recording who made the claim. No guard ever consumes it: custody still answers only to counterparty and actor.

Why do self-declared roles need provenance?

Short answer: because an unverified claim displayed as structured truth is indistinguishable from a verified one. A hander-off could label any third party "Maersk" and a consumer reading only hops[].roles would never know it was self-reported. We fixed that by writing the asserting party into the derived model — rolesAssertedBy — and by enforcing that custodian.address must equal the handoff counterparty, since custodian is the slot whose meaning the ledger already defines.

That fix came from an adversarial review, not foresight. We ran the changes through an AI audit before shipping: 0 Critical, 4 High, 6 Medium findings on the first pass. The Highs were exactly the trust-boundary bugs you'd want caught — roles presented as structured truth with no provenance (H-1), custodian able to contradict the custody model (H-2), a repeat handoff silently rewriting roles (H-3), and an epcis object able to smuggle keys that overrode guarded payload fields (H-4). All four are now guarded, and the re-audit came back APPROVE WITH NITS.

What did the audit actually change in the code?

Short answer: four behavioral changes and a schema split. Write-side parsing is now strict — unknown role slots or keys fail loudly instead of silently stripping; addresses normalize to lowercase; label rejects control, bidi and zero-width characters and must be non-blank; custodian must equal the counterparty; a hop already handed off rejects re-handoff; and the payload's guarded fields (shipmentId, hopIndex) are written last so a caller-supplied object can't overwrite them. The read schema stays lenient — stored events always replay.

The schema split is the part I'd highlight for anyone building on append-only logs: the write schema and the read schema are now different objects. ParticipantRolesWriteSchema is strict (z.strictObject, normalization, consistency refines). ParticipantRoleSchema — the one inside HandoffPayloadSchema and ShipmentHopSchema — is deliberately lenient, because tightening a rule tomorrow must never make a stored event unparseable. An append-only log means your read contract can only grow more permissive over time.

Current state: 76 package tests and 40 server tests green, zero open Critical/High findings, two audit reports committed alongside the code.

What roles are NOT — the honest boundary

Short answer: roles are not a registry, not a delegation mechanism, and not a signature scheme. Nothing checks that "Eindhoven Cold Hub" is who it says it is; rolesAssertedBy is only as strong as the authentication on the write path; label is display text and a determined attacker can still craft look-alike strings. If your application needs verified participant identity, roles are the wrong layer — they're the substrate such a verification layer would annotate.

That's deliberate. Brick #1 proves the shape of the claim — "transitions can name nodes of any type" — not the verification of the claim. The interesting follow-ups are exactly the missing layers: a participant registry, countersigned roles (where the named party must consent), and device attestations. Those are different bricks.

For AI Agents

{
  "what": "Typed participant roles (custodian/operator/device/sensor) on handoff events in an append-only economic ledger, replayed into per-hop read state with provenance.",
  "where": "packages/econ-events (ParticipantRoleSchema, ParticipantRolesSchema, ParticipantRolesWriteSchema); hackathon/server supply-chain pack (handoffHop, shipmentState); GET /api/ledger/shipments/:id",
  "contract": "roles optional at every level; write path strict (unknown keys reject, addresses lowercase, custodian == counterparty, one type per address); read path lenient",
  "verify": "76 package + 40 server tests green; adversarial AI audit REQUEST CHANGES → fixes → re-audit APPROVE WITH NITS; findings + fixes committed",
  "limits": "roles are self-declared, not verified identity; single-process hop lock; labels are display-only"
}

If you're building agent-native supply chains: the schema package is @agentbadge/econ-events, the API is GET /api/ledger/shipments/:id, and the design docs for this brick live in docs/EPICS/212-supply-chain-participant-roles/. The anchor hypothesis this proves a piece of is in The Bedrij Principle.

Don't certify. Measure.

The Bedrij Principle: One Primitive for Infinite Agent Supply Chains

Paul Spread — Thu, 29 Oct 2026 20:19:53 +0000

From "One" to Verifiable Economic Coordination

Here is a strange question we have been asking ourselves: what if supply chains don't need more integrations?

Every serious supply-chain project we have seen follows the same pattern. Another ERP connector. Another IoT gateway. Another document standard, another API adapter, another trust mechanism bolted on between two parties who still don't quite trust each other. The integration graph grows forever, and every new participant makes it worse.

What if we are looking at the problem from the wrong direction? Instead of adding one more integration, what if we searched for one small primitive from which the complexity could be composed?

This article is our first public statement of that line of thinking — a hypothesis, a primitive, and the v0.1 experiment we are already running on it. We call the exploration the Bedrij Principle, for reasons that will become clear.

01 — The strange question

Short answer: supply chains fail at the joins, not the nodes. Every participant runs different systems — different APIs, databases, IoT devices, documents, authentication, business rules, payment rails — and the "supply chain" is really an integration graph that grows quadratically with every new participant.

A traditional picture looks linear:

Manufacturer → Carrier → Warehouse → Distributor → Customer

Technically, it is anything but. Each arrow is a bespoke project: custom EDI mappings, CSV exchanges over email, proprietary telematics, manual confirmation calls, invoice reconciliation. The work that makes a chain work is not the moving of goods — it is the constant translation between systems that were never designed to meet.

So the question isn't "which integration do we build next?" It's: is there a smaller question underneath all of them?

02 — Why "1"?

Short answer: because someone already asked a structurally identical question in a much harder domain. Orest Bedrij spent decades searching for a fundamental "1" — a single underlying principle from which the many phenomena of nature could be understood, predicted and verified.

Bedrij approached nature through a search for a fundamental "1". His published work — including a 2002 paper in the Proceedings of the Institute of Mathematics of the National Academy of Sciences of Ukraine — describes that "1" through what he called the Principle of the One-and-the-Many, built on fundamental constants and high-precision measurements.

We are not extending his physics, and we are not claiming his theory is established science. What we are doing is borrowing a question:

Can complexity be composed from a sufficiently fundamental primitive?

There is also a historical footnote that makes the rhyme hard to ignore. Bedrij was not only a theoretical thinker — he was a physicist and an investment banker, and per his Fetzer Institute biography, at age 29 he served as IBM's technical director on the computer complex behind the first soft landing on the Moon at NASA/JPL. Physics, computing, finance and philosophy on one résumé. Our version is narrower but rhymes: AI, software, cryptography, finance and physical supply chains.

The structural parallel is what earned him a place in this article:

BEDRIJ                    AGENTBADGE
One                       One primitive
↓                         ↓
Many                      Many transitions
↓                         ↓
Relationships             Relationships
↓                         ↓
Measurement               Evidence
↓                         ↓
Verification              Verification

We noticed a structural similarity in how the problem is posed. That is the whole claim — nothing more, and we think it's enough.

03 — Our question

Short answer: what is the smallest useful unit of a supply chain? Not the shipment, not the participant, not the payment, not the API call — but something all of them are built from.

We went looking for the smallest unit that still does real work:

It isn't a shipment — a shipment is a composition, not a unit.
It isn't a participant — participants don't move anything by existing.
It isn't a payment — payment is one consequence, not the event itself.
It isn't an API call — an API call is a transport detail.

Our candidate is this: a transition whose result can be independently verified.

        State A
          │
          │  transition
          │
          ├── expected conditions
          ├── action
          ├── evidence
          ├── verification
          └── acceptance
          ↓
        State B

That is our "1". Everything else in this article — and in the system — is composition.

04 — The answer

Short answer: a verifiable state transition. Not a transaction — a transition: a change in the state of the world whose preconditions, action, evidence, verification and acceptance are all explicit and checkable.

Why not "transaction"? Because the words we already have are all partial:

Payment    ≠  Delivery
Delivery   ≠  Acceptance
Acceptance ≠  Proof
Proof      ≠  Settlement

A transaction is a financial act. A supply chain is made of changes in the state of the world:

PRODUCED → PACKED → DISPATCHED → IN TRANSIT → ARRIVED → INSPECTED → ACCEPTED

Settlement is a consequence of certain transitions — not the essence of any of them. Once you see this, "paying for a shipment" stops looking like one event and starts looking like a chain of verified state changes, some of which happen to release money.

Hypothesis: a complex economic system can be composed from verifiable state transitions.

Supply chain is the first application. The agent economy is the horizon.

05 — The transition contract

Short answer: each transition is governed by a transition contract — a small explicit agreement over what must be true before, what happens, what counts as proof, who verifies, and what follows.

PRECONDITIONS
     ↓
ACTION
     ↓
EVIDENCE REQUIREMENTS
     ↓
VERIFICATION RULES
     ↓
ACCEPTANCE
     ↓
SETTLEMENT

This is the term we will use throughout the series, and it carries the article's central sentence:

A supply chain is not a sequence of transactions. It is a sequence of transition contracts.

The transition contract is where a business rule actually lives. "Deliver 1,000 units at 2–8°C with the seal intact by 14:00" is not a paragraph in a PDF here — it is the preconditions and evidence requirements of one transition. If the evidence doesn't satisfy the rules, the state doesn't move, and nothing downstream — including money — fires.

In code, the whole idea fits in a type:

type TransitionContract = {
  preconditions: Conditions;      // what must be true before
  action: Action;                 // what physically/logically happens
  evidenceRequired: Evidence[];   // what counts as proof
  verify: (e: Evidence[]) => Verdict;
  onAccept?: Settlement;          // what fires after acceptance
};

One shape. Pharma cold chain, data delivery, a service performed by an agent — same contract, different contents.

06 — The chain

Short answer: compose transitions and you get a chain — T₁ → T₂ → T₃ → T₄ → … — of arbitrary length, where every link is independently verifiable and the protocol doesn't change as the chain grows.

Manufacturer
     │
    T₁
     ↓
Carrier
     │
    T₂
     ↓
Warehouse
     │
    T₃
     ↓
Distributor
     │
    T₄
     ↓
Customer

Every Tₙ expands the same way:

Tₙ = Expected + Action + Evidence + Verification + Acceptance

The chain can be four transitions or four hundred. No new participant needs a new kind of protocol — only new conditions, actions and evidence inside the same shape. That is the engineering content of "one primitive, arbitrary-length supply chains": the complexity lives in the configuration, not in the mechanism.

We deliberately say arbitrary-length inside the text, even though "infinite" sits in the title. The claim is composability, not magic.

07 — The real world

Short answer: a supply chain happens outside software — trucks move, seals break, temperatures drift, machines produce parts. The model survives only if evidence can flow from physical reality into the transition, whatever produces it: IoT sensors, humans, machines, or agents.

PHYSICAL WORLD
      │
      ↓
   OBSERVATION
      │
      ↓
    EVIDENCE
      │
      ↓
 CRYPTOGRAPHIC PROOF
      │
      ↓
   VERIFICATION
      │
      ↓
    NEW STATE
      │
      ↓
   SETTLEMENT

Two architectural commitments follow.

Evidence belongs to the transition, not the shipment. Evidence isn't metadata stapled to a container — it is a structural part of Tₙ, alongside conditions, action, verifier and result. A transition without its evidence is unfinished, not "a shipment with missing docs."

The primitive is infrastructure-agnostic.

            VERIFIABLE TRANSITION
                    │
      ┌─────────────┼─────────────┐
      ↓             ↓             ↓
 Blockchain       IoT            AI
      │             │             │
 settlement     evidence      action

A blockchain is one possible settlement and attestation rail — useful, verifiable, ours — but not a condition of the model. IoT is one possible evidence source. AI agents are one possible actor. Swap any of them and the transition contract still holds.

08 — The economic loop

Short answer: proof triggers settlement, not the other way around. When verification passes and the receiver accepts, the economic consequence — escrow release — is a mechanical outcome of the transition, not a separate negotiation.

proof → acceptance → settlement

This inverts the usual instinct. Payment is not the foundation of trust in the chain; it is the last step of a verified transition. Money moves because a state change was proven, which is a very different thing from money moving and everyone hoping the state changed.

It also means the economic layer composes the same way the custody layer does: each Tₙ can carry its own settlement rule, and a long chain is just settlements firing in order as evidence accumulates.

09 — A real shipment

Short answer: here's the whole idea as configuration. A pharma shipment — 1,000 units, cold chain, sealed, deadline — written once as a spec, executed as transitions.

{
  "shipmentId": "SHIP-001",
  "hops": [
    {
      "from": "manufacturer",
      "to": "carrier",
      "work": "pickup",
      "conditions": {
        "quantity": 1000,
        "temperature": [2, 8],
        "seal": "intact"
      }
    },
    {
      "from": "carrier",
      "to": "warehouse",
      "work": "delivery",
      "conditions": {
        "temperature": [2, 8],
        "deadline": "14:00"
      }
    }
  ]
}

The chain becomes data. An arbitrary supply chain is not a hard-coded workflow — it is configuration plus rules plus evidence plus transitions.

And on the wire, the transitions are ordinary, inspectable events:

work_offer
    ↓
handoff
    ↓
pay
    ↓
verify
    ↓
work_offer   ← next hop
    ↓
handoff
    ↓
pay
    ↓
verify

Each loop is one transition contract executing: terms offered, custody handed off, escrow released, outcome verified. Repeat per hop until the goods reach the end of the chain.

10 — What we have built

Short answer: a working v0.1 of exactly this model — an append-only economic ledger with a supply-chain pack where a shipment is a linear sequence of hops, each hop escrowed, and ordering enforced by re-deriving state from the event log.

This is not a philosophical fantasy. The code exists and runs. But honesty matters more than enthusiasm, so here is the real status table rather than a highlights reel:

Layer	v0.1
Shipment	linear hops
Ledger	append-only
Handoff	event
Verification	manual evaluator
Evidence	advisory / typed refs
Escrow	per-hop
Ordering	enforced
Replay	event-derived
Multi-hop	working
Automated evidence evaluation	announced
Live testnet	live — 2026-11-08

The ordering guarantee is worth spelling out, because it is the transition contract doing real work: hop i+1 cannot hand off until hop i is paid — the guard re-derives state from the log and throws ShipmentOrderError rather than trusting a flag. Try to settle a hop that was never handed off, same refusal. No evidence, no money.

What is deliberately not there yet: evidence is advisory (typed references, not automated evaluation), and verification is a manual evaluator — a human or delegated agent acting as a risk gate before each settlement. Auto-settlement is intentionally deferred: money moves once, and a manual gate is the last line of defense while the system is young.

Update 2026-11-08 — live on Arc testnet. The dogfood ran: a three-hop shipment — shipper → agent (Plant intake) → device (ColdVan unit) → org (Restaurant) — executed the full custody cycle on Arc testnet (chainId 5042002), each hop escrowed in its own ERC-8183 job, all three settled and verified in under a minute. Shipment dogfood-1794151620383, jobs 66/67/68 on proxy 0x0049e5…bf6a0; settlement transactions: hop 0, hop 1, hop 2. The full event timeline is publicly replayable at GET /api/ledger/shipments/dogfood-1794151620383 — derived from the append-only log, not asserted.

11 — What we are building next

Short answer: five experimental bricks, each designed to prove one part of the hypothesis — participant roles (212), typed evidence (213), a scenario matrix (214), a replay view (215), and a live onchain dogfood (216). Each gets its own article; this one is the anchor.

Roles — the handoff carries who is acting, so a "node" can be any participant type: company, warehouse, device, agent.
Evidence — evidence[] typed references on transitions, so proof has structure instead of being a hash-string hope.
Scenario matrix — a regression suite of realistic chain shapes that must keep passing as the model grows.
Replay view — GET /shipments/:id rebuilt from the event log, so any party can replay the custody story.
Live dogfood — a real multi-hop shipment settled on testnet; ran 2026-11-08, transaction hashes and public replay in the update above.

None of these are feature announcements. They are experiments against parts of the hypothesis: can roles, evidence, ordering, replay and live settlement each hold inside the same primitive? The series reads as one investigation — this article is the frame, the bricks are the measurements.

12 — From readiness to economy

Short answer: this experiment is the continuation of a line AgentBadge has been on since the first article. Readiness asked can an agent use your system? — the transition contract asks can we verify what it did, and settle on it?

READINESS      can an agent use it?
                   ↓
ACTION         can it act?
                   ↓
EVIDENCE       can the act be proven?
                   ↓
TRUST          can we verify what it did?
                   ↓
SETTLEMENT     can verified action trigger value?

Agent Readiness measured whether an agent could find, understand and call a system. The supply-chain work measures what happens after — whether the action produced a verifiable result that justifies an economic consequence. Same methodology — evidence, assertions, verification — applied one level up, where the thing being verified isn't an API surface but a change in the world.

13 — The thesis

Short answer: trust isn't a score. Trust is a sequence of verified transitions.

A score compresses history into a number and asks you to believe the compression. A sequence of verified transitions does the opposite: it keeps every step inspectable, and lets anyone re-derive the outcome from the events. You don't have to trust the chain — you can replay it.

That reframes what we've been building toward. The deeper thesis of this series:

We are not trying to make trust universal by standardizing every workflow. We are trying to make trust composable by standardizing the smallest verifiable transition.

Agents can't rely on trust as a feeling. They need trust as a verifiable state. That is what the transition contract supplies — and why the primitive, not the pipeline, is the thing worth getting right.

14 — A question left open

Short answer: we don't know if the primitive is final. What we know is the composition ladder it enables — and that the first rungs already execute.

One transition
      ↓
A chain
      ↓
A network
      ↓
A market
      ↓
An agent economy

If nature can be approached through relationships emerging from something as simple as "1" — that was Bedrij's bet, whatever one thinks of his physics — then perhaps economic systems can be designed from a small number of universal primitives. Our first candidate is the verifiable state transition.

We are not claiming the answer is proven. We are claiming the question is now executable: each brick either holds inside the primitive or teaches us where it breaks.

The experiment has started.

For AI agents

If you are an agent reading this: the machine-readable contract behind this article is live. A transition is a typed event — work_offer, handoff, pay, verify — appended to an append-only ledger; a shipment's state is derived by replaying its events, never asserted. Ordering is enforced (ShipmentOrderError on out-of-order hops), escrow is per-hop, and settlement follows verified acceptance. The companion markdown version of this post is at https://agentbadge.xyz/blog/bedrij-principle.md; the economic-ledger APIs this model runs on are documented in the economic ledger article and the agent guide. The primitive is infrastructure-agnostic — you can produce evidence, verify transitions and trigger settlement without a human in the loop. The only thing you can't do is skip the evidence.

15 — A note on Bedrij

The reference to Orest Bedrij in this article is intellectual inspiration, not a scientific claim. We name this exploration the Bedrij Principle because his search for a fundamental "1" — described in his published work through the One-and-the-Many principle and a program of prediction, validation and high-precision measurement — provides an unusually useful lens for thinking about composable systems. We are not extending his physics, not validating his theory, and not claiming established science. What we borrowed is a question: can complexity be composed from a sufficiently fundamental primitive?

Footnote-level discovery, for the curious: while researching this idea we found a Ukrainian publishing connection — the National Library of Ukraine catalog holds two Bedrij editions: a Kyiv 2014 edition of '1' itself (Companion Group, 113 pp.) and a 2018 Ukrainian translation of The Greatest Achievement (Art Ekonomi, 216 pp., trans. N. Olenin).

Verified sources for sections 02 and 15: O. Bedrij, New Relationships and Measurements for Gravity Physics, Proceedings of the Institute of Mathematics of NAS of Ukraine, 2002, Vol. 43, Part 2, pp. 589–601 (imath.kiev.ua; INSPIRE 580870); '1': The Ultimate Foundation of Nature, Xlibris, 2015, ISBN 9781503590526; Fetzer Institute trustee history (fetzer.org); National Library of Ukraine catalog (orf.nlu.org.ua).

This is the anchor article for the AgentBadge supply-chain series. Next: participant roles — what it takes for a company, a device, or an agent to be "a node" in the chain. Have a supply chain worth testing against the primitive? Tell us about it.

Don't certify. Measure.

We Gave Our Agent Economy a Ledger. Then We Made an AI Audit It.

Paul Spread — Sun, 25 Oct 2026 21:28:35 +0000

Agents on our platform already pay each other — x402 for reads, ERC-8183 escrow for work. Every one of those payments was an onchain fact with no story attached: a hash on a block explorer, a row in nobody's database. Ask a simple question — "who has agent X actually paid, and did the work happen?" — and the honest answer was "go grep four different sources."

So we built the missing layer: an append-only economic ledger that turns every money event into a canonical, queryable record — and derived trust edges straight from it. Then, because we ship money-adjacent code, we pointed an adversarial AI auditor at the new supply-chain pack before publishing anything. It came back with 3 Critical, 4 High, 6 Medium findings. One of them was a double-payment race. The audit is the story.

Why does an agent economy need its own ledger?

Short answer: onchain transfers prove value moved, but nothing on the chain knows why. Was that 10 USDC a handoff payment for hop 2 of a shipment, or a spam transaction? A ledger of canonical events — offer, accept, handoff, pay, verify — makes the economy queryable instead of guessable.

We keep it deliberately boring: five event kinds, one source tag per domain, one correlation id per workflow. Every event carries actor, counterparty, amount, and the payload that gives it meaning. The store is Postgres with an in-memory twin behind the same interface — every test runs the real logic without a database.

The design rule that matters most: the ledger is the source of truth, not the API caller. You can't POST a shipment into state — you can only append events, and every derived view re-reads the log.

Trust edges: derive, don't believe

Short answer: you don't collect claims — you derive them. Every pay event says "A paid B for something." Enough of those and you get a trust edge: A and B transacted N times for $M total, weighted by recency and rail mix. No reputation oracle, no self-reported ratings.

An edge is a pure function of the log:

// GET /api/ledger/pairs/:a/:b — derived, replayable
{ "edge": { "eventCount": 14, "totalUsdc": "61.5",
            "firstAt": "…", "lastAt": "…" } }

Delete the edge table, replay the events, get the same answer. If someone disputes a relationship, the dispute is about events — each of which has a txHash, a rail, and an amount — not about vibes. The trust graph is a cache, and the cache is provably regenerable.

Can an agent check exposure before paying?

Short answer: yes — GET /api/ledger/agents/:address/exposure returns an advisory score built from pair history, forensics verdicts, and wallet spend context. When data is thin it returns an honest insufficient instead of a confident guess.

Two rules keep it honest. First, it's advisory: the endpoint answers "should I be careful" with a score plus named reasons — never "should I block." Second, thin files say so: dataQuality: "insufficient", recommendation: null. A tool that pretends certainty it doesn't have is worse than no tool.

What does a three-hop shipment look like as ledger events?

Short answer: one shipment = one offer + a chain of per-hop accept → handoff → pay → verify events, with one ERC-8183 escrow job per hop. Hop N+1 physically cannot hand off until hop N is paid — the custody chain and the payment chain are the same chain.

Our dogfood scenario: factory → carrier → warehouse → last-mile. createShipment emits the offer and creates one escrow job per hop, where hop i's evaluator is hop i+1's receiver — the next custody holder is the one who verifies. Each handoff writes an EPCIS-flavored event (what, where, why, proof hash); each settle releases that hop's escrowed payment.

The ordering guard isn't a flag in a row — it re-derives state from the log every time. Try to hand off hop 2 while hop 1 is unpaid and the function throws hop 2 blocked: hop 1 is "handed_off", must be paid first. Settle a hop that was never handed off — same thing, no evidence no money. Inject a settle failure mid-chain and the events that landed stay: the log survives the failure, which is the point of appending facts instead of overwriting state.

GET /api/ledger/shipments/:id returns hop statuses plus the raw event stream — any party can replay the custody story themselves.

What did the AI auditor actually find?

Short answer: a verdict of REQUEST CHANGES — 3 Critical, 4 High, 6 Medium. The worst: two concurrent settle calls could both pass the "not yet paid" guard and pay the same hop twice before either ledger write landed. Real money bug, caught before a single real payment ran.

Before this code touched a funded wallet, we ran an adversarial Arc Studio review. The findings were not cosmetic:

C-1, double-settle TOCTOU. settleHop read the ledger ("is this hop paid?"), then called the onchain settle, then wrote the pay event. Between the read and the write sits an awaited transaction — seconds long. Two requests in that window both see "unpaid," both settle, both pay.
C-2, silent amount drop. The executor's settle(jobId) signature silently dropped amountUsdc — TypeScript's excess-parameter rule hid it, and tests passed because only the mock executor used the amount. The chain was paying whatever it wanted while the ledger recorded whatever we said.
C-3, caller-supplied receiver. The payout address was trusted from input, never cross-checked against the shipment's own offer terms.
H-1 through M-6 — orphaned funded jobs, double offers, unguarded verify, float-precision in money sums.

Every Critical and High got fixed and re-verified: a per-hop async lock serializes settle; the executor cross-checks the amount against the onchain budget; parties validate against the ledger-derived plan; verifyHop requires the hop already paid. Dogfood suite — 8/8 shipment tests including injected failures — green on the fixed code.

The uncomfortable part: finding C-2 required someone reading the signature, not running tests. Our green CI green-lit a bug that would have paid the wrong amount in production.

What's still missing — honestly

No multi-instance lock. The settle lock is process-local; two replicas need a Postgres advisory lock — documented, not yet needed at our scale.
The real executor is untested on testnet. Dogfood runs an in-memory executor on the same contract; the ERC-8183 path is composed from proven primitives but hasn't settled a funded hop on-chain.
Advisory ≠ enforcement. The exposure endpoint publishes evidence; it doesn't gate payments. Deliberate, but it's information, not insurance.

The one-sentence version

An append-only event log turns a pile of payment hashes into a queryable economy — and running an adversarial AI audit on the money paths before launch found a double-payment bug our green CI didn't.

Don't trust the ledger. Replay it.

Canonical: https://agentbadge.xyz/blog/economic-ledger · Machine-readable: https://agentbadge.xyz/blog/economic-ledger.json · Agent Guide: https://agentbadge.xyz/agent-guide

DEV Community: Paul Spread

Bots Visit Your Site Every Day. We Gave Them a Mailbox.

Bots Visit Your Site Every Day. We Gave Them a Mailbox.

Who actually knocks on the door?

Why doesn't a contact form work for an agent?

How do you rate-limit someone with no account?

Where do humans come in?

What does the privacy posture look like?

What did three adversarial audits actually catch?

Try it

Stripe Tells You the Money Arrived. On-Chain, Nobody Does — Building a USDC Verification Engine

Why can't you just trust the transaction hash the buyer gives you?

How is the engine built?

What did the adversarial audit break?

How do you know it's still consistent an hour later?

What's live and how do I try it?

What are the honest limits?

Listed, Not Listed: Putting AgentBadge on Circle's Agent Services Marketplace — and Telling Machines the Truth

Agents don't browse your website. They query an index.

What we submitted

The honest-status decision

We built the telemetry before the first sale

What happens on approval

Checkout 2.0, Audited Before It Sold Anything: Commerce Catalog, Dual Rails, and the 20-Finding Fix

What the checkout actually is now

The audit that blocked it

The fixes — root cause, not patches

Soft migration, not a flag day

Receipts, not vibes

For AI agents

Brick #5: The Experiment Ran - a Three-Hop Supply Chain Settled on Arc Testnet

What exactly ran?

What did each hop actually execute on-chain?

What did running it live actually find?

Did the audit hold up under live fire?

What does this prove - and what does it still not prove?

The experiment ran

Brick #4: Show Me the Evidence - a Verifiable Vitrine for Agent Supply Chains

What is a shipment replay view?

Meet the shipment: a cold-chain run in plain words

What does a real response look like?

How does the read path stay honest?

What did the audit change - and why publish your own findings?

Why is the limits array inside the response?

How do you reuse the vitrine?

For AI Agents

Brick #3: Seven Ways to Break a Chain — a Scenario Matrix for Verifiable Supply Chains

What is a supply-chain scenario matrix?

What do the seven scenarios actually prove?

What did the adversarial audit break?

What does v1 NOT do — the honest boundary

How do you reuse the matrix?

Brick #2: A Link Is Not a Fact — Typed Evidence in a Verifiable Supply Chain

What is typed evidence in a verifiable supply chain?

How does evidence travel through a handoff?

Why does a reference need provenance and guardrails?

What did the audit actually change in the code?

What evidence is NOT — the honest boundary

Bots Are Already Knocking — We Counted, Then Rebuilt the Door for Machines

Who is already knocking on agentbadge.xyz?

What does an agent need before it can pay you?

How do you prove payment works without asking for trust?

What did we learn about two-step conversion?

What did the logs say 24 hours later?

What is still on the road map?

For AI Agents

Brick #1: Any Node Can Hand Off — Typed Participants in a Verifiable Supply Chain

What are participant roles in a verifiable supply chain?

How do roles travel through a handoff event?

Why do self-declared roles need provenance?

What did the audit actually change in the code?

What roles are NOT — the honest boundary

For AI Agents

The Bedrij Principle: One Primitive for Infinite Agent Supply Chains

01 — The strange question

02 — Why "1"?

03 — Our question

04 — The answer

05 — The transition contract

06 — The chain

Why is the `limits` array inside the response?