0
# OpenZeppelin Contracts
1

2
OpenZeppelin Contracts is a comprehensive library of secure, battle-tested smart contract components for Solidity development on Ethereum and EVM-compatible blockchains. It provides standardized implementations of industry-standard token contracts (ERC20, ERC721, ERC1155, ERC777), flexible access control mechanisms, security patterns, proxy systems for upgradeability, governance frameworks, and essential utilities for cryptographic operations and mathematical calculations.
3

4
## Package Information
5

6
- **Package Name**: openzeppelin-solidity
7
- **Package Type**: npm
8
- **Language**: Solidity, JavaScript
9
- **Installation**: `npm install openzeppelin-solidity`
10
- **Documentation**: https://docs.openzeppelin.com/contracts
11
- **Version**: 4.8.1
12

13
## Core Imports
14

15
Import contracts using Solidity import statements:
16

17
```solidity
18
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
19
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
20
import "@openzeppelin/contracts/access/Ownable.sol";
21
import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
22
```
23

24
For specific extensions:
25

26
```solidity
27
import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
28
import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Enumerable.sol";
29
import "@openzeppelin/contracts/access/AccessControl.sol";
30
```
31

32
## Basic Usage
33

34
### Simple ERC20 Token
35

36
```solidity
37
pragma solidity ^0.8.0;
38

39
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
40
import "@openzeppelin/contracts/access/Ownable.sol";
41

42
contract MyToken is ERC20, Ownable {
43
    constructor() ERC20("MyToken", "MTK") {
44
        _mint(msg.sender, 1000000 * 10**decimals());
45
    }
46

47
    function mint(address to, uint256 amount) public onlyOwner {
48
        _mint(to, amount);
49
    }
50
}
51
```
52

53
### Simple NFT Collection
54

55
```solidity
56
pragma solidity ^0.8.0;
57

58
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
59
import "@openzeppelin/contracts/access/Ownable.sol";
60
import "@openzeppelin/contracts/utils/Counters.sol";
61

62
contract MyNFT is ERC721, Ownable {
63
    using Counters for Counters.Counter;
64
    Counters.Counter private _tokenIds;
65

66
    constructor() ERC721("MyNFT", "MNFT") {}
67

68
    function mint(address recipient) public onlyOwner returns (uint256) {
69
        _tokenIds.increment();
70
        uint256 newItemId = _tokenIds.current();
71
        _safeMint(recipient, newItemId);
72
        return newItemId;
73
    }
74
}
75
```
76

77
## Architecture
78

79
OpenZeppelin Contracts follows several key design patterns:
80

81
- **Inheritance-Based Extensions**: Core implementations extended through inheritance for additional functionality
82
- **Interface Compliance**: All contracts implement standard interfaces (IERC20, IERC721, etc.)
83
- **Security First**: Every contract follows security best practices and undergoes rigorous auditing
84
- **Gas Optimization**: Implementations balance security with gas efficiency
85
- **Modular Design**: Contracts can be combined and extended for custom use cases
86
- **Role-Based Access**: Flexible access control through roles and ownership patterns
87

88
## Capabilities
89

90
### Token Standards
91

92
Complete implementations of major Ethereum token standards with extensive extensions and utilities. Includes fungible tokens (ERC20), non-fungible tokens (ERC721), multi-tokens (ERC1155), and advanced tokens (ERC777).
93

94
```solidity { .api }
95
contract ERC20 is Context, IERC20, IERC20Metadata {
96
    function name() external view returns (string memory);
97
    function symbol() external view returns (string memory);
98
    function decimals() external view returns (uint8);
99
    function totalSupply() external view returns (uint256);
100
    function balanceOf(address account) external view returns (uint256);
101
    function transfer(address to, uint256 amount) external returns (bool);
102
    function allowance(address owner, address spender) external view returns (uint256);
103
    function approve(address spender, uint256 amount) external returns (bool);
104
    function transferFrom(address from, address to, uint256 amount) external returns (bool);
105
}
106

107
contract ERC721 is Context, ERC165, IERC721, IERC721Metadata {
108
    function balanceOf(address owner) external view returns (uint256 balance);
109
    function ownerOf(uint256 tokenId) external view returns (address owner);
110
    function safeTransferFrom(address from, address to, uint256 tokenId, bytes calldata data) external;
111
    function safeTransferFrom(address from, address to, uint256 tokenId) external;
112
    function transferFrom(address from, address to, uint256 tokenId) external;
113
    function approve(address to, uint256 tokenId) external;
114
    function setApprovalForAll(address operator, bool approved) external;
115
    function getApproved(uint256 tokenId) external view returns (address operator);
116
    function isApprovedForAll(address owner, address operator) external view returns (bool);
117
}
118
```
119

