checkpoint.rs

Overview

This file defines the Checkpoint struct and its associated functionality. The Checkpoint represents a snapshot in the blockchain or distributed ledger state progression, encapsulating an optional block and the optimistic state of the system after applying that block. It manages the application of new blocks to transition the system state forward, ensuring that blocks have been signature-verified before processing. The file emphasizes minimizing expensive clone operations on the state by employing ownership moves instead.

The file integrates multiple core components such as cryptographic envelopes (Envelope), block data (AckiNackiBlock), and an optimistic state implementation (OptimisticStateImpl). It also interacts with shared services and various repositories to persist and manage blockchain-related data.

Structs and Fields

Checkpoint

The central data structure in this file. It is marked with TypedBuilder and Getters for ergonomic construction and access.

• block: Option<Envelope<GoshBLS, AckiNackiBlock>>
  Optionally holds the block wrapped in a cryptographic envelope. The envelope verifies the block’s signature using the GoshBLS scheme. This field is optional and can be stripped during builder creation.

• state_after_block_applied: Arc
  An atomic reference-counted pointer to the optimistic state of the blockchain after applying the current block. This state contains the ledger and execution context and is shared immutably.

• shared_services: SharedServices
  Encapsulates services shared across the system, such as reference data service. Marked to skip getter generation, indicating restricted external access.

• block_state_repository: BlockStateRepository
  Repository interface for persisting and querying block states.

• accounts_repository: AccountsRepository
  Repository managing account state data.

• message_db: MessageDurableStorage
  Durable storage for messages related to the blockchain's operation.

• nack_set_cache: Arc<Mutex<FixedSizeHashSet>>
  A thread-safe, fixed-size cache to store identifiers of negatively acknowledged blocks (NACKs). This field is marked for removal in the future.

Methods

apply(self, next_block: Envelope<GoshBLS, AckiNackiBlock>) -> anyhow::Result<Self>

Purpose:
Applies a new block to the current checkpoint state, producing a new checkpoint with an updated state after the block is applied.

Parameters:

• next_block — A cryptographically verified block wrapped in an Envelope. This block must have passed signature verification before application.

Returns:

• Result<Self> — On success, returns a new Checkpoint instance reflecting the updated state. On failure, returns an error wrapped in anyhow::Result.

Usage:
The method consumes the current checkpoint instance (taking ownership), applies the given block to its optimistic state, updates cross-thread reference data via shared services, and returns a new checkpoint encapsulating the updated state.

let current_checkpoint: Checkpoint = ...;
let new_block: Envelope<GoshBLS, AckiNackiBlock> = ...;

match current_checkpoint.apply(new_block) {
    Ok(updated_checkpoint) => {
        // Proceed with the updated checkpoint
    }
    Err(e) => {
        // Handle failure, possibly triggering NACK and slashing
    }
}

Implementation Details:

• The method destructures the current Checkpoint instance to extract owned fields.

• It calls state.apply_block, passing the block's data and several repositories and caches, which returns cross-thread reference data and added messages.

• Using shared_services.exec, it updates the cross-thread reference data service.

• The design avoids cloning the state, which is costly, by using ownership moves.

• The method assumes that all blocks have already been signature-verified externally; failure in application leads to NACK and potential slashing.

Important Implementation Notes

• Optimistic State Cloning Avoidance:
  The checkpoint state is wrapped in an Arc to enable efficient sharing, but cloning the underlying state is expensive. The apply method takes ownership of the checkpoint and moves the state, avoiding unnecessary cloning.

• Signature Verification Assumption:
  The system relies on blocks being verified for signatures before applying them. This contract is vital to avoid incorrect state transitions and to enforce slashing on invalid blocks.

• Cross-Thread Reference Data Management:
  After applying a block, cross-thread reference data generated during the state update is set into a dedicated service via shared_services. This mechanism facilitates coordination between different execution threads or components.

• Repositories and Storage:
  The method interacts with repositories managing block states, accounts, and message durable storage. These repositories abstract persistence layers and ensure data consistency.

• NACK Set Cache:
  The nack_set_cache is a synchronized cache used to track blocks that were negatively acknowledged. This cache is intended for future removal, suggesting a refactor or redesign is planned.

Interactions with Other Components

• Envelope<GoshBLS, AckiNackiBlock>
  The block is wrapped in an envelope that provides cryptographic signature verification using the GoshBLS scheme. This ensures the authenticity and integrity of blocks before they are applied.

• OptimisticStateImpl
  Represents the state of the blockchain after applying a block. It contains the logic to apply blocks (apply_block) and manage state transitions optimistically.

• Shared Services
  The shared_services field provides access to cross-thread reference data services and potentially other utilities needed during block application.

• Repositories (BlockStateRepository, AccountsRepository)
  Interfaces to persistent storage layers for blocks and accounts, ensuring that state changes are recorded and retrievable.

• MessageDurableStorage
  Persistent storage for messages, possibly related to inter-node communication or transaction processing.

Mermaid Diagram

classDiagram
class Checkpoint {
-block: Option<Envelope>
-state_after_block_applied: Arc<OptimisticStateImpl>
-shared_services: SharedServices
-block_state_repository: BlockStateRepository
-accounts_repository: AccountsRepository
-message_db: MessageDurableStorage
-nack_set_cache: Arc<Mutex<FixedSizeHashSet>>
+apply()
}
Checkpoint --> Envelope : contains
Checkpoint --> OptimisticStateImpl : uses
Checkpoint --> SharedServices : uses
Checkpoint --> BlockStateRepository : uses
Checkpoint --> AccountsRepository : uses
Checkpoint --> MessageDurableStorage : uses
Checkpoint --> FixedSizeHashSet : uses

Additional References

• For details on cryptographic envelopes and BLS signatures, see bls.

• For understanding optimistic state management, see optimistic_state.

• For concepts on repositories and durable storage, see repository and message_storage.

• For concurrency handling patterns such as mutexes and atomic references, see concurrency and arc.