How Leash decides
Every number on this page is read from the engine that makes the decisions, so it cannot drift from the code.
On this page
Overview
AI agents pay merchants over x402: a server answers 402 Payment Required, the agent signs a payment and retries. Nothing in x402 says whether the merchant will deliver, or is who it claims to be. Leash sits in the agent's payment hook and answers that before anything is signed.
It reads a shared registry that every Leash agent writes to. One agent's loss becomes a signed, proof-backed report that protects every other agent. No verdict is permanent: blocks end, evidence expires, and a merchant earns trust back through probation.
- SDK (
@leash/guard): wraps a real x402 client. Set it up. - MCP server (
@leash/mcp): the LLM pays only through it, and cannot approve. Connect it. - Owner console: approvals signed with the owner's wallet, on the operator's machine.
Verdicts and reasons
Each payment gets one verdict, and every reason that fired. Any DENY reason makes the verdict DENY; otherwise any ESCALATE reason makes it ESCALATE; otherwise ALLOW.
| Reason | Verdict | When |
|---|---|---|
ceiling-exceeded | DENY | The amount is above the per-call ceiling ($1.00), or is not a number. |
declared-mismatch | DENY | The payTo, network, asset or origin contradicts a fresh ENS declaration: a spoof. |
over-declared-max | DENY | The price is above the merchant's own leash.maxPrice. |
replay | DENY | This exact challenge was paid in the last 120 seconds. |
stale-challenge | DENY | The 402 is older than its own maxTimeoutSeconds. |
blocked | DENY | The payee is BLOCKED, whether or not it claims an ENS name. |
merchant-cap-hard | DENY | 24-hour spend with this merchant would pass 5 times its soft cap. |
budget-exceeded | DENY | The session ($2.00) or daily ($10.00) budget would be passed. |
escalation-rate-limit | DENY | More than 10 new escalations in an hour: a defence against approval bombing. |
risk-band | DENY or ESCALATE | A risk score of 35 or more escalates; 70 or more denies, but only with two or more bad clusters. |
unsupported-asset | DENY | The 402 asks for a token other than the pinned USDC. |
unknown-merchant | ESCALATE | No valid ENS declaration. Unknown merchants always ask, even for dust. |
unknown-origin | ESCALATE | The call went around guardedFetch, so its real origin is unknown. |
limit-exceeded | ESCALATE | The amount is above the standing's auto-approve limit. |
merchant-cap | ESCALATE | 24-hour spend with this merchant would pass its soft cap. |
new-identity-budget | ESCALATE | NEW merchants together would take more than $0.10 today: identity rotation is bounded. |
price-drift | ESCALATE | More than twice the median of the last five prices paid for this resource: bait and switch. |
probation-limit | ESCALATE | Above the probation limit. |
probation-hold | ESCALATE | A bad report during probation started a hold. |
registry-unavailable | ESCALATE | No usable standing: Arkiv is unreachable and there is no cache that may be used. |
declared-stale-mismatch | ESCALATE | A stale ENS cache disagrees with the 402. Stale data never denies. |
unverified-reports | ESCALATE | Some evidence could not be checked because Mirror Node, Arkiv or Sepolia failed. |
safe-mode | ESCALATE | Two of ENS, Arkiv and Mirror Node are down. A cached block still denies. |
settlement-unknown | ESCALATE | An earlier attempt at this challenge may still settle, and Mirror Node cannot say yet. |
locally-blocked | DENY | The owner rejected this payee and blocked it on this machine. |
malformed-challenge | DENY | The payTo is not a plain account id, or the amount is not a whole number. The text is never shown. |
How a decision is made
- Parse the 402. Anything that is not a plain account id or whole-number amount is refused and replaced, so merchant text never reaches a log, card or tool result.
- Read the ENS declaration the 402 claims, in
extra.leashEns, and the merchant's standing from Arkiv, in parallel. - Re-verify the evidence. Every report row is checked on Mirror Node before it counts. Probes count only if an allow-listed prober created them; rebuttals only if the ENS role holder signed one with a listed reason.
- Replay the evidence into a standing with the same pure engine every reader uses, then score the payment.
- Apply the hard rules, the limits for that standing, the budgets, and the outage rules.
- Record the decision: one stored row, one structured log line and one HCS audit message, with its latency.
Measured on the real networks: p95 of 2 ms with warm caches and 2.3 s cold, against targets of 800 ms and 3 s.
The risk score
R runs from 0 to 100. It rises with bad evidence, money lost and amount at risk, and falls with trust and value delivered.
R = 100 × (0.30·bad + 0.20·loss + 0.15·trust + 0.20·exposure + 0.15·identity) bad = 1 − e^(−b) b: decayed bad evidence, one per cluster loss = L / (L + D + 0.05) L: money lost, D: value delivered trust = e^(−g / 2) g: decayed good evidence exposure = min(1, A / (D + 0.02)) A: this payment identity = base(standing) + 0.1·min(strikes, 3)
Identity base: ESTABLISHED 0, NEW 0.5, BLOCKED 0.5, PROBATION 0.7, UNKNOWN 1. Under 35 is clear; 35 or more escalates; 70 or more denies with two bad clusters. One cluster alone can never cause a DENY, whatever the score.
Examples from the spec: a NEW merchant and a $0.005 payment score 27.5 (ALLOW). After one bad cluster, 42.0 (ESCALATE). After two, the merchant is BLOCKED.
Standing
| From | To | When |
|---|---|---|
| UNKNOWN | NEW | The merchant declares itself in ENS. |
| NEW | ESTABLISHED | Good reports from 3 clusters, $0.10 delivered, little bad evidence, 1 day since the first good report, and no strikes. |
| NEW ESTABLISHED | BLOCKED | Bad reports from 2 independent clusters (3 if a contested ESTABLISHED merchant) and enough weight. Wallets under 24 hours old count half. |
| BLOCKED | PROBATION | The block runs its length: 5 days, then 10 days, then 20 days, by strike. Or earlier: one rebuttal, a passing probe, and 1 day of cooldown. |
| PROBATION | BLOCKED | One bad cluster starts a hold of 3 days, when every payment escalates; a second blocks again, one strike higher. |
| PROBATION | ESTABLISHED | Good reports from 3 clusters, $0.15 delivered, no bad reports, and at least 3 days per strike, up to 3 strikes. |
| PROBATION | NEW | 21 days pass quietly. Waiting alone never reaches ESTABLISHED. |
Limits and caps
| Standing | Pays alone up to | 24-hour soft cap | Hard cap |
|---|---|---|---|
| NEW | $0.01 | $0.05 | $0.25 |
| ESTABLISHED | Half its delivered value, up to its declared max and $1.00 | $1.00 | $5.00 |
| PROBATION | $0.05 divided by strikes, at least $0.01 | $0.10 | $0.50 |
| UNKNOWN | Never: always asks | – | – |
| BLOCKED | Never: denied | – | – |
Across all merchants: $1.00 per call, $2.00 per session, $10.00 per day, and $0.10 a day across NEW merchants. With a stale cache the soft caps halve. Above the soft cap the owner is asked; above the hard cap, never.
Proof of payment
Anyone can write a row to Arkiv, so every row is hostile until checked. A report counts only if all of these hold:
- Mirror Node shows a SUCCESS transfer of the pinned USDC, from the named payer to this payee, of at least the stated amount.
- The consensus time on Mirror Node matches the row, which uses Mirror's time, never its own.
- The payer's Hedera key signed the report: payee, transaction id, outcome, amount and the writer's address.
- One report per payment, one bad report per payer per payee per day, and at most 5 bad reports a day per reporter across payees.
Wallets are grouped by the account that funded them, so many wallets from one funder are one cluster. The reader takes the latest 200 reports that verify, reading past rows that do not; past 1,000 rows the read counts as incomplete, and the guard asks rather than allows.
Expiry and forgiveness
Reports expire on Arkiv after 60 days, and strikes are forgotten after 60 days with no block. Expiry is not a cleanup job: it is how a merchant is forgiven, enforced by the storage itself. Blocks double with each strike, so a merchant that scams, waits and scams again is blocked for longer each time, and is never blocked forever.
Probation, rebuttal and probes
A blocked merchant gets no payments, so it could never prove itself. The answer is a probe: a real paid call by the prober, at most $0.01 each and $0.50 a day.
- A rebuttal is signed by the wallet holding
ROLE_SET_TEXTfor theleash.rebuttalkey on the merchant's ENSv2 resolver, with one of five fixed reasons. Only the first per block counts. - It never unblocks by itself. It buys one probe. A passing probe ends the block early, after the cooldown, in PROBATION; a failing one keeps it blocked.
- In probation the prober retests once a day. Probes all count as one cluster, so a probe alone can never supply the three clusters recovery needs.
Outages and safe mode
| Down | Fallback | Effect |
|---|---|---|
| ENS | Cached declaration: fresh 1 minute, usable stale for 10 minutes | Stale: caps halve and a mismatch escalates. No cache: UNKNOWN, so ESCALATE. |
| Arkiv | Cached standing | A cached block still denies until it ends; ESTABLISHED is usable for 15 minutes with halved caps; otherwise ESCALATE registry-unavailable. |
| Mirror Node | Verdicts cached by transaction | Evidence it cannot check escalates, never denies. Reports wait in the outbox until settlement is confirmed. |
| Facilitator | Merchant-side | After a failed settle, Mirror Node is asked before any new attempt; unknown is ESCALATE. |
| HCS | Outbox | None: the audit trail is delayed, never blocking. |
| Two of ENS, Arkiv, Mirror | Safe mode | Every payment escalates; a cached block still denies. It ends after three healthy reads in a row. |
Replay and approvals
A challenge is hashed from its scheme, network, asset, amount, payee, resource and extras. Paying the same hash again within 120 seconds is a replay, unless the caller marks it as a deliberate repeat. The replay table, spend ledger, approvals and outbox live in SQLite, so they survive a restart.
An escalation creates a card with structured fields only. The owner approves with a wallet signature over the approval id, the challenge hash and an expiry 120 seconds out. The guard checks that signature against the owner's address when it is used, once, so a row written straight into the database cannot approve anything.
Failure modes, tested live
Each failure mode in the spec was caused for real on Hedera testnet, Arkiv and Sepolia, with real merchants and real local servers for faults a public merchant cannot show. 55 checks pass. The runner is apps/demo/src/failures.ts.
| Failure | What happened on the testnets | |
|---|---|---|
| F1 | Spoof or prompt injection | A spoof claiming weather's name was denied; a 402 whose payTo was instructions was denied before signing; through MCP, a paid body came back marked untrusted and no other result carried merchant text. |
| F2 | Merchant takes payment, returns junk | 0.03 to a NEW merchant escalated; two clusters blocked lemon; the next agent was denied without paying. |
| F3 | Price above the declared maximum, bait and switch | 0.30 against a 0.25 maximum was denied; a doubled price escalated price-drift. |
| F4 | Slow ramp | Ten 0.005 payments filled the cap; the next escalated; a real 0.20 request was denied by the hard cap. |
| F5 | Unknown merchant | Rogue, with no ENS name, escalated every time and was never paid. |
| F6 | Replay and stale challenges | A 402 held 61 s by the network was denied; replay was still denied after a real process restart. |
| F7 | ENS or Arkiv outage | Through relays that were really cut: a cached block still denied, a guard with no cache escalated, safe mode came and went by itself, and a held report was filed after recovery. |
| F8 | Griefing with bad reports | Three wallets from one funding cluster could not block; forged and flipped rows were ignored. |
| F9 | Settlement failure | With a facilitator failing at settle, nothing was paid twice and retries waited for Mirror Node; a dropped connection after paying was reported once it settled. |
| F10 | Approval abuse | The eleventh escalation in an hour was denied; approvals were single use, bound to one challenge and expired after 120 s; the MCP server has no approve tool. |
| F11 | Scam, wait, scam again | Block, probation, a hold on the next bad report, then strike 2 with the block doubled. |
| F12 | Identity rotation | A merchant at a blocked payTo with no ENS name was still denied; NEW merchants share one daily budget. |
| F13 | Rebuttal abuse | No-role and off-list rebuttals were refused, a second rebuttal bought no second probe, and a forged passing probe was ignored. |
| F14 | Bypass | The raw client was stopped as unknown-origin; an approval forged in the database did not pay. |
| F15 | Spam and time manipulation | Future-dated and wrong-time rows were ignored, and a 210-row flood could not hide the real reports. |
Policy clocks
Production uses the spec's durations: blocks of 5 days, 10 days, 20 days, a hold of 3 days and 60 days of evidence. The demo uses the same engine on a shorter clock, shown in a banner whenever it is on. LEASH_LIVE_BLOCK_SEC and LEASH_LIVE_DAY_SEC set it; by default one policy day is 18 seconds and blocks last 1, 2 and 5 minutes.
Registry schema
| Entity | Written by | Attributes |
|---|---|---|
| leash.report | The paying agent, after Mirror confirms settlement | ns, payee, domain, ens, outcome, txId, payer, payerSig, consensusTs, amountMicroUsd, reason, v |
| leash.probe | An allow-listed prober | ns, payee, result, txId, consensusTs, amountMicroUsd, deliveryDigest, v |
| leash.rebuttal | The rebuttal desk, signed by the ENS role holder | ns, payee, ens, reason, evidenceHash, episodeStart, filedAt, signer, signature, v |
No bodies, paths or queries are stored: a probe keeps only a hash of what it received, and a rebuttal only a hash of its evidence. Full details in arkiv/schema.md.
ENS records
A merchant declares itself with text records on its ENSv2 name, and names it in the 402 as extra.leashEns. See the merchant setup.