storage-layout

# Storage Layout ## EVM Storage Fundamentals Each storage slot is 32 bytes (256 bits). State variables are assigned slots sequentially starting at slot 0. Multiple variables smaller than 32 bytes are packed into a single slot when possible. ```solidity // Slot 0: addr (20 bytes) + isActive (1 byte) + role (1 byte) = 22 bytes — fits one slot // Slot 1: balance (32 bytes) — full slot // Slot 2: lastUpdate (8 bytes) — new slot (won't pack with previous full slot) contract Packed { address addr; // 20 bytes | slot 0 bool isActive; // 1 byte | slot 0 uint8 role; // 1 byte | slot 0 uint256 balance; // 32 bytes | slot 1 uint64 lastUpdate; // 8 bytes | slot 2 } ``` ## Struct Packing Order fields from largest to smallest alignment, grouping sub-32-byte fields together. ```solidity // BAD: 4 slots (128 bytes) struct UserBad { bool isActive; // 1 byte | slot 0 (31 bytes wasted) uint256 balance; // 32 bytes | slot 1 address wallet; // 20 bytes | slot 2 (12 bytes wasted) uint256 rewards; // 32 bytes | slot 3 } // GOOD: 3 slots (96 bytes) struct UserGood { uint256 balance; // 32 bytes | slot 0 uint256 rewards; // 32 bytes | slot 1 address wallet; // 20 bytes | slot 2 bool isActive; // 1 byte | slot 2 (packed with wallet) } ``` ### Aggressive Packing Example ```solidity // 1 slot (32 bytes) for a position record struct Position { address owner; // 20 bytes uint48 openedAt; // 6 bytes (good until year 8.9M) uint40 collateral; // 5 bytes (up to ~1.1T with scaling) bool isLong; // 1 byte } // Total: 20 + 6 + 5 + 1 = 32 bytes = 1 slot ``` ### Timestamp Sizing Guide | Type | Bytes | Max Value | Overflow Date | |------|-------|-----------|---------------| | uint32 | 4 | 4.29B | Feb 2106 | | uint40 | 5 | 1.1T | Year ~36812 | | uint48 | 6 | 281T | Year ~8.9M | Use `uint48` for timestamps in most protocol designs. `uint32` overflows in 2106. ## Storage Slot Calculation ```solidity // Fixed-size variables: sequential slots starting at 0 // Mappings: keccak256(key . slot) // Dynamic arrays: length at slot, elements at keccak256(slot) + index // Nested mappings: keccak256(innerKey . keccak256(outerKey . slot)) // Example: mapping(address => mapping(uint256 => uint256)) at slot 5 // Value at [addr][id] is stored at: // keccak256(abi.encode(id, keccak256(abi.encode(addr, 5)))) ``` ## Inspecting Storage Layout ```bash # Forge: inspect storage layout forge inspect src/MyContract.sol:MyContract storage-layout --pretty # Output shows slot, offset, type, and variable name # Use this to verify packing and detect collisions before deployment ``` ## Proxy Storage Patterns ### EIP-1967 Standard Slots ```solidity // Implementation slot bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc; // bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1) // Admin slot bytes32 internal constant _ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103; // bytes32(uint256(keccak256("eip1967.proxy.admin")) - 1) // Beacon slot bytes32 internal constant _BEACON_SLOT = 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50; // bytes32(uint256(keccak256("eip1967.proxy.beacon")) - 1) ``` ### Storage Gaps for Upgradeable Contracts ```solidity abstract contract StorageGapExample { uint256 public value1; address public admin; // Reserve 48 slots for future storage variables // When adding new variables, reduce the gap size accordingly uint256[48] private __gap; } // In V2, adding a new variable: abstract contract StorageGapExampleV2 { uint256 public value1; address public admin; uint256 public newValue; // added in V2 uint256[47] private __gap; // reduced from 48 to 47 } ``` ### Unstructured Storage (Diamond/EIP-2535) ```solidity library LibDiamond { bytes32 constant DIAMOND_STORAGE_POSITION = keccak256("diamond.standard.diamond.storage"); struct DiamondStorage { mapping(bytes4 => address) selectorToFacet; mapping(bytes4 => uint96) selectorToSlotPosition; bytes4[] selectors; mapping(bytes4 => bool) supportedInterfaces; address contractOwner; } function diamondStorage() internal pure returns (DiamondStorage storage ds) { bytes32 position = DIAMOND_STORAGE_POSITION; assembly { ds.slot := position } } } ``` ## Namespace Storage Pattern (ERC-7201) ```solidity /// @custom:storage-location erc7201:myprotocol.storage.vault struct VaultStorage { mapping(address => uint256) balances; uint256 totalDeposited; bool paused; } // keccak256(abi.encode(uint256(keccak256("myprotocol.storage.vault")) - 1)) // & ~bytes32(uint256(0xff)) bytes32 private constant VAULT_STORAGE_LOCATION = 0x...; function _getVaultStorage() private pure returns (VaultStorage storage $) { assembly { $.slot := VAULT_STORAGE_LOCATION } } ``` ## Common Mistakes - **Reordering variables** in an upgradeable contract (shifts all subsequent slots) - **Forgetting to reduce `__gap`** when adding variables - **Changing variable types** (e.g., `uint128` to `uint256` shifts layout) - **Inheriting in different order** between proxy versions - **Not running `forge inspect`** before deploying upgrades ## Storage Layout Verification Checklist - [ ] Run `forge inspect --storage-layout` on both old and new versions - [ ] Diff the layouts to verify no slot collisions - [ ] New variables only appended (never inserted) - [ ] `__gap` reduced by exactly the number of new slots used - [ ] Inheritance order unchanged between versions - [ ] Use EIP-7201 namespaced storage for new diamond/modular patterns - [ ] Struct field order optimized for packing