Epochs and Checkpoints

Sui uses a dual-layer finalization system: checkpoints provide fast, frequent state commitments, while epochs organize longer time periods for validator set changes and protocol upgrades.

Checkpoints

Checkpoints are Sui’s primary finalization mechanism, providing certified snapshots of the blockchain state at regular intervals.

Purpose of Checkpoints

Checkpoints serve multiple critical functions:

State Finalization: Provide cryptographic commitments to executed transactions
Fast Synchronization: Enable new validators and full nodes to catch up efficiently
Light Clients: Support verification without executing all transactions
Archival: Create immutable historical records for auditing and replay

Checkpoint Structure

// From sui-types/src/messages_checkpoint.rs
pub struct CheckpointSummary {
    epoch: EpochId,
    sequence_number: CheckpointSequenceNumber,
    network_total_transactions: u64,
    content_digest: CheckpointContentsDigest,
    previous_digest: Option<CheckpointDigest>,
    epoch_rolling_gas_cost_summary: GasCostSummary,
    timestamp_ms: CheckpointTimestamp,
    // Commitment to all live objects
    checkpoint_commitments: Vec<CheckpointCommitment>,
    // ...
}

Checkpoint Contents

Each checkpoint includes all transactions finalized since the previous checkpoint:

pub struct CheckpointContents {
    transactions: Vec<ExecutionDigests>,
}

pub struct ExecutionDigests {
    transaction: TransactionDigest,
    effects: TransactionEffectsDigest,
}

Checkpoint contents are stored separately from the summary, allowing efficient summary-only verification for light clients.

Checkpoint Creation Process

Building Checkpoints

Validators continuously build checkpoints from executed transactions:

Checkpoint Builder

The CheckpointBuilder orchestrates checkpoint creation:

// From crates/sui-core/src/checkpoints/mod.rs
pub struct PendingCheckpoint {
    roots: Vec<TransactionKey>,
    details: PendingCheckpointInfo,
}

pub struct PendingCheckpointInfo {
    timestamp_ms: CheckpointTimestamp,
    last_of_epoch: bool,
    checkpoint_height: CheckpointHeight,
    consensus_commit_ref: CommitRef,
    // ...
}

Building steps:

Transaction Execution: Execute consensus-ordered transactions
Content Collection: Gather transaction and effects digests
State Commitment: Compute accumulator root over live objects
Summary Creation: Build checkpoint summary with metadata
Signing: Sign summary with validator’s key

Checkpoint Signature Aggregation

Validators submit their checkpoint signatures to consensus:

// From crates/sui-core/src/checkpoints/checkpoint_output.rs
impl CheckpointOutput for SubmitCheckpointToConsensus {
    async fn checkpoint_created(
        &self,
        summary: &CheckpointSummary,
        contents: &CheckpointContents,
        epoch_store: &Arc<AuthorityPerEpochStore>,
        checkpoint_store: &Arc<CheckpointStore>,
    ) -> SuiResult {
        // Sign the checkpoint
        let summary = SignedCheckpointSummary::new(
            epoch_store.epoch(),
            summary.clone(),
            &*self.signer,
            self.authority,
        );
        
        // Submit signature to consensus
        let transaction = ConsensusTransaction::new_checkpoint_signature_message(summary);
        self.sender.submit_to_consensus(&[transaction], epoch_store)?;
        // ...
    }
}

Signature collection:

Validators create and sign checkpoint summaries locally
Signatures are submitted as consensus transactions
Validators collect signatures from consensus output
Once 2f+1 stake worth of signatures are collected, checkpoint is certified

Certified Checkpoints

A checkpoint becomes certified when it has a quorum of validator signatures:

pub struct CertifiedCheckpointSummary {
    summary: CheckpointSummary,
    auth_sig: AuthorityStrongQuorumSignInfo,
}

Certification guarantees:

Immutability: Checkpoint contents cannot be changed
Finality: All included transactions are permanently ordered
Network Agreement: A quorum of validators agree on the state

Certified checkpoints are stored in the CheckpointStore at crates/sui-core/src/checkpoints/mod.rs:156-200.

Checkpoint Storage

The CheckpointStore maintains checkpoint data:

// From crates/sui-core/src/checkpoints/mod.rs
pub struct CheckpointStoreTables {
    // Maps checkpoint contents digest to checkpoint contents
    checkpoint_content: DBMap<CheckpointContentsDigest, CheckpointContents>,
    
    // Stores certified checkpoints by sequence number
    certified_checkpoints: DBMap<CheckpointSequenceNumber, TrustedCheckpoint>,
    
    // Maps checkpoint digest to certified checkpoint
    checkpoint_by_digest: DBMap<CheckpointDigest, TrustedCheckpoint>,
    
