mod.rs

Overview

This file defines the AckiNackiBlock struct which encapsulates a blockchain block representation enriched with a CommonSection metadata structure and additional auxiliary data. It provides methods for block construction, hash verification, serialization/deserialization, and access to block-related metadata such as identifiers, sequence numbers, and references to parent blocks. The file also manages interactions with the underlying TVM block structure (tvm_block::Block), handling serialization and hash calculations essential for block validation and replication.

The AckiNackiBlock integrates tightly with other components managing the blockchain's threading model, block referencing, and cryptographic verification. Key dependencies include the CommonSection for block metadata, cryptographic hashing utilities (Sha256Hash), and block serialization utilities from the tvm_block and tvm_types crates.

Modules

• as_signatures_map: Likely handles signature mappings related to the blocks.

• common_section: Defines the CommonSection struct used extensively for block metadata.

• envelope_hash: Presumably manages hash envelopes for blocks.

• hash: Contains hashing utilities and implementations like calculate_hash.

• parse_block_accounts_and_messages (private): Handles parsing of block accounts and messages.

• serialize (private): Handles serialization logic related to blocks.

The file publicly re-exports the compare_hashes function from the hash module for external comparison of block hashes.

Constants

• BLOCK_SUFFIX_LEN: usize = 32

  Defines the fixed length of the block suffix used during hash verification, corresponding to the size of the SHA-256 hash.

Struct: AckiNackiBlock

Encapsulates a blockchain block along with its metadata and auxiliary serialized data.

Fields

• common_section: CommonSection
  Metadata section containing information such as thread ID, round, producer ID, etc.

• block: tvm_block::Block
  The underlying TVM block structure representing the core block data.

• tx_cnt: usize
  Number of transactions within the block.

• hash: Sha256Hash
  SHA-256 hash of the block data, used for integrity verification.

• raw_data: Option<Vec<u8>>
  Optional raw serialized block data, including the common section and block.

• block_cell: Option<Cell>
  Optional serialized cell representation of the block for efficient storage and transmission.

Trait Implementations

• Display

  Provides a human-readable string representation of the block for logging or display, including sequence number, block ID, transaction count, hash (in debug format), timestamp, common section, and parent block.

• Debug

  Provides a concise debug representation showing only the sequence number and block identifier.

Methods

new

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

Constructs a new AckiNackiBlock instance by initializing the common_section with the provided metadata and storing the provided TVM block and transaction count. The hash is initialized to zero and raw data is not precomputed.

• Parameters:

  • thread_id: Identifier of the blockchain thread this block belongs to.

  • block: The underlying TVM block structure.

  • producer_id: Node identifier of the block producer.

  • tx_cnt: Number of transactions in the block.

  • block_keeper_set_changes: Changes related to block keeper sets.

  • verify_complexity: Complexity indicator for signer verification.

  • refs: List of references to other blocks.

  • threads_table: Optional thread table indicating thread relationships.

  • round: Block round number.

  • block_height: Height of the block in the chain.

  • accounts_number_diff: (Optional) Change in accounts number, enabled via feature flag.

• Returns:
  A new instance of AckiNackiBlock.

• Usage Example:

let acki_block = AckiNackiBlock::new(
    thread_id,
    tvm_block,
    producer_id,
    tx_count,
    block_keeper_changes,
    verify_complexity,
    refs,
    Some(threads_table),
    round,
    block_height,
    #[cfg(feature = "monitor-accounts-number")]
    accounts_number_diff,
);

raw_block_data

pub fn raw_block_data(&self) -> anyhow::Result<(Vec<u8>, Cell)>

Retrieves the raw serialized block data and its corresponding Cell representation. It attempts to reuse cached raw data and Cell if present; otherwise, it serializes the block anew.

• Returns:
  A tuple of (Vec<u8>, Cell) representing the raw block data bytes and its serialized cell form.

• Errors:
  Returns an error if serialization or writing the cell to bytes fails.

• Implementation Details:
  The method carefully parses the raw_data buffer to extract portions corresponding to the common section and the block itself, utilizing byte length fields stored in big-endian format to split the data correctly.

parent

pub fn parent(&self) -> BlockIdentifier

Returns the identifier of the parent block by reading the previous reference from the TVM block info.

• Returns:
  The BlockIdentifier of the previous block.

parent_seq_no

pub fn parent_seq_no(&self) -> BlockSeqNo

Returns the sequence number of the parent block by reading it from the TVM block info.

• Returns:
  The BlockSeqNo of the parent block.

identifier

pub fn identifier(&self) -> BlockIdentifier

Returns the identifier of the current block computed as the hash of the underlying TVM block.

• Returns:
  The BlockIdentifier of this block.

seq_no

pub fn seq_no(&self) -> BlockSeqNo

Returns the sequence number of the current block.

• Returns:
  The BlockSeqNo of this block.

directives

pub fn directives(&self) -> Directives

Returns the directives contained in the common_section of the block.

• Returns:
  A clone of the Directives struct from the common section.

check_hash

pub fn check_hash(&self) -> anyhow::Result<bool>

Verifies that the stored hash matches the hash computed from the raw block data.

