OpenZeppelin Contracts 3.0

We're thrilled to finally announce the release of OpenZeppelin Contracts v3.0 ✨

Among other things, this release features the migration to Solidity v0.6, as well as a revamped access control system, streamlined token contracts, and new libraries for enumerable mappings.

To install this latest release, run:

npm install --save-dev @openzeppelin/contracts

What's New

• All contracts were migrated to Solidity v0.6.
• AccessControl was designed with help from the community and has replaced Roles contracts (such as MinterRole and PauserRole), which were removed.
• Crowdsales were removed: we'll continue to provide support for security issues on the v2.5 release, but will not bring them over to v3.0.
• We've added hooks, a new feature of the library that will make extending it easier than ever.
• ERC20 and ERC721 were simplified and streamlined, including all optional parts of the standard by default, and simplifying some of our own custom extensions.
• Support for better mapping types that let you efficiently iterate over all keys using EnumerableSet and EnumerableMap
• Many, many breaking changes with small improvements. We've also moved some contracts around (e.g. Ownable is now found under the access directory) and deleted some that were not being used. Head to our changelog to see the full list.

Compiling v0.6 Contracts

You can use the OpenZeppelin CLI to compile any Solidity v0.6 contract: just update the pragma statement on your source code and you'll be good to go!

pragma solidity ^0.6.0;

Note that you will need to use the v2.7 release of the CLI or newer to have Solidity v0.6 support. For detailed information about using the CLI compiler, head to its documenation.

Revamped Access Control

One of our most widely-used contracts is Ownable, providing a simple authorization scheme. However, this fell short in complex systems with multiple permissions.

The v3.0 release introduces AccessControl, a one-stop-shop for all authorization needs. It lets you easily define multiple roles with different permissions, as well as which accounts are allowed to grant and revoke each role. It also boosts transparency by enabling enumeration of all privileged accounts in a system.

AccessControl was designed with a security-first mindset, receiving input from a wide array of users and incorporating best practices in the field. Head to our Access Control guide for more information!

Preset Contracts

OpenZeppelin Contracts shine when you need the building blocks to get to the right feature set, but that's not all they can do! We've added a new family of Preset contracts starting with ERC20 and ERC721 tokens that you can quickly deploy as-is without having to write any Solidity code. Check out their documentation!

Migrating From OpenZeppelin Contracts v2.5

Other than the moved and deleted contracts mentioned above, the library API is pretty much the same as in the v2.5 release, so the migration should be straightforward. For instructions on how to update your Solidity v0.5 contracts to v0.6, refer to the official documentation.

If you're using the ERC20 or ERC721 tokens however, you'll have to remove all references to optional extensions (ERC20Detailed, ERC721Enumerable, etc.) - these have been included in the base contracts.

The other exception to this are contracts that use the Gas Station Network (GSN): if you're inheriting from GSNRecipient or one of the other GSN contracts, you'll need to add the following snippet to your contracts:

function _msgSender() internal view override(Context, GSNRecipient) returns (address payable) {
    return GSNRecipient._msgSender();
}

function _msgData() internal view override(Context, GSNRecipient) returns (bytes memory) {
    return GSNRecipient._msgData();
}

Using Hooks

To improve library flexibility, we're introducing hooks: functions that are called at specific moments during a contract's operation that you can use to hook into the internals and extend as you wish.

For example, the _beforeTokenTransfer hook in ERC20, ERC721 and ERC777 makes it very easy to add additional checks or actions to execute whenever tokens are transferred, minted or burned, regardless of what prompted it.

// Tokens can only be transferred, minted or burned if the contract is not paused
contract ERC20Pausable is ERC20, Pausable {
    function _beforeTokenTransfer(address from, address to, uint256 amount) 
        internal virtual override 
    {
        super._beforeTokenTransfer(from, to, amount);

        require(!paused(), "ERC20Pausable: token transfer while paused");
    }
}

As an additional benefit, using hooks will allow you to side-step some of the edge-cases product of the new override keyword.

Head over to our brand new guide on Extending the OpenZeppelin Contracts to learn more!

What's Next

We've started work in some exciting features for the upcoming releases, including fixed-point arithmetic and the ERC1155 token standard. To read more and find out how you can contribute, check out our Q2 2020 roadmap!

OpenZeppelin Contracts 3.0 beta

We're excited to announce the beta release of OpenZeppelin Contracts v3.0 ✨

