mod.rs

Overview

This file defines the data structures, enums, and GraphQL schema objects related to blockchain transactions within the system. It provides comprehensive representations of transaction details, status, types, and associated actions, bounces, computation, storage, credit, and split information. The file implements conversions from database transaction records to GraphQL-friendly transaction models and includes format helpers for large integer fields.

The core purpose of the file is to bridge the raw blockchain transaction data (from the database layer) to a structured, strongly typed, and GraphQL-exposable format. It supports querying, filtering, and loading transaction data with rich metadata and status information.

Enums

TransactionProcessingStatusEnum

Represents the processing status of a blockchain transaction.

Usage: Used to indicate the current state of a transaction during processing.

TransactionTypeEnum

Enumerates the type of transaction according to the blockchain specification clause 4.2.4.

BounceTypeEnum

Describes the type of bounce for a transaction message.

ComputeTypeEnum

Type of computation performed during transaction execution.

SkipReasonEnum

Reasons for skipping the compute phase.

Structs and GraphQL Objects

TransactionAction

Represents detailed information about the actions performed in a transaction.

ComplexObject Methods:

• total_fwd_fees(format: Option<BigIntFormat>) -> Option<String>: Formats the total forwarding fees for display.

• total_action_fees(format: Option<BigIntFormat>) -> Option<String>: Formats the total action fees.

TransactionBounce

Details about message bounce behavior and fees.

ComplexObject Methods:

• fwd_fees(format: Option<BigIntFormat>) -> Option<String>: Formats forwarding fees.

• msg_fees(format: Option<BigIntFormat>) -> Option<String>: Formats message fees.

• req_fwd_fees(format: Option<BigIntFormat>) -> Option<String>: Formats required forwarding fees.

TransactionCompute

Information about the compute phase of transaction execution.

ComplexObject Methods:

• gas_fees(format: Option<BigIntFormat>) -> Option<String>: Formats gas fees.

• gas_limit(format: Option<BigIntFormat>) -> Option<String>: Formats gas limit.

• gas_used(format: Option<BigIntFormat>) -> Option<String>: Formats gas used.

TransactionCredit

Represents credit information related to a transaction.

ComplexObject Methods:

• credit(format: Option<BigIntFormat>) -> Option<String>: Formats credit amount.

• due_fees_collected(_format: Option<BigIntFormat>) -> Option<String>: Placeholder for due fees collected, returns None.

TransactionSplitInfo

Information related to split transactions.

TransactionStorage

Storage-related transaction fee details.

ComplexObject Methods:

• storage_fees_collected(format: Option<BigIntFormat>) -> Option<String>: Formats collected storage fees.

• storage_fees_due(format: Option<BigIntFormat>) -> Option<String>: Formats due storage fees.

Transaction

The main struct representing a blockchain transaction with all associated metadata, actions, messages, and status.

ComplexObject Methods:

• balance_delta(format: Option<BigIntFormat>) -> Option<String>: Formats balance delta.

• ext_in_msg_fee(format: Option<BigIntFormat>) -> Option<String>: Formats external inbound message fee.

• lt(format: Option<BigIntFormat>) -> Option<String>: Formats logical time.

• prev_trans_lt(format: Option<BigIntFormat>) -> Option<String>: Formats previous transaction logical time.

• total_fees(format: Option<BigIntFormat>) -> Option<String>: Formats total fees collected.

Implementations and Conversions

From primitive types to enums

The file implements From trait conversions to map primitive integer values into their corresponding enum variants for:

• BounceTypeEnum (from i32)

• ComputeTypeEnum (from u8)

• SkipReasonEnum (from u8)

• TransactionProcessingStatusEnum (from u8)

• TransactionTypeEnum (from u8)

This allows easy casting from stored integer codes (e.g., from database) to meaningful enum types used in code and GraphQL interface.

From Database Transaction to GraphQL Transaction

The Fromdb::Transaction trait implementation converts a database transaction record into the GraphQL Transaction model. During this conversion:

• The transaction BOC (Base64 Object Code) is encoded as Base64 string.

• Nested structs like TransactionAction, TransactionCompute, TransactionStorage, and TransactionCredit are instantiated from database fields.

• Enum fields are converted using the From implementations.

