upgrade-solidity-contracts

Name: upgrade-solidity-contracts
Author: OpenZeppelin

200stars27forks

How to install upgrade-solidity-contracts?

openzeppelin/openzeppelin-skills/upgrade-solidity-contracts

$npx -y skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts

Installs into the current project.

Summary

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 st

Files · 1

View on GitHub

SKILL.md

1	# Solidity Upgrades
2
3	## Contents
4
5	- [Proxy Patterns Overview](#proxy-patterns-overview)
6	- [Upgrade Restrictions Between Major Versions (v4 → v5)](#upgrade-restrictions-between-major-versions-v4--v5)
7	- [Writing Upgradeable Contracts](#writing-upgradeable-contracts)
8	- [Hardhat Upgrades Workflow](#hardhat-upgrades-workflow)
9	- [Foundry Upgrades Workflow](#foundry-upgrades-workflow)
10	- [Handling Upgrade Validation Issues](#handling-upgrade-validation-issues)
11	- [Upgrade Safety Checklist](#upgrade-safety-checklist)
12
13	## Proxy Patterns Overview
14
15	\| Pattern \| Upgrade logic lives in \| Best for \|
16	\|---------\|----------------------\|----------\|
17	\| UUPS (`UUPSUpgradeable`) \| Implementation contract (override `_authorizeUpgrade`) \| Most projects — lighter proxy, lower deploy gas \|
18	\| Transparent \| Separate `ProxyAdmin` contract \| When admin/user call separation is critical — admin cannot accidentally call implementation functions \|
19	\| Beacon \| Shared beacon contract \| Multiple proxies sharing one implementation — upgrading the beacon atomically upgrades all proxies \|
20
21	All three use EIP-1967 storage slots for the implementation address, admin, and beacon.
22
23	> 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.
24
25	## Upgrade Restrictions Between Major Versions (v4 → v5)
26
27	Upgrading a proxy's implementation from one using OpenZeppelin Contracts v4 to one using v5 is not supported.
28
29	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.
30
31	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.
32
33	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.
34
35	## Writing Upgradeable Contracts
36
37	### Use initializers instead of constructors
38
39	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:
40
41	```solidity
42	import {Initializable} from "@openzeppelin/contracts/proxy/utils/Initializable.sol";
43
44	contract MyToken is Initializable, ERC20Upgradeable, OwnableUpgradeable {
45	/// @custom:oz-upgrades-unsafe-allow constructor
46	constructor() {
47	_disableInitializers(); // lock the implementation
48	}
49
50	function initialize(address initialOwner) public initializer {
51	__ERC20_init("MyToken", "MTK");
52	__Ownable_init(initialOwner);
53	}
54	}
55	```
56
57	Key rules:
58	- Top-level `initialize` uses the `initializer` modifier
59	- Parent init functions (`__X_init`) use `onlyInitializing` internally — call them explicitly, the compiler does not auto-linearize initializers like constructors
60	- Always call `_disableInitializers()` in a constructor to prevent attackers from initializing the implementation directly
61	- 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
62
63	### Use the upgradeable package
64
65	Import from `@openzeppelin/contracts-upgradeable` for base contracts (e.g., `ERC20Upgradeable`, `OwnableUpgradeable`). Import interfaces and l

People who liked this also viewed

6 picks

Type

upgrade-solidity-contracts

200stars27forks

View on GitHub

How to install upgrade-solidity-contracts?

openzeppelin/openzeppelin-skills/upgrade-solidity-contracts

$npx -y skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Solidity Upgrades
2
3	## Contents
4
5	- [Proxy Patterns Overview](#proxy-patterns-overview)
6	- [Upgrade Restrictions Between Major Versions (v4 → v5)](#upgrade-restrictions-between-major-versions-v4--v5)
7	- [Writing Upgradeable Contracts](#writing-upgradeable-contracts)
8	- [Hardhat Upgrades Workflow](#hardhat-upgrades-workflow)
9	- [Foundry Upgrades Workflow](#foundry-upgrades-workflow)
10	- [Handling Upgrade Validation Issues](#handling-upgrade-validation-issues)
11	- [Upgrade Safety Checklist](#upgrade-safety-checklist)
12
13	## Proxy Patterns Overview
14
15	\| Pattern \| Upgrade logic lives in \| Best for \|
16	\|---------\|----------------------\|----------\|
17	\| UUPS (`UUPSUpgradeable`) \| Implementation contract (override `_authorizeUpgrade`) \| Most projects — lighter proxy, lower deploy gas \|
18	\| Transparent \| Separate `ProxyAdmin` contract \| When admin/user call separation is critical — admin cannot accidentally call implementation functions \|
19	\| Beacon \| Shared beacon contract \| Multiple proxies sharing one implementation — upgrading the beacon atomically upgrades all proxies \|
20
21	All three use EIP-1967 storage slots for the implementation address, admin, and beacon.
22
23	> 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.
24
25	## Upgrade Restrictions Between Major Versions (v4 → v5)
26
27	Upgrading a proxy's implementation from one using OpenZeppelin Contracts v4 to one using v5 is not supported.
28
29	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.
30
31	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.
32
33	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.
34
35	## Writing Upgradeable Contracts
36
37	### Use initializers instead of constructors
38
39	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:
40
41	```solidity
42	import {Initializable} from "@openzeppelin/contracts/proxy/utils/Initializable.sol";
43
44	contract MyToken is Initializable, ERC20Upgradeable, OwnableUpgradeable {
45	/// @custom:oz-upgrades-unsafe-allow constructor
46	constructor() {
47	_disableInitializers(); // lock the implementation
48	}
49
50	function initialize(address initialOwner) public initializer {
51	__ERC20_init("MyToken", "MTK");
52	__Ownable_init(initialOwner);
53	}
54	}
55	```
56
57	Key rules:
58	- Top-level `initialize` uses the `initializer` modifier
59	- Parent init functions (`__X_init`) use `onlyInitializing` internally — call them explicitly, the compiler does not auto-linearize initializers like constructors
60	- Always call `_disableInitializers()` in a constructor to prevent attackers from initializing the implementation directly
61	- 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
62
63	### Use the upgradeable package
64
65	Import from `@openzeppelin/contracts-upgradeable` for base contracts (e.g., `ERC20Upgradeable`, `OwnableUpgradeable`). Import interfaces and l

People who liked this also viewed

6 picks

Type