Docs

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
  1. Overview
  2. Verdicts and reasons
  3. How a decision is made
  4. The risk score
  5. Standing
  6. Limits and caps
  7. Proof of payment
  8. Expiry and forgiveness
  9. Probation, rebuttal and probes
  10. Outages and safe mode
  11. Replay and approvals
  12. Failure modes, tested live
  13. Policy clocks
  14. Registry schema
  15. ENS records

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.

ALLOWESCALATEDENY
Every reason code
ReasonVerdictWhen
ceiling-exceededDENYThe amount is above the per-call ceiling ($1.00), or is not a number.
declared-mismatchDENYThe payTo, network, asset or origin contradicts a fresh ENS declaration: a spoof.
over-declared-maxDENYThe price is above the merchant's own leash.maxPrice.
replayDENYThis exact challenge was paid in the last 120 seconds.
stale-challengeDENYThe 402 is older than its own maxTimeoutSeconds.
blockedDENYThe payee is BLOCKED, whether or not it claims an ENS name.
merchant-cap-hardDENY24-hour spend with this merchant would pass 5 times its soft cap.
budget-exceededDENYThe session ($2.00) or daily ($10.00) budget would be passed.
escalation-rate-limitDENYMore than 10 new escalations in an hour: a defence against approval bombing.
risk-bandDENY or ESCALATEA risk score of 35 or more escalates; 70 or more denies, but only with two or more bad clusters.
unsupported-assetDENYThe 402 asks for a token other than the pinned USDC.
unknown-merchantESCALATENo valid ENS declaration. Unknown merchants always ask, even for dust.
unknown-originESCALATEThe call went around guardedFetch, so its real origin is unknown.
limit-exceededESCALATEThe amount is above the standing's auto-approve limit.
merchant-capESCALATE24-hour spend with this merchant would pass its soft cap.
new-identity-budgetESCALATENEW merchants together would take more than $0.10 today: identity rotation is bounded.
price-driftESCALATEMore than twice the median of the last five prices paid for this resource: bait and switch.
probation-limitESCALATEAbove the probation limit.
probation-holdESCALATEA bad report during probation started a hold.
registry-unavailableESCALATENo usable standing: Arkiv is unreachable and there is no cache that may be used.
declared-stale-mismatchESCALATEA stale ENS cache disagrees with the 402. Stale data never denies.
unverified-reportsESCALATESome evidence could not be checked because Mirror Node, Arkiv or Sepolia failed.
safe-modeESCALATETwo of ENS, Arkiv and Mirror Node are down. A cached block still denies.
settlement-unknownESCALATEAn earlier attempt at this challenge may still settle, and Mirror Node cannot say yet.
locally-blockedDENYThe owner rejected this payee and blocked it on this machine.
malformed-challengeDENYThe 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

  1. 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.
  2. Read the ENS declaration the 402 claims, in extra.leashEns, and the merchant's standing from Arkiv, in parallel.
  3. 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.
  4. Replay the evidence into a standing with the same pure engine every reader uses, then score the payment.
  5. Apply the hard rules, the limits for that standing, the budgets, and the outage rules.
  6. 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

Standing transitions
FromToWhen
UNKNOWNNEWThe merchant declares itself in ENS.
NEWESTABLISHEDGood reports from 3 clusters, $0.10 delivered, little bad evidence, 1 day since the first good report, and no strikes.
NEW ESTABLISHEDBLOCKEDBad reports from 2 independent clusters (3 if a contested ESTABLISHED merchant) and enough weight. Wallets under 24 hours old count half.
BLOCKEDPROBATIONThe 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.
PROBATIONBLOCKEDOne bad cluster starts a hold of 3 days, when every payment escalates; a second blocks again, one strike higher.
PROBATIONESTABLISHEDGood reports from 3 clusters, $0.15 delivered, no bad reports, and at least 3 days per strike, up to 3 strikes.
PROBATIONNEW21 days pass quietly. Waiting alone never reaches ESTABLISHED.

Limits and caps

Per merchant, by standing
StandingPays alone up to24-hour soft capHard cap
NEW$0.01$0.05$0.25
ESTABLISHEDHalf 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
UNKNOWNNever: always asks––
BLOCKEDNever: 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:

  1. Mirror Node shows a SUCCESS transfer of the pinned USDC, from the named payer to this payee, of at least the stated amount.
  2. The consensus time on Mirror Node matches the row, which uses Mirror's time, never its own.
  3. The payer's Hedera key signed the report: payee, transaction id, outcome, amount and the writer's address.
  4. 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_TEXT for the leash.rebuttal key 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

What a failure does to decisions
DownFallbackEffect
ENSCached declaration: fresh 1 minute, usable stale for 10 minutesStale: caps halve and a mismatch escalates. No cache: UNKNOWN, so ESCALATE.
ArkivCached standingA cached block still denies until it ends; ESTABLISHED is usable for 15 minutes with halved caps; otherwise ESCALATE registry-unavailable.
Mirror NodeVerdicts cached by transactionEvidence it cannot check escalates, never denies. Reports wait in the outbox until settlement is confirmed.
FacilitatorMerchant-sideAfter a failed settle, Mirror Node is asked before any new attempt; unknown is ESCALATE.
HCSOutboxNone: the audit trail is delayed, never blocking.
Two of ENS, Arkiv, MirrorSafe modeEvery 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.

F1 to F15
FailureWhat happened on the testnets
F1Spoof or prompt injectionA 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.
F2Merchant takes payment, returns junk0.03 to a NEW merchant escalated; two clusters blocked lemon; the next agent was denied without paying.
F3Price above the declared maximum, bait and switch0.30 against a 0.25 maximum was denied; a doubled price escalated price-drift.
F4Slow rampTen 0.005 payments filled the cap; the next escalated; a real 0.20 request was denied by the hard cap.
F5Unknown merchantRogue, with no ENS name, escalated every time and was never paid.
F6Replay and stale challengesA 402 held 61 s by the network was denied; replay was still denied after a real process restart.
F7ENS or Arkiv outageThrough 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.
F8Griefing with bad reportsThree wallets from one funding cluster could not block; forged and flipped rows were ignored.
F9Settlement failureWith 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.
F10Approval abuseThe 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.
F11Scam, wait, scam againBlock, probation, a hold on the next bad report, then strike 2 with the block doubled.
F12Identity rotationA merchant at a blocked payTo with no ENS name was still denied; NEW merchants share one daily budget.
F13Rebuttal abuseNo-role and off-list rebuttals were refused, a second rebuttal bought no second probe, and a forged passing probe was ignored.
F14BypassThe raw client was stopped as unknown-origin; an approval forged in the database did not pay.
F15Spam and time manipulationFuture-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

Arkiv entities
EntityWritten byAttributes
leash.reportThe paying agent, after Mirror confirms settlementns, payee, domain, ens, outcome, txId, payer, payerSig, consensusTs, amountMicroUsd, reason, v
leash.probeAn allow-listed proberns, payee, result, txId, consensusTs, amountMicroUsd, deliveryDigest, v
leash.rebuttalThe rebuttal desk, signed by the ENS role holderns, 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.