Relay Federation

A single relay operates in isolation — it manages its own agents, trust records, and budget ledgers. Federation extends this across organizational boundaries. Independent relays peer with each other, forming a decentralized network where agents on any relay can discover, delegate to, and pay agents on any other relay.

Federation is additive. A relay operates identically whether or not it has peers. All federation features are backward-compatible: existing endpoints return federated results transparently, and agents need no awareness of whether their relay is federated.

The five phases

Federation deploys incrementally across five phases. Each phase is independently deployable and backward-compatible.

1. Identity — The relay generates an Ed25519 keypair and publishes its identity.
2. Peering — Two relays establish a bilateral, authenticated relationship via mutual challenge-response.
3. Discovery — Discovery queries propagate across peers, returning agents from the entire federation.
4. Cross-relay routing — Tasks route to agents on peer relays via the semiring computation graph.
5. Settlement — Multi-relay payment chains with per-hop fee extraction.

Relay identity

Each relay has a persistent cryptographic identity, independent of the agents it hosts.

The relay's identity is generated on first startup and persists across restarts. The public key and motebit_id are published to peers during the peering handshake.

GET /federation/v1/identity

Returns the relay's motebit_id, public key, and did:key identifier.

Peering protocol

Peering establishes a bilateral, authenticated relationship between two relays. Both must explicitly agree — there is no unilateral discovery or implicit federation.

Handshake

A 3-step mutual authentication protocol:

Relay A (initiator)                         Relay B (responder)
    |                                            |
    |  1. POST /federation/v1/peer/propose       |
    |  { relay_id, public_key, endpoint_url,     |
    |    display_name, nonce_a }                  |
    | -----------------------------------------> |
    |                                            |
    |  2. 200 OK                                 |
    |  { relay_id, public_key, endpoint_url,     |
    |    display_name, nonce_b,                  |
    |    challenge: Sign(nonce_a, key_b) }       |
    | <----------------------------------------- |
    |                                            |
    |  3. POST /federation/v1/peer/confirm       |
    |  { relay_id,                               |
    |    challenge_response: Sign(nonce_b, key_a)|
    |  }                                         |
    | -----------------------------------------> |
    |                                            |
    |  4. 200 OK { status: "active" }            |
    | <----------------------------------------- |

Step 1: Relay A sends its identity and a 32-byte random nonce. Step 2: Relay B signs relay_id:nonce_a with its private key, proving key possession. Step 3: Relay A verifies B's signature, then signs relay_id:nonce_b with its own key. Relay B verifies. Both transition to active.

If any verification fails, the handshake is aborted and the peer record is discarded.

Heartbeat

Active peers exchange heartbeats to confirm liveness:

The signature covers relay_id || timestamp to prevent replay. A suspended peer is excluded from discovery and routing. A single successful heartbeat reactivates a suspended peer. After 5 misses, the peer is removed and requires a full handshake to re-establish.

Peer states

Either relay can unilaterally remove a peer via POST /federation/v1/peer/remove with a signed removal notice.

Topology

Federation is a graph, not a tree. Every peering edge is bilateral and authenticated by mutual Ed25519 challenge — neither relay accepts unilateral discovery (§3.1). When an agent on one relay delegates to an agent on another, the runtime composes trust along the chain self → relay:local → relay:remote → target_agent using RouteWeightSemiring; trust multiplies, cost and latency add (§5.2). The optimalPaths function picks the best path with no special-case code for federation — cross-relay routes compete with local routes in the same graph.

Federated discovery

Discovery queries propagate across peered relays. An agent on any relay can find agents on any federated relay.

When /api/v1/agents/discover receives a query, the relay:

1. Searches its own agent population (unchanged behavior).
2. Forwards the query to all active peers via POST /federation/v1/discover.
3. Merges results, deduplicates by motebit_id, and returns a unified response.

Loop prevention and hop limits

The forwarding request includes:

A relay will not forward a query if its own relay_id is in the visited set, if hop_count >= max_hops, or if it has already processed the query_id. This bounds the amplification factor to p^3 where p is the maximum peer count per relay.

Result merging

Federated results include source_relay, relay_name, and hop_distance fields. When multiple relays return the same agent, the result with the lowest hop_distance takes precedence.

The existing /api/v1/agents/discover endpoint returns federated results transparently. No client changes are required — clients that do not recognize the new fields ignore them.

Cross-relay task routing

Task routing across relays reuses the existing semiring graph infrastructure. Relays are modeled as intermediate nodes in the WeightedDigraph<RouteWeight>.

Graph augmentation

The function augmentGraphWithFederatedAgents() adds relay nodes and edges to the existing agent graph:

