EIP-8317 Contract storage layout description format (Contract Storage Layout Descriptor Format)
No call decision · EVM & execution · EIP status Draft · created 2026-06-25
Defines a language-neutral JSON format describing which storage slot a contract's state variables are stored in and how. It lets wallets and block explorers translate raw slot changes into variable names and readable sentences.
Why it is needed
Tools such as block explorers, debuggers, and wallets that preview transaction effects before signing cannot tell which variable changed just from raw storage slot values. Right now there is no commonly trusted format, so each tool builds its own interpretation scheme. The Solidity compiler's storageLayout output is used as a de facto standard, but it has problems. Type names like t_uint256 are Solidity's internal naming, making them hard for other languages to use, and the official documentation itself states that it is experimental and subject to change. In addition, approaches that place structs in slots computed by keccak256 hashing, such as namespaced storage (ERC-7201) or diamond storage (ERC-8042), are unknown to the compiler and cannot be described. There are also many cases, such as upgradeable proxies or EIP-7702 delegation contracts, where there is no compiler output at all from which to extract a layout. This format aims to capture all of these cases in a single predictable schema.
What changes
Today
- Each tool builds its own scheme for interpreting storage
- The Solidity-only, subject-to-change storageLayout output is the de facto standard
- Alternative layouts such as ERC-7201 and ERC-8042, and hand-written assembly, have no way to be described
- Wallets show simulation results only as raw slot numbers and hexadecimal values
After EIP-8317
- A single JSON format, neutral to language and compiler, shared by all tools
- Namespaced, diamond, and manually written layouts are all captured in the same format
- Complex slot computations are declared in a verifiable way rather than as opaque constants
- Wallets can show in sentence form whose variable changed and from what value to what
Who is affected
- Users: Storage values that a transaction will change can be checked, before signing, as variable names and readable sentences.
- Wallet developers: A common schema can be used for clear-signing and simulation displays. In exchange, a slot-derivation formula must be implemented for each supported language.
- Block explorers, debuggers, security tools: Can consume the standard descriptor to interpret storage changes instead of a custom parser.
- Compilers and verification services: Languages other than Solidity can also emit layout descriptors in the same format, and source verification services can publish them alongside.
In depth
File structure: compiler, storage, types
A layout file is a single JSON object, and its required members are compiler, storage, and types. The language field of the compiler object supports "Solidity", "Vyper", and "manual"; "manual" MUST be used when the compiler generates none of the layout, as with Huff, pure Yul, or hand-written assembly. Compiler-assigned entries and manually defined entries MAY be mixed within a single file. storage is an ordered array of top-level storage entries, and types is an object mapping type identifiers to type definitions. $schema and $comment are optional fields. The source provides the full JSON schema along with three example asset files: a plain ERC-20, an EIP-7702 and ERC-7201 mix, and an ERC-8042 diamond.
Storage entries and type definitions
Each entry requires label (the source variable name), slot (a decimal string), offset (the byte offset within the slot, 0 if it occupies the whole slot), and type (an identifier referencing the types object). If path is absent, consumers MUST compute it by concatenating labels from the top-level entry down to the struct member. source is either "compiler" (the default) or "manual", distinguishing whether the slot and offset came from a verifiable, compiler-emitted source or were declared manually by the author. Type definitions have five possible encodings: inplace, inplace_struct, mapping, dynamic_array, and bytes. Every type has label and numberOfBytes; mapping additionally has key and value, dynamic_array has value and an alias base for literal compatibility with Solidity's output, and inplace_struct has a members array of member entries.
baseSlotDerivation: making the base slot verifiable
Entries whose base slot is computed by a method other than sequential allocation declare that method with a baseSlotDerivation object. There are currently three schemes: "erc7201", "erc8042", and "custom". For erc7201, consumers MAY independently recompute and verify slot == keccak256(keccak256(namespaceId) - 1) & ~0xff; for erc8042, slot == keccak256(namespaceId). custom is for methods not yet standardized as an ERC, where the formula field holds a free-text description that cannot be machine-verified and the slot is written manually. baseSlotDerivation MUST NOT be used for slots that the compiler assigned sequentially. The same applies to slots relocated via Solidity's layout at syntax, since in both cases the compiler emits the final absolute slot directly, making separate re-derivation meaningless.
Slot derivation formulas and packed variables
Child values of composite types are stored at positions computed from the entry's slot as the base slot, according to encoding and compiler.language. In Solidity, mapping is keccak256(abi.encode(key, baseSlot)), dynamic_array is keccak256(baseSlot) + index * elementSlots, and bytes is inlined in the base slot if 31 bytes or fewer, or stored sequentially starting at keccak256(baseSlot) if longer. In Vyper, mapping is keccak256(abi.encode(key, baseSlot)) from version 0.3.0 onward, and keccak256(abi.encode(baseSlot, key)) with key and slot order reversed before that; dynamic_array is baseSlot + 1 + index * elementSlots; and bytes is inlined starting at the base slot without hash indirection. elementSlots = ceil(elementSize / 32), and nested types apply this recursively at each level. This table is the normative source for this ERC, and support for new languages MUST be added only through a revision of this ERC. When a packed slot changes, consumers MUST inspect each entry whose slot matches by offset and numberOfBytes to identify which variable changed, and MAY omit variables whose value is unchanged from the display.
display annotations: making it human-readable using ERC-7730 vocabulary
Each entry and struct member may have an optional display object, whose vocabulary follows ERC-7730. label supports {key[N]} and {index[N]} placeholders, with the outermost being {key[0]}. The Nth formatter in the keyFormats array applies to the Nth key or index, and format and params apply to the stored value itself using the same structure as ERC-7730 field formatters (tokenAmount, addressName, raw, date, etc.). template is either a plain string or an array of conditional entries; if an array, entries are evaluated in order and the first whose condition matches is used, with an entry having no condition placed at the end as a fallback (SHOULD). Templates support the {label}, {oldValue}, and {newValue} placeholders. description is for informational purposes only and MUST NOT be relied upon for security decisions without additional authenticity guarantees. When a struct member changes, the resolved label of the parent variable is shown together with the member label.
JSON Logic subset
Template conditions are JSON Logic expressions, but this ERC does not depend on the external JSON Logic specification and instead normatively defines the usable subset directly. An expression is a JSON object with a single operator as its key, and the context variables are oldValue, newValue, key, and index. The var operator reads a context value via a dot-separated path, as in {"var": "key.0"}. The operators that MUST be supported are ==, !=, >, >=, <, <=, !, and, or, and var, and wallets MUST NOT assume the presence of any other JSON Logic operators or features. false, 0, the empty string, the empty array, and null evaluate to false, and everything else evaluates to true.
Trust model, exclusions from scope, and current status
The layout file itself can be an attack surface. A file that falsely describes a slot's type or path can cause misleading variable names or values to be shown for an actual storage change. This ERC does not define the trust or distribution mechanism for layout files; standards that reference this format, such as ERC-7730, bear the responsibility of deciding how to establish a file's authenticity before using it for security-relevant display. Transient storage, meanwhile, is out of scope because it is cleared at the end of a transaction and has no effect on outcomes. This document's status is Draft, so the field structure and detailed rules may still change, and there are currently no records such as core developer call inclusion decisions.