inner_loop.rs

Overview

This file implements the core block validation loop for a blockchain node, processing incoming blocks in a continuous manner. It consumes blocks from a message queue, buffers them, filters out blocks that are already finalized or invalidated, and proceeds to verify the remaining blocks using a comprehensive validation algorithm. Validated blocks trigger acknowledgment messages, while invalid blocks are handled by branch invalidation and negative acknowledgment dispatch.

The main functionality is encapsulated in the inner_loop function, which coordinates the interaction between block state management, blockchain configuration, verification services, and messaging subsystems. This file plays a critical role in maintaining the integrity and correctness of the blockchain by ensuring only valid blocks are accepted and propagated.

Functions and Methods

read_into_buffer

fn read_into_buffer(
    rx: &mut InstrumentedReceiver<(BlockState, Envelope<GoshBLS, AckiNackiBlock>)>,
    buffer: &mut VecDeque<(BlockState, Envelope<GoshBLS, AckiNackiBlock>)>,
) -> bool

Reads all available messages from the receiver rx and appends them to the provided buffer. It continuously tries to receive blocks without blocking and finally blocks only if the buffer is empty. If the channel is disconnected, it returns false to signal termination.

• Parameters:

  • rx: The receiver channel from which (BlockState, Envelope) tuples are received.

  • buffer: A double-ended queue used to accumulate incoming blocks for processing.

• Returns:
  true if the channel is still active and blocks have been successfully read or awaited; false if the channel has been disconnected.

• Usage Example:

  let mut buffer = VecDeque::new();
  if !read_into_buffer(&mut rx, &mut buffer) {
      // Channel closed, exit loop or cleanup
  }
  

inner_loop

pub(super) fn inner_loop(
    mut rx: InstrumentedReceiver<(BlockState, Envelope<GoshBLS, AckiNackiBlock>)>,
    block_state_repo: BlockStateRepository,
    repository: RepositoryImpl,
    blockchain_config: Arc<BlockchainConfig>,
    node_config: Config,
    mut shared_services: SharedServices,
    send: AckiNackiSend,
    metrics: Option<BlockProductionMetrics>,
    wasm_cache: WasmNodeCache,
    message_db: MessageDurableStorage,
    authority: Arc<Mutex<Authority>>,
)

The primary loop function that continuously processes incoming blocks for validation.

• Parameters:

  • rx: Receiver for incoming (BlockState, Envelope) tuples representing candidate blocks.

  • block_state_repo: Repository managing block states.

  • repository: Repository implementation providing optimistic state access and account data.

  • blockchain_config: Shared blockchain configuration data.

  • node_config: Configuration specific to the node instance.

  • shared_services: Shared service handles used during block verification (e.g., cross-thread reference data).

  • send: Messaging interface for sending acknowledgment (ack) or negative acknowledgment (nack) messages.

  • metrics: Optional metrics collector for block production.

  • wasm_cache: Cache for WebAssembly execution environment used during validation.

  • message_db: Persistent storage for messages related to block processing.

  • authority: Authority structure managing thread-specific block validation authority and bad block handling.

• Functionality:

  1. Continuously reads incoming blocks into a buffer.

  2. Filters blocks that are already finalized, invalidated, or validated.

  3. For each candidate block:

     • Checks prerequisite conditions such as parent block application and signature verification.

     • Retrieves optimistic state for the block’s parent.

     • Gathers cross-thread reference data required for validation.

     • Runs the verify_block function which performs in-depth block verification including signature checks, execution, and state transitions.

  4. Records the validation result in the block state.

  5. Sends acknowledgment messages for valid blocks.

  6. For invalid blocks, triggers branch invalidation and sends negative acknowledgment with reason.

  7. Observes a global shutdown flag to exit cleanly.

• Return Value:
  This function does not return; it runs indefinitely until a shutdown signal or channel disconnect is detected.

