account.rs

Overview

This file defines the GraphQL schema and query resolvers related to blockchain accounts, their messages, and transactions. It provides the data structures and asynchronous query methods to fetch account information, paginate through account messages, and paginate through account transactions. These queries support filtering, pagination, and data consistency options tailored for blockchain data retrieved from a SQLite database and external clients.

The file primarily implements the BlockchainAccountQuery struct with GraphQL query methods, along with supporting enums, input objects, and connection/edge types used for GraphQL cursor-based pagination of messages and transactions.

Types, Enums, and Structs

BlockchainMessageTypeFilterEnum

An enumeration representing the type of blockchain messages for filtering purposes.

• Variants:

  • ExtIn: External inbound messages

  • ExtOut: External outbound messages

  • IntIn: Internal inbound messages

  • IntOut: Internal outbound messages

• Conversion:
  Implements From<BlockchainMessageTypeFilterEnum> for u8 to convert variants into numeric codes (1, 2, or 0), useful for database queries.

BlockchainMasterSeqNoFilter

An input object representing a filter for blockchain master sequence numbers (block sequence numbers).

• Fields:

  • start: Optional start sequence number (Option<i32>)

  • end: Optional end sequence number (Option<i32>)

Used to define a range for filtering messages or transactions by block sequence numbers.

Connection and Edge Types

These structs implement ConnectionNameType or EdgeNameType traits for GraphQL connections and edges used in pagination.

• BlockchainMessageEdge / BlockchainMessagesConnection

• BlockchainAccountEdge / BlockchainAccountsConnection

Each provides a static method to return its GraphQL type name, e.g., "BlockchainMessageEdge".

BlockchainAccountQuery<'a>

A GraphQL query object representing queries related to a specific blockchain account.

Fields

• ctx: &Context<'a>
  GraphQL execution context providing access to data loaders, database pools, and other contextual information.

• address: String
  The blockchain account address used to identify the account in queries.

• preloaded: Option<db::Account>
  Optional preloaded database account entity to avoid duplicate queries.

GraphQL Query Methods

info(_by_block: Option<String>) -> Option<BlockchainAccount>

Fetches account information such as the account's BOC (Bag of Cells) or other details.

• Parameters:

  • _by_block: Optional block hash to query the account state at a specific shard state corresponding to the block.

• Behavior:

  • If a preloaded account is available, it returns this directly.

  • Otherwise, queries the database for the account by address.

  • Uses SqlitePool and ClientContext from the context.

• Returns:
  An optional BlockchainAccount with account details.

• Usage example:

  let account_query = BlockchainAccountQuery { ctx, address, preloaded: None };
  let account_info = account_query.info(None).await;
  

messages(...) -> Option<Connection<String, BlockchainMessage, ...>>

Returns a paginated connection of blockchain messages related to the account, supporting various filters.

• Parameters:

  • allow_latest_inconsistent_data: Option<bool>: Disables latency for recent data to reduce realtime latency at the cost of consistency.

  • block_seq_no_range: Option<BlockchainMasterSeqNoFilter>: Filters messages by master sequence number range.

  • counterparties: Option<Vec<String>>: Filters messages by a list of counterparties (max 5).

  • msg_type: Option<Vec<BlockchainMessageTypeFilterEnum>>: Filters messages by specified types.

  • min_value: Option<String>: Filters messages with minimum value (may be unoptimized).

  • Pagination parameters: first, after, last, before (cursor-based pagination).

  • _archive: Option<bool>: Defines query scope for time range (max or recent).

• Implementation details:

  • Uses cursor-based pagination via async_graphql::connection::query.

  • Constructs db::AccountMessagesQueryArgs and queries messages from the database.

  • Checks GraphQL selection set to conditionally load related parent and child transactions using TransactionLoader.

  • Converts database messages into GraphQL Message objects with attached transactions when requested.

  • Returns a Connection type with edges containing cursors and message nodes.

• Returns:
  An optional Connection of BlockchainMessage objects with pagination metadata.

• Usage example snippet:

  let messages = account_query.messages(
      Some(false),
      Some(BlockchainMasterSeqNoFilter { start: Some(100), end: Some(200) }),
      None,
      Some(vec![BlockchainMessageTypeFilterEnum::ExtIn]),
      None,
      Some(10),
      None,
      None,
      None,
      None,
  ).await;
  

transactions(...) -> Option<Connection<String, BlockchainTransaction, ...>>

Returns a paginated connection of blockchain transactions related to the account, supporting various filters.

