Struct Store 

pub struct Store { /* private fields */ }

Main storage interface for the ethrex client.

The Store provides a high-level API for all blockchain data operations:

• Block storage and retrieval
• State trie management
• Account and storage queries
• Transaction indexing

Thread Safety

Store is Clone and thread-safe. All clones share the same underlying database connection and caches via Arc.

Caching

The store maintains several caches for performance:

• Trie Layer Cache: Recent trie nodes for fast state access
• Code Cache: LRU cache for contract bytecode (64MB default)
• Latest Block Cache: Cached latest block header for RPC

Example

let store = Store::new("./data", EngineType::RocksDB)?;

// Add a block
store.add_block(block).await?;

// Query account balance
let info = store.get_account_info(block_number, address)?;
let balance = info.map(|a| a.balance).unwrap_or_default();

Implementations

impl Store

pub async fn wait_for_persistence_idle(&self) -> Result<(), StoreError>

Block until the trie-update background worker has drained every prior message and is waiting for new work — i.e. Phase 2 (disk write of the bottom-most diff layer) and Phase 3 (in-memory layer removal) for all previously-applied updates have completed.

Implementation: the worker channel is sync_channel(0), so a send only returns once the worker calls recv() on the next loop iteration. TrieMessage::Ping carries no work, so the send completing is itself the idle signal.

Caller’s responsibility: hold off other senders to trie_update_worker_tx while this is in flight. Under concurrent producers the rendezvous guarantee degrades to “the prior message has been drained”, not “persistence is idle going forward” — a racing Update from another thread can be in-flight by the time this returns.

pub async fn add_block(&self, block: Block) -> Result<(), StoreError>

Add a block in a single transaction. This will store -> BlockHeader, BlockBody, BlockTransactions, BlockNumber.

pub async fn add_blocks(&self, blocks: Vec<Block>) -> Result<(), StoreError>

Add a batch of blocks in a single transaction. This will store -> BlockHeader, BlockBody, BlockTransactions, BlockNumber.

pub async fn add_block_header( &self, block_hash: BlockHash, block_header: BlockHeader, ) -> Result<(), StoreError>

Add block header

pub async fn add_block_headers( &self, block_headers: Vec<BlockHeader>, ) -> Result<(), StoreError>

Add a batch of block headers

pub fn get_block_header( &self, block_number: BlockNumber, ) -> Result<Option<BlockHeader>, StoreError>

Obtain canonical block header

pub async fn add_block_body( &self, block_hash: BlockHash, block_body: BlockBody, ) -> Result<(), StoreError>

Add block body

pub async fn get_block_body( &self, block_number: BlockNumber, ) -> Result<Option<BlockBody>, StoreError>

Obtain canonical block body

pub async fn remove_block( &self, block_number: BlockNumber, ) -> Result<(), StoreError>

Remove canonical block

pub async fn get_block_bodies( &self, from: BlockNumber, to: BlockNumber, ) -> Result<Vec<Option<BlockBody>>, StoreError>

Obtain canonical block bodies in from..=to

pub async fn get_block_bodies_by_hash( &self, hashes: Vec<BlockHash>, ) -> Result<Vec<BlockBody>, StoreError>

Obtain block bodies from a list of hashes

pub async fn get_block_body_by_hash( &self, block_hash: BlockHash, ) -> Result<Option<BlockBody>, StoreError>

Obtain any block body using the hash

pub fn get_block_header_by_hash( &self, block_hash: BlockHash, ) -> Result<Option<BlockHeader>, StoreError>

pub fn add_pending_block(&self, block: Block) -> Result<(), StoreError>

pub async fn get_pending_block( &self, block_hash: BlockHash, ) -> Result<Option<Block>, StoreError>

pub async fn add_block_number( &self, block_hash: BlockHash, block_number: BlockNumber, ) -> Result<(), StoreError>

Add block number for a given hash

