跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
效率与协作

upgrade-solidity-contracts

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.

OpenZeppelin · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add OpenZeppelin/openzeppelin-skills --skill 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

PatternUpgrade logic lives inBest for
UUPS (UUPSUpgradeable)Implementation contract (override _authorizeUpgrade)Most projects — lighter proxy, lower deploy gas
TransparentSeparate ProxyAdmin contractWhen admin/user call separation is critical — admin cannot accidentally call implementation functions
BeaconShared beacon contractMultiple 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
阅读完整来源 ↗