pulse_attestations.rs

Overview

This file defines the PulseAttestations struct and its associated methods, which manage the process of monitoring and requesting missing attestations (blocks) in a distributed blockchain-like network. The main responsibilities include triggering requests for missing blocks based on time or queue length, managing block gap adjustments, and coordinating requests for missing block ranges from interested network peers.

The module interacts closely with block states, attestation targets, and network messaging components to ensure timely synchronization of block data among nodes. It uses atomic operations and timing mechanisms to manage request intervals and gap expansions, providing efficiency and reliability in block attestation collection.

PulseAttestations Struct

Purpose

PulseAttestations is designed to track the state of block finalization and trigger network requests for missing attestations dynamically. It encapsulates logic for deciding when to request missing blocks, how to manage request frequency, and how to adjust parameters like the block gap for retries.

Fields

• node_id: NodeIdentifier
  The identifier of the local node using this struct.

• thread_identifier: ThreadIdentifier
  Identifier for the thread or chain this instance monitors.

• send_tx: NetDirectSender<NodeIdentifier, NetworkMessage>
  Network channel sender to dispatch requests directly to other nodes.

• last_finalized_block_seq_no: Option<BlockSeqNo>
  The sequence number of the last finalized block known to this node.

• last_requested_range: Option<(BlockSeqNo, BlockSeqNo)>
  The last range of block sequence numbers requested from peers.

• last_requested_time: Option<Instant>
  Timestamp of when the last request was sent.

• last_pulse: Instant
  Timestamp of the last pulse event indicating a new finalized block or reset.

• trigger_by_time: Option<Duration>
  Optional duration after which to trigger a request if no activity.

• trigger_by_length: Option<usize>
  Optional queue length threshold to trigger a request.

• request_retry_timeout: Duration
  Minimum duration between repeated requests for missing blocks.

• missing_blocks_were_requested: Arc<AtomicBool>
  Atomic flag indicating if missing blocks have been requested recently.

• trigger_increase_block_gap: Option<Duration>
  Optional duration after which to increase the allowed block gap.

• last_gap_increase: Instant
  Timestamp of the last block gap increase.

• block_gap: BlockGap
  Atomic integer representing the current block gap threshold.

• min_generations_to_request: Option<usize>
  Minimum number of block generations to include in a request.

Methods

pulse(&mut self, last_finalized_block: &BlockState) -> anyhow::Result<()>

Updates the internal state in response to a newly finalized block.

• Sets last_finalized_block_seq_no to the sequence number of the provided block.

• Resets timers and request tracking fields (last_requested_time, last_requested_range).

• Updates min_generations_to_request based on the attestation target's generation deadline.

• Updates the last_pulse timestamp to current time.

• Resets the missing_blocks_were_requested flag to false.

Parameters

• last_finalized_block: Reference to the latest finalized block state.

Returns

• Ok(()) if update succeeds.

• Error if the new finalized block sequence number is not strictly greater than the previous one.

Example Usage

pulse_attestations.pulse(&latest_finalized_block)?;

evaluate(&mut self, candidates: &UnfinalizedBlocksSnapshot, _block_state_repository: &BlockStateRepository, metrics: Option<&BlockProductionMetrics>) -> anyhow::Result<()>

Evaluates whether conditions to trigger requests for missing attestations are met and potentially increases the block gap parameter.

• Checks if a request should be triggered based on elapsed time or queue length.

• (Commented out) Calls _try_request_missing to send requests if conditions are met.

• Increases the block gap if the configured trigger_increase_block_gap duration has elapsed.

• Reports the current block gap to metrics for monitoring.

Parameters

• candidates: Snapshot of unfinalized blocks available locally.

• _block_state_repository: Repository of block states for chain tracking.

• metrics: Optional reference to block production metrics for reporting.

Returns

• Ok(()) after evaluation.

