Struct LocalStorageLayer 

pub struct LocalStorageLayer { /* private fields */ }

Local storage layer that tracks modifications on top of a remote layer.

Provides transactional semantics: modifications are tracked locally without affecting the underlying remote layer or cache. Changes can be inspected via diff.

Block-based Storage Strategy

• latest_block_number: Current working block number (modifications in HashMap)
• Keys queried at a block higher than the last modification of that key, queried at modifications HashMap
• Blocks between first_forked_block_number and latest_block_number are in local_storage table
• Blocks before first_forked_block_number come from remote provider

Cloning

LocalStorageLayer is cheap to clone. The underlying modifications and deleted prefixes use Arc<RwLock<_>>, so clones share the same state.

Thread Safety

The layer is Send + Sync and can be shared across async tasks. All operations use read/write locks which will block until the lock is acquired.

Implementations

impl LocalStorageLayer

pub fn new( parent: RemoteStorageLayer, first_forked_block_number: u32, first_forked_block_hash: H256, metadata: Metadata, ) -> Self

Create a new local storage layer.

Arguments

• parent - The remote storage layer to use as the base state
• first_forked_block_number - The initial block number where the fork started
• first_forked_block_hash - The hash of the first forked block
• metadata - The runtime metadata at the fork point

Returns

A new LocalStorageLayer with no modifications, with current_block_number set to first_forked_block_number + 1 (the block being built).

pub fn get_current_block_number(&self) -> u32

Get the current block number.

pub fn cache(&self) -> &StorageCache

Get a reference to the underlying storage cache.

This provides access to the cache for operations like clearing local storage.

pub fn remote(&self) -> &RemoteStorageLayer

Get the underlying remote storage layer.

This provides access to the remote layer for operations that need to fetch data directly from the remote chain (e.g., block headers, bodies). The remote layer maintains a persistent connection to the RPC endpoint.

pub fn fork_block_hash(&self) -> H256

Get the hash of the first forked block.

This is the block hash at which the fork was created, used for querying storage keys on the remote chain.

pub async fn metadata_at( &self, block_number: u32, ) -> Result<Arc<Metadata>, LocalStorageError>

Get the metadata valid at a specific block number.

For blocks at or after the fork point, returns metadata from the local version tree. For blocks before the fork point, fetches metadata from the remote node.

Arguments

• block_number - The block number to get metadata for

Returns

• Ok(Arc<Metadata>) - The metadata valid at the given block
• Err(_) - Lock error, RPC error, or metadata decode error

pub fn register_metadata_version( &self, block_number: u32, metadata: Metadata, ) -> Result<(), LocalStorageError>

Register a new metadata version starting at the given block number.

This should be called when a runtime upgrade occurs (:code storage key changes) to record that a new metadata version is now active.

Arguments

• block_number - The block number where this metadata becomes valid
• metadata - The new runtime metadata

Returns

• Ok(()) - Metadata version registered successfully
• Err(_) - Lock error

pub fn has_code_changed_at( &self, block_number: u32, ) -> Result<bool, LocalStorageError>

Check if the :code storage key was modified at the specified block.

This is used to detect runtime upgrades. When a runtime upgrade occurs in block X, the new runtime is used starting from block X+1. So when building X+1, we check if code changed in X (the parent) to determine if we’re now using a new runtime.

Arguments

• block_number - The block number to check for code modifications

Returns

• Ok(true) - The :code key was modified at the specified block
• Ok(false) - The :code key was not modified at the specified block
• Err(_) - Lock error

pub async fn get( &self, block_number: u32, key: &[u8], ) -> Result<Option<Arc<LocalSharedValue>>, LocalStorageError>

Get a storage value, checking local modifications first.

Arguments

• key - The storage key to fetch

Returns

• Ok(Some(value)) - Value exists (either modified locally, in local_storage, or in parent)
• Ok(None) - Key doesn’t exist or was deleted via prefix deletion
• Err(_) - Lock error or parent layer error

Behavior

Storage lookup strategy based on block_number:

1. If block_number == latest_block_number or the key in local modifications is valid for this block: Check modifications HashMap, then remote at first_forked_block
2. If first_forked_block_number < block_number < latest_block_number: Check local_storage table
3. Otherwise: Check remote provider directly (fetches block_hash from blocks table)

pub async fn next_key( &self, prefix: &[u8], key: &[u8], ) -> Result<Option<Vec<u8>>, LocalStorageError>

Get the next key after the given key that starts with the prefix.

Arguments

• prefix - Storage key prefix to match
• key - The current key; returns the next key after this one

Returns

• Ok(Some(key)) - The next key after key that starts with prefix
• Ok(None) - No more keys with this prefix
• Err(_) - Lock error or parent layer error

Behavior

1. Queries the parent layer for the next key
2. Skips keys that match deleted prefixes
3. Does not consider locally modified keys (they are transient)

Note

This method currently delegates directly to the parent layer. Locally modified keys are not included in key enumeration since they represent uncommitted changes.

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

Enumerate all keys matching a prefix, merging remote and local state.

This method combines keys from the remote layer (at the fork point) with locally modified keys, producing a sorted, deduplicated list of keys that exist at the specified fork-local block.

For the latest block, uses the in-memory modifications and deleted_prefixes snapshots. For historical fork-local blocks, queries the persisted local values in the cache to reconstruct the key set that existed at that block.

