mod.rs

Overview

This file defines GraphQL schema objects and data conversion logic related to blockchain blocks within the application. It provides data structures representing blocks, their constituent parts, and associated metadata. The file facilitates the conversion between database models (db::Block) and GraphQL-friendly types used in the schema, enabling querying and manipulation of block data via GraphQL API. Key domain concepts such as block status, block references, value flows, and account transactions within blocks are modeled here.

The file also includes utility implementations for formatting large integer fields and enumerations describing block processing states. It offers asynchronous GraphQL resolvers for complex fields that require formatting or additional computation. This module interacts closely with other parts of the schema, particularly block filtering and resolution modules (filter and resolver submodules), message handling (InMsg, OutMsg), and currency formatting.

Modules and Re-exports

• filter (submodule): Contains filtering logic for blocks, exposed as BlockFilter.

• resolver (submodule): Contains loading and resolving logic for blocks, exposed as BlockLoader.

• Re-exports:

  • BlockFilter from filter

  • BlockLoader from resolver

Type Aliases

• Boolean = bool

• Int = i32

• Float = f64

These aliases simplify readability and maintain consistency within the GraphQL schema definitions.

Enum: BlockProcessingStatusEnum

Description

Represents the processing status of a block with four possible states:

• Unknown

• Proposed

• Finalized

• Refused

Implementation Details

• Implements From<Option<i64>> to convert numeric status codes from the database into enum variants.

• Status code mapping:

  • 1 → Proposed

  • 2 → Finalized

  • 3 → Refused

  • Any other value or None → Unknown

Usage Example

let status_code: Option<i64> = Some(2);
let status_enum = BlockProcessingStatusEnum::from(status_code);
// status_enum == BlockProcessingStatusEnum::Finalized

Structs and Detailed Descriptions

ExtBlkRef

GraphQL object representing an external block reference with optional fields:

• end_lt: Logical time indicating block formation end (optional, formatted as string).

• file_hash: Hash of the block file.

• root_hash: Root hash of the block.

• seq_no: Sequence number as a floating-point.

Methods

• end_lt(format: Option<BigIntFormat>) -> Option<String>: Formats the end_lt field using a provided big integer format.

BlockMasterShardHashesDescr

Represents metadata about master shard hashes:

• gen_utime: Generation timestamp (optional float).

• root_hash: Root hash string.

BlockMasterShardHashes

Represents shard hash data for a master block:

• workchain_id: Workchain identifier.

• shard: Shard string.

• descr: Description object (BlockMasterShardHashesDescr).

BlockMaster

Represents a master block containing shard hash information:

• shard_hashes: Optional shard hashes (BlockMasterShardHashes).

Directives

Contains specific directives related to the block:

• share_state_resource_address: Optional resource address string.

BlockValueFlow

Describes the flow of values (currencies/tokens) related to the block:

• Multiple optional fields representing amounts in base currency (as strings) and other currencies (vectors of OtherCurrency):

  • created, created_other

  • exported, exported_other

  • fees_collected, fees_collected_other

  • fees_imported, fees_imported_other

  • from_prev_blk, from_prev_blk_other

  • imported, imported_other

  • minted, minted_other

  • to_next_blk, to_next_blk_other

Methods

Each base currency field has an async method that formats it for GraphQL queries using format_big_int.

BlockAccountBlocksTransactions

Represents a transaction within an account block:

• lt: Logical time.

• total_fees: Total fees paid in base currency.

• total_fees_other: Fees paid in other currencies.

• transaction_id: Identifier string for the transaction.

Methods

Async methods provide formatted versions of lt and total_fees fields.

BlockAccountBlocks

Represents an account block inside a block:

• account_addr: Account address.

• new_hash: New hash string after block application.

• old_hash: Previous hash string.

• tr_count: Number of transactions.

• transactions: Optional vector of transactions (BlockAccountBlocksTransactions).

Block

The main GraphQL object representing a blockchain block:

• Identifiers and Metadata:

  • id: Unique string identifier.

  • hash: Optional block hash.

  • seq_no: Sequence number.

  • shard: Shard identifier string.

  • workchain_id: Workchain integer ID.

  • version: Block version as float.

  • gen_utime: Generation timestamp.

  • gen_utime_string: Human-readable formatted generation time.

  • status: Numeric processing status.

  • status_name: Enum status (BlockProcessingStatusEnum).

  • chain_order: Chain order string for pagination/sorting.

  • key_block: Boolean indicating if this is a key block.

  • producer_id: Producer’s identifier.

  • rand_seed: Random seed string.

• Block Content and Signatures:

  • boc: Serialized block data encoded as base64.

  • aggregated_signature: Vector of bytes representing combined signatures.

  • signature_occurrences: Vector of signature occurrences bytes.

• Block Relations:

  • prev_ref, prev_alt_ref, prev_vert_ref, prev_vert_alt_ref: Optional external references to related blocks.

  • master, master_ref: Optional master block info and references.

  • master_seq_no: Sequence number of masterchain block committing this block.

  • prev_key_block_seqno: Seq no of the previous key block.

  • min_ref_mc_seqno: Last known master block at shard generation time.

• Block Behavior Flags:

  • after_merge, after_split, before_split: Booleans indicating block state in relation to merges/splits.

  • want_merge, want_split: Flags representing if the block wants to merge or split.

• Messages and Transactions:

  • in_msg_descr: Optional vector of inbound message descriptions (InMsg).

  • out_msg_descr: Optional vector of outbound message descriptions (OutMsg).

  • out_msgs: Optional serialized outbound messages string.

  • account_blocks: Optional vector of account blocks (BlockAccountBlocks).

  • tr_count: Number of transactions in the block.

