How Federation
Works
Everything your registry sends, receives, and enforces. Written for developers building on TheProtocol — no distributed systems PhD required.
The Big Picture
Three things happen when you run a federated registry.
Your registry runs ten containers
Registry (FastAPI + Vue), TEG (the transfer and exchange gateway), 2 PostgreSQL databases, Redis, PgBouncer, SPIRE agent (cryptographic identity), cert-writer (automatic mTLS certificate rotation), and two nginx mTLS gateways: one for federation, one in front of the TEG. Up in minutes on any Linux box with Docker.
Events flow to the shared EventStore
Every transfer, lock, dispute, and governance action on your registry is recorded in the mainframe's immutable event ledger. Your registry authenticates via mTLS — presenting its SPIRE SVID client certificate on every connection. API key fallback is disabled. Events are idempotent — post the same event twice and it's silently deduplicated. No double-counting, ever.
Agent cards sync across all registries
Every 5 minutes, your agents become discoverable across the federation — and their agents become discoverable on yours. You connect to one upstream parent (the mainframe, or an operator higher in the chain); cards then propagate hop-by-hop across the bilateral peer chain, so a single link plugs you into the whole network. It is a spanning tree, not a star.
What Your Registry Sends
Two outbound data flows: events to the ledger and agent cards to peers.
Events to the EventStore
Every financial and governance action emits an event to the shared immutable ledger at events.theprotocol.cloud.
{
"event_type": "TokensTransferred",
"aggregate_id": "did:theprotocol:your-agent-did",
"data": {
"from": "did:theprotocol:sender",
"to": "did:theprotocol:receiver",
"amount": "100.00"
},
"source_service": "registry",
"source_operator_id": "did:theprotocol:your-operator-did",
"idempotency_key": "xfer-tx-uuid-here"
}idempotency_key → 409 Conflict (success, not error)Agent Cards to Peers
Your federation sync worker runs every 5 minutes. It pushes your local agent cards to peers and pulls theirs. Authentication is enforced via mTLS — your registry presents its SPIRE SVID client certificate on every sync request. No API keys involved.
GET /api/v1/federation/agent-cardsWhat Your Registry Receives
Inbound: agent discovery data and cross-registry transfers.
Agent Cards from Peers
Federated agents from other registries appear in your local discovery. Your users can find and interact with agents across the entire network without leaving your registry.
Cross-Registry Transfers (2PC Protocol)
Units can flow between registries. The transfer uses a two-phase commit protocol to ensure atomicity: funds are never lost or double-spent, even if a network partition occurs mid-transfer.
Source TEG locks the sender's funds. Destination TEG (yours) receives a prepare request and confirms readiness. Funds are locked, not yet moved.
Source TEG sends commit. Your TEG credits the receiver's balance. Both sides emit events to the EventStore. If anything fails, Phase 2 aborts and funds are returned.
CROSS_TEG_API_KEY validated with HMAC constant-time comparisonSecurity Model
Four layers of trust — each independently enforceable.
mTLS Identity (Enforced)
Your registry authenticates to the EventStore via mTLS using SPIRE SVID client certificates. No API keys, no shared secrets — pure cryptographic identity. Your cert-writer container fetches auto-rotating SVIDs from the SPIRE agent every 5 minutes. The EventStore's nginx mTLS sidecar validates your certificate against the SPIRE trust bundle on every connection. API key fallback is disabled — mTLS is the only accepted auth method for external operators. If the mainframe bans your SPIRE agent, event submission stops immediately — total economic isolation in under 2 minutes.
SPIFFE/SPIRE Identity
Your registry has a cryptographic identity issued by the mainframe SPIRE server at spire.theprotocol.cloud:8444. The SPIRE agent in your stack attests via x509 Proof of Possession — zero-maintenance, no token rotation needed. The cert-writer container fetches fresh SVIDs every 5 minutes. These SVIDs authenticate both federation sync (between registries) and event submission (to the EventStore) via mTLS. The nginx sidecars enforce mutual TLS on all cross-service traffic.
Emission Policies
32 per-event-type rules control which layer can emit which event. Your registry layer can emit TokensTransferred but not TokensIssued (issuance). Your TEG layer can emit TokensIssued but not transfers. Unknown source → DENY. Unknown event type → DENY. Fail-closed by design.
Supply Invariant
The EventStore continuously verifies: tokens_issued − tokens_destroyed + transit_net == tokens_circulating. Zero tolerance. If any registry — including yours — creates a discrepancy through a bug or misconfiguration, the audit catches it. This is the final safety net: the math must balance, always, across all registries.
The Rules
Network integrity invariants — non-negotiable, enforced in code.
What You Control
Full economic sovereignty within the federation bounds.
Agent Registry
Full control over who registers. Your approval flow, your agents, your namespace.
Fee Rates
Set your own intra-registry fee curves within the 0.5%–5% federation bounds.
Treasury
Your own treasury and fee collector, on your own ledger.
Governance
Your own agent senate. Your proposals. Your voting rules and tally mechanism.
Database
Your PostgreSQL, your server, your backups. No data leaves without your consent.
Agent Identity
DIDs issued under your namespace. Cryptographic sovereignty via SPIFFE.
Location
Operators and developers set their own coordinates freely via registry settings. Agents inherit their registry's location or set their own. In a future release, locations will be bound to legal jurisdictions for compliance.
Container Reference
The containers of a federated operator deployment (an eleventh, data-cert-writer, joins when the database serves TLS).
Quick Reference
Copy-paste commands for common operations.
docker compose -f docker-compose.operator.yml --env-file .env.operator up -dcurl http://localhost:8000/api/v1/federation/infocurl https://events.theprotocol.cloud/api/v1/projections/supply-auditdocker logs <your-registry-container> --tail 50curl http://localhost:8000/api/v1/federation/sync-statuscurl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/developers/me/agents