The Book of Proxy

MODULE 00 Storage slots in Solidity

Where state variables actually live: sequential slot allocation, the packing rules, and reading or writing a slot directly with sload and sstore.

Every proxy bug is, underneath, a storage bug. So the book starts where the EVM starts: a contract's storage is a mapping from a 256-bit key to a 256-bit value — 2²⁵⁶ slots, all of them zero until written. Solidity hands out those slots at compile time, and it is the slot number, never the variable name, that survives into the deployed bytecode.

Sequential allocation

State variables are assigned slots in declaration order: the first gets slot 0, the second slot 1, and so on. The assignment is permanent — recompiling with the variables reordered produces a contract that reads different data out of the same storage.

contract Sequential {
    uint256 a;   // slot 0
    uint256 b;   // slot 1
    uint256 c;   // slot 2
}

Packing

Variables smaller than 32 bytes share a slot when they are declared consecutively and their sizes add up to 256 bits or fewer. Solidity fills a slot from the least significant (rightmost) byte leftwards. A variable that does not fit in the space left over starts a fresh slot — it is never split across two.

contract Wasteful {
    uint16  a;   // slot 0  (2 bytes used, 30 wasted)
    uint256 x;   // slot 1  (a full slot must start fresh)
    uint32  b;   // slot 2  (2 bytes used, 28 wasted)
}                // → 3 slots

contract Packed {
    uint256 x;   // slot 0
    uint16  a;   // slot 1, bytes 0-1
    uint32  b;   // slot 1, bytes 2-5
}                // → 2 slots

Reading and writing slots directly

Yul gives you three tools. x.slot is compile-time information — the slot index a variable was assigned. sload(slot) returns all 32 bytes of that slot as a bytes32. sstore(slot, value) overwrites all 32 bytes.

contract Direct {
    uint256 x = 42;

    function slotOfX() external pure returns (uint256 s) {
        assembly { s := x.slot }          // → 0
    }

    function readRaw(uint256 s) external view returns (bytes32 v) {
        assembly { v := sload(s) }        // no type checking whatsoever
    }

    function writeRaw(uint256 s, uint256 v) external {
        assembly { sstore(s, v) }         // overwrites the WHOLE slot
    }
}

MODULE 01 Storage slots of dynamic types

Mappings, arrays, strings and bytes do not get a slot for their data — they get a keccak256 formula. Here are all of them.

A uint256 has a fixed size, so the compiler can reserve a slot for it. A mapping or a dynamic array cannot — their size is unknown at compile time. Solidity solves this by giving the variable a base slot and deriving the data locations by hashing, which spreads them across the 2²⁵⁶ address space so densely that a collision is not a practical concern.

Mappings

contract MappingSlot {
    mapping(address => uint256) balance;   // base slot 0

    function slotOf(address key) public pure returns (bytes32) {
        return keccak256(abi.encode(key, uint256(0)));
    }

    function readVia(address key) public view returns (uint256 v) {
        bytes32 s = slotOf(key);
        assembly { v := sload(s) }
    }
}

Nested mappings just apply the formula again, once per level:

Dynamic arrays

The base slot is used here — it holds the array's length. The elements start at the hash of the base slot and run consecutively:

// uint256[] arr at base slot 2, reading arr[3]
uint256 s = uint256(keccak256(abi.encode(uint256(2)))) + 3;
assembly { value := sload(s) }

Elements pack the same way struct fields do — types of 128 bits or less share slots; an address (20 bytes) does not pack with another address. Nested arrays hash twice:

Strings and bytes

These have two encodings and a one-bit tag to tell them apart.

bytes uses the identical scheme. Fixed-size bytes1…bytes32 are value types: they take one slot (packing where they can) and are indexed with value[0].

Dynamic types inside structs

A struct's fields are laid out from the struct's base slot as though they were top-level variables. A mapping at field index k therefore has base slot structBase + k, and the usual mapping formula applies from there.

MODULE 02 ABI encoding for function calls

The calldata a proxy forwards byte for byte: selector derivation, the head/tail layout for dynamic types, and which abi.encode* helper to reach for.

A proxy's whole job is to hand somebody else's code the calldata it received, unmodified. To reason about that — and about selector clashes, which cause several of the bugs later in this book — you need to know exactly what calldata is.

The function selector

The first four bytes of calldata are bytes4(keccak256(signature)), where the signature is the function name and its parameter types with no spaces and no parameter names.

bytes4(keccak256("transfer(address,uint256)")) == 0xa9059cbb

