Skip to content

Federation

Federation connects independently configured Witness networks. On batch closure, the home gateway can send the AttestationBatch to configured peers through POST /v1/federation/anchor. A peer signs an attestation whose hash is the batch's Merkle root and whose network ID is the peer's own network ID. The resulting CrossAnchor is therefore independently verifiable against the peer's secret-free verification configuration.

The home configuration specifies:

  • peer network IDs and gateway URLs;
  • min_witnesses required from each peer; and
  • cross_anchor_threshold, the number of distinct peer networks required for a federated verification level.

Peer requests use federation bearer tokens. Public peer discovery and verification configuration exclude endpoints' operational credentials and inbound/outbound auth tokens. Peer gateway URLs require HTTPS except for explicit loopback development URLs, and outbound calls are SSRF-filtered.

Implemented verification

For a cross-anchor to count, its root, batch ID, home network ID, and witnessing network must link to the bundle's verified home batch. The peer signature must meet that peer's configured minimum, and the caller must supply the peer's verification configuration. Distinct verified peers must meet the home cross-anchor threshold for VerificationLevel::Federated.

Missing or unavailable peer configurations reduce the achieved level; they do not get treated as valid anchors.

Assumptions

Peer operators are independent enough to provide additional durability, their public configurations are correct, and federation credentials are rotated and protected. Federation is optional and can be disabled.

Non-goals

Federation does not provide Byzantine-fault-tolerant consensus, a global order across networks, or protection from collusion by enough witnesses or operators. It does not make peers a single consensus committee; it adds independent signed cross-anchors for a batch root.

TODO — maintainer review

Specify peer retry, timeout, and retention guarantees, and provide an operator guide for token rotation and independence of network deployments. Review the meaning of a federated result when a peer has a valid signature but incomplete external-anchor evidence.