mod.rs

Overview

This file defines the core data structures and GraphQL schema representations for blockchain accounts within the system. It primarily models the concept of an Account as it exists in the underlying blockchain, including its state, status, and related metadata. The file provides conversions from database models to GraphQL-friendly objects and implements various computed fields and formatting helpers to expose account details through a GraphQL API.

The account abstraction here treats smart contracts and accounts interchangeably, consistent with the semantics of the TVM-based blockchain. The file also defines enumerations representing the status of accounts and their possible state changes.

Modules and Imports

filter: This submodule (imported and re-exported as AccountFilter) provides filtering capabilities for accounts.
helpers: Utility functions including ecc_from_bytes (likely decoding ECC-encoded data) and format_big_int (formatting large integers for display).
schema::db: The database schema models, particularly the db::Account struct used to convert database records into GraphQL objects.
schema::graphql::currency::OtherCurrency: Representation of currencies other than the native token.
schema::graphql::formats::BigIntFormat: Formatting options for large integer values in GraphQL responses.

Enumerations

AccountStatusEnum

An enumeration describing the current lifecycle state of an account.

Variant	Description
`Uninit`	Account is uninitialized (0)
`Active`	Account is active (1)
`Frozen`	Account is frozen (2)
`NonExist`	Account does not exist (3)

Implements From<u8> for easy conversion from numeric status codes.
Uses PascalCase renaming in GraphQL schema.

AccountStatusChangeEnum

Enumerates possible state changes for an account.

Variant	Description
`Unchanged`	No change in status (default)
`Frozen`	Account has been frozen
`Deleted`	Account has been deleted

Internal use, pub(crate).
Implements From<u8> for conversion from numeric codes.
Uses PascalCase renaming in GraphQL schema.

Struct: Account

Represents a blockchain account (or smart contract) with detailed state and metadata fields. Annotated as a GraphQL SimpleObject with some complex computed fields.

Fields

Field	Type	Description
`id`	`String`	Full account address (unique identifier).
`address`	`String`	Alias for `id`.
`acc_type`	`Option<u8>`	Numeric account type code.
`acc_type_name`	`AccountStatusEnum`	Enum representation of the account status.
`balance`	`Option<String>`	Account balance in native tokens, stored as a string for large number support.
`balance_other`	`Option<Vec<OtherCurrency>>`	Balances in other currencies besides the native token.
`bits`	`Option<String>`	Sum of bits used by the account's cells, relevant for storage fee calculations.
`boc`	`Option<String>`	Bag of cells encoding the account struct in base64.
`cells`	`Option<String>`	Number of cells forming the account.
`code`	`Option<String>`	Base64-encoded smart contract code if present.
`code_hash`	`String`	Hash of the contract code.
`data`	`Option<String>`	Base64-encoded smart contract data if present.
`data_hash`	`String`	Hash of the contract data.
`dapp_id`	`Option<String>`	Identifier for decentralized application association.
`due_payment`	`Option<String>`	Accumulated storage payments unpaid, applicable to uninitialized or frozen accounts.
`init_code_hash`	`String`	Initial code hash when the account was deployed.
`last_paid`	`Option<u64>`	Unix timestamp of last storage payment or account creation.
`last_trans_lt`	`Option<String>`	Logical time of the last transaction, as a string.
`library`	`Option<String>`	Base64-encoded library code used by the smart contract.
`library_hash`	`Option<String>`	Hash of the library code.
`prev_code_hash`	`Option<String>`	Hash of the previous code, if applicable.
`proof`	`Option<String>`	Base64-encoded Merkle proof showing account membership in shard state.
`public_cells`	`Option<String>`	Number of public cells in the account, relevant for storage fee calculations.
`split_depth`	`Option<i32>`	Depth of splitting in large smart contracts.
`state_hash`	`Option<String>`	Representation hash of StateInit when account is frozen.
`tick`	`Option<bool>`	Present only for certain masterchain contracts; indicates tick status.
`tock`	`Option<bool>`	Present only for certain masterchain contracts; indicates tock status.
`workchain_id`	`i32`	Workchain identifier of the account address.