Canonicalisation rules when building the signature string:

• struct becomes a tuple — (uint256,address)
• address payable becomes address
• enum becomes uint8
• user-defined value types resolve to their underlying type
• memory / calldata / storage are ignored

Head and tail

Arguments are encoded in two regions. Static types (uint256, bool, address, fixed arrays of statics, structs with only static fields) are padded to 32 bytes and written inline in the head. Dynamic types (string, bytes, dynamic arrays, and anything containing them) write a 32-byte offset in the head, and the real data goes in the tail at that offset.

foo(uint256,string)  with  (5, "hi")

0x  a1b2c3d4                                                          selector
    0000000000000000000000000000000000000000000000000000000000000005  5
    0000000000000000000000000000000000000000000000000000000000000040  offset -> 0x40
    0000000000000000000000000000000000000000000000000000000000000002  length 2
    6869000000000000000000000000000000000000000000000000000000000000  "hi", right-padded

Which helper to use

MODULE 03 Low level call vs high level call

Both compile to the same opcode. The difference is the safety code the compiler wraps around it — and a low-level call to an empty address returning true.

Calling IFoo(target).bar() and calling target.call(...) both end in the CALL opcode. Everything that differs is bytecode Solidity generates around it.

Failure handling

A high-level call through an interface reverts automatically when the callee reverts — the compiler emits the check. A low-level call does not: per the Solidity docs, low-level calls "return false as their first return value in case of an exception instead of bubbling up". Ignoring that boolean is one of the most common findings in an audit.

// low level — you own the check
(bool ok, bytes memory ret) = target.call(abi.encodeCall(IFoo.bar, ()));
if (!ok) revert CallFailed();

// high level — the compiler owns the check
IFoo(target).bar();

The empty-address trap

High-level calls do not have this problem because the compiler first runs EXTCODESIZE and reverts when the target has no code. If you are writing low-level calls, you have to do it yourself:

function safeCall(address target, bytes memory data) internal returns (bytes memory) {
    require(target.code.length > 0, "no code at target");
    (bool ok, bytes memory ret) = target.call(data);
    if (!ok) {
        assembly { revert(add(ret, 0x20), mload(ret)) }   // bubble the real reason
    }
    return ret;
}

The three variants

Gas is forwarded under EIP-150's 63/64 rule: a call gets all but a sixty-fourth of the remaining gas unless you cap it explicitly. That reserved sixty-fourth is what lets the caller still handle a failed subcall rather than dying with it.

MODULE 04 Try/catch and all the ways Solidity can revert

Every revert shape a proxy might have to forward: empty, Error(string), Panic(uint256) and custom errors — plus what try/catch cannot catch.

A proxy has to forward whatever the implementation threw, byte for byte. That means knowing the four shapes revert data comes in.

The four shapes

Panic codes

Panics come from the safety checks the compiler inserts, not from your requires:

try / catch

try IFoo(target).risky() returns (uint256 v) {
    // success path — v is available here
} catch Error(string memory reason) {
    // revert("...") and require(..., "...")
} catch Panic(uint256 code) {
    // assert, overflow, division by zero, ...
} catch (bytes memory data) {
    // custom errors and empty reverts — decode `data` yourself
}

catch (bytes memory data) {
    if (bytes4(data) == IFoo.Unauthorized.selector) {
        // handle the specific custom error
    }
}

MODULE 05 Assembly revert

revert(offset, size) in Yul, how to hand-encode each error shape, and the bubble-up idiom every proxy fallback ends with.

The Yul revert takes a memory offset and a byte length: everything in that window becomes the return data. It is how a proxy forwards an implementation's error without knowing what that error was.

Writing the data first

mstore(p, v) writes 32 bytes at p, left-padding anything shorter. So mstore(0, 0xff) actually writes 0x00…00ff across bytes 0–31 — the ff lands at byte 31, not byte 0. mstore8 writes a single byte when you need that precision.

Hand-encoding each shape

// 1. no reason
assembly { revert(0, 0) }

// 2. custom error, no args:  error Unauthorized();
//    selector must sit in the FIRST four bytes, so shift it left
assembly {
    mstore(0x00, 0x82b4290000000000000000000000000000000000000000000000000000000000)
    revert(0x00, 0x04)
}

// 3. custom error with args: error BadAmount(uint256 got);
assembly {
    mstore(0x00, 0x1f2a200000000000000000000000000000000000000000000000000000000000)
    mstore(0x04, got)
    revert(0x00, 0x24)          // 4 selector + 32 arg
}