• Returns:
  Ok(true) if the hash matches, Ok(false) if it does not.

• Errors:
  Returns an error if the hash calculation fails.

• Implementation Details:
  The method uses either cached raw_data or serializes the block to obtain the data to hash. It excludes the hash suffix bytes when recalculating the hash. Debug-level tracing logs are emitted at various stages for diagnostics.

get_hash

pub fn get_hash(&self) -> Sha256Hash

Returns the current SHA-256 hash of the block.

• Returns:
  The Sha256Hash value.

get_common_section

pub fn get_common_section(&self) -> &CommonSection

Returns a reference to the block's CommonSection.

• Returns:
  Reference to the CommonSection.

set_common_section

pub fn set_common_section(
    &mut self,
    common_section: CommonSection,
    update_hash: bool,
) -> anyhow::Result<()>

Updates the block's CommonSection and optionally recalculates and updates the block hash and raw serialized data.

• Parameters:

  • common_section: The new CommonSection to set.

  • update_hash: Boolean indicating whether to update the hash and raw data after setting.

• Returns:
  Empty result on success.

• Errors:
  Returns an error if serialization or hash calculation fails.

• Implementation Details:
  To optimize performance, hash recalculation and raw data serialization are deferred until explicitly requested (update_hash == true). Special logic enabled under the feature flag nack_test can simulate a fake block by resetting the hash and raw data for specific sequence numbers and producer nodes.

is_thread_splitting

pub fn is_thread_splitting(&self) -> bool

Determines whether the current block causes a thread splitting event.

• Returns:
  true if the block spawns a new thread as indicated by the threads_table entries; false otherwise.

• Implementation Details:
  The method checks the optional threads_table in the common_section and iterates over its rows to see if the block identifier is recognized as a spawning block for any thread.

tvm_block

pub fn tvm_block(&self) -> &tvm_block::Block

Returns a reference to the underlying TVM block.

• Returns:
  Reference to the tvm_block::Block.

tx_cnt

pub fn tx_cnt(&self) -> usize

Returns the count of transactions in the block.

• Returns:
  Number of transactions (usize).

time

pub fn time(&self) -> anyhow::Result<u64>

Returns the timestamp of block generation in milliseconds.

• Returns:
  Timestamp as u64.

• Errors:
  Returns an error if reading block info fails.

• Implementation Details:
  Reads the generation time (gen_utime_ms) from the TVM block's info struct.

Important Implementation Details and Algorithms

• Hash Calculation and Verification:
  The block hash is a SHA-256 digest calculated over the serialized block data excluding the hash suffix itself. The method check_hash ensures block integrity by recalculating this hash and comparing it with the stored hash.

• Serialization Handling:
  The block utilizes both a raw data buffer (raw_data) and a TVM Cell structure (block_cell) for serialized representations. These are used interchangeably depending on availability to optimize serialization operations.

• CommonSection Integration:
  The CommonSection carries critical metadata, including threading information, references, and producer details. It is tightly coupled with block identity and validation.

• Thread Splitting Detection:
  The block can represent thread-splitting events, evaluated by checking the threads_table in the CommonSection for spawning blocks.

Interaction with Other System Components

• tvm_block:
  The block relies on the TVM Block type for core block data storage, manipulation, and serialization.

• CommonSection:
  The block metadata and threading information are managed in the common_section module, which is integral for block context.

• Hashing Utilities:
  Uses SHA-256 hashing functions from the hash module to ensure block data integrity.

• BlockKeeperSetChange:
  Tracks modifications to block keeper sets, which likely affect block validation and consensus.

• Node Identifier and Signer Index:
  Used to identify block producers and verify signatures, tying into node and consensus mechanisms.

• ThreadsTable and ThreadIdentifier:
  Used for managing multi-threaded blockchain structures and detecting thread splitting.

• Serialization Utilities:
  Uses write_boc and Cell from tvm_types for block serialization to and from the Bag of Cells (BOC) format.

Visual Diagram: AckiNackiBlock Class Structure

classDiagram
class AckiNackiBlock {
-common_section: CommonSection
-block: tvm_block::Block
-tx_cnt: usize
-hash: Sha256Hash
-raw_data: Option<Vec<u8>>
-block_cell: Option<Cell>
+new()
+raw_block_data()
+parent()
+parent_seq_no()
+identifier()
+seq_no()
+directives()
+check_hash()
+get_hash()
+get_common_section()
+set_common_section()
+is_thread_splitting()
+tvm_block()
+tx_cnt()
+time()
}
AckiNackiBlock --> CommonSection : contains
AckiNackiBlock --> "tvm_block::Block" : contains
AckiNackiBlock --> Sha256Hash : contains
AckiNackiBlock --> Vec<u8> : optionally contains
AckiNackiBlock --> Cell : optionally contains

This diagram illustrates the main structure of AckiNackiBlock, showing its fields and methods, as well as its relationships to key types like CommonSection, tvm_block::Block, Sha256Hash, and serialization buffers.

For further details on the hashing mechanisms, see hash and for the metadata structure, refer to CommonSection. Interaction with the thread model is elaborated under ThreadsTable and ThreadIdentifier. Serialization and TVM block internals are documented in tvm_block and serialize.