mod.rs

Overview

This file defines the GraphQL schema entities and data transformation logic related to blockchain blocks within the system. It provides detailed data structures representing blocks, their references, value flows, transactions, and statuses, along with the necessary conversions from database models to GraphQL objects. The file primarily facilitates querying block-related data in a structured manner via GraphQL, including complex field formatting and relationships between blocks and their messages.

The file also exposes filtering and resolver modules (filter and resolver) for block-related queries, enabling flexible data access and manipulation.

Modules and Re-exports

• filter: Contains filtering logic for querying blocks.

• resolver: Contains GraphQL resolvers to load blocks.

• Re-exports BlockFilter and BlockLoader for external usage.

Type Aliases

• Boolean = bool

• Int = i32

• Float = f64

These aliases improve readability for GraphQL type mapping.

Enum: BlockProcessingStatusEnum

Represents the processing status of a block.

Variants

• Unknown: Status is unknown (default).

• Proposed: Block is proposed.

• Finalized: Block is finalized.

• Refused: Block is refused.

Implementation Details

• Implements From<Option<i64>> for conversion from optional integer status codes.

• Maps integer codes 1, 2, 3 to Proposed, Finalized, and Refused respectively, otherwise Unknown.

Usage Example

let status_enum = BlockProcessingStatusEnum::from(Some(2)); // returns Finalized

Struct: ExtBlkRef

Represents an external block reference with optional fields.

Fields

• end_lt: Optional logical time indicating the end of block formation (hidden from GraphQL).

• file_hash: Optional file hash string.

• root_hash: Optional root hash string.

• seq_no: Optional sequence number as float.

Complex Fields and Methods

• end_lt(format: Option<BigIntFormat>) -> Option<String>: Formats the end_lt field for GraphQL output using the helper format_big_int.

Usage

Used to represent references to other blocks, such as previous blocks or alternative references.

Structs: BlockMasterShardHashesDescr, BlockMasterShardHashes, BlockMaster

These represent nested structures related to masterchain shard hashes, including generation time and root hash.

• BlockMasterShardHashesDescr: Contains generation time and root hash.

• BlockMasterShardHashes: Contains workchain ID, shard ID, and description.

• BlockMaster: Contains shard hashes.

Used internally within the Block struct to describe masterchain block details.

Struct: Directives

Contains directive-related information for a block.

• share_state_resource_address: An optional address string related to shared state resources.

Struct: BlockValueFlow

Represents the flow of value (currency) within a block.

Fields

• Various optional string fields representing amounts (e.g., created, exported, fees_collected), hidden from direct GraphQL output.

• Corresponding collections of OtherCurrency for these amounts, exposed to GraphQL.

ComplexObject Methods

Each numeric string field has an async method that formats the amount using format_big_int for presentation.

Usage

Used to track currency movements such as minted tokens, fees, and transfers related to a block.

Struct: BlockAccountBlocksTransactions

Represents individual transactions within account blocks of a block.

Fields

• lt: Logical time of the transaction (hidden from GraphQL).

• total_fees: Total fees paid in the transaction (hidden from GraphQL).

• total_fees_other: Fees in other currencies, exposed to GraphQL.

• transaction_id: Optional transaction identifier.

ComplexObject Methods

• lt(format: Option<BigIntFormat>) -> Option<String>: Formats logical time.

• total_fees(format: Option<BigIntFormat>) -> Option<String>: Formats total fees.

Struct: BlockAccountBlocks

Represents account blocks within a block.

Fields

• account_addr: Account address string.

• new_hash: New hash after block application.

• old_hash: Previous hash.

• tr_count: Transaction count.

• transactions: Optional list of BlockAccountBlocksTransactions.

Struct: Block

Core GraphQL object representing a blockchain block with extensive fields.

Selected Fields

• id: Unique block identifier.

• account_blocks: Optional list of BlockAccountBlocks.

• after_merge, after_split, before_split, want_merge, want_split: Optional booleans indicating block state changes.

• aggregated_signature: Aggregated signature bytes.

• boc: Optional serialized bag of cells encoded as base64.

• chain_order: Unique field for pagination and sorting.

• created_by: Optional public key of the block producer.

• directives: Directives object.

• end_lt, start_lt: Logical creation times for block formation.

• file_hash: Shard block file hash.

• flags, gen_catchain_seqno, gen_software_version, gen_utime, gen_validator_list_hash_short, global_id: Various metadata fields.

• hash: Block hash (optional, usually same as id).

• in_msg_descr, out_msg_descr: Optional vectors of incoming and outgoing messages (InMsg and OutMsg).

• key_block: Indicates if this is a key block.

• master, master_ref: Masterchain-related references.

• prev_ref, prev_alt_ref, prev_vert_ref, prev_vert_alt_ref: References to previous blocks.

• producer_id: Producer identifier string.

• rand_seed: Random seed string.

• seq_no: Sequence number.

• shard: Optional shard identifier.

• signature_occurrences: Signature occurrences as bytes.

• status: Numeric status code.

• status_name: Enum variant of block processing status.

• thread_id: Optional thread identifier.

• tr_count: Transaction count.

• value_flow: Optional BlockValueFlow object.

• version: Block version number.

• vert_seq_no: Vertical sequence number.

• workchain_id: Workchain identifier.

Conversion from Database Model

Implements From<db::Block> trait to convert from database block representation to GraphQL Block. This involves:

• Encoding boc with base64.

• Constructing ExtBlkRef for previous alternative references.

• Converting optional integers and floats to appropriate types.

• Formatting timestamps using chrono to human-readable strings.

• Populating fields with proper defaults or transformations.

• Handling features like store_events_only to conditionally include prev_ref.

ComplexObject Methods

