mod.rs

Overview

This file implements the management and aggregation of attestations related to blockchain blocks within the system. It provides data structures and methods to collect, store, fold (aggregate), and manage attestations that represent validators' signatures on block data. The attestations are organized in a compacted form keyed by block sequence number, block identifier, and attestation type.

The file's core functionality revolves around:

• Collecting unverified attestations.

• Folding multiple attestations into aggregated attestations to optimize signature verification.

• Applying cutoff mechanisms to discard outdated attestations.

• Aggregating attestations based on required filters and block states.

This functionality supports consensus and validation processes by ensuring that sufficient valid attestations are gathered and combined to form proofs of block finalization or approval.

Data Structures and Types

CollectedAttestations

A struct that holds collections of attestations in two main forms:

• compacted_unverified_attestations: a map from a compacted key to a set of unverified compacted attestations.

• folded_attestations: a map from the same compacted key to aggregated attestations (folded envelopes).

Other fields include:

• cutoff: a block sequence number that acts as a lower bound cutoff. Attestations with sequence numbers less or equal to this are pruned.

• notifications: a thread-safe synchronization primitive using an atomic counter and condition variable to notify about updates.

Key Methods

• add: Adds a single attestation if it passes cutoff filtering.

• add_bunch: Adds multiple attestations with optional cutoff filtering.

• move_cutoff: Updates the cutoff and prunes attestations older than or equal to the cutoff.

• aggregate: Aggregates attestations based on required block states and aggregation filters, folding them together when possible.

Debug Trait

Implements a custom Debug trait that displays the cutoff value.

Guarded Mutability

Implements the AllowGuardedMut trait to allow controlled mutable access in guarded contexts.

AggregateFilter

A builder-based struct defining criteria for aggregation of attestations:

• attestation_type: The type of attestation target (primary or fallback).

• min_signatures_inclusive: Minimum number of signatures required for aggregation.

• action_on_condition_missed: Action to take if aggregation conditions are not met (default is to skip).

It supports construction from an AttestationTargetCheckpoint to map checkpoint requirements to aggregation filters.

AggregateActionOnConditionMissed

An enum defining actions when aggregation conditions fail. Currently, it only supports the Skip action, which ignores failed aggregations.

Key Types and Aliases

• CompactedMapKey: A key constructed from block sequence number, block identifier, and attestation target type. Used as keys for maps storing attestations.

• CompactedMap<T>: Alias for BTreeMap<CompactedMapKey, T>.

• Envelope<GoshBLS, AttestationData>: Represents signed attestation envelopes with BLS signatures.

• CompactedAttestation: A space-efficient representation of an attestation used in sets of unverified attestations.

Detailed Function and Method Descriptions

CollectedAttestations::notifications

pub fn notifications(&self) -> &Arc<(parking_lot::Mutex<u32>, parking_lot::Condvar)>

Returns a reference to the notification synchronization primitive that can be used to wait for updates to the attestation collections.

CollectedAttestations::touch

pub fn touch(&self)

Increments the internal notification counter and notifies all waiting threads. This method is called whenever the attestation collections are modified.

CollectedAttestations::add

pub fn add(
    &mut self,
    attestation: Envelope<GoshBLS, AttestationData>,
    enable_cutoff: bool,
) -> anyhow::Result<bool>

Adds a single attestation to the unverified set if it is newer than the cutoff (when cutoff is enabled).

• Parameters:

  • attestation: The attestation envelope to add.

  • enable_cutoff: Whether to apply cutoff filtering.

• Returns:

  • Ok(true) if the attestation was added (the set was modified).

  • Ok(false) if the attestation was rejected or already present.

  • Err if an error occurs during processing.

• Usage Example:

let mut collected = CollectedAttestations::default();
let result = collected.add(attestation_envelope, true)?;
if result {
    println!("New attestation added");
}

CollectedAttestations::add_bunch

pub fn add_bunch(
    &mut self,
    attestations: Vec<Envelope<GoshBLS, AttestationData>>,
    enable_cutoff: bool,
) -> anyhow::Result<bool>

Adds multiple attestations at once, applying cutoff filtering if enabled.

• Parameters:

  • attestations: Vector of attestation envelopes.

  • enable_cutoff: Whether to apply cutoff filtering.

• Returns:

  • Ok(true) if any attestation was added.

  • Ok(false) if none were added.

  • Err on error.

• Usage Example:

let mut collected = CollectedAttestations::default();
let added = collected.add_bunch(attestation_vec, false)?;
if added {
    println!("Some attestations added");
}

CollectedAttestations::move_cutoff

