tempo_precompiles/storage/types/

mapping.rs

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

use alloy::primitives::{U256, keccak256};
use std::marker::PhantomData;

use crate::storage::{Layout, Slot, Storable, StorableType, StorageKey};

/// 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 `Storable<N>`)
///
/// # 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 `.at(key)` to compute and obtain a `Slot<V>` 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:
///
/// # Relationship with `Slot<V>`
///
/// `Mapping<K, V>` is essentially a slot computation helper. The `.at(key)` method
/// performs the keccak256 hash to compute the actual storage slot and returns a
/// `Slot<V>` that can be used for read/write operations.
#[derive(Debug, Clone, Copy)]
pub struct Mapping<K, V> {
    base_slot: U256,
    _phantom: PhantomData<(K, V)>,
}

impl<K, V> Mapping<K, V> {
    /// Creates a new `Mapping` with the given base slot number.
    ///
    /// This is typically called with slot constants generated by the `#[contract]` macro.
    #[inline]
    pub const fn new(base_slot: U256) -> Self {
        Self {
            base_slot,
            _phantom: PhantomData,
        }
    }

    /// Returns the U256 base storage slot number for this mapping.
    #[inline]
    pub const fn slot(&self) -> U256 {
        self.base_slot
    }

    /// Returns a `Slot<V>` for the given key.
    ///
    /// This enables the composable pattern: `mapping.at(key).read(storage)`
    /// where the mapping slot computation happens once, and the resulting slot
    /// can be used for multiple operations.
    pub fn at<const N: usize>(&self, key: K) -> Slot<V>
    where
        K: StorageKey,
        V: Storable<N>,
    {
        Slot::new(mapping_slot(key.as_storage_bytes(), self.base_slot))
    }

    /// Returns a `Slot<V>` for a mapping field within a struct at a given base slot.
    ///
    /// This method enables accessing mapping fields within structs when you have
    /// the struct's base slot at runtime and know the field's offset.
    #[inline]
    pub fn at_offset<const N: usize>(
        struct_base_slot: U256,
        field_offset_slots: usize,
        key: K,
    ) -> Slot<V>
    where
        K: StorageKey,
        V: Storable<N>,
    {
        let field_slot = struct_base_slot + U256::from(field_offset_slots);
        Slot::new(mapping_slot(key.as_storage_bytes(), field_slot))
    }
}

/// Type-safe access wrapper for nested EVM storage mappings (two-level hash-based storage).
///
/// Like `Mapping<K, V>`, this struct does not store data. It provides a zero-cost abstraction
/// for accessing nested mapping storage using Solidity's double-hash layout. It wraps a base
/// slot and provides methods to navigate through two levels of key lookups.
///
/// # Type Parameters
///
/// - `K1`: First-level key type (must implement `StorageKey`)
/// - `K2`: Second-level key type (must implement `StorageKey`)
/// - `V`: Value type (must implement `Storable<N>`)
///
/// # Storage Layout
///
/// Nested mappings use a two-step hashing process:
/// - Base slot: stored in the inner mapping's `base_slot`
/// - Intermediate slot for `k1`: `keccak256(k1 || base_slot)`
/// - Final slot for `k1, k2`: `keccak256(k2 || intermediate_slot)`
///
/// # Usage Pattern
///
/// The typical usage follows a two-step composable pattern:
/// 1. Create a `NestedMapping<K1, K2, V>` with a base slot
/// 2. Call `.at(key1)` to get an intermediate `Mapping<K2, V>`
/// 3. Call `.at(key2)` on the intermediate mapping to get a `Slot<V>`
/// 4. Use `.read()`, `.write()`, or `.delete()` on the resulting slot
///
/// # Accessing Nested Mapping Fields Within Structs
///
/// When a nested mapping is a field within a struct, you can manually compute the field's
/// slot by adding the offset to the struct's base slot, then create a new `NestedMapping`:
///
/// # Relationship with `Mapping<K, V>` and `Slot<V>`
///
/// `NestedMapping<K1, K2, V>` internally wraps `Mapping<K1, Mapping<K2, V>>`. The first
/// `.at(k1)` call performs the first hash to compute an intermediate slot and returns a
/// `Mapping<K2, V>`. The second `.at(k2)` call on that mapping performs the second hash
/// and returns a `Slot<V>` for read/write operations.
#[derive(Debug, Clone, Copy)]
pub struct NestedMapping<K1, K2, V> {
    _inner: Mapping<K1, Mapping<K2, V>>,
}

