Cerberus: On-Chain Payment Firewall for AI Agents

Three gates. MCP risk control. On-chain policy enforcement.

Security middleware for AI agent payments — off-chain MCP soft controls + on-chain Policy hard floor.

Full project guide: docs/PROJECT_GUIDE.md
MetaMask + network setup (step-by-step): docs/PROJECT_GUIDE.md#10-complete-metamask-guide-connect-wallet--add-network

Architecture

Payment Request
      │
      ▼
┌─────────────────────────────────────┐
│  Layer 1: Identity Verification     │  MCP: @cerberus/mcp-identity
├─────────────────────────────────────┤
│  Layer 2: Risk & Safety Screening   │  MCP: @cerberus/mcp-payment-guard
├─────────────────────────────────────┤
│  Layer 3: Execution & Authorization │  MCP: @cerberus/mcp-execution
│           + Policy.validate (chain) │  + PaymentGateway.pay (wallet)
└─────────────────────────────────────┘
      │
      ▼
  Approved / Blocked + Audit Log + Events

Pitch: MCP lets the agent check smartly; on-chain Policy makes rules unbypassable; events are independently verifiable.

Quick Start (Simulated Demo)

npm install
npm run demo

Open http://localhost:3000 — badge ⚡ Simulated.

Five scenarios: Identity / Risk / On-chain Policy / Success / Amount Limit.

On-Chain Mode + MetaMask (Summary)

# Terminal 1 — keep running
npm run node

# Terminal 2
npm run deploy:local

# Terminal 3
npm run demo

1. Badge should show ⛓️ On-chain.
2. In MetaMask, add network Localhost 8545 (RPC http://127.0.0.1:8545, chainId 31337).
3. Import Hardhat Account #0 private key:
   0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
4. Run scenario 4 · Successful Payment → Connect Wallet → Approve & Pay.

Full step-by-step guide: §10 in docs/PROJECT_GUIDE.md.

Base Sepolia: PRIVATE_KEY=0x... npm run deploy:base-sepolia (then switch MetaMask to chainId 84532).

Mode	Layer 3 Policy
⚡ Simulated	In-memory whitelist simulation
⛓️ On-chain	viem readContract → Policy.validateWithReason

MCP Servers

npm run mcp:identity
npm run mcp:guard
npm run mcp:execution

Project Structure

cerberus/
├── docs/PROJECT_GUIDE.md     # Full project guide + MetaMask tutorial
├── packages/core/            # Three-layer firewall + chain/viem
├── packages/mcp-identity/
├── packages/mcp-payment-guard/
├── packages/mcp-execution/
├── packages/contracts/       # Policy, PaymentGateway, AgentRegistry, MockUSDC
└── apps/demo/                # Next.js demo + wagmi

License

MIT