Storage layout detection

When this applies

• UUPS / Transparent proxy upgrades
• OpenZeppelin *Upgradeable contracts
• EIP-2535 Diamonds with shared storage
• Libraries that read storage via assembly
• Any change that modifies inheritance order or struct layout in an upgradeable contract
• Initializers that depend on storage being zero

Detection patterns

Missing __gap (HIGH)

contract BaseUpgradeable {
    uint256 public foo;
    // no uint256[50] __gap;   ← can't append fields to derived contracts safely
}

OZ convention: each base contract reserves __gap for future fields.

Slot collision between proxy and implementation (CRITICAL)

Implementation defines address public owner in slot 0; proxy uses slot 0 for its admin. Hello, hijacked proxy. Use EIP-1967 slots (bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1)).

Inheritance reorder breaks layout (HIGH)

// V1: contract X is A, B, C
// V2: contract X is A, C, B   ← B's vars now at C's old slots

Even one append to a parent breaks all descendants.

Struct field reorder/insert (HIGH)

Solidity packs adjacent same-bit-width fields. Inserting a bool between two uint256 adds a slot. Verify with forge inspect <Contract> storage.

Type widening (HIGH)

uint8 → uint256 changes packing.

Library uses fixed assembly slot (MEDIUM-HIGH)

assembly { sstore(0x0, value) }   // ← collides with the consumer's slot 0

Use namespaced storage (keccak256("myapp.storage.foo")).

Diamond storage namespace collision (HIGH)

Two facets using the same bytes32 STORAGE_POSITION. Always derive from a unique namespace string.

ERC-7201 namespaced storage missing on new code (MEDIUM)

Modern best-practice: use @custom:storage-location erc7201:my.namespace.

Severity rubric

Remediation patterns

• Run forge inspect <Contract> storageLayout for V1 and V2; diff JSON. Any non-append change = abort.
• OpenZeppelin Upgrades Plugin: validateUpgrade() catches most layout breaks at build time.
• Each upgradeable base contract reserves uint256[N] private __gap at the end (size by convention).
• Use EIP-1967 / EIP-7201 for namespaced storage in libraries and diamonds.
• Never modify or remove existing storage slots — only append.

False-positive notes

• Adding a constant or immutable variable doesn't change storage layout (lives in bytecode, not storage).
• Pure function additions don't affect layout.
• Internal helper changes within a function don't affect layout.

Related

• [[initialization]] — re-init after upgrade
• [[delegatecall-risks]] — proxy mechanics
• [[upgrade-safety]] (command/skill bridge)