pub fn move_cutoff(&mut self, block_seq_no: BlockSeqNo, _block_id: BlockIdentifier)

Moves the cutoff to a new block sequence number and prunes all attestations with sequence numbers less or equal to the cutoff, both in unverified and folded collections.

• Parameters:

  • block_seq_no: New cutoff block sequence number.

  • _block_id: Block identifier associated with the cutoff (unused in this implementation).

• Behavior:

  • Removes old attestations to free memory and prevent processing stale data.

  • Logs the cutoff movement with tracing instrumentation.

CollectedAttestations::aggregate

pub fn aggregate(
    &mut self,
    required: &[(BlockState, AggregateFilter)],
) -> anyhow::Result<Vec<Envelope<GoshBLS, AttestationData>>>

Aggregates attestations for a set of required block states and corresponding aggregation filters.

• Parameters:

  • required: Slice of tuples with a BlockState and an AggregateFilter.

• Returns:

  • A vector of aggregated attestation envelopes that meet the filter criteria or are already stored in the block state.

  • Errors if critical data is missing from block states or aggregation cannot proceed.

• Implementation Details:

  • For each required block state and filter:

    • Checks if the block state already has sufficient aggregated attestations.

    • If not, attempts to use already folded attestations.

    • If folded attestations are insufficient, tries to combine folded with unverified attestations, verifying signers against the block state's backing set (bk_set).

    • Uses the try_fold function to combine signatures and produce a new folded attestation.

    • Inserts newly folded attestations back into the folded map.

    • The aggregation respects the action_on_condition_missed policy.

  • Uses tracing instrumentation to log progress and issues.

• Usage Example:

let aggregated = collected_attestations.aggregate(&[(block_state, aggregate_filter)])?;
for attestation in aggregated {
    println!("Aggregated attestation: {:?}", attestation);
}

Implementation Details and Algorithms

• Compacted Keys: The use of CompactedMapKey ensures efficient lookup and grouping of attestations by block sequence number, block ID, and attestation type.

• Folding Attestations: Folding aggregates multiple individual attestations into a single attestation with combined signatures using cryptographic BLS signature aggregation (GoshBLS).

• Cutoff Mechanism: The cutoff mechanism optimizes memory and processing by discarding attestations for blocks older than a known finalized sequence number.

• Concurrency Notifications: The notification mechanism uses parking_lot primitives to notify other threads about new attestations or changes.

• Signature Verification: While this module assumes attestations are authenticated at the network layer, it supports fallback individual verification and triggers NACKs (negative acknowledgments) on failures (implementation noted as TODO).

• Error Handling: Uses anyhow::Result for error propagation, particularly in the aggregation process where missing block state data can cause failures.

Interactions with Other System Components

• Envelope<GoshBLS, AttestationData>: This file manipulates envelopes containing attestations, relying on their structure and cryptographic methods.

• BlockState: Reads data from block states, including backing sets (bk_set), finalization proofs, and block identifiers, to determine aggregation eligibility.

• CompactedAttestation: Uses compacted representations to efficiently store and compare attestations.

• GoshBLS: Cryptographic BLS signature operations for merging and verifying signatures.

• AttestationTargetCheckpoint: Converts checkpoint information into aggregation filters.

• Synchronization Primitives: Uses parking_lot::Mutex and Condvar for thread-safe notification signaling.

• try_fold Function: Invoked to perform signature folding, combining multiple attestations into one.

• CompactedMapKey: Provides keys for organizing attestations in maps.

This module serves as a core part of the attestation management subsystem and interacts closely with block state management, cryptographic verification, and network layers.

Visual Diagram

classDiagram
class CollectedAttestations {
-compacted_unverified_attestations: CompactedMap<HashSet<CompactedAttestation>>
-folded_attestations: CompactedMap<Envelope>
-cutoff: BlockSeqNo
-notifications: Arc<(Mutex<u32>, Condvar)>
+notifications()
+touch()
+add()
+add_bunch()
+move_cutoff()
+aggregate()
}
class AggregateFilter {
-attestation_type: AttestationTargetType
-min_signatures_inclusive: usize
-action_on_condition_missed: AggregateActionOnConditionMissed
+from(AttestationTargetCheckpoint)
}
class AggregateActionOnConditionMissed {
<<enumeration>>
+Skip
}
CollectedAttestations ..> AggregateFilter : uses
CollectedAttestations ..> AggregateActionOnConditionMissed : uses
CollectedAttestations --> Envelope : stores
CollectedAttestations --> CompactedAttestation : stores
AggregateFilter --> AttestationTargetCheckpoint : from

This diagram shows the primary data structures and their relationships within the file, highlighting key methods and composition.