block.rs

Overview

This file defines data structures and conversion logic related to blockchain blocks, specifically for archival and serialization purposes. It focuses on representing block metadata, references to external blocks, and the flow of values within blocks. The primary struct, ArchBlock, serves as a comprehensive container for block-related information, facilitating conversions from database rows and serialized block data formats. It integrates with blockchain-specific types and serialization utilities, enabling interoperability between the database layer and the internal representation of blocks.

Data Structures

ExtBlkRef

A struct representing an external block reference. This includes optional fields that identify a block's sequence number, logical time, and cryptographic hashes.

• Fields:

  • seq_no: Option<i64> — The sequence number of the referenced block.

  • end_lt: Option<String> — The logical time at the end of the block, as a string.

  • file_hash: Option<String> — File hash associated with the block.

  • root_hash: Option<String> — Root hash of the block.

• Usage: Used within ArchBlock as references to previous blocks (prev_ref and prev_alt_ref), enabling traceability of block lineage.

BlockValueFlow

Represents the flow of values (e.g., tokens or currency units) within a block, including creation, export, import, and fees.

• Fields:

  • created: Option<String>

  • exported: Option<String>

  • fees_collected: Option<String>

  • fees_imported: Option<String>

  • imported: Option<String>

  • minted: Option<String>

  • recovered: Option<String>

• Note: All fields are optional and store hexadecimal string representations of value amounts.

ArchBlock

The central struct representing an archived blockchain block with extensive metadata fields.

• Fields:

  • id: String — Unique block identifier (hex string).

  • status: u8 — Block status code.

  • seq_no: u32 — Block sequence number.

  • parent: String — Parent block ID.

  • aggregated_signature: Option<Vec<u8>> — Optional aggregated signature bytes.

  • signature_occurrences: Option<Vec<u8>> — Optional signature occurrences bytes.

  • share_state_resource_address: Option<String>

  • global_id: Option<i64>

  • version: Option<i64>

  • after_merge, before_split, after_split, want_merge, want_split, key_block: Optional booleans describing block state flags.

  • flags: Option<i64>

  • shard: Option<String>

  • workchain_id: Option<i64>

  • gen_utime: Option<i64> — Generation Unix time.

  • gen_utime_ms_part: Option<i64> — Millisecond part of generation time.

  • start_lt, end_lt: Option<String> — Logical time boundaries as strings.

  • gen_validator_list_hash_short: Option<i64>

  • gen_catchain_seqno: Option<i64>

  • min_ref_mc_seqno: Option<i64>

  • prev_key_block_seqno: Option<i64>

  • gen_software_version: Option<i64>

  • gen_software_capabilities: Option<String>

  • boc: Option<Vec<u8>> — Block serialized data bytes.

  • file_hash: Option<String>

  • root_hash: Option<String>

  • prev_ref: Option<ExtBlkRef> — Reference to the previous block.

  • prev_alt_ref: Option<ExtBlkRef> — Alternative previous block reference.

  • in_msgs, out_msgs: Option<String> — Serialized inbound and outbound messages.

  • data: Option<Vec<u8>>

  • chain_order: Option<String>

  • tr_count: Option<i64> — Transaction count.

  • value_flow: Option<BlockValueFlow> — Flow of values in the block.

  • thread_id: Option<String>

  • producer_id: Option<String>

• Purpose: Serves as a canonical representation of a block's archived state, suitable for storage and serialization.

Functions and Implementations

Conversion: impl From<&Row<'_>> for ArchBlock

Constructs an ArchBlock from a SQLite database row.

• Parameters:

  • val: &Row<'_> — A reference to a database row containing block data.

• Returns:

  • An instance of ArchBlock populated with values extracted from the row.

• Details:

  • Uses Row::get to retrieve each field by index.

  • Optional fields use .ok() to gracefully handle missing columns.

  • The previous block references prev_ref and prev_alt_ref are constructed manually from sequential columns.

• Usage Example:

  let row: Row = /* fetched from database */;
  let block: ArchBlock = (&row).into();
  

Conversion: impl From<BlockSerializationSetFH> for ArchBlock

Constructs an ArchBlock from a serialized block structure BlockSerializationSetFH.

• Parameters:

  • blk: BlockSerializationSetFH — Serialized block data including raw block bytes and metadata.

• Returns:

  • An ArchBlock instance representing the block data.