pub async fn get_block_number( &self, block_hash: BlockHash, ) -> Result<Option<BlockNumber>, StoreError>

Obtain block number for a given hash

pub async fn add_transaction_location( &self, transaction_hash: H256, block_number: BlockNumber, block_hash: BlockHash, index: Index, ) -> Result<(), StoreError>

Store transaction location (block number and index of the transaction within the block)

pub async fn add_transaction_locations( &self, locations: Vec<(H256, BlockNumber, BlockHash, Index)>, ) -> Result<(), StoreError>

Store transaction locations in batch (one db transaction for all)

pub async fn get_transaction_location( &self, transaction_hash: H256, ) -> Result<Option<(BlockNumber, BlockHash, Index)>, StoreError>

Obtain transaction location (block hash and index)

pub async fn add_receipt( &self, block_hash: BlockHash, index: Index, receipt: Receipt, ) -> Result<(), StoreError>

Add receipt

pub async fn add_receipts( &self, block_hash: BlockHash, receipts: Vec<Receipt>, ) -> Result<(), StoreError>

Add receipts

pub async fn get_receipt( &self, block_number: BlockNumber, index: Index, ) -> Result<Option<Receipt>, StoreError>

Obtain receipt for a canonical block represented by the block number.

pub fn get_account_code( &self, code_hash: H256, ) -> Result<Option<Code>, StoreError>

Get account code by its hash.

Check if the code exists in the cache (attribute account_code_cache), if not, reads the database, and if it exists, decodes and returns it.

pub fn code_exists(&self, code_hash: H256) -> Result<bool, StoreError>

Check if account code exists by its hash, without constructing the full Code struct. More efficient than get_account_code for existence checks since it skips RLP decoding and Code struct construction (no jump_targets deserialization). Note: The underlying get() still reads the value from RocksDB (including blob files).

pub fn get_code_metadata( &self, code_hash: H256, ) -> Result<Option<CodeMetadata>, StoreError>

Get code metadata (length) by its hash.

Checks cache first, falls back to database. If metadata is missing, falls back to loading full code and extracts length (auto-migration).

pub async fn add_account_code(&self, code: Code) -> Result<(), StoreError>

Add account code

pub async fn clear_snap_state(&self) -> Result<(), StoreError>

Clears all checkpoint data created during the last snap sync

pub async fn get_transaction_by_hash( &self, transaction_hash: H256, ) -> Result<Option<Transaction>, StoreError>

pub async fn get_transaction_by_location( &self, block_hash: H256, index: u64, ) -> Result<Option<Transaction>, StoreError>

pub async fn get_block_by_hash( &self, block_hash: BlockHash, ) -> Result<Option<Block>, StoreError>

pub async fn get_block_by_number( &self, block_number: BlockNumber, ) -> Result<Option<Block>, StoreError>

pub async fn get_canonical_block_hash( &self, block_number: BlockNumber, ) -> Result<Option<BlockHash>, StoreError>

pub async fn set_chain_config( &mut self, chain_config: &ChainConfig, ) -> Result<(), StoreError>

Stores the chain configuration values, should only be called once after reading the genesis file Ignores previously stored values if present

pub async fn update_earliest_block_number( &self, block_number: BlockNumber, ) -> Result<(), StoreError>

Update earliest block number

pub async fn get_earliest_block_number(&self) -> Result<BlockNumber, StoreError>

Obtain earliest block number

pub async fn get_finalized_block_number( &self, ) -> Result<Option<BlockNumber>, StoreError>

Obtain finalized block number

pub async fn get_safe_block_number( &self, ) -> Result<Option<BlockNumber>, StoreError>

Obtain safe block number

pub async fn get_latest_block_number(&self) -> Result<BlockNumber, StoreError>

Obtain latest block number

pub async fn update_pending_block_number( &self, block_number: BlockNumber, ) -> Result<(), StoreError>

Update pending block number

pub async fn get_pending_block_number( &self, ) -> Result<Option<BlockNumber>, StoreError>

