attestation_target_checkpoints.rs

Overview

This file defines structures and logic for managing attestation target checkpoints related to block finalization in a blockchain consensus context. It tracks the progress and validation status of ancestor blocks through a system of checkpoints that represent deadlines and required attestation counts for blocks to be considered finalized. The main entities encapsulate checkpoint data, their validation results, and mechanisms to inherit and update checkpoint states as new blocks are added.

Key Components

Structs and Enums

`AttestationTargetCheckpoint`

Purpose: Represents a checkpoint for an attestation target of a block, tracking how far along it is (current_distance), the deadline to finalize, and how many attestations are required.
Fields:
- current_distance: usize — Distance progressed toward the deadline.
- deadline: usize — Maximum allowable distance before checkpoint failure.
- required_attestation_count: usize — Number of attestations required to pass.
- attestation_target_type: AttestationTargetType — Type of attestation target (Primary or Fallback).
Traits: Clone, Serialize, Deserialize, Debug, PartialEq, Copy, Getters, TypedBuilder.
Methods:
- check(&self, attestation_target_type: &AttestationTargetType, verified_signatures_count: usize) -> AttestationTargetCheckpointCheckResult
  - Checks if the checkpoint passes or fails based on:
    - Whether the current distance exceeds the deadline (failure).
    - Whether the attestation target type matches.
    - Whether the verified signature count meets the required attestation count (pass).
  - Returns AttestationTargetCheckpointCheckResult (CheckpointPassed, CheckpointFailed, or NoAction).

Usage Example:

let checkpoint = AttestationTargetCheckpoint::builder()
    .current_distance(2)
    .deadline(5)
    .required_attestation_count(3)
    .attestation_target_type(AttestationTargetType::Primary)
    .build();

let result = checkpoint.check(&AttestationTargetType::Primary, 4);
// result == CheckpointPassed

`AttestationTargetCheckpointCheckResult` (enum)

Variants:
- CheckpointFailed — The checkpoint has failed due to deadline or insufficient attestations.
- CheckpointPassed — The checkpoint has passed successfully.
- NoAction — No state change; conditions not met to pass or fail.

`AncestorBlocksFinalizationCheckpoints`

Purpose: Holds collections of checkpoints for ancestor blocks, divided into primary and fallback categories.
Fields:
- primary: HashMap<BlockIdentifier, AttestationTargetCheckpoint> — Primary checkpoints keyed by block ID.
- fallback: HashMap<BlockIdentifier, Vec<AttestationTargetCheckpoint>> — Fallback checkpoints keyed by block ID, as multiple fallback checkpoints may exist per block.
Traits: Clone, Serialize, Deserialize, Debug, PartialEq, Getters, TypedBuilder.

`InheritedAncestorBlocksFinalizationCheckpoints`

Purpose: Wraps AncestorBlocksFinalizationCheckpoints to mark checkpoints inherited from a parent block.
Methods:
- into_builder(self) -> AncestorBlocksFinalizationCheckpointsConstructor
  - Converts the inherited checkpoints into a constructor for updating checkpoints based on new attestations.

`AncestorBlocksFinalizationCheckpointsConstructor`

Purpose: Facilitates updating checkpoint states based on attestation counts.
Fields:
- inherited_checkpoints: AncestorBlocksFinalizationCheckpoints — Checkpoints to update.
- passed_primary: Vec<BlockIdentifier> — Blocks that passed primary checkpoints.
- passed_fallback: Vec<BlockIdentifier> — Blocks that passed fallback checkpoints.
- passed_fallback_preattestation_checkpoint: Vec<BlockIdentifier> — Blocks that passed fallback pre-attestation checkpoints.
Traits: TypedBuilder.
Methods:
- update(self, attestation_count: HashMap<(BlockIdentifier, AttestationTargetType), usize>) -> AncestorBlocksFinalizationCheckpointsConstructorResults
  - Takes a map of attestation counts for blocks and updates checkpoints accordingly.
- note(&mut self, attested_block: BlockIdentifier, attestation_target_type: AttestationTargetType, verified_signatures_count: usize)
  - Internal method to record attestation progress for a specific block and checkpoint type.
- complete(self) -> AncestorBlocksFinalizationCheckpointsConstructorResults
  - Finalizes the update, identifying failed checkpoints, passed checkpoints, and handling transition from primary to fallback.

`AncestorBlocksFinalizationCheckpointsConstructorResults`

Purpose: Contains the results after updating checkpoints.
Fields:
- remaining_checkpoints: AncestorBlocksFinalizationCheckpoints — Checkpoints still active.
- passed_primary: Vec<BlockIdentifier> — Blocks that passed primary checkpoints.
- passed_fallback: Vec<BlockIdentifier> — Blocks that passed fallback checkpoints.
- passed_fallback_preattestation_checkpoint: Vec<BlockIdentifier> — Blocks that passed pre-attestation fallback checkpoints.
- transitioned_to_fallback: Vec<BlockIdentifier> — Blocks that transitioned from primary to fallback checkpoint tracking.
- failed: Vec<BlockIdentifier> — Blocks where checkpoints failed.

Functions

`inherit_checkpoint(mut checkpoint: AttestationTargetCheckpoint) -> AttestationTargetCheckpoint`

