mod.rs

Overview

This file defines the core Repository trait and related types and errors used for managing blockchain-related data structures and state in a modular and extensible manner. It serves as an abstraction layer for accessing, storing, and manipulating blocks, optimistic states, attestations, and related blockchain metadata. The trait is designed to be implemented by concrete repository types that interact with persistent storage, caches, and synchronization services.

The file also declares and re-exports several submodules related to state management and data repositories, such as accounts, cross_thread_ref_repository, optimistic_state, and repository_impl. It provides error handling via the RepositoryError enum and integrates with various blockchain-specific types like BlockIdentifier, ThreadIdentifier, and AckiNackiBlock.

Modules and Re-exports

• accounts: Manages account-related data storage and retrieval.

• cross_thread_ref_data (private): Contains data structures for cross-thread references.

• cross_thread_ref_repository: Provides interfaces for reading and writing cross-thread reference data.

• optimistic_shard_state: Handles shard-specific optimistic states.

• optimistic_state: Defines optimistic state management.

• repository_impl: Contains concrete implementations of the repository interfaces.

• tvm_cell_serde (private): Serialization utilities for TVM cells.

• load_saved_blocks: Utilities for loading blocks from storage.

• optimistic_state_save_service: Service for saving optimistic states asynchronously.

• stub_repository (test only): Provides stub implementations for testing purposes.

Re-exported Types

• CrossThreadRefData

• CrossThreadRefDataRead

• CrossThreadRefDataRepository

• start_optimistic_state_save_service

These re-exports allow external modules to access key data types and services without depending on internal module paths.

RepositoryError Enum

Defines error conditions related to repository operations:

This enum uses the thiserror crate for ergonomic error handling and debugging.

Repository Trait

The central abstraction in this file is the generic Repository trait, parametrized by multiple associated types to accommodate different blockchain implementations and cryptographic schemes.

Associated Types

Methods

Block Access and Management

• get_finalized_block(&self, identifier: &BlockIdentifier) -> anyhow::Result<Option<Arc<Self::CandidateBlock>>>
  Retrieves a finalized block by its identifier, if it exists.

• get_block_from_repo_or_archive(&self, block_id: &BlockIdentifier, thread_id: &ThreadIdentifier) -> anyhow::Result<Arc<Self::CandidateBlock>>
  Fetches a block from the repository or archive storage by block and thread identifiers.

• last_finalized_optimistic_state(&self, thread_id: &ThreadIdentifier) -> Option<Arc<Self::OptimisticState>>
  Returns the last finalized optimistic state for a given thread.

• select_thread_last_finalized_block(&self, thread_id: &ThreadIdentifier) -> anyhow::Result<Option<(BlockIdentifier, BlockSeqNo)>>
  Chooses the last finalized block in a thread, returning its identifier and sequence number.

• is_block_suspicious(&self, block_id: &BlockIdentifier) -> anyhow::Result<Option<bool>>
  Checks if a block is flagged as suspicious.

• mark_block_as_finalized(&mut self, block, block_state, state_sync_service) -> anyhow::Result<()>
  Marks a block as finalized, updating relevant state and optionally synchronizing via a service.

• erase_block(&self, block_id: &BlockIdentifier, thread_id: &ThreadIdentifier) -> anyhow::Result<()>
  Removes a block from the repository.

• is_block_already_applied(&self, block_id: &BlockIdentifier) -> anyhow::Result<bool>
  Determines if a block has already been applied to the state.

State Management

• get_optimistic_state(&self, block_id: &BlockIdentifier, thread_id: &ThreadIdentifier, min_state: Option<Arc<Self::OptimisticState>>) -> anyhow::Result<Option<Arc<Self::OptimisticState>>>
  Retrieves an optimistic state for a block, optionally bounded by a minimum state.

• get_full_optimistic_state(&self, block_id: &BlockIdentifier, thread_id: &ThreadIdentifier, min_state: Option<Arc<Self::OptimisticState>>) -> anyhow::Result<Option<Arc<Self::OptimisticState>>>
  Similar to get_optimistic_state but returns a full optimistic state, including all details.

• store_optimistic<T: Into<Arc<Self::OptimisticState>>>(&self, state: T) -> anyhow::Result<()>
  Persists an optimistic state to storage.

• store_optimistic_in_cache<T: Into<Arc<Self::OptimisticState>>>(&self, state: T) -> anyhow::Result<()>
  Stores an optimistic state in an in-memory cache.

• set_state_from_snapshot(&mut self, snapshot: Self::StateSnapshot, thread_id: &ThreadIdentifier, skipped_attestation_ids: Arc<Mutex<HashSet<BlockIdentifier>>>) -> anyhow::Result<()>
  Restores state from a serialized snapshot and manages skipped attestations.

• sync_accounts_from_state(&mut self, shard_state: Arc<ShardStateUnsplit>) -> anyhow::Result<()>
  Synchronizes account data based on the provided shard state.

• save_account_diffs(&self, block_id: BlockIdentifier, accounts: HashMap<String, SerializedItem>) -> anyhow::Result<()>
  Saves differences in account data related to a specific block.

• get_zero_state_for_thread(&self, thread_id: &ThreadIdentifier) -> anyhow::Result<Arc<Self::OptimisticState>>
  Retrieves the zero (initial) state for a thread.

Metadata and Auxiliary Access

