Skip to content

Architecture Overview

What is the Agent Registry?

The Agent Registry is a smart contract-based public registry for autonomous AI agents, deployed on Base (an Ethereum Layer 2 network). It combines an on-chain registry with a gasless relayer, REST API, SDKs, and a web dashboard to provide a complete infrastructure for agent identification, accountability, and compliance.

The system is modeled after Germany's Handelsregister (commercial register). Every autonomous agent that transacts economically must be registered with a responsible human entity (Haftungsperson), maintain compliance through periodic attestation, and be publicly queryable by anyone -- including infrastructure providers who enforce KYA (Know Your Agent) checks before provisioning services.

Architecture

The following diagram shows the end-to-end flow from agent registration to public queries:

Agent (has private key, zero ETH)
  |
  +-- 1. Signs EIP-712 message (free, local)
  |
  v
Relayer (port 3001)
  |
  +-- 2. Verifies signature
  +-- 3. Pays gas from relayer wallet
  |
  v
MinimalForwarder (on-chain, ERC-2771)
  |
  +-- 4. Verifies signature on-chain
  +-- 5. Forwards call with agent as msg.sender
  |
  v
Agentenregister (on-chain)
  |
  +-- 6. Registers agent, emits events
  |
  v
REST API (port 3000)
  |
  +-- 7. Queries contract, serves JSON
  |
  v
Infrastructure Providers / Dashboard / Anyone
  |
  +-- 8. KYA checks, agent lookup, lineage trees

How Gasless Registration Works

  1. An agent generates a private key (free, no ETH needed)
  2. The agent constructs a registration call and signs it as an EIP-712 typed data message (free, happens locally)
  3. The agent sends POST /relay to the relayer with the signed request
  4. The relayer verifies the signature, checks rate limits, and submits the transaction to the MinimalForwarder contract -- paying the gas fee (~$0.005)
  5. The MinimalForwarder verifies the signature on-chain and forwards the call to the Agentenregister with the agent's address as the sender (not the relayer's)
  6. The agent is registered on-chain without ever holding any cryptocurrency

ERC-2771 Meta-Transactions

The gasless pattern uses ERC-2771, a standard for native meta-transactions. The MinimalForwarder is the trusted forwarder, and the Agentenregister contract uses _msgSender() instead of msg.sender to recover the original signer's address.

Project Structure

agentenregister/
+-- contracts/
|   +-- Agentenregister.sol        -- Core registry smart contract
|   +-- MinimalForwarder.sol       -- ERC-2771 gasless forwarder
+-- relayer/
|   +-- relayer.js                 -- Gasless relayer service (port 3001)
+-- api/
|   +-- server.js                  -- REST API for queries & KYA checks (port 3000)
+-- sdk/
|   +-- agentenregister.py         -- Python SDK for agent integration
|   +-- typescript/                -- TypeScript SDK (@agentenregister/sdk)
|       +-- src/
|       |   +-- index.ts           -- Main AgentRegistry class
|       |   +-- types.ts           -- TypeScript type definitions
|       |   +-- abi.ts             -- Contract ABI constants
|       |   +-- utils.ts           -- Hash functions, chain configs
|       +-- tests/
|           +-- registry.test.ts   -- SDK unit tests (32 tests)
+-- dashboard/                     -- Public web dashboard (Next.js 14)
|   +-- src/
|       +-- app/                   -- Pages: overview, agents, compliance, revenue, KYA
|       +-- components/            -- Reusable UI components
|       +-- lib/                   -- API hooks, types
+-- scripts/
|   +-- setup.js                   -- Key generation + deployment automation
|   +-- deploy.js                  -- Hardhat deployment script
|   +-- deploy-local.js            -- Local Hardhat node deployment
|   +-- claim-faucet.mjs           -- Automated Coinbase CDP faucet claims
|   +-- run-tests-live.js          -- Live integration tests (Base Sepolia)
|   +-- scientific-harness.js      -- Scientific experiment: 100 agents + metrics
|   +-- verify-contracts.js        -- Basescan contract verification
+-- test/
|   +-- Agentenregister.test.js    -- Test suite (68 tests)
+-- docs/                          -- Project documentation (Markdown)
+-- hardhat.config.js
+-- package.json
+-- .env.example
+-- README.md

Key Services

The Agent Registry runs three services. All three can run simultaneously with npm start (for relayer + API) and npm run dashboard (for the dashboard).

Relayer Service (port 3001)

The relayer enables gasless registration. Agents sign an EIP-712 message locally (free), POST it to the relayer, and the relayer submits the transaction and pays the gas fee.

Property Value
Port 3001 (configurable via RELAYER_PORT)
Start command npm run relayer
Purpose Accept signed meta-transactions, pay gas, submit to chain
Security Rate-limited, daily gas budget cap, balance backpressure
Cost ~$0.005 per registration on Base L2

Endpoints:

Method Endpoint Description
POST /relay Submit a signed meta-transaction
GET /nonce/:address Get forwarder nonce for an address
GET /domain Get EIP-712 domain parameters
GET /status Relayer status, balance, daily usage

For full details, see the Relayer API Reference.

REST API Service (port 3000)

A public, read-only query layer over the on-chain registry. Infrastructure providers, dashboards, and anyone can query agent data without needing blockchain tooling.

Property Value
Port 3000 (configurable via PORT)
Start command npm run api
Purpose JSON API for agent queries, KYA checks, stats
Rate limit 60 requests/minute per IP
Caching 5 min for agents, 1 min for KYA, 10 min for lineage

Endpoints:

Method Endpoint Description
GET /api/v1/stats Registry-wide statistics
GET /api/v1/agent/:id Full agent record with compliance
GET /api/v1/agent/:id/lineage Recursive lineage tree
GET /api/v1/agent/:id/revenue Revenue history (paginated)
GET /api/v1/kya/:wallet KYA compliance check
GET /health Health check

For full details, see the REST API Reference.

Web Dashboard (port 3002)

A public registry explorer built with Next.js 14, Tailwind CSS, Recharts, and SWR.

Property Value
Port 3002
Start command npm run dashboard
Requires API server running on port 3000
Build npm run dashboard:build

Pages:

Route Description
/ Stats overview: agent counts, status/generation charts, recent registrations
/agents Agent explorer: searchable, filterable, paginated table
/agents/:id Agent detail: full "Handelsregisterauszug" with compliance, revenue, children
/lineage/:id Lineage tree: recursive parent-child visualization
/compliance Compliance monitor: all agents sorted by attestation age
/revenue Revenue analytics: charts by currency, category
/kya KYA checker: input wallet, get instant compliance result

For full details, see the Dashboard Overview.

What's Next?