Module consensus 

Federated Learning Round Consensus Tracker

Production-grade consensus mechanism for federated learning rounds. A quorum of participating nodes must commit their gradient updates before a round can proceed to aggregation.

Overview

RoundConsensusTracker manages the lifecycle of federated learning rounds. Each round is identified by a RoundId (a monotonically increasing u64). Peers cast Votes, and the QuorumPolicy determines whether consensus has been reached.

Quorum Logic

A round commits when:

• At least min_peers votes have been received, AND
• The fraction of Commit votes meets commit_threshold

A round aborts when:

• It is impossible to reach the commit threshold even if all remaining expected peers vote Commit (i.e. enough Abort/Abstain votes exist), OR
• The timeout elapses

Gradient CID Collection

On commit the QuorumResult::Commit variant carries the gradient_cid values of every committing peer, ready for aggregation.

Examples

use ipfrs_tensorlogic::consensus::{
    RoundConsensusTracker, RoundId, PeerVote, Vote, QuorumPolicy, QuorumResult,
};
use std::time::Duration;

let policy = QuorumPolicy::default();
let tracker = RoundConsensusTracker::new(policy);

let round_id = RoundId::from(1_u64);
let peers = vec!["peer-a".to_string(), "peer-b".to_string(), "peer-c".to_string()];
tracker.begin_round(round_id.clone(), peers).expect("example: should succeed in docs");

for (i, peer) in ["peer-a", "peer-b", "peer-c"].iter().enumerate() {
    let vote = PeerVote::new(
        peer.to_string(),
        round_id.clone(),
        Vote::Commit,
        Some(format!("bafyreic{}", i)),
    );
    let result = tracker.cast_vote(vote).expect("example: should succeed in docs");
    if let QuorumResult::Commit { gradient_cids } = result {
        assert_eq!(gradient_cids.len(), 3);
        break;
    }
}

Structs

ConsensusStats

Atomic counters tracking aggregate consensus activity.

ConsensusStatsSnapshot

Immutable snapshot of ConsensusStats.

PeerVote

A single vote cast by a peer for a specific round.

QuorumPolicy

Policy parameters governing when a round can proceed to aggregation.

RoundConsensusTracker

Central registry for federated learning round consensus.

RoundId

Monotonically-increasing federated learning round identifier.

Enums

ConsensusError

Errors that can be returned by RoundConsensusTracker operations.

QuorumResult

Outcome of evaluating the quorum policy against the current vote set.

RoundStatus

Internal lifecycle state of a single round.

Vote

A peer’s vote for a federated learning round.