Struct PeerPool 

pub struct PeerPool { /* private fields */ }

Implementations

impl PeerPool

pub async fn new( network: NetworkType, tls: Connector, max_peers: usize, requirement: PeerRequirement, connect_timeout: Duration, ) -> Result<Self, ChiaQueryError>

Spin up the pool by connecting to max_peers random full-node peers concurrently. Under PeerRequirement::Required at least one peer must succeed, otherwise we return ChiaQueryError::PeerDiscoveryFailed; under PeerRequirement::Optional an empty pool is returned and refills later.

pub fn peak_height(&self) -> u32

Latest peak height observed across all connected peers. Returns 0 if no peak has been received yet.

pub async fn select_peer(&self) -> Option<(Peer, SocketAddr)>

Round-robin select a peer from the pool. Returns None when the pool is empty.

pub async fn select_corroborating_peers( &self, asked: SocketAddr, ) -> Vec<(Peer, SocketAddr)>

Every peer that could CORROBORATE an answer already given by the peer at asked.

A corroborating peer must be two things at once, and neither alone is enough:

• A different address than asked. Asking the same connection twice returns the same opinion twice, which reads as agreement while being one voice.
• PeerOrigin::Discovered. A peer reached from a preferred address — an operator’s node, or one on this machine — is an excellent peer to READ from and is not evidence about the chain independent of this host, exactly as independent_peer_count records.

They are returned ALL AT ONCE, and there is deliberately no singular form of this. Asking corroborators one at a time lets the first responder settle a claim about the chain, which is exactly the power a hostile peer has (dig_ecosystem#2462) — and a single corroborator cannot reach CORROBORATION_FLOOR at all, so a caller that took one would be building an answer it is not allowed to report as corroborated.

Returns an empty vector when the pool holds nobody who qualifies, which is the honest answer that there is nobody to corroborate with.

pub async fn eject_peer(&self, addr: SocketAddr)

Remove a peer from the pool and asynchronously connect a replacement.

pub async fn has_peers(&self) -> bool

Whether the pool has at least one usable peer.

pub async fn peer_count(&self) -> usize

How many peers the pool HOLDS right now.

This is a live count of the connections currently in the pool, not max_peers’s target: a pool that is still filling reports what it has, and reports the target only once it has reached it. A caller showing this number to a user is stating a fact about the machine, so a configured intention must never stand in for it.

A peer is removed by eject_peer, which runs when a request to it FAILS. So the count is of peers held and believed usable; a connection that has died silently is still counted until something tries to use it. That is the same liveness standard has_peers has always answered by, made countable.

pub async fn independent_peer_count(&self) -> usize

How many peers the pool holds that are INDEPENDENT opinions.

peer_count answers “how many connections do I have”; this answers “how many of them could corroborate each other”. They differ by the peers reached from a preferred address — an operator’s trusted node or one on this machine — which are excellent peers to READ from and are not evidence about the chain independent of this host. A caller deciding whether enough separate sources agree MUST use this number, because counting a co-resident node as an independent voice is the thing that made a single local process able to look like a full peer set (dig_ecosystem#2648).

pub async fn corroboration_readiness( &self, asked: SocketAddr, ) -> CorroborationReadiness

Whether the pool can honestly attempt a CORROBORATED read of an answer given by asked.

The count is of the peers that WILL be asked to corroborate — precisely the set select_corroborating_peers returns for the same address, because both use is_corroborator to decide the set.

It takes the answering address rather than subtracting one blindly. An earlier version charged the asker’s slot against the independent set whatever the asker was, so a read from the operator’s own node — which is not in that set at all — silently spent an independent voice it had never occupied. On the host this crate is sized for, two genuinely independent peers agreeing with a co-resident node were downgraded to Uncorroborated* and pushed on to the centralized coinset tier, which is the opposite of what NC-12 asks for.

This refuses; it never degrades. Corroborating against however many peers happen to be present turns a four-voice quorum into a two-voice one that still reports itself corroborated, and no consumer downstream can tell those apart. A caller handed CorroborationReadiness::Insufficient must decline the read, not proceed with fewer voices.

pub async fn cycle_expired_peers(&self) -> Option<SocketAddr>

Rotate out the OLDEST discovered peer that has outlived PEER_LIFETIME, if any.

Returns the address ejected, so a caller can log or refill deliberately. This is NC-12’s cycling half and it is driven by AGE alone: a peer that has answered every request is exactly the peer this removes, because a set that never fails is a set an attacker only has to capture once. The pool’s other eviction, eject_peer, fires on request FAILURE and cannot substitute for this — a captured peer does not fail.

Only PeerOrigin::Discovered entries are rotated. A priority entry is the operator’s own node or one on this machine; cycling it would re-dial the same address, spending a handshake to change nothing.

One per call, so cycling can never empty the pool in a single sweep.

pub async fn maintain(&self)

One maintenance pass: rotate out an over-age peer, then refill toward capacity.

Cycling before refilling is deliberate. Refilling first would find the pool at capacity and do nothing, so the rotation would leave a permanently smaller pool.

pub async fn try_refill(&self)

If the pool is under capacity, try to connect one new peer. Also spawns a background task to handle its inbound NewPeakWallet messages.

pub async fn subscribe_frames(&self, capacity: usize) -> FrameSubscription

Subscribe to this pool’s frames, with room for capacity unread ones.

Falling further behind than capacity ENDS the subscription — see FrameSubscription for why a gap is not an option.