Struct StorageCache 

pub struct StorageCache { /* private fields */ }

SQLite-backed persistent cache for storage values.

Enables fast restarts without re-fetching all data from live chains and reduces load on public RPC endpoints.

Implementations

impl StorageCache

pub async fn open(maybe_path: Option<&Path>) -> Result<Self, CacheError>

Open or create a cache database at the specified path.

Creates the parent directory if it doesn’t exist.

pub async fn in_memory() -> Result<Self, CacheError>

Open an in-memory cache.

Creates a fresh in-memory SQLite database and runs all migrations to set up the storage and blocks tables.

pub async fn get_storage( &self, block_hash: H256, key: &[u8], ) -> Result<Option<Option<Vec<u8>>>, CacheError>

Get a cached storage value.

Returns

• Ok(Some(Some(value))) - Cached with a value.
• Ok(Some(None)) - Cached as empty (storage key exists but has no value).
• Ok(None) - Not in cache (unknown).

pub async fn set_storage( &self, block_hash: H256, key: &[u8], value: Option<&[u8]>, ) -> Result<(), CacheError>

Cache a storage value.

Arguments

• block_hash - The block hash this storage is from
• key - The storage key
• value - The storage value, or None if the key has no value (empty)

pub async fn get_storage_batch( &self, block_hash: H256, keys: &[&[u8]], ) -> Result<Vec<Option<Option<Vec<u8>>>>, CacheError>

Get multiple cached storage values in a batch.

Returns results in the same order as the input keys.

pub async fn set_storage_batch( &self, block_hash: H256, entries: &[(&[u8], Option<&[u8]>)], ) -> Result<(), CacheError>

Cache multiple storage values in a batch.

Uses a transaction for efficiency.

pub async fn get_local_key( &self, key: &[u8], ) -> Result<Option<LocalKeyRow>, CacheError>

Get a local key’s ID from the local_keys table.

Returns

• Ok(Some(key_row)) - Key exists with its ID
• Ok(None) - Key not in local_keys table

pub async fn insert_local_key(&self, key: &[u8]) -> Result<i32, CacheError>

Insert a new key into local_keys and return its ID.

If the key already exists, returns the existing ID.

pub async fn get_local_value_at_block( &self, key: &[u8], block_number: u32, ) -> Result<Option<Option<Vec<u8>>>, CacheError>

Get a local storage value valid at a specific block number.

Queries the local_values table for a value that is valid at the given block: valid_from <= block_number AND (valid_until IS NULL OR valid_until > block_number)

Returns

• Ok(Some(Some(value))) - Value found with data
• Ok(Some(None)) - Value found but explicitly deleted (NULL in DB)
• Ok(None) - No value valid at this block (no row found)

pub async fn get_local_values_at_block_batch( &self, keys: &[&[u8]], block_number: u32, ) -> Result<Vec<Option<Option<Vec<u8>>>>, CacheError>

Get multiple local storage values valid at a specific block number.

Returns results in the same order as the input keys.

• Some(Some(value)) - Value found with data
• Some(None) - Value found but explicitly deleted (NULL in DB)
• None - No value valid at this block (no row found)

pub async fn get_local_keys_at_block( &self, prefix: &[u8], block_number: u32, ) -> Result<Vec<Vec<u8>>, CacheError>

Get all locally-modified keys matching a prefix that existed at a specific block.

Joins local_keys with local_values to find keys where:

• The key starts with prefix
• A value entry is valid at block_number (valid_from <= block AND (valid_until IS NULL OR valid_until > block))
• The value is not NULL (i.e., the key was not deleted at that block)

Returns a sorted list of matching keys.

pub async fn get_local_deleted_keys_at_block( &self, prefix: &[u8], block_number: u32, ) -> Result<Vec<Vec<u8>>, CacheError>

Get all locally-deleted keys matching a prefix at a specific block.

