Joining a Federation

A federation is a set of nodes that run consensus together, producing attested roots at regular intervals. Joining an existing federation requires exchanging public keys with current members and configuring peer addresses.

Configuring Peers

Pass the --federation-peers flag with comma-separated addresses of existing federation members:

dregg-node run \
  --federation-peers "node1.fed.example:8420,node2.fed.example:8420,node3.fed.example:8420"

Key Exchange (Constitutional Consensus)

Share your node's public key (printed during dregg-node init) with existing federation members. Under Constitutional Consensus, your node is admitted when h existing members reference your join-request block in the Blocklace (typically h = 2f+1). No separate "epoch reconfiguration" step is needed -- membership changes take effect as soon as the Blocklace records sufficient support.

Initial Sync (Fast-Sync)

On first connection, the node does not replay the full Blocklace history. Instead, it fetches the latest ledger checkpoint from a peer (checkpoint serving API), verifies it against a known trust anchor, and resumes participation from the checkpoint height. This takes seconds, not hours.

After checkpoint sync, the node receives new Blocklace blocks via cordial dissemination (reactive push with frontier exchange).

Blocklace + Cordial Miners

Production federations run Blocklace consensus with Cordial Miners for total ordering:

dregg-node run \
  --node-index 2 \
  --federation-peers "node1:8420,node2:8420,node3:8420"

Cordial Miners provides 3-round BFT finality, tolerating up to f = (n-1)/3 Byzantine faults. The protocol is quiescent -- no messages when idle. A single-node federation (n=1) uses the same code path with a trivial committee. See Consensus Architecture for details.

Persistence

Nodes persist all state to redb (ACID, WAL, crash-safe). On restart:

• Blocklace blocks are restored from the incremental store
• Ledger state is restored from the latest checkpoint (every 100 blocks)
• The node resumes Cordial Miners participation at its last known round

Membership Changes

Constitutional Consensus handles membership continuously:

• Joining: Produce a join-request block. Admitted when h members reference it.
• Leaving: Stop producing blocks. Timeout-leave removes inactive nodes automatically.
• Eviction: Equivocating nodes are detected structurally in the Blocklace and removed.

Peer discovery currently bootstraps from the static peer list passed via --peer. Gossip-based discovery and multi-federation routing tables follow the federation architecture sketched in docs/protocol-sketch.md; the operator-facing knobs for those paths land with the relay-marketplace work, not in this guide.