• has_thread_metadata(&self, thread_id: &ThreadIdentifier) -> bool
  Checks if metadata exists for a given thread.

• init_thread(&mut self, thread_id: &ThreadIdentifier, parent_block_id: &BlockIdentifier) -> anyhow::Result<()>
  Initializes a thread with a parent block identifier.

• get_latest_block_id_with_producer_group_change(&self, thread_id: &ThreadIdentifier) -> anyhow::Result<BlockIdentifier>
  Returns the latest block ID where a producer group changed in a thread.

• load_sent_attestations(&self) -> anyhow::Result<HashMap<ThreadIdentifier, Vec<(BlockSeqNo, Self::Attestation)>>>
  Loads all sent attestations grouped by thread.

• get_all_metadata(&self) -> RepositoryMetadata
  Returns all metadata associated with the repository.

• get_message_db(&self) -> MessageDurableStorage
  Provides access to the message durable storage system.

• unfinalized_blocks(&self) -> Arc<Mutex<HashMap<ThreadIdentifier, UnfinalizedCandidateBlockCollection>>>
  Accesses the collection of unfinalized candidate blocks, grouped by thread.

• get_message_storage_service(&self) -> &MessageDBWriterService
  Provides a reference to the message database writer service.

Implementation Details and Algorithms

• The repository design emphasizes concurrency safety and performance by using Arc for shared ownership and Mutex (from parking_lot) for locking mutable shared data like unfinalized blocks and skipped attestation sets.

• Blocks and states are wrapped in Arc pointers to allow efficient cloning and sharing without deep copying.

• The trait supports optimistic state management, allowing the system to maintain and update provisional states that can later be finalized or discarded. This is essential for blockchain protocols that rely on optimistic execution or eventual consistency.

• The trait methods are designed to return anyhow::Result, enabling flexible error handling and propagation with rich context.

• The interface is generic over cryptographic schemes and data types, facilitating adaptability to various blockchain protocols or cryptographic primitives.

• The repository interacts with services such as the StateSyncService to synchronize state changes across distributed nodes.

Interactions with Other System Components

• Blocks and States: Interacts with types like AckiNackiBlock, BlockIdentifier, BlockSeqNo, and ThreadIdentifier to identify and manage blockchain data.

• Cryptography: Uses BLS signature schemes (BLSSignatureScheme) and signed envelopes (BLSSignedEnvelope) for verifying authenticity of blocks and attestations.

• Storage: Relies on durable storage abstractions such as MessageDurableStorage and MessageDBWriterService for persisting messages and account diffs.

• State Synchronization: Optional integration with StateSyncService to coordinate finalized block states across nodes.

• Optimistic State Management: Works with OptimisticState implementations to handle provisional ledger states, including snapshotting and caching.

• Cross-thread References: Through imported modules like cross_thread_ref_repository, it manages references and data dependencies across blockchain threads.

• Account Data: Syncs and persists account changes via accounts module and SerializedItem from documents_db.

Usage Examples

Retrieving a Finalized Block

let block_id = BlockIdentifier::default(); // example block identifier
match repository.get_finalized_block(&block_id)? {
    Some(block) => {
        // Process the finalized block
    }
    None => {
        // Handle block not found case
    }
}

Marking a Block as Finalized

let candidate_block = ...; // an instance implementing CandidateBlock
let block_state = BlockState::new(...); // block state info
repository.mark_block_as_finalized(&candidate_block, block_state, None)?;

Loading Optimistic State

let thread_id = ThreadIdentifier::default();
let block_id = BlockIdentifier::default();
let optimistic_state = repository.get_optimistic_state(&block_id, &thread_id, None)?;
if let Some(state) = optimistic_state {
    // Use optimistic state
}

Initializing a Thread

let thread_id = ThreadIdentifier::default();
let parent_block_id = BlockIdentifier::default();
repository.init_thread(&thread_id, &parent_block_id)?;

Mermaid Diagram: Repository Trait Structure

classDiagram
class Repository {
<<trait>>
+get_finalized_block()
+get_block_from_repo_or_archive()
+last_finalized_optimistic_state()
+clear_verification_markers()
+has_thread_metadata()
+init_thread()
+select_thread_last_finalized_block()
+is_block_suspicious()
+mark_block_as_finalized()
+get_optimistic_state()
+get_full_optimistic_state()
+erase_block()
+is_block_already_applied()
+set_state_from_snapshot()
+sync_accounts_from_state()
+save_account_diffs()
+store_optimistic()
+store_optimistic_in_cache()
+get_latest_block_id_with_producer_group_change()
+load_sent_attestations()
+get_zero_state_for_thread()
+get_all_metadata()
+get_message_db()
+unfinalized_blocks()
+get_message_storage_service()
}
class RepositoryError {
<<enum>>
+DepthSearchBlockCountLimitReached
+DepthSearchMinStateLimitReached
+BlockNotFound
}

This diagram highlights the core trait Repository with its primary methods and the associated RepositoryError enum representing possible errors during repository operations.

For detailed explanations of types such as BlockIdentifier, ThreadIdentifier, or cryptographic components like BLSSignatureScheme, refer to their respective documentation sections such as BlockIdentifier and BLSSignatureScheme. The optimistic state management strategy is detailed in Optimistic State Management, and the repository's interaction with storage systems is explained in Storage Systems.