transaction.rs

Overview

This file defines the data structures and methods to query and manage blockchain transaction records stored in a SQLite database. It provides functionality to retrieve transactions based on various filters such as account address, pagination parameters, transaction status, balance changes, and blockchain-specific attributes. The file primarily interacts with the database layer using SQL queries built dynamically with the sqlx crate and supports asynchronous operations.

The core components include:

• AccountTransactionsQueryArgs: A struct for specifying filters and pagination when querying account-specific transactions.

• Transaction: A struct representing a blockchain transaction record and associated methods to query those transactions from the database.

Structs and Methods

AccountTransactionsQueryArgs

A struct encapsulating filters and pagination arguments for querying account transactions.

pub struct AccountTransactionsQueryArgs {
    allow_latest_inconsistent_data: Option<bool>,
    block_seq_no_range: Option<BlockchainMasterSeqNoFilter>,
    aborted: Option<bool>,
    min_balance_delta: Option<String>,
    max_balance_delta: Option<String>,
    pub pagination: PaginationArgs,
}

Fields

• allow_latest_inconsistent_data: Optional flag to allow fetching potentially inconsistent latest data.

• block_seq_no_range: Optional range filter on the blockchain master sequence number (BlockchainMasterSeqNoFilter).

• aborted: Optional filter for aborted transactions.

• min_balance_delta / max_balance_delta: Optional minimum and maximum balance delta filters as strings.

• pagination: Pagination arguments (PaginationArgs) controlling limit, direction, and cursors.

Methods

• new(...) -> Self

  Constructor accepting all fields as parameters for creating an instance.

  Parameters:

  • allow_latest_inconsistent_data: Option<bool>

  • block_seq_no_range: Option<BlockchainMasterSeqNoFilter>

  • aborted: Option<bool>

  • min_balance_delta: Option<String>

  • max_balance_delta: Option<String>

  • pagination: PaginationArgs

  Returns:

  • AccountTransactionsQueryArgs instance

  Usage example:

  let args = AccountTransactionsQueryArgs::new(
      Some(true),
      Some(seq_no_filter),
      Some(false),
      Some("1000".to_string()),
      None,
      pagination_args,
  );
  

Transaction

Represents a blockchain transaction with detailed fields describing its execution, status, and metadata.

#[derive(Clone, FromRow, Debug)]
pub struct Transaction {
    pub rowid: i64,
    pub id: String,
    pub aborted: bool,
    pub account_addr: String,
    pub action_success: bool,
    pub action_valid: bool,
    pub action_no_funds: bool,
    pub action_status_change: u8,
    pub action_result_code: i32,
    pub action_tot_actions: i16,
    pub action_spec_actions: i16,
    pub action_skipped_actions: i16,
    pub action_msgs_created: i16,
    pub action_list_hash: String,
    pub action_tot_msg_size_cells: f64,
    pub action_tot_msg_size_bits: f64,
    pub balance_delta: String,
    pub block_id: String,
    pub boc: Vec<u8>,
    pub chain_order: String,
    pub credit: Option<String>,
    pub credit_first: bool,
    pub compute_account_activated: bool,
    pub compute_exit_code: i32,
    pub compute_gas_fees: String,
    pub compute_gas_used: f64,
    pub compute_gas_limit: f64,
    pub compute_mode: i8,
    pub compute_msg_state_used: bool,
    pub compute_success: bool,
    pub compute_type: u8,
    pub compute_vm_final_state_hash: String,
    pub compute_vm_init_state_hash: String,
    pub compute_vm_steps: u64,
    pub destroyed: bool,
    pub end_status: u8,
    pub in_msg: String,
    pub lt: String,
    pub new_hash: String,
    pub now: u64,
    pub old_hash: String,
    pub orig_status: u8,
    pub out_msgs: String,
    pub outmsg_cnt: u16,
    pub prev_trans_hash: String,
    pub prev_trans_lt: String,
    pub proof: Option<Vec<u8>>,
    pub status: u8,
    pub storage_fees_collected: Option<String>,
    pub storage_status_change: Option<u8>,
    pub total_fees: String,
    pub tr_type: u8,
    pub workchain_id: i32,
}

Fields Description

Each field corresponds to a column in the transactions database table and captures aspects such as:

• Transaction identifiers (id, rowid)

• Execution status flags (aborted, action_success, compute_success, etc.)

• Action details (action_tot_actions, action_msgs_created, action_list_hash)

• Financial amounts and fees (balance_delta, compute_gas_fees, total_fees)

• Blockchain metadata (block_id, chain_order, workchain_id)

• Message identifiers (in_msg, out_msgs)

• Execution environment state hashes and steps (compute_vm_final_state_hash, compute_vm_init_state_hash, compute_vm_steps)

Methods

list

pub async fn list(
    pool: &SqlitePool,
    filter: String,
    order_by: String,
    limit: Option<i32>,
) -> anyhow::Result<Vec<Transaction>>

Fetches a list of transactions matching a raw SQL filter and order clause, optionally limited by count.

• Parameters:

  • pool: Reference to the SQLite connection pool.

  • filter: SQL filter clause (e.g., "WHERE account_addr = 'addr'").

  • order_by: SQL order clause (e.g., "ORDER BY chain_order DESC").

  • limit: Optional maximum number of rows to fetch; defaults to defaults::QUERY_BATCH_SIZE.

• Returns: Asynchronous result resolving to a vector of Transaction objects.

• Usage example:

  let txs = Transaction::list(&pool, "WHERE aborted = 0".to_string(), "ORDER BY now DESC".to_string(), Some(100)).await?;
  

blockchain_transactions

