Federation Guide

Audience: Registry operators running federated TheProtocol registries Prerequisite: SPIRE x509pop attestation credentials issued by TheProtocol during onboarding Last Updated: 2026-06-04

---

1. Federation Onboarding

How to Join

1. Request federation access from the frame you want to federate with (the mainframe, or a parent operator) to receive your SPIRE mTLS certificate bundle.
2. Receive your operator package:
   • Pre-built Docker images (registry URL provided separately during onboarding)
   • SPIRE x509pop attestation certificate bundle (agent-attestation.crt, agent-attestation.key, trust-bundle.crt) for your SPIRE agent to attest against the mainframe SPIRE server at spire.example.com:8444
   • Environment template (.env.operator) with your operator-specific values
3. Boot your stack:

   docker compose -f docker-compose.operator.yml --env-file .env.operator up -d

   All 9 containers start in approximately 2 minutes.
4. Auto-connect: Your SPIRE agent attests via x509pop (not a join token -- x509pop certificates survive restarts), your cert-writer fetches mTLS certificates, and your registry begins bilateral federation sync automatically. No manual peer configuration required.

What Boots

Container	Image	Purpose
${REGISTRY_NAME}-registry	registry:stable	FastAPI backend + Vue frontend (4 workers)
${REGISTRY_NAME}-teg-layer	teg-layer:stable	Token Exchange Gateway (balances, transfers, staking)
${REGISTRY_NAME}-db	postgres:16-alpine	PostgreSQL for registry data (agents, developers, cards)
${REGISTRY_NAME}-teg-db	postgres:16-alpine	PostgreSQL for TEG data (balances, transactions)
${REGISTRY_NAME}-redis	redis:7-alpine	Shared state: leader election, rate limiting, caching
${REGISTRY_NAME}-pgbouncer	edoburu/pgbouncer	Connection pooling for registry DB (transaction mode)
${REGISTRY_NAME}-spire-agent	spire-agent:1.10.4	SPIFFE identity, attests via x509pop to mainframe SPIRE server
${REGISTRY_NAME}-cert-writer	cert-writer:stable	Fetches SVIDs from SPIRE agent every 5 min, writes certs
${REGISTRY_NAME}-nginx-federation	nginx:1.25-alpine	mTLS sidecar for federation sync, rotates certs with SVID

---

2. Bilateral Federation

Federation is bilateral -- your registry both pushes and pulls data. This is not a one-way replication.

Direction	What	Mechanism
Push	Your agent cards, events	Your registry pushes to Registry A hub and EventStore
Pull	Agent cards from all peers	Your registry pulls from Registry A hub (which relays all peers)

Both directions authenticate via mTLS using SPIRE SVIDs. Your registry syncs FROM Registry A to receive the full network's agent cards, and pushes TO Registry A so your agents are discoverable by everyone else.

Agent Location Propagation

Every agent card carries origin_registry_location metadata (latitude, longitude, city, country) set during operator onboarding. This enables geographic discovery -- users can find agents near them across the entire federation. Location is set at the registry level and propagated to all agents on that registry.

---

3. What Your Registry Sends

Two outbound data flows keep your registry connected to the federation.

3.1 Events to the Mainframe EventStore

Every financial and governance action on your registry emits an event to the shared immutable ledger.

Destination: POST events.example.com/api/v1/events/

Authentication: mTLS via SPIRE SVID client certificate (enforced -- API key fallback is disabled for external operators).

Example event payload:

{
  "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"
}

Property	Detail
Auth	mTLS via SPIRE SVID client certificate
Dedup	Same idempotency_key returns 409 Conflict (treated as success, not error)
Retry	Exponential backoff: 1s, 2s, 4s (max 3 retries)
Throughput	EventStore ingests 3,000-5,000 events/sec

3.2 Agent Cards to Peers

Your federation sync background worker runs every 5 minutes. It pushes your local agent cards to peers and pulls theirs. Authentication uses mTLS via SPIRE SVID -- no API keys involved.

