Which version of OpenZeppelin Contracts should be used for upgradeable contracts?

I’m using upgradeable contracts for quite some time and just stumbled upon your CLI’s deprecation warning. Bold choice but I’d say it’s a step in the right direction.

What still confuses me is which package to use to deploy upgradeable contracts (using the new truffle upgradeProxy features) -> are we still supposed to use the premade @openzeppelin/contracts-ethereum-package contracts that contain e.g. the ERC20PresetMinterPauser**UpgradeSafe** presets? Or would you recommend to simply use the non upgradeable contracts (containing constuctors) from @openzeppelin/contracts and manually extend them to implement the Initializable base that now is available on @openzeppelin/contracts/proxy/Initializable.sol (the latest tutorial on upgradeable contracts is actually using it but doesn’t say a word on how to proceed with the “old” UpgradeSafe presets. Its Box example is hard too compare with the preset erc20 token contracts…)

This is quite confusing to say the least :wink: But hey, thanks for making all that so much simpler and safe! - even though it’s hard to stay synced with all these changes…

Moved from The Future of contracts-ethereum-package


Hi @elmariachi111,

I am sorry that it is confusing.

When creating upgradeable contracts it is recommended to deploy using OpenZeppelin Upgrades Plugins (documentation: https://docs.openzeppelin.com/upgrades-plugins/1.x/).

If you want to use/extend OpenZeppelin Contracts then you should use the Upgrade Safe fork which is currently OpenZeppelin Contracts Ethereum Package. (The plan is to change the name to make it less confusing: The Future of contracts-ethereum-package).

There is an open issue to improve the documentation around the Upgrade Safe version of OpenZeppelin Contracts.

1 Like

Thanks for the feedback @elmariachi111!

We know, and we’re actively working on making it simpler, less confusing, and more documented.

I’ve been working for the past few weeks on the plan outlined in The Future of contracts-ethereum-package and the work is almost complete. I think I can safely say we will be releasing it next week, along with some initial documentation. We’ll make sure that the new package is mentioned in the relevant places and well explained.

As for your questions:

Yes, although note that you don’t need to use the presets, you can use any contract from the package, as indicated by the “UpgradeSafe” suffix they are all safe to use with upgradeable proxies.

This would not work: @openzeppelin/contracts has constructors, and it’s not possible to remove the constructors through inheritance by just adding Initializable. This is why there are two packages: one of them has constructors, the other doesn’t (along with a few other necessary changes).


yeah, that clears the skies a little :slight_smile: Awesome, thank you!

After I posted that question here yesterday I tried to “migrate” a project from oz/cli to your new upgrade plugins, trying truffle first and buidler second. I must really say, that from a DX/convenience (deploy -> upgrade -> done) point of view we’re really losing something here (here’s my commit history if you feel truly bored but I definitely don’t expect anyone to dig through it).

At the moment:

  • truffle is ok. I mean, writing migrations in a meaningful way can be confusing (especially when you’re supposed to call one migration several times because it’s just upgrading a changed contract with new code - did you notice, that their migrate command takes a --to flag and a --f (sic!) flag?
  • next, truffle puts the deployed contract addresses right into their build output - when working with oz, I simply gitignored the build folder and recreated it on each developers’ local machine - the live deployment addresses stayed committed in the .openzeppelin folder. When collaborating with several people each build / deploy on a developer machine would overwrite the built artifact file, removing the deployed artifacts for the next developer. Here’s an old Stackoverflow thread https://ethereum.stackexchange.com/questions/24296/what-is-a-standard-gitignore-for-truffle#comment31291_24300 that actually came to the same conclusion;)
  • When I used truffle to “migrate” a simple upgrade safe ERC20 to Görli using Infura, it ran the dryrun first and then arbitrarily crashed while deploying the “real” thing. That felt way more unstable than an oz deploy --network goerli.

So I tried buidler. Well, hardhat that is (now). Only that your plugin docs https://docs.openzeppelin.com/upgrades-plugins/1.x/buidler-upgrades#install aren’t compatible to hardhat’s recent rewrite of their deplyoment tools. So at 2am I switched back to buidler, nearly the same and it works with your new plugins, great :slight_smile: But wait, there is no thing like an “oz deploy” there (and that super massive 3rd party “deploy” plugin https://hardhat.org/plugins/hardhat-deploy.html is not “officially unsupported”) but I must write deploy scripts on my own? Well, that’s certainly powerful, but boy I’m going to miss oz deploy for sure (and so is my team) :frowning:


I feel you. Unfortunately there was a lot more to the CLI than oz deploy, and it was not sustainable for us to keep working on it. We decided to prioritize building security features over pure developer experience features in the form of the Upgrades plugins.

I would expect more deployment solutions to emerge for Hardhat.

As for Hardhat support in the Upgrades plugins: we’re working on this and it will likely be released in a few days.

If you have any other feedback about the plugins feel free to reach out or open issues in the repository.


@elmariachi111 Check out our latest release for the upgradeable version of OpenZeppelin Contracts.

Also some improved documentation!

Thank you for the feedback so far! :pray: I would love to hear what you think of the new release and docs.


This post was flagged by the community and is temporarily hidden.


Hey @frangio . Imo the docs are concise and good to go - haven’t tested with hardhat again but I assume it’s simply working :slight_smile: I’ve migrated our codebase to use the plugin and after some struggles with deploying on goerli testnet using truffle (it’s definitely worth telling truffle to use infuras websocket endpoints) I was able to upgrade contracts.

I’m still struggling with the big question what must go into source control here - I committed the new .openzeppelin folder that contains the logic contract addresses but it doesn’t point us to the proxy contract which is the entrypoint for our app to call. I’m hesitating to commit the truffle build output instead since it also contains all information of my local dev chain and that’s absolutely nothing you’d like to put under source control since it’s unique to each developer :roll_eyes:

BTW: the app built by the repo is deployed on ipfs here: https://ledger-workshop.eth.link/

1 Like

Hi @elmariachi111,

The advice for version control is as follows:

Though I appreciate that there is still an issue about the proxy addresses and the best way to handle these.