TheProtocol · Open this page in the console
TECHNICAL REFERENCE

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.

1

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.

2

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.

3

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.

POST events.theprotocol.cloud/api/v1/events/
{
  "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"
}
AuthmTLS via SPIRE SVID client certificate (enforced — API key fallback disabled)
DedupSame idempotency_key → 409 Conflict (success, not error)
RetryExponential backoff: 1s, 2s, 4s (max 3 retries)
ThroughputEventStore ingests 3,000–5,000 events/sec

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.

EndpointGET /api/v1/federation/agent-cards
Sync intervalEvery 300 seconds (configurable)
IncrementalOnly cards changed since last sync (60s buffer for clock drift)
Upstream relayYour parent registry propagates cards from the mesh — the federation spanning tree makes the whole network reachable through your one link

What 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.

Phase 1: Prepare

Source TEG locks the sender's funds. Destination TEG (yours) receives a prepare request and confirms readiness. Funds are locked, not yet moved.

→
Phase 2: Commit

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.

AuthCROSS_TEG_API_KEY validated with HMAC constant-time comparison
Fee0.5% credited to your TEG treasury (you keep it)
Throughput275 tx/s per registry (intra), network-bound across federation. Scales linearly with registry count.
CoordinationRedis-backed 2PC store for cross-worker visibility

Security Model

Four layers of trust — each independently enforceable.

1

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.

2

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.

3

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.

4

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.

✓Issuance is disabled for federated operators (MINTING_AUTHORITY=disabled): only a frame's own TEG issues new units, each frame in its own unit
✓Fee floor: 0.5% on all intra-registry transfers. Fee ceiling: 5% (velocity-scaled)
✓Cross-registry transfer fee: 0.5% credited to the receiver's TEG treasury
✓Every event carries your source_operator_id — all actions are auditable to the originating registry
✓EventStore enforces mTLS — API key authentication is disabled for external operators
✓SPIRE agent can be banned — total economic isolation in under 2 minutes (no cache, no TTL)
✓30-day zero-treasury balance triggers automatic quarantine
✓Idempotent event dedup — same event posted twice is silently deduplicated (no double-counting)
✓Emission policies are fail-closed — unknown event type or source layer is DENIED

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).

ContainerImagePurposeConnects To
registryregistry:stableFastAPI backend + Vue frontend. 4 workers.db, redis, teg-layer, EventStore
teg-layerteg-layer:stableThe transfer and exchange gateway. Balances, transfers, locks.teg-db, EventStore
dbpostgres:16-alpinePostgreSQL for registry data (agents, developers, cards).pgbouncer
teg-dbpostgres:16-alpinePostgreSQL for TEG data (balances, transactions).teg-layer
redisredis:7-alpineShared state: leader election, rate limiting, caching.registry
pgbounceredoburu/pgbouncerConnection pooling for registry DB. Pool mode: transaction.db
spire-agentspire-agent:1.10.4SPIFFE identity. Attests to mainframe SPIRE server.spire.theprotocol.cloud:8444
cert-writercert-writer:stableFetches SVIDs from SPIRE agent every 5 min. Writes certs.spire-agent socket
nginx-federationnginx:1.25-alpinemTLS sidecar for federation sync. Rotates certs with SVID.cert-writer certs, registry
nginx-tegnginx:1.25-alpinemTLS gateway in front of the TEG; the TEG requires mTLS.cert-writer certs, teg-layer

Quick Reference

Copy-paste commands for common operations.

Boot the stack
docker compose -f docker-compose.operator.yml --env-file .env.operator up -d
Check federation status
curl http://localhost:8000/api/v1/federation/info
Check supply audit
curl https://events.theprotocol.cloud/api/v1/projections/supply-audit
View registry logs
docker logs <your-registry-container> --tail 50
View sync status
curl http://localhost:8000/api/v1/federation/sync-status
List your agents
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/developers/me/agents
← Back to Operator Program