Implementation Details

Implements Fromdb::Account for conversion from the database representation. This involves decoding ECC-encoded balances and base64-encoding fields such as boc, code, and data.
Uses helper functions like ecc_from_bytes and tvm_types::base64_encode.
Some fields are skipped in GraphQL (#[graphql(skip)]) to avoid exposing raw or internal data.

Complex Object Fields (Computed)

Defined via the #[ComplexObject] macro, these provide asynchronous methods to resolve fields with optional formatting.

Method	Description	Parameters	Returns
`balance`	Returns the account balance formatted according to the optional `BigIntFormat`.	`format: Option<BigIntFormat>`	`Option<String>`
`bits`	Returns the total bits used by the account's cells, formatted if requested.	`format: Option<BigIntFormat>`	`Option<String>`
`cells`	Returns the number of cells forming the account, formatted if requested.	`format: Option<BigIntFormat>`	`Option<String>`
`due_payment`	Returns the due storage payment amount if any; does not currently format the value.	`_format: Option<BigIntFormat>`	`Option<String>`
`last_trans_lt`	Returns the logical time of the last transaction, formatted if requested.	`format: Option<BigIntFormat>`	`Option<String>`
`public_cells`	Returns the number of public cells, formatted if requested.	`format: Option<BigIntFormat>`	`Option<String>`

Usage Examples

GraphQL Query Example:

query {
  account(id: "some-account-id") {
    id
    acc_type_name
    balance(format: { decimal_places: 2 })
    bits
    cells
    due_payment
    last_trans_lt
  }
}

This would return the account's main details, with balance formatted as a decimal string.

Rust Conversion Example:

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

This converts a database account into the GraphQL Account object with all necessary transformations.

Interaction with Other Parts of the System

Database Layer (db::Account): This file depends on the database model for raw account data and converts it into a GraphQL-friendly structure.
Helpers Module: Uses utility functions for ECC decoding and big integer formatting.
GraphQL Schema: Integrates with the GraphQL schema, exposing accounts and their properties with appropriate formatting and filtering.
Currency Module: Supports multiple currencies via OtherCurrency.
Filter Module: Imports and re-exports account filtering capabilities, likely used in queries to filter accounts by various criteria.

Important Implementation Details and Algorithms

Status Conversion: The enums AccountStatusEnum and AccountStatusChangeEnum implement From<u8> to map raw numeric status codes to meaningful enum variants.
Base64 Encoding: Fields like boc, code, and data are base64-encoded using the tvm_types::base64_encode function to prepare binary data for GraphQL transport.
ECC Decoding: The balance_other field is decoded from ECC-encoded bytes to a vector of OtherCurrency, ensuring accurate multi-currency representation.
Big Integer Formatting: Numeric fields stored as strings are formatted on-demand using the format_big_int helper, which supports various formatting options.

classDiagram
class Account {
+id: String
-address: String
-acc_type: Option<u8>
-acc_type_name: AccountStatusEnum
-balance: Option<String>
-balance_other: Option<Vec<OtherCurrency>>
-bits: Option<String>
-boc: Option<String>
-cells: Option<String>
-code: Option<String>
-code_hash: String
-data: Option<String>
-data_hash: String
-dapp_id: Option<String>
-due_payment: Option<String>
-init_code_hash: String
-last_paid: Option<u64>
-last_trans_lt: Option<String>
-library: Option<String>
-library_hash: Option<String>
-prev_code_hash: Option<String>
-proof: Option<String>
-public_cells: Option<String>
-split_depth: Option<i32>
-state_hash: Option<String>
-tick: Option<bool>
-tock: Option<bool>
-workchain_id: i32
+balance()
+bits()
+cells()
+due_payment()
+last_trans_lt()
+public_cells()
}
class AccountStatusEnum {
<<enumeration>>
+Uninit
+Active
+Frozen
+NonExist
}
class AccountStatusChangeEnum {
<<enumeration>>
+Unchanged
+Frozen
+Deleted
}
Account --> AccountStatusEnum : acc_type_name
Account --> AccountStatusChangeEnum : status changes