// 4. Error(string) — selector, offset, length, data
assembly {
    mstore(0x00, 0x08c379a000000000000000000000000000000000000000000000000000000000)
    mstore(0x04, 0x20)          // offset to the string
    mstore(0x24, 5)             // length
    mstore(0x44, "oops")        // the bytes, right-padded
    revert(0x00, 0x64)
}

Bubbling up return data

This is the idiom that closes every proxy fallback in the rest of the book. returndatasize() gives the length of whatever the last call returned, and returndatacopy(dest, offset, size) copies it into memory:

assembly {
    // forward all calldata to the implementation
    calldatacopy(0, 0, calldatasize())
    let ok := delegatecall(gas(), impl, 0, calldatasize(), 0, 0)

    // copy back whatever came out — return data or revert data
    returndatacopy(0, 0, returndatasize())

    switch ok
    case 0 { revert(0, returndatasize()) }   // re-throw the original error
    default { return(0, returndatasize()) }  // pass the result through
}

MODULE 06 Delegatecall

Borrow another contract's code, keep your own storage, sender and balance. The one opcode every pattern in this book is built on — and the one that makes them dangerous.

delegatecall executes the target's bytecode in the caller's context. The target supplies logic and nothing else: no storage, no balance, no identity.

What is preserved

contract Logic {
    uint256 public number;                       // slot 0 — of whoever calls it

    function setNumber(uint256 n) external { number = n; }
    function whoAmI() external view returns (address) { return address(this); }
}

contract Caller {
    uint256 public number;                       // slot 0 — the one actually written
    address public logic;

    function set(uint256 n) external {
        (bool ok,) = logic.delegatecall(abi.encodeCall(Logic.setNumber, (n)));
        require(ok);
        // Logic's bytecode ran; Caller's slot 0 changed. Logic.number is untouched.
    }
}

Storage collision — the central danger

The implementation's variable names are irrelevant. Only slot numbers cross the delegatecall boundary. If the two layouts disagree, writes land on the wrong variable:

contract ProxyV1 {
    address implementation;   // slot 0
    address admin;            // slot 1
}

contract LogicV1 {
    uint256 counter;          // slot 0  ← same slot as `implementation`
    function inc() external { counter++; }
}

// inc() writes 1 into slot 0.
// The proxy now believes its implementation lives at address 0x…01.
// Every subsequent call delegatecalls to an address with no code — and succeeds silently.

Immutables and constants are the exception

Neither occupies a slot — their values are baked into the implementation's bytecode and travel with it. Under delegatecall they therefore report the implementation's values, not the proxy's. codesize() behaves the same way. Module 18's noDelegateCall is built directly on this quirk.

MODULE 07 Introduction to proxies

Putting modules 00-06 together: a contract that keeps the storage, a second that keeps the logic, and a fallback that welds them into an upgradeable whole.

Contracts are immutable. A proxy works around that by splitting a system in two: the proxy holds the storage and the address users interact with, and an implementation holds the logic. Upgrading means pointing the proxy at new logic — the address and all the state stay put.

Why storage must live in the proxy

Deploying a new implementation gives you a fresh, empty contract. If balances lived there, an upgrade would orphan every user's funds. Keeping state in the proxy — which never gets redeployed — is what makes an upgrade a change of behaviour rather than a migration.

The fallback

The proxy declares almost nothing. Anything it does not recognise hits the fallback, which forwards the calldata verbatim:

contract Proxy {
    // slot chosen by ERC-1967 so an implementation can never collide with it — module 08
    bytes32 private constant _IMPL =
        0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;

    constructor(address impl) { _setImplementation(impl); }

    fallback() external payable { _delegate(_implementation()); }
    receive()  external payable { _delegate(_implementation()); }

    function _implementation() internal view returns (address impl) {
        assembly { impl := sload(_IMPL) }
    }

    function _setImplementation(address impl) private {
        require(impl.code.length > 0, "not a contract");
        assembly { sstore(_IMPL, impl) }
    }

    function _delegate(address impl) internal {
        assembly {
            calldatacopy(0, 0, calldatasize())
            let ok := delegatecall(gas(), impl, 0, calldatasize(), 0, 0)
            returndatacopy(0, 0, returndatasize())
            switch ok
            case 0 { revert(0, returndatasize()) }
            default { return(0, returndatasize()) }
        }
    }
}

