account.rs

Overview

The account.rs file provides the data structures and serialization logic for representing blockchain accounts in an archival format. It defines a serializable struct, ArchAccount, which encapsulates the account's state and metadata in a format suitable for storage or transmission. The file includes conversion implementations from internal serialization sets to ArchAccount, utility functions for encoding account status, and address construction based on workchain and account identifiers.

Structs and Data Types

ArchAccount

A serializable and deserializable struct representing an archived view of a blockchain account.

pub struct ArchAccount {
    pub id: String,
    pub workchain_id: i32,
    pub boc: Option<Vec<u8>>,
    pub init_code_hash: Option<String>,
    pub last_paid: Option<u32>,
    pub bits: Option<String>,
    pub cells: Option<String>,
    pub public_cells: Option<String>,
    pub last_trans_lt: Option<String>,
    pub last_trans_hash: Option<String>,
    pub balance: Option<String>,
    pub balance_other: Option<Vec<u8>>,
    pub code: Option<Vec<u8>>,
    pub code_hash: Option<String>,
    pub data: Option<Vec<u8>>,
    pub data_hash: Option<String>,
    pub acc_type: u8,
    pub last_trans_chain_order: Option<String>,
    pub dapp_id: String,
    pub due_payment: Option<String>,
    pub proof: Option<Vec<u8>>,
    pub prev_code_hash: Option<String>,
    pub state_hash: Option<String>,
    pub split_depth: Option<u32>,
}

• id: Account address as a string.

• workchain_id: Identifier for the workchain the account belongs to.

• boc: Optional serialized Bag of Cells (BOC) representing the account data.

• init_code_hash: Optional hex string of the initial code hash.

• last_paid: Optional Unix timestamp of the last payment.

• bits, cells, public_cells: Optional string representations of storage usage metrics.

• last_trans_lt: Optional string representing the logical time of the last transaction.

• last_trans_hash: Optional hash of the last transaction.

• balance: Optional hexadecimal string of the account balance in nanograms.

• balance_other: Optional serialized other balance data.

• code, code_hash: Optional binary and hash of the account code.

• data, data_hash: Optional binary and hash of the account data.

• acc_type: Encoded account status as a u8.

• last_trans_chain_order: Optional transaction chain order.

• dapp_id: DApp identifier as a hex string or "None".

• due_payment: Optional due payment amount as a hexadecimal string.

• proof: Optional serialized proof data.

• prev_code_hash: Optional previous code hash.

• state_hash: Optional state hash for frozen accounts.

• split_depth: Optional split depth of the state.

The struct derives Deserialize, Serialize, Clone, Debug, and Default traits for JSON (de)serialization and cloning purposes.

Trait Implementations

From<AccountSerializationSet> for ArchAccount

Converts an AccountSerializationSet (an internal representation of an account plus serialized data) into an ArchAccount.

Process:

• Extracts the account address and converts it to string.

• Serializes the account status using serialize_account_status.

• Assigns BOC, DApp ID, initial code hash, and transaction logical time.

• Extracts and formats storage statistics (last paid, bits, cells, public cells).

• Serializes and formats balance and other balance data.

• For active accounts, serializes and stores code and data cells (if not pruned).

• For frozen accounts, stores the frozen state hash.

• Logs an error if the account status is non-existent during serialization.

Usage Example:

let arch_account: ArchAccount = account_serialization_set.into();

From<DeletedAccountSerializationSet> for ArchAccount

Converts a DeletedAccountSerializationSet (representation of a deleted account) into an ArchAccount.

Process:

• Constructs the account address using construct_address from workchain ID and account ID.

• Sets the account type to non-existent.

• Includes the previous code hash if available.

• Other fields remain as defaults.

Usage Example:

let deleted_arch_account: ArchAccount = deleted_account_serialization_set.into();

Functions

serialize_account_status

pub(crate) fn serialize_account_status(status: &AccountStatus) -> u8

Encodes an AccountStatus enum into a compact u8 representation.

Parameters:

• status: Reference to an AccountStatus enum.