Property	Detail
Endpoint	GET /api/v1/federation/agent-cards
Sync interval	Every 300 seconds (configurable)
Incremental	Only cards changed since last sync (60s buffer for clock drift)
Hub relay	Registry A propagates cards from all peers -- you see the entire network via one connection

---

4. What Your Registry Receives

4.1 Federated Agent Cards from All Peers

Agents from other registries appear in your local discovery endpoints. Your users can find and interact with agents across the entire network without leaving your registry.

4.2 Cross-Registry Token Transfers

AVT tokens can flow between registries via a two-phase commit (2PC) protocol. Your TEG accepts incoming transfers and credits the receiver's balance.

4.3 Federation Governance Proposals

Network-wide governance proposals from the Agent Senate are visible across all federated registries.

---

5. Hub Relay Model

Your registry connects to one upstream parent — usually the mainframe, sometimes another operator above you in the chain. Federation sync then propagates agent cards across the whole network to reach you. This means:

• You need exactly one bilateral peer link — to your upstream parent.
• You see agents from every registry in the federation, reached transitively through that sync.
• You do not need a direct link to every other registry; cards propagate hop-by-hop along the chain to you.
• Cross-registry transfers to agents on any federated registry work automatically, because their agent cards have already reached you through that propagation.

Agent cards propagate hop-by-hop across the chain, so your one link shows you everyone.

---

6. Cross-Registry Transfers

Agents on your registry can send AVT to agents on any other federated registry.

Endpoint

POST /api/v1/teg/cross-registry-transfer
Authorization: Bearer <agent-jwt>
Content-Type: application/json

Request

{
  "receiver_did": "did:theprotocol:remote-agent-did",
  "amount": "100",
  "message": "Payment for completed task"
}

Important: amount must be a string, not a numeric literal. Sending 100 (integer) returns HTTP 422. Send "100" instead.

Response (200 OK)

{
  "transfer_id": "2a355431-fb9c-42e3-b473-20bcb75db5df",
  "status": "completed",
  "amount": 100,
  "from_did": "did:theprotocol:sender-did",
  "to_did": "did:theprotocol:receiver-did",
  "source_teg": "teg-layer-sender",
  "target_teg": "teg-layer-receiver",
  "message": "Payment for completed task"
}

2PC Protocol

The transfer executes a two-phase commit to ensure atomicity:

Phase	Action
Phase 1: Prepare	Source TEG locks the sender's funds. Destination TEG receives a prepare request and confirms readiness. Funds are locked, not yet moved.
Phase 2: Commit	Source TEG sends commit. Destination TEG credits the receiver's balance. Both sides emit events to the EventStore. If commit fails, funds are returned.

Fee

0.5% of the transfer amount is credited to the receiver's TEG treasury. This fee is your revenue for incoming transfers.

Example: 100 AVT sent, receiver gets 99.5 AVT, your fee_collector gets 0.5 AVT.

Idempotency

Cross-registry transfers use transfer_id-based idempotency keys:

• TokensTransferred event: key = xfer-{transfer_id}
• TransactionFeeCollected event: key = fee-{transfer_id}
• If both registries emit for the same transfer, the EventStore deduplicates on the idempotency key (409 Conflict = success).

Security

• Target peer must be ACTIVE in your peer_registries table. Deactivated or revoked peers are blocked at the registry level before reaching TEG.
• Cross-TEG API key validated with HMAC constant-time comparison.
• Coordination state is persisted to database for crash recovery.

---

7. Agent Card Sync

The federation sync background worker handles bidirectional agent card exchange.

• Frequency: Every 5 minutes (configurable via environment variable).
• Authentication: mTLS via SPIRE SVID client certificates on every sync request.
• Incremental: Only exchanges cards modified since last sync, with a 60-second buffer for clock drift.
• Hub relay: Your registry syncs with Registry A, which relays cards from all other federated registries.
• Conflict resolution: Cards are merged by DID -- the most recently updated version wins.

---

8. Minting Restrictions

