Leash.

Leash

A spending leash for AI agents on QoreChain. A classical key can only stop things. Starting or loosening anything needs a post-quantum signature.

Built for QoreChain Developer Fest, "Build Before Q-Day", Post-Quantum AI Agents track. Testnet only (qorechain-diana).

Leash

Demo video (2:56, voiceover, music, captions): https://david-film-library.pages.dev/media/leash-demo.mp4

The problem

An AI agent that pays for things holds a key, and today that key is secp256k1. If it leaks, or is broken by a quantum computer, the agent can be drained. Giving the agent a spending limit does not help if the same classical key can raise the limit.

QoreChain's own rules help, but they have traps. From its docs: a missing or disabled spending rule means no limit, not zero. An ERC-20 transfer counts as zero value inside an EVM window, and allowed targets do not cap token amounts. Windows are capped at 17,280 blocks (about 6 hours). Leash closes these gaps, and tells you the ones it cannot close.

The idea in one rule

Who May do May not do
The agent (secp256k1 key) Spend inside a mandate: per-payment and daily caps, allowlisted recipients, until an expiry. Freeze itself. Change anything about its own mandate
The owner's classical key Freeze. It can only stop things. Grant, loosen, extend or unfreeze
The owner's ML-DSA-87 key Sign a mandate: a new agent, new limits, new recipients, unfreeze (Everything else is on the owner)

A mandate takes effect only when LeashGuard verifies an ML-DSA-87 signature on chain through QoreChain's pqcVerify precompile. The signed message binds the chain id, this guard, a nonce and the whole mandate, so a signature cannot be replayed on another chain or guard, used twice, or altered.

What is in the repo

Try it

Requires Foundry, Node 22 and pnpm.

pnpm install
forge install foundry-rs/forge-std --no-git
pnpm test                 # 46 contract tests + 30 TypeScript tests (compiler, flow language, monitor rules)
pnpm demo:local           # v1: payments, the full flow and the drill on a local node
pnpm demo:local:v2        # v2: every adapter, then the drill for swaps, wraps and vaults (16 checks)
pnpm demo:monitor         # the monitor catching a burst and an unexplained outflow, freezing with a stop-only key
pnpm mcp:e2e              # an MCP client drives swaps, wraps and vaults through the server (24 checks)
pnpm compile "agent 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 up to 3 QOR a day, at most 1 QOR per payment, only to 0x90F79bf6EB2c4f870365E785982E1f101E93b906 for 3 hours"

The compiler refuses what it cannot parse exactly and says so loudly when it applies a default:

LEASH REFUSED
  [error] Say who the agent may pay: 'only to 0x… and 0x…'. An empty allowlist means the agent can spend nothing.
  [error] Give at least one cap: '50 fUSD a day' or 'at most 20 fUSD per payment'.

Use it from an agent

Leash ships an MCP server and a skill. Payments: leash_status, leash_check, leash_pay, leash_freeze. Actions (LeashGuardV2): leash_routes, leash_swap, leash_wrap, leash_unwrap, leash_vault_deposit, leash_vault_redeem, leash_execute. Also leash_compile, leash_loosen_prepare, leash_monitor and leash_drill_local. The agent holds only its own key; there is no tool that loosens a mandate. Setup for Hermes Agent, Claude Code and Cursor is in mcp/README.md. Bridging is not guarded because no bridge route is live, and the doc says why.

What was proven, and where

Check Result
Contract tests (Foundry, stubbed precompiles) 46 of 46 pass: 21 for LeashGuard and 25 for LeashGuardV2 and its adapters, each with a fuzz test that the agent never moves more than the daily cap
Compiler, flow-language and monitor tests 30 of 30 pass
Mutation check, v2: break the guard on purpose The tests fail each time: no rate floor, output to anywhere, caps skipped, approval left open, native value unchecked, no route needed
v2 drill, local node 16 of 16 as expected, after a tour through all five adapter actions
Q-Day drill, local node 14 of 14 as expected
Mutation check: break the guard on purpose The drill fails each time: no per-payment cap (13/14), no post-quantum check (9/14), owner key allowed to spend (13/14)
Real testnet: applyMandate with a real ML-DSA-87 signature Accepted by the pqcVerify precompile
Real testnet: Q-Day drill 13 of 13 as expected
Real testnet, v2: a LeashGuardV2 mandate with swap, wrap, vault routes Accepted by pqcVerify with a real ML-DSA-87 signature (0xd588cfa9…fd58bc), guard 0x6781ab2c…35eb
Real testnet, v2: every adapter as a real transaction wrap, unwrap, vault deposit, vault redeem and swap all succeeded
Real testnet, v2: Q-Day drill for actions 15 of 15 as expected (reports/testnet-v2-drill.json)
Real testnet, v2: an MCP client swaps and wraps through the guard A 10 USD swap (0x20a6e7d2…e161) and a 0.5 QOR wrap succeeded; a 90 USD swap was refused by the chain (OverPerTxLimit); a router the owner did not allow has no route (transcript)
Real testnet: an MCP client pays through the guard A 0.1 QOR payment succeeded; 5 QOR and an off-allowlist address were refused by the chain (transcript)

On the testnet, guard 0xa0ebb5daf8229da498346f0c824276d126c2a34c was deployed in 0x1670f698…9669 and armed in 0x53d44e69…14ae; full hashes are in reports/testnet-drill.json. The drill ends by freezing the guard; pnpm testnet rearm later re-armed it with a second owner-signed ML-DSA-87 mandate (nonce 2) for the MCP demo.

The drill

For each attempt the expected result is stated first. A legitimate payment must succeed, so a guard that refuses everything cannot pass, and the freeze kill switch must work.

PASS  control   legitimate payment inside the mandate                        succeeded
PASS  agent key pay more than the per-payment cap                            blocked (OverPerTxLimit)
PASS  agent key pay an address that is not on the allowlist                  blocked (RecipientNotAllowed)
PASS  agent key pay in a token the mandate does not cover                    blocked (TokenNotSpendable)
PASS  agent key keep paying after the daily cap                              blocked (OverDailyLimit)
PASS  agent key loosen the mandate with a forged post-quantum signature      blocked (BadPqcSignature)
PASS  agent key loosen the mandate with a signature for a different mandate  blocked (BadPqcSignature)
PASS  agent key replay the owner's signature from a different guard          blocked (BadPqcSignature)
PASS  owner key spend directly                                               blocked (NotAgent)
PASS  owner key grant itself a bigger mandate (no post-quantum signature)    blocked (BadPqcSignature)
PASS  owner key freeze the guard (the kill switch)                           allowed
PASS  agent key keep paying after the freeze                                 blocked (IsFrozen)
PASS  owner key unfreeze with an old signature                               blocked (BadPqcSignature)

Honest limits

How the chain's own layers fit

Leash is defence in depth, not a replacement. The chain's EVM window (opened by a hybrid-signed native message) bounds the agent account's EVM transactions by time, count and target. LeashGuard then bounds what those transactions can do to the money. The plan Leash prints includes the window settings, scoped to the guard.

Credits

The pqcVerify and pqcKeyStatus usage, the idea of reading the signer's public key from the chain's key registry, and the stand-in precompile used in the Foundry tests follow the organisers' qday-vault sample (Apache-2.0). forge-std is used for tests. See AI_USAGE.md for how this was built.

Licence

Apache-2.0. See LICENSE.

View this page on GitHub · raw markdown