block_index.rs

Overview

The block_index.rs file defines the BlockIndex struct, which serves as a concise representation of a block's identity within a blockchain or distributed ledger system. It encapsulates two key attributes: the block's sequence number (block_seq_no) and its unique identifier (block_identifier). This struct is designed to enable efficient indexing, comparison, and retrieval of blocks.

The file also provides implementations to construct a BlockIndex from other blockchain data structures, as well as traits to support ordering and comparison operations between instances of BlockIndex. This functionality is essential for sorting blocks and ensuring consistent ordering in block processing workflows.

Structs and Implementations

BlockIndex

Description

BlockIndex is a data structure containing minimal identifying information about a block:

• block_seq_no: Represents the sequence number of the block, which currently corresponds to the block's position in the blockchain but is noted to be changed to represent the block height in the future.

• block_identifier: A unique identifier for the block, typically a hash or similar cryptographic identifier.

The struct derives several traits to facilitate cloning, debugging, equality checks, serialization, and deserialization. It also uses the Getters derive macro to automatically generate getter methods for its fields.

Fields

Methods

• new(seq_no: BlockSeqNo, identifier: BlockIdentifier) -> Self

  Constructs a new BlockIndex instance using the provided sequence number and block identifier.

  Parameters:

  • seq_no: The sequence number of the block.

  • identifier: The unique identifier of the block.

  Returns:

  • A new BlockIndex instance.

  Example:

  let seq_no = BlockSeqNo::from(42);
  let identifier = BlockIdentifier::new(...);
  let block_index = BlockIndex::new(seq_no, identifier);
  

Trait Implementations

Conversion from Envelope<GoshBLS, AckiNackiBlock> to BlockIndex

impl From<&Envelope<GoshBLS, AckiNackiBlock>> for BlockIndex

• Converts a reference to an Envelope wrapping a AckiNackiBlock into a BlockIndex.

• Extracts the sequence number and block identifier from the inner AckiNackiBlock data.

• Enables seamless construction of a BlockIndex from blockchain message envelopes.

Usage:

let envelope: Envelope<GoshBLS, AckiNackiBlock> = ...;
let block_index: BlockIndex = BlockIndex::from(&envelope);

Ordering Traits: PartialOrd and Ord

• PartialOrd and Ord are implemented to allow comparison and sorting of BlockIndex instances.

• The comparison is primarily based on the block sequence number (block_seq_no).

• If sequence numbers are equal, the ordering is determined by comparing the block identifiers via BlockIdentifier::compare.

Implementation Detail:

• partial_cmp returns the full ordering result by delegating to cmp.

• cmp first compares sequence numbers; if they are equal, it calls BlockIdentifier::compare for tie-breaking.

Usage Example:

let index1 = BlockIndex::new(seq_no1, id1);
let index2 = BlockIndex::new(seq_no2, id2);

if index1 < index2 {
    // index1 precedes index2 in blockchain order
}

Implementation Details

• The use of the derive_getters crate simplifies access to private fields without exposing them for mutation.

• Serialization and deserialization are supported via serde traits, enabling easy storage or network transmission of BlockIndex instances.

• The sequence number field is currently named block_seq_no but is planned to be updated to represent block height, which aligns with blockchain terminology for block positioning.

• The ordering implementation ensures deterministic ordering of blocks, which is critical for consensus and validation processes.

Interactions with Other Modules

• Envelope and BLSSignedEnvelope: These types represent signed messages or blocks in the system. BlockIndex can be derived from an Envelope containing an AckiNackiBlock, facilitating indexing of blocks received or processed as envelopes.

• AckiNackiBlock: This is the block data type encapsulated by envelopes. BlockIndex extracts sequence number and identifier from it.

• BlockSeqNo and BlockIdentifier: These types are used as the core components of BlockIndex. Their implementations provide ordering and comparison methods utilized by BlockIndex.

• GoshBLS: A cryptographic scheme (likely BLS signatures) used in envelopes; referenced here to specify the type of envelope.

This file thus forms a bridge between raw block data (AckiNackiBlock), its envelope representation, and the indexing and ordering logic essential for block management in the system.

Diagram: Structure of block_index.rs

classDiagram
class BlockIndex {
-block_seq_no: BlockSeqNo
-block_identifier: BlockIdentifier
+new()
+block_seq_no()
+block_identifier()
+cmp()
}
BlockIndex ..> BlockSeqNo : uses
BlockIndex ..> BlockIdentifier : uses
BlockIndex ..> Envelope : From<&Envelope<GoshBLS, AckiNackiBlock>>

This diagram illustrates the core BlockIndex struct with its fields and main constructor, as well as its relationships with other types used in this file.