0
# OpenZeppelin Solidity Contracts
1

2
OpenZeppelin Contracts is a comprehensive library of secure, community-vetted smart contracts for Solidity development on Ethereum. It provides battle-tested implementations of standard token contracts (ERC20, ERC721, ERC777, ERC1155), flexible role-based access control systems, reusable utility components for building custom contracts and complex decentralized systems, and Gas Station Network integration for gasless transactions.
3

4
## Package Information
5

6
- **Package Name**: @openzeppelin/contracts
7
- **Package Type**: npm
8
- **Language**: Solidity
9
- **Installation**: `npm install @openzeppelin/contracts`
10
- **Version**: 3.4.2
11

12
## Core Imports
13

14
```solidity
15
// Token contracts
16
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
17
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
18

19
// Access control
20
import "@openzeppelin/contracts/access/Ownable.sol";
21
import "@openzeppelin/contracts/access/AccessControl.sol";
22

23
// Utilities
24
import "@openzeppelin/contracts/utils/math/SafeMath.sol";
25
import "@openzeppelin/contracts/utils/Address.sol";
26
```
27

28
## Basic Usage
29

30
```solidity
31
pragma solidity ^0.8.0;
32

33
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
34
import "@openzeppelin/contracts/access/Ownable.sol";
35

36
contract MyToken is ERC20, Ownable {
37
    constructor() ERC20("MyToken", "MTK") {
38
        _mint(msg.sender, 1000000 * 10**decimals());
39
    }
40
    
41
    function mint(address to, uint256 amount) public onlyOwner {
42
        _mint(to, amount);
43
    }
44
}
45
```
46

47
## Architecture
48

49
OpenZeppelin Contracts follows several key design patterns:
50

51
- **Inheritance-based Extensions**: Most functionality is provided through contract inheritance
52
- **Interface Segregation**: Clean interfaces separated from implementations  
53
- **Library Pattern**: Mathematical and utility functions as libraries
54
- **Security First**: Built-in protection against common vulnerabilities (reentrancy, overflow, etc.)
55
- **Modular Design**: Mix-and-match functionality through multiple inheritance
56
- **Standards Compliance**: Full EIP/ERC standard implementations
57

58
## Capabilities
59

60
### Token Standards
61

62
Comprehensive implementations of Ethereum token standards with extensions for common patterns like minting, burning, and pausing.
63

64
```solidity { .api }
65
// ERC20 - Fungible Token Standard
66
interface IERC20 {
67
    function totalSupply() external view returns (uint256);
68
    function balanceOf(address account) external view returns (uint256);
69
    function transfer(address recipient, uint256 amount) external returns (bool);
70
    function allowance(address owner, address spender) external view returns (uint256);
71
    function approve(address spender, uint256 amount) external returns (bool);
72
    function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);
73
}
74

75
// ERC721 - Non-Fungible Token Standard  
76
interface IERC721 {
77
    function balanceOf(address owner) external view returns (uint256 balance);
78
    function ownerOf(uint256 tokenId) external view returns (address owner);
79
    function safeTransferFrom(address from, address to, uint256 tokenId) external;
80
    function transferFrom(address from, address to, uint256 tokenId) external;
81
    function approve(address to, uint256 tokenId) external;
82
    function getApproved(uint256 tokenId) external view returns (address operator);
83
    function setApprovalForAll(address operator, bool _approved) external;
84
    function isApprovedForAll(address owner, address operator) external view returns (bool);
85
}
86
```
87

88
[Token Standards](./token-standards.md)
89

90
### Access Control
91

92
Role-based and ownership-based access control mechanisms for managing contract permissions and administrative functions.
93

94
```solidity { .api }
95
// Simple ownership pattern
96
abstract contract Ownable {
97
    function owner() public view virtual returns (address);
98
    function renounceOwnership() public virtual;
99
    function transferOwnership(address newOwner) public virtual;
100
    modifier onlyOwner();
101
}
102

103
// Role-based access control
104
abstract contract AccessControl {
105
    function hasRole(bytes32 role, address account) public view returns (bool);
106
    function getRoleAdmin(bytes32 role) public view returns (bytes32);
107
    function grantRole(bytes32 role, address account) public virtual;
108
    function revokeRole(bytes32 role, address account) public virtual;
109
    function renounceRole(bytes32 role, address account) public virtual;
110
}
111
```
112

113
[Access Control](./access-control.md)
114

115
### Security Utilities
116

117
Mathematical operations, address utilities, and security patterns to prevent common vulnerabilities in smart contracts.
118

119
```solidity { .api }
120
// Safe mathematical operations
121
library SafeMath {
122
    function add(uint256 a, uint256 b) internal pure returns (uint256);
123
    function sub(uint256 a, uint256 b) internal pure returns (uint256);
124
    function mul(uint256 a, uint256 b) internal pure returns (uint256);
125
    function div(uint256 a, uint256 b) internal pure returns (uint256);
126
}
127

128
// Reentrancy protection
129
abstract contract ReentrancyGuard {
130
    modifier nonReentrant();
131
}
132

133
// Emergency pause functionality
134
abstract contract Pausable {
135
    function paused() public view virtual returns (bool);
136
    modifier whenNotPaused();
137
    modifier whenPaused();
138
}
139
```
140

141
[Security Utilities](./security-utilities.md)
142

