compacted_attestation.rs

Overview

This file defines the CompactedAttestation struct and implements conversions between CompactedAttestation and the Envelope type specialized for GoshBLS signatures and AttestationData. The primary purpose is to represent and handle a compacted form of attestations, which aggregate multiple individual signatures efficiently. This facilitates optimized storage and processing of attestations within the system.

Key functionalities include:

• Holding aggregated signature data and related metadata.

• Providing access to the set of signers contributing to the aggregated signature.

• Converting between the compacted form and the full Envelope form for interoperability.

Detailed Breakdown

Struct: CompactedAttestation

pub struct CompactedAttestation {
    parent_block_id: BlockIdentifier,
    envelope_hash: AckiNackiEnvelopeHash,
    aggregated_signature: <GoshBLS as BLSSignatureScheme>::Signature,
    signature_occurrences: BTreeMap<SignerIndex, u16>,
    target_type: AttestationTargetType,
}

Description

CompactedAttestation encapsulates a compact representation of an attestation that aggregates multiple signatures into one. It contains metadata about the parent block, a unique hash of the attestation envelope, the aggregated BLS signature, and a mapping of signers to the count of their signature occurrences.

Fields

• parent_block_id: BlockIdentifier
  The identifier of the parent block to which this attestation relates.

• envelope_hash: AckiNackiEnvelopeHash
  A unique hash identifying the attestation envelope; used to verify integrity.

• aggregated_signature: <GoshBLS as BLSSignatureScheme>::Signature
  The aggregated BLS signature resulting from combining individual signatures.

• signature_occurrences: BTreeMap<SignerIndex, u16>
  A map where keys are signer indices and values are the count of how many times each signer’s signature appears in the aggregation.

• target_type: AttestationTargetType
  Indicates the type of attestation target, specifying the context or purpose of the attestation.

Traits

• Hash, PartialEq, Clone, Eq
  Enables hashing, equality checks, cloning, and usage in collections requiring these traits.

• Getters (from derive_getters)
  Automatically generates getter methods for all fields, e.g., parent_block_id(), envelope_hash(), etc.

Methods

signers

pub fn signers(&self) -> impl Iterator<Item = &SignerIndex>

Returns an iterator over the set of signers (SignerIndex) who contributed signatures to the aggregated signature.

• Return: Iterator over references to SignerIndex.

• Usage example:

let compacted: CompactedAttestation = /* obtain instance */;
for signer in compacted.signers() {
    println!("Signer index: {:?}", signer);
}

Trait Implementations for Conversion

From<&Envelope<GoshBLS, AttestationData>> for CompactedAttestation

fn from(value: &Envelope<GoshBLS, AttestationData>) -> Self

Creates a CompactedAttestation instance from a reference to an Envelope containing AttestationData signed with GoshBLS.

• Copies the parent block ID and envelope hash from the envelope's data.

• Extracts the aggregated signature.

• Clones the signature occurrences from the envelope.

• Copies the attestation target type.

Usage example:

let envelope: Envelope<GoshBLS, AttestationData> = /* existing envelope */;
let compacted: CompactedAttestation = CompactedAttestation::from(&envelope);

From<(CompactedAttestation, &CompactedMapKey)> for Envelope<GoshBLS, AttestationData>

fn from(value: (CompactedAttestation, &CompactedMapKey)) -> Self

Reconstructs an Envelope from a tuple containing a CompactedAttestation and a reference to a CompactedMapKey.

• Uses the aggregated signature from the compacted attestation.

• Converts the signature occurrences map into a HashMap.

• Builds new AttestationData using information from the CompactedMapKey and the compacted attestation fields.

• Calls Envelope::create to instantiate the new envelope.

Usage example:

let compacted: CompactedAttestation = /* existing compacted attestation */;
let map_key: &CompactedMapKey = /* reference to map key */;
let envelope: Envelope<GoshBLS, AttestationData> = (compacted, map_key).into();

Implementation Details and Algorithms

• The signature_occurrences field uses a BTreeMap to maintain ordered keys, which can be beneficial for consistent iteration order and deterministic serialization.

• Aggregation leverages the GoshBLS signature scheme, a variant of Boneh–Lynn–Shacham (BLS) signature, which supports secure signature aggregation.

• Conversion from Envelope to CompactedAttestation clones signature occurrences using a method clone_signature_occurrences() provided by the Envelope type, ensuring the internal state is preserved.

• Conversion back to Envelope requires a CompactedMapKey to provide some block identification and sequencing metadata necessary to reconstruct the full envelope's attestation data.

Interaction with Other Modules

• Uses types from the bls module, including Envelope, BLSSignatureScheme, and GoshBLS for signature representation and cryptographic operations.

• Depends on node::associated_types for domain-specific types like AttestationData, AttestationTargetType, and SignerIndex.

• Uses types module entities such as BlockIdentifier, AckiNackiEnvelopeHash, and CompactedMapKey for block references and envelope indexing.

• The CompactedAttestation struct acts as a bridge between the compacted attestation representation used internally for efficiency and the full Envelope data structure used for broader protocol operations.

Visual Diagram

classDiagram
class CompactedAttestation {
-parent_block_id: BlockIdentifier
-envelope_hash: AckiNackiEnvelopeHash
-aggregated_signature: Signature
-signature_occurrences: BTreeMap<SignerIndex, u16>
-target_type: AttestationTargetType
+signers(): Iterator<SignerIndex>
}
class Envelope {
<<generic>>
+create()
}
class CompactedMapKey {
+block_identifier()
+block_seq_no()
}
CompactedAttestation --> "1" Envelope : converts to/from
CompactedAttestation --> "1" CompactedMapKey : uses in conversion