This is the main item in Contract's roadmap, featuring the migration to Solidity v0.6.

To install the beta release, run:

npm install --save-dev @openzeppelin/contracts@beta

What's Included in the Beta

The final v3.0 release is not yet finished, but we're putting together this beta version early to ease the transition to this new Solidity version for the community.

Here's what you will find in the beta:

• All contracts were migrated to ^0.6.0.
• Roles contracts (such as MinterRole and PauserRole) were removed: we're redesigning our Access Control solution and will have a better version of these in the v3.0 release.
• Crowdsales were removed: we'll continue to provide support for security issues on the v2.5 release, but will not bring them over to v3.0.
• We've added hooks, a new feature of the library that will make extending it easier than ever. Read more below!

We expect for the final v3.0 release to come out in early March. If you want to contribute, head to our list of pending changes: most of them can be tackled quickly by beginner and intermediate users!

Compiling v0.6 Contracts

You can use the OpenZeppelin CLI to compile any Solidity v0.6 contract: just update the pragma statement on your source code and you'll be good to go!

pragma solidity ^0.6.0;

Note that you will need to use the recent v2.7 release of the CLI to have Solidity v0.6 support. For detailed information about using the CLI compiler, head to its documenation.

Migrating From OpenZeppelin Contracts v2.5

Other than the contract removals mentioned above, the library API is pretty much the same as in the v2.5 release, so the migration should be straightforward. For instructions on how to update your Solidity v0.5 contracts to v0.6, refer to the official documentation.

The exception to this is contracts that use the Gas Station Network (GSN): if you're inheriting from GSNRecipient or one of the other GSN contracts, you'll need to add the following snippet to your contracts:

function _msgSender() internal view override(Context, GSNRecipient) returns (address payable) {
    return GSNRecipient._msgSender();
}

function _msgData() internal view override(Context, GSNRecipient) returns (bytes memory) {
    return GSNRecipient._msgData();
}

Using Hooks

To improve library flexibility, we're introducing hooks: functions that are called at specific moments during a contract's operation that you can use to hook into the internals and extend as you wish.

For example, the _beforeTokenTransfer hook in ERC20, ERC721 and ERC777 makes it very easy to add additional checks or actions to execute whenever tokens are transferred, minted or burned, regardless of what prompted it.

// Tokens can only be transferred, minted or burned if the contract is not paused
contract ERC20Pausable is ERC20, Pausable {
    function _beforeTokenTransfer(address from, address to, uint256 amount) 
        internal virtual override 
    {
        super._beforeTokenTransfer(from, to, amount);

        require(!paused(), "ERC20Pausable: token transfer while paused");
    }
}

As an additional benefit, using hooks will allow you to side-step some of the edge-cases product of the new override keyword.

Next Steps

The final v3.0 release is still a couple weeks away, but you can help us get there faster! Head to the list of v3.0 pending changes to learn about areas where you can contribute, or take a look at Contract's roadmap for more information on the general direction we're taking.

While you wait for v3.0 to come out, check out the recent v2.5 release, the final OpenZeppelin Contracts release with support for Solidity v0.5, and our newly improved documentation site, with tons of guides, API References and other learning resources!

OpenZeppelin Contracts 2.5

We're very happy the announce the release of OpenZeppelin Contracts v2.5!

This new release features:

• EnumerableSet: similar to Solidity's mapping, but that lets you retrieve all the keys! Useful for dapps that need to display a set of accounts with some property, and cannot rely on events alone.
• Create2: a simple library for using the CREATE2 opcode, allowing for deployment and pre-computation of addresses when using it.
  To learn more about all the cool things you can do with it, head to Getting the Most out of CREATE2
• ERC721Metadata.baseURI: a neat extension for massive gas savings when the token URIs share a prefix, like https://my.cool.app/token/<id>

There are also some minor improvements, such as gas optimizations for ReentrancyGuard and additional extensibility of ERC777, among others.

For the complete list of changes, head to our changelog.

To install the new release, run:

$ npm install @openzeppelin/contracts@latest

New Documentation 📚

We've also recently done some some improvements to our documentation website, including new detailed guides and documentation for our other tools, such as the Test Helpers, our blazing-fast Test Environment and the OpenZeppelin Command Line Interface. Check them out for a radically better development experience!

Saying Goodbye to Solidity v0.5 👋

