accounts.rs

Overview

The accounts.rs file defines the AccountsRepository struct, which manages the persistent storage and lifecycle of account states in a filesystem-based repository. It supports loading, storing, and clearing old account states based on transaction identifiers and provides thread-safe tracking of deleted accounts. The repository organizes account data under a specified directory and uses a naming scheme involving transaction logical time (LT) and transaction hashes for versioning.

This file primarily interacts with:

Account identifiers and transaction metadata types defined in crate::types.
Serialization and deserialization utilities from the tvm_types crate.
Shard account iteration from the tvm_block::ShardAccounts.
Temporary file path generation from crate::helper.
Thread-safe synchronization primitives (Arc, Mutex) from the standard library.

`AccountsRepository` Struct

Fields

Field Name	Type	Description
`data_dir`	`PathBuf`	Base directory path where account data is stored, specifically under a subdirectory named "accounts".
`unload_after`	`Option<u32>`	Optional configuration controlling how long accounts can remain loaded before they should be unloaded.
`store_after`	`u32`	Configuration parameter defining thresholds related to storing accounts.
`deleted_accounts`	`Arc<Mutex<HashMap<ThreadIdentifier, BTreeMap<u64, Vec<AccountAddress>>>>>`	Thread-safe map tracking deleted accounts per thread, indexed by logical time (LT).

Methods

`new`

pub fn new(data_dir: PathBuf, unload_after: Option<u32>, store_after: u32) -> Self

Creates a new AccountsRepository instance.

Parameters:
- data_dir: Root directory under which accounts are stored.
- unload_after: Optional unload threshold.
- store_after: Store threshold.
Returns: A new AccountsRepository with data_dir appended by "accounts" and initialized deleted accounts map.
Usage Example:

let repo = AccountsRepository::new(PathBuf::from("/var/data"), Some(300), 100);

`account_path`

fn account_path(
    &self,
    account_id: &AccountAddress,
    last_trans_hash: &tvm_types::UInt256,
    last_trans_lt: u64,
) -> PathBuf

Constructs the filesystem path for storing or loading an account state based on its identifier and transaction metadata.

Parameters:
- account_id: The account address.
- last_trans_hash: The transaction hash of the last transaction.
- last_trans_lt: The logical time of the last transaction.
Returns: A PathBuf representing the full path to the account state file.

Implementation Detail: The path is composed as:

data_dir / account_id.to_hex_string() / "{last_trans_lt}_{last_trans_hash:x}"

`load_account`

pub fn load_account(
    &self,
    account_id: &AccountAddress,
    last_trans_hash: &tvm_types::UInt256,
    last_trans_lt: u64,
) -> anyhow::Result<tvm_types::Cell>

Loads a serialized account state from the filesystem and deserializes it into a tvm_types::Cell.

Parameters:
- account_id: Account address to load.
- last_trans_hash: Hash of the last transaction.
- last_trans_lt: Logical time of the last transaction.
Returns: Result holding the deserialized tvm_types::Cell on success or an error on failure.
Constraints: Panics if unload_after is not set (must be enabled).
Errors: Reading or deserialization failures are wrapped with context including the file path.
Usage Example:

let account_cell = repo.load_account(&account_id, &last_hash, last_lt)?;

`store_account`

pub fn store_account(
    &self,
    account_id: &AccountAddress,
    last_trans_hash: &tvm_types::UInt256,
    last_trans_lt: u64,
    account: tvm_types::Cell,
) -> anyhow::Result<()>

Serializes and stores the given account state to disk atomically using a temporary file.

Parameters:
- account_id: Account address to store.
- last_trans_hash: Hash of the last transaction.
- last_trans_lt: Logical time of the last transaction.
- account: The tvm_types::Cell representing the account state.
Returns: Ok(()) on success or an error on failure.
Implementation Details:
- Creates parent directories as needed.
- Writes serialized data to a temporary file.
- Renames the temporary file atomically to the target path.
- Optionally calls sync_all() on the file if the sync_files feature is enabled.
- Uses hexadecimal and LT-based naming consistent with account_path.
Constraints: Panics if unload_after is not set.
Usage Example:

