Struct Mapping 

pub struct Mapping<K, V: StorableType> {
    base_slot: U256,
    address: Address,
    cache: HandlerCache<K, V::Handler>,
}

Type-safe access wrapper for EVM storage mappings (hash-based key-value storage).

This struct does not store data itself. Instead, it provides a zero-cost abstraction for accessing mapping storage slots using Solidity’s hash-based layout. It wraps a base slot number and provides methods to compute the actual storage slots for keys.

Type Parameters

• K: Key type (must implement StorageKey)
• V: Value type (must implement StorableType)

Mapping<K, V> is essentially a slot computation helper. The [key] method performs the keccak256 hash to compute the actual storage slot and returns a Handler that can be used for read/write operations.

Storage Layout

Mappings use Solidity’s storage layout:

• Base slot: stored in base_slot field (never accessed directly)
• Actual slot for key k: keccak256(k || base_slot)

Usage Pattern

The typical usage follows a composable pattern:

1. Create a Mapping<K, V> with a base slot (usually from generated constants)
2. Call [key] to compute and obtain a Handler for that key
3. Use .read(), .write(), or .delete() on the resulting slot

Accessing Mapping Fields Within Structs

When a mapping is a field within a struct stored in another mapping, use the static at_offset method to compute the slot without creating a Mapping instance:

Fields

base_slot: U256

address: Address

cache: HandlerCache<K, V::Handler>

Implementations

impl<K, V: StorableType> Mapping<K, V>

pub fn new(base_slot: U256, address: Address) -> Self

Creates a new Mapping with the given base slot number and address.

This is typically called with slot constants generated by the #[contract] macro.

pub const fn slot(&self) -> U256

Returns the U256 base storage slot number for this mapping.

pub fn at(&self, key: &K) -> &V::Handler

where K: StorageKey + Hash + Eq + Clone,

Returns a Handler for the given key.

This enables the composable pattern: mapping.at(&key).read() where the mapping slot computation happens once, and the resulting slot can be used for multiple operations.

The handler is computed on first access and cached for subsequent accesses. Takes a reference to avoid cloning on cache hits.

pub fn at_mut(&mut self, key: &K) -> &mut V::Handler

where K: StorageKey + Hash + Eq + Clone,

Returns a mutable Handler for the given key.

Use this when you need to call mutable methods like write() or delete().

The handler is computed on first access and cached for subsequent accesses. Takes a reference to avoid cloning on cache hits.

Trait Implementations

impl<K: Clone, V: Clone + StorableType> Clone for Mapping<K, V>

where V::Handler: Clone,

fn clone(&self) -> Mapping<K, V>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K: Debug, V: Debug + StorableType> Debug for Mapping<K, V>

where V::Handler: Debug,

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

Formats the value using the given formatter.

impl<K, V: StorableType> Default for Mapping<K, V>

fn default() -> Self

Returns the “default value” for a type.

impl<K, V: StorableType> Index<K> for Mapping<K, V>

where K: StorageKey + Hash + Eq + Clone,

fn index(&self, key: K) -> &Self::Output

Returns a reference to the cached handler for the given key.

The handler is computed on first access and cached for subsequent accesses.

type Output = <V as StorableType>::Handler

The returned type after indexing.

impl<K, V: StorableType> IndexMut<K> for Mapping<K, V>

where K: StorageKey + Hash + Eq + Clone,

fn index_mut(&mut self, key: K) -> &mut Self::Output

Returns a mutable reference to the cached handler for the given key.

impl<K, V> StorableType for Mapping<K, V>

where V: StorableType,

const LAYOUT: Layout

Describes how this type is laid out in storage.

type Handler = Mapping<K, V>

The handler type that provides storage access for this type.

fn handle(slot: U256, _ctx: LayoutCtx, address: Address) -> Self::Handler

Creates a handler for this type at the given storage location.

const SLOTS: usize = _

Number of storage slots this type takes.

const BYTES: usize = _

Number of bytes this type takes.

const IS_PACKABLE: bool = _

Whether this type can be packed with adjacent fields.

const IS_DYNAMIC: bool = false

Whether this type stores it’s data in its base slot or not.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 112 bytes