serialize.rs

Overview

This file implements serialization and deserialization logic for the AckiNackiBlock data structure. It provides methods to convert the block into raw byte arrays including and excluding the hash, and integrates with Rust's serde framework to support transparent serialization and deserialization. The serialization process carefully encodes constituent parts of the block such as the common section, the TVM block, transaction count, and the block hash. The deserialization process reverses this, reconstructing the full AckiNackiBlock instance from raw bytes.

The file relies on external crates and modules like serde for serialization traits, tvm_block for handling TVM blocks, and tvm_types for encoding and decoding BOC (Bag of Cells) cells. It also references internal modules such as common_section and the main AckiNackiBlock definition.

Detailed Explanation

AckiNackiBlock::get_raw_data_without_hash(&self) -> anyhow::Result<Vec<u8>>

• Purpose:
  Produces a serialized byte vector representing the AckiNackiBlock data excluding the block hash.

• Functionality:

  1. Serializes the common_section field using bincode.

  2. Prefixes the serialized common_section with its length encoded as an 8-byte big-endian integer.

  3. Serializes the block field (a TVM block) using the serialize() method from the tvm_block crate.

  4. Encodes the serialized TVM block into a BOC format using write_boc, prefixes it with its length as 8-byte BE integer.

  5. Appends the transaction count (tx_cnt) as an 8-byte BE integer.

  6. Returns the assembled byte vector.

• Parameters:

  • &self: Reference to the AckiNackiBlock instance.

• Returns:

  • anyhow::Result<Vec<u8>>: Serialized byte vector on success, or an error on failure.

• Example Usage:

  let raw_data = acki_nacki_block.get_raw_data_without_hash()?;
  

• Implementation Details:
  This method uses length-prefixed encoding to maintain clear boundaries between serialized sections, ensuring safe parsing during deserialization.

impl Serialize for AckiNackiBlock

• Purpose:
  Implements the serde::Serialize trait to allow AckiNackiBlock instances to be serialized using any serde serializer.

• Method:

  • serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    Serializes the block into bytes and passes them to the provided serializer.

• Behavior:

  • If the optional raw_data field is present, it serializes that data directly.

  • Otherwise, it calls get_raw_data_without_hash to obtain raw bytes (excluding hash), appends the block hash, and serializes the complete data.

• Parameters:

  • &self: The block instance.

  • serializer: A generic serializer implementing serde::Serializer.

• Returns:

  • Result of the serialization operation.

• Error Handling:
  Converts internal errors into serde serialization errors with custom messages.

• Usage:
  Enables seamless integration with any serde-based serialization format (e.g., JSON, CBOR, binary).

impl<'de> Deserialize<'de> for AckiNackiBlock

• Purpose:
  Implements the serde::Deserialize trait to reconstruct an AckiNackiBlock from serialized bytes.

• Method:

  • deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    Reads bytes from the deserializer and parses them into the AckiNackiBlock fields.

• Deserialization Workflow:

  1. Deserialize raw bytes into a Vec<u8>.

  2. Extract the first 8 bytes as the length of the common_section and parse the section using bincode.

  3. Extract the next 8 bytes as the length of the TVM block data, decode the BOC using read_single_root_boc, and construct the TVM block.

  4. Extract the next 8 bytes as the transaction count (tx_cnt).

  5. Extract the remaining 32 bytes as the block hash.

  6. Validate lengths and construct the final AckiNackiBlock instance with all fields filled, including cached raw data and the serialized TVM block cell.

• Parameters:

  • deserializer: A generic deserializer implementing serde::Deserializer.

• Returns:

  • Result<Self, D::Error>: The reconstructed AckiNackiBlock or an error if deserialization fails.

• Error Handling:
  Custom error messages are returned for each failure point, including length parsing, decoding, and field extraction.

• Usage:
  Allows instantiation of AckiNackiBlock from raw serialized data for network transmission, storage, or inter-process communication.

Important Implementation Details and Algorithms

• The serialization format is custom and consists of concatenated fields each prefixed with their length encoded as 8-byte big-endian integers. This design aids in robust and unambiguous parsing.

• The block's TVM cell serialization leverages tvm_block and tvm_types crates for domain-specific encoding in BOC format.

• The cached raw_data field is used to optimize serialization by avoiding recomputation of raw bytes if they are already available.

• The deserialization method performs strict validation on lengths and expected remaining bytes to ensure data integrity.

• The block hash is handled as a fixed 32-byte array appended to the serialized raw data, separating it from the main block content serialization.

Interaction with Other Parts of the System

• AckiNackiBlock Type:
  This file extends the AckiNackiBlock struct (defined elsewhere) by implementing serialization traits and a method for obtaining raw serialized data without the hash.

• common_section::CommonSection:
  Part of the block that is serialized/deserialized using bincode within this workflow.

• tvm_block::Block and tvm_types:
  Used for serializing and deserializing the TVM block component of AckiNackiBlock. The BOC format encoding/decoding is performed here.

• Serde Framework:
  The file's implementations allow AckiNackiBlock to integrate with any serde-compatible serialization format, supporting both reading and writing.

• Tracing:
  The function get_raw_data_without_hash logs tracing information during serialization, useful for debugging.

Mermaid Diagram: Flowchart of Serialization & Deserialization Workflow

flowchart TD
A[AckiNackiBlock Instance] --> B["get_raw_data_without_hash()"]
B --> C[Serialize common_section with length prefix]
C --> D[Serialize TVM block cell with length prefix]
D --> E[Append tx_cnt as 8-byte BE]
E --> F["Return raw data bytes (excluding hash)"]
A --> G[serde Serialize trait]
G -->|If raw_data exists| H[Serialize raw_data directly]
G -->|Else| B
B --> I[Append hash bytes]
I --> J[Serialize combined bytes]
K[Deserialize raw bytes] --> L[Parse 8-byte length: common_section_len]
L --> M[Deserialize common_section]
M --> N[Parse 8-byte length: block_len]
N --> O[Read BOC and construct TVM block]
O --> P[Parse 8-byte tx_cnt]
P --> Q[Parse 32-byte hash]
Q --> R[Construct AckiNackiBlock with all fields]
classDef serialize fill:#cfe2f3,stroke:#2f5597;
classDef deserialize fill:#f4cccc,stroke:#a61c00;
B,C,D,E,F,G,H,I,J serialize
K,L,M,N,O,P,Q,R deserialize

Summary of Key Functions and Traits

For additional technical details on serialization and deserialization in Rust, refer to the Serde Serialization topic. For understanding the BOC (Bag of Cells) format and TVM block specifics, see BOC Format and TVM Block subtopics.