service.rs

Overview

This file implements the AttestationTargetsService, a core service responsible for evaluating whether the required attestations from ancestor blocks are met for the next block in a blockchain thread. It mainly focuses on verifying the sufficiency of attestations against finalization checkpoints derived from ancestor blocks' states. This service interacts with the BlockStateRepository to retrieve state data and uses the concept of attestation target checkpoints to decide if the next block's ancestor attestations fulfill the protocol's criteria.

Structs and Enums

AttestationTargetsService

A service struct constructed with a BlockStateRepository instance used to access block states for evaluation.

• Fields:

  • block_state_repository: BlockStateRepository
    Repository interface for fetching block states.

• Builder:
  Uses TypedBuilder for ergonomic construction.

AttestationsFailure

An enum listing possible failure reasons related to attestation processing.

• Variants:

  • ChainIsTooShort

  • NotAllInitialAttestationTargetsSet

  • ThreadIdentifierIsNotSet

  • AttestationsAreNotVerifiedYet

  • FailedToSaveBlockState

  • InvalidBlock_TailDoesNotMeetCriteria

Currently, this enum is defined but not extensively used in the implementation.

Functions and Methods

AttestationTargetsService::evaluate_if_next_block_ancestors_required_attestations_will_be_met

pub fn evaluate_if_next_block_ancestors_required_attestations_will_be_met(
    &self,
    thread_identifier: ThreadIdentifier,
    parent_block_identifier: BlockIdentifier,
    next_block_attestations: HashMap<(BlockIdentifier, AttestationTargetType), HashSet<SignerIndex>>,
) -> anyhow::Result<bool, UnfinalizedAncestorBlocksSelectError>

Purpose

Determines if the attestations provided for the next block meet the required attestation thresholds of ancestor blocks in the same thread, according to finalization checkpoints.

Parameters

• thread_identifier: ThreadIdentifier
  The thread ID for the next block whose ancestors' attestations are being evaluated.

• parent_block_identifier: BlockIdentifier
  The identifier of the parent block of the next block.

• next_block_attestations: HashMap<(BlockIdentifier, AttestationTargetType), HashSet<SignerIndex>>
  A mapping from (BlockIdentifier, AttestationTargetType) pairs to sets of SignerIndex values representing which signers have attested.

Returns

• anyhow::Result<bool, UnfinalizedAncestorBlocksSelectError>
  Returns Ok(true) if all required attestations are met, Ok(false) otherwise. Errors such as failure to load block states return an Err.

Description

1. Retrieves the parent block state from the repository.

2. Extracts the parent block's thread identifier and ancestor blocks' finalization checkpoints.

3. If the thread identifiers do not match, it assumes the attestations are sufficient and returns true.

4. Otherwise, it creates mutable copies of the primary and fallback finalization checkpoints and applies the inherit_checkpoint transformation to each checkpoint.

5. Constructs a new AncestorBlocksFinalizationCheckpointsConstructor using the inherited checkpoints.

6. Calls .update(...) with the counts of attestations per (BlockIdentifier, AttestationTargetType).

7. Checks the failed field in the update result; if empty, all required attestations are met.

8. Returns the boolean result.

Usage Example

let service = AttestationTargetsService::builder()
    .block_state_repository(block_state_repo)
    .build();

let result = service.evaluate_if_next_block_ancestors_required_attestations_will_be_met(
    thread_id,
    parent_block_id,
    next_block_attestations_map,
);

match result {
    Ok(true) => println!("All ancestor attestations requirements met."),
    Ok(false) => println!("Some ancestor attestations requirements are missing."),
    Err(e) => eprintln!("Evaluation error: {:?}", e),
}

Implementation Details and Algorithms

• Checkpoint Inheritance:
  Attestation checkpoints from ancestor blocks are processed through inherit_checkpoint to adjust them according to the protocol's rules before evaluation.

• Finalization Checkpoints Structure:
  The checkpoints are divided into primary and fallback categories. Both are cloned and mutated for the evaluation context.

• Update Mechanism:
  The AncestorBlocksFinalizationCheckpointsConstructor is used to apply the updated attestations and determine which checkpoints fail to meet requirements.

• Thread Identifier Validation:
  The evaluation only proceeds with detailed checks if the thread identifier of the next block matches that of the parent block; otherwise, it returns success immediately.

• Error Handling:
  The method returns specific errors if block states are missing or cannot be loaded, using the UnfinalizedAncestorBlocksSelectError enum.

Interaction with Other Components

• BlockStateRepository
  This component is queried for the state of the parent block to access the thread identifier and ancestor blocks' finalization checkpoints.

• AncestorBlocksFinalizationCheckpoints and AncestorBlocksFinalizationCheckpointsConstructor
  Used to manage and update the finalization checkpoints for ancestor blocks.

• AttestationTargetType
  Enum that indicates the type of attestation target (e.g., Primary, Fallback), used as part of the keys in attestation mappings.

• UnfinalizedAncestorBlocksSelectError
  Error type used to indicate issues related to loading or selecting unfinalized ancestor blocks.

• inherit_checkpoint function
  Transforms checkpoints to be used in the evaluation context, details of which are implemented in another module.

• Test Module
  Contains regression tests that reproduce specific scenarios for the evaluation function, ensuring correctness under load or edge cases.

Visual Diagram

classDiagram
class AttestationTargetsService {
-block_state_repository: BlockStateRepository
+evaluate_if_next_block_ancestors_required_attestations_will_be_met()
}
class BlockStateRepository
class AncestorBlocksFinalizationCheckpointsConstructor {
+builder()
+update()
}
class AncestorBlocksFinalizationCheckpoints {
+primary: HashMap
+fallback: HashMap
}
class AttestationTargetType
class UnfinalizedAncestorBlocksSelectError
AttestationTargetsService --> BlockStateRepository
AttestationTargetsService --> AncestorBlocksFinalizationCheckpointsConstructor
AncestorBlocksFinalizationCheckpointsConstructor --> AncestorBlocksFinalizationCheckpoints
AttestationTargetsService ..> AttestationTargetType
AttestationTargetsService ..> UnfinalizedAncestorBlocksSelectError

Test Coverage

The tests module includes two regression test cases that simulate real-world failure scenarios observed in load tests. These tests:

• Construct controlled block states with specific finalization checkpoints.

• Provide sets of next block attestations.

• Validate that the evaluation method returns the expected successful results.

Tests utilize utilities such as tempfile for temporary repository paths and tracing_test to capture logs.

For more information on related data structures and error handling, see BlockStateRepository, AncestorBlocksFinalizationCheckpoints, and AttestationTargetType.