Struct CachingDatabase 

pub struct CachingDatabase { /* private fields */ }

A database wrapper that caches state lookups for parallel pre-warming.

This enables parallel warming workers to share cached data, and allows the sequential execution phase to reuse warmed state. Reduces redundant database/trie lookups when multiple transactions touch the same accounts.

Thread-safe via RwLock - optimized for read-heavy concurrent access.

This caching database is inspired by reth’s overlay/proof worker cache.

Besides the per-block warmer/executor sharing above, the mempool prewarmer builds one instance per slot and publishes it across the block boundary: execute_block_pipeline seeds the next block’s execution with it when the parent state and fork match (see ethrex-blockchain::prewarm).

Invariant

Because one instance is shared across the block boundary (and the prewarmer may still be filling it while the next block executes), every cached entry must be a pure function of the parent state root. A cache layer whose entries also depend on the executing block (fork, number, timestamp, …) needs a matching handoff guard in execute_block_pipeline — see precompile_cache, whose fork-dependent entries are covered by the fork-equality check there.

Implementations

impl CachingDatabase

pub fn new(inner: Arc<dyn Database>, precompile_cache_enabled: bool) -> Self

pub fn code_bytes(&self) -> u64

Total Code::size of the bytecode this cache holds.

pub fn touched_keys_where( &self, account_filter: &dyn Fn(&Address) -> bool, slot_filter: &dyn Fn(&(Address, H256)) -> bool, ) -> TouchedKeys

Snapshot of the touched key sets matching the given filters: cached accounts (with their storage roots) and cached storage slot keys. The filters let a caller that tracks already-processed keys collect only the delta, keeping the per-call allocation O(new) while the scan stays O(cache).

Trait Implementations

impl Database for CachingDatabase

fn get_account_states_batch( &self, addresses: &[Address], ) -> Result<Vec<AccountState>, DatabaseError>

Warms every address through Self::prefetch_accounts, then answers from the cache under one read lock. Repeated addresses cost a single database read, and a caller that wants the states pays one map lookup each rather than a full get_account_state round trip per address.

The read lock spans the whole assembly, so callers should keep addresses to a bounded slice: a writer (an executor filling the same cache) waits on it.

fn prefetch_codes(&self, code_hashes: &[H256]) -> Result<u64, DatabaseError>

Fetches the uncached bytecodes in one batch and inserts them, reading each distinct hash once however many entries share it.

Returns only the warmed byte count, not the bytecodes: the executor reads code through Self::get_account_code, which this turns into a cache hit. Assembling a result vector here would hold the write lock that guards every executor code read for the length of the batch, to build something a warming caller discards.

fn get_account_state( &self, address: Address, ) -> Result<AccountState, DatabaseError>

fn get_storage_value( &self, address: Address, key: H256, ) -> Result<U256, DatabaseError>

fn get_block_hash(&self, block_number: u64) -> Result<H256, DatabaseError>

fn get_chain_config(&self) -> Result<ChainConfig, DatabaseError>

fn get_account_code(&self, code_hash: H256) -> Result<Code, DatabaseError>

fn get_code_metadata( &self, code_hash: H256, ) -> Result<CodeMetadata, DatabaseError>

fn precompile_cache(&self) -> Option<&PrecompileCache>

Access the precompile cache, if available at this database layer.

fn code_cache_budget_bytes(&self) -> u64

Byte budget for warming bytecode ahead of execution, as measured by Code::size.

fn prefetch_accounts(&self, addresses: &[Address]) -> Result<(), DatabaseError>

Prefetch a batch of accounts into the cache. Default: sequential fallback.

fn prefetch_storage( &self, keys: &[(Address, H256)], ) -> Result<(), DatabaseError>

Prefetch a batch of storage slots into the cache. Default: sequential fallback.

fn get_account_codes_batch( &self, code_hashes: &[H256], ) -> Result<Vec<Option<Code>>, DatabaseError>

Batch bytecode lookup, aligned to code_hashes. None means the hash is absent from the database. Default: loop. Backends with a batched read path (e.g. rocksdb multi_get_cf on the account-codes table) should override this; the caching layer above dispatches to it from Self::prefetch_codes.

fn get_storage_values_batch( &self, keys: &[(Address, H256)], ) -> Result<Vec<U256>, DatabaseError>

Batch storage-slot lookup. Default: loop. Backends with a batched read path (e.g. rocksdb multi_get_cf on the storage flat key-value table) should override this and the caching layer above will dispatch to it.