• Directives and Value Flow:

  • directives: Directives struct.

  • value_flow: Optional BlockValueFlow struct.

• Other Fields:

  • flags, gen_catchain_seqno, gen_software_version, gen_software_capabilities, gen_validator_list_hash_short, global_id, thread_id, vert_seq_no: Various optional numeric and string metadata fields.

Conversion Implementation

• Implements From<db::Block> to convert database block model into GraphQL Block.

• Handles optional fields and data transformations such as base64 encoding of block data (boc).

• Constructs external block references conditionally.

• Formats generation time into a human-readable string.

• Converts boolean-like integer fields using helper traits (ToBool, ToInt, ToFloat).

Complex Object Resolvers

• Async methods to format large integer fields (end_lt, start_lt, gen_software_capabilities) for GraphQL responses.

• Logical time fields (start_lt and end_lt) correspond to blockchain event timing and are formatted using a custom big integer formatter.

Public Methods

• set_in_msg_descr(&mut self, in_msgs: Vec<InBlockMessage>): Sets inbound message descriptions from a vector of database messages by converting each into GraphQL InMsg.

Implementation Details and Algorithms

• Formatting of Big Integers: Several fields represent large numeric values stored as strings to avoid loss of precision in JSON or GraphQL. These fields are exposed in GraphQL with asynchronous resolvers that apply formatting using the format_big_int helper. This approach ensures consistent representation of blockchain logical times and large amounts.

• Conversion from DB Model: The From<db::Block> trait implementation performs field-by-field mapping from the persistent database block representation to the API-facing GraphQL type. It includes conditional logic for optional fields and data transformations such as:

  • Base64 encoding of block binary objects.

  • DateTime formatting with chrono for generation time.

  • Boolean conversions from integer flags using custom traits.

  • Construction of nested objects like ExtBlkRef.

• Enum Mapping: The BlockProcessingStatusEnum maps integer status codes from the DB to meaningful enum variants, improving API semantics.

• Use of Async GraphQL Macros: The use of #[graphql(complex)] allows defining async resolvers on fields that require additional processing or formatting beyond direct field access.

Interaction with Other System Components

• Message Types: Uses InMsg and OutMsg from sibling modules to represent inbound and outbound messages attached to blocks. These likely correspond to transaction and message entities in the blockchain.

• Helpers: Relies on utility functions and traits from crate::helpers for data formatting and conversions (format_big_int, ToBool, ToInt, ToFloat).

• Database Layer: Converts from db::Block entity representing persistent block data.

• Currency Representation: Uses OtherCurrency type from the currency schema submodule to represent multiple currency denominations in value flow.

• Filter and Resolver Submodules: Exposes BlockFilter and BlockLoader for filtering and loading block data, indicating this module is central in the GraphQL API schema for blocks.

GraphQL Schema Highlights

• Uses SimpleObject, ComplexObject, and Enum derive macros for GraphQL schema generation.

• Fields named in snake_case to match GraphQL naming conventions.

• Skips certain fields in GraphQL exposure (e.g., raw internal data) with #[graphql(skip)].

• Provides rich nested structures to represent hierarchical blockchain data.

Visual Diagram

classDiagram
class Block {
+id: String
+hash: Option<String>
+seq_no: i64
+shard: Option<String>
+workchain_id: Option<i64>
+status: u8
+status_name: BlockProcessingStatusEnum
+gen_utime_string: String
+boc: Option<String>
+aggregated_signature: Vec<u8>
+set_in_msg_descr()
}
class ExtBlkRef {
+end_lt: Option<String>
+file_hash: Option<String>
+root_hash: Option<String>
+seq_no: Option<f64>
}
class BlockProcessingStatusEnum {
<<enumeration>>
Unknown
Proposed
Finalized
Refused
}
class BlockValueFlow {
+created: Option<String>
+exported: Option<String>
+fees_collected: Option<String>
+fees_imported: Option<String>
+from_prev_blk: Option<String>
+imported: Option<String>
+minted: Option<String>
+to_next_blk: Option<String>
}
class BlockAccountBlocks {
+account_addr: Option<String>
+new_hash: Option<String>
+old_hash: Option<String>
+tr_count: Option<i32>
}
class BlockAccountBlocksTransactions {
+lt: Option<String>
+total_fees: Option<String>
+transaction_id: Option<String>
}
class Directives {
+share_state_resource_address: Option<String>
}
Block "1" o-- "*" BlockAccountBlocks : contains
BlockAccountBlocks "1" o-- "*" BlockAccountBlocksTransactions : contains
Block "1" o-- "1" Directives : has
Block "1" o-- "1" BlockValueFlow : has
Block "1" o-- "0..1" ExtBlkRef : prev_ref, prev_alt_ref, etc.
Block --> BlockProcessingStatusEnum : status_name

Usage Examples

Conversion from Database Block

let db_block: db::Block = fetch_block_from_db();
let gql_block = Block::from(db_block);

Setting Inbound Message Descriptions

let mut block = gql_block;
let in_msgs: Vec<InBlockMessage> = fetch_inbound_messages();
block.set_in_msg_descr(in_msgs);

Querying Formatted Logical Time in GraphQL

GraphQL query example to get the formatted start_lt field with a specific format:

query {
  block(id: "block_id") {
    start_lt(format: DECIMAL)
  }
}

References to Related Topics

• Formatting and conversion utilities are detailed in helpers subtopic.

• Currency representation and multi-currency handling are discussed in currency schema subtopic.

• Message types InMsg and OutMsg are defined in the message module.

• Filtering and loading mechanisms for blocks are found in [filter and resolver modules](/filter, /resolver).

• GraphQL schema design utilizing async_graphql macros and patterns is covered under GraphQL Schema Design.