Skip to content

System Architecture

The Agent Registry is composed of six layers: the agent layer, the SDK layer, the relay layer, the blockchain layer, the query layer, and the enforcement layer. Each layer is independent and communicates through well-defined interfaces.

Full System Architecture

graph TB
    subgraph "AGENT LAYER"
        A1["Autonomous Agent"]
        A2["Corporate Bot"]
        A3["Child Agent"]
    end
    subgraph "SDK LAYER"
        SDK_PY["Python SDK"]
        SDK_JS["TypeScript SDK"]
    end
    subgraph "RELAY LAYER"
        REL["Gasless Relayer<br/>(ERC-2771)"]
    end
    subgraph "BLOCKCHAIN LAYER (Base L2)"
        FWD["MinimalForwarder<br/>(EIP-712)"]
        REG["Agentenregister"]
    end
    subgraph "QUERY LAYER"
        API["REST API"]
    end
    subgraph "FRONTEND"
        WEB["Web Dashboard"]
    end
    subgraph "ENFORCEMENT (KYA)"
        KYA["Infrastructure Providers"]
    end
    A1 --> SDK_PY
    A2 --> SDK_JS
    A3 --> SDK_PY
    SDK_PY -->|"sign + POST"| REL
    SDK_JS -->|"sign + POST"| REL
    REL -->|"submit + pay gas"| FWD
    FWD -->|"call + append sender"| REG
    REG -->|"events"| API
    API --> WEB
    KYA -->|"GET /kya/:wallet"| API

Layer Descriptions

Agent Layer

The top layer consists of the autonomous agents themselves. These can be:

  • Autonomous agents -- fully self-directed AI systems that earn money, make decisions, and spawn children
  • Corporate bots -- enterprise-operated agents for customer service, data processing, or automated operations
  • Child agents -- agents spawned by other agents, forming lineage trees

Agents interact with the registry exclusively through the SDK layer. They never need to understand blockchain mechanics, gas fees, or transaction formatting.

SDK Layer

The SDK layer provides language-native interfaces for agent developers.

SDK Language Status Features
agentenregister.py Python Production Gasless + direct mode, type hints, dataclasses
@agentenregister/sdk TypeScript Production Gasless + direct mode, full type safety

Both SDKs support:

  • Gasless mode (default): sign locally, relay through the relayer service
  • Direct mode: submit transactions directly to the blockchain (requires ETH)

Relay Layer

The gasless relayer is an Express.js service that accepts signed EIP-712 requests from agents and submits them to the blockchain, paying gas on the agent's behalf.

Relayer Details

  • Port: 3001
  • Rate limits: 20 requests/IP/hour, 10 requests/signer/hour
  • Daily budget: 0.05 ETH (configurable)
  • Backpressure: Refuses requests when balance drops below 0.001 ETH

See Gasless Transactions for the full technical flow.

Blockchain Layer

Two smart contracts deployed on Base L2 (an Ethereum Layer 2 chain):

Contract Purpose Address (Base Sepolia)
MinimalForwarder ERC-2771 trusted forwarder; verifies EIP-712 signatures and forwards calls 0x70c2...29e5
Agentenregister Core registry; stores agent records, lineage, compliance, revenue 0x2EFa...EA23

Why Base L2?

Base is an Ethereum Layer 2 built on the OP Stack. It provides Ethereum's security guarantees with transaction costs 50-100x lower than mainnet. A typical registration costs the relayer approximately $0.005. See the project docs for the full chain selection rationale.

Query Layer

The REST API is a read-only Express.js service that queries the on-chain registry and serves JSON responses.

Endpoint Description Cache TTL
GET /api/v1/stats Registry-wide statistics 10 min
GET /api/v1/agent/:id Full agent record + compliance 5 min
GET /api/v1/agent/:id/lineage Recursive lineage tree 10 min
GET /api/v1/agent/:id/revenue Paginated revenue history 5 min
GET /api/v1/kya/:wallet KYA compliance check 1 min
GET /health Health check None

Rate limiting: 60 requests/minute per IP.

Enforcement Layer (KYA)

Infrastructure providers integrate with the KYA API to verify agents before provisioning services. This creates an economic incentive for agents to register and maintain compliance.

See KYA (Know Your Agent) for the full enforcement model.

Agent Registration Flow

The following sequence diagram shows the complete gasless registration flow, from an agent's register() call to the on-chain event.

sequenceDiagram
    participant Agent
    participant SDK
    participant Relayer
    participant Forwarder as MinimalForwarder
    participant Registry as Agentenregister
    Agent->>SDK: register(params)
    SDK->>SDK: Encode calldata + sign EIP-712
    SDK->>Relayer: POST /relay {request, signature}
    Relayer->>Relayer: Verify signature, check rate limits
    Relayer->>Forwarder: execute(request, signature)
    Forwarder->>Forwarder: Verify signature on-chain, check nonce
    Forwarder->>Registry: call(data + agent_address)
    Registry->>Registry: _msgSender() extracts agent address
    Registry-->>Forwarder: agentId
    Forwarder-->>Relayer: success + receipt
    Relayer-->>SDK: {txHash, blockNumber}
    SDK-->>Agent: agentId

Step-by-step:

  1. Agent calls SDK: The agent calls register() with its parameters (Haftungsperson, capabilities, operational scope, etc.)
  2. SDK encodes and signs: The SDK encodes the registerAgent() calldata and signs it as EIP-712 typed data using the agent's private key
  3. SDK posts to relayer: The signed request is sent to POST /relay on the relayer service
  4. Relayer validates: The relayer verifies the signature off-chain, checks rate limits, and checks its own balance
  5. Relayer submits: The relayer calls MinimalForwarder.execute() on-chain, paying gas
  6. Forwarder verifies: The MinimalForwarder verifies the EIP-712 signature on-chain, checks the nonce, and forwards the call to the Agent Registry with the agent's address appended to calldata
  7. Registry processes: The Agent Registry's _msgSender() extracts the real sender (the agent, not the relayer) from the appended calldata, and registers the agent
  8. Response propagates: The agent ID propagates back through the stack to the agent

Data Flow Diagram

graph LR
    subgraph "Write Path (gasless)"
        W1["Agent signs"] --> W2["Relayer submits"] --> W3["Forwarder verifies"] --> W4["Registry stores"]
    end
    subgraph "Read Path (free)"
        R1["Anyone queries"] --> R2["API reads contract"] --> R3["JSON response"]
    end
    subgraph "Enforcement Path"
        E1["Provider needs to verify"] --> E2["GET /kya/:wallet"] --> E3["Allow or deny service"]
    end
  • Write path: All state changes go through the gasless relay pipeline. Every write emits an event for auditability.
  • Read path: All queries go through the REST API, which reads directly from the smart contract. No gas cost, no authentication required.
  • Enforcement path: Infrastructure providers call the KYA endpoint before provisioning services.

Deployment Environments

Environment Chain RPC Endpoint Purpose
Local Hardhat localhost:8545 Development and testing
Testnet Base Sepolia sepolia.base.org Integration testing, scientific experiments
Mainnet Base mainnet.base.org Production registry

Service Ports

Service Default Port Command
REST API 3000 npm run api
Gasless Relayer 3001 npm run relayer
Web Dashboard 3002 npm run dashboard

All three services can be started simultaneously with npm start (uses concurrently).