System Overview

RobotMoney is a layered protocol where information flows up and control flows down. Each tenant has its own logical instance of every layer, with hard isolation at the database, credential-encryption, and policy boundaries.

At a Glance

┌────────────────────────────────────────────────────────────────┐
│                    Clients (humans, agents)                    │
│   Dashboard · Internal services · External MCP · Surfaces      │
└────────────────────────────────────────────────────────────────┘
                              ↓ Auth (email/password · SIWX)
┌────────────────────────────────────────────────────────────────┐
│                       RobotMoney API                           │
│              REST · JSON-RPC · MCP server surface              │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                  The Six-Layer Protocol Stack                  │
│  Raw → Ledger → Wiki → Policy → Agent → Audit                  │
└────────────────────────────────────────────────────────────────┘
                ↓                              ↓
┌─────────────────────────────┐  ┌─────────────────────────────┐
│        Off-chain state      │  │    On-chain commitments     │
│  Postgres · pgvector · Azure Blob   │  │ Base L2 · RobotMoney contracts │
└─────────────────────────────┘  └─────────────────────────────┘
                                              ↓
                              ┌────────────────────────────────┐
                              │ Execution rails                │
                              │  Bank APIs · Processors ·      │
                              │  Session-key smart account     │
                              │  (x402 fail-closed. RFC 0001) │
                              └────────────────────────────────┘

What Lives Where

Component

Location

Notes

Raw Artifacts

Azure Blob

Content-addressed, tenant-prefixed object storage

Ledger Records

Postgres

Immutable, append-only with supersedence

Wiki Graph and Embeddings

Postgres + pgvector

Updated incrementally

Policy Compiled Form

Postgres

Hash-anchored on-chain

Audit Hash Chain

Postgres

Production tenant roots batched on-chain; demo and sandbox tenant chains remain database-only

Agent Identity

BrainMCPAgentRegistry (Base L2)

Stores agentId/tenantId/scopeHash/behaviorHash (ERC-8004 reputation planned. RFC 0001)

Smart Account State

BrainSmartAccount per tenant (Base L2)

Session-key account (scope, spend caps, bound policyVersion)

Policy Hashes

BrainPolicyRegistry (Base L2)

EIP-712 signed by tenant

Audit Anchors

BrainAuditAnchor (Base L2)

EIP-712 signed by RobotMoney anchorer

On-Chain Surface Is Intentionally Small

RobotMoney's on-chain surface is intentionally minimal. Most logic lives off-chain. On-chain contracts exist for six narrow purposes:

On-Chain Purpose

Contract

Anchor State

BrainAuditAnchor

Register Policy Hashes

BrainPolicyRegistry

Register Agent Identity

BrainMCPAgentRegistry

Enforce Session-Key Scope/Limits and Route Execution

BrainSmartAccount

Custody Conditional Escrow Locks

BrainEscrow

Publish Reputation Roots

BrainReputationRegistry

All six contracts are deployed on Base Sepolia today and written in Solidity 0.8.x, built and tested with Foundry. Mainnet deployment is blocked on external audit, bytecode verification, and operator attestation. The contracts are immutable: there is no upgrade path in the MVP, and any change ships as a separately audited redeploy.

→ Smart contract overview

Six Layers, One API

The same API surface serves humans, internal agents, and external agents. Auth differs; primitives don't.

Layer

Primary API Endpoints

Raw

POST /v1/sources, POST /v1/raw/ingest

Ledger

GET /v1/ledger/transactions, GET /v1/ledger/balances

Wiki

POST /v1/wiki/question, GET /v1/wiki/entity/{id}

Policy

POST /v1/policy, POST /v1/policy/evaluate

Agent

POST /v1/agents, POST /v1/agents/{id}/propose

Audit

GET /v1/audit/{id}, GET /v1/audit/{id}/proof

→ Full API reference

Approval Surfaces

Agent proposals can be delivered to Slack, Microsoft Teams, and email through @brain/surfaces and the standalone services/surface-gateway deployable. These surfaces are not execution rails. They render proposals, capture human decisions, and send every decision through the same RobotMoney approval pipeline: expiry, tenant-scoped identity, policy re-check, terminal-decision idempotency, audit, canonical PaymentIntent approval, then the normal section 6 execution handoff. The gateway has its own DB role and does not receive Ledger or execution outbox privileges.

→ Surface approval adapters