Struct Storage 

pub struct Storage<'a, D> { /* private fields */ }

Hierarchical storage abstraction over EVM account state.

Subspaces are derived from base_key using keccak-based mixing; direct state I/O (when available) targets account. The struct is parameterised over the executor’s Database so the same shape can be inhabited by an executor &'a mut State<D> or by Detached for read paths that operate purely through a [StorageBackend].

The lifetime 'a ties the handle to the originating &mut State<D> borrow so a Storage value cannot outlive the state it references. The state is held as a NonNull internally (with a PhantomData for the lifetime) so multiple disjoint subspaces over the same state can coexist; direct I/O goes through one unsafe deref controlled by the same SAFETY invariant described below.

Safety

All direct I/O methods on Storage<'a, D> materialise &mut *state for the duration of a single SLOAD/SSTORE. The executor runs each block on a single thread and the EVM call graph is sequential, so no two such borrows overlap at runtime. The lifetime 'a ensures the underlying State<D> cannot be dropped while Storage handles into it are alive.

Implementations

impl<'a, D> Storage<'a, D>

pub fn new(state: &'a mut State<D>, base_key: B256) -> Self

Creates a new Storage backed by the ArbOS state account.

pub fn new_with_account( state: &'a mut State<D>, base_key: B256, account: Address, ) -> Self

Creates a new Storage backed by a specific account.

pub fn open_sub_storage(&self, sub_key: &[u8]) -> Storage<'a, D>

Opens a child subspace by hashing the parent key with the child ID.

pub fn open_sub_storage_with_key(&self, key: B256) -> Storage<'a, D>

Opens a child subspace using a pre-derived key, avoiding a keccak hash.

pub fn open_account(&self, account: Address, base_key: B256) -> Storage<'a, D>

Opens a sibling handle bound to the same backing state but targeting a different account and base_key. Used when constructing accessors for well-known non-ArbOS addresses (e.g. the filtered-transactions store).

pub fn new_slot(&self, offset: u64) -> U256

Creates a StorageSlot handle for a specific offset.

pub fn slot_for_key(&self, key: B256) -> U256

Computes the EVM slot for a B256-keyed entry under this subspace.

pub fn base_key(&self) -> B256

Returns the base key for this storage subspace.

pub fn account(&self) -> Address

Returns the account address this storage subspace is bound to.

impl Storage<'static, Detached>

pub fn detached(account: Address, base_key: B256) -> Self

Builds a Storage handle that has no executor state pointer.

All reads and writes must be routed through a [StorageBackend]; direct I/O methods on Storage are gated on D: Database and are therefore inaccessible here.

impl<'a, D: Database> Storage<'a, D>

pub fn get_by_uint64(&self, offset: u64) -> Result<B256, StorageError>

Reads a 32-byte value by uint64 offset.

pub fn set_by_uint64( &self, offset: u64, value: B256, ) -> Result<(), StorageError>

Writes a 32-byte value by uint64 offset.

pub fn get_uint64_by_uint64(&self, offset: u64) -> Result<u64, StorageError>

Reads a u64 by uint64 offset, truncating values that exceed u64::MAX.

pub fn set_uint64_by_uint64( &self, offset: u64, value: u64, ) -> Result<(), StorageError>

Writes a u64 by uint64 offset.

pub fn get(&self, key: B256) -> Result<B256, StorageError>

Reads a 32-byte value by B256 key using mapAddress algorithm.

pub fn set(&self, key: B256, value: B256) -> Result<(), StorageError>

Writes a 32-byte value by B256 key using mapAddress algorithm.

impl<'a, D> Storage<'a, D>

pub unsafe fn state_mut(&self) -> &'a mut State<D>

Re-borrows the underlying state for direct State<D>-level operations (e.g. account-level reads such as get_account_balance and writes such as set_account_nonce/set_account_code).

The returned reference inherits the lifetime parameter 'a of the Storage, so it is decoupled from any temporary borrow on &self. This shape lets callers thread the same backing state through methods that take &mut self without artificial borrow conflicts.

Safety

arbreth’s executor runs each block on a single thread and the EVM call graph is sequential, so no two such borrows are live at the same time at runtime. Callers must not nest two state_mut() returns from overlapping Storage handles.

Trait Implementations

impl<D> Clone for Storage<'_, D>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<D: Database> StorageBackend for Storage<'_, D>

fn sload(&mut self, account: Address, slot: U256) -> Result<U256, StorageError>

Reads the value at (account, slot). Reads through StorageBackend follow the host’s normal storage path (journaled when invoked on EvmInternals); for non-journaled reads see SystemStateBackend.

fn sstore( &mut self, account: Address, slot: U256, value: U256, ) -> Result<(), StorageError>

Writes value to (account, slot).

impl<D: Database> SystemStateBackend for Storage<'_, D>

type Error = StorageError

Concrete failure type produced by the backend. Convertible into StorageError so callers can stay uniform.

fn sload_system( &mut self, account: Address, slot: U256, ) -> Result<U256, Self::Error>

Reads the value at (account, slot) without journaling.

impl<D: Send> Send for Storage<'_, D>

impl<D: Sync> Sync for Storage<'_, D>