December 2019 saw the release of Solidity v0.6. This new version of the language has major improvements, and we're already underway to release the next version of OpenZeppelin Contracts with support for Solidity v0.6.

However, it also includes a lot of breaking changes, making it difficult to support both v0.5 and v0.6 code at the same time. For this reason, we've decided OpenZeppelin Contracts v2.5 will be the last version supporting Solidity v0.5.

The exciting good news it that the next OpenZeppelin Contracts release will be v3.0, where we'll get to redesign some quirky bits of the library, improving ease of use and flexibility. Stay tuned!

OpenZeppelin 2.4

In 2.4 we're releasing support for the Gas Station Network for user onboarding and metatransactions ⛽, new functions to safeguard your contracts against the Istanbul hard fork, and improvements to error messages.

Read the full announcement in the OpenZeppelin Forum, and make sure to check out the details in the changelog!

Enjoy!

OpenZeppelin 2.3

In 2.3 we're introducing ERC777, revert reasons, and a new documentation site. 🎆 Take a look and tell us what you think in the announcement thread!

Take a look and tell us what you think!

ERC777

The long awaited sequel to ERC20. Its main additions are transfer hooks and operators. Hooks let your contracts react to token transfers. In other words, running code when a contract receives tokens is a built-in feature: no more messing around with approve and transferFrom!

The other special feature, operators, provides simpler and more flexible ways of delegating usage of your tokens to other people or contracts, like decentralized exchanges.

All of this with full compatibility with ERC20!

Start building on it and tell us what you think! We're looking for ideas for extensions, custom operators, or utilities. Share your ideas here or in a new thread.

Revert reasons

Are you tired of running into cryptic errors like VM Exception while processing transaction: revert? All errors in OpenZeppelin now have proper error messages that will be displayed when you test your code! We've kept them succinct and to the point. Each error message is unique, so if you're having trouble figuring out exactly which require statement you've hit, it is easy to look up the error string in the source code, and look at the actual condition that is not being met.

Documentation site

We've revamped the docs, take a look!

It'll be super helpful to both people looking to get started in smart contract development, and veteran OpenZeppelin users who just need to quickly recall a function signature. Among other improvements, we've bundled together related concepts, added overviews for each section, and added crosslinks to other contracts and functions to make exploring the docsite a breeze!

Everything is automatically generated from the comments in the source code, so if you spot a typo or have a suggestion, simply open an issue or PR to get it sorted out in no time!

Some sections still require a bit of work to get them to where we want them to be, stay tuned!

More

Some more things are included in this release such as an implementation of ERC1820, and a fix for a bug in PostDeliveryCrowdsale. Take a look at the changelog!
We have revamped the documentation site infrastructure and feel, take a look! It'll be super helpful to both people looking to get started in smart contract development and OpenZeppelin, and veteran users who just need to quickly recall an API. Among other improvements, we've bundled together related concepts, added overviews for each section, and added crosslinks to other contracts and functions to make exploring the docsite a breeze!

Everything is automatically generated from the comments in the source code, so if you spot a typo or have a suggestion, simply open an issue or PR to get it sorted out in no time!

Some sections still require a bit of work to get them to where we want them to be, stay tuned!

More

Some more things are included in this release such as an implementation of ERC1820, and a fix for a bug in PostDeliveryCrowdsale. Take a look at the changelog!

OpenZeppelin 2.3 RC 3

The final release has been published! See v2.3.0.

OpenZeppelin 2.3 RC 0

A newer release candidate has been published! See v2.3.0-rc.3.

OpenZeppelin 2.2

No changes from the release candidate for this one, we're ironing out the kinks in the release process! 🚫 🐛

This minor release includes a way to store token balances and supply so that they can be later queried in a gas-efficient manner 🔖, allows safe interaction with some old, non-compliant tokens 🔒, prevents user errors when using ECDSA signatures 📝 (the magic behind metatransactions! ✨), and provides multiple minor additions and improvements to the API.

To install the release run npm install openzeppelin-solidity@latest.

We would love your help by reviewing newly added contracts, their interface and documentation so that we can make names clearer, features easier to use, and the library better as a whole! Your feedback is extremely useful to us :)

Highlights

New features

