Crate tenzro_consensus 

HotStuff-2 BFT Consensus Engine for Tenzro Network

This crate implements the HotStuff-2 consensus protocol, a two-phase BFT consensus algorithm with O(n) linear communication complexity per view.

Overview

HotStuff-2 provides:

• Fast Finality: Two-phase protocol (PREPARE → COMMIT → DECIDE)
• Linear Communication: O(n) message complexity per view
• Optimistic Responsiveness: Commits in network delay time under good conditions
• TEE Integration: Validators with TEE attestation get priority in leader selection
• Robust Liveness: Automatic view changes on timeout

Architecture

The consensus engine consists of several key components:

• HotStuff2Engine: Main consensus engine implementing the protocol
• ValidatorSet: Manages the set of validators and their voting power
• EpochManager: Handles epoch transitions and validator set updates
• VoteCollector: Collects votes and forms quorum certificates
• BlockProposer: Creates block proposals with transaction selection
• Mempool: Transaction pool with priority ordering
• FinalityTracker: Tracks finalized blocks and sends notifications

Protocol Flow

1. PREPARE Phase:

   • Leader proposes a block
   • Validators vote on the proposal
   • Prepare QC formed when 2f+1 votes collected

2. COMMIT Phase:

   • Leader shares prepare QC
   • Validators vote to commit
   • Commit QC formed when 2f+1 votes collected

3. DECIDE Phase:

   • Block is finalized
   • Transactions removed from mempool
   • Advance to next height

TEE Integration

Validators with valid TEE attestation receive priority in leader selection, providing hardware-rooted trust. The leader selection algorithm gives TEE-attested validators 2x voting weight for leader selection while maintaining standard voting power for consensus.

Examples

use tenzro_consensus::{
    HotStuff2Engine, ConsensusConfig, ConsensusEngine,
    EpochManager, ValidatorInfo,
};
use tenzro_crypto::pq::MlDsaSigningKey;
use tenzro_crypto::{KeyPair, KeyType};
use tenzro_types::primitives::Address;

#[tokio::main]
async fn main() -> tenzro_consensus::Result<()> {
    // Generate validator triple keypair (Ed25519 classical + ML-DSA-65 PQ
    // + BLS12-381 for HotStuff-2 vote-signature aggregation)
    let keypair = KeyPair::generate(KeyType::Ed25519)?;
    let pq_key = MlDsaSigningKey::generate();
    let bls_key = tenzro_crypto::bls::BlsKeyPair::generate()?;

    // Convert address (tenzro_crypto::Address is 20 bytes, tenzro_types::Address is 32 bytes)
    let crypto_addr = keypair.address();
    let mut addr_bytes = [0u8; 32];
    addr_bytes[..20].copy_from_slice(crypto_addr.as_bytes());
    let address = Address::new(addr_bytes);

    // Create validators with mandatory PQ + BLS verifying keys
    let validators = vec![
        ValidatorInfo::new(
            address,
            keypair.public_key().clone(),
            pq_key.verifying_key_bytes().to_vec(),
            bls_key.public_key().to_bytes().to_vec(),
            1000,
        ),
    ];

    // Create epoch manager
    let epoch_manager = EpochManager::new(validators, 10000)?;

    // Create consensus engine
    let config = ConsensusConfig::default()
        .with_block_time(400)
        .with_view_timeout(2000);

    let mut engine = HotStuff2Engine::new(keypair, pq_key, bls_key, config, epoch_manager);

    // Start consensus
    engine.start().await?;

    // Engine now participates in consensus...

    Ok(())
}

Re-exports

pub use admission::AdmissionConfig;

pub use admission::AdmissionController;

pub use admission::AdmissionDecision;

pub use admission::BucketSnapshot;

pub use admission::DefaultLaneResolver;

pub use admission::Lane;

pub use admission::LaneResolver;

pub use admission::LaneStats;

pub use config::BftThreshold;

pub use config::ConsensusConfig;

pub use config::ProposerElectionKind;

