What is Storage Layout?

Storage layout is how a smart contract's state variables are organized in the EVM's storage slots. The order and packing of variables determines gas costs and, critically, whether proxy upgrades are safe.

How does Storage Layout work?

Variables are assigned to storage slots sequentially in the order declared.
Smaller types (uint8, bool) pack into shared slots to save space.
Dynamic types (arrays, mappings) use hash-based addressing.
When upgrading via proxy, the new implementation must preserve the existing layout new variables must be appended, never inserted.

Why does Storage Layout matter?

Incorrect layout changes in a proxy upgrade silently corrupt state, potentially losing user funds or breaking protocol logic entirely. It is one of the most common sources of critical bugs in upgradeable contracts.

Key features of Storage Layout

Sequential slot assignment in declaration order
Smaller types pack into shared slots for gas efficiency
Dynamic types use deterministic hash-based locations
Must never be reordered in upgradeable contracts

Examples of Storage Layout

Packing four uint8 variables into one slot instead of four slots cuts storage costs by 75 percent. USDC's upgradeable design carefully appends new variables to the end across versions.

Inserting a new variable between existing ones in a proxy upgrade is a critical bug that corrupts all subsequent storage reads.