common_section.rs

Overview

This file defines the CommonSection struct along with its associated types and functionality, which encapsulates common metadata and state information related to blocks within the system. It handles data such as block height, round, producer identification, attestations, acknowledgments, and references to other blocks. Serialization and deserialization logic are implemented to support efficient persistence and transmission of this data. The file also defines the Directives struct, which contains optional sharing state resources that can be referenced by thread identifiers.

The CommonSection is a core data structure used within the block processing and consensus mechanisms, interacting with components like block keepers, cryptographic envelopes, and node identification. It supports conditional compilation features such as monitoring account differences.

Detailed Entities and Components

Directives Struct

Description

Directives encapsulates optional instructions or resource sharing information related to block processing. It currently holds an optional map, share_state_resources, which associates ThreadIdentifiers with corresponding BlockIdentifiers.

Fields

• share_state_resources: Option<HashMap<ThreadIdentifier, BlockIdentifier>>
  An optional mapping specifying shared state resources by thread.

Traits and Derivations

• Clone, Default, Serialize, Deserialize, PartialEq, Eq, TypedBuilder, Getters

• Implements Debug with a custom formatter showing the share_state_resources field.

Usage Example

let directives = Directives::default();
if let Some(resources) = directives.share_state_resources() {
    // Process shared state resources
}

CommonSection Struct

Description

CommonSection aggregates essential metadata and state references for a blockchain block. It is intended to be embedded or used as part of larger block-related structures, holding attestations, acknowledgments, references, threading information, and other consensus-related data.

Fields

Methods on CommonSection

new

pub fn new(
    thread_id: ThreadIdentifier,
    round: BlockRound,
    producer_id: NodeIdentifier,
    block_keeper_set_changes: Vec<BlockKeeperSetChange>,
    verify_complexity: SignerIndex,
    refs: Vec<BlockIdentifier>,
    threads_table: Option<ThreadsTable>,
    block_height: BlockHeight,
    #[cfg(feature = "monitor-accounts-number")] accounts_number_diff: i64,
) -> Self

Description

Constructs a new CommonSection instance initializing all core fields, with empty vectors for attestations, acks, and nacks, and default Directives.

Parameters

• thread_id: The thread identifier for this block.

• round: The consensus round number.

• producer_id: Node identifier of the block producer.

• block_keeper_set_changes: Vector of changes in block keeper sets.

• verify_complexity: Expected complexity for verification (ack/nack count).

• refs: References to other blocks this block depends on.

• threads_table: Optional snapshot of the threads table at this block.

• block_height: The height of this block.

• accounts_number_diff: (If feature enabled) the difference in account count.

Returns

• A new instance of CommonSection.

Usage Example

let common_section = CommonSection::new(
    thread_id,
    round,
    producer_id,
    vec![],
    verify_complexity,
    vec![],
    None,
    block_height,
    #[cfg(feature = "monitor-accounts-number")]
    0,
);

wrap_serialize

fn wrap_serialize(&self) -> WrappedCommonSection

Description

Prepares a serializable wrapper struct WrappedCommonSection by serializing internal vectors (block_attestations, acks, nacks) into byte arrays using bincode. This method handles conditional compilation fields appropriately.

Returns

• A WrappedCommonSection struct with serialized data and other copied fields.

Implementation Detail

• Uses bincode::serialize for efficient binary serialization of the envelopes.

• Asserts the presence of the producer_selector before serialization.

wrap_deserialize

fn wrap_deserialize(data: WrappedCommonSection) -> Self

Description

Deserializes a WrappedCommonSection back into a CommonSection by decoding the serialized byte arrays (block_attestations, acks, nacks) and reconstructing all fields.

Parameters

• data: A WrappedCommonSection instance with serialized internal data.

Returns

• A fully deserialized CommonSection.

Implementation Detail

• Uses bincode::deserialize to convert byte arrays back to vectors of envelopes.

