message.rs

Overview

This file defines the ArchMessage struct and related functionality for representing and serializing blockchain messages within the GOSH DAO system. It provides a structured archival format for messages, capturing essential metadata, serialized content, and associated cryptographic proofs. The file also includes utility functions for extracting fee information from messages.

The primary functionality revolves around transforming raw message data, encapsulated in the MessageSerializationSet type, into the archival-friendly ArchMessage form. This transformation includes serialization of message bodies and state initialization components, as well as categorizing messages by their header types.

Structs and Functions

`ArchMessage`

A data structure representing a blockchain message archive entry. It contains identifiers, serialized message content, cryptographic hashes, metadata about message status and type, source and destination details, value and fee information, temporal markers, and optional proof and state initialization data.

Fields

Field Name	Type	Description
`id`	`String`	Unique identifier of the message, hex-encoded.
`transaction_id`	`Option<String>`	Optional transaction identifier in hex string form.
`boc`	`Option<Vec<u8>>`	Serialized Bag of Cells (BOC) representation of the entire message.
`body`	`Option<Vec<u8>>`	Serialized BOC of the message body, if present.
`body_hash`	`Option<String>`	Optional hash of the message body.
`status`	`Option<u8>`	Optional status code indicating message state.
`msg_type`	`Option<u8>`	Optional message type indicator (0 = internal, 1 = external inbound, `2` = external outbound).
`src`	`Option<String>`	Optional source address of the message.
`src_dapp_id`	`Option<String>`	Optional source decentralized app identifier.
`src_workchain_id`	`Option<i32>`	Optional source workchain identifier.
`dst`	`Option<String>`	Optional destination address of the message.
`dst_workchain_id`	`Option<i32>`	Optional destination workchain identifier.
`fwd_fee`	`Option<String>`	Optional forwarding fee, represented as a hexadecimal string.
`bounce`	`Option<bool>`	Optional bounce flag indicating if the message is bounceable.
`bounced`	`Option<bool>`	Optional bounced flag indicating if the message was bounced.
`value`	`Option<String>`	Optional message value in hexadecimal format.
`value_other`	`Option<Vec<u8>>`	Optional serialized additional value data.
`created_lt`	`Option<String>`	Optional logical time of message creation, as string.
`created_at`	`Option<u32>`	Optional creation timestamp (unix time).
`dst_chain_order`	`Option<String>`	Optional destination chain order identifier.
`src_chain_order`	`Option<String>`	Optional source chain order identifier.
`proof`	`Option<Vec<u8>>`	Optional cryptographic proof data associated with the message.
`code`	`Option<Vec<u8>>`	Optional serialized BOC of the message's state initialization code.
`code_hash`	`Option<String>`	Optional hash of the state initialization code.
`data`	`Option<Vec<u8>>`	Optional serialized BOC of the message's state initialization data.
`data_hash`	`Option<String>`	Optional hash of the state initialization data.
`msg_chain_order`	`Option<String>`	Optional message chain order identifier.

Traits Derived

Deserialize and Serialize from serde for JSON and other serialization formats.
Clone for duplication.
Debug for formatted output.
Default for default initialization.

`impl From<MessageSerializationSet> for ArchMessage`

Converts a MessageSerializationSet instance into an ArchMessage. This conversion serializes various message components, extracts metadata, and sets archival fields accordingly.

Parameters

msg: A MessageSerializationSet instance that encapsulates a message along with its serialized form, proofs, and transaction metadata.

Returns

An ArchMessage instance populated with serialized and metadata fields extracted from msg.

Description

Converts message and transaction identifiers to hex strings.
Serializes the full BOC of the message and the message body (if present).
Extracts status and proof data.
Serializes the state initialization code and data if available and not pruned.
Handles three types of message headers from the CommonMsgInfo enum:
- IntMsgInfo (internal message): sets extensive fields including source/destination, bounce flags, values, fees, and creation times.
- ExtInMsgInfo (external inbound message): sets basic source/destination and creation time fields.
- ExtOutMsgInfo (external outbound message): sets body, source/destination, and creation time fields.