Returns keys where the value entry valid at block_number has a NULL value (explicitly deleted). This is needed to exclude deleted keys from merged remote + local key enumeration.

pub async fn insert_local_value( &self, key_id: i32, value: Option<&[u8]>, valid_from: u32, ) -> Result<(), CacheError>

Insert a new local value entry.

Arguments

• key_id - The key ID from local_keys table
• value - The value bytes, or None to record a deletion
• valid_from - Block number when this value becomes valid

pub async fn close_local_value( &self, key_id: i32, valid_until: u32, ) -> Result<(), CacheError>

Close the currently open local value entry (set valid_until).

Finds the entry for this key_id where valid_until IS NULL and sets it.

pub async fn commit_local_changes( &self, entries: &[(&[u8], Option<&[u8]>)], block_number: u32, ) -> Result<(), CacheError>

Commit a batch of local storage changes in a single transaction.

For each entry: upserts the key into local_keys, closes the previous value (sets valid_until), and inserts the new value. Wrapping everything in one transaction avoids per-operation fsync overhead, reducing commit time from tens of seconds to sub-second.

pub async fn clear_local_storage(&self) -> Result<(), CacheError>

Clear all local storage data (both local_keys and local_values tables).

This removes all locally tracked key-value pairs and their validity history. Uses a transaction to ensure both tables are cleared atomically.

pub async fn cache_block( &self, hash: H256, number: u32, parent_hash: H256, header: &[u8], ) -> Result<(), CacheError>

Cache block metadata.

pub async fn get_block( &self, hash: H256, ) -> Result<Option<BlockRow>, CacheError>

Get cached block metadata.

pub async fn get_block_by_number( &self, block_number: u32, ) -> Result<Option<BlockRow>, CacheError>

Get cached block metadata by block number.

pub async fn clear_block(&self, hash: H256) -> Result<(), CacheError>

Clear all cached data for a specific block.

pub async fn get_prefix_scan_progress( &self, block_hash: H256, prefix: &[u8], ) -> Result<Option<PrefixScanProgress>, CacheError>

Get the progress of a prefix scan operation.

Returns

• Ok(Some(progress)) - Scan has been started, returns progress info
• Ok(None) - No scan has been started for this prefix

pub async fn update_prefix_scan( &self, block_hash: H256, prefix: &[u8], last_key: &[u8], is_complete: bool, ) -> Result<(), CacheError>

Update the progress of a prefix scan operation (upsert).

Creates a new progress record or updates an existing one. Uses SQLite’s ON CONFLICT DO UPDATE for atomic upsert semantics.

Arguments

• block_hash - The block hash being scanned
• prefix - The storage prefix being scanned
• last_key - The last key that was processed
• is_complete - Whether the scan has finished

pub async fn get_keys_by_prefix( &self, block_hash: H256, prefix: &[u8], ) -> Result<Vec<Vec<u8>>, CacheError>

Get all cached keys matching a prefix.

Uses a range query (key >= prefix AND key < prefix+1) for efficient prefix matching on SQLite’s B-tree index. This is more performant than LIKE or GLOB patterns for binary key prefixes.

pub async fn next_key_from_cache( &self, block_hash: H256, prefix: &[u8], key: &[u8], ) -> Result<Option<Vec<u8>>, CacheError>

Find the next cached key after key that matches prefix.

Uses a range query (key > current AND key >= prefix AND key < prefix+1) for efficient lookup on SQLite’s B-tree index.

Returns

• Ok(Some(next_key)) - The next key after key matching the prefix
• Ok(None) - No more keys with this prefix after key

pub async fn count_keys_by_prefix( &self, block_hash: H256, prefix: &[u8], ) -> Result<usize, CacheError>

Count cached keys matching a prefix.

Uses the same range query strategy as Self::get_keys_by_prefix for efficient counting without loading key data.

Trait Implementations

impl Clone for StorageCache

fn clone(&self) -> StorageCache

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for StorageCache

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

Formats the value using the given formatter.