• Handles conditional compilation fields accordingly.

WrappedCommonSection Struct

Description

A private helper struct used to facilitate the custom serialization and deserialization logic for CommonSection. It stores serialized byte arrays for attestations, acknowledgments, and negative acknowledgments.

Fields

Trait Implementations

Serialize for CommonSection

• Delegates serialization to wrap_serialize producing a WrappedCommonSection which is then serialized.

• Ensures all internal data is correctly serialized in a consistent format.

Deserialize for CommonSection

• Deserializes into a WrappedCommonSection and uses wrap_deserialize to obtain a CommonSection.

Debug for CommonSection and Directives

• Custom implementations that list main fields for easy debugging.

• Adjusts fields shown depending on the feature flag monitor-accounts-number.

Implementation Details and Algorithms

• The serialization strategy uses an internal wrapper struct WrappedCommonSection to handle complex fields like vectors of cryptographic envelopes by serializing them to byte arrays with bincode. This approach ensures compact and efficient serialization while encapsulating the complexity.

• Conditional compilation (cfg(feature = "monitor-accounts-number")) is used to optionally include account monitoring data without affecting other use cases.

• The CommonSection struct is designed to be extensible and is tightly integrated with cryptographic and consensus-related data types such as Envelope<GoshBLS, T>, BlockKeeperSetChange, and producer selectors.

• The refs field supports cross-thread and inter-block dependencies, which is crucial for multi-threaded blockchain architectures. This aligns with topics in Threads and Thread Identifiers and Block Dependencies.

• The verify_complexity field relates to the expected number of acknowledgments/nacks, supporting verification complexity estimation in consensus algorithms, linked to Consensus Verification.

Interactions with Other System Components

• Block Keeper System: The block_keeper_set_changes field interfaces with Block Keeper System to track changes in sets responsible for block validation or storage.

• Cryptographic Envelopes: Uses Envelope from BLS Cryptography Module for attestations, acknowledgments, and negative acknowledgments, ensuring data authenticity and non-repudiation.

• Node Identification and Signers: Fields like producer_id and verify_complexity utilize types from Node Management such as NodeIdentifier and SignerIndex.

• Threading Model: thread_id, refs, and threads_table connect with the system’s threading model, supporting parallel block processing and cross-thread message passing.

• Producer Selection: The optional producer_selector integrates with producer election or selection logic as found in Producer Selector Module.

Mermaid Diagram: Structure of common_section.rs

classDiagram
class Directives {
+share_state_resources: Option<HashMap<ThreadIdentifier, BlockIdentifier>>
+default()
+clone()
}
Directives ..> HashMap
Directives ..> ThreadIdentifier
Directives ..> BlockIdentifier
class CommonSection {
+block_height: BlockHeight
+directives: Directives
+block_attestations: Vec<Envelope<GoshBLS, AttestationData>>
+round: BlockRound
+producer_id: NodeIdentifier
+thread_id: ThreadIdentifier
+threads_table: Option<ThreadsTable>
+refs: Vec<BlockIdentifier>
+block_keeper_set_changes: Vec<BlockKeeperSetChange>
+verify_complexity: SignerIndex
+acks: Vec<Envelope<GoshBLS, AckData>>
+nacks: Vec<Envelope<GoshBLS, NackData>>
+producer_selector: Option<ProducerSelector>
+accounts_number_diff: i64 (optional)
+new()
-wrap_serialize()
-wrap_deserialize()
}
CommonSection --> Directives
CommonSection --> Envelope
CommonSection --> BlockKeeperSetChange
CommonSection --> ProducerSelector
CommonSection --> ThreadsTable
CommonSection --> ThreadIdentifier
CommonSection --> BlockIdentifier
CommonSection --> NodeIdentifier

This diagram illustrates the main data structures and their relationships in common_section.rs, emphasizing the composition of CommonSection and its dependencies on other system types.