Struct Consensus 

pub struct Consensus<V: ValuePayload + 'static, A: ValidatorAddress + 'static, P: ProposerSelector<A> + Send + Sync + 'static> { /* private fields */ }

Pathfinder consensus engine

This is the main consensus engine for Starknet nodes that implements Byzantine Fault Tolerant (BFT) consensus using the Malachite implementation of Tendermint. It’s generic over validator addresses, consensus values, and proposer selection algorithms, making it suitable for Starknet’s consensus requirements.

Generic Parameters

• V: Your consensus value type (must implement ValuePayload)
• A: Your validator address type (must implement ValidatorAddress)
• P: Your proposer selector type (must implement ProposerSelector<A>)

Usage

let config = Config::new(my_address);
let mut consensus = Consensus::new(config);

// Start consensus at a height
consensus.handle_command(ConsensusCommand::StartHeight(height, validator_set));

// Poll for events
while let Some(event) = consensus.next_event().await {
    // Handle events
}

Custom Proposer Selection

To use a custom proposer selector:

let config = Config::new(my_address);
let custom_selector = WeightedProposerSelector;
let mut consensus = Consensus::new(config).with_proposer_selector(custom_selector);

Crash Recovery

The consensus engine supports crash recovery through write-ahead logging:

let validator_sets = Arc::new(StaticValidatorSetProvider::new(validator_set));
let mut consensus = Consensus::recover(config, validator_sets)?;

Implementations

impl<V: ValuePayload + 'static, A: ValidatorAddress + 'static, P: ProposerSelector<A> + Send + Sync + 'static> Consensus<V, A, P>

pub fn new(config: Config<A>) -> DefaultConsensus<V, A>

Create a new consensus engine for the current validator.

Arguments

• config: The consensus configuration containing validator address, timeouts, and other settings

Example

let config = Config::new(my_address);
let mut consensus = Consensus::new(config);

pub fn with_proposer_selector<PS: ProposerSelector<A> + Send + Sync + 'static>( self, proposer_selector: PS, ) -> Consensus<V, A, PS>

Set the proposer selector for this consensus engine.

This method consumes self and returns a new Consensus instance with the specified proposer selector.

Arguments

• proposer_selector: The proposer selection algorithm to use

Example

let config = Config::new(my_address);
let custom_selector = WeightedProposerSelector;
let mut consensus = Consensus::new(config).with_proposer_selector(custom_selector);

pub fn recover<VS: ValidatorSetProvider<A> + 'static>( config: Config<A>, validator_sets: Arc<VS>, ) -> Result<DefaultConsensus<V, A>>

Recover recent heights from the write-ahead log.

This method is used to recover consensus state after a crash or restart. It reads the write-ahead log and reconstructs the consensus state for all incomplete heights.

Arguments

• config: The consensus configuration
• validator_sets: A provider for validator sets at different heights

Example

let validator_sets = Arc::new(StaticValidatorSetProvider::new(validator_set));
let mut consensus = Consensus::recover(config, validator_sets)?;

pub fn handle_command(&mut self, cmd: ConsensusCommand<V, A>)

Feed a command into the consensus engine.

This method is the primary way to interact with the consensus engine. Commands include starting new heights, submitting proposals, and processing votes.

Arguments

• cmd: The command to process

Example

// Start a new height
consensus.handle_command(ConsensusCommand::StartHeight(height, validator_set));

// Submit a proposal
consensus.handle_command(ConsensusCommand::Proposal(signed_proposal));

// Process a vote
consensus.handle_command(ConsensusCommand::Vote(signed_vote));

pub async fn next_event(&mut self) -> Option<ConsensusEvent<V, A>>

Poll all engines for an event.

This method should be called regularly to process events from the consensus engine. Events include requests for proposals, decisions, gossip messages, and errors.

Returns

Returns Some(event) if an event is available, or None if no events are ready.

Example

while let Some(event) = consensus.next_event().await {
    match event {
        ConsensusEvent::RequestProposal { height, round } => {
            // Build and submit a proposal
        }
        ConsensusEvent::Decision { height, value } => {
            // Consensus reached, process the value
        }
        ConsensusEvent::Gossip(message) => {
            // Send message to peers
        }
        ConsensusEvent::Error(error) => {
            // Handle error
        }
    }
}

pub fn is_height_finalized(&self, height: u64) -> bool

Check if a specific height has been finalized (i.e., a decision has been reached)

Arguments

• height: The height to check

Returns

Returns true if the height has been finalized, false otherwise.

Example

if consensus.is_height_finalized(height) {
    println!("Height {} has been finalized", height);
}

pub fn current_height(&self) -> Option<u64>

Get the current maximum height being tracked by the consensus engine.