single_block_verifier.rs

Overview

This file implements the functionality for producing a single verification block within a blockchain environment. It defines a generic BlockVerifier trait and a concrete implementation, TVMBlockVerifier, which is responsible for generating a verification block from an existing block and its optimistic state. The verification process includes message preprocessing, validation of incoming messages, execution of slashing logic, and block construction using the TVM (TON Virtual Machine) configuration and runtime services.

The file integrates multiple components such as blockchain configuration, accounts repository, block state repository, and shared services to perform the verification step. It ensures the correctness and uniqueness of incoming messages, handles external inbound messages, and enforces execution time limits during verification.

Traits and Structures

BlockVerifier Trait

The BlockVerifier trait abstracts the behavior required to generate a verification block.

Associated Types

• OptimisticState: Represents the state used optimistically during block verification.

• Message: The message type used during block verification.

Methods

generate_verify_block

fn generate_verify_block<'a, I>(
    self,
    block: &AckiNackiBlock,
    initial_state: Self::OptimisticState,
    refs: I,
    message_db: MessageDurableStorage,
) -> anyhow::Result<(AckiNackiBlock, Self::OptimisticState)>
where
    I: Iterator<Item = &'a CrossThreadRefData> + Clone,
    CrossThreadRefData: 'a;

• Parameters:

  • block: The block to be verified, of type AckiNackiBlock.

  • initial_state: The optimistic state representing the parent block state.

  • refs: An iterator over CrossThreadRefData references required during preprocessing.

  • message_db: A durable storage interface for accessing message data.

• Returns:

  • A Result containing a tuple with the newly generated verification block (AckiNackiBlock) and the updated optimistic state.

• Description:

  • This method performs the verification logic by preprocessing references, assembling inbound messages, checking for message uniqueness, enforcing execution time limits, and building a new verification block using BlockBuilder.

• Usage Example:

  let verifier: TVMBlockVerifier = ...;
  let (verified_block, new_state) = verifier.generate_verify_block(&block, parent_state, refs_iter, message_db)?;
  

TVMBlockVerifier Struct

The TVMBlockVerifier is a concrete implementation of the BlockVerifier trait tailored for the TVM blockchain environment.

Fields

• blockchain_config: Arc<BlockchainConfig> — Shared blockchain configuration parameters.

• node_config: Config — Configuration specific to the node.

• epoch_block_keeper_data: Vec<BlockKeeperData> — Data related to block keeper epochs.

• block_nack: Vec<Envelope<GoshBLS, NackData>> — List of negative acknowledgment envelopes used for slashing.

• shared_services: SharedServices — Shared runtime services used in block processing.

• accounts_repository: AccountsRepository — Repository interface for account data.

• block_state_repository: BlockStateRepository — Repository interface for block state data.

• metrics: Option<BlockProductionMetrics> — Optional metrics for block production monitoring.

• wasm_cache: WasmNodeCache — Cache for WebAssembly execution nodes.

Methods

print_block_info

fn print_block_info(block: &tvm_block::Block);

• Parameters:

  • block: Reference to a TVM block.

• Description:

  • Logs detailed information about the given block including generation time, counts of incoming and outgoing messages, and account blocks.

• Example Usage:

  TVMBlockVerifier::print_block_info(&block);
  

generate_verify_block (Implementation)

• Implements the trait method described above. Detailed steps include:

  1. Initialization: Extracts thread identifier and initializes execution time limits.

  2. Slashing Messages: Processes block_nack to generate wallet slashing messages and maintains a whitelist of slashing message hashes.

  3. Preprocessing: Executes preprocessing with cross-thread references and slashing messages using shared_services.

  4. Message Parsing: Iterates over incoming messages in the block:

     • Extracts transactions and verifies uniqueness of messages by logical time per destination account.

     • Collects inbound external messages and handles aborted transactions with execution timeout exceptions to adjust time limits.

  5. Grouping External Messages: Groups external inbound messages by account address, attaching timestamps and indices.

  6. Block Building: Creates a BlockBuilder instance to build the verification block with the collected messages, execution limits, and blockchain config.

  7. Result Composition: Constructs the resulting AckiNackiBlock with updated state and references, preserving thread tables and other metadata.

• Error Handling:

  • Uses anyhow::Result for error propagation.

  • Ensures uniqueness of incoming messages, and reports failures in preprocessing or message parsing.

• Instrumentation:

  • Employs the tracing::instrument macro for detailed logging and tracing during execution.

Implementation Details and Algorithms

• Message Uniqueness Check: Uses a nested map (HashMap<AccountAddress, BTreeMap<u64, UInt256>>) keyed by destination account and logical time to ensure no duplicate incoming messages are processed. This is critical for maintaining blockchain consistency.

• Slashing Logic: Processes negative acknowledgments (block_nack) to generate slashing messages that penalize misbehaving nodes, employing cryptographic envelopes and referencing node identities.

• Execution Time Management: Detects transactions aborted due to execution timeout and adjusts verification time limits dynamically to prevent premature termination.

• Message Grouping: External inbound messages are grouped using a timestamp and index stamp, organized per account. This grouping facilitates orderly processing during block building.

• Block Building: Utilizes the BlockBuilder to assemble the verification block, incorporating state, gas limits, random seeds, and preprocessed messages.

Interaction with Other System Components

• Blockchain Configuration (BlockchainConfig): Provides gas limits and other blockchain parameters influencing block verification.

• Node and Wallet Configurations: Utilizes node-specific configuration (Config) and wallet slash message creation logic for slashing operations.

• Shared Services: Accesses cross-thread reference data services for preprocessing.

• Repositories: Reads and updates account and block state repositories.

• Message Storage: Reads messages from MessageDurableStorage as part of preprocessing and verification.

• Block Builder: Relies on the BlockBuilder for constructing the verified block.

• Metrics: Optionally records metrics related to block production for monitoring purposes.

Mermaid Diagram: Structure of single_block_verifier.rs

classDiagram
class BlockVerifier {
<<trait>>
+generate_verify_block()
}
class TVMBlockVerifier {
-blockchain_config: Arc<BlockchainConfig>
-node_config: Config
-epoch_block_keeper_data: Vec<BlockKeeperData>
-block_nack: Vec<Envelope<GoshBLS, NackData>>
-shared_services: SharedServices
-accounts_repository: AccountsRepository
-block_state_repository: BlockStateRepository
-metrics: Option<BlockProductionMetrics>
-wasm_cache: WasmNodeCache
+print_block_info()
+generate_verify_block()
}
BlockVerifier <|.. TVMBlockVerifier