    // Maps epoch ID to last checkpoint in that epoch
    epoch_last_checkpoint_map: DBMap<EpochId, CheckpointSequenceNumber>,
    
    // Watermarks for checkpoint progress
    watermarks: DBMap<CheckpointWatermark, (CheckpointSequenceNumber, CheckpointDigest)>,
    // ...
}

Checkpoint Watermarks

Watermarks track checkpoint processing progress:

Highest Verified: Latest checkpoint with verified signatures
Highest Synced: Latest checkpoint with downloaded contents
Highest Executed: Latest checkpoint with executed transactions

Full Checkpoint Contents

For state synchronization, full checkpoint contents include:

pub struct FullCheckpointContents {
    transactions: Vec<TransactionEffects>,
    user_signatures: Vec<Vec<GenericSignature>>,
}

This enables validators to:

Download complete checkpoint data
Verify all transactions and effects
Apply state changes without re-execution

Epochs

Epochs are fixed-duration periods that organize validator set changes and protocol upgrades.

Epoch Structure

// From sui-types/src/epoch_data.rs
pub struct EpochData {
    epoch_id: EpochId,
    epoch_start_timestamp: CheckpointTimestamp,
    epoch_digest: CheckpointDigest,
}

Each epoch has:

Epoch ID: Sequential number starting from 0 (genesis)
Start Timestamp: Wall clock time when epoch began
Epoch Digest: Digest of the last checkpoint from previous epoch
Duration: Typically 24 hours (configurable)

Epoch Lifecycle

Epoch Start

At the beginning of each epoch:

Load System State: Read epoch start configuration from previous epoch’s final checkpoint
Initialize Committee: Create committee from validator set
Configure Protocol: Load protocol version and parameters
Start Consensus: Initialize consensus with new committee
Open for Transactions: Begin accepting user transactions

// From crates/sui-core/src/authority/epoch_start_configuration.rs
pub struct EpochStartConfiguration {
    system_state: EpochStartSystemState,
    epoch_digest: CheckpointDigest,
    flags: Vec<EpochFlag>,
}

Epoch Operation

During normal epoch operation:

Validators process transactions through consensus
Checkpoints are created every few seconds
Staking operations are recorded but not applied
Protocol operates under consistent rules

Epoch End

As the epoch approaches its end (based on timestamp):

Close User Transactions: Stop accepting new user-submitted transactions
Process Remaining: Complete all in-flight consensus transactions
Build Final Checkpoint: Create the last checkpoint of the epoch
Safe Mode Check: Determine if epoch should enter safe mode
Execute Epoch Change: Run system transaction to transition to next epoch

Epoch changes are triggered by timestamp rather than checkpoint number, ensuring predictable epoch durations.

End-of-Epoch Data

The final checkpoint of an epoch includes special end-of-epoch data:

pub struct EndOfEpochData {
    // Validators for the next epoch
    next_epoch_committee: Vec<(AuthorityName, StakeUnit)>,
    
    // Protocol version for next epoch
    next_epoch_protocol_version: ProtocolVersion,
    
    // Epoch change transaction effects
    epoch_commitments: Vec<CheckpointCommitment>,
}

Epoch Statistics

Epochs accumulate statistics during their lifetime:

// From crates/sui-core/src/checkpoints/mod.rs
pub struct EpochStats {
    pub checkpoint_count: u64,
    pub transaction_count: u64,
    pub total_gas_reward: u64,
}

Tracked metrics:

Total checkpoints created
Total transactions processed
Total gas fees collected
Stake rewards distributed

State Synchronization

Checkpoints enable efficient state synchronization for validators and full nodes.

Checkpoint Execution

The CheckpointExecutor applies checkpoints to build state:

// From crates/sui-core/src/checkpoints/checkpoint_executor
pub struct CheckpointExecutor {
    checkpoint_store: Arc<CheckpointStore>,
    execution_cache: Arc<dyn ExecutionCacheWrite>,
    state: Arc<AuthorityState>,
    // ...
}

Execution process:

Download Checkpoint: Fetch certified checkpoint and full contents
Verify Signature: Validate quorum signatures on summary
Execute Transactions: Apply transaction effects to state
Update Accumulator: Recompute state commitments
Advance Watermark: Mark checkpoint as executed

State Sync Protocol

Validators synchronize through the state sync network:

Checkpoint Pruning

Older checkpoint data can be pruned to save storage:

Full Contents: Pruned after state is executed (configurable retention)
Summaries: Retained indefinitely (small size)
Watermarks: Track what can be safely pruned

Pruning configuration is managed by AuthorityStorePruner and PrunerWatermarks.

Checkpoint Height

Checkpoint height represents the consensus round that produced the checkpoint:

pub type CheckpointHeight = u64;

