Module mapping_probe 

Trace-based discovery of hash-derived storage slots.

Solidity, Vyper, and hand-written assembly contracts all place mapping entries (and dynamic arrays) at storage slots derived with keccak256. The canonical Solidity layout for mapping(K => V) entry m[k] is keccak256(k ‖ slot); Vyper hashes the same two words in the opposite order (keccak256(slot ‖ k)); Solady-style assembly packs a key and a seed into a single 32-byte word. That diversity makes a static base-slot guess unreliable across tokens.

This module derives the layout dynamically from a single simulated call. HashStorageProbe is a revm::Inspector that records, over one execution:

• every KECCAK256 preimage, keyed by its hash output, and
• every SLOAD — its slot and the value it loaded.

HashStorageProbe::accesses then factors each hashed SLOAD back into a HashSlotAccess — the mapping key chain, the declared base slot, the detected SlotLayout, and the exact storage slot that was read — without assuming a preimage byte order. See resolve for the disambiguation rules.

A discovered single-level mapping can be captured as a TrackedMapping, a small reusable descriptor whose TrackedMapping::slot_for recomputes the exact storage slot for any key using the discovered layout. That is the building block for “derive a token’s balance slot once, then track these addresses” workflows: discover with the probe, then fan out cheaply.

Coupling

This module depends only on revm and alloy primitives — it is decoupled from balances, allowances, or any ERC-20 semantics. EvmCache builds ergonomic wrappers on top (balance-slot discovery, layout-aware writes); the reactive freshness/prefetch layers consume TrackedMapping::slot_for to register derived slots.

Structs

HashSlotAccess

One hash-derived SLOAD observed during a simulation, factored into its mapping structure.

HashStorageProbe

A revm::Inspector that records KECCAK256 preimages and every SLOAD (slot + loaded value), so accesses can reconstruct the mapping layout of hashed reads and slots_returning can find the slot that drove a getter’s return value (hashed or plain).

TrackedMapping

A reusable descriptor for a single-level hash-derived mapping on one contract, from which the storage slot of any key can be recomputed.

Enums

Confidence

Confidence in a HashSlotAccess factoring, ordered weakest → strongest so min degrades correctly as evidence weakens.

SlotLayout

The storage layout a HashSlotAccess was factored into.

Type Aliases

TrackedBalances

A discovered balance mapping paired with each tracked holder’s (address, storage slot) — the return of EvmCache::track_erc20_balances.