tvm_cell_serde.rs

Overview

This file provides serialization and deserialization logic for the tvm_types::Cell type using the serde_with crate's traits. It defines a custom format handler, CellFormat, which implements both SerializeAs and DeserializeAs traits to enable converting a Cell instance to and from a binary representation suitable for serialization frameworks supported by serde.

The serialization process converts a Cell into a binary Bag of Cells (BOC) format, while deserialization reconstructs the Cell from the BOC bytes. This allows seamless integration of Cell objects with formats like JSON, CBOR, or others that serde supports, by encoding the cell data as a byte vector.

Detailed Components

CellFormat Struct

pub struct CellFormat;

• Purpose: Acts as a marker type to implement custom serialization and deserialization for tvm_types::Cell.

• Properties: None (unit struct).

Implementation of SerializeAs for CellFormat

impl serde_with::SerializeAs<tvm_types::Cell> for CellFormat {
    fn serialize_as<S>(value: &tvm_types::Cell, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        let buffer: Vec<u8> = tvm_types::write_boc(value)
            .map_err(|e| <S as serde::Serializer>::Error::custom(format!("{e}, ")))?;
        <Vec<u8> as serde::Serialize>::serialize(&buffer, serializer)
    }
}

• Function: serialize_as

• Parameters:

  • value: Reference to the tvm_types::Cell instance to serialize.

  • serializer: A serde serializer to produce the serialized output.

• Returns: Result wrapping the success type S::Ok or a serialization error S::Error.

• Functionality:

  • Converts the Cell into a vector of bytes representing its BOC encoding using tvm_types::write_boc.

  • Handles errors by converting them into custom serialization errors.

  • Serializes the byte vector using the provided serializer.

• Usage Example:

let cell: tvm_types::Cell = ...; // some cell instance
let serialized_bytes = serde_with::SerializeAs::<tvm_types::Cell>::serialize_as(&CellFormat, &cell, serializer)?;

Implementation of DeserializeAs for CellFormat

impl<'de> serde_with::DeserializeAs<'de, tvm_types::Cell> for CellFormat {
    fn deserialize_as<D>(deserializer: D) -> Result<tvm_types::Cell, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let buffer: Vec<u8> = <Vec<u8> as serde::Deserialize>::deserialize(deserializer)?;
        let cell = tvm_types::read_single_root_boc(&buffer)
            .map_err(|e| <D as serde::Deserializer>::Error::custom(format!("{e}")))?;
        Ok(cell)
    }
}

• Function: deserialize_as

• Parameters:

  • deserializer: A serde deserializer to read the serialized input.

• Returns: Result wrapping a deserialized tvm_types::Cell or a deserialization error D::Error.

• Functionality:

  • Deserializes a vector of bytes from the input.

  • Converts the byte vector into a Cell by parsing it as a single-root BOC using tvm_types::read_single_root_boc.

  • Maps any parsing error into a custom deserialization error.

• Usage Example:

let deserialized_cell: tvm_types::Cell = serde_with::DeserializeAs::<tvm_types::Cell>::deserialize_as(&CellFormat, deserializer)?;

Important Implementation Details

• BOC Encoding/Decoding: The file relies on the tvm_types crate's functions:

  • write_boc(&Cell) -> Result<Vec<u8>, Error> serializes a cell into its BOC binary form.

  • read_single_root_boc(&[u8]) -> Result<Cell, Error> parses a BOC byte slice back into a Cell.

• Error Mapping: Serialization and deserialization errors from tvm_types are mapped into serde errors via the custom method. This integration ensures that errors flow correctly through the serde framework.

• Zero-Copy / Efficiency: The approach serializes the entire BOC as a byte vector, which is a compact and canonical representation for a Cell, suitable for network transmission or storage.

• Trait Usage: The use of serde_with::SerializeAs and DeserializeAs allows users to specify this custom format in annotations or wrapper types when serializing or deserializing structures containing Cell fields.

Interaction with Other System Components

• tvm_types Crate: This file depends heavily on the tvm_types crate for the core Cell type and BOC serialization/deserialization functions.

• serde Ecosystem: It integrates tvm_types::Cell with the serde serialization framework, enabling interoperability with various data formats (e.g., JSON, CBOR).

• serde_with Crate: Implements the SerializeAs and DeserializeAs traits from this crate to provide custom serialization logic decoupled from the original Cell type.

• Usage Context: Other parts of the application or library that handle TVM cells can use this format to serialize/deserialize cells transparently when sending over APIs, saving to files, or communicating across distributed systems.

Visual Diagram

classDiagram
class CellFormat {
+serialize_as()
+deserialize_as()
}
CellFormat ..> tvm_types::Cell : SerializeAs / DeserializeAs
CellFormat --> serde::Serializer : uses
CellFormat --> serde::Deserializer : uses
CellFormat --> Vec~u8~ : intermediate BOC format
tvm_types::Cell --> tvm_types::write_boc : serialization
tvm_types::Cell --> tvm_types::read_single_root_boc : deserialization

This diagram depicts the CellFormat struct implementing serialization and deserialization methods for the tvm_types::Cell type, using BOC binary encoding as an intermediate format. It shows dependencies on serde serializer/deserializer traits and the tvm_types functions for reading and writing BOC.