As you may already know, we recently released two plugins to upgrade smart contracts in your Buidler or Truffle projects. You can kickstart your upgradeable project by just following the documentation, but if it is already built with the OpenZeppelin CLI and you'd like to make the switch to use Buidler or Truffle, this is your guide.
This walkthrough assumes you already have a project set up using the OpenZeppelin CLI, but if you don't and you'd like to follow along you can clone this repo (read the readme!) and it will be just as good as a starting point.
But first, some context.
The main difference between the CLI and the plugins is that the former used to keep track of your upgradeable (and non-upgradeable) deployments for you. This was handy in some contexts since you didn't need to worry too much about proxies, implementations or addresses and you could just focus on operations like upgrading or sending transactions to your contracts just by their name.
But having the CLI keep track of your deployments came at the expense of limiting your freedom to integrate with different tools and workflows. And since the plugins were designed to work independently of the CLI, we lifted that restriction so now you have the flexibility to keep track of your proxies the way you think it's best.
Keeping that aside, everything else remains the same since both the CLI and plugins make use of the same known Proxy and ProxyAdmin contracts under the hood, making up two different interfaces to manage them. This means that migrating your project won't touch anything on chain, everything is safe and local.
Install Buidler and when initializing it, select the Create an empty buidler.config.js option.
$ npm install --save-dev @nomiclabs/buidler
$ npx buidler
Then install the Upgrades plugin:
$ npm install --save-dev @openzeppelin/buidler-upgrades
$ npm install --save-dev @nomiclabs/buidler-ethers ethers # peer dependencies
Once it is done, register the plugin in the Buidler config file by adding these lines:
// buidler.config.js
usePlugin('@nomiclabs/buidler-ethers');
usePlugin('@openzeppelin/buidler-upgrades');
module.exports = {
// ...
};1
Initialize your project and don't overwrite contracts or test directories. By not overwriting contracts directory, you won't get an initial migration (Migrations.sol). Make sure you create one.
$ npm install --save-dev truffle @openzeppelin/truffle-upgrades
$ npx truffle init