mod.rs

Overview

This Rust source file serves as a central module aggregator and encapsulates functionalities related to block state management, persistence, and validation within the system. It exposes several submodules responsible for handling different aspects of the block state lifecycle, including attestation checkpoints, inner block states, state repositories, unfinalized ancestor blocks, and utility tools. Additionally, it provides a service for asynchronously saving state to persistent storage.

Internally, the file includes a private submodule that manages the loading and saving of block state data from and to the filesystem, currently using file-based persistence with plans to migrate to an embedded database.

Modules and Exports

• attestation_target_checkpoints: Manages attestation target checkpoints related to block validation.

• block_state_inner: Defines the inner structure and operations of the block state.

• repository: Contains repository implementations for persisting and retrieving data.

• save_service: Implements an asynchronous service for saving block states; its start_state_save_service function is publicly re-exported.

• state: Defines the main block state entity, AckiNackiBlockState.

• tools: Provides utility functions for block state processing.

• unfinalized_ancestor_blocks: Handles blocks that are ancestors but not yet finalized.

Private Module: private

This module encapsulates file-based persistence logic for AckiNackiBlockState. It is not exposed outside this file, ensuring encapsulation of storage details.

Functions

load_state(file_path: PathBuf) -> anyhow::Result<Option<AckiNackiBlockState>>

• Description: Attempts to load a block state from the specified file path.

• Parameters:

  • file_path: The path to the file where the block state is stored.

• Returns:

  • Ok(Some(AckiNackiBlockState)) if the block state was successfully loaded.

  • Ok(None) if no block state file exists at the path.

  • Err if an error occurred during loading.

• Implementation Details:

  • Uses load_from_file utility from the repository implementation to deserialize the state.

  • On successful loading, assigns the file_path to the loaded state instance to maintain a reference for future saves.

  • Errors are wrapped with context indicating the file path involved for easier debugging.

• Example Usage:

  let path = PathBuf::from("state_data.bin");
  match private::load_state(path)? {
      Some(state) => { /* use loaded state */ }
      None => { /* initialize new state */ }
  }
  

save(state: &AckiNackiBlockState) -> anyhow::Result<()>

• Description: Saves the given block state to its associated file path.

• Parameters:

  • state: A reference to the AckiNackiBlockState instance to be saved.

• Returns:

  • Ok(()) if the save operation succeeded.

  • Err if an error occurred during saving.

• Implementation Details:

  • Retrieves the file_path stored within the state.

  • Uses save_to_file utility to serialize and write the state to disk.

  • The false flag indicates no special options (such as atomic write) are applied currently.

  • Ensures errors propagate with context for troubleshooting.

• Example Usage:

  private::save(&current_state)?;
  

Interaction with Other Parts of the System

• The file imports and re-exports the start_state_save_service from the save_service submodule, making it available for starting asynchronous persistence operations.

• It relies on serialization and deserialization utilities from the repository module to perform file-based persistence.

• The state module defines the core data structure AckiNackiBlockState which is the subject of loading and saving operations.

• The encapsulated private persistence functions can be used by higher-level services or modules to maintain block state durability.

• The file hints at future migration plans to an embedded database, implying this layer may be replaced or extended with more robust storage mechanisms.

Important Implementation Notes

• Persistence currently uses file-based storage via load_from_file and save_to_file.

• Error handling is done via the anyhow crate, providing rich error context.

• The file_path is stored inside the AckiNackiBlockState object, coupling state and its storage location.

• The design keeps persistence implementation details private, encouraging modularity and potential future replacement without affecting consumers.

Mermaid Diagram

classDiagram
class AckiNackiBlockState {
+file_path: PathBuf
}
class private {
+load_state(file_path: PathBuf) Result<Option<AckiNackiBlockState>>
+save(state: &AckiNackiBlockState) Result<()>
}
class save_service {
+start_state_save_service()
}
mod_rs --> attestation_target_checkpoints
mod_rs --> block_state_inner
mod_rs --> repository
mod_rs --> save_service
mod_rs --> state
mod_rs --> tools
mod_rs --> unfinalized_ancestor_blocks
mod_rs --> private
private ..> AckiNackiBlockState : uses
private o--> repository : uses load/save functions
save_service ..> AckiNackiBlockState : manages saving

This diagram illustrates the main components exposed or encapsulated within the file and their relationships, focusing on the private persistence functions and how they operate with the AckiNackiBlockState entity and other modules.