chain_tracker.rs

Overview

The chain_tracker.rs file provides functionality to identify and analyze gaps in blockchain data sequences, specifically focusing on missing parent blocks within chains. This is crucial for maintaining the integrity of blockchains by detecting incomplete or invalid chains due to missing blocks. The core operations include finding all gaps in a chain of unfinalized blocks and determining the shortest gap that might fix all chains starting from a specified minimum sequence number.

This file interacts primarily with data structures representing blocks and their states — such as BlockState, BlockStateRepository, and UnfinalizedBlocksSnapshot — and uses metrics reporting via BlockProductionMetrics. These components are part of the broader blockchain node and types management subsystems.

Functions

_find_shortest_gap

pub fn _find_shortest_gap(
    thread_identifier: &ThreadIdentifier,
    unprocessed_blocks_cache: &UnfinalizedBlocksSnapshot,
    block_state_repository: &BlockStateRepository,
    min_seq_no: BlockSeqNo,
    metrics: Option<BlockProductionMetrics>,
) -> Option<BlockSeqNo>

Description

Finds the potentially shortest gap in the block sequence that may fix all chains. It analyzes gaps in the block sequence after the given min_seq_no and returns the smallest sequence number representing a missing block that could restore chain continuity.

Parameters

• thread_identifier: &ThreadIdentifier
  Identifies the blockchain thread for which gaps are to be found.

• unprocessed_blocks_cache: &UnfinalizedBlocksSnapshot
  Snapshot of unfinalized blocks that the function examines to find gaps.

• block_state_repository: &BlockStateRepository
  Repository interface to query block states, particularly to check existence and finalization status of parent blocks.

• min_seq_no: BlockSeqNo
  The minimum sequence number threshold. Gaps below or equal to this will be ignored as they are considered already processed or finalized.

• metrics: Option<BlockProductionMetrics>
  Optional metrics collector to track gap querying operations.

Returns

• Option<BlockSeqNo>
  Returns the sequence number of the shortest detected gap greater than min_seq_no. Returns None if no suitable gap is found.

Usage Example

let shortest_gap = _find_shortest_gap(
    &thread_id,
    &unfinalized_blocks_snapshot,
    &block_state_repo,
    last_finalized_seq_no + 1,
    Some(metrics_collector),
);
if let Some(gap_seq_no) = shortest_gap {
    println!("Shortest missing gap found at sequence number: {}", gap_seq_no);
}

Implementation Details

• Calls _find_all_gaps to retrieve all missing parent block states.

• Iterates over all detected gaps, filtering out blocks below or equal to min_seq_no.

• Uses the .guarded() method to safely access block sequence numbers.

• Tracks and returns the lowest sequence number representing the shortest gap.

_find_all_gaps

pub fn _find_all_gaps(
    thread_identifier: &ThreadIdentifier,
    unprocessed_blocks_cache: &UnfinalizedBlocksSnapshot,
    block_state_repository: &BlockStateRepository,
    metrics: Option<BlockProductionMetrics>,
) -> Vec<BlockState>

Description

Identifies all gaps within the specified blockchain thread by finding blocks that have missing parent blocks. Returns a list of BlockState instances representing blocks whose parents are not stored or finalized.

Parameters

• thread_identifier: &ThreadIdentifier
  Specifies the blockchain thread to inspect.

• unprocessed_blocks_cache: &UnfinalizedBlocksSnapshot
  Collection of unfinalized blocks to search for gaps.

• block_state_repository: &BlockStateRepository
  Used to check whether parent blocks are stored/finalized.

• metrics: Option<BlockProductionMetrics>
  Optional metrics reporting for gap queries.

Returns

• Vec<BlockState>
  A vector of block states corresponding to blocks that have missing parent blocks.

Usage Example

let gaps = _find_all_gaps(
    &thread_id,
    &unfinalized_blocks_snapshot,
    &block_state_repo,
    None,
);
for gap_block in gaps {
    println!("Block with missing parent: {:?}", gap_block);
}

Implementation Details

• Reports query metrics if provided.

• Filters blocks by matching thread identifier.

• For each block, checks if the parent block identifier exists and whether the parent block is stored.

• Collects blocks whose parents are missing or not stored.

Important Implementation Details

• Uses .guarded() method extensively to safely access internal data of BlockState objects while handling potential concurrency or mutation issues. See Guarded Access for more on this pattern.

• The logic assumes that a missing parent block indicates a gap that prevents chain finalization.

• min_seq_no parameter in _find_shortest_gap acts as a cutoff to prevent considering blocks that are already finalized or irrelevant.

• Metrics reporting is optional but integrated to monitor performance and behavior of gap detection.

Interaction with Other System Components

• BlockState and BlockStateRepository: The backbone of block storage and state querying. This file queries block existence and finalization status using these components.

• UnfinalizedBlocksSnapshot: Provides a snapshot of unfinalized blocks, which is the primary data source for gap detection.

• BlockProductionMetrics: Metrics collection component used optionally for monitoring gap detection queries.

• ThreadIdentifier and BlockSeqNo: Essential types for identifying blockchains and block ordering within threads.

Visual Diagram

flowchart TD
A[Start: _find_shortest_gap] --> B[_find_all_gaps]
B --> C[Filter gaps by thread & missing parent]
C --> D[List of BlockState gaps]
D --> E[Iterate gaps]
E --> F{Is seq_no > min_seq_no?}
F -- Yes --> G[Update shortest gap if smaller]
F -- No --> E
G --> E
E --> H[Return shortest gap or None]
subgraph _find_all_gaps
direction TB
A1[Input: UnfinalizedBlocksSnapshot] --> A2[Iterate blocks]
A2 --> A3[Filter by thread]
A3 --> A4[Check parent block existence]
A4 --> A5[Check parent block is stored?]
A5 -- No --> A6[Collect block as gap]
A5 -- Yes --> A2
A6 --> A2
A2 --> Result[List of gaps]
end

The diagram illustrates the workflow of the two primary functions: _find_shortest_gap calls _find_all_gaps to gather all gaps and then filters for the shortest gap sequence number greater than the specified minimum. The _find_all_gaps process filters blocks by thread, verifies parent block existence, and collects blocks with missing or unstored parents.

References

• BlockState for detailed understanding of block metadata and states.

• BlockStateRepository for block storage and retrieval mechanisms.

• UnfinalizedBlocksSnapshot for snapshot handling of unfinalized blocks.

• Guarded Access for concurrency-safe data access patterns.

• BlockProductionMetrics for metrics reporting related to block production and gap queries.