Every line of that assembly comes from module 05: copy the calldata in, delegatecall, copy the result out, and either return it or re-throw it. The return is why this must be assembly — a Solidity fallback() cannot return dynamic data.

The two hazards

Upgrading

An upgrade is one sstore behind an access-control check. In practice it is paired with a delegatecall so new state can be initialised atomically — upgradeToAndCall, which module 12 explains.

MODULE 08 EIP-1967 storage slots for proxies

Standardised, unreachable slots for the implementation, admin and beacon pointers — and the keccak256(...) - 1 trick that makes them unreachable.

The proxy needs somewhere to keep its implementation pointer that no implementation could ever reach by accident. EIP-1967 standardises three such slots so that wallets and block explorers can also find them.

The three slots

Why subtract one

library ERC1967 {
    bytes32 internal constant IMPLEMENTATION_SLOT =
        0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;

    event Upgraded(address indexed implementation);

    function getImplementation() internal view returns (address a) {
        assembly { a := sload(IMPLEMENTATION_SLOT) }
    }

    function setImplementation(address newImpl) internal {
        require(newImpl.code.length > 0, "ERC1967: not a contract");
        assembly { sstore(IMPLEMENTATION_SLOT, newImpl) }
        emit Upgraded(newImpl);
    }
}

The events

The standard also fixes the log signatures so off-chain indexers can track upgrades: Upgraded(address indexed implementation), AdminChanged(address previousAdmin, address newAdmin) and BeaconUpgraded(address indexed beacon).

MODULE 09 The transparent upgradeable proxy

Route on msg.sender instead of on the selector: the admin gets the upgrade functions, everyone else gets the implementation. No clash is possible.

The transparent pattern removes selector clashes by removing public functions from the proxy entirely. There is only the fallback, and it decides what to do based on who is calling rather than what they called.

fallback() external payable {
    if (msg.sender == _proxyAdmin()) {
        // the admin may call exactly one thing: upgradeToAndCall
        if (msg.sig != ITransparentUpgradeableProxy.upgradeToAndCall.selector) {
            revert ProxyDeniedAdminAccess();
        }
        _dispatchUpgradeToAndCall();
    } else {
        _delegate(_implementation());   // everyone else always reaches the logic
    }
}

A user can never be routed to upgrade logic, and the admin can never be routed to the implementation. Because no selector is ever compared against the proxy's own functions, a clash cannot occur — the ambiguity has been moved out of the selector space and into the caller.

The ProxyAdmin indirection

That raises a question: if the admin can only ever call upgradeToAndCall, how does an admin who is also a normal user interact with the app? OpenZeppelin's answer is a second contract.

• The proxy stores its admin as an immutable — a deployed ProxyAdmin contract, fixed forever.
• ProxyAdmin is an Ownable whose owner can change.
• "Changing the proxy admin" means transferring ProxyAdmin's ownership, not touching the proxy at all.

Immutable admin, ERC-1967 slot anyway

Reading the admin from an immutable rather than storage saves the ~2,100 gas of a cold SLOAD on every call. The proxy still writes the admin address into the ERC-1967 admin slot at construction — purely so block explorers recognise it — and then never reads it.

upgradeToAndCall

function upgradeToAndCall(address newImplementation, bytes memory data) internal {
    _setImplementation(newImplementation);
    emit Upgraded(newImplementation);
    if (data.length > 0) {
        Address.functionDelegateCall(newImplementation, data);
    }
}

Combining the two is what makes an upgrade atomic: the new implementation is installed and its reinitializer runs in the same transaction, so there is no window in which the new code is live but its new state is unset. Note it does not require the implementation to actually change — passing the current one is a way for the admin to execute an arbitrary delegatecall.

The inheritance chain

MODULE 10 UUPS: universal upgradeable proxy standard

Move the upgrade function into the implementation. Cheaper calls, a swappable authorisation scheme — and the ability to permanently brick your own contract.

The transparent proxy solves the selector clash by making the proxy smarter. UUPS solves it by making the proxy dumber: the proxy has no upgrade logic at all, so there is nothing to clash with. The upgradeToAndCall function lives in the implementation and runs — via delegatecall — against the proxy's storage, rewriting the proxy's ERC-1967 slot.

_authorizeUpgrade

UUPSUpgradeable leaves exactly one thing for you to write, and it is the access control. An empty override is a total loss of the contract.