• ERC20Snapshot: this variant allows for snapshots to be created on demand, storing the current token balances and total supply so that they can be later retrieved in a gas-efficient manner and e.g. calculate dividends at a past time. (#1617)
• SafeERC20: the ERC20 standard requires that all function calls (e.g. transfer, approve, etc.) return a boolean value indicating success. However, they are multiple widely used tokens out there that return no such value: they simply revert when encountering an error condition. Since Solidity v0.4.22, special code was needed to interact with this non-compliant tokens: now, all of SafeERC20 can be used to safely call both compliant and non-compliant tokens, without the developer having to worry about it. (#1655)
• TimedCrowdsale: an internal _extendTime(uint256 newClosingTime) function was added (with a corresponding TimedCrowdsaleExtended(uint256 prevClosingTime, uint256 newClosingTime) event) allowing for users to safely develop mechanisms to extend the durations of unclosed crowdsales. Note that due to it being internal, there's no out-of-the-box way to do it: this feature is opt-in and must be explicitly invoked by users.

Improvements

• ECDSA: recover no longer accepts malleable signatures (those using upper-range values for s, or 0/1 for v). This helps prevent multiple issues when using signatures as unique identifiers. Read more about common ECDSA issues here. (#1622)
• ERC721's transfers are now more gas efficient due to removal of unnecessary SafeMath calls. (#1610)

Bugfixes:

• (minor) SafeERC20: safeApprove wasn't properly checking for a zero allowance when attempting to set a non-zero allowance. This bug was reported independently by @nikeshnazareth. Thanks a lot! (#1647)

Breaking changes in drafts:

• TokenMetadata has been renamed to ERC20Metadata. (#1618)
• The library Counter has been renamed to Counters and its API has been improved. See an example in ERC721, lines 17 and 204. (#1610)

You can also see all details of this release in our changelog.

OpenZeppelin 2.2.0 RC1

This minor release includes a way to store token balances and supply so that they can be later queried in a gas-efficient manner 🔖, allows safe interaction with some old, non-compliant tokens 🔒, prevents user errors when using ECDSA signatures 📝 (the magic behind metatransactions! ✨), and provides multiple minor additions and improvements to the API.

To install the release candidate run npm install openzeppelin-solidity@next.

We would love your help by reviewing newly added contracts, their interface and documentation so that we can make names clearer, features easier to use, and the library better as a whole! Your feedback is extremely useful to us :)

Highlights

New features

• ERC20Snapshot: this variant allows for snapshots to be created on demand, storing the current token balances and total supply so that they can be later retrieved in a gas-efficient manner and e.g. calculate dividends at a past time. (#1617)
• SafeERC20: the ERC20 standard requires that all function calls (e.g. transfer, approve, etc.) return a boolean value indicating success. However, they are multiple widely used tokens out there that return no such value: they simply revert when encountering an error condition. Since Solidity v0.4.22, special code was needed to interact with this non-compliant tokens: now, all of SafeERC20 can be used to safely call both compliant and non-compliant tokens, without the developer having to worry about it. (#1655)
• TimedCrowdsale: an internal _extendTime(uint256 newClosingTime) function was added (with a corresponding TimedCrowdsaleExtended(uint256 prevClosingTime, uint256 newClosingTime) event) allowing for users to safely develop mechanisms to extend the durations of unclosed crowdsales. Note that due to it being internal, there's no out-of-the-box way to do it: this feature is opt-in and must be explicitly invoked by users.

Improvements

• ECDSA: recover no longer accepts malleable signatures (those using upper-range values for s, or 0/1 for v). This helps prevent multiple issues when using signatures as unique identifiers. Read more about common ECDSA issues here. (#1622)
• ERC721's transfers are now more gas efficient due to removal of unnecessary SafeMath calls. (#1610)

Bugfixes:

• (minor) SafeERC20: safeApprove wasn't properly checking for a zero allowance when attempting to set a non-zero allowance. This bug was reported independently by @nikeshnazareth. Thanks a lot! (#1647)

Breaking changes:

• TokenMetadata (in drafts) has been renamed to ERC20Metadata. (#1618)

You can also see all details of this release in our changelog.

OpenZeppelin 2.1.3

Bugfix release 🐛 🔧

A minor issue with SafeERC20.safeApprove was identified and reported independently by @nikeshnazareth (thanks once again!), this release contains the correspondig fix: #1647.

This bug has been present since v2.0.0. Updating to this latest version is recommended, but no immediate emergency action should be required for production code using affected versions, due to the low severity of the issue.

These independent reviews are a great way to keep our code secure and correct: we'll be making a push for a properly funded bug bounty during these next weeks to continue encouraging them. Stay tuned!