_try_request_missing(&mut self, candidates: &UnfinalizedBlocksSnapshot, block_state_repository: &BlockStateRepository, metrics: Option<BlockProductionMetrics>) -> anyhow::Result<()>

Private method to identify missing blocks and send requests to interested peer nodes.

• Avoids retrying requests if the last request was sent too recently.

• Collects a set of nodes interested in attestation excluding self.

• Determines the block sequence range that needs to be requested using _find_shortest_gap.

• Marks missing blocks as requested.

• Calls _make_request to dispatch the network requests.

Parameters

• candidates: Snapshot of unfinalized blocks.

• block_state_repository: Repository for block state lookup.

• metrics: Optional metrics for reporting.

Returns

• Ok(()) if requests were successfully sent or no action was needed.

_make_request(&mut self, attestation_interested_parties: HashSet<NodeIdentifier>, request_range_start: BlockSeqNo, request_range_end: BlockSeqNo, request_at_least_this_number_of_blocks: Option<usize>, metrics: Option<BlockProductionMetrics>) -> anyhow::Result<()>

Sends block range requests to the specified set of peer nodes.

• Reports the number of requested blocks to metrics.

• Iterates over all interested nodes and sends a network message to request blocks within the specified range.

• Updates last_requested_time and last_requested_range fields.

Parameters

• attestation_interested_parties: Set of node IDs to send requests to.

• request_range_start: Starting block sequence number of the requested range.

• request_range_end: Ending block sequence number of the requested range.

• request_at_least_this_number_of_blocks: Optionally, the minimum number of blocks to request.

• metrics: Optional metrics object for reporting.

Returns

• Ok(()) if requests are successfully sent.

• Error if network message sending fails.

Implementation Details and Algorithms

• Block Gap Management: The block gap (block_gap) is an atomic integer that controls how large a gap in block sequence numbers is allowed before triggering a request for missing blocks. It can be increased automatically after a configured duration to adapt to network conditions.

• Request Timing Control: The struct uses timestamps (last_requested_time, last_pulse, and last_gap_increase) and durations (trigger_by_time, request_retry_timeout, trigger_increase_block_gap) to ensure that requests are sent at appropriate intervals and not too frequently.

• Attestation Interest Determination: When requesting missing blocks, the system collects interested peers by aggregating all attestation interested parties from candidate blocks, excluding the local node.

• Shortest Gap Detection: Requests for missing blocks are optimized by finding the shortest gap in the sequence of blocks that needs to be filled using the external _find_shortest_gap function.

• Concurrency Safety: Atomic types and Arc wrappers are used to safely share and update state flags and counters across threads.

Interaction with Other System Components

• Network Messaging: Uses NetDirectSender to send NetworkMessage requests to specific peer nodes for missing block ranges.

• Block State Tracking: Interfaces with BlockState and BlockStateRepository to determine finalized blocks and detect gaps in unfinalized blocks.

• Metrics Reporting: Reports block gap sizes and requested block counts to BlockProductionMetrics for performance monitoring.

• Utilities: Relies on utility functions such as next_seq_no for sequence number incrementing and guarded for safe access to guarded block state internals.

Mermaid Diagram: Structure of PulseAttestations

classDiagram
class PulseAttestations {
-node_id: NodeIdentifier
-thread_identifier: ThreadIdentifier
-send_tx: NetDirectSender
-last_finalized_block_seq_no: Option<BlockSeqNo>
-last_requested_range: Option<(BlockSeqNo, BlockSeqNo)>
-last_requested_time: Option<Instant>
-last_pulse: Instant
-trigger_by_time: Option<Duration>
-trigger_by_length: Option<usize>
-request_retry_timeout: Duration
-missing_blocks_were_requested: Arc<AtomicBool>
-trigger_increase_block_gap: Option<Duration>
-last_gap_increase: Instant
-block_gap: BlockGap
-min_generations_to_request: Option<usize>
+pulse()
+evaluate()
-_try_request_missing()
-_make_request()
}