Quest 10

Upgradeable contracts — proxy pattern

Contract code is immutable once deployed. But if you MUST ship a bugfix, the proxy pattern gives you a way.

Lesson

The problem

You deploy V1. Users put $100M in. You find a bug. You can't edit V1. Options:

1. Live with the bug (bad) 2. Migrate all $100M to a fresh V2 (expensive, trust-breaking) 3. Use a proxy so you can point all the money at new code

How a proxy works

Two contracts:

Proxy — has the storage, holds the funds, immutable
Implementation (V1, V2, ...) — has the logic

User calls proxy.doThing(). Proxy's fallback() uses delegatecall to invoke V1's code — but the storage reads/writes happen in Proxy's slots. When you upgrade, you deploy V2 and point the proxy at it. Storage stays intact.

solidity
// simplified proxy
contract Proxy {
    address public implementation;
    address public admin;

    fallback() external payable {
        assembly {
            let impl := sload(0)  // implementation slot
            calldatacopy(0, 0, calldatasize())
            let result := delegatecall(gas(), impl, 0, calldatasize(), 0, 0)
            returndatacopy(0, 0, returndatasize())
            switch result
            case 0 { revert(0, returndatasize()) }
            default { return(0, returndatasize()) }
        }
    }

    function upgradeTo(address newImpl) public {
        require(msg.sender == admin);
        implementation = newImpl;
    }
}

Gotchas

Storage layout must be append-only. V2 must declare variables in the SAME order as V1, only adding new ones at the end.
No constructors. Initialization happens in an initialize() function that can only be called once (OZ's Initializable modifier).
Selector collisions. Proxy admin functions must not collide with impl function signatures. OZ's "transparent proxy" pattern solves this.

OpenZeppelin upgradeable contracts

bash
npm install --save-dev @openzeppelin/hardhat-upgrades
npm install @openzeppelin/contracts-upgradeable

solidity
import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract MyTokenV1 is Initializable, ERC20Upgradeable, OwnableUpgradeable {
    function initialize(address owner_) public initializer {
        __ERC20_init("MyToken", "MTK");
        __Ownable_init(owner_);
        _mint(owner_, 1_000_000 * 10**18);
    }
}

Deploy with OZ's upgrades plugin:

typescript
import { upgrades, ethers } from "hardhat";
const Factory = await ethers.getContractFactory("MyTokenV1");
const instance = await upgrades.deployProxy(Factory, [deployer.address]);

Your task (quiz)

Answer on upgrade safety.

References

Quiz

Q1. Why does an upgradeable contract use `initialize()` instead of a constructor?

Constructors are not supported in Solidity 0.8The proxy contract has no way to invoke the implementation's constructor, so init logic must live in a regular function that's called once after deploymentConstructors can't take argumentsIt's faster

Q2. In V2 you want to add a new state variable. Where do you declare it?

At the top of the variable list, so it's the first storage slotAfter all the V1 variables, in the same order V1 had themAnywhere — Solidity will handle the layoutIn a separate contract

solidity

// simplified proxy contract Proxy { address public implementation; address public admin; fallback() external payable { assembly { let impl := sload(0) // implementation slot calldatacopy(0, 0, calldatasize()) let result := delegatecall(gas(), impl, 0, calldatasize(), 0, 0) returndatacopy(0, 0, returndatasize()) switch result case 0 { revert(0, returndatasize()) } default { return(0, returndatasize()) } } } function upgradeTo(address newImpl) public { require(msg.sender == admin); implementation = newImpl; } }

solidity

import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol"; import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol"; import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol"; contract MyTokenV1 is Initializable, ERC20Upgradeable, OwnableUpgradeable { function initialize(address owner_) public initializer { __ERC20_init("MyToken", "MTK"); __Ownable_init(owner_); _mint(owner_, 1_000_000 * 10**18); } }