impl<K1, K2, V> NestedMapping<K1, K2, V> {
    /// Creates a new `NestedMapping` with the given base slot number.
    ///
    /// This is typically called with slot constants generated by the `#[contract]` macro.
    #[inline]
    pub const fn new(base_slot: U256) -> Self {
        Self {
            _inner: Mapping::new(base_slot),
        }
    }

    /// Returns the U256 base storage slot number for this nested mapping.
    #[inline]
    pub const fn slot(&self) -> U256 {
        self._inner.slot()
    }

    /// Returns a `Mapping<K2, V>` for the given first-level key.
    #[inline]
    pub fn at(&self, key1: K1) -> Mapping<K2, V>
    where
        K1: StorageKey,
    {
        let intermediate_slot = mapping_slot(key1.as_storage_bytes(), self._inner.base_slot);
        Mapping::new(intermediate_slot)
    }
}

impl<K, V> Default for Mapping<K, V> {
    fn default() -> Self {
        Self::new(U256::ZERO)
    }
}

impl<K1, K2, V> Default for NestedMapping<K1, K2, V> {
    fn default() -> Self {
        Self::new(U256::ZERO)
    }
}

// Mappings occupy a full 32-byte slot in the layout (used as a base for hashing),
// even though they don't store data in that slot directly.
//
// **NOTE:** Necessary to allow it to participate in struct layout calculations.
impl<K, V> StorableType for Mapping<K, V> {
    const LAYOUT: Layout = Layout::Slots(1);
}

// Nested mappings occupy a full 32-byte slot in the layout (used as a base for hashing),
// even though they don't store data in that slot directly.
//
// **NOTE:** Necessary to allow it to participate in struct layout calculations.
impl<K1, K2, V> StorableType for NestedMapping<K1, K2, V> {
    const LAYOUT: Layout = Layout::Slots(1);
}

// -- HELPER FUNCTIONS ---------------------------------------------------------

fn left_pad_to_32(data: &[u8]) -> [u8; 32] {
    let mut buf = [0u8; 32];
    buf[32 - data.len()..].copy_from_slice(data);
    buf
}

/// Compute storage slot for a mapping
#[inline]
pub fn mapping_slot<T: AsRef<[u8]>>(key: T, mapping_slot: U256) -> U256 {
    let mut buf = [0u8; 64];
    buf[..32].copy_from_slice(&left_pad_to_32(key.as_ref()));
    buf[32..].copy_from_slice(&mapping_slot.to_be_bytes::<32>());
    U256::from_be_bytes(keccak256(buf).0)
}