This implementation leverages write_boc for serialization of cells and uses hash functions to produce hex-encoded hashes for the code and data cells.

Usage Example

let arch_msg: ArchMessage = message_serialization_set_instance.into();

`pub(crate) fn get_msg_fees(msg: &Message) -> Option<(&Grams, &Grams)>`

Extracts the internal message fees from a given Message if it is an internal message.

Parameters

msg: A reference to a Message instance.

Returns

Some((&Grams, &Grams)) tuple containing the ihr_fee (import fee) and fwd_fee (forwarding fee) if the message header is internal.
None if the message is of any other type.

Description

This function inspects the message header using msg.header() and matches on the CommonMsgInfo enum. Only internal messages (IntMsgInfo) contain fee information; for external messages, fees are not applicable or accessible in this context.

Usage Example

if let Some((ihr_fee, fwd_fee)) = get_msg_fees(&message) {
    println!("Import fee: {}, Forwarding fee: {}", ihr_fee, fwd_fee);
}

Important Implementation Details

Serialization of Cells: The message's body, state initialization code, and data are serialized using the write_boc function from the tvm_types crate. This serialization converts cells into a binary Bag of Cells (BOC) format suitable for storage or transmission.
Handling of Pruned Cells: When serializing state initialization code and data, the implementation checks if the cell is pruned (i.e., removed or optimized away) before attempting serialization. Pruned cells are skipped to avoid errors.
Message Header Differentiation: The conversion logic uses the CommonMsgInfo enum to differentiate between internal, external inbound, and external outbound messages, populating fields selectively based on message type.
Hex Encoding: Identifiers and hashes are converted to hexadecimal string representations for easier readability and use in systems expecting hex strings.
Optional Fields: Many fields in ArchMessage are optional (Option<T>), reflecting that not all messages contain all metadata or serialized components.

Interaction with Other Modules

tvm_block crate: Provides core blockchain types such as Message, CommonMsgInfo, Grams, and serialization traits, used extensively for message representation and manipulation.
tvm_types crate: Offers utilities like write_boc for serializing cell structures into BOC format.
crate::serialization::MessageSerializationSet: Represents the input message data set, containing a message and its serialized form, used as the source for constructing ArchMessage.

The ArchMessage type acts as a bridge between raw blockchain message data and archival storage or further processing components that require a structured, serializable message format.

Visual Diagram: Class Diagram for ArchMessage and Related Conversion

classDiagram
class ArchMessage {
+id: String
+transaction_id: Option<String>
+boc: Option<Vec<u8>>
+body: Option<Vec<u8>>
+body_hash: Option<String>
+status: Option<u8>
+msg_type: Option<u8>
+src: Option<String>
+src_dapp_id: Option<String>
+src_workchain_id: Option<i32>
+dst: Option<String>
+dst_workchain_id: Option<i32>
+fwd_fee: Option<String>
+bounce: Option<bool>
+bounced: Option<bool>
+value: Option<String>
+value_other: Option<Vec<u8>>
+created_lt: Option<String>
+created_at: Option<u32>
+dst_chain_order: Option<String>
+src_chain_order: Option<String>
+proof: Option<Vec<u8>>
+code: Option<Vec<u8>>
+code_hash: Option<String>
+data: Option<Vec<u8>>
+data_hash: Option<String>
+msg_chain_order: Option<String>
}
class MessageSerializationSet {
<<struct>>
}
ArchMessage <|-- MessageSerializationSet : from()
class Message {
<<struct>>
+header()
}
class CommonMsgInfo {
<<enum>>
IntMsgInfo
ExtInMsgInfo
ExtOutMsgInfo
}
ArchMessage ..> MessageSerializationSet : Conversion Input
MessageSerializationSet ..> Message : Contains
Message ..> CommonMsgInfo : header() returns

References

Serialization for detailed information about the MessageSerializationSet and serialization concepts.
Blockchain Messages for understanding message types and structures.
Bag of Cells (BOC) Serialization for details on the BOC binary format and serialization processes.
CommonMsgInfo for the enum that distinguishes message header types.