In The Future of contracts-ethereum-package we described our plans to improve the experience of using upgradeability together with OpenZeppelin Contracts, our secure library of smart contracts. Today we're finally releasing the new package that is the result of this work, meant to replace the existing @openzeppelin/contracts-ethereum-package.
On the surface, this release will not seem like a big deal. While the package name has changed, and contract names have slightly changed as well, everything else remains the same. Adopting the new package should be very simple. Under the surface, however, we have made some big infrastructure changes that will enable better paced and more secure releases.
npm install @openzeppelin/contracts-upgradeable
Developers wishing to use OpenZeppelin Contracts in an upgradeable contract have had to use @openzeppelin/contracts-ethereum-package so far. The first improvement we wanted to make was changing the name of this package into something that would better represent its purpose and contents. We have chosen @openzeppelin/contracts-upgradeable, which we think communicates clearly that it is a variant of the main @openzeppelin/contracts package that is safe to use with upgradeability.
New projects should choose the new package. Existing projects should switch if they expect continued maintenance, which they can do by following the simple migration instructions in the changelog.
The second improvement we have been working on is an automated process for building this variant based on the main OpenZeppelin Contracts codebase. The repository regularly pulls in updates from the main codebase and converts the code into its upgrade safe variant, using our upgradeability transpiler.
While we will still manually review the generated code, this level of automation is a huge boost to the maintainability of the project, and will enable us to release updates in sync with the main OpenZeppelin Contracts.
Although we are very confident in the transpiler for its use with OpenZeppelin Contracts, it's worth noting that it was built and tested specifically for this purpose, and we can't guarantee that it will produce correct results if used on a different project. If this is something you are interested in, let us know in the comments below.
Lastly, we have already started working on improving documentation, with a new article published at docs.openzeppelin.com/contracts/upgradeable. The article explains how to use the package, the differences with the main OpenZeppelin Contracts package, and includes a few notes on questions that are likely to arise. We want to grow this article to cover more of these topics, so please let us know if you think of something we should mention.
npm install @openzeppelin/contracts-upgradeable
Note that this release mirrors version 3.2.0 of OpenZeppelin Contracts, and is thus compatible with Solidity 0.6. A release compatible with Solidity 0.7 will come eventually but is not an immediate priority for us. (Let us know if you want it!)