/// Compute storage slot for a double mapping (mapping\[key1\]\[key2\])
#[inline]
pub fn double_mapping_slot<T: AsRef<[u8]>, U: AsRef<[u8]>>(
    key1: T,
    key2: U,
    base_slot: U256,
) -> U256 {
    let intermediate_slot = mapping_slot(key1, base_slot);
    let mut buf = [0u8; 64];
    buf[..32].copy_from_slice(&left_pad_to_32(key2.as_ref()));
    buf[32..].copy_from_slice(&intermediate_slot.to_be_bytes::<32>());
    U256::from_be_bytes(keccak256(buf).0)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{
        error::Result,
        storage::{PrecompileStorageProvider, StorageOps, hashmap::HashMapStorageProvider},
    };
    use alloy::primitives::{Address, B256, address};
    use proptest::prelude::*;

    // Test helper that implements StorageOps
    struct TestContract<'a, S> {
        address: Address,
        storage: &'a mut S,
    }

    impl<'a, S: PrecompileStorageProvider> StorageOps for TestContract<'a, S> {
        fn sstore(&mut self, slot: U256, value: U256) -> Result<()> {
            self.storage.sstore(self.address, slot, value)
        }

        fn sload(&mut self, slot: U256) -> Result<U256> {
            self.storage.sload(self.address, slot)
        }
    }

    /// Helper to create a test contract with fresh storage.
    fn setup_test_contract<'a>(
        storage: &'a mut HashMapStorageProvider,
    ) -> TestContract<'a, HashMapStorageProvider> {
        TestContract {
            address: Address::random(),
            storage,
        }
    }

    // Test slot constants
    const TEST_SLOT_0: U256 = U256::ZERO;
    const TEST_SLOT_1: U256 = U256::from_limbs([1, 0, 0, 0]);
    const TEST_SLOT_2: U256 = U256::from_limbs([2, 0, 0, 0]);
    const TEST_SLOT_MAX: U256 = U256::MAX;

    // Property test strategies
    fn arb_address() -> impl Strategy<Value = Address> {
        any::<[u8; 20]>().prop_map(Address::from)
    }

    fn arb_u256() -> impl Strategy<Value = U256> {
        any::<[u64; 4]>().prop_map(U256::from_limbs)
    }

    #[test]
    fn test_mapping_slot_deterministic() {
        let key: B256 = U256::from(123).into();
        let slot1 = mapping_slot(key, U256::ZERO);
        let slot2 = mapping_slot(key, U256::ZERO);

        assert_eq!(slot1, slot2);
    }

    #[test]
    fn test_different_keys_different_slots() {
        let key1: B256 = U256::from(123).into();
        let key2: B256 = U256::from(456).into();

        let slot1 = mapping_slot(key1, U256::ZERO);
        let slot2 = mapping_slot(key2, U256::ZERO);

        assert_ne!(slot1, slot2);
    }

    #[test]
    fn test_tip20_balance_slots() {
        // Test balance slot calculation for TIP20 tokens (slot 10)
        let alice = address!("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266");
        let bob = address!("0x70997970C51812dc3A010C7d01b50e0d17dc79C8");

        let alice_balance_slot = mapping_slot(alice, U256::from(10));
        let bob_balance_slot = mapping_slot(bob, U256::from(10));

        println!("Alice balance slot: 0x{alice_balance_slot:064x}");
        println!("Bob balance slot: 0x{bob_balance_slot:064x}");

        // Verify they're different
        assert_ne!(alice_balance_slot, bob_balance_slot);
    }

    #[test]
    fn test_tip20_allowance_slots() {
        // Test allowance slot calculation for TIP20 tokens (slot 11)
        let alice = address!("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266");
        let tip_fee_mgr = address!("0xfeec000000000000000000000000000000000000");

        let allowances = NestedMapping::<Address, Address, U256>::new(U256::from(11));
        let allowance_slot = allowances.at(alice).at(tip_fee_mgr).slot();

        println!("Alice->TipFeeManager allowance slot: 0x{allowance_slot:064x}");

        // Just verify it's calculated consistently
        let allowance_slot2 = allowances.at(alice).at(tip_fee_mgr).slot();
        assert_eq!(allowance_slot, allowance_slot2);
    }

    #[test]
    fn test_double_mapping_different_keys() {
        let alice = address!("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266");
        let bob = address!("0x70997970C51812dc3A010C7d01b50e0d17dc79C8");
        let spender = address!("0xfeec000000000000000000000000000000000000");

        let allowances = NestedMapping::<Address, Address, U256>::new(U256::from(11));
        let alice_allowance = allowances.at(alice).at(spender).slot();
        let bob_allowance = allowances.at(bob).at(spender).slot();

        assert_ne!(alice_allowance, bob_allowance);
    }

    #[test]
    fn test_left_padding_correctness() {
        let addr = address!("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266");
        let bytes: &[u8] = addr.as_ref();
        let padded = left_pad_to_32(bytes);

        // First 12 bytes should be zeros (left padding)
        assert_eq!(&padded[..12], &[0u8; 12]);
        // Last 20 bytes should be the address
        assert_eq!(&padded[12..], bytes);
    }

    #[test]
    fn test_mapping_slot_encoding() {
        let key = address!("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266");
        let base_slot = U256::from(10);

        // Manual computation to validate
        let mut buf = [0u8; 64];
        // Left-pad the address to 32 bytes
        buf[12..32].copy_from_slice(key.as_ref());
        // Slot in big-endian
        buf[32..].copy_from_slice(&base_slot.to_be_bytes::<32>());

        let expected = U256::from_be_bytes(keccak256(buf).0);
        let computed = mapping_slot(key, base_slot);

        assert_eq!(computed, expected, "mapping_slot encoding mismatch");
    }

    #[test]
    fn test_double_mapping_account_role() {
        let account = address!("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266");
        let role: B256 = U256::ONE.into();
        let base_slot = U256::ONE;

        let roles = NestedMapping::<Address, B256, U256>::new(base_slot);
        let slot = roles.at(account).at(role).slot();

        // Verify deterministic
        let slot2 = roles.at(account).at(role).slot();
        assert_eq!(slot, slot2);

        // Verify different role yields different slot
        let different_role: B256 = U256::from(2).into();
        let different_slot = roles.at(account).at(different_role).slot();
        assert_ne!(slot, different_slot);
    }

    #[test]
    fn test_mapping_size() {
        // Mapping now contains a U256 base_slot field (32 bytes)
        assert_eq!(std::mem::size_of::<Mapping<Address, U256>>(), 32);
        assert_eq!(std::mem::size_of::<Mapping<U256, Address>>(), 32);
        // Nested mapping also contains a U256 (outer mapping's slot)
        assert_eq!(
            std::mem::size_of::<Mapping<Address, Mapping<Address, U256>>>(),
            32
        );
    }

    #[test]
    fn test_mapping_creation() {
        let _simple: Mapping<Address, U256> = Mapping::new(U256::ZERO);
        let _another: Mapping<U256, bool> = Mapping::new(U256::ONE);
    }

    #[test]
    fn test_mapping_slot_extraction() {
        assert_eq!(Mapping::<Address, U256>::new(U256::ONE).slot(), U256::ONE);
        assert_eq!(
            Mapping::<U256, Address>::new(U256::from(2)).slot(),
            U256::from(2)
        );

        // Test with larger slot number
        assert_eq!(Mapping::<Address, U256>::new(U256::MAX).slot(), U256::MAX);
    }

    #[test]
    fn test_mapping_edge_case_zero() {
        // Explicit test for U256::ZERO base slot
        assert_eq!(Mapping::<Address, U256>::new(U256::ZERO).slot(), U256::ZERO);

        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);
        let user = Address::random();

        let zero_mapping = Mapping::<Address, U256>::new(U256::ZERO);
        let value = U256::from(1000u64);

        _ = zero_mapping.at(user).write(&mut contract, value);
        let loaded = zero_mapping.at(user).read(&mut contract).unwrap();
        assert_eq!(loaded, value);
    }

    #[test]
    fn test_mapping_edge_case_max() {
        // Explicit test for U256::MAX base slot
        let max_mapping = Mapping::<Address, U256>::new(U256::MAX);
        assert_eq!(max_mapping.slot(), U256::MAX);

        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);
        let user = Address::random();

        let value = U256::from(999u64);
        _ = max_mapping.at(user).write(&mut contract, value);
        let loaded = max_mapping.at(user).read(&mut contract).unwrap();
        assert_eq!(loaded, value);
    }

    #[test]
    fn test_mapping_read_write_balances() {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);
        let user1 = Address::random();
        let user2 = Address::random();

        let named_mapping = Mapping::<Address, U256>::new(TEST_SLOT_1);

        let balance1 = U256::from(1000u64);
        let balance2 = U256::from(2000u64);

        // Write balances
        _ = named_mapping.at(user1).write(&mut contract, balance1);
        _ = named_mapping.at(user2).write(&mut contract, balance2);

        // Read balances
        let loaded1 = named_mapping.at(user1).read(&mut contract).unwrap();
        let loaded2 = named_mapping.at(user2).read(&mut contract).unwrap();

        assert_eq!(loaded1, balance1);
        assert_eq!(loaded2, balance2);
    }

    #[test]
    fn test_mapping_read_default_is_zero() {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);
        let user = Address::random();

        let named_mapping = Mapping::<Address, U256>::new(TEST_SLOT_1);

        // Reading uninitialized mapping slot should return zero
        let balance = named_mapping.at(user).read(&mut contract).unwrap();
        assert_eq!(balance, U256::ZERO);
    }

    #[test]
    fn test_mapping_overwrite() {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);
        let user = Address::random();

        let named_mapping = Mapping::<Address, U256>::new(TEST_SLOT_1);

        // Write initial balance
        _ = named_mapping.at(user).write(&mut contract, U256::from(100));
        assert_eq!(
            named_mapping.at(user).read(&mut contract),
            Ok(U256::from(100))
        );

        // Overwrite with new balance
        _ = named_mapping.at(user).write(&mut contract, U256::from(200));
        assert_eq!(
            named_mapping.at(user).read(&mut contract),
            Ok(U256::from(200))
        );
    }

    #[test]
    fn test_nested_mapping_read_write_allowances() {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);
        let owner = Address::random();
        let spender1 = Address::random();
        let spender2 = Address::random();

        // Nested mapping: outer slot is 11, inner slot is dummy (unused)
        let nested_mapping = NestedMapping::<Address, Address, U256>::new(TEST_SLOT_1);

        let allowance1 = U256::from(500u64);
        let allowance2 = U256::from(1500u64);

        // Write allowances using nested API
        _ = nested_mapping
            .at(owner)
            .at(spender1)
            .write(&mut contract, allowance1);
        _ = nested_mapping
            .at(owner)
            .at(spender2)
            .write(&mut contract, allowance2);

        // Read allowances using nested API
        let loaded1 = nested_mapping
            .at(owner)
            .at(spender1)
            .read(&mut contract)
            .unwrap();
        let loaded2 = nested_mapping
            .at(owner)
            .at(spender2)
            .read(&mut contract)
            .unwrap();

        assert_eq!(loaded1, allowance1);
        assert_eq!(loaded2, allowance2);
    }

    #[test]
    fn test_nested_mapping_default_is_zero() {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);
        let owner = Address::random();
        let spender = Address::random();

        let nested_mapping = NestedMapping::<Address, Address, U256>::new(TEST_SLOT_1);

        // Reading uninitialized nested mapping should return zero
        let allowance = nested_mapping
            .at(owner)
            .at(spender)
            .read(&mut contract)
            .unwrap();
        assert_eq!(allowance, U256::ZERO);
    }

    #[test]
    fn test_nested_mapping_independence() {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);
        let owner1 = Address::random();
        let owner2 = Address::random();
        let spender = Address::random();

        let nested_mapping = NestedMapping::<Address, Address, U256>::new(TEST_SLOT_1);

        // Set allowance for owner1 -> spender
        _ = nested_mapping
            .at(owner1)
            .at(spender)
            .write(&mut contract, U256::from(100));

        // Verify owner2 -> spender is still zero (independent slot)
        let allowance2 = nested_mapping
            .at(owner2)
            .at(spender)
            .read(&mut contract)
            .unwrap();
        assert_eq!(allowance2, U256::ZERO);

        // Verify owner1 -> spender is unchanged
        let allowance1 = nested_mapping
            .at(owner1)
            .at(spender)
            .read(&mut contract)
            .unwrap();
        assert_eq!(allowance1, U256::from(100));
    }

    #[test]
    fn test_mapping_with_different_key_types() {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);

        // Mapping with U256 key
        let nonces_mapping = Mapping::<Address, U256>::new(TEST_SLOT_2);
        let user = Address::random();
        let nonce = U256::from(42);

        _ = nonces_mapping.at(user).write(&mut contract, nonce);
        let loaded_nonce = nonces_mapping.at(user).read(&mut contract).unwrap();
        assert_eq!(loaded_nonce, nonce);

        // Mapping with bool value
        let flags_mapping = Mapping::<Address, bool>::new(TEST_SLOT_MAX);
        _ = flags_mapping.at(user).write(&mut contract, true);
        let loaded_flag = flags_mapping.at(user).read(&mut contract).unwrap();
        assert!(loaded_flag);
    }

    proptest! {
        #![proptest_config(ProptestConfig::with_cases(500))]

        #[test]
        fn proptest_mapping_read_write(
            key in arb_address(),
            value in arb_u256()
        ) {
            let mut storage = HashMapStorageProvider::new(1);
            let mut contract = setup_test_contract(&mut storage);

            // Test with TestSlot10
        let test_mapping = Mapping::<Address, U256>::new(TEST_SLOT_0);

            // Write and read back
            test_mapping.at(key).write(&mut contract, value)?;
            let loaded = test_mapping.at(key).read(&mut contract)?;
            prop_assert_eq!(loaded, value, "roundtrip failed");

            // Delete and verify
            test_mapping.at(key).delete(&mut contract)?;
            let after_delete = test_mapping.at(key).read(&mut contract)?;
            prop_assert_eq!(after_delete, U256::ZERO, "not zero after delete");
        }

        #[test]
        fn proptest_mapping_key_isolation(
            key1 in arb_address(),
            key2 in arb_address(),
            value1 in arb_u256(),
            value2 in arb_u256()
        ) {
            // Skip if keys are the same
            prop_assume!(key1 != key2);

            let mut storage = HashMapStorageProvider::new(1);
            let mut contract = setup_test_contract(&mut storage);

        let test_mapping = Mapping::<Address, U256>::new(TEST_SLOT_0);

            // Write different values to different keys
            test_mapping.at(key1).write(&mut contract, value1)?;
            test_mapping.at(key2).write(&mut contract, value2)?;

            // Verify both keys retain their independent values
            let loaded1 = test_mapping.at(key1).read(&mut contract)?;
            let loaded2 = test_mapping.at(key2).read(&mut contract)?;

            prop_assert_eq!(loaded1, value1, "key1 value changed");
            prop_assert_eq!(loaded2, value2, "key2 value changed");

            // Delete key1, verify key2 unaffected
            test_mapping.at(key1).delete(&mut contract)?;
            let after_delete1 = test_mapping.at(key1).read(&mut contract)?;
            let after_delete2 = test_mapping.at(key2).read(&mut contract)?;

            prop_assert_eq!(after_delete1, U256::ZERO, "key1 not deleted");
            prop_assert_eq!(after_delete2, value2, "key2 affected by key1 delete");
        }

        #[test]
        fn proptest_nested_mapping_isolation(
            owner1 in arb_address(),
            owner2 in arb_address(),
            spender in arb_address(),
            allowance1 in arb_u256(),
            allowance2 in arb_u256()
        ) {
            // Skip if owners are the same
            prop_assume!(owner1 != owner2);

            let mut storage = HashMapStorageProvider::new(1);
            let mut contract = setup_test_contract(&mut storage);

        let nested_mapping = NestedMapping::<Address, Address, U256>::new(TEST_SLOT_1);

            // Write different allowances for different owners
            nested_mapping.at(owner1).at(spender).write(&mut contract, allowance1)?;
            nested_mapping.at(owner2).at(spender).write(&mut contract, allowance2)?;

            // Verify both owners' allowances are independent
            let loaded1 = nested_mapping.at(owner1).at(spender).read(&mut contract)?;
            let loaded2 = nested_mapping.at(owner2).at(spender).read(&mut contract)?;

            prop_assert_eq!(loaded1, allowance1, "owner1 allowance changed");
            prop_assert_eq!(loaded2, allowance2, "owner2 allowance changed");

            // Delete owner1's allowance, verify owner2 unaffected
            nested_mapping.at(owner1).at(spender).delete(&mut contract)?;
            let after_delete1 = nested_mapping.at(owner1).at(spender).read(&mut contract)?;
            let after_delete2 = nested_mapping.at(owner2).at(spender).read(&mut contract)?;

            prop_assert_eq!(after_delete1, U256::ZERO, "owner1 allowance not deleted");
            prop_assert_eq!(after_delete2, allowance2, "owner2 allowance affected");
        }
    }

    // -- RUNTIME SLOT OFFSET TESTS --------------------------------------------

    #[test]
    fn test_mapping_at_offset() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);

        // Simulate: mapping(bytes32 => Orderbook) books
        // where Orderbook has a mapping field `bids` at field offset 1
        let pair_key: B256 = U256::from(0x1234).into();
        let orderbook_base_slot = mapping_slot(pair_key, TEST_SLOT_1);

        // Use Mapping::*_at_offset() to access the bids mapping within the Orderbook struct
        let tick: i16 = 100;
        let bid_value = U256::from(500);

        // Write to orderbook.bids[tick]
        Mapping::<i16, U256>::at_offset(
            orderbook_base_slot,
            1, // bids field is at offset 1 in Orderbook
            tick,
        )
        .write(&mut contract, bid_value)?;

        // Read from orderbook.bids[tick]
        let read_value =
            Mapping::<i16, U256>::at_offset(orderbook_base_slot, 1, tick).read(&mut contract)?;

        assert_eq!(read_value, bid_value);

        // Delete orderbook.bids[tick]
        Mapping::<i16, U256>::at_offset(orderbook_base_slot, 1, tick).delete(&mut contract)?;

        let deleted_value =
            Mapping::<i16, U256>::at_offset(orderbook_base_slot, 1, tick).read(&mut contract)?;

        assert_eq!(deleted_value, U256::ZERO);

        Ok(())
    }

    #[test]
    fn test_nested_mapping_at_offset() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);

        // Simulate a struct with nested mapping at field offset 3
        let struct_key: B256 = U256::from(0xabcd).into();
        let struct_base_slot = mapping_slot(struct_key, TEST_SLOT_2);

        let owner = Address::random();
        let spender = Address::random();
        let allowance = U256::from(1000);

        // Write to nested_mapping[owner][spender]
        let field_slot = struct_base_slot + U256::from(3); // nested mapping at field offset 3
        let nested_mapping = NestedMapping::<Address, Address, U256>::new(field_slot);
        nested_mapping
            .at(owner)
            .at(spender)
            .write(&mut contract, allowance)?;

        // Read back
        let read_allowance = nested_mapping.at(owner).at(spender).read(&mut contract)?;

        assert_eq!(read_allowance, allowance);

        // Delete
        nested_mapping.at(owner).at(spender).delete(&mut contract)?;

        let deleted = nested_mapping.at(owner).at(spender).read(&mut contract)?;

        assert_eq!(deleted, U256::ZERO);

        Ok(())
    }

    #[test]
    fn test_multiple_fields_at_different_offsets() -> eyre::Result<()> {
        let mut storage = HashMapStorageProvider::new(1);
        let mut contract = setup_test_contract(&mut storage);

        // Simulate Orderbook with multiple mapping fields
        let pair_key: B256 = U256::from(0x5678).into();
        let orderbook_base = mapping_slot(pair_key, TEST_SLOT_0);

        // bids at offset 1
        let tick1: i16 = 50;
        let bid1 = U256::from(100);
        Mapping::<i16, U256>::at_offset(orderbook_base, 1, tick1).write(&mut contract, bid1)?;

        // asks at offset 2
        let tick2: i16 = -25;
        let ask1 = U256::from(200);
        Mapping::<i16, U256>::at_offset(orderbook_base, 2, tick2).write(&mut contract, ask1)?;

        // bidBitmap at offset 3
        let bitmap_key: i16 = 10;
        let bitmap_value = U256::from(0xff);
        Mapping::<i16, U256>::at_offset(orderbook_base, 3, bitmap_key)
            .write(&mut contract, bitmap_value)?;

        // Verify all fields are independent
        let read_bid =
            Mapping::<i16, U256>::at_offset(orderbook_base, 1, tick1).read(&mut contract)?;
        let read_ask =
            Mapping::<i16, U256>::at_offset(orderbook_base, 2, tick2).read(&mut contract)?;
        let read_bitmap =
            Mapping::<i16, U256>::at_offset(orderbook_base, 3, bitmap_key).read(&mut contract)?;

        assert_eq!(read_bid, bid1);
        assert_eq!(read_ask, ask1);
        assert_eq!(read_bitmap, bitmap_value);

        Ok(())
    }
}