sigil-tower · finality

Source: sigil/node/sigil-tower/src/finality.rs. SHA-256: bab1ac1f3f5ad74f8d93b95bce5090274f698ef4016b6dfb21ec1d6c558ccc63.

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.

finality::FinalityUpdate

Result of adding a finality vote.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum FinalityUpdate {
    /// No state change resulted from this vote.
    NoChange,
    /// A checkpoint was justified at the given epoch.
    Justified(u64),
    /// A checkpoint was finalized at the given epoch.
    Finalized(u64),
}

Source line: 17.

finality::FinalityState

The finality state machine tracking justification and finalization progress.

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FinalityState {
/// The most recently justified checkpoint.

pub justified_checkpoint: FinalityCheckpoint,
/// The most recently finalized checkpoint.

pub finalized_checkpoint: FinalityCheckpoint,
/// Votes for the current target epoch, keyed by voter DID.

pub votes: HashMap<String, FinalityVote>
}

Source line: 28.

finality::FinalityState::new

Create a new finality state rooted at the given genesis checkpoint.

pub fn new(genesis_checkpoint: FinalityCheckpoint) -> Self;

Source line: 43.

finality::FinalityState::add_vote

Add a finality vote and check whether it triggers justification or finalization.

Returns FinalityUpdate indicating what changed.

pub fn add_vote(
        &mut self,
        vote: FinalityVote,
        total_stake: u64,
    ) -> Result<FinalityUpdate, TowerError>;

Source line: 58.

finality::FinalityState::is_justified

Whether the given epoch has been justified.

pub fn is_justified(&self, epoch: u64) -> bool;

Source line: 136.

finality::FinalityState::is_finalized

Whether the given epoch has been finalized.

pub fn is_finalized(&self, epoch: u64) -> bool;

Source line: 141.

finality::FinalityState::required_stake_for_justification

Returns the minimum stake required for justification (2/3 of total stake).

SECURITY: Uses u128 intermediate arithmetic to prevent overflow when total_stake is large (e.g., > u64::MAX / 2). Without this, the multiplication total_stake * 2 would silently wrap, potentially allowing justification with far less than 2/3 stake -- a consensus safety violation that could enable finality attacks.

pub fn required_stake_for_justification(&self, total_stake: u64) -> u64;

Source line: 152.

finality::FinalityState::clear_votes

Clear votes for a new voting period (e.g., epoch transition).

pub fn clear_votes(&mut self);

Source line: 163.