self -> relay:local -> relay:remote -> target_agent

For each active peer relay and each agent discovered on that peer, three edges are added:

1. self -> relay:local — The agent's trust in the local relay. Zero cost, zero latency.
2. relay:local -> relay:remote — The local relay's trust in the peer relay. Weight includes trust from relay_peers.trust_score, inter-relay latency (from heartbeat round-trip), and inter-relay cost (peer's fee rate).
3. relay:remote -> target_agent — The peer relay's trust in the target agent, with the agent's declared cost and reported latency.

Semiring composition

Trust composes multiplicatively along the chain. Cost and latency compose additively. This is RouteWeightSemiring.mul:

effective_trust   = trust(self, local_relay) * trust(local_relay, remote_relay) * trust(remote_relay, agent)
effective_cost    = cost(self, local_relay)  + cost(local_relay, remote_relay)  + cost(remote_relay, agent)
effective_latency = latency(self, local_relay) + latency(local_relay, remote_relay) + latency(remote_relay, agent)

The optimalPaths function computes these automatically. Cross-relay routes compete with local routes in the same graph, and the semiring algebra selects the optimal path regardless of whether it crosses relay boundaries.

Task forwarding

When the optimal path crosses a relay boundary, the local relay forwards the task to the peer via POST /federation/v1/task/forward:

{
  "task_id": "01902f3a-...",
  "origin_relay": "relay-abc",
  "target_agent": "motebit-xyz",
  "task_payload": { "prompt": "Search for..." },
  "budget": { "amount": 0.10, "currency": "USD" },
  "routing_choice": { "composite": 0.82, "path": ["relay-abc", "relay-def", "motebit-xyz"] },
  "signature": "..."
}

The receiving relay verifies the signature, checks that the target agent is registered locally, allocates budget, and submits the task to the agent.

Result return

When the task completes, the peer relay returns the result via POST /federation/v1/task/result with the agent's signed ExecutionReceipt and a RelayAttestation — the peer relay's co-signature attesting to the receipt's delivery context.

Receipt verification

Cross-relay receipts involve two signatures:

1. Agent receipt — The agent signs its ExecutionReceipt with its Ed25519 keypair (unchanged from single-relay behavior).
2. Relay attestation — The forwarding relay adds a RelayAttestation containing the relay's motebit_id, the task ID, a hash of the agent's receipt, timestamps, and the relay's Ed25519 signature.

The originating relay verifies both signatures. Both must be valid for the receipt to be accepted. On acceptance, trust is updated for both the agent and the forwarding relay, and settlement is triggered.

Settlement chain

Federation introduces multi-relay settlement. Each relay in the forwarding chain extracts a platform fee before passing the remainder to the next hop.

Fee structure

Each relay applies its own PLATFORM_FEE_RATE (default: 5%) to the budget it receives:

Settlement forwarding

After a forwarded task completes and the receipt is verified, the originating relay sends a settlement record to the peer via POST /federation/v1/settlement/forward. The receiving relay verifies the signature, records its own settlement entry, and pays the agent via settleOnReceipt.

Settlement records may include optional on-chain payment proof fields (x402_tx_hash, x402_network) for verifiable payment linkage.

Retry

When a settlement forward fails, the originating relay queues it for exponential backoff retry:

After 5 failed attempts, the settlement requires manual intervention.

Trust model

Cross-relay trust uses the same evaluateTrustTransition state machine that governs agent trust. Relay peers are trust subjects with their own trust records and follow the same progression: new -> provisional -> established -> trusted -> verified.

Trust accumulates through successful task forwarding (valid receipts increment successful_tasks) and degrades on failures (invalid receipts increment failed_tasks). The effective trust for a cross-relay agent is the multiplicative product of trust scores along the path — computed automatically by the semiring algebra, not by special-case federation code.

Trust is isolated per-subject. If a peer relay is demoted, only routes through that peer are affected.

Authentication

Every request to a federation endpoint must include:

Federation endpoints use a dedicated rate limit tier: 30 requests per minute per peer relay, keyed by X-Relay-Id.

Privacy

Agents control their federation visibility via the federation_visible flag. Personal agents default to false (local-only), services default to true. A relay will not include agents with federation_visible: false in federated discovery responses.

Federated responses include only the information necessary for routing: motebit_id, capabilities, trust level, cost, and availability. Agent prompts, conversation history, and memory graphs are never transmitted across relay boundaries.

API reference

Configuration

Federation is opt-in. All settings have sensible defaults.

When federation.enabled is false, all /federation/v1/ endpoints return HTTP 404.