repo.store_account(&account_id, &last_hash, last_lt, account_cell)?;

`clear_old_accounts`

pub fn clear_old_accounts(
    &self,
    thread_id: &ThreadIdentifier,
    relevant_state: &ShardAccounts,
    cut_lt: u64,
)

Removes old account state files and directories that are no longer relevant, based on logical time thresholds.

Parameters:
- thread_id: Identifier for the current thread.
- relevant_state: A ShardAccounts reference providing iteration over current accounts.
- cut_lt: Logical time threshold; states older than this are candidates for deletion.
Functionality:
- Iterates over accounts known in the relevant_state.
- For each account, reads the directory to identify old states with state_lt < account.last_trans_lt().
- Deletes old state files.
- Removes account directories if all states are older than cut_lt and tracked deleted accounts indicate no recent activity.
Thread Safety: Uses mutex locking to access deleted_accounts.
Logging: Uses tracing to log deletions and warnings.
Interaction: Relies on ShardAccounts::iterate_accounts to enumerate active accounts.

`accounts_deleted`

pub fn accounts_deleted(
    &self,
    thread_id: &ThreadIdentifier,
    accounts: Vec<AccountAddress>,
    lt: u64,
)

Records accounts that have been deleted for a specific thread and logical time.

Parameters:
- thread_id: Identifier of the thread where deletion occurred.
- accounts: Vector of account addresses deleted.
- lt: Logical time at which deletion occurred.
Functionality: Inserts the deleted accounts into the deleted_accounts map under the given thread and LT key.

Accessors

get_unload_after() -> Option<u32>
Returns the current unload threshold setting.
get_store_after() -> u32
Returns the current store threshold setting.

Implementation Details and Algorithms

Account states are versioned and stored using a directory structure keyed by account hex strings and filenames combining logical time and transaction hash. This allows efficient retrieval of specific versions.
The file write operation is atomic due to writing first to a temporary file and then renaming it, which avoids partial writes or corruption.
The clear_old_accounts method implements a cleanup algorithm that removes obsolete files and directories, balancing storage usage and performance. It cross-references active shard accounts and deleted account tracking to determine what can be safely removed.
Synchronization of deleted account tracking across threads is handled via an Arc<Mutex<...>> to ensure consistency.

Interaction with Other System Components

Uses AccountAddress and ThreadIdentifier types from the local crate::types module, which represent unique account and thread identifiers.
Interfaces with tvm_types for serialization (boc::write_boc) and deserialization (boc::read_single_root_boc) of account states.
Uses ShardAccounts from tvm_block to iterate and manage accounts within a shard.
Uses get_temp_file_path utility to safely generate temporary file paths during storage.
Employs Rust's standard synchronization primitives (Arc, Mutex) to manage concurrent access to deleted accounts tracking.
Logging and diagnostics are performed via the tracing crate.

Diagram: `AccountsRepository` Structure and Workflow

classDiagram
class AccountsRepository {
-data_dir: PathBuf
-unload_after: Option<u32>
-store_after: u32
-deleted_accounts: Arc<Mutex<HashMap<ThreadIdentifier, BTreeMap<u64, Vec<AccountAddress>>>>>
+new()
+account_path()
+load_account()
+store_account()
+clear_old_accounts()
+accounts_deleted()
+get_unload_after()
+get_store_after()
}
AccountsRepository --> AccountAddress : uses
AccountsRepository --> tvm_types::Cell : stores/loads
AccountsRepository --> ShardAccounts : iterates accounts
AccountsRepository --> ThreadIdentifier : tracks thread IDs
AccountsRepository --> Mutex : synchronizes deleted_accounts
AccountsRepository --> PathBuf : manages file paths

This diagram highlights the main properties and public methods of AccountsRepository, as well as its relationships with key types used for account identification, storage, synchronization, and iteration.

accounts.rs

Overview

AccountsRepository Struct

Fields

Methods

new

account_path

load_account

store_account

clear_old_accounts

accounts_deleted