/upgrade-solidity-contracts

name: upgrade-solidity-contracts
description: "Upgrade Solidity smart contracts using OpenZeppelin proxy patterns. Use when users need to: (1) make contracts upgradeable with UUPS, Transparent, or Beacon proxies, (2) write initializers instead of constructors, (3) use the Hardhat or Foundry upgrades plugins, (4) understand storage layout rules and ERC-7201 namespaced storage, (5) validate upgrade safety, (6) manage proxy deployments and upgrades, or (7) understand upgrade restrictions between OpenZeppelin Contracts major versions."
license: AGPL-3.0-only
metadata:
  author: OpenZeppelin

Solidity Upgrades

Contents

• [Proxy Patterns Overview](#proxy-patterns-overview)
• [Upgrade Restrictions Between Major Versions (v4 → v5)](#upgrade-restrictions-between-major-versions-v4--v5)
• [Writing Upgradeable Contracts](#writing-upgradeable-contracts)
• [Hardhat Upgrades Workflow](#hardhat-upgrades-workflow)
• [Foundry Upgrades Workflow](#foundry-upgrades-workflow)
• [Handling Upgrade Validation Issues](#handling-upgrade-validation-issues)
• [Upgrade Safety Checklist](#upgrade-safety-checklist)

Proxy Patterns Overview

| Pattern | Upgrade logic lives in | Best for | |---------|----------------------|----------| | **UUPS** (`UUPSUpgradeable`) | Implementation contract (override `_authorizeUpgrade`) | Most projects — lighter proxy, lower deploy gas | | **Transparent** | Separate `ProxyAdmin` contract | When admin/user call separation is critical — admin cannot accidentally call implementation functions | | **Beacon** | Shared beacon contract | Multiple proxies sharing one implementation — upgrading the beacon atomically upgrades all proxies |

All three use EIP-1967 storage slots for the implementation address, admin, and beacon.

> **Transparent proxy — v5 constructor change:** In v5, `TransparentUpgradeableProxy` automatically deploys its own `ProxyAdmin` contract and stores the admin address in an immutable variable (set at construction time, never changeable). The second constructor parameter is the **owner address** for that auto-deployed `ProxyAdmin` — do **not** pass an existing `ProxyAdmin` contract address here. Transfer of upgrade capability is handled exclusively through `ProxyAdmin` ownership. This differs from v4, where `ProxyAdmin` was deployed separately and its address was passed to the proxy constructor.

Upgrade Restrictions Between Major Versions (v4 → v5)

**Upgrading a proxy's implementation from one using OpenZeppelin Contracts v4 to one using v5 is not supported.**

v4 uses sequential storage (slots in declaration order); v5 uses namespaced storage (ERC-7201, structs at deterministic slots). A v5 implementation cannot safely read state written by a v4 implementation. Manual data migration is theoretically possible but often infeasible — `mapping` entries cannot be enumerated, so values written under arbitrary keys cannot be relocated.

**Recommended approach:** Deploy new proxies with v5 implementations and migrate users to the new address — do not upgrade proxies that currently point to v4 implementations.

**Updating your codebase to v5 is encouraged.** The restriction above applies only to already-deployed proxies. New deployments built on v5, and upgrades within the same major version, are fully supported.

Writing Upgradeable Contracts

Use initializers instead of constructors

Proxy contracts delegatecall into the implementation. Constructors run only when the implementation itself is deployed, not when a proxy is created. Replace constructors with initializer functions:

import {Initializable} from "@openzeppelin/contracts/proxy/utils/Initializable.sol";

contract MyToken is Initializable, ERC20Upgradeable, OwnableUpgradeable {
    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() {
        _disableInitializers(); // lock the implementation
    }

    function initialize(address initialOwner) public initializer {
        __ERC20_init("MyToken", "MTK");
        __Ownable_init(initialOwner);
    }
}

Key rules:

• Top-level `initialize` uses the `initializer` modifier
• Parent init functions (`__X_init`) use `onlyInitializing` internally — call them explicitly, the compiler does not auto-linearize initializers like constructors
• Always call `_disableInitializers()` in a constructor to prevent attackers from initializing the implementation directly
• Do not set initial values in field declarations (e.g., `uint256 x = 42`) — these compile into the constructor and won't execute for the proxy. `constant` is safe (inlined at compile time). `immutable` values are stored in bytecode and shared across all proxies — the plugins flag them as unsafe by default; use `/// @custom:oz-upgrades-unsafe-allow state-variable-immutable` to opt in when a shared value is intended

Use the upgradeable package

Import from `@openzeppelin/contracts-upgradeable` for base contracts (e.g., `ERC20Upgradeable`, `OwnableUpgradeable`). Import interfaces and libraries from `@openzeppelin/contracts`. In v5.5+, `Initializable` and `UUPSUpgradeable` should also be imported directly from `@openzeppelin/contracts` — aliases in the upgradeable package will be removed in the next major release.

Storage layout rules

When upgrading, the new implementation must be storage-compatible with the old one:

• **Never** reorder, remove, or change the type of existing state variables
• **Never** insert new variables before existing ones
• **Only** append new variables at the end
• **Never** change the inheritance order of base contracts

Namespaced storage (ERC-7201)

The modern approach — all `@openzeppelin/contracts-upgradeable` contracts (v5+) use this. State variables are grouped into a struct at a deterministic storage slot, isolating each contract's storage and eliminating the need for storage gaps. Recommended for all contracts that may be imported as base contracts.

/// @custom:storage-location erc7201:example.main
struct MainS