Keys that were deleted locally (either individually via set(key, None) or via delete_prefix) are excluded.

pub fn set( &self, key: &[u8], value: Option<&[u8]>, ) -> Result<(), LocalStorageError>

Set a storage value locally.

Arguments

• key - The storage key to set
• value - The value to set, or None to mark as deleted

Returns

• Ok(()) - Value was set successfully
• Err(_) - Lock error

Behavior

• Does not affect the parent layer or underlying cache
• Overwrites any previous local modification for this key
• Passing None marks the key as explicitly deleted (different from never set)

pub fn set_initial( &self, key: &[u8], value: Option<&[u8]>, ) -> Result<(), LocalStorageError>

Set a storage value visible from the fork point onwards.

Unlike Self::set, which records the modification at the current working block, this marks the entry with last_modification_block = first_forked_block_number - 1 (saturating at 0) so it is visible immediately at the fork head and for any later fork-local query, but not for historical pre-fork queries. This is used for injecting initial state (e.g., dev accounts, sudo key) that should be readable before any block is built.

These entries are never committed to the persistent cache by Self::commit (which only commits entries at current_block_number), but they remain in the in-memory modifications map for the lifetime of the fork.

pub async fn get_batch( &self, block_number: u32, keys: &[&[u8]], ) -> Result<Vec<Option<Arc<LocalSharedValue>>>, LocalStorageError>

Get multiple storage values in a batch.

Arguments

• block_number - The block number to query
• keys - Slice of storage keys to fetch (as byte slices)

Returns

• Ok(vec) - Vector of optional values, in the same order as input keys
• Err(_) - Lock error or parent layer error

Behavior

Storage lookup strategy based on block_number (same as get):

1. If block_number == latest_block_number: Check modifications HashMap, then remote at first_forked_block
2. If first_forked_block_number < block_number < latest_block_number and the key is valid for block_number: Check modifications HashMap table
3. If first_forked_block_number < block_number < latest_block_number: Check local_storage table
4. Otherwise: Check remote provider directly (fetches block_hash from blocks table)

pub fn set_batch( &self, entries: &[(&[u8], Option<&[u8]>)], ) -> Result<(), LocalStorageError>

Set multiple storage values locally in a batch.

Arguments

• entries - Slice of (key, value) pairs to set

Returns

• Ok(()) - All values were set successfully
• Err(_) - Lock error

Behavior

• Does not affect the parent layer or underlying cache
• Overwrites any previous local modifications for the given keys
• None values mark keys as explicitly deleted
• More efficient than calling set() multiple times due to single lock acquisition

pub fn set_batch_initial( &self, entries: &[(&[u8], Option<&[u8]>)], ) -> Result<(), LocalStorageError>

Batch version of Self::set_initial.

Sets multiple storage values visible from the fork point onwards, using last_modification_block = first_forked_block_number - 1 (saturating at 0). See Self::set_initial for details.

pub fn delete_prefix(&self, prefix: &[u8]) -> Result<(), LocalStorageError>

Delete all keys matching a prefix.

Arguments

• prefix - The prefix to match for deletion

Returns

• Ok(()) - Prefix was marked as deleted successfully
• Err(_) - Lock error

Behavior

• Removes all locally modified keys that start with the prefix
• Marks the prefix as deleted, affecting future get() calls
• Keys in the parent layer matching this prefix will return None after this call

pub fn is_deleted(&self, prefix: &[u8]) -> Result<bool, LocalStorageError>

Check if a prefix has been deleted.

Arguments

• prefix - The prefix to check

Returns

• Ok(true) - Prefix has been deleted via delete_prefix
• Ok(false) - Prefix has not been deleted
• Err(_) - Lock error

pub fn diff( &self, ) -> Result<Vec<(Vec<u8>, Option<Arc<LocalSharedValue>>)>, LocalStorageError>

Get all local modifications as a vector.

Returns

• Ok(vec) - Vector of (key, value) pairs representing all local changes
• Err(_) - Lock error

Behavior

• Returns only locally modified keys, not the full state
• None values indicate keys that were explicitly deleted
• Does not include keys deleted via prefix deletion

pub async fn commit(&mut self) -> Result<(), LocalStorageError>

Commit modifications to the local storage tables, creating new validity entries.

Returns

• Ok(()) - All modifications were successfully committed to the cache
• Err(_) - Lock error or cache error

Behavior

• Only commits modifications whose last_modification_block == latest_block_number
• For each key to commit:
  • If key not in local_keys: insert key, then insert value with valid_from = latest_block_number
  • If key exists: close current open value (set valid_until), insert new value
• The modifications HashMap remains intact and available after commit
• Increases the latest block number

pub fn child(&self) -> LocalStorageLayer

Create a child layer for nested modifications.

Returns

A cloned LocalStorageLayer that shares the same parent and state.

Behavior

• The child shares the same modifications and deleted_prefixes via Arc
• Changes in the child affect the parent and vice versa
• Useful for creating temporary scopes that can be discarded

Note

This is currently a simple clone. In the future, this may be updated to create true isolated child layers with proper parent-child relationships.

Trait Implementations

impl Clone for LocalStorageLayer

fn clone(&self) -> LocalStorageLayer

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LocalStorageLayer

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

Formats the value using the given formatter.