The Future of contracts-ethereum-package

If you’re unfamiliar with “Contracts Ethereum Package”, it’s a variant of the popular OpenZeppelin Contracts but for upgradeable contracts. It ships a modified version of the regular contracts so that they support proxy upgradeability: by replacing constructors with initializer functions, delaying initialization of state variables, and ensuring storage layout compatibility across versions.

This post is the continuation of Planning the demise of OpenZeppelin Contracts' evil twin from November last year. In that post, @spalladino proposed two alternative plans for improving the user experience around using OpenZeppelin Contracts with upgradeable contracts by getting rid of Contracts Ethereum Package, affectionately referred to as Contracts’ evil twin.

Plan A consisted in merging Contracts Ethereum Package into the “vanilla” OpenZeppelin Contracts, shipping both sets of contracts together. Plan B consisted in getting rid of the upgradeable variant altogether, and automating at “compile time” the necessary source code transformations needed on vanilla Contracts.

Plan B was the clear winner at the time and so we moved forward with building the so called Transpiler. We hadn’t got to the point of integrating it into the OpenZeppelin CLI workflow by the time Contracts 3.0 was going to be released, so to make Contracts Ethereum Package easier for us we decided to repurpose the transpiler into a standalone tool we could use to build the upgradeable variant, which would continue to be shipped as the Ethereum Package.

Since then we’ve been focusing our efforts on building a better programmatic API for deploying and managing upgradeable contracts, which has now been released as the OpenZeppelin Upgrades plugins for Truffle and Buidler. Now that it’s been released we’re focusing again on the issue of improving the experience of using OpenZeppelin Contracts and upgradeability together.

While our end goal is still to provide an upgradeability transpiler for the end user, it’s a significant effort and it will take us a while to get there. But there is nonetheless a number of improvements we can already make in the immediate future. We’ve decided to tackle the following two issues.

Confusing name. The name “ethereum package” turns out to be very generic, thus it has bad discoverability and it doesn’t explain its purpose very well.

Release cadence. The Ethereum Package variant tends to have delayed and slower releases. This is due to a lot of manual work we still have to do for every release.

To tackle the first issue we’ve decided to use the “upgrade safe” terminology introduced in Contracts Ethereum Package 3.0 the “upgradeable” term, and release the package under a new name: @openzeppelin/contracts-upgradeable. We hope this does a better job of communicating the purpose and contents of the package.

In the end, we went with “upgradeable” to avoid any potential confusion with Gnosis Safe. See the release announcement at First release of OpenZeppelin Contracts Upgradeable.

To improve release cadence we will be automating as much of the process as possible. First and foremost we have to improve the transpilation process so that it doesn’t need manual intervention, and a big part of this is figuring out how to run the same test suite on the transpiled contracts. And then we want to put in place a continuous integration pipeline that will run this process on every commit to the vanilla Contracts repository, so if any issues come up we’ll detect them as soon as possible. With this in place it should be simple to put out releases in parallel with vanilla Contracts.

Let us know if you have thoughts about these plans! Have you had any issues with Contracts Ethereum Package that I didn’t mention? Is there any other improvement you would like to see?


Hi @frangio,

The issues I generally see in the community are:

  • Confusion over how to use OpenZeppelin Contracts for upgradeable contracts - the name change makes this clearer
  • Release cadence - the general rule is approximately two weeks after an official release of OpenZeppelin Contracts, it will be great to improve on this.

In future, will there be deployed implementation contracts?
Currently ERC20PresetMinterPauserUpgradeSafe & ERC721PresetMinterPauserAutoIdUpgradeSafe are deployed.

There will no longer be predeployed implementation contracts because it’s one of the things that adds a lot of friction to the release process for us, and we’re not aware of people actually using them.

1 Like

This is really great! +1 to tackling those issues in the short term. I think the new name helps a lot!

Also now that the Proxy contracts were moved to the core package, does it also make sense to have more examples/tutorials in the docs on how to use them directly without the SDK?


1 Like

Yes, definitely! I’m working on those docs and will try to provide that kind of information.


Nice pal! Let us know if you need help we are behind you every step of the way!


Feedback from @oberstet that documentation could be improved on how to use:

I created an issue for the documentation:

1 Like

Agree 100%. Documentation is certainly something that has to be improved in this next iteration of the upgrade safe contracts.

1 Like

Hi @frangio,

DragonLord on Telegram wanted Solidity 0.7 support for an upgrade safe fork of OpenZeppelin Contracts. This would build on OpenZeppelin Contracts and Solidity 0.7

Interested to see if anyone else in the community has this need yet?

There will no longer be predeployed implementation contracts because it’s one of the things that adds a lot of friction to the release process for us, and we’re not aware of people actually using them.

So does this mean, for people like me that built their token off of the pre-deployed presets (specifically ERC721PresetMinterPauserAutoIdUpgradeSafe), I wouldn’t be able to do that with the new version and it MIGHT be beneficial to just write my own contract going forward with of all the provided examples as a guide?

1 Like

Hi @EvilJordan,

The change means that as part of the release process for OpenZeppelin Contracts Upgrade Safe it won’t include deploying the presets. This is to speed up the release process and reduce the time between an OpenZeppelin Contracts release and an equivalent OpenZeppelin Contracts Upgrade Safe release.

You can still use the presets in production, and for upgradeable contracts you can use the existing deployed version or deploy the implementations yourself.

It is up to you whether you use the preset as your implementation contract, extend the preset or implement your own version extending from ERC721 depends what changes you may envisage in the future. For upgradeable contracts we need to maintain the storage layout between upgrades so can’t change the order or type of state variables, we can only add new state variables after the existing ones, unless we modify the amount of reserved slots.

As an aside, I suggest looking at the recently released OpenZeppelin Upgrades Plugins:

1 Like

A post was split to a new topic: Which OpenZeppelin Contracts should be used for upgradeable contracts?

See: First release of OpenZeppelin Contracts Upgradeable