Scoped Treasury — A policy-controlled stablecoin treasury that lets a business grant narrowly scoped payment authority to other entities (employees, bots, servers, contractors, internal teams, payment agents) without exposing the treasury's master private key.
Demo prototype. Not a production custody system.
This repository ships Foundry contracts (MockUSDC, PolicyManager,
ScopedTreasury), a chain-neutral script/Deploy.s.sol, and a Vite + React
dashboard that signs with local Anvil keys (no wallet modal). Start at
AGENTS.md and docs/README.md.
The entity never receives the treasury owner's private key. It receives a constrained authorization capability enforced by the policy layer.
A business holds digital assets (stablecoins) in a treasury wallet. Automated or human operators need to pay vendors from that treasury. Handing them the master key is too dangerous; approving every transfer manually does not scale.
The missing layer is scoped permissions: an entity can trigger transfers from the treasury only within a policy (asset, per-transaction cap, daily cap, merchant allowlist, time window). Compromise of the delegate key inherits that policy, not the treasury.
Ownership, custody, authorization, and execution stay separate. The dashboard is part of that loop: the owner grants, an entity signs, the treasury executes only after PolicyManager consumes the limits.
flowchart TD
Owner[Owner]
Entity[Entity — employee / bot / server / team / …]
UI[Vite dashboard]
Treasury[ScopedTreasury]
Policy[PolicyManager]
ERC20[MockUSDC]
Merchant[Merchant]
Owner --> UI
Entity --> UI
UI -->|create / revoke policy| Policy
UI -->|sign PaymentAuthorization| Entity
UI -->|executePayment| Treasury
Treasury -->|validateAndConsume| Policy
Policy --> Treasury
Treasury --> ERC20
ERC20 --> Merchant
- Owner configures policies and can withdraw. Single root of authority.
- ScopedTreasury holds ERC-20 balances and executes transfers.
- PolicyManager stores policies, verifies signatures, consumes limits.
- Entity signs off-chain; anyone may submit
executePayment. The signer can be a person, a bot, a server, or any other key — not a special “agent” type.
Detail, including how the UI, contracts, and each payment fit together:
docs/architecture.md.
Each policy binds a delegate (the entity address) and a token to:
perTransactionLimit/dailyLimit- UTC day bucket (
spendingDay) andspentToday validAfter/validUntilactive(revocation flips this)- recipient allowlist:
recipientAllowed[policyId][address]
Demo Payments entity: MockUSDC, $250/tx, $2,000/day, Merchants A/B/C, 24h.
- Owner calls
PolicyManager.createPolicyandsetRecipient. - The entity signs a
PaymentAuthorization(EIP-712) with its own key. - Relayer or entity calls
ScopedTreasury.executePayment. - Treasury asks PolicyManager to validate and consume (signature, activity, window, nonce, token, recipient, per-tx, daily limit).
- Only then:
ERC20.transferfrom the treasury to the merchant. PaymentExecutedis emitted. Failures revert with a custom error — no on-chain “denied” event.
Assume the entity key can leak. The attacker is still bound by token,
caps, allowlist, expiry, revocation, and nonce uniqueness. They cannot
call owner withdraw. See threat model in architecture.md.
Four UI scenarios (must stay trivial after any change):
- Merchant A, $75 → success
- Merchant A, $500 →
TransactionLimitExceeded - Unknown address, $50 →
RecipientNotAllowed - Revoke, then Merchant A $50 →
PolicyInactive
Walkthrough: docs/usage.md.
This dashboard is intentionally not hosted on a public URL. The UI signs with local Anvil keys (including the owner key) so a reviewer can click without MetaMask. That is safe on local runs only.
Watch the recorded demo
One command installs missing tools (Foundry, Node.js) if needed, starts Anvil,
deploys and seeds the contracts, and opens the dashboard at
http://localhost:5173:
./scripts/demo.shSkip auto-install if you already have the toolchain (or do not want this script to install anything):
./scripts/demo.sh --no-installCtrl+C stops the app and, if this script started it, the local chain.
While Anvil is running, every transaction is written to .anvil.log in
the repo root. Tail it to inspect hashes and RPC calls:
tail -f .anvil.logA demo.sh run that starts Anvil truncates this file first, so you only
see the current session. Reusing an already-running chain leaves the existing
log in place.
./scripts/teardown.shStops Anvil on port 8545 and deletes .anvil.log.
To also uninstall tools that demo.sh recorded as having been installed by
this repo (Foundry and/or Node.js via Homebrew):
./scripts/teardown.sh --uninstallWarning for reviewers: --uninstall removes those binaries from your
machine. It does not remove Foundry or Node you already had before
running the demo — only what .demo-installed lists. Default teardown
leaves tools in place.
Manual steps: docs/usage.md.
forge build
forge test
cd frontend && npm run buildThe suite must include an explicit delegate cannot withdraw test.
This is a prototype. A real wallet stack would add smart accounts, ERC-4337 (Account abstraction), session keys, MPC/HSM, passkeys (easy auth), multisig/DAO controlled treasury, relayers/paymasters, real stablecoins, ramps, KYC/AML, and monitoring. None of that is in this repo.