account.rs

Overview

This file defines GraphQL query types and structures related to account data retrieval and pagination of account-related events for an application using a GraphQL API. It provides mechanisms to query account information as well as to paginate through account events such as outgoing external messages. The file leverages asynchronous database access, cursor-based pagination, and GraphQL connection patterns to enable efficient data fetching.

Key Components

Structs and Their Purpose

SingleAccount

A simple GraphQL object representing an individual account with the following fields:

• id: String — Unique identifier of the account.

• boc: Option<String> — Optional base64 encoded Bag of Cells (BOC) containing the account struct.

• dapp_id: Option<String> — Optional decentralized application identifier associated with the account.

Implementation Details

• Implements conversion from the database model db::Account into SingleAccount.

• The boc field is encoded from raw binary data to a base64 string using tvm_types::base64_encode.

AccountQuery

Represents a GraphQL query context for a specific account address.

• address: String — The unique address of the account being queried.

• preloaded: Option<db::Account> — Optional preloaded database account to avoid redundant queries.

AccountEventEdge and AccountEventsConnection

Custom types implementing GraphQL connection traits for paginating account events:

• AccountEventEdge implements EdgeNameType with the GraphQL type name "AccountEventEdge".

• AccountEventsConnection implements ConnectionNameType with the GraphQL type name "AccountEventsConnection".

These types are used in the cursor-based pagination of account events.

Detailed Function and Method Descriptions

impl From<db::Account> for SingleAccount

• Purpose: Converts a database account model into a GraphQL-friendly SingleAccount object.

• Parameters: acc — a db::Account instance.

• Returns: A new SingleAccount instance.

• Usage Example:

  let db_account: db::Account = ...;
  let gql_account: SingleAccount = db_account.into();
  

impl AccountQuery

This implementation block exposes two main asynchronous GraphQL query methods:

async fn info(&self, ctx: &Context<'_>) -> Option<SingleAccount>

• Purpose: Retrieves detailed account information.

• Parameters:

  • ctx: The GraphQL context providing access to database and other services.

• Returns: An optional SingleAccount instance if the account is found.

• Behavior:

  • If preloaded account data is present, returns it directly.

  • Otherwise, queries the database for the account by address using db::Account::by_address.

• Usage Example:

  query {
    account(address: "0:abc123") {
      info {
        id
        boc
        dapp_id
      }
    }
  }
  

async fn events(...) -> Option<Connection<...>>

• Purpose: Provides cursor-based pagination over account events (outgoing external messages).

• Parameters:

  • ctx: GraphQL context for data access.

  • first: Option<i32> — Number of items to return forward from the cursor (mutually exclusive with last).

  • after: Option<String> — Cursor to paginate after.

  • last: Option<i32> — Number of items to return backward from the cursor (mutually exclusive with first).

  • before: Option<String> — Cursor to paginate before.

• Returns: An optional GraphQL Connection object representing a paginated list of events.

• Implementation Details:

  • Uses async_graphql::connection::query to handle pagination logic.

  • Fetches messages from the database via db::Message::account_events.

  • Uses a PaginationArgs struct to manage pagination parameters and cursors.

  • Builds a Connection object with Edges wrapping the events and their cursors.

• Usage Example:

  query {
    account(address: "0:abc123") {
      events(first: 10, after: "cursor123") {
        edges {
          node {
            id
            type
            ...
          }
        }
        pageInfo {
          hasNextPage
          hasPreviousPage
        }
      }
    }
  }
  

Important Implementation Details and Algorithms

• Cursor-based Pagination: The events method implements cursor-based pagination via async_graphql connection traits, allowing efficient forward and backward navigation through account events without offset-based queries, which improves performance on large datasets.

• Conversion and Encoding: The BOC data is encoded as base64 to safely represent binary data as strings in GraphQL responses.

• Use of Arc<ClientContext> and SqlitePool: These shared contexts are retrieved from the GraphQL context for database access and client operations, ensuring thread safety and efficient resource sharing.

• Tracing: The file uses debug-level tracing logs for pagination parameters and page boundary markers to aid in diagnostics.

Interaction with Other System Components

• Database Layer (db): Uses db::Account and db::Message modules for fetching account and event data from the SQLite database.

• GraphQL Framework: Implements GraphQL objects and connections using async_graphql, leveraging its connection model for pagination.

• TVM Client: The ClientContext from the TVM client is injected into the context and used during account queries, possibly to enrich or verify account data.

• Event Conversion: Events returned in the events connection are converted from database messages into the Event GraphQL object defined elsewhere in the schema (crate::schema::graphql_std::events::Event).

Mermaid Diagram: Structure of account.rs

classDiagram
class SingleAccount {
+id: String
+boc: Option<String>
+dapp_id: Option<String>
}
class AccountQuery {
+address: String
+preloaded: Option<db::Account>
+info()
+events()
}
class AccountEventEdge {
<<EdgeNameType>>
}
class AccountEventsConnection {
<<ConnectionNameType>>
}
SingleAccount <|-- db::Account : From
AccountQuery ..> SqlitePool : uses
AccountQuery ..> Arc~ClientContext~ : uses
AccountQuery ..> AccountEventEdge : uses for pagination
AccountQuery ..> AccountEventsConnection : uses for pagination
AccountQuery ..> Event : events output node

This class diagram shows the primary data structures and their relationships in the file. It highlights how AccountQuery serves as the main query type, depending on database and client contexts, and how it leverages custom connection and edge types for paginating events.