account_boc_loader.rs

Overview

This file provides functionality to retrieve and reconstruct an account's state from the shard state stored in an optimistic repository. It focuses on loading the account data from a shard state representation, handling complexities such as account redirections and external accounts, and returning the account's structured form along with its optional decentralized application (DApp) identifier.

The core function, get_account_from_shard_state, takes a thread-safe reference to a repository and an account address string, then returns the account's BOC (Bag of Cells) representation (tvm_block::Account) and an optional UInt256 representing the DApp identifier.

Detailed Explanation

Function: get_account_from_shard_state

pub fn get_account_from_shard_state(
    repository: Arc<Mutex<RepositoryImpl>>,
    account_address: &str,
) -> anyhow::Result<(tvm_block::Account, Option<UInt256>)>

Purpose

Retrieves the account data from the shard state managed by the repository. The function handles cases where the account is a redirect or an external account, ensuring the returned account data is consistent and valid.

Parameters

• repository: An Arc<Mutex<RepositoryImpl>> instance providing synchronized access to the repository implementation containing shard states and accounts.

• account_address: A string slice representing the account's address to be fetched.

Returns

• Ok((tvm_block::Account, Option<UInt256>)): On success, returns a tuple containing the account's BOC representation and an optional DApp identifier.

• Err(anyhow::Error): Returns errors if the shard state or account cannot be found or if inconsistencies are detected.

Workflow

1. Lock Repository: Acquire a mutex lock on the repository to safely access the data.

2. Load Default Shard State: Retrieve the last finalized optimistic state for the default thread.

3. Parse Account Address: Convert the account address string into an internal AccountAddress type for querying.

4. Determine Routing and Thread:

   • Construct an AccountRouting using the DApp identifier and account ID.

   • Find the matching thread from the default state's threads table.

5. Load No-DApp Shard State: Fetch the shard state corresponding to the determined thread.

6. Read Accounts from Shard State: Extract accounts from the shard state.

7. Retrieve Account:

   • Find the specific account by its ID.

   • Handle errors if the account is missing.

8. Handle Redirect Accounts:

   • If the account is a redirect, resolve the actual DApp ID.

   • Find the appropriate thread for the actual DApp routing.

   • Load the shard state and account from this actual thread.

9. Handle External Accounts:

   • For external accounts, verify the account cell's hash against cached or repository-loaded data.

   • Set the account cell for the account structure.

10. Extract DApp ID: Clone the DApp identifier from the account if present.

11. Convert to Structured Account: Read the account's BOC data and convert it into a structured tvm_block::Account.

12. Return Result: Provide the reconstructed account and optional DApp identifier.

Usage Example

use std::sync::Arc;
use parking_lot::Mutex;
use anyhow::Result;

fn example_usage(repo: Arc<Mutex<RepositoryImpl>>, addr: &str) -> Result<()> {
    let (account, dapp_id) = get_account_from_shard_state(repo, addr)?;
    println!("Loaded account with DApp ID: {:?}", dapp_id);
    // Further processing with `account`...
    Ok(())
}

Important Implementation Details

• Thread Safety: The use of Arc<Mutex<RepositoryImpl>> ensures concurrent access to the repository is safely managed.

• Optimistic State Handling: The function relies on the optimistic state system (OptimisticState), specifically the last finalized states for threads, to locate the shard state containing the account.

• Account Routing: The routing logic uses AccountRouting and ThreadIdentifier to determine the exact thread shard state to query, handling complex account distribution.

• Redirect Accounts: Accounts marked as redirects require an additional lookup to retrieve the actual account data from a different shard.

• External Accounts: Special verification is performed for external accounts, ensuring the integrity of their account cell hashes against cached or repository data.

• Error Propagation: Uses anyhow::Result extensively for error handling, providing detailed error messages when shard states or accounts are missing or corrupted.

• Tracing: Employs tracing::trace! macros for detailed step-by-step logging to aid in debugging and monitoring.

Interaction with Other System Components

• Repository Layer: Interfaces with RepositoryImpl, OptimisticState, and related structures to access shard states and accounts.

• Types Module: Uses types such as AccountAddress, AccountRouting, DAppIdentifier, and ThreadIdentifier to manage account and state routing logic.

• tvm_types and tvm_block: Leverages types from these crates/modules for account identification and BOC serialization/deserialization.

• Accounts Repository: For external accounts, it interacts with accounts_repository() to load account cells based on transaction history.

• Threads and Shard States: Integrates with thread-based state partitioning (ThreadIdentifier) to locate the correct shard state for account retrieval.

Visual Diagram

flowchart TD
A[get_account_from_shard_state] --> B[Lock Repository]
B --> C[Load Default Optimistic State]
C --> D[Parse Account Address]
D --> E[Construct AccountRouting]
E --> F[Find Potential Thread]
F --> G[Load No-DApp Shard State]
G --> H[Read Accounts]
H --> I[Find Account by ID]
I --> J{Is Redirect?}
J -- Yes --> K[Resolve Actual DApp ID]
K --> L[Find Actual Thread]
L --> M[Load Actual Shard State]
M --> N[Read Accounts]
N --> O[Find Account by ID]
J -- No --> P{Is External?}
P -- Yes --> Q[Verify Account Cell Hash]
Q --> R[Set Account Cell]
P -- No --> S[Proceed]
O --> S
R --> S
S --> T[Extract DApp ID]
T --> U[Convert to tvm_block::Account]
U --> V[Return Account and DApp ID]

This flowchart illustrates the decision points and loading steps in the account retrieval process, highlighting handling for redirect and external accounts within the shard state system.