contract MyLogic is UUPSUpgradeable, OwnableUpgradeable {
    constructor() { _disableInitializers(); }        // module 12

    function initialize(address owner_) external initializer {
        __Ownable_init(owner_);
        __UUPSUpgradeable_init();
    }

    function _authorizeUpgrade(address newImpl) internal override onlyOwner {}
    //                                                          ^^^^^^^^^
    //  forget this modifier and anyone can upgrade the contract to their own code
}

Because the authorisation lives in the implementation, each version can define its own. You can ship v1 gated by an EOA owner, then upgrade to a v2 gated by a timelock or a multisig or a governance vote — without touching the proxy.

proxiableUUID

Before switching, the current implementation asks the candidate which slot it considers the implementation slot:

function proxiableUUID() external view virtual returns (bytes32) {
    return ERC1967Utils.IMPLEMENTATION_SLOT;   // keccak256("eip1967.proxy.implementation") - 1
}

If the call reverts or returns a different slot, the target is not UUPS-compliant and the upgrade is rejected. This is a guard rail, not a guarantee — it catches the accident of upgrading to a plain non-upgradeable contract.

UUPS versus transparent

If your implementation is pressed against the 24 KB limit, the transparent proxy's ability to keep upgrade code out of it can be the deciding factor.

MODULE 11 ERC-7201 storage namespaces

Give every contract in an inheritance chain its own hashed storage root, so adding a parent never shifts a child's variables.

Sequential slots have a second failure mode beyond proxy/implementation collision: inheritance collision. Parent variables are laid out before child variables, so adding one field to a base contract shifts everything below it — and in an upgrade, every shifted variable now reads its neighbour's data.

Why storage gaps are not enough

The traditional mitigation is a uint256[50] private __gap; at the end of each base contract: new variables consume gap entries instead of shifting anything. But gaps are finite, easy to mis-size, and cannot help at all when you insert a new parent above an existing one in the linearisation — that shifts everything regardless.

The namespace formula

Structs instead of state variables

Declaring any state variable forces Solidity to start at slot 0. So a namespaced contract declares none: the variables become fields of a struct that is never instantiated, and an accessor points that struct at the computed root.

/// @custom:storage-location erc7201:openzeppelin.storage.ERC20
struct ERC20Storage {
    mapping(address => uint256) _balances;
    mapping(address => mapping(address => uint256)) _allowances;
    uint256 _totalSupply;
    string  _name;
    string  _symbol;
}

// keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.ERC20")) - 1)) & ~bytes32(uint256(0xff))
bytes32 private constant ERC20StorageLocation =
    0x52c63247e1f47db19d5ce0460030c497f73fa268027848dcb15b3c9e2d13ec00;

function _getERC20Storage() private pure returns (ERC20Storage storage $) {
    assembly { $.slot := ERC20StorageLocation }
}

function balanceOf(address a) public view returns (uint256) {
    ERC20Storage storage $ = _getERC20Storage();
    return $._balances[a];
}

The key insight is that the slot formulas from module 01 are relative: a mapping at "field 0" of the struct hashes against the struct's root exactly as it would have hashed against slot 0. The struct simply becomes a new origin. Two contracts with different namespaces therefore have layouts that cannot overlap, no matter how the inheritance graph is rearranged.

The annotation

@custom:storage-location erc7201:<namespace> is not decorative — it is the machine-readable declaration that upgrade-safety tooling (module 17) reads to verify that a new version did not move anything.

MODULE 12 The initializable pattern

Constructors run against the wrong storage, so upgradeable contracts initialise by function call — with three modifiers and one constructor line that stops a real attack.

A constructor runs once, at deployment, against the deploying contract's own storage. Under a proxy that is exactly the wrong contract: the implementation's constructor writes the implementation's storage, which no user ever reads. The proxy's storage stays empty.

Initialise by function instead

contract MyToken is Initializable, OwnableUpgradeable {
    uint256 public rate;

    constructor() { _disableInitializers(); }        // see below

    function initialize(address owner_, uint256 rate_) external initializer {
        __Ownable_init(owner_);                      // parent: onlyInitializing
        rate = rate_;                                // writes the PROXY's storage
    }
}

The three modifiers

Two flags rather than one is what makes inheritance work. A single boolean would be set by the child's initializer before the parents ran, locking them out. Instead initializer raises _initializing, every onlyInitializing parent runs inside that window, and on exit the flag drops and _initialized is bumped to the version number.

The uninitialised-implementation attack

_disableInitializers

constructor() {
    _disableInitializers();
}

This sets _initialized to type(uint64).max in the implementation's storage, so no initializer can ever run there again. The proxy is untouched — its _initialized is its own — so proxies still initialise normally. Put this constructor in every implementation contract you write; there is no case where you want it absent.

