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 (peer_manager.rs)

The data layer. Tracks every known peer in a flat HashMap<SocketAddr, PeerInfo> together with three HashSets for the cold/warm/hot buckets.

Governor (governor.rs)

The policy layer. Runs on a 30-second tokio::interval in dugite-node.

Wiring

The governor runs as a standalone tokio::spawn task in node/mod.rs. Every 30 seconds it:

1. Acquires a read lock on Arc<RwLock<PeerManager>> and calls governor.evaluate() and governor.maybe_churn().
2. Acquires a write lock and applies the resulting GovernorEvents by calling promote_to_hot, demote_to_warm, peer_disconnected, and recompute_reputations.
3. GovernorEvent::Connect is acknowledged but not executed here — outbound connections originate from the main connection loop via peers_to_connect().

Peer Selection State Machine

Peers progress through a formal state machine:

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

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>>. The governor task acquires a read lock for evaluate() and a write lock only for event application, keeping the write-lock window minimal.

Files