pub async fn blockchain_transactions(
    pool: &SqlitePool,
    args: &BlockchainTransactionsQueryArgs,
) -> anyhow::Result<Vec<Transaction>>

Fetches blockchain transactions matching complex filters encapsulated in BlockchainTransactionsQueryArgs, supporting pagination.

• Parameters:

  • pool: SQLite connection pool.

  • args: Reference to a BlockchainTransactionsQueryArgs struct with filters and pagination.

• Returns: A vector of Transaction matching the filters.

• Implementation details:

  • Builds dynamic SQL WHERE clauses based on args.

  • Supports filtering by pagination cursors (after, before), code hash, and balance delta ranges.

  • Orders results according to the pagination direction.

  • Uses asynchronous fetch with error handling.

account_transactions

pub async fn account_transactions(
    pool: &SqlitePool,
    account: String,
    args: &AccountTransactionsQueryArgs,
) -> anyhow::Result<Vec<Self>>

Fetches transactions related to a specific account address, filtered by the provided AccountTransactionsQueryArgs.

• Parameters:

  • pool: SQLite connection pool.

  • account: The account address string to filter transactions.

  • args: Reference to AccountTransactionsQueryArgs containing filters and pagination.

• Returns: Asynchronous result with a vector of Transaction for the specified account.

• Implementation details:

  • Constructs SQL WHERE clauses including account address, aborted flag, pagination cursors, sequence number range, and balance delta filters.

  • Queries database asynchronously and returns results ordered by chain order, respecting pagination direction.

by_in_message

pub async fn by_in_message(
    pool: &SqlitePool,
    msg_id: &str,
    _fields: Option<Vec<String>>,
) -> anyhow::Result<Option<Transaction>>

Fetches a single transaction identified by its input message ID.

• Parameters:

  • pool: SQLite connection pool.

  • msg_id: String slice of the message ID, optionally stripped of the "message/" prefix.

  • _fields: Optional vector of field names (currently unused).

• Returns: An optional Transaction wrapped in an async result if found.

• Usage example:

  let tx = Transaction::by_in_message(&pool, "message/1234abcd", None).await?;
  

Implementation Details and Algorithms

• Dynamic SQL Query Construction: The methods build SQL query strings dynamically based on input parameters (filters, pagination). The QueryBuilder from sqlx is used to safely build and execute these queries.

• Pagination Support: Pagination is implemented using PaginationArgs which provides methods to get direction (Forward or Backward) and limit count. Pagination cursors (after, before) are used to filter transactions by chain_order to support cursor-based pagination.

• Filtering by Ranges and Flags: The code supports filtering transactions by boolean flags (e.g., aborted), numeric ranges (balance_delta), and sequence numbers (block_seq_no_range).

• Asynchronous Database Access: All database operations use async/await patterns with the sqlx crate to allow non-blocking IO.

• Error Handling: Errors during database queries are captured and propagated using the anyhow crate.

Interactions with Other System Components

• Database Layer: The file depends on sqlx::SqlitePool for connection pooling and executing SQL queries against the transactions table.

• GraphQL Schema Extensions: It utilizes types from the crate::schema::graphql_ext::blockchain_api module such as BlockchainTransactionsQueryArgs, BlockchainMasterSeqNoFilter, and pagination-related types (PaginationArgs, PaginateDirection) indicating integration with the GraphQL API layer.

• Helpers and Defaults: Uses helper functions like u64_to_string and constants from defaults for query batch sizes.

• Tracing and Logging: Uses the tracing crate for debug and trace level logging of SQL queries and query results.

Mermaid Diagram: Class Diagram for Transaction and QueryArgs

classDiagram
class AccountTransactionsQueryArgs {
-allow_latest_inconsistent_data: Option<bool>
-block_seq_no_range: Option<BlockchainMasterSeqNoFilter>
-aborted: Option<bool>
-min_balance_delta: Option<String>
-max_balance_delta: Option<String>
+pagination: PaginationArgs
+new()
}
class Transaction {
+rowid: i64
+id: String
+aborted: bool
+account_addr: String
+action_success: bool
+action_valid: bool
+action_no_funds: bool
+action_status_change: u8
+action_result_code: i32
+action_tot_actions: i16
+action_spec_actions: i16
+action_skipped_actions: i16
+action_msgs_created: i16
+action_list_hash: String
+action_tot_msg_size_cells: f64
+action_tot_msg_size_bits: f64
+balance_delta: String
+block_id: String
+boc: Vec<u8>
+chain_order: String
+credit: Option<String>
+credit_first: bool
+compute_account_activated: bool
+compute_exit_code: i32
+compute_gas_fees: String
+compute_gas_used: f64
+compute_gas_limit: f64
+compute_mode: i8
+compute_msg_state_used: bool
+compute_success: bool
+compute_type: u8
+compute_vm_final_state_hash: String
+compute_vm_init_state_hash: String
+compute_vm_steps: u64
+destroyed: bool
+end_status: u8
+in_msg: String
+lt: String
+new_hash: String
+now: u64
+old_hash: String
+orig_status: u8
+out_msgs: String
+outmsg_cnt: u16
+prev_trans_hash: String
+prev_trans_lt: String
+proof: Option<Vec<u8>>
+status: u8
+storage_fees_collected: Option<String>
+storage_status_change: Option<u8>
+total_fees: String
+tr_type: u8
+workchain_id: i32
+list()
+blockchain_transactions()
+account_transactions()
+by_in_message()
}

This diagram shows the Transaction struct with its properties and methods, as well as the AccountTransactionsQueryArgs struct with its fields and constructor method. The diagram emphasizes the data-centric nature of these classes and their primary asynchronous query methods.