pub use epoch_manager::Epoch;

pub use epoch_manager::EpochManager;

pub use epoch_manager::EpochStateStore;

pub use epoch_manager::EpochStats;

pub use error::ConsensusError;

pub use error::Result;

pub use finality::FinalityNotification;

pub use finality::FinalityTracker;

pub use finality::ForkChoice;

pub use hotstuff2::BlockProvider;

pub use hotstuff2::ConsensusOutMessage;

pub use hotstuff2::HotStuff2Engine;

pub use hotstuff2::Phase;

pub use hotstuff2::StateRootProvider;

pub use leader_reputation::proposer_window;

pub use leader_reputation::reputation_seed;

pub use leader_reputation::voter_window;

pub use leader_reputation::LeaderReputation;

pub use leader_reputation::ProposerHistory;

pub use leader_reputation::ProposerRecord;

pub use leader_reputation::ValidatorWeights;

pub use leader_reputation::VoterHistory;

pub use leader_reputation::VoterRecord;

pub use leader_reputation::ACTIVE_WEIGHT;

pub use leader_reputation::FAILED_WEIGHT;

pub use leader_reputation::FAILURE_THRESHOLD_PERCENT;

pub use leader_reputation::INACTIVE_WEIGHT;

pub use leader_reputation::NO_TEE_MULTIPLIER_BPS;

pub use leader_reputation::TEE_MULTIPLIER_BPS;

pub use mempool::Mempool;

pub use mempool::MempoolStats;

pub use proposer::BlockProposer;

pub use timeout::CollectOutcome;

pub use timeout::NecCollectOutcome;

pub use timeout::NecSigner;

pub use timeout::NoEndorsementCertificate;

pub use timeout::NoEndorsementCollector;

pub use timeout::NoEndorsementMsg;

pub use timeout::TcSigner;

pub use timeout::TimeoutCertificate;

pub use timeout::TimeoutCollector;

pub use timeout::TimeoutMsg;

pub use timeout::NO_ENDORSEMENT_CERTIFICATE_FORMAT_VERSION;

pub use timeout::NO_ENDORSEMENT_MSG_FORMAT_VERSION;

pub use timeout::TIMEOUT_CERTIFICATE_FORMAT_VERSION;

pub use timeout::TIMEOUT_MSG_FORMAT_VERSION;

pub use traits::ConsensusEngine;

pub use traits::ConsensusNetwork;

pub use traits::SlashingCallback;

pub use traits::StateManager;

pub use validator::EquivocationDetector;

pub use validator::EquivocationEvidence;

pub use validator::ProposerElection;

pub use validator::ReputationProposer;

pub use validator::RoundRobinProposer;

pub use validator::ValidatorInfo;

pub use validator::ValidatorSet;

pub use validator::ValidatorStatus;

pub use vote_state::open_default_file_store;

pub use vote_state::FileVoteStateStore;

pub use vote_state::LastSignState;

pub use vote_state::MemoryVoteStateStore;

pub use vote_state::VoteStateStore;

pub use vote_state::VoteStep;

pub use vote_state::VrsDecision;

pub use voter::bls_payload_for_vote;

pub use voter::QuorumCertificate;

pub use voter::Vote;

pub use voter::VoteCollector;

pub use voter::VoteType;

Modules

admission

Per-DID flow control & admission lanes (Agent-Swarm Spec 2).

config

Consensus configuration

epoch_manager

Epoch management for validator set transitions

error

Error types for the consensus module

finality

Finality tracking for consensus

hotstuff2

HotStuff-2 BFT consensus implementation

leader_reputation

Aptos-style LeaderReputation proposer election for HotStuff-2.

mempool

Transaction mempool with priority ordering.

proposer

Block proposal logic

timeout

Pacemaker timeout messages and certificates for HotStuff-2.

traits

Consensus engine trait definitions

validator

Validator set management for consensus

vote_state

Persistent vote state for double-sign protection.

voter

Vote handling and quorum certificate formation