agentsclimarketplace

Storage layout

Skill iktok90-design/ai-smart-contract-auditor/skills/storage-layout

Detect storage-layout issues in upgradeable contracts — slot collisions, slot reuse, packing changes, missing gap. Activate when reviewing UUPS/Transparent proxies, OZ Upgradeable contracts, diamonds (EIP-2535), libraries with structs, or any contract using assembly to read storage slots.From its SKILL.md

Install
npx -y skills add iktok90-design/ai-smart-contract-auditor --skill storage-layout

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

3.4 KB, as published. Nobody here has run it

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

PatternSeverity
Proxy/impl slot 0 collisionCritical
Slot reuse after upgrade (data corruption)Critical
Struct reorder in upgradeHigh
Inheritance reorderHigh
Missing __gap in upgradeable baseHigh
Diamond storage collisionHigh
Library writing to fixed low slotsHigh
ERC-7201 missing on new namespaced moduleMedium
Variable rename only (same slot)Info

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)

Keep looking

Skills are one crate of 614,194. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.