• end_lt(format: Option<BigIntFormat>): Formats the end logical time.

• gen_software_capabilities(format: Option<BigIntFormat>): Formats software capabilities.

• start_lt(format: Option<BigIntFormat>): Formats the start logical time.

Other Methods

• set_in_msg_descr(&mut self, in_msgs: Vec<InBlockMessage>): Sets the incoming message descriptors for the block.

• (Commented out) set_out_msg_descr for setting outgoing messages.

Interaction with Other Parts of the System

• Uses helper functions format_big_int, ToBool, ToFloat, ToInt from crate::helpers for type conversions and formatting.

• Imports database message types InBlockMessage and schema database types.

• Depends on InMsg and OutMsg types from sibling modules for message descriptions.

• Uses OtherCurrency and BigIntFormat from crate::schema::graphql::currency and formats respectively for currency representation and formatting.

• Exposes filtering and resolving capabilities via filter::BlockFilter and resolver::BlockLoader to integrate with GraphQL query handling.

• Converts database entities (db::Block) to GraphQL objects for API responses.

Important Implementation Details

• Logical times (start_lt, end_lt) are stored as strings internally but formatted using a BigInt formatter on demand.

• The conversion from database block to GraphQL Block carefully handles optional fields, default values, and feature flags.

• Timestamps are converted to human-readable UTC strings using the chrono crate.

• The status field is stored as a numeric code while status_name is an enum for semantic clarity.

• The BlockValueFlow and BlockAccountBlocksTransactions structs use complex objects to provide formatted numeric fields alongside raw data.

• Some GraphQL fields are intentionally hidden (#[graphql(skip)]) and exposed only via computed methods to support formatting and abstraction.

• The file enables extensibility through modular submodules for filtering and resolving queries.

Mermaid Diagram: Structure of mod.rs

classDiagram
class Block {
+id: String
+account_blocks: Option<Vec<BlockAccountBlocks>>
+after_merge: Option<Boolean>
+after_split: Option<Boolean>
+aggregated_signature: Vec<u8>
+before_split: Option<Boolean>
+boc: Option<String>
+chain_order: Option<String>
+created_by: Option<String>
+directives: Directives
+file_hash: String
+flags: Option<Int>
+gen_catchain_seqno: Option<Float>
+gen_software_capabilities: Option<String>
+gen_software_version: Option<Float>
+gen_utime: Option<Int>
+gen_utime_string: String
+global_id: Option<Int>
+hash: Option<String>
+in_msg_descr: Option<Vec<Option<InMsg>>>
+key_block: Option<Boolean>
+master: Option<BlockMaster>
+master_ref: Option<ExtBlkRef>
+prev_ref: Option<ExtBlkRef>
+prev_alt_ref: Option<ExtBlkRef>
+producer_id: Option<String>
+rand_seed: String
+seq_no: i64
+shard: Option<String>
+status: u8
+status_name: BlockProcessingStatusEnum
+thread_id: Option<String>
+tr_count: Option<i32>
+value_flow: Option<BlockValueFlow>
+version: Option<Float>
+workchain_id: Option<i64>
+set_in_msg_descr()
}
class ExtBlkRef {
-end_lt: Option<String>
+file_hash: Option<String>
+root_hash: Option<String>
+seq_no: Option<f64>
+end_lt()
}
class BlockValueFlow {
-created: Option<String>
+created_other: Option<Vec<OtherCurrency>>
-exported: Option<String>
+exported_other: Option<Vec<OtherCurrency>>
-fees_collected: Option<String>
+fees_collected_other: Option<Vec<OtherCurrency>>
-fees_imported: Option<String>
+fees_imported_other: Option<Vec<OtherCurrency>>
-from_prev_blk: Option<String>
+from_prev_blk_other: Option<Vec<OtherCurrency>>
-imported: Option<String>
+imported_other: Option<Vec<OtherCurrency>>
-minted: Option<String>
+minted_other: Option<Vec<OtherCurrency>>
-to_next_blk: Option<String>
+to_next_blk_other: Option<Vec<OtherCurrency>>
+created()
+exported()
+fees_collected()
+fees_imported()
+from_prev_blk()
+imported()
+minted()
+to_next_blk()
}
class BlockAccountBlocks {
+account_addr: Option<String>
+new_hash: Option<String>
+old_hash: Option<String>
+tr_count: Option<i32>
+transactions: Option<Vec<BlockAccountBlocksTransactions>>
}
class BlockAccountBlocksTransactions {
-lt: Option<String>
-total_fees: Option<String>
+total_fees_other: Option<Vec<OtherCurrency>>
+transaction_id: Option<String>
+lt()
+total_fees()
}
class BlockMaster {
+shard_hashes: Option<BlockMasterShardHashes>
}
class BlockMasterShardHashes {
+workchain_id: Option<Int>
+shard: Option<String>
+descr: Option<BlockMasterShardHashesDescr>
}
class BlockMasterShardHashesDescr {
+gen_utime: Option<f64>
+root_hash: Option<String>
}
class Directives {
+share_state_resource_address: Option<String>
}
Block --> ExtBlkRef : prev_ref, prev_alt_ref, master_ref
Block --> BlockValueFlow : value_flow
Block --> BlockAccountBlocks : account_blocks
BlockAccountBlocks --> BlockAccountBlocksTransactions : transactions
Block --> BlockMaster : master
BlockMaster --> BlockMasterShardHashes : shard_hashes
BlockMasterShardHashes --> BlockMasterShardHashesDescr : descr
Block --> Directives : directives

This diagram illustrates the primary data structures in the file and their relationships, showing how the Block object is composed of multiple nested entities representing block metadata, references, transaction details, and value flow.