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
- Upgrade Restrictions Between Major Versions (v4 → v5)
- Writing Upgradeable Contracts
- Hardhat Upgrades Workflow
- Foundry Upgrades Workflow
- Handling Upgrade Validation Issues
- 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,
TransparentUpgradeableProxyautomatically deploys its ownProxyAdmincontract 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-deployedProxyAdmin— do not pass an existingProxyAdmincontract address here. Transfer of upgrade capability is handled exclusively throughProxyAdminownership. This differs from v4, whereProxyAdminwas 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
initializeuses theinitializermodifier - Parent init functions (
__X_init) useonlyInitializinginternally — 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.constantis safe (inlined at compile time).immutablevalues 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-immutableto 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
阅读完整来源 ↗