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.

// 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.

// 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

// 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.