Purpose: Increments the current_distance of a checkpoint by 1 to represent progressing further from the origin block.
Parameters:
- checkpoint — The checkpoint to inherit and update.
Returns: A new AttestationTargetCheckpoint with incremented current_distance.
Usage: Used when inheriting checkpoints from a parent block to track distance progression.

`inherit_ancestor_blocks_finalization_distances`

fn inherit_ancestor_blocks_finalization_distances(
    parent_block_state: &BlockState,
    block_state: &BlockState,
) -> anyhow::Result<InheritedAncestorBlocksFinalizationCheckpoints>

Purpose: Creates a new set of finalization checkpoints for a block by inheriting and updating checkpoints from its parent block.
Parameters:
- parent_block_state: &BlockState — The state of the parent block.
- block_state: &BlockState — The state of the current block.
Returns: Result wrapping inherited checkpoints or an error if preconditions are not met.
Implementation Details:
- Validates presence of thread identifiers and attestation targets for parent and current block.
- If both blocks are on the same thread, increments the distance on all inherited checkpoints.
- Otherwise, initializes empty checkpoints.
- Inserts new checkpoints for the current block with initial distance zero and deadlines/counts based on the block's attestation target.
Error Handling: Uses anyhow::bail! to return errors if block states are not ready.
Interaction: Uses guarded accessors on BlockState to extract necessary information.

Implementation Details and Algorithms

Checkpoint Update Logic:
- The main update loop in AncestorBlocksFinalizationCheckpointsConstructor::update iterates over attestation counts keyed by (BlockIdentifier, AttestationTargetType).
- For each block and attestation target type, note method checks the checkpoint status:
  - If primary checkpoint passes, it removes fallback checkpoints and records the block as passed primary.
  - If fallback checkpoints are present, retains only those not passed or failed, recording passes accordingly.
- The complete method filters out checkpoints that failed based on deadlines and whether fallback checkpoints exist. Blocks failing primary checkpoints but having fallback checkpoints are transitioned to fallback tracking.
- Failed checkpoints are removed from the tracking state.
Inheritance of Checkpoints:
- inherit_checkpoint simply increments current_distance to indicate progression.
- inherit_ancestor_blocks_finalization_distances manages inheritance considering thread continuity and inserts fresh checkpoints for the current block.

Interactions with Other System Components

Uses types and traits from:
- crate::node::associated_types::AttestationTargetType — Enum representing attestation target types.
- crate::node::BlockState — Provides access to block metadata such as thread ID and attestation targets.
- crate::types::BlockIdentifier — Unique identifiers for blocks.
- crate::utilities::guarded::Guarded — Provides safe guarded accessors for block state data.
The file's functionality is central to block finalization logic and interacts with broader consensus mechanisms managing attestations and block validation.

Visual Diagram

classDiagram
class AttestationTargetCheckpoint {
+current_distance: usize
+deadline: usize
+required_attestation_count: usize
+attestation_target_type: AttestationTargetType
+check()
}
class AncestorBlocksFinalizationCheckpoints {
+primary: HashMap<BlockIdentifier, AttestationTargetCheckpoint>
+fallback: HashMap<BlockIdentifier, Vec<AttestationTargetCheckpoint>>
}
class InheritedAncestorBlocksFinalizationCheckpoints {
-ancestor_checkpoints: AncestorBlocksFinalizationCheckpoints
+into_builder()
}
class AncestorBlocksFinalizationCheckpointsConstructor {
-inherited_checkpoints: AncestorBlocksFinalizationCheckpoints
-passed_primary: Vec<BlockIdentifier>
-passed_fallback: Vec<BlockIdentifier>
-passed_fallback_preattestation_checkpoint: Vec<BlockIdentifier>
+update()
+note()
+complete()
}
class AncestorBlocksFinalizationCheckpointsConstructorResults {
+remaining_checkpoints: AncestorBlocksFinalizationCheckpoints
+passed_primary: Vec<BlockIdentifier>
+passed_fallback: Vec<BlockIdentifier>
+passed_fallback_preattestation_checkpoint: Vec<BlockIdentifier>
+transitioned_to_fallback: Vec<BlockIdentifier>
+failed: Vec<BlockIdentifier>
}
AttestationTargetCheckpoint --|> AttestationTargetCheckpointCheckResult
InheritedAncestorBlocksFinalizationCheckpoints --> AncestorBlocksFinalizationCheckpointsConstructor
AncestorBlocksFinalizationCheckpointsConstructor --> AncestorBlocksFinalizationCheckpointsConstructorResults
AncestorBlocksFinalizationCheckpointsConstructor *-- AncestorBlocksFinalizationCheckpoints
AncestorBlocksFinalizationCheckpointsConstructorResults *-- AncestorBlocksFinalizationCheckpoints

This diagram illustrates the core data structures and their relationships, highlighting the flow from inherited checkpoints through the constructor to update results.

attestation_target_checkpoints.rs

Overview

Key Components

Structs and Enums

AttestationTargetCheckpoint

AttestationTargetCheckpointCheckResult (enum)

AncestorBlocksFinalizationCheckpoints

InheritedAncestorBlocksFinalizationCheckpoints

AncestorBlocksFinalizationCheckpointsConstructor

AncestorBlocksFinalizationCheckpointsConstructorResults