MODULE 13 The beacon proxy pattern

One upgrade transaction, thousands of proxies. Move the implementation pointer out of the proxies and into a shared beacon.

If you run a factory that deploys one proxy per user, upgrading means one transaction per proxy. With ten thousand vaults that is not an upgrade, it is a migration. The beacon pattern moves the implementation address into a single shared contract that every proxy queries.

The two contracts

contract UpgradeableBeacon is IBeacon, Ownable {
    address private _implementation;

    function implementation() public view returns (address) { return _implementation; }

    function upgradeTo(address newImplementation) public onlyOwner {
        require(newImplementation.code.length > 0, "not a contract");
        _implementation = newImplementation;
        emit Upgraded(newImplementation);          // one tx upgrades every proxy
    }
}

contract BeaconProxy is Proxy {
    // immutable: read from bytecode, not storage, on every call
    address private immutable _beacon;

    constructor(address beacon, bytes memory data) payable {
        _beacon = beacon;
        ERC1967Utils.upgradeBeaconToAndCall(beacon, data);   // writes the ERC-1967 beacon slot
    }

    function _implementation() internal view override returns (address) {
        return IBeacon(_beacon).implementation();
    }
}

The proxy's _beacon is immutable, so an individual proxy can never be pointed somewhere else — the beacon owner controls all of them or none. The beacon address is additionally written to the ERC-1967 beacon slot so explorers can follow the chain.

The cost

When to reach for it

Per-user vaults, vesting schedules and account contracts are the classic fit: dozens or thousands of proxies, one shared logic, and a security fix that must land everywhere at once.

MODULE 14 EIP-1167: the minimal proxy (clone)

45 bytes of runtime that do one thing: delegatecall a hard-coded address. The cheapest way to deploy the same contract ten thousand times.

A minimal proxy is not upgradeable and has no admin. It is a fixed forwarder: every call is delegatecalled to one implementation whose address is compiled into the bytecode. Because deployment cost is dominated by bytecode size, cloning a 20 KB contract costs roughly what deploying 45 bytes costs.

The runtime bytecode

3d602d80600a3d3981f3  363d3d373d3d3d363d73 <20-byte impl> 5af43d82803e903d91602b57fd5bf3
└──── creation (10) ──┘└──────────────── runtime (45) ─────────────────────────────────┘

Deploying with Clones.sol

using Clones for address;

// non-deterministic
address instance = implementation.clone();

// CREATE2 — address is knowable before deployment
address instance = implementation.cloneDeterministic(salt);
address predicted = implementation.predictDeterministicAddress(salt, address(this));

// clones have no constructor: initialise immediately, in the same transaction
IVault(instance).initialize(msg.sender, params);

Limitations

• Not upgradeable. The address is in the bytecode; changing it means deploying a different clone. Use a beacon (module 13) if the fleet must be upgradeable.
• No constructor. Initialise by function, exactly as in module 12.
• Delegatecall overhead on every call — roughly 2,600 gas versus calling the implementation directly.
• immutable variables come from the implementation and are therefore identical across all clones — module 15 exists to solve that.

MODULE 15 EIP-3448: the MetaProxy standard

A clone with per-instance immutable parameters — appended to the bytecode and delivered to the implementation as extra calldata.

Module 14 ended on a limitation: every EIP-1167 clone shares one implementation, so they share its immutables. If you are cloning an ERC-20, all your tokens have the same name. The usual fix is to store name and symbol per clone — but that means an SLOAD forever, plus an initialisation transaction.

EIP-3448 instead appends the parameters to the clone's own bytecode and hands them to the implementation as calldata on every call.

Bytecode layout

┌────────────────────┬──────────────────────────┬──────────────────────┐
│  runtime (54 B)    │  ABI-encoded metadata    │  metadata length     │
│  proxy logic       │  e.g. (name, symbol, ..) │  (32 B, last word)   │
└────────────────────┴──────────────────────────┴──────────────────────┘

The runtime is 54 bytes rather than 1167's 45 because it must also copy the metadata. Total deployed size is 65 bytes of known, verifiable prefix plus however much metadata you appended — and because the prefix is standard, Etherscan can recognise a MetaProxy and resolve its implementation exactly as it does for a 1167 clone.

How the implementation reads it

The proxy appends the metadata to the incoming calldata before delegatecalling. So from the implementation's point of view, every call arrives with extra bytes on the end, and the last word says how many:

function getMetadata() private pure returns (bytes memory data) {
    assembly {
        let posOfMetadataSize := sub(calldatasize(), 32)
        let size := calldataload(posOfMetadataSize)
        let dataPtr := sub(posOfMetadataSize, size)
        data := mload(0x40)
        mstore(0x40, add(data, add(size, 0x20)))   // bump the free memory pointer
        mstore(data, size)                          // write the length
        calldatacopy(add(data, 0x20), dataPtr, size)
    }
}

function name() external pure returns (string memory n) {
    (n, , ) = abi.decode(getMetadata(), (string, string, uint256));
}

Against EIP-1167

MODULE 16 The fallback extension pattern

Not every delegatecall is a proxy. When a contract outgrows 24 KB, forward only the selectors it does not implement to an extension.

EIP-170 caps deployed bytecode at 24,576 bytes. A contract that has outgrown it does not necessarily want upgradeability, tooling, admin roles or any of the machinery in the preceding modules — it just needs more room. The fallback extension pattern gives it exactly that.

// Both contracts inherit the SAME storage contract — this is the whole trick
contract Storage {
    uint256 internal count;
    mapping(address => uint256) internal balances;
}

contract Main is Storage {
    address private immutable extension;

    constructor(address ext) { extension = ext; }

    // hot path stays in this contract
    function increment() external { count++; }

    // everything else falls through
    fallback() external payable {
        address ext = extension;
        assembly {
            calldatacopy(0, 0, calldatasize())
            let ok := delegatecall(gas(), ext, 0, calldatasize(), 0, 0)
            returndatacopy(0, 0, returndatasize())
            switch ok
            case 0 { revert(0, returndatasize()) }
            default { return(0, returndatasize()) }
        }
    }
}

contract Extension is Storage {
    // cold, rarely-called, or view-only functions live here
    function auditReport() external view returns (uint256, uint256) { ... }
}

Storage layout is the requirement

Because the extension runs by delegatecall, it writes Main's storage. The two contracts must agree slot for slot. Duplicating the declarations by hand is how this pattern goes wrong; inheriting a single shared Storage contract — or using ERC-7201 namespaces from module 11 — makes the agreement structural rather than a convention.

Costs and hazards

MODULE 17 Foundry upgrades with the OpenZeppelin plugin

The tooling that reads your storage layout and refuses the upgrade when it would corrupt state. The part of this book you should never skip.

Everything so far has been a rule you have to remember: do not reorder variables, do not change types, append only, never leave _authorizeUpgrade open. The OpenZeppelin Foundry Upgrades plugin turns those rules into a compile-time check.

Setup

forge install OpenZeppelin/openzeppelin-contracts-upgradeable
forge install OpenZeppelin/openzeppelin-foundry-upgrades

# foundry.toml
[profile.default]
build_info    = true
extra_output  = ["storageLayout"]
ffi           = true
ast           = true

Deploying and upgrading

// UUPS
address proxy = Upgrades.deployUUPSProxy(
    "MyTokenV1.sol",
    abi.encodeCall(MyTokenV1.initialize, (owner, 100))
);

// Transparent — the second argument becomes the ProxyAdmin owner
address proxy = Upgrades.deployTransparentProxy(
    "MyTokenV1.sol",
    msg.sender,
    abi.encodeCall(MyTokenV1.initialize, (owner, 100))
);

// Beacon
address beacon = Upgrades.deployBeacon("MyTokenV1.sol", msg.sender);
address proxy  = Upgrades.deployBeaconProxy(beacon, abi.encodeCall(...));

// Upgrade — validated before anything is written on chain
Upgrades.upgradeProxy(proxy, "MyTokenV2.sol", "");

Declaring the predecessor

Validation needs to know what the new version is replacing. That is the @custom:oz-upgrades-from annotation — without it, validation fails rather than silently passing:

/// @custom:oz-upgrades-from MyTokenV1
contract MyTokenV2 is MyTokenV1 {
    uint256 public newField;              // appended — safe

    function initializeV2() external reinitializer(2) { newField = 1; }
}

What it actually checks

function testUpgradePreservesState() public {
    address proxy = Upgrades.deployTransparentProxy(
        "ContractA.sol", msg.sender, abi.encodeCall(ContractA.initialize, (10))
    );
    assertEq(ContractA(proxy).value(), 10);

    Upgrades.upgradeProxy(proxy, "ContractB.sol", "", msg.sender);

    assertEq(ContractB(proxy).value(), 10);   // state survived the upgrade
}