• Parameters:

  • allow_latest_inconsistent_data: Option<bool>: Similar to messages, controls latency vs. consistency.

  • block_seq_no_range: Option<BlockchainMasterSeqNoFilter>: Filters transactions by block sequence number range.

  • aborted: Option<bool>: Filters transactions by aborted status.

  • min_balance_delta: Option<String>: Filters transactions with minimum balance delta.

  • max_balance_delta: Option<String>: Filters transactions with maximum balance delta.

  • Pagination parameters: first, after, last, before.

  • _archive: Option<bool>: Defines query scope for time range.

• Implementation details:

  • Uses cursor-based pagination.

  • Constructs AccountTransactionsQueryArgs to query transactions from the database.

  • Converts database transactions into GraphQL Transaction objects.

  • Generates edges with cursors from transaction chain order.

  • Returns the paginated connection.

• Returns:
  An optional Connection of BlockchainTransaction objects.

• Usage example:

  let txs = account_query.transactions(
      None,
      None,
      None,
      None,
      None,
      Some(5),
      None,
      None,
      None,
  ).await;
  

Important Implementation Details

• Cursor-Based Pagination: Both messages and transactions use the async_graphql::connection::query helper for pagination implementing the Relay Cursor Connections Specification. Pagination parameters (first, last, before, after) dictate the subset of results returned.

• GraphQL Selection Set Checking: For messages, the resolver inspects the GraphQL query's selection set to determine if related transactions (src_transaction or dst_transaction) need to be loaded. This optimizes data fetching by avoiding unnecessary loads.

• Data Loading: Uses DataLoader pattern (TransactionLoader) for batching and caching transaction fetches, reducing redundant database calls.

• Filtering Support: Both messages and transactions support multiple filters (e.g., message types, counterparties, sequence number ranges, value or balance delta thresholds) that influence the underlying database queries.

• Consistency vs. Realtime Data: The allow_latest_inconsistent_data flag controls whether recent data latency is enforced to guarantee consistency or if the most recent data is fetched at the cost of potential inconsistency, which is important in blockchain state querying.

• Type Aliases: The file aliases BlockchainAccount and BlockchainMessage to local GraphQL types (Account and Message) for clarity and semantic alignment.

Interactions with Other System Components

• Database Layer (db): Uses database query modules (db::Account, db::Message, db::Transaction) to fetch blockchain account data, messages, and transactions from an SQLite backend.

• GraphQL Schema (async_graphql): Implements GraphQL schema types and resolvers using async_graphql components like Object, InputObject, Enum, and connection utilities.

• Transaction Loader (TransactionLoader): Utilizes a data loader component to batch and cache transaction fetches, improving performance and reducing database load.

• Client Context (tvm_client::ClientContext): Provides external client context for blockchain interaction, passed down from the GraphQL context.

• Other GraphQL Modules: References types from sibling modules for messages, transactions, accounts, and blockchain API extensions.

Visual Diagram: Class Diagram of Key Structs and Their Methods

classDiagram
class BlockchainAccountQuery {
+ctx: &Context
+address: String
+preloaded: Option<db::Account>
+info(_by_block: Option<String>) : Option<BlockchainAccount>
+messages(...) : Option<Connection<String, BlockchainMessage>>
+transactions(...) : Option<Connection<String, BlockchainTransaction>>
}
class BlockchainMessageTypeFilterEnum {
<<enum>>
+ExtIn
+ExtOut
+IntIn
+IntOut
}
class BlockchainMasterSeqNoFilter {
+start: Option<i32>
+end: Option<i32>
}
class BlockchainMessagesConnection {
+type_name<T>() : String
}
class BlockchainMessageEdge {
+type_name<T>() : String
}
class BlockchainTransactionsConnection {
+type_name<T>() : String
}
class BlockchainTransactionsEdge {
+type_name<T>() : String
}
BlockchainAccountQuery --> BlockchainMessageTypeFilterEnum : uses
BlockchainAccountQuery --> BlockchainMasterSeqNoFilter : uses
BlockchainAccountQuery --> BlockchainMessagesConnection : returns
BlockchainAccountQuery --> BlockchainMessageEdge : returns
BlockchainAccountQuery --> BlockchainTransactionsConnection : returns
BlockchainAccountQuery --> BlockchainTransactionsEdge : returns

References to Related Topics

• For detailed explanation of cursor-based pagination and GraphQL connection types, see Cursor-Based Pagination.

• For database query structures and filters, see Database Query Arguments.

• For GraphQL schema design patterns and selection set inspection, refer to GraphQL Schema Design.

• For data loader pattern and caching, see DataLoader Pattern.

• For blockchain message and transaction domain models, see Blockchain Transactions and Messages.