Obtain pending block number

pub async fn get_receipts_for_block( &self, block_hash: &BlockHash, ) -> Result<Vec<Receipt>, StoreError>

pub async fn get_receipts_for_block_from_index( &self, block_hash: &BlockHash, start_index: u64, max_count: Option<usize>, ) -> Result<Vec<Receipt>, StoreError>

Retrieves receipts for a block starting from the given index, optionally limited to max_count receipts.

Uses cursor-based prefix iteration over the 32-byte block hash prefix for efficient batch retrieval. Used by:

• eth/70 partial receipt requests (EIP-7975) via p2p
• eth_getTransactionReceipt RPC with a count limit to avoid fetching the entire block’s receipts

pub async fn set_header_download_checkpoint( &self, block_hash: BlockHash, ) -> Result<(), StoreError>

Sets the hash of the last header downloaded during a snap sync

pub async fn get_header_download_checkpoint( &self, ) -> Result<Option<BlockHash>, StoreError>

Gets the hash of the last header downloaded during a snap sync

pub async fn set_latest_valid_ancestor( &self, bad_block: BlockHash, latest_valid: BlockHash, ) -> Result<(), StoreError>

The forkchoice_update and new_payload methods require the latest_valid_hash when processing an invalid payload. To provide this, we must track invalid chains.

We only store the last known valid head upon encountering a bad block, rather than tracking every subsequent invalid block.

pub async fn get_latest_valid_ancestor( &self, block: BlockHash, ) -> Result<Option<BlockHash>, StoreError>

Returns the latest valid ancestor hash for a given invalid block hash. Used to provide latest_valid_hash in the Engine API when processing invalid payloads.

pub fn get_block_number_sync( &self, block_hash: BlockHash, ) -> Result<Option<BlockNumber>, StoreError>

Obtain block number for a given hash

pub fn get_canonical_block_hash_sync( &self, block_number: BlockNumber, ) -> Result<Option<BlockHash>, StoreError>

Get the canonical block hash for a given block number.

pub async fn write_storage_trie_nodes_batch( &self, storage_trie_nodes: StorageUpdates, ) -> Result<(), StoreError>

CAUTION: This method writes directly to the underlying database, bypassing any caching layer. For updating the state after block execution, use Self::store_block_updates.

pub async fn write_account_code_batch( &self, account_codes: Vec<(H256, Code)>, ) -> Result<(), StoreError>

CAUTION: This method writes directly to the underlying database, bypassing any caching layer. For updating the state after block execution, use Self::store_block_updates.