• Usage Example:

  inner_loop(
      rx,
      block_state_repo,
      repository,
      blockchain_config,
      node_config,
      shared_services,
      send,
      metrics,
      wasm_cache,
      message_db,
      authority,
  );
  

• Important Notes:

  • The function maintains a VecDeque buffer for incoming blocks to handle bursts of received messages efficiently.

  • The filtering logic ensures only blocks that need validation are processed, improving efficiency.

  • Uses fine-grained locking and guarded access patterns for thread-safe state mutation.

  • Interacts with multiple subsystems such as block state repository, shared services, and messaging system.

  • Handles different verification failure reasons distinctly, including complex execution and bad blocks.

  • Invokes branch invalidation strategies on bad block detection, maintaining blockchain consistency.

Implementation Details and Algorithms

• Block Buffering:
  Incoming blocks are buffered using a VecDeque to allow efficient insertion and retention filtering. This prevents repeated re-processing of already validated or finalized blocks.

• Validation Filtering:
  The retain method on the buffer filters out blocks that are finalized, invalidated, or already validated. This reduces unnecessary processing.

• Parent Block Checks:
  The algorithm ensures that a block’s parent is already applied before validation proceeds. This ordering is critical to maintain blockchain consistency.

• Cross-thread Reference Resolution:
  Blocks may reference data from other threads. The loop uses the shared_services facility to fetch and assemble all required cross-thread reference data before verification.

• Verification Process:
  The core verification is delegated to the verify_block function, which is a comprehensive validator checking block integrity, signatures, state transitions, and execution correctness. The verification result guides further actions.

• Acknowledgment and Nack Handling:
  Upon successful validation, an acknowledgment is sent back to the network. For invalid blocks, the system triggers branch invalidation and sends a negative acknowledgment with a detailed reason. This mechanism helps maintain network consensus and data integrity.

• Shutdown Handling:
  The loop periodically checks a global shutdown flag (SHUTDOWN_FLAG) to exit gracefully when the node is shutting down.

Interactions with Other System Components

• BlockState and BlockStateRepository:
  The loop reads and updates block states, including validation status, finalization, and invalidation markers.

• Repository and Optimistic State:
  Retrieves optimistic blockchain state snapshots used during block execution and verification.

• SharedServices:
  Provides access to services like cross-thread reference data retrieval, essential for validating blocks that reference other threads.

• Messaging System:
  Sends acknowledgments and negative acknowledgments via AckiNackiSend interface to communicate validation results to other nodes or components.

• Authority and Thread Authority:
  Manages block validation authority per thread and handles confirmed bad block notifications to maintain security and consensus.

• WasmNodeCache and MessageDurableStorage:
  Supports execution and persistence layers used during block execution and verification.

• BlockchainConfig and Config:
  Supplies runtime parameters and node-specific configuration essential for validation logic.

• Verification Logic (verify_block):
  The verification function is a key collaborator, performing actual block validation using various inputs prepared in the loop.

Mermaid Diagram

flowchart TD
A[InstrumentedReceiver] -->|read_into_buffer| B["Buffer (VecDeque)"]
B --> C{Filter Blocks}
C -->|Validated or Finalized| B
C -->|To Validate| D[Validation Loop]
D --> E[Check Parent Block Applied]
E --> F[Retrieve Optimistic State]
F --> G[Get Cross-Thread Reference Data]
G --> H[verify_block Function]
H --> I{VerificationResult}
I -->|ValidBlock| J[Send Ack]
I -->|BadBlock| K[Invalidate Branch & Send Nack]
I -->|TooComplexExecution| L[Log Warning]
J & K & L --> M[Update BlockState Validation Status]
M --> B
M -->|Shutdown Flag| N[Exit Loop]

This diagram illustrates the main workflow inside the inner_loop function, showcasing how blocks are read, filtered, validated, and how results are communicated back to the system. It highlights interaction with the buffer, verification process, state updates, and shutdown handling.