Mandatedocs
Concepts

Architecture

Every component on one page, and where each guarantee lives.

The user delegates bounded authority to an AI agent through a smart account they own. The agent plans and executes; the contract enforces; a Ledger co-signs anything irreversible.

The system

You Agent runtime: console, MCP server, SDK Base Sepolia Arc testnet, USDC is gas execute, inside caps executeWithGuardian clear-signed approval text setMandate, setPolicy, setGuardian attestation, about 8 s receiveMessage guardian guardian Chat or MCP Owner wallet: sets caps, policy, roles Ledger: guardian key Claude: turns the request into a typed intent Deterministic planner: recipes and action adapters build the calls Simulation: policy, caps and protocol logic against live state Executor: agent wallet sends one step at a time The Graph: one standardized query across six lending subgraphs MandateAccount Compound v3: borrow real USDC against WETH CCTP v2 TokenMessenger: burn MandateAccount, same address CCTP v2 MessageTransmitter: mint Recipient

Components

ComponentWhereJob
ModelClaude via the Vercel AI SDK or any MCP clientReads tool results, produces one structured intent, explains. Never writes calldata, never holds a key.
Planner@yashjain99/mandate-sdk recipes and action adaptersTurns the intent into typed steps with concrete calls, a binding maxUsdcOut, and a guardian flag derived from the on-chain policy.
SimulationSDKDry-runs the next step against live state; later steps are checked statically and re-simulated right before they run.
ExecutorSDK, driven by execute_stepAsks the chain whether a step already ran, then sends it through the account. Idempotent by construction.
MandateAccountSolidity, Base Sepolia and Arc, same addressAllow-list of target and selector, per-transaction and rolling daily caps on measured USDC outflow, guardian verification, replay guard.
GuardianA Ledger, over WebHID in the browser or USB in NodeClear-signs a nine-line text approval for irreversible steps.
OwnerA browser walletSets and revokes the mandate, edits policy, rotates roles, withdraws.
Market dataThe Graph, Messari standardized lending subgraphs, plus MorphoLive USDC borrow rates; the venue with an implemented executor is recommended.
Storememory, JSON files, or Upstash RedisPlans, approvals and the audit trail.

Where each guarantee lives

GuaranteeEnforced byNot by
Only allow-listed callsMandateAccount.policies on every call, wildcard address(0) per selector, explicit deny beats wildcardthe planner, which merely refuses to build what the policy forbids
Spend caps_runMeasured: balance before and after each call, decreases summed, checked against perTxCap and the 24-hour dailyCapany number the agent declares
Human on irreversible stepsexecuteWithGuardian: rebuilds the approval text from typed arguments, recovers the signer, checks deadline, consumes the nonce, enforces maxUsdcOut on measured outflowthe UI
No double executionexecuted[planId][step] in the contract; the executor also probes the chain before every sendretries being careful
Same account on both chainsMandateFactory through the canonical CREATE2 deployer, configured after deployment so the init code is chain-independenta lookup table
The guardian cannot escalatea signature never lifts the allow-list; only the owner changes policytrust in the device

Data flow for one request

  1. Intent. "I need 10 USDC on Arc by Friday to pay 0x…. Don't sell my ETH." becomes { amountUsdc: 10, recipient, constraints: { doNotSell: ["ETH"] }, repayInDays: 7 }.
  2. Rates. One GraphQL document runs against Aave v3 (three networks), Compound v3 (two) and Spark; the on-chain Compound rate on Base Sepolia joins as the executable twin.
  3. Plan. Five steps: supply and borrow (agent), CCTP burn (guardian), mint on Arc (agent, direct), payment (guardian), schedule repayment (agent).
  4. Simulate. Step one dynamically, the rest statically; the console shows verified versus deferred.
  5. Execute. The borrow lands on its own. At the burn, the model pauses; the Ledger shows the text; the contract verifies it. The mint follows the attestation. The payment needs the second tap. The repayment intent is recorded on Arc.
  6. Audit. Every plan, simulation, approval request, signature and transaction is written to the store with reasoning and explorer links.

Surfaces

  • Console (apps/web): Next.js chat with toolApproval, owner page, activity page, Ledger approval sheet.
  • MCP server (@yashjain99/mandate-mcp): the same tools for Claude Desktop, Cursor or Claude Code, with the guardian pause made explicit.
  • SDK (@yashjain99/mandate-sdk): everything above without a model, for your own agent or script.

Read next: Bounded delegation, Mandates and caps, Guardian approvals.

Live demo and addresses

What is deployed, where to look, and what a full run looks like.

Bounded delegation

Three roles, one contract, and a model that never touches a key.

On this page

The systemComponentsWhere each guarantee livesData flow for one requestSurfaces