Skip to content

Federation setup

Federation is optional cross-anchoring between independent Witness gateways. A gateway submits a closed batch to configured peer gateways at POST /v1/federation/anchor; returned cross-anchors are stored with the batch. Federation adds an independent durability signal. It does not provide global ordering, BFT consensus, or protection from colluding operators.

Configuration shape

The federation object in network.json contains:

{
  "federation": {
    "enabled": true,
    "batch_period": 3600,
    "peer_networks": [
      {
        "id": "peer-network",
        "gateway": "https://peer.example.org",
        "min_witnesses": 2,
        "auth_token": "<token-for-peer>"
      }
    ],
    "cross_anchor_threshold": 1,
    "inbound_auth_token": "<token-peers-present-to-this-gateway>"
  }
}

batch_period defaults to 3600 seconds, min_witnesses defaults to 2, and cross_anchor_threshold is the number of distinct configured peer networks required for the configured federated result. The exact threshold should be chosen from the operator's trust model; this page does not prescribe one.

The outbound auth_token is sent to that peer. The inbound token authenticates peers calling this gateway. Both are secrets and are omitted from public verification configuration. A previous_inbound_auth_token is accepted by the current implementation during token transition; it is not a universal revocation mechanism.

Safe setup sequence

  1. Obtain and independently review each peer's public verification configuration, network ID, gateway URL, and expected witness threshold.
  2. Exchange only the tokens required for the two configured directions.
  3. Configure inbound_auth_token before exposing the federation route.
  4. Set peer URLs to HTTPS endpoints that are reachable from the gateway.
  5. Keep the SSRF-safe HTTP client and resolver enabled; private, loopback, and link-local destinations are rejected by the outbound validation.
  6. Start with a deliberate cross_anchor_threshold and observe whether peers respond before treating the result as federated.

Peer failure reduces the achieved federation level and can leave a batch without a cross-anchor. An accepted cross-anchor is not evidence that every peer or operator is honest. Verify the returned attestation against the peer's caller-supplied network verification configuration.