Storage Layout Safety

---
name: "storage-layout-safety"
description: "Type Thought-template (instantiate before use) - Trigger Pattern STORAGE_LAYOUT flag detected"
---

# Skill: Storage Layout Safety

> **Type**: Thought-template (instantiate before use)
> **Trigger Pattern**: STORAGE_LAYOUT flag detected
> **Inject Into**: depth-state-trace, depth-edge-case
> **Finding prefix**: `[SLS-N]`
> **Rules referenced**: R1, R4, R8, R10, R14

Covers: memory vs storage confusion, lost writes, proxy/upgrade storage collisions, inline assembly slot safety, and storage semantic corruption.

This vulnerability class exists ONLY on EVM - type-safe VMs (Move, Solana's Borsh model) enforce layout correctness at the runtime level. EVM's untyped 256-bit slot model permits silent corruption when layouts diverge.

---

## Trigger Patterns
```
proxy|upgradeable|diamond|delegatecall|EIP1967|StorageSlot|
sstore|sload|assembly\s*\{|tstore|tload|reinitializer|
UUPSUpgradeable|TransparentUpgradeableProxy|BeaconProxy
```

---

## Step 1: Storage Surface Inventory

Map the contract's persistent state surface before analyzing bugs:

| # | Variable | Type | Slot Assignment | Written By | Read By | Proxy-Relevant? |
|---|----------|------|----------------|-----------|---------|-----------------|

For each state variable, determine:
- Sequential layout (compiler-assigned) vs manual slot (EIP-1967, custom `bytes32` constant)?
- Accessed via Solidity or via assembly `sstore`/`sload`?
- For structs: trace slot computation (base + offset). For mappings: `keccak256(key . slot)`. For arrays: `keccak256(slot) + index`.

Tag: `[TRACE:variable={name} → slot={computation} → writers={functions}]`

---

## Step 2: Memory vs Storage Confusion

For each function operating on structs or complex types:

### 2a. Reference Type Assignment
Trace every local variable of struct, array, or mapping type:
- Declared as `storage` or `memory`?
- If `memory`: is the function INTENDING to modify persistent state? If yes → lost write (copy modified in memory, never persisted).
- If `storage`: does every code path that modifies the reference complete without early return before the write?

### 2b. Parameter Data Location
For each function accepting struct/array parameters:
- Is the parameter `memory` or `calldata`?
- Does the function modify the parameter expecting persistence? `function update(MyStruct memory s)` modifies `s.field` but `s` is a memory copy - original unchanged.

### 2c. Library Forwarding
For libraries called via `using ... for`:
- Does the library function take `storage` or `memory` references?
- Mismatch between caller expectation and library signature → silent behavioral change.

Tag: `[TRACE:function={name} → var={var} → location={memory/storage} → write_persisted={YES/NO}]`

---

## Step 3: Proxy Storage Layout Analysis

### 3a. Implementation vs Proxy Slot Overlap
- Map slots used by PROXY (admin, implementation, beacon).
- Map slots used by IMPLEMENTATION (state variables from slot 0).
- Any overlap? For EIP-1967: verify randomized slots match spec (`bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1)`).

### 3b. Upgrade Layout Continuity
For each upgrade path (V1 → V2):
- V1 variables in SAME slots in V2? (no reordering, no type changes, no removed mid-sequence variables)
- New variables APPENDED after existing? (not inserted)
- Inheritance order identical? (different order = different slot assignment)
- `__gap` storage slots reserved? New variables consuming gap correctly?

### 3c. Diamond / Namespaced Storage
For EIP-2535 or namespaced storage:
- Each facet uses unique namespace (keccak256 of distinct string)?
- Can two facets share the same namespace accidentally?
- Storage structs within namespace consistent across facet upgrades?

Tag: `[TRACE:proxy_slot={N} → impl_var={name} → collision={YES/NO}]`

---

## Step 4: Assembly Storage Safety

For each inline assembly block using `sstore` or `sload`:

### 4a. Slot Computation
- Target slot hardcoded, constant-derived, or influenced by external input?
- If input-influenced → can attacker target ARBITRARY slots? Is slot value bounded/validated before `sstore`?

### 4b. Value Encoding
- Correctly handles types < 32 bytes? (`sstore` writes full 32 bytes - masking/shifting correct for packed slots?)
- For packed storage (multiple variables in one slot): does assembly preserve neighboring values?

### 4c. Transient Storage (EIP-1153)
If `tstore`/`tload` used:
- Correctly distinguished from `sstore`/`sload`? (transient cleared after tx, permanent is not)
- Critical state accidentally stored with `tstore` instead of `sstore`?

Tag: `[BOUNDARY:user_input={MAX} → computed_slot={value} → target={what_gets_overwritten}]`

### 4d. Hardcoded Offset into ABI-Encoded Data

**Processing**: ENUMERATE all `calldataload`/`mload(add(` sites with literal offsets + all byte-slicing with hardcoded N on dynamic-type data → PROCESS each against the criteria below → COVERAGE GATE before moving to Step 5.

**Scope**: Any code that reads from ABI-encoded data using hardcoded byte offsets rather than following offset pointers. This includes:
- `calldataload(N)` in assembly (raw calldata)
- `mload(add(data, N))` in assembly (bytes memory/calldata variable)
- `data[N:]` or `data[N:N+32]` byte-slicing in Solidity with hardcoded N
- Hardcoded offset arithmetic into nested `bytes` fields after `abi.decode`

Grep: `calldataload\(` with a numeric literal, `mload(add(` with a literal offset on a bytes variable, fixed-offset byte-slicing on decoded `bytes` data.

| Read Site | Mechanism | Offset | Hardcoded? | Into Dynamic-Type Content? | Value Used For | Same Value Read via abi.decode? |
|-----------|-----------|--------|-----------|---------------------------|----------------|-------------------------------|

**Root cause**: ABI encoding is a convention, not enforced by the EVM. Dynamic types (`bytes`, `string`, `T[]`) use offset pointers — the content can be placed anywhere the pointer says. Hardcoded offsets assume canonical pointer values. A caller can supply non-canonical (but ABI-valid) encoding, making the hardcoded position contain attacker-controlled data instead of the expected field. This applies at every nesting level — top-level calldata, inner `bytes` fields, and nested structs.

**Three impact categories**:

**HIGH/CRITICAL — Dual-read divergence**: Hardcoded-offset read + the same value also read via `abi.decode` or pointer-following elsewhere. The two reads see different values. Enables: authorization bypass (auth sees attacker, execution sees victim), accounting divergence (check validates amount X, transfer uses amount Y).

**MEDIUM — Single-read assumption violation**: Hardcoded-offset read into dynamic-type content, value is security-critical, no dual-read exists but offset pointer is not validated as canonical. The contract reads attacker-controlled data as a trusted field. Latent Critical — any future addition of `abi.decode` on the same data creates dual-read divergence.

**MEDIUM — Revert injection / DoS**: Hardcoded-offset read lands on attacker-controlled data that triggers a revert (zero address, overflow, out-of-bounds). Legitimate calldata (via canonical encoding) would succeed, but attacker-crafted non-canonical encoding causes revert. Enables: griefing specific operations, front-run DoS if attacker can submit a malformed version of a victim's pending transaction.

**MEDIUM — Hash divergence**: Contract hashes raw calldata or portions of it (via assembly `keccak256` over `calldatacopy` or manual packing) for signature verification, deduplication, or identity. Non-canonical encoding produces different hashes for logically identical inputs — or identical hashes for different inputs if overlapping tail pointers are used. Breaks: signature verification, replay protection, UserOp-style identity schemes.

**Do not report if**: The read targets a static-type parameter in the ABI head area (position is fixed regardless of offset pointers), or the value is not security-critical, or the contract validates that the offset pointer equals the expected canonical value before reading.

**Additional note — memory vs calldata decoding inconsistency**: Non-canonical calldata that decodes successfully via `abi.decode` from calldata may fail when the same bytes are copied to memory and re-decoded — the Solidity memory decoder is stricter. Code that copies calldata to memory then decodes should be checked for this asymmetry.

Tag: `[TRACE:hardcoded_read({mechanism}, offset={N}) → dynamic_type_content={YES/NO} → dual_read={YES/NO} → impact={DIVERGENCE/ASSUMPTION/REVERT_DOS/HASH_DIVERGENCE}]`

---

## Step 5: Storage Semantic Corruption

### 5a. Deletion Consistency
When mapping entries or array elements are deleted:
- ALL auxiliary structures updated? (index arrays, counters, totals, role flags)
- `delete mapping[key]` clears value but leaves stale entries in enumeration arrays?

### 5b. Bit Packing / Bitmap Operations
For manual bit packing:
- Every write correctly MASKs target bits without corrupting neighbors?
- Stale bits cleared on deletion? (`|= (1 << n)` to set but `= 0` instead of `&= ~(1 << n)` to clear → clears ALL bits)

### 5c. Uninitialized Storage Reads
Variables read before explicit write:
- Default value (0, address(0), false) a VALID state the code handles correctly?
- `require(configuredValue > 0)` but never set → permanent DoS. `if (admin == address(0)) { unrestricted }` → open access until set.

Tag: `[TRACE:delete={op} → auxiliary={state} → updated={YES/NO} → consumer={func} → reads_stale={YES/NO}]`

---

## Key Questions (must answer all)
1. Does the contract use sequential layout, manual slots, or both?
2. For proxy patterns: do implementation variables overlap with proxy admin slots?
3. For assembly: can any `sstore` target be influenced by external input?
4. For struct operations: are all memory-reference modifications intentional (not lost writes)?
5. For deletion: are all auxiliary data structures updated when primary state is removed?

## Common False Positives
- **EIP-1967 compliant**: Standard randomized slots with verified computation → no collision
- **Intentional memory copy**: Read-only computation on a copy, no intent to persist → not a lost write
- **Reserved gaps with matching inheritance**: `__gap` consumed correctly → no layout shift
- **Audited library assembly**: Well-tested library (e.g., OpenZeppelin `StorageSlot`) → lower risk

## Step Execution Checklist (MANDATORY)

| Section | Required | Completed? | Notes |
|---------|----------|------------|-------|
| 1. Storage Surface Inventory | YES | | All state variables with slots |
| 2. Memory vs Storage Confusion | IF structs/complex types | | Data location of all references |
| 3. Proxy Storage Layout | IF proxy/upgradeable | | Slot overlap, upgrade continuity |
| 4. Assembly Storage Safety | IF assembly with sstore/sload | | Slot computation, value encoding |
| 4d. Hardcoded Offset into ABI Data | IF calldataload/mload at hardcoded offset OR byte-slicing with literal offset on dynamic-type data | | Dual-read divergence, assumption violation, revert injection |
| 5. Storage Semantic Corruption | IF delete/restructure ops | | Auxiliary state consistency |