143
### Proxy Patterns
144

145
Upgradeable contract patterns including transparent proxies, beacon proxies, and minimal proxies for contract upgradeability.
146

147
```solidity { .api }
148
// Base contract for upgradeable contracts
149
abstract contract Initializable {
150
    modifier initializer();
151
}
152

153
// Minimal proxy factory
154
library Clones {
155
    function clone(address implementation) internal returns (address instance);
156
    function cloneDeterministic(address implementation, bytes32 salt) internal returns (address instance);
157
    function predictDeterministicAddress(address implementation, bytes32 salt) internal view returns (address predicted);
158
}
159
```
160

161
[Proxy Patterns](./proxy-patterns.md)
162

163
### Presets
164

165
Ready-to-deploy token contracts with common configurations for rapid development and deployment.
166

167
```solidity { .api }
168
// Fixed supply ERC20 token
169
contract ERC20PresetFixedSupply is ERC20 {
170
    constructor(string memory name, string memory symbol, uint256 initialSupply, address owner);
171
}
172

173
// Mintable and pausable ERC20
174
contract ERC20PresetMinterPauser is ERC20, ERC20Burnable, ERC20Pausable, AccessControl {
175
    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
176
    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
177
}
178
```
179

180
[Contract Presets](./contract-presets.md)
181

182
### Cryptography & Math
183

184
Cryptographic utilities and mathematical libraries for signature verification, hash operations, and safe arithmetic.
185

186
```solidity { .api }
187
// ECDSA signature operations
188
library ECDSA {
189
    function recover(bytes32 hash, bytes memory signature) internal pure returns (address);
190
    function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32);
191
}
192

193
// Merkle proof verification
194
library MerkleProof {
195
    function verify(bytes32[] memory proof, bytes32 root, bytes32 leaf) internal pure returns (bool);
196
}
197
```
198

199
[Cryptography & Math](./cryptography-math.md)
200

201
### Payment Mechanisms
202

203
Secure payment splitting, pull payment patterns, and escrow mechanisms for handling payments and fund management.
204

205
```solidity { .api }
206
// Payment splitting among multiple payees
207
contract PaymentSplitter {
208
    function totalShares() external view returns (uint256);
209
    function shares(address account) external view returns (uint256);
210
    function released(address account) external view returns (uint256);
211
    function release(address payable account) external;
212
}
213

214
// Pull payment pattern for safe withdrawals
215
abstract contract PullPayment {
216
    function payments(address dest) external view returns (uint256);
217
    function withdrawPayments(address payable payee) external;
218
}
219

220
// Escrow for conditional fund release
221
contract RefundEscrow {
222
    function deposit(address refundee) external payable;
223
    function close() external;
224
    function enableRefunds() external;
225
    function beneficiaryWithdraw() external;
226
}
227
```
228

229
[Payment Mechanisms](./payment-mechanisms.md)
230

231
### GSN Support
232

233
Gas Station Network integration for enabling gasless transactions and meta-transactions.
234

235
```solidity { .api }
236
// Base GSN recipient contract
237
abstract contract GSNRecipient {
238
    function acceptRelayedCall(
239
        address relay,
240
        address from,
241
        bytes calldata encodedFunction,
242
        uint256 transactionFee,
243
        uint256 gasPrice,
244
        uint256 gasLimit,
245
        uint256 nonce,
246
        bytes calldata approvalData,
247
        uint256 maxPossibleCharge
248
    ) external view virtual returns (uint256, bytes memory);
249
    
250
    function _msgSender() internal view virtual returns (address payable);
251
    function _msgData() internal view virtual returns (bytes memory);
252
}
253

254
// Signature-based GSN authentication
255
contract GSNRecipientSignature is GSNRecipient {
256
    function getTrustedSigner() external view returns (address);
257
}
258
```
259

260
[GSN Support](./gsn-support.md)
261

262
### Introspection
263

264
Interface detection and registry patterns including ERC165 for interface introspection and ERC1820 for registry-based interface implementation discovery.
265

266
```solidity { .api }
267
// ERC165 interface detection
268
interface IERC165 {
269
    function supportsInterface(bytes4 interfaceId) external view returns (bool);
270
}
271

272
// Interface detection utilities
273
library ERC165Checker {
274
    function supportsInterface(address account, bytes4 interfaceId) internal view returns (bool);
275
    function supportsAllInterfaces(address account, bytes4[] memory interfaceIds) internal view returns (bool);
276
}
277

278
// ERC1820 registry for interface implementation discovery
279
interface IERC1820Registry {
280
    function setInterfaceImplementer(address account, bytes32 _interfaceHash, address implementer) external;
281
    function getInterfaceImplementer(address account, bytes32 _interfaceHash) external view returns (address);
282
}
283
```
284

285
[Introspection](./introspection.md)
286

287
## Types
288

289
```solidity { .api }
290
// Events common across token standards
291
event Transfer(address indexed from, address indexed to, uint256 value);
292
event Approval(address indexed owner, address indexed spender, uint256 value);
293

294
// Access control events
295
event RoleAdminChanged(bytes32 indexed role, bytes32 indexed previousAdminRole, bytes32 indexed newAdminRole);
296
event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender);
297
event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender);
298

299
// Ownership events
300
event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
301

302
// Pausable events
303
event Paused(address account);
304
event Unpaused(address account);
305
```