MODULE 18 noDelegateCall explained

Uniswap V3's one-line defence against being cloned: compare address(this) to an immutable recorded at deployment.

Everything in this book so far assumed you want your code delegatecalled. Sometimes you do not. Uniswap V3's source was released under a business licence, and a fork could have sidestepped it by deploying minimal proxies that delegatecall the deployed V3 pool code — inheriting the logic without copying the bytecode. noDelegateCall closes that door.

The mechanism

Module 06 established that under delegatecall address(this) is the caller's address, while immutable values are read from the executing contract's bytecode and therefore stay constant. Put those together and you get a check that can tell the two contexts apart:

abstract contract NoDelegateCall {
    /// @dev The original address of this contract, fixed at deployment.
    address private immutable original;

    constructor() {
        // address(this) here is the real deployed address; it is immutable
        // so it lives in the bytecode and is inlined at every use site.
        original = address(this);
    }

    function checkNotDelegateCall() private view {
        require(address(this) == original);
    }

    modifier noDelegateCall() {
        checkNotDelegateCall();
        _;
    }
}

Called normally, address(this) is the pool and matches original. Called through a proxy, address(this) is the proxy while original is still the pool's own address — the comparison fails and the call reverts.

Why immutable is load-bearing

MODULE 19 The diamond proxy (EIP-2535)

One proxy, many implementations. A selector-to-facet mapping, an upgrade primitive with three actions, and the introspection functions that keep it auditable.

Every proxy so far had exactly one implementation, and therefore inherited its 24 KB limit. A diamond maps each function selector to its own implementation contract — a facet — so the system as a whole has no practical size ceiling.

Routing

fallback() external payable {
    DiamondStorage storage ds;
    bytes32 position = DIAMOND_STORAGE_POSITION;
    assembly { ds.slot := position }

    address facet = ds.selectorToFacet[msg.sig].facetAddress;
    require(facet != address(0), "Diamond: function does not exist");

    assembly {
        calldatacopy(0, 0, calldatasize())
        let ok := delegatecall(gas(), facet, 0, calldatasize(), 0, 0)
        returndatacopy(0, 0, returndatasize())
        switch ok
        case 0 { revert(0, returndatasize()) }
        default { return(0, returndatasize()) }
    }
}

Same fallback as module 07, with one extra step: a mapping lookup on msg.sig instead of a single stored address. Routing is O(1) — there is no chain of conditionals.

diamondCut

enum FacetCutAction { Add, Replace, Remove }

struct FacetCut {
    address facetAddress;
    FacetCutAction action;
    bytes4[] functionSelectors;
}

/// @param _init      contract to delegatecall for initialisation (address(0) to skip)
/// @param _calldata  the initialisation call
function diamondCut(FacetCut[] calldata _cut, address _init, bytes calldata _calldata) external;

event DiamondCut(FacetCut[] _cut, address _init, bytes _calldata);

The _init / _calldata pair is delegatecalled in the same transaction, giving the atomic upgrade-and-initialise property that upgradeToAndCall gives a single-implementation proxy.

The loupe

Because there is no single implementation to point tooling at, EIP-2535 mandates four view functions so explorers and auditors can reconstruct the diamond without replaying every DiamondCut log:

function facets() external view returns (Facet[] memory);
function facetFunctionSelectors(address _facet) external view returns (bytes4[] memory);
function facetAddresses() external view returns (address[] memory);
function facetAddress(bytes4 _selector) external view returns (address);

Storage: DiamondStorage and AppStorage

Multiple facets sharing one storage multiplies the collision problem from module 06. The two conventional answers both amount to namespacing, and both are ERC-7201 in spirit:

• DiamondStorage — each facet defines its own struct at its own hashed position, exactly as in module 11. Facets cannot corrupt each other because their roots are unrelated.
• AppStorage — one shared application struct that every facet declares as its first state variable, so it lands at slot 0 for all of them. Simpler to write and read; it forces every facet to agree on one layout, so appending fields is the only safe change.

Facets cannot call each other directly

A facet is not deployed with the diamond's storage, so calling another facet's function as an internal function would run against the wrong context. The three options:

• Self-call — IOther(address(this)).f(), which re-enters the diamond's fallback and routes correctly. Costs a full external call.
• Direct delegatecall — look the facet up and delegatecall it manually. Cheaper, more code.
• Shared internal library — duplicate the logic into both facets at compile time. No runtime cost, more bytecode.