Struct ExplorerService

pub struct ExplorerService {
    pub db: ExplorerDb,
    pub darkfid_client: Arc<DarkfidRpcClient>,
}

Represents the service layer for the Explorer application, bridging the RPC layer and the database. It encapsulates explorer business logic and provides a unified interface for core functionalities, providing a clear separation of concerns between RPC handling and data management layers.

Core functionalities include:

• Data Transformation: Converting database data into structured responses suitable for RPC callers.
• Blocks: Synchronization, retrieval, counting, and management.
• Contracts: Handling native and user contract data, source code, tar files, and metadata.
• Metrics: Providing metric-related data over the life of the chain.
• Transactions: Synchronization, calculating gas data, retrieval, counting, and related block information.

Fields

db: ExplorerDb

Explorer database instance

darkfid_client: Arc<DarkfidRpcClient>

JSON-RPC client used to execute requests to Darkfi blockchain nodes

Implementations

impl ExplorerService

pub fn reset_blocks(&self) -> Result<()>

Resets blocks in the database by clearing all block related trees, returning an Ok result on success.

pub async fn put_block(&self, block: &BlockInfo) -> Result<()>

Adds the provided [BlockInfo] to the block explorer database.

This function processes each transaction in the block, calculating and updating the latest [GasMetrics] for non-genesis blocks and for transactions that are not PoW rewards. After processing all transactions, the block is permanently persisted to the explorer database.

pub fn get_block_count(&self) -> usize

Provides the total block count.

pub fn get_blocks(&self) -> Result<Vec<BlockRecord>>

Fetch all known blocks from the database.

pub fn get_block_by_hash( &self, header_hash: &str, ) -> Result<Option<BlockRecord>>

Fetch a block given its header hash from the database.

pub fn get_block_by_height(&self, height: u32) -> Result<Option<BlockRecord>>

Fetch a block given its height from the database.

pub fn last_block(&self) -> Result<Option<(u32, String)>>

Fetch the last block from the database.

pub fn get_last_n(&self, n: usize) -> Result<Vec<BlockRecord>>

Fetch the last N blocks from the database.

pub fn get_by_range(&self, start: u32, end: u32) -> Result<Vec<BlockRecord>>

Fetch blocks within a specified range from the database.

pub fn reset_to_height(&self, reset_height: u32) -> Result<()>

Resets the [ExplorerDb::blockchain::blocks] and [ExplorerDb::blockchain::transactions] trees to a specified height by removing entries above the reset_height, returning a result that indicates success or failure.

The function retrieves the last explorer block and iteratively rolls back entries in the [BlockStore::main], [BlockStore::order], and [BlockStore::difficulty] trees to the specified reset_height. It also resets the [TxStore::main] and [TxStore::location] trees to reflect the transaction state at the given height.

This operation is performed atomically using a sled transaction applied across the affected sled trees, ensuring consistency and avoiding partial updates.

impl ExplorerService

pub fn get_contract_count(&self) -> usize

Fetches the total contract count of all deployed contracts in the explorer database.

pub fn get_contracts(&self) -> Result<Vec<ContractRecord>>

Retrieves all contracts from the store excluding native contracts (DAO, Deployooor, and Money), transforming them into Vec of ContractRecords, and returns the result.

pub fn get_native_contracts(&self) -> Result<Vec<ContractRecord>>

Retrieves all native contracts (DAO, Deployooor, and Money) from the store, transforming them into Vec of ContractRecords and returns the result.

pub fn get_contract_source_paths( &self, contract_id: &ContractId, ) -> Result<Vec<String>>

Fetches a list of source code file paths for a given [ContractId], returning an empty vector if no contracts are found.

pub fn get_contract_metadata( &self, contract_id: &ContractId, ) -> Result<Option<ContractMetaData>>

Fetches ContractMetaData for a given [ContractId], returning None if no metadata is found.

pub fn get_contract_source_content( &self, contract_id: &ContractId, path: &str, ) -> Result<Option<String>>

Fetches the source code content for a specified [ContractId] and path, returning None if no source content is found.

pub fn add_contract_source( &self, contract_id: &ContractId, tar_bytes: &[u8], ) -> Result<()>

Adds source code for a specified [ContractId] from a provided tar file (in bytes).

This function extracts the tar archive from tar_bytes, then loads each source file into the store. Each file is keyed by its path prefixed with the Contract ID. Returns a successful result or an error.

pub fn add_contract_metadata( &self, contract_ids: &[ContractId], metadata: &[ContractMetaData], ) -> Result<()>

Adds provided [ContractId] with corresponding ContractMetaData pairs into the contract metadata store, returning a successful result upon success.

pub async fn deploy_native_contracts(&self) -> Result<()>

Deploys native contracts required for gas calculation and retrieval.

pub fn load_native_contract_sources(&self) -> Result<()>

Loads native contract source code into the explorer database by extracting it from tar archives created during the explorer build process. The extracted source code is associated with the corresponding [ContractId] for each loaded contract and stored.

pub fn load_native_contract_metadata(&self) -> Result<()>

Loads ContractMetaData for deployed native contracts into the explorer database by adding descriptive information (e.g., name and description) used to display contract details.

fn to_contract_record(&self, contract_id: &ContractId) -> Result<ContractRecord>

Converts a [ContractId] into a ContractRecord.

This function retrieves the ContractMetaData associated with the provided Contract ID and uses any found metadata to construct a contract record. Upon success, the function returns a ContractRecord containing relevant details about the contract.

fn get_filtered_contracts<F>(&self, filter_fn: F) -> Result<Vec<ContractRecord>>

where F: Fn(&ContractId) -> bool,

