Struct PeerConsensus 

pub struct PeerConsensus {
    pub config: ConsensusConfig,
}

Peer consensus manager

Fields

config: ConsensusConfig

Implementations

impl PeerConsensus

pub fn new(config: ConsensusConfig) -> Self

Create a new peer consensus manager

pub fn discover_diverse_peers(&self, all_peers: Vec<PeerInfo>) -> Vec<PeerInfo>

Discover diverse peers

Filters peers to ensure diversity across:

• ASNs (max N per ASN)
• Subnets (/16 for IPv4, /32 for IPv6)
• Geographic regions
• Bitcoin implementations

pub fn determine_checkpoint_height(&self, peer_tips: Vec<Natural>) -> Natural

Determine checkpoint height based on peer chain tips

Uses median of peer tips minus safety margin to prevent deep reorgs.

Mathematical invariants:

• Median is always between min(tips) and max(tips)
• Checkpoint height is always >= 0
• Checkpoint height <= median_tip

pub async fn request_utxo_sets<C: UtxoCommitmentsNetworkClient>( &self, network_client: &C, peers: &[(PeerInfo, String)], checkpoint_height: Natural, checkpoint_hash: Hash, ) -> Vec<PeerCommitment>

Request UTXO sets from multiple peers

Sends GetUTXOSet messages via the provided network client and collects responses. Returns list of peer commitments (peer + commitment pairs).

The caller provides a list of (PeerInfo, peer_id) tuples where peer_id is an opaque identifier understood only by the node’s networking layer. This keeps the consensus layer agnostic of concrete transport types or peer address formats.

pub fn find_consensus( &self, peer_commitments: Vec<PeerCommitment>, ) -> UtxoCommitmentResult<ConsensusResult>

Find consensus among peer responses

Groups commitments by their values and finds the majority consensus. Returns the consensus commitment if threshold is met.

pub fn verify_consensus_commitment( &self, consensus: &ConsensusResult, header_chain: &[BlockHeader], ) -> UtxoCommitmentResult<bool>

Verify consensus commitment against block headers

Verifies that:

1. Block header chain is valid (PoW verification)
2. Commitment supply matches expected supply at height
3. Commitment block hash matches actual block hash

pub fn verify_utxo_proofs( &self, consensus: &ConsensusResult, utxos_to_verify: Vec<(OutPoint, UTXO, MerkleProof)>, ) -> UtxoCommitmentResult<bool>

Verify UTXO proofs for critical UTXOs after consensus verification

This function should be called after verify_consensus_commitment() succeeds to cryptographically verify that specific UTXOs exist in the consensus commitment.

This prevents coin freezing attacks where malicious peers provide commitments with correct total supply but missing/modified individual UTXOs.

Arguments

• consensus - The verified consensus commitment
• utxos_to_verify - Vector of (outpoint, expected_utxo, proof) tuples to verify

Returns

Ok(true) if all proofs are valid, Err if any verification fails

Example

use blvm_protocol::utxo_commitments::{UtxoMerkleTree, peer_consensus::PeerConsensus};

// After verify_consensus_commitment succeeds:
let utxos_to_verify = vec![
    (outpoint1, utxo1, proof1),
    (outpoint2, utxo2, proof2),
];

peer_consensus.verify_utxo_proofs(&consensus, utxos_to_verify)?;

pub fn verify_utxo_proofs_parallel( &self, consensus: &ConsensusResult, utxos_to_verify: Vec<(OutPoint, UTXO, MerkleProof)>, ) -> UtxoCommitmentResult<bool>

Verify UTXO proofs in parallel (optimized for batch verification)

This function performs parallel verification of multiple UTXO proofs, which is more efficient when verifying many UTXOs at once.

Arguments

• consensus - The verified consensus commitment
• utxos_to_verify - Vector of (outpoint, expected_utxo, proof) tuples to verify

Returns

Ok(true) if all proofs are valid, Err if any verification fails

Performance

Uses parallel processing for better performance when verifying many proofs. For small batches (< 10), sequential verification may be faster due to overhead.

pub fn verify_utxo_proofs_parallel_fallback( &self, consensus: &ConsensusResult, utxos_to_verify: Vec<(OutPoint, UTXO, MerkleProof)>, ) -> UtxoCommitmentResult<bool>

Verify UTXO proofs in parallel (fallback for when rayon is not available)

Falls back to sequential verification if parallel feature is not enabled.