• Optional fields are handled gracefully with Option.

• JSON string fields such as outbound messages (out_msgs) are deserialized.

• Some fields are explicitly left None or commented for future filling (code_hash, installed, etc.).

Interaction with Other Parts of the System

• Imports: Uses types from sibling modules account and message, indicating dependencies on account status enums and message structures.

• Helpers: Uses a helper function format_big_int to convert large integer strings into formatted strings for GraphQL presentation.

• Database: Imports the database schema types (db::Transaction), indicating close coupling with the database layer.

• GraphQL: Uses async_graphql macros to define GraphQL enums and objects, enabling this file's types to be served via GraphQL API.

• Resolver Module: Re-exports TransactionFilter and TransactionLoader from related submodules, which likely handle filtering and loading transactions for queries.

Important Implementation Details

• All enums are annotated with #[graphql(rename_items = "PascalCase")] to control naming conventions in the GraphQL schema.

• Some fields are intentionally skipped or hidden from GraphQL using #[graphql(skip)] or #[graphql(visible = false)] to control schema exposure.

• Complex objects define async methods to expose formatted versions of large integer values with optional formatting parameters.

• The transaction logical time (lt) and fees are handled as strings to accommodate very large integer values that exceed standard 64-bit integer limits.

• The file leverages Rust's Option extensively to handle nullable or optional blockchain data.

• Comments provide detailed explanations of blockchain-specific concepts such as TVM (TON Virtual Machine) exit codes, gas fees, and message delivery semantics.

• The Transaction struct is designed to represent a rich set of blockchain transaction metadata, suitable for querying and analysis.

Usage Examples

Creating a Transaction from a database transaction record

let db_trx: db::Transaction = get_transaction_from_db(id);
let trx: Transaction = db_trx.into();

Querying formatted total fees in a GraphQL resolver

async fn total_fees(&self, format: Option<BigIntFormat>) -> Option<String> {
    self.total_fees(format).await
}

Mermaid Class Diagram

classDiagram
    class Transaction {
        +id: String
        +aborted: bool
        +account_addr: Option<String>
        +action: TransactionAction
        +balance_delta: Option<String>
        +block_id: String
        +boc: String
        +bounce: Option<TransactionBounce>
        +chain_order: String
        +code_hash: Option<String>
        +compute: TransactionCompute
        +credit: Option<TransactionCredit>
        +credit_first: bool
        +destroyed: bool
        +end_status: u8
        +end_status_name: AccountStatusEnum
        +ext_in_msg_fee: Option<String>
        +in_message: Option<Message>
        +in_msg: String
        +installed: Option<bool>
        +lt: Option<String>
        +master_seq_no: Option<f64>
        +new_hash: Option<String>
        +now: u64
        +now_string: String
        +old_hash: Option<String>
        +orig_status: u8
        +orig_status_name: AccountStatusEnum
        +out_messages: Option<Vec<Option<Message>>>
        +out_msgs: Vec<String>
        +outmsg_cnt: u16
        +prepare_transaction: Option<String>
        +prev_trans_hash: Option<String>
        +prev_trans_lt: Option<String>
        +proof: Option<String>
        +split_info: Option<TransactionSplitInfo>
        +status: u8
        +status_name: TransactionProcessingStatusEnum
        +storage: TransactionStorage
        +total_fees: Option<String>
        +tr_type: u8
        +tr_type_name: TransactionTypeEnum
        +tt: Option<String>
        +workchain_id: i32
    }

    class TransactionAction {
        +action_list_hash: String
        +msgs_created: Option<i16>
        +no_funds: bool
        +result_arg: Option<i32>
        +result_code: i32
        +skipped_actions: i16
        +spec_actions: i16
        +status_change: u8
        +status_change_name: AccountStatusChangeEnum
        +success: bool
        +tot_actions: i16
        +tot_msg_size_bits: Option<f64>
        +tot_msg_size_cells: Option<f64>
        +valid: bool
    }

    class TransactionBounce {
        +bounce_type: Option<i32>
        +bounce_type_name: Option<BounceTypeEnum>
        +msg_size_bits: Option<f64>
        +msg_size_cells: Option<f64>
    }

    class TransactionCompute {
        +account_activated: bool
        +compute_type: u8
        +compute