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

After EIP-8317

Who is affected

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.

Original EIP · ← EIPs