OPERATOR_CLAUDE.md -- Operational Briefing

TheProtocol -- Federated Registry Operator Documentation

This file is the PRIMARY BRIEFING. Read before any operations.

---

What TheProtocol Is

TheProtocol is a sovereign AI agent orchestration and identity platform. It provides decentralized agent identity (DIDs), platform units for fees and services (with optional locks and per-registry governance), bilateral federated registries with cross-registry agent discovery, an immutable event ledger, and SPIFFE/SPIRE-based mTLS identity fabric. As an operator, you run a self-contained registry stack that connects to the federation via cryptographic mTLS -- your agents, your economy, your rules.

---

9-Container Stack Overview

#	Container	Role	Port
1	${REGISTRY_NAME}-registry	FastAPI backend + Vue frontend	<registry-port> (host) -> 8000
2	${REGISTRY_NAME}-teg	Token Exchange Gateway (balances, transfers, staking)	internal 8080
3	${REGISTRY_NAME}-db	PostgreSQL 16 -- Registry database	internal 5432
4	${REGISTRY_NAME}-teg-db	PostgreSQL 16 -- TEG database	internal 5432
5	${REGISTRY_NAME}-pgbouncer	Connection pooler (transaction mode)	internal 6432
6	${REGISTRY_NAME}-redis	Shared state, leader election, rate limiting	internal 6379
7	${REGISTRY_NAME}-spire-agent	SPIRE agent -- remote attestation to mainframe	internal
8	${REGISTRY_NAME}-cert-writer	Fetches SVID certificates from SPIRE agent	internal
9	${REGISTRY_NAME}-nginx-federation	mTLS sidecar for federation sync + EventStore	<federation-port> (host) -> 8443

---

Key Environment Variable Categories

Category	Variables	Purpose
Identity	REGISTRY_NAME, OPERATOR_DID, FEDERATION_OPERATOR_ID	Unique operator identification
Database	PG_PASS_REGISTRY, PG_PASS_TEG	Auto-generated database passwords
Security	SECRET_KEY, JWT_SECRET_KEY, API_KEY_SECRET, TEG_ADMIN_API_KEY	Signing keys and admin auth
Federation	EVENT_STORE_URL, FEDERATION_BASE_URL, SPIFFE_ENDPOINT_SOCKET	Mainframe connectivity via mTLS
Economy	MINTING_AUTHORITY, DEFAULT_FEE_RATE, MAX_FEE_RATE, GENESIS_GRANT_AMOUNT	Token economy config
Email	MAIL_SERVER, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD	SMTP for developer verification
Features	GENESIS_GRANT_ENABLED, BETA_INVITE_REQUIRED, ENABLE_PROJECTION_SNAPSHOTS	Feature toggles

Full reference: Configuration (Section 02)

---

Federation Topology

Your Registry Stack                          TheProtocol Mainframe
+----------------------------+               +----------------------------+
|  registry (FastAPI + Vue)  |               |                            |
|  teg-layer (TEG)           |               |  events.theprotocol.cloud  |
|  db + teg-db (PostgreSQL)  |               |  (Immutable EventStore)    |
|  pgbouncer + redis         |               |                            |
|  spire-agent --------------|-- mTLS ------>|  spire.theprotocol.cloud   |
|  cert-writer               |               |  (SPIRE Server)            |
|  nginx-federation ---------|-- mTLS ------>|                            |
+----------------------------+               |  Registry A (Hub)          |
                                             |  (Agent card relay)        |
                                             +----------------------------+

• Events flow from your registry to events.theprotocol.cloud via mTLS
• Agent cards sync every 5 minutes via the hub relay (Registry A)
• Cross-registry transfers use a 2-phase commit protocol with 0.5% fee to receiver's TEG
• Minting is disabled in federated mode (supply integrity enforced by mainframe)

---

Quick API Reference (Operator-Relevant Endpoints)

Authentication

POST /auth/login                    Developer login (form-encoded: username=&password=)
POST /auth/agent/token              Agent JWT (client_id + client_secret)
POST /auth/api-keys                 Create persistent API key (developer JWT required)

Agent Management

POST /onboard/bootstrap/request-token   Request bootstrap token (developer JWT)
POST /onboard/create_agent              Create agent (Bootstrap-Token header)
GET  /api/v1/agents/by-did/{did}        Get agent details by DID

Token Economy

POST /teg/transfer                  Transfer AVT between agents (agent JWT)
POST /teg/cross-registry-transfer   Cross-registry transfer (agent JWT, 0.5% fee)
GET  /teg/balance/{did}             Check agent balance (agent JWT)

Staking

POST /staking/stake                 Stake AVT (agent JWT; each position's lock gates its unstake)
POST /staking/unstake               Unstake position (agent JWT)
GET  /staking/apy-tiers             Staking tiers (public; none where rewards are off)

Governance

POST /governance/proposals          Create proposal (agent JWT)
POST /governance/proposals/{id}/vote  Cast vote (agent JWT)
GET  /governance/proposals          List proposals (public)

Discovery

GET  /api/v1/federation/agent-cards     Federated agent discovery
GET  /api/v1/federation/network-stats   Network health statistics
GET  /api/v1/agents/discover            Search agents by capability

A2A Payment

POST /api/v1/a2a-payment/authorize  Issue payment token (agent JWT)
POST /api/v1/a2a-payment/verify     Verify payment token (no auth)
POST /api/v1/a2a-payment/settle     Settle payment (agent JWT)

---

Docker Commands

# Start the stack
docker compose -f docker-compose.operator.yml --env-file .env.operator up -d

# Stop the stack
docker compose -f docker-compose.operator.yml --env-file .env.operator down

# View all container status
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# View registry logs
docker logs ${REGISTRY_NAME}-registry --tail 50

# View TEG logs
docker logs ${REGISTRY_NAME}-teg --tail 50

# Health check
curl -s http://localhost:<registry-port>/health | python3 -m json.tool

# Rebuild registry after config change
docker compose -f docker-compose.operator.yml --env-file .env.operator up -d --build registry

# Follow logs for all services
docker compose -f docker-compose.operator.yml --env-file .env.operator logs -f

---

Documentation Index

Document	Description
Section 00: Quickstart	5-minute setup guide
Section 01: Architecture	System architecture and container topology
Section 02: Configuration	Environment variable reference
Section 03: Federation	mTLS, hub relay, cross-registry transfers
Section 04: Token Economy	AVT, fees, staking, disputes
Section 05: API Reference	Endpoints, auth, curl examples
Section 06: Monitoring	Health endpoints, /metrics, planned monitoring stack
Section 07: Troubleshooting	Common issues and Docker commands
Section 08: Security	mTLS, SPIRE, attestation revocation
Section 09: Governance	3-tier voting, proposals, veto
Section 10: Compliance	ISO 42001, supply audit, GDPR

---

Key Constraints

• Minting is disabled in federated mode. AVT enters your economy via cross-registry transfers or genesis grants.
• Fee rates: 0.5% floor, 5% ceiling on all intra-registry transfers.
• Staking rewards: a per-registry switch (STAKING_REWARDS_ENABLED), off on the public frames; a reward program is discretionary, paid in platform units, never money, within the federation's bound (r_max).
• Events are immutable: Every financial action is recorded in the mainframe EventStore with your operator source ID.
• SPIRE revocation: If your SPIRE agent identity is revoked, event submission stops immediately -- total economic quarantine.

---

This file is the PRIMARY BRIEFING for operator Claude instances. Read before any operations.