pub struct PendingCheckpointInfo {
    checkpoint_height: CheckpointHeight,
    consensus_commit_ref: CommitRef,
    // ...
}

Checkpoint height:

Derived from consensus commit round
May not be strictly monotonic (due to checkpoint splitting)
Used for consensus coordination

Fork Detection

Checkpoints enable detection of forks and inconsistencies:

// From crates/sui-core/src/checkpoints/mod.rs
pub struct CheckpointStoreTables {
    // Stores local checkpoint computations for fork detection
    locally_computed_checkpoints: DBMap<CheckpointSequenceNumber, CheckpointSummary>,
    
    // Stores transaction fork detection information
    transaction_fork_detected: DBMap<u8, (TransactionDigest, TransactionEffectsDigest, TransactionEffectsDigest)>,
}

Fork detection:

Validators compute checkpoint summaries locally
Compare local summary with certified summary
If mismatch detected, log fork information
Store evidence for investigation

Performance Considerations

Checkpoint Frequency

Checkpoints are created approximately every:

2-3 seconds during normal operation
Determined by consensus commit rate
Configurable through protocol parameters

Checkpoint Size

Checkpoint size varies based on transaction throughput:

Summary: ~500 bytes (fixed)
Contents: ~100 bytes per transaction
Full Contents: ~1-5 KB per transaction (includes effects)

State Sync Performance

Checkpoint-based state sync achieves:

Download Rate: Limited by network bandwidth
Execution Rate: Limited by database write speed
Catch-up Time: Typically minutes to hours depending on lag

Key Implementation Files

Checkpoint Types: crates/sui-types/src/messages_checkpoint.rs
Checkpoint Store: crates/sui-core/src/checkpoints/mod.rs
Checkpoint Builder: crates/sui-core/src/checkpoints/checkpoint_output.rs
Checkpoint Executor: crates/sui-core/src/checkpoints/checkpoint_executor/
Epoch Data: crates/sui-types/src/epoch_data.rs
Epoch Store: crates/sui-core/src/authority/authority_per_epoch_store.rs
Committee Store: crates/sui-core/src/epoch/committee_store.rs

Architecture

Objects & Ownership

Transactions

Move Language

Tokenomics

Epochs and Checkpoints

Checkpoints

Purpose of Checkpoints

Checkpoint Structure

Checkpoint Contents

Checkpoint Creation Process

Building Checkpoints

Checkpoint Builder

Checkpoint Signature Aggregation

Certified Checkpoints

Checkpoint Storage

Checkpoint Watermarks

Full Checkpoint Contents

Epochs

Epoch Structure

Epoch Lifecycle

Epoch Start

Epoch Operation

Epoch End

End-of-Epoch Data

Epoch Statistics

State Synchronization

Checkpoint Execution

State Sync Protocol

Checkpoint Pruning

Checkpoint Height

Fork Detection

Performance Considerations

Checkpoint Frequency

Checkpoint Size

State Sync Performance

Key Implementation Files

Build docs developers (and LLMs) love

Architecture

Objects & Ownership

Transactions

Move Language

Tokenomics

Documentation Index

​Checkpoints

​Purpose of Checkpoints

​Checkpoint Structure

​Checkpoint Contents

​Checkpoint Creation Process

​Building Checkpoints

​Checkpoint Builder

​Checkpoint Signature Aggregation

​Certified Checkpoints

​Checkpoint Storage

​Checkpoint Watermarks

​Full Checkpoint Contents

​Epochs

​Epoch Structure

​Epoch Lifecycle

​Epoch Start

​Epoch Operation

​Epoch End

​End-of-Epoch Data

​Epoch Statistics

​State Synchronization

​Checkpoint Execution

​State Sync Protocol

​Checkpoint Pruning

​Checkpoint Height

​Fork Detection

​Performance Considerations

​Checkpoint Frequency

​Checkpoint Size

​State Sync Performance

​Key Implementation Files

​Related Topics

Build docs developers (and LLMs) love

Checkpoints

Purpose of Checkpoints

Checkpoint Structure

Checkpoint Contents

Checkpoint Creation Process

Building Checkpoints

Checkpoint Builder

Checkpoint Signature Aggregation

Certified Checkpoints

Checkpoint Storage

Checkpoint Watermarks

Full Checkpoint Contents

Epochs

Epoch Structure

Epoch Lifecycle

Epoch Start

Epoch Operation

Epoch End

End-of-Epoch Data

Epoch Statistics

State Synchronization

Checkpoint Execution

State Sync Protocol

Checkpoint Pruning

Checkpoint Height

Fork Detection

Performance Considerations

Checkpoint Frequency

Checkpoint Size

State Sync Performance

Key Implementation Files

Related Topics