pub fn write( &self, table: &'static str, key: Vec<u8>, value: Vec<u8>, ) -> Result<(), StoreError>

Helper method for async writes Spawns blocking task to avoid blocking tokio runtime

pub async fn read_async( &self, table: &'static str, key: Vec<u8>, ) -> Result<Option<Vec<u8>>, StoreError>

Helper method for async reads Spawns blocking task to avoid blocking tokio runtime

pub fn read( &self, table: &'static str, key: Vec<u8>, ) -> Result<Option<Vec<u8>>, StoreError>

Helper method for sync reads Spawns blocking task to avoid blocking tokio runtime

pub async fn write_batch_async( &self, table: &'static str, batch_ops: Vec<(Vec<u8>, Vec<u8>)>, ) -> Result<(), StoreError>

Helper method for batch writes Spawns blocking task to avoid blocking tokio runtime This is the most important optimization for healing performance

pub fn write_batch( &self, table: &'static str, batch_ops: Vec<(Vec<u8>, Vec<u8>)>, ) -> Result<(), StoreError>

Helper method for batch writes

pub async fn add_fullsync_batch( &self, headers: Vec<BlockHeader>, ) -> Result<(), StoreError>

pub async fn read_fullsync_batch( &self, start: BlockNumber, limit: u64, ) -> Result<Vec<Option<BlockHeader>>, StoreError>

pub async fn clear_fullsync_headers(&self) -> Result<(), StoreError>

pub fn delete( &self, table: &'static str, key: Vec<u8>, ) -> Result<(), StoreError>

Delete a key from a table

pub fn store_block_updates( &self, update_batch: UpdateBatch, ) -> Result<(), StoreError>

pub fn new( path: impl AsRef<Path>, engine_type: EngineType, ) -> Result<Self, StoreError>

Opens (or creates) a store at path with the default StoreConfig.

Production callers that need to override storage tunables (e.g. the RocksDB block cache size from a CLI option) should use Store::new_with_config.

pub fn new_with_config( path: impl AsRef<Path>, engine_type: EngineType, config: StoreConfig, ) -> Result<Self, StoreError>

Opens (or creates) a store at path, applying the supplied StoreConfig.

pub async fn new_from_genesis( store_path: &Path, engine_type: EngineType, genesis_path: &str, ) -> Result<Self, StoreError>

Opens (or creates) a store at store_path and seeds it from the given genesis file, using the default StoreConfig.

pub async fn new_from_genesis_with_config( store_path: &Path, engine_type: EngineType, genesis_path: &str, config: StoreConfig, ) -> Result<Self, StoreError>

Opens (or creates) a store at store_path from genesis, applying the supplied StoreConfig.

pub async fn get_account_info( &self, block_number: BlockNumber, address: Address, ) -> Result<Option<AccountInfo>, StoreError>

pub fn get_account_info_by_hash( &self, block_hash: BlockHash, address: Address, ) -> Result<Option<AccountInfo>, StoreError>

pub fn get_account_state_by_acc_hash( &self, block_hash: BlockHash, account_hash: H256, ) -> Result<Option<AccountState>, StoreError>

pub async fn get_fork_id(&self) -> Result<ForkId, StoreError>

pub async fn get_code_by_account_address( &self, block_number: BlockNumber, address: Address, ) -> Result<Option<Code>, StoreError>

pub async fn get_nonce_by_account_address( &self, block_number: BlockNumber, address: Address, ) -> Result<Option<u64>, StoreError>

pub fn apply_account_updates_batch( &self, block_hash: BlockHash, account_updates: &[AccountUpdate], ) -> Result<Option<AccountUpdatesList>, StoreError>

Applies account updates based on the block’s latest storage state and returns the new state root after the updates have been applied.

pub fn apply_account_updates_from_trie_batch<'a>( &self, state_trie: &mut Trie, account_updates: impl IntoIterator<Item = &'a AccountUpdate>, ) -> Result<AccountUpdatesList, StoreError>

pub fn apply_account_updates_from_trie_with_witness( &self, state_trie: Trie, account_updates: &[AccountUpdate], storage_tries: HashMap<Address, (TrieWitness, Trie)>, ) -> Result<(HashMap<Address, (TrieWitness, Trie)>, AccountUpdatesList), StoreError>

Performs the same actions as apply_account_updates_from_trie but also returns the used storage tries with witness recorded

pub async fn setup_genesis_state_trie( &self, genesis_accounts: BTreeMap<Address, GenesisAccount>, ) -> Result<H256, StoreError>

Adds all genesis accounts and returns the genesis block’s state_root

pub fn store_witness( &self, block_hash: BlockHash, block_number: u64, witness: ExecutionWitness, ) -> Result<(), StoreError>

Stores a pre-serialized execution witness for a block.

The witness is converted to RPC format (RpcExecutionWitness) before storage to avoid expensive encode_subtrie traversal on every read. This pre-computes the serialization at write time instead of read time.

pub fn get_witness_json_bytes( &self, block_number: u64, block_hash: BlockHash, ) -> Result<Option<Vec<u8>>, StoreError>

Returns the raw JSON bytes of a cached witness for a block.

This is the most efficient method for the RPC handler since it avoids deserialization and re-serialization. The bytes can be parsed directly as a JSON Value for the RPC response.

pub fn get_witness_by_number_and_hash( &self, block_number: u64, block_hash: BlockHash, ) -> Result<Option<RpcExecutionWitness>, StoreError>

Returns the deserialized RpcExecutionWitness for a block.

Prefer get_witness_json_bytes when you need to return the witness as JSON (e.g., for RPC responses) to avoid re-serialization.

pub fn store_block_access_list( &self, block_hash: BlockHash, bal: &BlockAccessList, ) -> Result<(), StoreError>

Stores a block access list for a given block hash.

pub fn get_block_access_list( &self, block_hash: BlockHash, ) -> Result<Option<BlockAccessList>, StoreError>

Returns the block access list for a given block hash, if stored.

pub async fn add_initial_state( &mut self, genesis: Genesis, ) -> Result<(), StoreError>

pub async fn add_initial_state_skip_validation( &mut self, genesis: Genesis, ) -> Result<(), StoreError>

Like Store::add_initial_state, but trusts a pre-existing datadir’s state instead of validating it against the provided genesis. If a genesis header is already stored, it is kept as-is rather than recomputing the genesis state root from genesis.alloc and rejecting on mismatch. The chain config from the genesis file is still applied either way.

Intended for booting a datadir produced out-of-band (e.g. by a state generator that writes the state trie directly and emits a genesis file with an empty alloc), where the operator vouches for the stored state root. Has no effect on a fresh datadir: the genesis is built normally.

pub async fn load_initial_state(&self) -> Result<(), StoreError>

pub fn get_storage_at( &self, block_number: BlockNumber, address: Address, storage_key: H256, ) -> Result<Option<U256>, StoreError>

pub fn get_storage_at_root( &self, state_root: H256, address: Address, storage_key: H256, ) -> Result<Option<U256>, StoreError>

pub fn get_storage_at_root_with_known_storage_root( &self, state_root: H256, account_hash: H256, storage_root: H256, storage_key: H256, ) -> Result<Option<U256>, StoreError>

Gets storage value when the account hash and storage root are already known.

This skips the state-trie account lookup and account RLP decode done by Self::get_storage_at_root, and directly opens the account storage trie.

pub fn get_chain_config(&self) -> ChainConfig

pub async fn get_latest_canonical_block_hash( &self, ) -> Result<Option<BlockHash>, StoreError>

pub async fn forkchoice_update( &self, new_canonical_blocks: Vec<(BlockNumber, BlockHash)>, head_number: BlockNumber, head_hash: BlockHash, safe: Option<BlockNumber>, finalized: Option<BlockNumber>, ) -> Result<(), StoreError>

Updates the canonical chain. Inserts new canonical blocks, removes blocks beyond the new head, and updates the head, safe, and finalized block pointers. All operations are performed in a single database transaction.

pub fn state_trie( &self, block_hash: BlockHash, ) -> Result<Option<Trie>, StoreError>

Obtain the storage trie for the given block

pub fn storage_trie( &self, block_hash: BlockHash, address: Address, ) -> Result<Option<Trie>, StoreError>

Obtain the storage trie for the given account on the given block

pub async fn get_account_state( &self, block_number: BlockNumber, address: Address, ) -> Result<Option<AccountState>, StoreError>

pub fn get_account_state_by_root( &self, state_root: H256, address: Address, ) -> Result<Option<AccountState>, StoreError>

pub fn get_account_state_from_trie( &self, state_trie: &Trie, address: Address, ) -> Result<Option<AccountState>, StoreError>

pub async fn get_account_proof( &self, state_root: H256, address: Address, storage_keys: &[H256], ) -> Result<Option<AccountProof>, StoreError>

Constructs a merkle proof for the given account address against a given state. If storage_keys are provided, also constructs the storage proofs for those keys.

Returns None if the state trie is missing, otherwise returns the proof.

pub fn iter_accounts_from( &self, state_root: H256, starting_address: H256, ) -> Result<impl Iterator<Item = (H256, AccountState)>, StoreError>

pub fn iter_accounts( &self, state_root: H256, ) -> Result<impl Iterator<Item = (H256, AccountState)>, StoreError>

pub fn iter_storage_from( &self, state_root: H256, hashed_address: H256, starting_slot: H256, ) -> Result<Option<impl Iterator<Item = (H256, U256)>>, StoreError>

pub fn iter_storage( &self, state_root: H256, hashed_address: H256, ) -> Result<Option<impl Iterator<Item = (H256, U256)>>, StoreError>

pub fn get_account_range_proof( &self, state_root: H256, starting_hash: H256, last_hash: Option<H256>, ) -> Result<Vec<Vec<u8>>, StoreError>

pub fn get_storage_range_proof( &self, state_root: H256, hashed_address: H256, starting_hash: H256, last_hash: Option<H256>, ) -> Result<Option<Vec<Vec<u8>>>, StoreError>

pub fn get_trie_nodes( &self, state_root: H256, paths: Vec<Vec<u8>>, byte_limit: u64, ) -> Result<Vec<Vec<u8>>, StoreError>

Receives the root of the state trie and a list of paths where the first path will correspond to a path in the state trie (aka a hashed account address) and the following paths will be paths in the account’s storage trie (aka hashed storage keys) If only one hash (account) is received, then the state trie node containing the account will be returned. If more than one hash is received, then the storage trie nodes where each storage key is stored will be returned For more information check out snap capability message GetTrieNodes The paths can be either full paths (hash) or partial paths (compact-encoded nibbles), if a partial path is given for the account this method will not return storage nodes for it

pub fn new_state_trie_for_test(&self) -> Result<Trie, StoreError>

Creates a new state trie with an empty state root, for testing purposes only

pub fn open_state_trie(&self, state_root: H256) -> Result<Trie, StoreError>

Obtain a state trie from the given state root Doesn’t check if the state root is valid Used for internal store operations

pub fn open_direct_state_trie( &self, state_root: H256, ) -> Result<Trie, StoreError>

Obtain a state trie from the given state root Doesn’t check if the state root is valid Used for internal store operations

pub fn open_locked_state_trie( &self, state_root: H256, ) -> Result<Trie, StoreError>

Obtain a state trie locked for reads from the given state root Doesn’t check if the state root is valid Used for internal store operations

pub fn open_storage_trie( &self, account_hash: H256, state_root: H256, storage_root: H256, ) -> Result<Trie, StoreError>

Obtain a storage trie from the given address and storage_root. Doesn’t check if the account is stored

pub fn open_direct_storage_trie( &self, account_hash: H256, storage_root: H256, ) -> Result<Trie, StoreError>

Obtain a storage trie from the given address and storage_root. Doesn’t check if the account is stored

pub fn open_locked_storage_trie( &self, account_hash: H256, state_root: H256, storage_root: H256, ) -> Result<Trie, StoreError>

Obtain a read-locked storage trie from the given address and storage_root. Doesn’t check if the account is stored

pub fn has_state_root(&self, state_root: H256) -> Result<bool, StoreError>

pub fn ancestors(&self, block_hash: BlockHash) -> AncestorIterator

Takes a block hash and returns an iterator to its ancestors. Block headers are returned in reverse order, starting from the given block and going up to the genesis block.

pub fn is_canonical_sync( &self, block_hash: BlockHash, ) -> Result<bool, StoreError>

Checks if a given block belongs to the current canonical chain. Returns false if the block is not known

pub fn generate_flatkeyvalue(&self) -> Result<(), StoreError>

pub fn create_checkpoint( &self, path: impl AsRef<Path>, ) -> Result<(), StoreError>

pub fn get_store_directory(&self) -> Result<PathBuf, StoreError>

pub fn last_written(&self) -> Result<Vec<u8>, StoreError>

Trait Implementations

impl Clone for Store

fn clone(&self) -> Store

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Store

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.