0
# OpenZeppelin Contracts Upgradeable
1
2
OpenZeppelin Contracts Upgradeable is a secure smart contract library for Solidity that provides upgradeable implementations of standards like ERC20 and ERC721, flexible role-based permissioning schemes, and reusable components for building custom contracts and complex decentralized systems. All contracts follow the upgradeable pattern using ERC-7201 namespaced storage and initialization functions instead of constructors.
3
4
## Package Information
5
6
- **Package Name**: @openzeppelin/contracts-upgradeable
7
- **Package Type**: npm
8
- **Language**: Solidity
9
- **Installation**: `npm install @openzeppelin/contracts-upgradeable`
10
- **Peer Dependency**: `@openzeppelin/contracts` (version 5.4.0)
11
12
## Core Imports
13
14
Standard import pattern for Solidity contracts:
15
16
```solidity
17
import {ContractNameUpgradeable} from "@openzeppelin/contracts-upgradeable/module/ContractNameUpgradeable.sol";
18
```
19
20
Common examples:
21
22
```solidity
23
import {ERC20Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
24
import {ERC721Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC721/ERC721Upgradeable.sol";
25
import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
26
import {AccessControlUpgradeable} from "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";
27
import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
28
```
29
30
## Basic Usage
31
32
All upgradeable contracts follow this initialization pattern:
33
34
```solidity
35
pragma solidity ^0.8.20;
36
37
import {ERC20Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
38
import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
39
import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
40
41
contract MyToken is Initializable, ERC20Upgradeable, OwnableUpgradeable {
42
/// @custom:oz-upgrades-unsafe-allow constructor
43
constructor() {
44
_disableInitializers();
45
}
46
47
function initialize(address initialOwner) initializer public {
48
__ERC20_init("MyToken", "MTK");
49
__Ownable_init(initialOwner);
50
}
51
52
function mint(address to, uint256 amount) public onlyOwner {
53
_mint(to, amount);
54
}
55
}
56
```
57
58
## Architecture
59
60
OpenZeppelin Contracts Upgradeable is built around several key architectural patterns:
61
62
- **Upgradeable Pattern**: Uses ERC-7201 namespaced storage to avoid storage collisions across upgrades
63
- **Initialization Pattern**: Replaces constructors with `__ContractName_init()` functions using the `initializer` modifier
64
- **Modular Design**: Contracts can be combined through inheritance to create sophisticated functionality
65
- **Security-First**: Battle-tested contracts with extensive audit history and formal verification
66
- **Compatibility**: Maintains compatibility with standard OpenZeppelin contracts while adding upgradeability
67
68
## Capabilities
69
70
### Access Control
71
72
Comprehensive permission management systems including role-based access control, ownership patterns, and advanced access management with time-based operations.
73
74
```solidity { .api }
75
// Role-based access control
76
abstract contract AccessControlUpgradeable {
77
function hasRole(bytes32 role, address account) external view returns (bool);
78
function grantRole(bytes32 role, address account) external;
79
function revokeRole(bytes32 role, address account) external;
80
}
81
82
// Simple ownership pattern
83
abstract contract OwnableUpgradeable {
84
function owner() external view returns (address);
85
function transferOwnership(address newOwner) external;
86
modifier onlyOwner();
87
}
88
```
89
90
[Access Control](./access-control.md)
91
92
### Token Standards
93
94
Complete implementations of popular token standards including ERC-20 fungible tokens, ERC-721 NFTs, ERC-1155 multi-tokens, and the draft ERC-6909 standard.
95
96
```solidity { .api }
97
// ERC-20 fungible tokens
98
contract ERC20Upgradeable {
99
function balanceOf(address account) external view returns (uint256);
100
function transfer(address to, uint256 value) external returns (bool);
101
function approve(address spender, uint256 value) external returns (bool);
102
}
103
104
// ERC-721 NFTs
105
contract ERC721Upgradeable {
106
function ownerOf(uint256 tokenId) external view returns (address);
107
function transferFrom(address from, address to, uint256 tokenId) external;
108
function approve(address to, uint256 tokenId) external;
109
}
110
111
// ERC-1155 multi-tokens
112
contract ERC1155Upgradeable {
113
function balanceOf(address account, uint256 id) external view returns (uint256);
114
function safeTransferFrom(address from, address to, uint256 id, uint256 value, bytes calldata data) external;
115
function setApprovalForAll(address operator, bool approved) external;
116
}
117
```
118
119
[Token Standards](./token-standards.md)
120
121
### Governance
122
123
Advanced DAO governance framework with flexible voting mechanisms, proposal management, timelock controllers, and vote delegation systems.
124
125
```solidity { .api }
126
// Core governance contract
127
abstract contract GovernorUpgradeable {
128
function propose(address[] calldata targets, uint256[] calldata values, bytes[] calldata calldatas, string calldata description) external returns (uint256);
129
function castVote(uint256 proposalId, uint8 support) external returns (uint256);
130
function execute(address[] calldata targets, uint256[] calldata values, bytes[] calldata calldatas, bytes32 descriptionHash) external payable returns (uint256);
131
}
132
133
// Vote delegation and tracking
134
abstract contract VotesUpgradeable {
135
function getVotes(address account) external view returns (uint256);
136
function delegate(address delegatee) external;
137
function getPastVotes(address account, uint256 timepoint) external view returns (uint256);
138
}
139
```
140
141
[Governance](./governance.md)
142
143
### Security Utilities
144
145
Essential security patterns including reentrancy guards, pausable functionality, multicall batching, and comprehensive cryptographic signature verification with modular signers supporting ECDSA, P256, RSA, and multi-signature schemes.
146
147
```solidity { .api }
148
// Reentrancy protection
149
abstract contract ReentrancyGuardUpgradeable {
150
modifier nonReentrant();
151
}
152
153
// Emergency pause functionality
154
abstract contract PausableUpgradeable {
155
function paused() external view returns (bool);
156
modifier whenNotPaused();
157
modifier whenPaused();
158
}
159
160
// Batch multiple calls
161
abstract contract MulticallUpgradeable {
162
function multicall(bytes[] calldata data) external returns (bytes[] memory results);
163
}
164
```
165
166
[Security Utilities](./security-utilities.md)
167
168
### Proxy and Upgradeability
169
170
Core upgradeability infrastructure including the Initializable base contract and UUPS upgrade pattern for implementing upgradeable smart contracts.
171
172
```solidity { .api }
173
// Initialization control
174
abstract contract Initializable {
175
modifier initializer();
176
modifier reinitializer(uint64 version);
177
modifier onlyInitializing();
178
}
179
180
// UUPS upgrade pattern
181
abstract contract UUPSUpgradeable {
182
function upgradeToAndCall(address newImplementation, bytes calldata data) external payable;
183
function proxiableUUID() external view returns (bytes32);
184
}
185
```
186
187
[Proxy and Upgradeability](./proxy-upgradeability.md)
188
189
### Finance
190
191
Financial utilities including vesting wallets with linear and cliff-based release schedules for token distribution and payment management.
192
193
```solidity { .api }
194
// Linear vesting wallet
195
contract VestingWalletUpgradeable {
196
function beneficiary() external view returns (address);
197
function start() external view returns (uint256);
198
function duration() external view returns (uint256);
199
function release() external;
200
function release(address token) external;
201
}
202
```
203
204
[Finance](./finance.md)
205
206
### Meta-Transactions
207
208
ERC-2771 meta-transaction support enabling gasless transactions through trusted forwarders and context-aware message handling.
209
210
```solidity { .api }
211
// Meta-transaction context
212
abstract contract ERC2771ContextUpgradeable {
213
function isTrustedForwarder(address forwarder) external view returns (bool);
214
function _msgSender() internal view returns (address);
215
}
216
217
// Meta-transaction forwarder
218
contract ERC2771ForwarderUpgradeable {
219
function verify(ForwardRequestData calldata request) external view returns (bool);
220
function execute(ForwardRequestData calldata request) external payable returns (bool, bytes memory);
221
}
222
```
223
224
[Meta-Transactions](./meta-transactions.md)
225
226
### Account Abstraction
227
228
Draft ERC-7579 account abstraction implementations enabling modular smart contract accounts with validator, executor, and hook support.
229
230
```solidity { .api }
231
// ERC-7579 account abstraction
232
abstract contract AccountERC7579Upgradeable {
233
function installModule(uint256 moduleTypeId, address module, bytes calldata initData) external;
234
function uninstallModule(uint256 moduleTypeId, address module, bytes calldata deinitData) external;
235
function isModuleInstalled(uint256 moduleTypeId, address module, bytes calldata additionalContext) external view returns (bool);
236
}
237
```
238
239
[Account Abstraction](./account-abstraction.md)
240
241
## Common Types
242
243
```solidity { .api }
244
// Common modifiers used across contracts
245
modifier initializer(); // Marks initialization functions
246
modifier onlyInitializing(); // Restricts to initialization phase
247
modifier reinitializer(uint64 version); // Marks re-initialization functions
248
249
// Storage pattern used by all contracts (ERC-7201)
250
bytes32 private constant StorageLocation = keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.ContractName")) - 1)) & ~bytes32(uint256(0xff));
251
252
// Common events
253
event Initialized(uint64 version);
254
```
255
256
## Initialization Pattern
257
258
All upgradeable contracts follow this standard pattern:
259
260
```solidity { .api }
261
// Internal initialization functions
262
function __ContractName_init(/* parameters */) internal onlyInitializing {
263
__ContractName_init_unchained(/* parameters */);
264
}
265
266
function __ContractName_init_unchained(/* parameters */) internal onlyInitializing {
267
// Contract-specific initialization logic
268
}
269
```
270
271
When inheriting multiple contracts, call all initializers in the correct order:
272
273
```solidity
274
function initialize(/* parameters */) initializer public {
275
__ERC20_init("TokenName", "TKN");
276
__Ownable_init(initialOwner);
277
__CustomContract_init(/* custom parameters */);
278
}
279
```