• Implementation Details:

  • Computes file_hash if absent by hashing the block bytes.

  • Reads block metadata and previous block references using blockchain-specific APIs (read_info(), read_prev_ref()).

  • Serializes nested references using helper function serialize_block_ref.

  • Converts value flow details using serialize_value_flow.

  • Extracts fields such as generation time, version, shard info, flags, and software capabilities.

  • Several commented-out sections indicate potential extensions for serializing state updates, messages, and transactions, which could be activated as needed.

• Usage Example:

  let serialized_block: BlockSerializationSetFH = /* obtained from deserialization */;
  let arch_block: ArchBlock = serialized_block.into();
  

Helper Functions

serialize_block_ref

Converts a blockchain external block reference type (tvm_block::blocks::ExtBlkRef) into the module's ExtBlkRef.

• Parameters:

  • blk_ref: tvm_block::blocks::ExtBlkRef — The original block reference.

• Returns:

  • ExtBlkRef with fields converted to appropriate string and integer types.

• Usage: Used internally during conversion from serialized block data.

serialize_value_flow

Converts a blockchain internal ValueFlow type into the module's BlockValueFlow.

• Parameters:

  • value_flow: tvm_block::ValueFlow — Internal value flow data.

• Returns:

  • BlockValueFlow with hexadecimal string representations of various value amounts.

• Usage: Used internally during conversion from serialized block data.

Testing

Module: tests

• Contains a single test function test_block_deser which verifies deserialization of ArchBlock from JSON.

• Checks that the prev_ref field is correctly deserialized and not None.

• Uses serde_json to parse JSON and serde to deserialize.

Interactions with Other Modules

• rusqlite::Row for database row extraction.

• serde::{Deserialize, Serialize} for serialization and deserialization support.

• serde_with::with_prefix for handling prefixed serialization keys.

• tvm_types::UInt256 for cryptographic hash calculation and representation.

• crate::helpers::u64_to_string for formatting capabilities as strings.

• crate::serialization::BlockSerializationSetFH which represents serialized block data input.

• The file uses blockchain-specific types such as tvm_block::blocks::ExtBlkRef and tvm_block::ValueFlow for internal data extraction.

Important Implementation Details

• Uses Rust's From trait implementations for ergonomic conversion between database rows, serialized block data, and internal representations.

• Optional fields are used extensively to reflect the possibility of missing data in the database or during deserialization.

• Conversion from serialized data performs deep extraction of nested block references and value flows.

• The file hash is computed if missing, ensuring data integrity.

• Commented-out code sections hint at advanced serialization features for messages and transactions, which rely on other parts of the system.

• The use of with_prefix! macro supports prefixed serialization keys for the nested prev_ref and prev_alt_ref structures.

Diagram

classDiagram
class ExtBlkRef {
+seq_no: Option<i64>
+end_lt: Option<String>
+file_hash: Option<String>
+root_hash: Option<String>
}
class BlockValueFlow {
+created: Option<String>
+exported: Option<String>
+fees_collected: Option<String>
+fees_imported: Option<String>
+imported: Option<String>
+minted: Option<String>
+recovered: Option<String>
}
class ArchBlock {
+id: String
+status: u8
+seq_no: u32
+parent: String
+aggregated_signature: Option<Vec<u8>>
+signature_occurrences: Option<Vec<u8>>
+share_state_resource_address: Option<String>
+global_id: Option<i64>
+version: Option<i64>
+after_merge: Option<bool>
+before_split: Option<bool>
+after_split: Option<bool>
+want_merge: Option<bool>
+want_split: Option<bool>
+key_block: Option<bool>
+flags: Option<i64>
+shard: Option<String>
+workchain_id: Option<i64>
+gen_utime: Option<i64>
+gen_utime_ms_part: Option<i64>
+start_lt: Option<String>
+end_lt: Option<String>
+gen_validator_list_hash_short: Option<i64>
+gen_catchain_seqno: Option<i64>
+min_ref_mc_seqno: Option<i64>
+prev_key_block_seqno: Option<i64>
+gen_software_version: Option<i64>
+gen_software_capabilities: Option<String>
+boc: Option<Vec<u8>>
+file_hash: Option<String>
+root_hash: Option<String>
+prev_ref: Option<ExtBlkRef>
+prev_alt_ref: Option<ExtBlkRef>
+in_msgs: Option<String>
+out_msgs: Option<String>
+data: Option<Vec<u8>>
+chain_order: Option<String>
+tr_count: Option<i64>
+value_flow: Option<BlockValueFlow>
+thread_id: Option<String>
+producer_id: Option<String>
}
ArchBlock o-- ExtBlkRef : "prev_ref, prev_alt_ref"
ArchBlock o-- BlockValueFlow : "value_flow"