Returns:

• u8 compact representation of the account status.

Example:

let encoded = serialize_account_status(&AccountStatus::AccStateActive);
// encoded == 1

construct_address

pub(crate) fn construct_address(
    workchain_id: i32,
    account_id: AccountId,
) -> anyhow::Result<MsgAddressInt>

Constructs a MsgAddressInt (message address) from a workchain ID and an account ID.

Implementation Details:

• If the workchain ID is in the range [-128, 127] and the account_id has 256 remaining bits, uses with_standart constructor.

• Otherwise, uses with_variant constructor.

• Returns an error if address construction fails.

Parameters:

• workchain_id: 32-bit signed integer identifier of the workchain.

• account_id: An AccountId struct representing the account identifier.

Returns:

• Result<MsgAddressInt, anyhow::Error>: On success, returns the constructed MsgAddressInt; otherwise, an error.

Example:

let addr = construct_address(0, account_id)?;
println!("{}", addr.to_string());

Important Implementation Notes

• Account serialization distinguishes between different account statuses (active, frozen, uninitialized, non-existent) and serializes their corresponding fields accordingly.

• For active accounts, code and data cells are serialized only if they are not pruned.

• Balance is stored both as a hexadecimal string and as serialized "other" balance data.

• The DApp ID is converted to a hex string if present; otherwise, it defaults to "None".

• last_trans_lt stores the last transaction logical time as a string via a helper function u64_to_string.

• prev_code_hash and state_hash are optional and stored as hex strings.

• Errors during serialization, especially for non-existent accounts, are logged using the tracing crate.

• The file uses types and functions from external crates like tvm_block and tvm_types, including AccountStatus, MsgAddressInt, AccountId, and serialization helpers.

• The write_boc function serializes cells into BOC format.

• AccountSerializationSet and DeletedAccountSerializationSet are intermediary structures from other parts of the system representing accounts and their serialized forms.

Interaction with Other Modules

• tvm_block Module: Provides core types such as AccountStatus, MsgAddressInt, and traits like Serializable.

• tvm_types Module: Contains types and serialization functions like AccountId and write_boc.

• crate::helpers Module: Supplies utility functions such as u64_to_string for formatting numeric values.

• crate::serialization Module: Defines AccountSerializationSet and DeletedAccountSerializationSet used as input for conversion into ArchAccount.

• The file acts as a bridge between internal account representations and archival JSON or BOC serializations, facilitating persistence or network transmission.

Visual Diagram: Class Diagram for ArchAccount and Related Conversions

classDiagram
class ArchAccount {
+id: String
+workchain_id: i32
+boc: Option<Vec<u8>>
+init_code_hash: Option<String>
+last_paid: Option<u32>
+bits: Option<String>
+cells: Option<String>
+public_cells: Option<String>
+last_trans_lt: Option<String>
+last_trans_hash: Option<String>
+balance: Option<String>
+balance_other: Option<Vec<u8>>
+code: Option<Vec<u8>>
+code_hash: Option<String>
+data: Option<Vec<u8>>
+data_hash: Option<String>
+acc_type: u8
+last_trans_chain_order: Option<String>
+dapp_id: String
+due_payment: Option<String>
+proof: Option<Vec<u8>>
+prev_code_hash: Option<String>
+state_hash: Option<String>
+split_depth: Option<u32>
}
class AccountSerializationSet
class DeletedAccountSerializationSet
class AccountStatus
AccountSerializationSet --> ArchAccount : From trait (conversion)
DeletedAccountSerializationSet --> ArchAccount : From trait (conversion)
AccountStatus ..> ArchAccount : acc_type encoded by serialize_account_status()

References to Related Topics

• For details on the AccountStatus enum and its variants, see Account Status.

• Serialization and deserialization mechanisms involving BOC format are detailed in BOC Serialization.

• Address construction and message address representation are covered under Addressing.

• For the internal structures AccountSerializationSet and DeletedAccountSerializationSet, see Account Serialization Sets.

• Utility functions for data formatting like u64_to_string are explained in Helper Functions.