v3.1.0

This is the first release since v3.0, our last major release. It includes the long-awaited ERC1155 token and helpers for safe calls and downcasts, as well as a number of minor improvements.

To install this release, run:

npm install --save-dev @openzeppelin/contracts

ERC1155

This is a new token standard developed by the gaming industry, focusing on gas efficiency. It's key difference is that it is a multi-token contract: a single ERC1155 can be used to represent an arbitrary number of tokens, which is very useful in applications that require many tokens by removing the high gas costs associated with deploying them. Check out our new documentation page to learn more!.

More Replacements for call

The low-level call primitive can be hard to use correctly and is often considered unsafe. With the addition of sendValue in Contracts and try-catch in Solidity, there's only a few scenarios in which call is still needed, the most troublesome one being forwarding calls.

The new functionCall helpers can forward call data to a recipient contract while imitating Solidity's function call semantics, such as bubbling up revert reasons and rejecting calls to EOAs. We expect the addition of these functions to greatly reduce the need to rely on call.

Using SafeMath on Small Signed Integers

We've expanded the scope of the SafeCast library to also include signed integer downcasting, which allows for users that need small types (such as int8 or int32) to perform checked arithmetic on them by using SafeMath, and then downcast the result to the intended size.

OpenZeppelin Contracts 3.0.1

This is a small bugfix release, addressing an issue that allowed for some internal functions in ERC777 to be called with the zero address as one of their arguments.

This was reported in #2208, fixed in #2212 for the v2.5 branch, and ported to the v3.0 branch in #2213.

OpenZeppelin Contracts 2.5.1

This is a small bugfix release, addressing an issue that allowed for some internal functions in ERC777 to be called with the zero address as one of their arguments.

This was reported in #2208 and fixed in #2212.

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.