Auxiliary function that retrieves ContractRecords filtered by a provided filter_fn closure.

This function accepts a filter function Fn(&ContractId) -> bool that determines which contracts are included based on their [ContractId]. It iterates over Contract IDs stored in the blockchain’s contract tree, applying the filter function to decide inclusion. Converts the filtered Contract IDs into ContractRecord instances, returning them as a Vec, or an empty Vec if no contracts are found.

impl ExplorerService

pub fn get_base_statistics(&self) -> Result<Option<BaseStatistics>>

Fetches the latest BaseStatistics from the explorer database, or returns None if no block exists.

pub async fn get_metrics_statistics(&self) -> Result<Vec<MetricStatistics>>

Fetches the latest metrics from the explorer database, returning a vector of MetricStatistics if found, or an empty Vec if no metrics exist.

pub async fn get_latest_metrics_statistics(&self) -> Result<MetricStatistics>

Fetches the latest metrics from the explorer database, returning MetricStatistics if found, or zero-initialized defaults when not.

impl ExplorerService

pub fn reset_transactions(&self) -> Result<()>

Resets transactions in the database by clearing transaction-related trees, returning an Ok result on success.

pub fn get_transaction_count(&self) -> usize

Provides the transaction count of all the transactions in the explorer database.

pub fn get_transactions(&self) -> Result<Vec<TransactionRecord>>

Fetches all known transactions from the database.

This function retrieves all transactions stored in the database and transforms them into a vector of TransactionRecords. If no transactions are found, it returns an empty vector.

pub fn get_transactions_by_header_hash( &self, header_hash: &str, ) -> Result<Vec<TransactionRecord>>

Fetches all transactions from the database for the given block header_hash.

This function retrieves all transactions associated with the specified block header hash. It first parses the header hash and then fetches the corresponding [BlockInfo]. If the block is found, it transforms its transactions into a vector of TransactionRecords. If no transactions are found, it returns an empty vector.

pub fn get_transaction_by_hash( &self, tx_hash: &TransactionHash, ) -> Result<Option<TransactionRecord>>

Fetches a transaction given its header hash.

This function retrieves the transaction associated with the provided [TransactionHash] and transforms it into a TransactionRecord if found. If no transaction is found, it returns None.

fn get_tx_block_info( &self, tx_hash: &TransactionHash, ) -> Result<Option<BlockInfo>>

Fetches the [BlockInfo] associated with a given transaction hash.

This auxiliary function first fetches the location of the transaction in the blockchain. If the location is found, it retrieves the associated [HeaderHash] and then fetches the block information corresponding to that header hash. The function returns the [BlockInfo] if successful, or None if no location or header hash is found.

fn get_block_info(&self, header_hash: HeaderHash) -> Result<Option<BlockInfo>>

Fetches the [BlockInfo] associated with a given [HeaderHash].

This auxiliary function attempts to retrieve the block information using the specified [HeaderHash]. It returns the associated [BlockInfo] if found, or None when not found.

pub async fn calculate_tx_gas_data( &self, tx: &Transaction, verify_fee: bool, ) -> Result<GasData>

Calculates the gas data for a given transaction, returning a [GasData] instance detailing various aspects of the gas usage.

fn to_tx_record( &self, block_info_opt: Option<BlockInfo>, tx: &Transaction, ) -> Result<TransactionRecord>

Converts a [Transaction] and its associated block information into a TransactionRecord.

This auxiliary function first retrieves the gas data associated with the provided transaction. If [BlockInfo] is not provided, it attempts to fetch it using the transaction’s hash, returning an error if the block information cannot be found. Upon success, the function returns a TransactionRecord containing relevant details about the transaction.

impl ExplorerService

pub async fn sync_blocks(&self, reset: bool) -> Result<()>

Synchronizes blocks between the explorer and a Darkfi blockchain node, ensuring the database remains consistent by syncing any missing or outdated blocks.

If provided reset is true, the explorer’s blockchain-related and metric sled trees are purged and syncing starts from the genesis block. The function also handles reorgs by re-aligning the explorer state to the correct height when blocks are outdated. Returns a result indicating success or failure.

Reorg handling is delegated to the Self::reorg_blocks function, whose documentation provides more details on the reorg process during block syncing.

async fn reorg_blocks( &self, last_synced_height: u32, last_darkfid_height: u32, ) -> Result<u32>

Handles blockchain reorganizations (reorgs) during the explorer node’s startup synchronization with Darkfi nodes, ensuring the explorer provides a consistent and accurate view of the blockchain.

A reorg occurs when the blocks stored by the blockchain nodes diverge from those stored by the explorer. This function resolves inconsistencies by identifying the point of divergence, searching backward through block heights, and comparing block hashes between the explorer database and the blockchain node. Once a common block height is found, the explorer is re-aligned to that height.

If no common block can be found, the explorer resets to the “genesis height,” removing all blocks, transactions, and metrics from its database to resynchronize with the canonical chain from the nodes.

Returns the last height at which the explorer’s state was successfully re-aligned with the blockchain.

impl ExplorerService

pub fn new( db_path: String, darkfid_client: Arc<DarkfidRpcClient>, ) -> Result<Self>

Creates a new ExplorerService instance.

pub async fn init(&self) -> Result<()>

Initializes the explorer service by deploying native contracts and loading native contract source code and metadata required for its operation.

pub fn reset_explorer_state(&self, height: u32) -> Result<()>

Resets the explorer state to the specified height. If a genesis block height is provided, all blocks and transactions are purged from the database. Otherwise, the state is reverted to the given height. The explorer metrics are updated to reflect the updated blocks and transactions up to the reset height, ensuring consistency. Returns a result indicating success or an error if the operation fails.