sigil-consensus · round

Source: sigil/node/sigil-consensus/src/round.rs. SHA-256: c6e695ad63cdafbfbc838e987d55667a21aa9a104c8478e15e1371b7156df8c9.

This reference follows declared source modules, retains conditional attributes, and includes public declarations and implementation methods. Private-module re-exports and trait resolution require the compiler; this is a source reference, not a claim that every listed item is a root import. Function bodies and constant values are omitted.

round::PreVote

A pre-vote message from a validator.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PreVote {
/// DID of the voting validator.

pub validator_did: String,
/// Hash of the block being voted on.

pub block_hash: SigilHash,
/// Block height this vote applies to.

pub height: u64,
/// Consensus view this vote applies to.

pub view: u64,
/// Ed25519 signature over (block_hash || height || epoch || view || "prevote").

pub signature: Vec<u8>
}

Source line: 20.

round::PreCommit

A pre-commit message from a validator.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PreCommit {
/// DID of the committing validator.

pub validator_did: String,
/// Hash of the block being committed to.

pub block_hash: SigilHash,
/// Block height this commit applies to.

pub height: u64,
/// Consensus view this commit applies to.

pub view: u64,
/// Ed25519 signature over (block_hash || height || epoch || view || "precommit").

pub signature: Vec<u8>
}

Source line: 35.

round::ConsensusMessage

Messages exchanged during consensus rounds.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ConsensusMessage {
    /// A block proposal from the elected proposer.
    Propose {
        /// The proposed block (boxed to reduce enum size).
        block: Box<Block>,
        /// DID of the proposer.
        proposer_did: String,
        /// Round view number (increments on view change).
        view: u64,
    },
    /// A pre-vote for a proposed block.
    PreVote(PreVote),
    /// A pre-commit for a proposed block.
    PreCommit(PreCommit),
    /// A finalize notification (informational, not a vote).
    Finalize {
        /// Hash of the finalized block.
        block_hash: SigilHash,
        /// Block height.
        height: u64,
    },
}

Source line: 50.

round::ProposalValidation

Result of external proposal validation before the round may enter PreVote.

sigil-consensus is a pure state-machine crate, so it cannot re-execute blocks or read the node's state snapshot itself. The node/coordinator must validate chain ID, parent hash, proposer authority/signature, every transaction signature and chain ID, transaction/receipt roots, execution state root, non-zero roots for non-empty blocks, and gas limits before constructing Passed.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum ProposalValidation {
    /// The outer node verified the full proposal validity checklist.
    Passed,
    /// The proposal failed validation and must not receive a prevote.
    Rejected {
        /// Structured or human-readable rejection reason from the outer node.
        reason: String,
    },
}

Source line: 82.

round::ProposalValidation::passed

Convenience constructor for successful outer validation.

pub fn passed() -> Self;

Source line: 94.

round::ProposalValidation::rejected

Convenience constructor for rejected outer validation.

pub fn rejected(reason: impl Into<String>) -> Self;

Source line: 99.

round::ConsensusDecision

The final decision from a consensus round.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ConsensusDecision {
/// The finalized block.

pub block: Block,
/// Block hash.

pub block_hash: SigilHash,
/// Block height.

pub height: u64,
/// Epoch this block belongs to.

pub epoch: u64,
/// Collected pre-commits that formed quorum.

pub commits: Vec<PreCommit>
}

Source line: 117.

round::ConsensusRound

A consensus round for a specific block height.

This is the core state machine. It tracks the current phase, the proposed block, accumulated votes, and determines when thresholds are met.

pub struct ConsensusRound {
/// Block height for this round.

pub height: u64,
/// Epoch number.

pub epoch: u64,
/// Current phase of the round.

pub phase: ConsensusPhase,
/// DID of the elected proposer for this height.

pub proposer_did: String,
/// The proposed block, if one has been received.

pub proposed_block: Option<Block>,
/// Accumulated pre-votes: validator_did -> PreVote.

pub prevotes: HashMap<String, PreVote>,
/// Accumulated pre-commits: validator_did -> PreCommit.

pub precommits: HashMap<String, PreCommit>,
/// View number (increments on view changes).

pub view: u64,
/// When this round started.

pub start_time: Instant
}

Source line: 134.

round::ConsensusRound::new

Create a new consensus round for the given height.

pub fn new(height: u64, epoch: u64, proposer_did: String, validator_set: ValidatorSet) -> Self;

Source line: 159.

round::ConsensusRound::is_quorum

Returns true if the given stake amount meets or exceeds the quorum threshold.

Uses u128 intermediate to prevent overflow when total_stake > u64::MAX / 2.

pub fn is_quorum(votes_stake: u64, total_stake: u64) -> bool;

Source line: 177.

round::ConsensusRound::receive_proposal

Handle a block proposal.

Validates that:

The round is in the Propose phase
The proposal comes from the elected proposer
Basic block structure is valid (height, epoch)
The proposer's Ed25519 signature is valid

pub fn receive_proposal(
        &mut self,
        block: Block,
        proposer_did: &str,
        signature: &[u8],
        validation: ProposalValidation,
    ) -> Result<(), ConsensusError>;

Source line: 193.

round::ConsensusRound::can_prevote

Check whether we can transition to the pre-vote phase.

Returns true if:

A block has been proposed
The proposer is valid (is the elected proposer and in the validator set)

pub fn can_prevote(&self) -> bool;

Source line: 263.

round::ConsensusRound::add_prevote

Add a pre-vote from a validator.

Validates that:

The round is in the PreVote phase
The validator is in the active set
The validator has not already voted
The Ed25519 signature is valid

Returns true if quorum has been reached after adding this vote.

pub fn add_prevote(&mut self, vote: PreVote) -> Result<bool, ConsensusError>;

Source line: 280.

round::ConsensusRound::can_precommit

Check whether the pre-vote quorum has been reached and we can transition to the PreCommit phase.

pub fn can_precommit(&self) -> bool;

Source line: 338.

round::ConsensusRound::advance_to_precommit

Advance from PreVote to PreCommit phase.

Should be called once can_precommit() returns true.

pub fn advance_to_precommit(&mut self) -> Result<(), ConsensusError>;

Source line: 346.

round::ConsensusRound::add_precommit

Add a pre-commit from a validator.

Validates that:

The round is in the PreCommit phase
The validator is in the active set
The validator has not already committed
The Ed25519 signature is valid

Returns true if quorum has been reached after adding this commit.

pub fn add_precommit(&mut self, commit: PreCommit) -> Result<bool, ConsensusError>;

Source line: 382.

round::ConsensusRound::try_finalize

Attempt to finalize the round.

If 2/3+ of stake has pre-committed, produces a ConsensusDecision and transitions to the Finalize phase.

pub fn try_finalize(&mut self) -> Result<Option<ConsensusDecision>, ConsensusError>;

Source line: 442.

round::ConsensusRound::validator_set

Returns a reference to the validator set.

pub fn validator_set(&self) -> &ValidatorSet;

Source line: 499.

round::ConsensusRound::elapsed

Returns the elapsed time since the round started.

pub fn elapsed(&self) -> std::time::Duration;

Source line: 504.

sigil-consensus · round

On this page