120
[Token Standards](./tokens.md)
121

122
### Access Control
123

124
Role-based and ownership-based access control mechanisms for restricting function access and managing permissions in smart contracts.
125

126
```solidity { .api }
127
abstract contract AccessControl is Context, IAccessControl, ERC165 {
128
    function hasRole(bytes32 role, address account) public view virtual returns (bool);
129
    function getRoleAdmin(bytes32 role) public view virtual returns (bytes32);
130
    function grantRole(bytes32 role, address account) public virtual;
131
    function revokeRole(bytes32 role, address account) public virtual;
132
    function renounceRole(bytes32 role, address account) public virtual;
133
}
134

135
abstract contract Ownable is Context {
136
    function owner() public view virtual returns (address);
137
    function renounceOwnership() public virtual onlyOwner;
138
    function transferOwnership(address newOwner) public virtual onlyOwner;
139
}
140
```
141

142
[Access Control](./access-control.md)
143

144
### Security Patterns
145

146
Security mechanisms including reentrancy protection, pausable contracts, and pull payment patterns to prevent common smart contract vulnerabilities.
147

148
```solidity { .api }
149
abstract contract ReentrancyGuard {
150
    modifier nonReentrant();
151
}
152

153
abstract contract Pausable is Context {
154
    function paused() public view virtual returns (bool);
155
    modifier whenNotPaused();
156
    modifier whenPaused();
157
}
158
```
159

160
[Security Patterns](./security.md)
161

162
### Proxy Patterns
163

164
Upgradeable contract patterns and proxy utilities for creating flexible, maintainable smart contract systems.
165

166
```solidity { .api }
167
library Clones {
168
    function clone(address implementation) internal returns (address instance);
169
    function cloneDeterministic(address implementation, bytes32 salt) internal returns (address instance);
170
    function predictDeterministicAddress(address implementation, bytes32 salt, address deployer) internal pure returns (address predicted);
171
}
172

173
abstract contract Proxy {
174
    function _delegate(address implementation) internal virtual;
175
    function _implementation() internal view virtual returns (address);
176
    function _fallback() internal virtual;
177
}
178
```
179

180
[Proxy Patterns](./proxy.md)
181

182
### Governance
183

184
On-chain governance systems with voting mechanisms, proposal management, and timelock controllers for decentralized decision making.
185

186
```solidity { .api }
187
abstract contract Governor is Context, ERC165, EIP712, IGovernor {
188
    function name() public view virtual returns (string memory);
189
    function version() public view virtual returns (string memory);
190
    function hashProposal(address[] memory targets, uint256[] memory values, bytes[] memory calldatas, bytes32 descriptionHash) public pure virtual returns (uint256);
191
    function state(uint256 proposalId) public view virtual returns (ProposalState);
192
    function propose(address[] memory targets, uint256[] memory values, bytes[] memory calldatas, string memory description) public virtual returns (uint256);
193
    function execute(address[] memory targets, uint256[] memory values, bytes[] memory calldatas, bytes32 descriptionHash) public payable virtual returns (uint256);
194
    function castVote(uint256 proposalId, uint8 support) public virtual returns (uint256);
195
}
196

197
contract TimelockController is AccessControl {
198
    function isOperation(bytes32 id) public view virtual returns (bool registered);
199
    function isOperationPending(bytes32 id) public view virtual returns (bool pending);
200
    function isOperationReady(bytes32 id) public view virtual returns (bool ready);
201
    function isOperationDone(bytes32 id) public view virtual returns (bool done);
202
    function getTimestamp(bytes32 id) public view virtual returns (uint256 timestamp);
203
    function getMinDelay() public view virtual returns (uint256 duration);
204
    function schedule(address target, uint256 value, bytes calldata data, bytes32 predecessor, bytes32 salt, uint256 delay) public virtual;
205
    function execute(address target, uint256 value, bytes calldata data, bytes32 predecessor, bytes32 salt) public payable virtual;
206
}
207
```
208

