parse.rs

Overview

This file provides functionality for reading and serializing blockchain-related data structures, specifically focusing on zero state accounts and messages within a shard/thread context. It includes implementations for extracting detailed information from accounts and messages, serializing them into a transportable format, and interacting with message storage abstractions. The main focus is on the ZeroState structure, which encapsulates methods for accessing shard state data such as accounts and messages.

Key capabilities include:

• Iterating over all accounts within a shard/thread and extracting their properties.

• Iterating over all messages within a shard/thread, unpacking and serializing them.

• A dummy in-memory message storage implementation used as a stub for message retrieval during iteration.

This file interacts closely with core blockchain entities such as ThreadIdentifier, MessageIdentifier, WrappedMessage, and state-related types like StateInit. It also relies on message serialization and Base64 encoding utilities to prepare messages for external use or transport.

Structs and Traits

DummyMessageStorage

A stub implementation of the DurableStorageRead trait for messages.

• Purpose: Serves as a stand-in message storage that always returns empty results or panics on message load, effectively simulating no messages stored.

• Trait Implemented: DurableStorageRead<MessageIdentifier, Arc<WrappedMessage>>

• Methods:

  • next: Always returns Ok(None), indicating no next message key.

  • load_message: Unreachable; should not be called.

  • remaining_messages: Always returns an empty vector.

This dummy storage is used internally when iterating over messages in the zero state, as actual persistent storage is not needed or not yet implemented.

ZeroStateMessage

A serializable representation of a blockchain message in zero state.

• Fields:

  • id: String — Hash identifier of the message.

  • source: String — Hex-encoded source account ID or "None".

  • destination: String — Hex-encoded destination account ID or "None".

  • value: u128 — Amount of currency (grams) carried by the message.

  • ecc: HashMap<u32, String> — Extra currency components (keyed values associated with the message value).

  • src_dapp_id: Option<String> — Optional source decentralized application ID as hex string.

  • boc: String — Base64-encoded Bag of Cells (BOC) serialized message.

  • state_init: Option<String> — Optional Base64-encoded serialized state initialization data.

This struct provides a high-level view of message data suitable for export or further processing.

ZeroStateAccount

A serializable representation of a blockchain account in zero state.

• Fields:

  • address: String — Hex-encoded account address or "None".

  • code_hash: String — Hex-encoded hash of the account's code or "None".

  • balance: u128 — Account balance in currency units (grams).

  • dapp_id: String — Hex-encoded decentralized application ID or "None".

Represents accounts in a simplified form, focusing on identifiers, code, and balance.

impl ZeroState

The core implementation providing methods for reading accounts and messages from a zero state.

read_all_accounts

pub fn read_all_accounts(
    &mut self,
    thread_identifier: &ThreadIdentifier,
) -> anyhow::Result<Vec<ZeroStateAccount>>

• Purpose: Retrieves all accounts associated with a specified thread (shard) and returns them as a vector of ZeroStateAccount.

• Parameters:

  • thread_identifier: Identifier specifying the thread/shard to read from, referencing ThreadIdentifier.

• Returns: A Result wrapping a vector of ZeroStateAccount. Errors if account iteration fails.

• Usage:

  • Internally calls get_shard_state to access the shard state.

  • Uses iterate_accounts to traverse each account.

  • Extracts account ID, code hash, balance, and dapp ID, converting them to hex strings or "None" if missing.

• Errors: Returns an error if account iteration or reading fails.

Example

let accounts = zero_state.read_all_accounts(&thread_id)?;
for account in accounts {
    println!("Account: {}", account.address);
}

read_all_messages

pub fn read_all_messages(
    &mut self,
    thread_identifier: &ThreadIdentifier,
) -> anyhow::Result<Vec<ZeroStateMessage>>

• Purpose: Retrieves all messages queued in the zero state for the specified thread, serializes them, and returns as a vector of ZeroStateMessage.

• Parameters:

  • thread_identifier: Identifier of the thread/shard to read messages from.

• Returns: A Result wrapping a vector of ZeroStateMessage. Errors if message unpacking or serialization fails.

• Usage:

  • Obtains the current state for the thread using state(thread_identifier).

  • Clones the message queue from the state.

  • Uses a DummyMessageStorage as the message backend while iterating messages via AccountMessagesIterator.

  • For each message:

    • Unpacks with error handling.

    • Serializes the message into a BOC (Bag of Cells) format.

    • Encodes the BOC as Base64.

    • Optionally serializes and Base64-encodes the state_init if present.

    • Extracts fields for source, destination, value, ECC components, message hash, and source dapp ID.

• Errors: Fails with an error if unpacking, serialization, or encoding fails.

Example

let messages = zero_state.read_all_messages(&thread_id)?;
for msg in messages {
    println!("Message id: {}", msg.id);
}

Important Implementation Details

• Serialization and Encoding: Messages and state initialization data are serialized using the serialize() method from the Serializable trait and then encoded into Base64 strings via base64_encode. The BOC format is used as the container for serialized cells, utilizing write_boc.

• Error Handling: The methods wrap errors using the anyhow crate, providing context for failures during iteration, unpacking, serialization, or encoding.

• Dummy Storage Usage: DummyMessageStorage is a placeholder to satisfy the interface for message iteration (DurableStorageRead), indicating the file handles reading from a message queue abstraction without directly managing persistent storage here.

Interactions with Other Modules

• ZeroState: The primary struct extended by this file, providing shard state access methods.

• ThreadIdentifier: Used to specify the shard/thread context when reading accounts or messages.

• MessageIdentifier and WrappedMessage: Used in message storage and iteration.

• AccountMessagesIterator: Provides iteration capability over account messages, requiring a storage backend.

• Serialization and encoding utilities:

  • Serializable trait for serializing blockchain data structures.

  • write_boc and base64_encode for encoding serialized cells.

• Error types: LoadErr for storage reading errors.

These components collaborate to extract, serialize, and present zero state blockchain data in a structured form.

Mermaid Diagram: File Structure and Main Functions Flow

flowchart TD
ZeroState["ZeroState"]
DummyStorage["DummyMessageStorage"]
ReadAccounts["read_all_accounts()"]
ReadMessages["read_all_messages()"]
MsgIterator["AccountMessagesIterator"]
State["Shard State"]
MsgQueue["Messages Queue"]
MsgStorage["DurableStorageRead Trait"]
ZeroState --> ReadAccounts
ZeroState --> ReadMessages
ReadMessages --> MsgQueue
MsgQueue --> MsgIterator
MsgIterator --> DummyStorage
DummyStorage --> MsgStorage
ReadAccounts --> State
ReadMessages --> State

This diagram shows ZeroState as the central struct, with two main methods: read_all_accounts and read_all_messages. read_all_messages interacts with message queues and an iterator that depends on a message storage backend, represented here by DummyMessageStorage. Both methods rely on the shard state accessed through ZeroState.