Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
@openzeppelin/contracts-upgradeable
Advanced tools
@openzeppelin/contracts-upgradeable is a library for secure smart contract development. It provides reusable and upgradeable smart contract components that follow best practices in security and gas efficiency. The package is particularly useful for creating upgradeable smart contracts, which can be modified after deployment without changing their address.
Upgradeable Contracts
This feature allows you to create upgradeable contracts using the Initializable base contract. The `initialize` function is used instead of a constructor to set initial values.
```json
{
"code": "import { Initializable } from '@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol';\n\ncontract MyContract is Initializable {\n uint256 public value;\n\n function initialize(uint256 _value) public initializer {\n value = _value;\n }\n}"}
```
Access Control
This feature provides role-based access control mechanisms. The `AccessControlUpgradeable` contract allows you to define roles and restrict access to certain functions based on these roles.
```json
{
"code": "import { AccessControlUpgradeable } from '@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol';\n\ncontract MyAccessControl is Initializable, AccessControlUpgradeable {\n bytes32 public constant ADMIN_ROLE = keccak256('ADMIN_ROLE');\n\n function initialize(address admin) public initializer {\n _setupRole(ADMIN_ROLE, admin);\n }\n}"}
```
ERC20 Token
This feature allows you to create upgradeable ERC20 tokens. The `ERC20Upgradeable` contract provides the standard ERC20 functionality, and the `initialize` function sets the token's name and symbol.
```json
{
"code": "import { ERC20Upgradeable } from '@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol';\n\ncontract MyToken is Initializable, ERC20Upgradeable {\n function initialize(string memory name, string memory symbol) public initializer {\n __ERC20_init(name, symbol);\n }\n}"}
```
zos-lib is a library for writing upgradeable smart contracts. It provides similar functionalities to @openzeppelin/contracts-upgradeable, including initializable contracts and upgradeable proxies. However, it is less actively maintained compared to @openzeppelin/contracts-upgradeable.
Truffle is a development environment, testing framework, and asset pipeline for Ethereum. While it does not focus solely on upgradeable contracts, it provides tools for managing smart contract development and deployment, including migrations which can be used to handle upgrades.
Hardhat is a development environment for Ethereum software. It offers a flexible and extensible way to manage smart contract development and testing. While it does not provide built-in support for upgradeable contracts, it can be used in conjunction with other libraries like @openzeppelin/contracts-upgradeable to achieve similar functionality.
A library for secure smart contract development. Build on a solid foundation of community-vetted code.
:mage: Not sure how to get started? Check out Contracts Wizard — an interactive smart contract generator.
:building_construction: Want to scale your decentralized application? Check out OpenZeppelin Defender — a secure platform for automating and monitoring your operations.
[!IMPORTANT] OpenZeppelin Contracts uses semantic versioning to communicate backwards compatibility of its API and storage layout. For upgradeable contracts, the storage layout of different major versions should be assumed incompatible, for example, it is unsafe to upgrade from 4.9.3 to 5.0.0. Learn more at Backwards Compatibility.
+> [!NOTE] +> You are looking at the upgradeable variant of OpenZeppelin Contracts. Be sure to review the documentation on Using OpenZeppelin Contracts with Upgrades. +
$ npm install @openzeppelin/contracts-upgradeable
[!WARNING] When installing via git, it is a common error to use the
master
branch. This is a development branch that should be avoided in favor of tagged releases. The release process involves security measures that themaster
branch does not guarantee.
[!WARNING] Foundry installs the latest version initially, but subsequent
forge update
commands will use themaster
branch.
$ forge install OpenZeppelin/openzeppelin-contracts-upgradeable
Add @openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/
in remappings.txt.
Once installed, you can use the contracts in the library by importing them:
pragma solidity ^0.8.20;
import {ERC721Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC721/ERC721Upgradeable.sol";
contract MyCollectible is ERC721Upgradeable {
function initialize() initializer public {
__ERC721_init("MyCollectible", "MCO");
}
}
If you're new to smart contract development, head to Developing Smart Contracts to learn about creating a new project and compiling your contracts.
To keep your system secure, you should always use the installed code as-is, and neither copy-paste it from online sources nor modify it yourself. The library is designed so that only the contracts and functions you use are deployed, so you don't need to worry about it needlessly increasing gas costs.
The guides in the documentation site will teach about different concepts, and how to use the related contracts that OpenZeppelin Contracts provides:
The full API is also thoroughly documented, and serves as a great reference when developing your smart contract application. You can also ask for help or follow Contracts's development in the community forum.
Finally, you may want to take a look at the guides on our blog, which cover several common use cases and good practices. The following articles provide great background reading, though please note that some of the referenced tools have changed, as the tooling in the ecosystem continues to rapidly evolve.
This project is maintained by OpenZeppelin with the goal of providing a secure and reliable library of smart contract components for the ecosystem. We address security through risk management in various areas such as engineering and open source best practices, scoping and API design, multi-layered review processes, and incident response preparedness.
The OpenZeppelin Contracts Security Center contains more details about the secure development process.
The security policy is detailed in SECURITY.md
as well, and specifies how you can report security vulnerabilities, which versions will receive security patches, and how to stay informed about them. We run a bug bounty program on Immunefi to reward the responsible disclosure of vulnerabilities.
The engineering guidelines we follow to promote project quality can be found in GUIDELINES.md
.
Past audits can be found in audits/
.
Smart contracts are a nascent technology and carry a high level of technical risk and uncertainty. Although OpenZeppelin is well known for its security audits, using OpenZeppelin Contracts is not a substitute for a security audit.
OpenZeppelin Contracts is made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. As set out further in the Terms, you acknowledge that you are solely responsible for any use of OpenZeppelin Contracts and you assume all risks associated with any such use.
OpenZeppelin Contracts exists thanks to its contributors. There are many ways you can participate and help build high quality software. Check out the contribution guide!
OpenZeppelin Contracts is released under the MIT License.
Your use of this Project is governed by the terms found at www.openzeppelin.com/tos (the "Terms").
5.0.0 (2023-10-05)
The following contracts and libraries were added:
AccessManager
: A consolidated system for managing access control in complex systems.
AccessManaged
: A module for connecting a contract to an authority in charge of its access control.GovernorTimelockAccess
: An adapter for time-locking governance proposals using an AccessManager
.AuthorityUtils
: A library of utilities for interacting with authority contracts.GovernorStorage
: A Governor module that stores proposal details in storage.ERC2771Forwarder
: An ERC2771 forwarder for meta transactions.ERC1967Utils
: A library with ERC1967 events, errors and getters.Nonces
: An abstraction for managing account nonces.MessageHashUtils
: A library for producing digests for ECDSA operations.Time
: A library with helpers for manipulating time-related objects.The following contracts, libraries, and functions were removed:
Address.isContract
(because of its ambiguous nature and potential for misuse)Checkpoints.History
Counters
ERC20Snapshot
ERC20VotesComp
ERC165Storage
(in favor of inheritance based approach)ERC777
ERC1820Implementer
GovernorVotesComp
GovernorProposalThreshold
(deprecated since 4.4)PaymentSplitter
PullPayment
SafeMath
SignedSafeMath
Timers
TokenTimelock
(in favor of VestingWallet
)Escrow
, ConditionalEscrow
and RefundEscrow
)AccessControlCrossChain
and all the vendored bridge interfacesThese removals were implemented in the following PRs: #3637, #3880, #3945, #4258, #4276, #4289
abi.encodeCall
in place of abi.encodeWithSelector
and abi.encodeWithSignature
for improved type-checking of parameters (#4293)abi.encodePacked
with clearer alternatives (e.g. bytes.concat
, string.concat
). (#4504) (#4296)ERC1155Supply.totalSupply
, ERC721.ownerOf
, ERC721.balanceOf
and ERC721.totalSupply
in ERC721Enumerable
, ERC20.totalSupply
in ERC20FlashMint
, and ERC1967._getImplementation
in ERC1967Proxy
. (#4299)override
specifier from functions that only override a single interface function. (#4315)Governor
, Initializable
, and UUPSUpgradeable
: Use internal functions in modifiers to optimize bytecode size. (#4472)Ownable
: Added an initialOwner
parameter to the constructor, making the ownership initialization explicit. (#4267)Ownable
: Prevent using address(0) as the initial owner. (#4531)AccessControl
: Added a boolean return value to the internal _grantRole
and _revokeRole
functions indicating whether the role was granted or revoked. (#4241)access
: Moved AccessControl
extensions to a dedicated directory. (#4359)AccessManager
: Added a new contract for managing access control of complex systems in a consolidated location. (#4121)AccessManager
, AccessManaged
, GovernorTimelockAccess
: Ensure that calldata shorter than 4 bytes is not padded to 4 bytes. (#4624)AccessManager
: Use named return parameters in functions that return multiple values. (#4624)AccessManager
: Make schedule
and execute
more conservative when delay is 0. (#4644)VestingWallet
: Fixed revert during 1 second time window when duration is 0. (#4502)VestingWallet
: Use Ownable
instead of an immutable beneficiary
. (#4508)Governor
: Optimized use of storage for proposal data (#4268)Governor
: Added validation in ERC1155 and ERC721 receiver hooks to ensure Governor is the executor. (#4314)Governor
: Refactored internals to implement common queuing logic in the core module of the Governor. Added queue
and _queueOperations
functions that act at different levels. Modules that implement queuing via timelocks are expected to override _queueOperations
to implement the timelock-specific logic. Added _executeOperations
as the equivalent for execution. (#4360)Governor
: Added voter
and nonce
parameters in signed ballots, to avoid forging signatures for random addresses, prevent signature replay, and allow invalidating signatures. Add voter
as a new parameter in the castVoteBySig
and castVoteWithReasonAndParamsBySig
functions. (#4378)Governor
: Added support for casting votes with ERC-1271 signatures by using a bytes memory signature
instead of r
, s
and v
arguments in the castVoteBySig
and castVoteWithReasonAndParamsBySig
functions. (#4418)Governor
: Added a mechanism to restrict the address of the proposer using a suffix in the description.GovernorStorage
: Added a new governor extension that stores the proposal details in storage, with an interface that operates on proposalId
, as well as proposal enumerability. This replaces the old GovernorCompatibilityBravo
module. (#4360)GovernorTimelockAccess
: Added a module to connect a governor with an instance of AccessManager
, allowing the governor to make calls that are delay-restricted by the manager using the normal queue
workflow. (#4523)GovernorTimelockControl
: Clean up timelock id on execution for gas refund. (#4118)GovernorTimelockControl
: Added the Governor instance address as part of the TimelockController operation salt
to avoid operation id collisions between governors using the same TimelockController. (#4432)TimelockController
: Changed the role architecture to use DEFAULT_ADMIN_ROLE
as the admin for all roles, instead of the bespoke TIMELOCK_ADMIN_ROLE
that was used previously. This aligns with the general recommendation for AccessControl
and makes the addition of new roles easier. Accordingly, the admin
parameter and timelock will now be granted DEFAULT_ADMIN_ROLE
instead of TIMELOCK_ADMIN_ROLE
. (#3799)TimelockController
: Added a state getter that returns an OperationState
enum. (#4358)Votes
: Use Trace208 for checkpoints. This enables EIP-6372 clock support for keys but reduces the max supported voting power to uint208. (#4539)ERC2771Forwarder
: Added deadline
for expiring transactions, batching, and more secure handling of msg.value
. (#4346)ERC2771Context
: Return the forwarder address whenever the msg.data
of a call originating from a trusted forwarder is not long enough to contain the request signer address (i.e. msg.data.length
is less than 20 bytes), as specified by ERC-2771. (#4481)ERC2771Context
: Prevent revert in _msgData()
when a call originating from a trusted forwarder is not long enough to contain the request signer address (i.e. msg.data.length
is less than 20 bytes). Return the full calldata in that case. (#4484)ProxyAdmin
: Removed getProxyAdmin
and getProxyImplementation
getters. (#3820)TransparentUpgradeableProxy
: Removed admin
and implementation
getters, which were only callable by the proxy owner and thus not very useful. (#3820)ERC1967Utils
: Refactored the ERC1967Upgrade
abstract contract as a library. (#4325)TransparentUpgradeableProxy
: Admin is now stored in an immutable variable (set during construction) to avoid unnecessary storage reads on every proxy call. This removed the ability to ever change the admin. Transfer of the upgrade capability is exclusively handled through the ownership of the ProxyAdmin
. (#4354)ERC1967Utils
to UUPSUpgradeable
. (#4356)UUPSUpgradeable
, TransparentUpgradeableProxy
and ProxyAdmin
: Removed upgradeTo
and upgrade
functions, and made upgradeToAndCall
and upgradeAndCall
ignore the data argument if it is empty. It is no longer possible to invoke the receive function (or send value with empty data) along with an upgrade. (#4382)BeaconProxy
: Reject value in initialization unless a payable function is explicitly invoked. (#4382)Proxy
: Removed redundant receive
function. (#4434)BeaconProxy
: Use an immutable variable to store the address of the beacon. It is no longer possible for a BeaconProxy
to upgrade by changing to another beacon. (#4435)Initializable
: Use the namespaced storage pattern to avoid putting critical variables in slot 0. Allow reinitializer versions greater than 256. (#4460)Initializable
: Use intermediate variables to improve readability. (#4576)ERC20
, ERC721
, ERC1155
: Deleted _beforeTokenTransfer
and _afterTokenTransfer
hooks, added a new internal _update
function for customizations, and refactored all extensions using those hooks to use _update
instead. (#3838, #3876, #4377)ERC20
: Removed Approval
event previously emitted in transferFrom
to indicate that part of the allowance was consumed. With this change, allowances are no longer reconstructible from events. See the code for guidelines on how to re-enable this event if needed. (#4370)ERC20
: Removed the non-standard increaseAllowance
and decreaseAllowance
functions. (#4585)ERC20Votes
: Changed internal vote accounting to reusable Votes
module previously used by ERC721Votes
. Removed implicit ERC20Permit
inheritance. Note that the DOMAIN_SEPARATOR
getter was previously guaranteed to be available for ERC20Votes
contracts, but is no longer available unless ERC20Permit
is explicitly used; ERC-5267 support is included in ERC20Votes
with EIP712
and is recommended as an alternative. (#3816)SafeERC20
: Refactored safeDecreaseAllowance
and safeIncreaseAllowance
to support USDT-like tokens. (#4260)SafeERC20
: Removed safePermit
in favor of documentation-only permit
recommendations. Based on recommendations from @trust1995 (#4582)ERC721
: _approve
no longer allows approving the owner of the tokenId. (#4377) _setApprovalForAll
no longer allows setting address(0) as an operator. (#4377)ERC721
: Renamed _requireMinted
to _requireOwned
and added a return value with the current owner. Implemented ownerOf
in terms of _requireOwned
. (#4566)ERC721Consecutive
: Added a _firstConsecutiveId
internal function that can be overridden to change the id of the first token minted through _mintConsecutive
. (#4097)ERC721URIStorage
: Allow setting the token URI prior to minting. (#4559)ERC721URIStorage
, ERC721Royalty
: Stop resetting token-specific URI and royalties when burning. (#4561)ERC1155
: Optimized array allocation. (#4196)ERC1155
: Removed check for address zero in balanceOf
. (#4263)ERC1155
: Optimized array accesses by skipping bounds checking when unnecessary. (#4300)ERC1155
: Bubble errors triggered in the onERC1155Received
and onERC1155BatchReceived
hooks. (#4314)ERC1155Supply
: Added a totalSupply()
function that returns the total amount of token circulating, this change will restrict the total tokens minted across all ids to 2**256-1 . (#3962)ERC1155Receiver
: Removed in favor of ERC1155Holder
. (#4450)Address
: Removed the ability to customize error messages. A common custom error is always used if the underlying revert reason cannot be bubbled up. (#4502)Arrays
: Added unsafeMemoryAccess
helpers to read from a memory array without checking the length. (#4300)Arrays
: Optimized findUpperBound
by removing redundant SLOAD. (#4442)Checkpoints
: Library moved from utils
to utils/structs
(#4275)DoubleEndedQueue
: Refactored internal structure to use uint128
instead of int128
. This has no effect on the library interface. (#4150)ECDSA
: Use unchecked arithmetic for the tryRecover
function that receives the r
and vs
short-signature fields separately. (#4301)EIP712
: Added internal getters for the name and version strings (#4303)Math
: Makes ceilDiv
to revert on 0 division even if the numerator is 0 (#4348)Math
: Optimized stack operations in mulDiv
. (#4494)Math
: Renamed members of Rounding
enum, and added a new rounding mode for "away from zero". (#4455)MerkleProof
: Use custom error to report invalid multiproof instead of reverting with overflow panic. (#4564)MessageHashUtils
: Added a new library for creating message digest to be used along with signing or recovery such as ECDSA or ERC-1271. These functions are moved from the ECDSA
library. (#4430)Nonces
: Added a new contract to keep track of user nonces. Used for signatures in ERC20Permit
, ERC20Votes
, and ERC721Votes
. (#3816)ReentrancyGuard
, Pausable
: Moved to utils
directory. (#4551)Strings
: Renamed toString(int256)
to toStringSigned(int256)
. (#4330)Strings.equal
(#4262)These breaking changes will require modifications to ERC20, ERC721, and ERC1155 contracts, since the _afterTokenTransfer
and _beforeTokenTransfer
functions were removed. Thus, any customization made through those hooks should now be done overriding the new _update
function instead.
Minting and burning are implemented by _update
and customizations should be done by overriding this function as well. _transfer
, _mint
and _burn
are no longer virtual (meaning they are not overridable) to guard against possible inconsistencies.
For example, a contract using ERC20
's _beforeTokenTransfer
hook would have to be changed in the following way.
-function _beforeTokenTransfer(
+function _update(
address from,
address to,
uint256 amount
) internal virtual override {
- super._beforeTokenTransfer(from, to, amount);
require(!condition(), "ERC20: wrong condition");
+ super._update(from, to, amount);
}
In the case of ERC721
, the _update
function does not include a from
parameter, as the sender is implicitly the previous owner of the tokenId
. The address of this previous owner is returned by the _update
function, so it can be used for a posteriori checks. In addition to to
and tokenId
, a third parameter (auth
) is present in this function. This parameter enabled an optional check that the caller/spender is approved to do the transfer. This check cannot be performed after the transfer (because the transfer resets the approval), and doing it before _update
would require a duplicate call to _ownerOf
.
In this logic of removing hidden SLOADs, the _isApprovedOrOwner
function was removed in favor of a new _isAuthorized
function. Overrides that used to target the _isApprovedOrOwner
should now be performed on the _isAuthorized
function. Calls to _isApprovedOrOwner
that preceded a call to _transfer
, _burn
or _approve
should be removed in favor of using the auth
argument in _update
and _approve
. This is showcased in ERC721Burnable.burn
and in ERC721Wrapper.withdrawTo
.
The _exists
function was removed. Calls to this function can be replaced by _ownerOf(tokenId) != address(0)
.
Batch transfers will now emit TransferSingle
if the batch consists of a single token, while in previous versions the TransferBatch
event would be used for all transfers initiated through safeBatchTransferFrom
. Both behaviors are compliant with the ERC-1155 specification.
Users that were registering EIP-165 interfaces with _registerInterface
from ERC165Storage
should instead do so by overriding the supportsInterface
function as seen below:
function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
return interfaceId == type(MyInterface).interfaceId || super.supportsInterface(interfaceId);
}
Methods in SafeMath superseded by native overflow checks in Solidity 0.8.0 were removed along with operations providing an interface for revert strings. The remaining methods were moved to utils/Math.sol
.
- import "@openzeppelin/contracts/utils/math/SafeMath.sol";
+ import "@openzeppelin/contracts/utils/math/Math.sol";
function tryOperations(uint256 x, uint256 y) external view {
- (bool overflowsAdd, uint256 resultAdd) = SafeMath.tryAdd(x, y);
+ (bool overflowsAdd, uint256 resultAdd) = Math.tryAdd(x, y);
- (bool overflowsSub, uint256 resultSub) = SafeMath.trySub(x, y);
+ (bool overflowsSub, uint256 resultSub) = Math.trySub(x, y);
- (bool overflowsMul, uint256 resultMul) = SafeMath.tryMul(x, y);
+ (bool overflowsMul, uint256 resultMul) = Math.tryMul(x, y);
- (bool overflowsDiv, uint256 resultDiv) = SafeMath.tryDiv(x, y);
+ (bool overflowsDiv, uint256 resultDiv) = Math.tryDiv(x, y);
// ...
}
Custom Governor modules that override internal functions may require modifications if migrated to v5. In particular, the new internal functions _queueOperations
and _executeOperations
may need to be used. If assistance with this migration is needed reach out via the OpenZeppelin Support Forum.
The ECDSA
library is now focused on signer recovery. Previously it also included utility methods for producing digests to be used with signing or recovery. These utilities have been moved to the MessageHashUtils
library and should be imported if needed:
import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+import {MessageHashUtils} from "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol";
contract Verifier {
using ECDSA for bytes32;
+ using MessageHashUtils for bytes32;
function _verify(bytes32 data, bytes memory signature, address account) internal pure returns (bool) {
return data
.toEthSignedMessageHash()
.recover(signature) == account;
}
}
The upgradeable version of the contracts library used to include a variant suffixed with Upgradeable
for every contract. These variants, which are produced automatically, mainly include changes for dealing with storage that don't apply to libraries and interfaces.
The upgradeable library no longer includes upgradeable variants for libraries and interfaces. Projects migrating to 5.0 should replace their library and interface imports with their corresponding non-upgradeable version:
// Libraries
-import {AddressUpgradeable} from '@openzeppelin/contracts-upgradeable/utils/AddressUpgradeable.sol';
+import {Address} from '@openzeppelin/contracts/utils/Address.sol';
// Interfaces
-import {IERC20Upgradeable} from '@openzeppelin/contracts-upgradeable/interfaces/IERC20.sol';
+import {IERC20} from '@openzeppelin/contracts/interfaces/IERC20.sol';
Some changes may affect offchain systems if they rely on assumptions that are changed along with these new breaking changes. These cases are:
A concrete example is AccessControl, where it was previously advised to catch revert reasons using the following regex:
/^AccessControl: account (0x[0-9a-f]{40}) is missing role (0x[0-9a-f]{64})$/
Instead, contracts now revert with custom errors. Systems that interact with smart contracts outside of the network should consider reliance on revert strings and possibly support the new custom errors.
After 5.0, the storage location of some variables were changed. This is the case for Initializable
and all the upgradeable contracts since they now use namespaced storaged locations. Any system relying on storage locations for retrieving data or detecting capabilities should be updated to support these new locations.
FAQs
Secure Smart Contract library for Solidity
The npm package @openzeppelin/contracts-upgradeable receives a total of 177,485 weekly downloads. As such, @openzeppelin/contracts-upgradeable popularity was classified as popular.
We found that @openzeppelin/contracts-upgradeable demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.