209
[Governance](./governance.md)
210

211
### Utility Functions
212

213
Common utility functions including mathematical operations, cryptographic utilities, data structures, and helper functions for smart contract development.
214

215
```solidity { .api }
216
library Math {
217
    function max(uint256 a, uint256 b) internal pure returns (uint256);
218
    function min(uint256 a, uint256 b) internal pure returns (uint256);
219
    function average(uint256 a, uint256 b) internal pure returns (uint256);
220
    function ceilDiv(uint256 a, uint256 b) internal pure returns (uint256);
221
    function mulDiv(uint256 x, uint256 y, uint256 denominator) internal pure returns (uint256 result);
222
    function sqrt(uint256 a) internal pure returns (uint256);
223
}
224

225
library ECDSA {
226
    function recover(bytes32 hash, bytes memory signature) internal pure returns (address);
227
    function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32);
228
    function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32);
229
}
230

231
library Address {
232
    function isContract(address account) internal view returns (bool);
233
    function sendValue(address payable recipient, uint256 amount) internal;
234
    function functionCall(address target, bytes memory data) internal returns (bytes memory);
235
}
236
```
237

238
[Utilities](./utilities.md)
239

240
### Financial Primitives
241

242
Payment splitting, vesting schedules, and other financial mechanisms for handling cryptocurrency payments and distributions.
243

244
```solidity { .api }
245
contract PaymentSplitter is Context {
246
    function totalShares() public view returns (uint256);
247
    function totalReleased() public view returns (uint256);
248
    function shares(address account) public view returns (uint256);
249
    function released(address account) public view returns (uint256);
250
    function payee(uint256 index) public view returns (address);
251
    function release(address payable account) public virtual;
252
}
253

254
contract VestingWallet is Context {
255
    function beneficiary() public view virtual returns (address);
256
    function start() public view virtual returns (uint256);
257
    function duration() public view virtual returns (uint256);
258
    function released() public view virtual returns (uint256);
259
    function releasable() public view virtual returns (uint256);
260
    function release() public virtual;
261
}
262
```
263

264
[Financial Primitives](./finance.md)
265

266
### Meta-Transactions
267

268
ERC2771 meta-transaction support for gasless transactions and improved user experience in decentralized applications.
269

270
```solidity { .api }
271
abstract contract ERC2771Context is Context {
272
    function isTrustedForwarder(address forwarder) public view virtual returns (bool);
273
    function _msgSender() internal view virtual override returns (address sender);
274
    function _msgData() internal view virtual override returns (bytes calldata);
275
}
276

277
contract MinimalForwarder is EIP712 {
278
    struct ForwardRequest {
279
        address from;
280
        address to;
281
        uint256 value;
282
        uint256 gas;
283
        uint256 nonce;
284
        bytes data;
285
    }
286
    
287
    function getNonce(address from) public view returns (uint256);
288
    function verify(ForwardRequest calldata req, bytes calldata signature) public view returns (bool);
289
    function execute(ForwardRequest calldata req, bytes calldata signature) public payable returns (bool, bytes memory);
290
}
291
```
292

293
[Meta-Transactions](./metatx.md)
294

295
### Cross-Chain Integration
296

297
Cross-chain messaging utilities for communicating across different blockchain networks, supporting Layer 2 solutions and bridge protocols.
298

299
```solidity { .api }
300
abstract contract CrossChainEnabled {
301
    function _isCrossChain() internal view virtual returns (bool);
302
    function _crossChainSender() internal view virtual returns (address);
303
}
304

305
abstract contract CrossChainEnabledOptimism is CrossChainEnabled {
306
    constructor(address crossChainMessenger);
307
    function crossChainMessenger() public view virtual returns (address);
308
}
309

310
abstract contract CrossChainEnabledArbitrumL1 is CrossChainEnabled {
311
    constructor(address bridge);
312
    function bridge() public view virtual returns (address);
313
}
314
```
315

316
[Cross-Chain Integration](./crosschain.md)