Storage Layout

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

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

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

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

# 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

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

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
}

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

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