P2P Governor

This document describes Dugite's peer management architecture, implementing the Ouroboros P2P peer selection governor.

Architecture

Two modules implement peer management in dugite-network:

PeerManager (manager.rs)

The data layer. Tracks every known peer in a HashMap<SocketAddr, PeerInfo> keyed by socket address, with PeerInfo.state holding each peer's temperature.

Governor (governor.rs)

The policy layer. Its decision function is called on a 2-second tokio::interval in dugite-node; churn timers (below) run on their own, much longer independent cadences checked on every tick.

Wiring

The governor runs inline in the main select! loop in node/mod.rs — not as a separate spawned task. Every 2 seconds (governor_ticker) it:

1. Acquires a read lock on Arc<RwLock<PeerManager>>, snapshots local-root groups, the big-ledger-peer set, and the peer currently holding the BlockFetch fetch slot (so the governor never demotes the peer actively downloading blocks), then calls governor.compute_actions_with_blp(...), which returns a Vec<GovernorAction>. Churn decisions are folded into this same call — there is no separate churn step.
2. GovernorAction::PromoteToWarm(addr) is dispatched via a background tokio::spawn (through lifecycle.spawn_connect(...)) so a slow TCP connect never blocks the block-processing side of the same select! loop.
3. All other actions (PromoteToHot, DemoteToWarm, DemoteToCold, ForgetPeer, PeerShareRequest, DiscoverMore) are fast, O(1) operations applied inline under a write lock on the same tick.

Peer Selection State Machine

Peers progress through a formal state machine (PeerState, mirroring Haskell's PeerStatus):

stateDiagram-v2
    [*] --> Cold
    Cold --> Warm: TCP connect + handshake
    Warm --> Hot: Activate mini-protocols
    Hot --> Warm: Deactivate mini-protocols
    Warm --> Cold: Disconnect
    Hot --> Cooling: Forceful disconnect
    Cooling --> Cold: Cooldown elapsed

Cooling sits between Hot/Warm and Cold — a peer whose connection is being torn down but hasn't fully released yet (the outbound-governor reflection of the connection manager's TerminatingState, dugite's analogue of TCP TIME_WAIT). It is not eligible for re-promotion until it reaches Cold.

Target Counts

The governor maintains six independent target counts:

When any target is not met, the governor attempts to satisfy the deficit. When any target is exceeded, surplus peers are demoted by lowest reputation.

Local Root Peer Pinning

Local root peers (from localRoots in the topology file) have pinned targets that override the normal target counts. Local roots are never demoted for surplus reduction and are never churned.

Churn

The governor performs periodic churn to rotate peers:

• Deadline churn (normal mode) — Approximately every 55 minutes, a fraction of established and active peers are replaced.
• Bulk sync churn — During active block download, churn cycles are more aggressive (~15 minutes) to shed peers with poor block-fetch performance.

Big Ledger Peer Preference During Sync

Big ledger peers (SPOs in the top 90% of stake, obtained via GetLedgerPeerSnapshot) serve as trusted anchors during bulk block download. The governor maintains a separate target bucket for BLPs. When SyncState is Syncing or PreSyncing, BLP targets take priority.

Thread Safety

The PeerManager is wrapped in Arc<RwLock<PeerManager>>. Each governor tick acquires a read lock to snapshot peer state and compute GovernorActions, then a separate write lock only to apply the fast, inline actions (background connects are dispatched as their own tasks and never hold the lock), keeping the write-lock window minimal.

Files