Upgradeable Contracts skill for Codex

An upgrade is safe when the new implementation’s storage layout is a strict extension of the old one, every initializer can run exactly once, the implementation itself cannot be initialized or hijacked, the upgrade is validated by tooling and rehearsed on a fork, and upgrade rights sit behind a multisig and, for value-holding systems, a timelock.

First question: should it be upgradeable at all?

Situation	Recommendation
Simple token or NFT with fixed rules	Immutable. Upgradeability adds trust assumptions users must accept
Protocol in early iteration with value at stake	Upgradeable, behind multisig + timelock, with a plan to reduce or renounce later
Many identical instances (vaults, pools)	Beacon proxy, or immutable clones with a migration path
Need to swap one strategy or module	Immutable core plus a settable module address (with timelock)
Contract over the 24 KB size limit	Split into libraries or modules first; a diamond (EIP-2535) only as a last resort

Proxy pattern choice

Pattern	Upgrade logic lives in	Pros	Cons
UUPS (default)	Implementation (_authorizeUpgrade)	Cheaper calls, one contract to deploy per proxy	A V2 without UUPSUpgradeable bricks upgrades forever
Transparent	Proxy + ProxyAdmin (auto-created in OZ 5.x)	Upgrade logic cannot be forgotten in V2	Extra admin contract, slightly more gas
Beacon	Beacon contract shared by many proxies	Upgrade N proxies in one tx	All instances change together

Inspect first

1. Read AGENTS.md, foundry.toml or Hardhat config, and installed OZ packages: @openzeppelin/contracts-upgradeable must be the same major and minor as @openzeppelin/contracts.
2. For an existing deployment, collect: proxy address, current implementation (cast implementation <proxy> or read the ERC-1967 slot), admin/owner, the exact source and compiler settings of the current implementation (verified source on the explorer).
3. Find the previous deployment’s build info or the V1 source at its release tag. Layout comparisons need the deployed version, not whatever V1 looks like on main today.

Writing an upgradeable contract (OZ 5.x, UUPS)

// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import {Ownable2StepUpgradeable} from "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";

contract VaultV1 is Initializable, Ownable2StepUpgradeable, UUPSUpgradeable {
    /// @custom:storage-location erc7201:example.vault
    struct VaultStorage {
        mapping(address => uint256) balanceOf;
        uint256 totalDeposits;
    }

    // keccak256(abi.encode(uint256(keccak256("example.vault")) - 1)) & ~bytes32(uint256(0xff))
    bytes32 private constant VAULT_STORAGE = 0x...; // compute once and paste; test it

    function _s() private pure returns (VaultStorage storage $) {
        assembly { $.slot := VAULT_STORAGE }
    }

    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() { _disableInitializers(); }

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

    function _authorizeUpgrade(address) internal override onlyOwner {}
}

• constructor() { _disableInitializers(); } stops anyone initializing the implementation contract directly.
• No constructors with logic, no immutable state that differs per proxy, no initial values on state variable declarations (they run in the implementation’s constructor, not the proxy).
• Use ERC-7201 namespaced storage for your own state (as OZ 5.x does internally). It removes the need for __gap arrays and makes adding fields safe within the struct (append only).
• Add a test asserting the constant equals the formula, so a typo cannot land storage at a random slot.

Writing V2

/// @custom:oz-upgrades-from VaultV1
contract VaultV2 is Initializable, Ownable2StepUpgradeable, UUPSUpgradeable {
    /// @custom:storage-location erc7201:example.vault
    struct VaultStorage {
        mapping(address => uint256) balanceOf;
        uint256 totalDeposits;
        uint256 withdrawFeeBps;     // appended: safe
    }
    // ... same slot constant and accessor ...

    function initializeV2(uint256 feeBps) external reinitializer(2) onlyOwner {
        _s().withdrawFeeBps = feeBps;
    }
}

Storage rules, for linear and namespaced layouts alike:

