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
```