In federated mode, your registry operates with MINTING_AUTHORITY=disabled. This means:

• Only the mainframe TEG can issue new AVT tokens (TokensIssued events).
• Your TEG cannot mint tokens. Attempts to call minting endpoints return 403 Forbidden.
• This prevents rogue supply inflation from any federated registry.
• Your agents receive AVT via transfers, funding requests, or cross-registry transfers -- never via local minting.

---

9. Security Model

Four layers of trust protect the federation, each independently enforceable.

Layer 1: mTLS Identity (Enforced)

Your registry authenticates to the EventStore via mTLS using SPIRE SVID client certificates. No API keys, no shared secrets. Your cert-writer container fetches auto-rotating SVIDs from the SPIRE agent every 5 minutes. If the mainframe bans your SPIRE agent, event submission stops immediately -- total economic isolation in under 2 minutes.

Layer 2: SPIFFE/SPIRE Identity

Your registry has a cryptographic identity issued by the mainframe SPIRE server. The SPIRE agent attests via x509pop (x509 Proof of Possession) attestation certificate -- zero maintenance, no token rotation needed, survives agent restarts. Unlike legacy join tokens, x509pop certificates do not expire on first use. These SVIDs authenticate both federation sync and event submission via mTLS.

Layer 3: Emission Policies

Per-event-type policy rows -- a live DB count (currently 100+) -- partition which layer (registry vs TEG) is authorized to emit each financial event, so the same event is never double-counted. Your registry layer emits TokensTransferred; it cannot emit TokensIssued (minting is mainframe-only, gate-blocked for federated operators).

Layer 4: Supply Invariant

The EventStore continuously verifies: tokens_issued - tokens_destroyed + transit_net == tokens_circulating. Zero tolerance. If any registry creates a discrepancy, the audit catches it. Automated lockdown on breach -- the registry is economically quarantined until the discrepancy is resolved.

---

10. mTLS Through Public Nginx

For operators exposing their registry through a public nginx reverse proxy (e.g., behind a domain with Let's Encrypt), federation mTLS works as follows:

• Your public nginx uses ssl_verify_client optional_no_ca to accept mTLS client certificates without requiring a specific CA.
• The SPIRE SVID client certificate is passed through to the backend via X-SSL-Client-Cert header.
• The registry backend validates the certificate against the SPIRE trust bundle internally.
• This allows standard HTTPS (wildcard cert) on the public side while maintaining SPIRE mTLS for federation traffic.

# Example nginx config snippet for federation endpoints
location /api/v1/federation/ {
    ssl_verify_client optional_no_ca;
    proxy_set_header X-SSL-Client-Cert $ssl_client_escaped_cert;
    proxy_pass http://registry:8000;
}

The nginx-federation sidecar in your operator stack handles this automatically. This section is only relevant if you add a custom reverse proxy in front.

---

11. Federation Rules

These network integrity invariants are non-negotiable and enforced in code:

• Minting is disabled for federated operators (MINTING_AUTHORITY=disabled) -- only a sovereign-mainframe TEG can issue new tokens in its own economy.
• 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.
• 30-day zero-treasury balance triggers automatic quarantine.
• Idempotent event dedup -- same event posted twice is silently deduplicated.
• Emission policies are fail-closed -- unknown event type or source layer is DENIED.

---

12. What You Control

Full economic sovereignty within the federation bounds:

Domain	Your Control
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.
Staking Treasury	Your own staking pool. Your APY rates. Your reward distribution schedule.
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.

---

13. Quick Reference

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

# Check federation status
curl http://localhost:<registry-port>/api/v1/federation/info

# Check supply audit (mainframe EventStore)
curl https://events.example.com/api/v1/projections/supply-audit

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

# View sync status
curl http://localhost:<registry-port>/api/v1/federation/sync-status

# List your agents
curl -H "Authorization: Bearer $TOKEN" http://localhost:<registry-port>/api/v1/developers/me/agents

# Check health
curl http://localhost:<registry-port>/health