stub_repository.rs

Overview

This file defines stub implementations primarily intended for testing purposes within the repository layer of the system. It provides mock versions of core repository traits and optimistic state handling that emulate the behavior of their real counterparts without performing actual data operations. These stubs enable isolated testing of components that depend on repository interactions without requiring a full database or network setup.

The file contains:

• OptimisticStateStub: A stub implementation of the OptimisticState trait, representing a simplified optimistic blockchain state.

• RepositoryStub: A stub implementation of the Repository trait, simulating repository functions related to block data and optimistic states.

These stubs serve as placeholders for the real implementations, facilitating unit tests and integration tests for modules interacting with repository abstractions.

Detailed Explanations

OptimisticStateStub

A mock structure implementing the OptimisticState trait. It is designed to represent an optimistic state snapshot of a blockchain shard or thread in a minimalistic way.

Definition

#[derive(Clone)]
pub struct OptimisticStateStub {
    _key: u64,
    _acc: u16,
    _state: tvm_block::Account,
}

• _key: A placeholder key (u64).

• _acc: A placeholder account index or identifier (u16).

• _state: The underlying account state (tvm_block::Account).

Trait Implementation: OptimisticState

Implements the required methods for the OptimisticState trait with todo!() placeholders, except for the type declarations.

Associated Types

• Cell: ()

• Message: MessageStub (used only in tests)

• ShardState: ShardStateUnsplit

Important Methods

• get_share_stare_refs(): Returns a map of thread identifiers to block identifiers representing shared state references.

• get_block_seq_no(): Returns the sequence number of the block.

• apply_block(): Applies a candidate block to the optimistic state, potentially updating the state and producing cross-thread references and messages.

• get_thread_id(): Returns the thread identifier associated with this optimistic state.

• add_slashing_messages(): Adds slashing-related messages to the state.

These methods are currently unimplemented (todo!()), indicating that this stub serves as a template or placeholder.

Usage Example

let mut state = OptimisticStateStub { _key: 0, _acc: 0, _state: some_account };
let thread_id = state.get_thread_id();

RepositoryStub

A mock repository implementation of the Repository trait, used for testing repository-dependent components.

Definition

pub struct RepositoryStub {
    _storage: HashMap<BlockIdentifier, Envelope<GoshBLS, AckiNackiBlock>>,
    optimistic_state: HashMap<BlockIdentifier, <Self as Repository>::OptimisticState>,
}

• _storage: Stores candidate blocks indexed by their block identifiers.

• optimistic_state: Stores optimistic state snapshots indexed by block identifiers.

Initialization

impl Default for RepositoryStub {
    fn default() -> Self {
        Self::new()
    }
}

impl RepositoryStub {
    pub fn new() -> Self {
        Self { _storage: HashMap::new(), optimistic_state: HashMap::new() }
    }
}

Creates an empty stub repository with no stored blocks or states.

Trait Implementation: Repository

Implements the Repository trait with the following associated types:

• Attestation: Envelope<GoshBLS, AttestationData>

• BLS: GoshBLS

• CandidateBlock: Envelope<GoshBLS, AckiNackiBlock>

• EnvelopeSignerIndex: u16

• NodeIdentifier: NodeIdentifier

• OptimisticState: OptimisticStateStub

• StateSnapshot: OptimisticStateStub

Selected Methods and Behavior

• get_optimistic_state() and get_full_optimistic_state(): Return the optimistic state for a given block identifier if present.

• mark_block_as_finalized(): Empty implementation returning Ok(()).

• Most other methods are unimplemented (todo!()), reflecting their placeholder nature.

Usage Example

let mut repo = RepositoryStub::new();
let block_id = some_block_identifier;
if let Ok(Some(state)) = repo.get_optimistic_state(&block_id, &some_thread_id, None) {
    // Use optimistic state for testing
}

Important Implementation Details and Algorithms

• The stubs do not implement actual logic but define method signatures matching the expected repository and optimistic state traits.

• The OptimisticStateStub and RepositoryStub use todo!() macros to indicate unimplemented methods, serving as placeholders.

• The RepositoryStub maintains in-memory hash maps for blocks and states to simulate repository behavior.

• Conversions from and to Vec<u8> for OptimisticStateStub are declared but unimplemented, suggesting serialization/deserialization stubs.

Interactions with Other System Components

• The stubs depend on core types such as BlockIdentifier, ThreadIdentifier, Envelope, AckiNackiBlock, and GoshBLS signatures, which are part of the system's blockchain and cryptographic layers.

• OptimisticStateStub implements the OptimisticState trait, which is used in consensus and state management modules.

• RepositoryStub implements the Repository trait, which is a central abstraction used by multiple components for block storage, state management, and synchronization.

• The stubs are conditionally compiled for test environments (#[cfg(test)]), ensuring they do not affect production code.

• They interact indirectly with services like StateSyncService, MessageDurableStorage, and BlockStateRepository as specified in method signatures.

For related abstractions and detailed trait descriptions, see:

• Repository

• OptimisticState

• BlockStateRepository

• StateSyncService

Diagram: Structure of stub_repository.rs

classDiagram
class OptimisticStateStub {
-_key: u64
-_acc: u16
-_state: Account
+get_share_stare_refs()
+get_block_seq_no()
+get_block_id()
+serialize_into_buf()
+get_shard_state()
+get_block_info()
+apply_block()
+get_thread_id()
+add_slashing_messages()
}
class RepositoryStub {
-_storage: HashMap<BlockIdentifier, Envelope>
-optimistic_state: HashMap<BlockIdentifier, OptimisticStateStub>
+new()
+get_optimistic_state()
+get_full_optimistic_state()
+mark_block_as_finalized()
}
OptimisticStateStub ..|> OptimisticState
RepositoryStub ..|> Repository

This diagram highlights the two main stub structures, their key properties, and selected methods, including their trait implementations. It illustrates the core in-memory storage for blocks and optimistic states and the stubbed method interfaces.