Skip to content
MANDATE owl logoMANDATE

Quickstart

The fastest path from a clean checkout to a compliant order accepted on-chain and a non-compliant order rejected by the circuit.

Prerequisites

Node ≥ 20, noirup (nargo 1.0.0-beta.22), bbup (bb 5.0.0-nightly, auto-matched to nargo), and foundryup. Built and tested on macOS arm64.

Installation

Install the published MCP server package directly with your package manager of choice:

npm install @0xgks/mandate-mcp

Or run it without installing, via npx:

npx -y @0xgks/mandate-mcp@0.1.0

One-command demo

From a clone of the repository, one script starts Anvil, deploys contracts (including the real bb-generated UltraHonk verifier), starts the sequencer, runs two agents (momentum + market maker), and runs the misbehave scenario:

./demo/run.sh

# knobs
DURATION=120 EPOCH_MS=6000 ./demo/run.sh   # shorter demo, faster epochs

What you will see:

  1. Deploy (including the real UltraHonk verifier) on a local Anvil chain.
  2. Two agents prove compliance and commit orders every epoch; batches clear at a uniform price.
  3. The misbehave scenario: the momentum agent tries a ~10× over-notional order → the prover fails on “order notional exceeds mandate maximum” → the script shows committedIn(epoch, commitment) = false on-chain. An unprovable order never existed.
  4. Unattended run; watch demo/logs/*.log, or poll the protocol-explorer endpoints at http://127.0.0.1:8787/epochs and /portfolio/<agentId>.

MCP / MoonPay Agent local setup

This is the fastest path to a working @0xgks/mandate-mcp integration: one command stands up a persistent local Anvil chain, deploys the contracts, starts the sequencer, generates a fresh test-only demo agent (session key, policy, whitelist), registers it, and writes a ready-to-paste MCP config.

npm run local:start     # idempotent: safe to re-run, never rotates keys/policy
npm run local:status     # read-only health check
npm run local:stop       # gracefully stops anvil + sequencer, keeps all state
npm run local:reset -- --yes   # DESTROYS local chain state + generated secrets

local:start writes two git-ignored, chmod 600 files: .local/mandate-mcp.env (all MANDATE_* values) and .local/moonpay-agent-mandate.json(a complete, ready-to-paste MCP config with real values filled in). Copy that JSON into your MCP client's config (e.g. claude_desktop_config.json's mcpServers key) and fully restart the client — most clients only read this file at startup.

Test prompts

Once your MCP client is connected, try these prompts:

Use the mandate_get_epoch tool and tell me the current epoch, phase, and breaker status.
Use the mandate_get_portfolio tool and summarize the current portfolio state for the configured agent.
Use only mandate_submit_order to submit a buy order for 250 units at a price of 3500. Do not use any unrestricted wallet, swap, transfer, or MoonPay execution tool.
Use only mandate_submit_order to attempt a buy order for 10000 units at a price of 3500. Return the exact policy or proof rejection reason. Do not bypass the MANDATE policy engine.

Security reminder

Do not give the same agent unrestricted wallet, swap, transfer, or trading tools alongside mandate_submit_order— MANDATE's proof-gating only works if it's the only execution path available. This whole stack is local-only, unaudited research software: never use real funds, real private keys, or a public RPC endpoint with it.

Running the test suites

  • cd circuits/policy_check && nargo test — Noir circuit (13/13)
  • cd contracts && forge test — Contracts (24/24)
  • cd agents && npm run selftest — SDK / agents TS ↔ Noir parity
  • cd agents && npx tsx src/merkle.test.ts — Sparse Merkle tree tests
  • cd agents && npx tsx src/prover.test.ts — Real proof + bb verify + violation throws