8000 GitHub - bolajahmad/scoped-treasury-demo: A policy-controlled stablecoin treasury that lets a business grant narrowly scoped payment authority to other entities without exposing the treasury's master private key. · GitHub
[go: up one dir, main page]

Skip to content

About

A policy-controlled stablecoin treasury that lets a business grant narrowly scoped payment authority to other entities without exposing the treasury's master private key.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Scoped Treasury

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.

Problem

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.

Why it matters

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.

Architecture

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
Loading
  • 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.

Policy model

Each policy binds a delegate (the entity address) and a token to:

  • perTransactionLimit / dailyLimit
  • UTC day bucket (spendingDay) and spentToday
  • validAfter / validUntil
  • active (revocation flips this)
  • recipient allowlist: recipientAllowed[policyId][address]

Demo Payments entity: MockUSDC, $250/tx, $2,000/day, Merchants A/B/C, 24h.

Transaction lifecycle

  1. Owner calls PolicyManager.createPolicy and setRecipient.
  2. The entity signs a PaymentAuthorization (EIP-712) with its own key.
  3. Relayer or entity calls ScopedTreasury.executePayment.
  4. Treasury asks PolicyManager to validate and consume (signature, activity, window, nonce, token, recipient, per-tx, daily limit).
  5. Only then: ERC20.transfer from the treasury to the merchant.
  6. PaymentExecuted is emitted. Failures revert with a custom error — no on-chain “denied” event.

Security model

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.

Demo

Four UI scenarios (must stay trivial after any change):

  1. Merchant A, $75 → success
  2. Merchant A, $500 → TransactionLimitExceeded
  3. Unknown address, $50 → RecipientNotAllowed
  4. 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

Running locally

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.sh

Skip auto-install if you already have the toolchain (or do not want this script to install anything):

./scripts/demo.sh --no-install

Ctrl+C stops the app and, if this script started it, the local chain.

Anvil logs

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.log

A 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.

Teardown

./scripts/teardown.sh

Stops 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 --uninstall

Warning 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.

Tests

forge build
forge test
cd frontend && npm run build

The suite must include an explicit delegate cannot withdraw test.

Production considerations

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.

About

A policy-controlled stablecoin treasury that lets a business grant narrowly scoped payment authority to other entities without exposing the treasury's master private key.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0