• Never remove, reorder or change the type of an existing variable or struct field.
• Only append new variables at the end (or at the end of the namespaced struct).
• Never change the inheritance order of contracts that hold linear storage.
• Renaming is layout-safe but confuses everyone; avoid it.
• Keep UUPSUpgradeable and _authorizeUpgrade in every UUPS version.

Validate before every upgrade

Primary check with OpenZeppelin tooling:

• Foundry: openzeppelin-foundry-upgrades (Upgrades.validateUpgrade("VaultV2.sol", opts), Upgrades.upgradeProxy(proxy, "VaultV2.sol", data)). It requires in foundry.toml: ffi = true, ast = true, build_info = true, extra_output = ["storageLayout"], and a forge clean before running. It shells out to the @openzeppelin/upgrades-core CLI via npx, which needs network the first time.
• Hardhat: @openzeppelin/hardhat-upgrades (upgrades.validateUpgrade, upgrades.upgradeProxy). Check that the plugin version supports your Hardhat major.

Independent check for linear storage (catches inserted, moved and retyped variables, and gap misuse):

forge inspect src/VaultV1.sol:VaultV1 storageLayout --json > old.json
forge inspect src/VaultV2.sol:VaultV2 storageLayout --json > new.json
python3 scripts/storage_layout_diff.py old.json new.json   # exit 1 = incompatible

Namespaced (ERC-7201) structs do not appear in that output; rely on the OZ validator plus a fork test for them.

Fork rehearsal

function test_UpgradeToV2_PreservesState() public {
    vm.createSelectFork(vm.rpcUrl("mainnet"), FORK_BLOCK);
    VaultV1 proxy = VaultV1(PROXY);
    uint256 before = proxy.balanceOf(KNOWN_USER);

    address owner = proxy.owner();
    VaultV2 impl = new VaultV2();
    vm.prank(owner);
    proxy.upgradeToAndCall(address(impl), abi.encodeCall(VaultV2.initializeV2, (30)));

    assertEq(VaultV2(PROXY).balanceOf(KNOWN_USER), before, "state survived");
    assertEq(VaultV2(PROXY).withdrawFeeBps(), 30);
    vm.prank(owner);                                  // even the owner cannot re-run it
    vm.expectRevert(Initializable.InvalidInitialization.selector);
    VaultV2(PROXY).initializeV2(50);
}

In OZ 5.x, UUPS proxies only expose upgradeToAndCall (pass empty bytes for no call).

Executing an upgrade

- [ ] 1. OZ validation passes; storage diff clean; full test suite green on V2
- [ ] 2. Fork rehearsal against the live proxy at a recent block passes
- [ ] 3. Deploy the new implementation; verify its source on the explorer
- [ ] 4. Prepare the upgrade call (upgradeToAndCall with reinitializer data) as a Safe
        transaction or timelock proposal; record calldata in the repo
- [ ] 5. User confirms network, proxy, new implementation address and calldata
- [ ] 6. Signers execute; after the timelock delay, execute
- [ ] 7. Post-checks: implementation slot updated, key state reads unchanged, events emitted

Never execute steps 3 to 6 on mainnet without explicit user confirmation at each step. Deploying the implementation is harmless; the upgrade transaction is not.

Governance of upgrade rights

• Owner or admin is a multisig (Safe), never a deployer EOA after launch.
• Value-holding systems put a TimelockController between the multisig and the proxy so users can exit before an upgrade they disagree with lands.
• Document the upgrade authority in the README and docs; users and auditors will ask.

Gotchas

• A forgotten initialize call after deploying a proxy lets anyone initialize it and take ownership. Deploy and initialize in the same transaction (pass init data to the proxy constructor or use the upgrades plugin).
• selfdestruct or delegatecall to arbitrary addresses in an implementation can brick every proxy that uses it.
• Upgrading from OZ 4.x to 5.x in place is not supported: 5.x moved to namespaced storage, so the layout is incompatible.
• Changing compiler optimizer settings changes bytecode but not layout; still validate.
• immutable variables live in the implementation bytecode: every proxy sees the same value. Allowed only for values that are truly global, with the unsafe-allow annotation.