Storage layout
Suggest an editThe compiler places state variables into 32-byte storage slots in declaration order, and puts the contents of arrays and mappings at slots derived by hashing. Anyone can compute a slot and read it, so marking a state variable
privatedoes not make it secret.
Storage is an array of slots
The mappings lesson described storage as a flat array of 2^256 slots, 32 bytes each, all initialized to zero. State variables get assigned positions in this array when the contract is compiled, starting from slot 0 in declaration order.
Consider this contract:
// Solidity 0.8.24, Ethereum mainnet
contract Sample {
uint256 a = 123;
uint128 b = 10;
uint128 c = 20;
}The compiler walks the variables in order. a is 32 bytes wide, so it takes all of slot 0. Next is b, which is 16 bytes wide. It can't fit in slot 0, so b starts at slot 1 in the low 16 bytes. Next is c, also 16 bytes wide. The high 16 bytes of slot 1 are still free, so c fits there. b and c share slot 1.
The packing rule: adjacent state variables get packed into the same slot if their combined size fits in 32 bytes. The first variable in declaration order occupies the low bytes. Each subsequent packed variable occupies the next higher bytes upward.
Every storage slot you write costs gas, so the order of declaration decides how many slots you pay for. If you write uint128 b; uint256 a; uint128 c; instead, the compiler can't pack b and c together because a sits between them, and you end up using three slots instead of two. The structs lesson counted the difference in gas.
Reading storage from outside
Storage isn't private to the contract. Every full node holds a copy of every contract's storage. Any client can ask any node for the contents of any slot via the JSON-RPC method eth_getStorageAt(contractAddress, slot).
From a Hardhat test using viem:
// Hardhat 3 with viem
const slot0 = await publicClient.getStorageAt({
address: sample.address,
slot: 0n,
});
const slot1 = await publicClient.getStorageAt({
address: sample.address,
slot: 1n,
});
console.log("slot 0:", slot0);
console.log("slot 1:", slot1);For the example contract above this prints:
slot 0: 0x000000000000000000000000000000000000000000000000000000000000007b
slot 1: 0x000000000000000000000000000000140000000000000000000000000000000aSlot 0 reads as 0x...7b, where 7b is the hex of 123, the value of a. The leading zeros are just the slot's 32-byte width.
Slot 1 reads as 0x...0014...000a. Two values are visible inside the slot. The high 16 bytes hold 0x14, which is 20 in decimal, the value of c. The low 16 bytes hold 0x0a, which is 10 in decimal, the value of b. They share the slot as the diagram showed.
The contract didn't expose a, b, or c as public, and the read works anyway.
A dynamic array keeps its length in its slot and its elements at a hash
Fixed-size types fit in a known number of slots, so the compiler assigns them positions at compile time. Dynamic types like uint256[] and mapping(K => V) can grow at runtime, so the compiler can't know in advance how many slots they'll need. The Solidity spec handles this by giving each dynamic type a main slot at the usual declaration-order position and then placing the actual contents at slots derived through hashing.
Take this contract:
// Solidity 0.8.24, Ethereum mainnet
contract Sample {
uint256 a = 123;
uint256[] arr;
constructor() {
arr.push(10);
arr.push(20);
}
}a takes slot 0. The dynamic array arr gets slot 1 as its main slot, but the main slot holds only the array length.
For a dynamic array at main slot p, the elements are stored starting at slot keccak256(p). The first element is at keccak256(p), the second at keccak256(p) + 1, the i-th at keccak256(p) + i. The keccak256 output is a 256-bit number, so the elements land at some unpredictable position in the slot array, typically nowhere near the other state variables.
Reading slot 1 of this contract returns 0x...02, the length. Slot keccak256(1), with the 1 padded to 32 bytes, returns 0x...0a, which is 10, and the slot after it returns 0x...14, which is 20. Anyone who knows the contract's address and the main slot number can read the whole array.
A mapping value sits at the hash of its key and the main slot
Mappings use a similar derivation but include the key. For a mapping declared at main slot p, the value at key k is stored at slot keccak256(k . p), where . means concatenation. Both k and p are padded to 32 bytes before being concatenated, then the 64-byte result is hashed.
// Solidity 0.8.24, Ethereum mainnet
contract Sample {
uint256 a = 123;
uint256[] arr;
mapping(address => uint256) balances;
constructor() {
arr.push(10);
arr.push(20);
balances[msg.sender] = 100;
}
}The mapping balances is the third state variable, so it gets slot 2 as its main slot. But the main slot stays at zero forever. Mappings don't track length, since every possible key already conceptually "exists" with the default value 0.
For the deployer's address, the value sits at the slot keccak256(deployer . 2), and reading that slot returns 0x...64, which is 100. The mappings lesson covers what follows from this derivation: a key that was never written reads as zero, and a mapping can't be enumerated or returned from a function.
Each level of nesting adds one hash
A mapping(address => uint256[]) stores the dynamic array at the slot derived from the address key, and that array's elements live at further slots derived from that slot. A mapping(address => mapping(uint256 => bool)) derives a slot from the outer key, then derives again from the inner key.
Each level of dynamic indirection is one more keccak256 step. The derivation is deterministic, so anyone holding the keys can compute the final slot and read it.
"Private" doesn't mean private
The private keyword in Solidity controls who can reference the variable in source code. A private uint256 secret cannot be referenced by name from a contract that inherits yours. The Solidity compiler enforces this at compile time.
Storage doesn't know any of that. There is no access control at the storage level, and there couldn't be, because every node stores every slot and any client can read any of them via eth_getStorageAt.
The common mistake looks like this:
// Solidity 0.8.24, Ethereum mainnet
contract VulnerableLock {
address private owner;
uint256 private secretCode;
constructor(uint256 _secretCode) {
owner = msg.sender;
secretCode = _secretCode;
}
function unlock(uint256 attempt) external {
require(attempt == secretCode, "wrong code");
// do something privileged
}
}The deployer believes secretCode is hidden because it's private. But anyone watching the deployment transaction can already see the constructor argument in calldata, and after deployment anyone can read secretCode straight off the chain:
cast storage <lock_address> 1 --rpc-url <node_url>
# 0x0000000000000000000000000000000000000000000000000000000000000539
# that's the secret in hex (0x539 = 1337)Sealed RNG seeds, commit values, off-chain authentication codes, internal pricing data, partial private keys split across slots: all have been stored as private state variables and read straight off the chain.
The actual options for keeping a value secret on chain are limited, and each has a cost:
- The value can live off chain entirely, with the contract verifying a hash or signature from an off-chain source. The contract then relies on that source to keep the value secret and to stay available.
- You can use commit-reveal: store
keccak256(value, salt)during a commit phase, then have the user revealvalueandsaltlater. The commit is on chain but the preimage stays hidden until reveal. This takes two transactions with a delay between them, as the front-running lesson showed, and from the reveal on the value is public. - For richer guarantees, cryptographic schemes like zero-knowledge proofs let a contract verify properties of a value without ever seeing the value itself. The proof has to be computed off chain, and verifying it costs more gas than checking a signature (more in off-chain computation, on-chain verification).
Inserting a variable moves every variable after it
A variable's slot follows from the declarations before it, so changing the declarations changes the layout. Insert a new uint256 between a and b in the first Sample, and it takes slot 1, while b and c move to slot 2.
A freshly deployed contract is not affected, because its storage starts empty. The shift matters when new code runs on storage that an earlier version wrote. That code would read b and c from slot 2, which the old version never wrote, and would find the old b and c where it expects the new variable. An upgradeable contract is in this position, and the next lesson covers it.