This is briefly mentioned in How the plugins work:
The plugins will keep track of all the implementation contracts you have deployed in an
.openzeppelin folder in the project root, as well as the proxy admin.
In more detail, the
.openzeppelin directory tracks for each network: 1) the addresses of already deployed implementation contracts so they can be reused for future proxies, 2) their storage layout to verify compatibility of future upgrades, 3) the address of the ProxyAdmin contract for reuse.
While it’s not a requirement to persist this directory, it would be wasteful not to reuse the things that can be reused.
In a serverless environment you can provide each instance with an already populated
.openzeppelin directory. It wouldn’t need persistence because the plugins will not do any additional changes. (There is one situation where the plugins will change the contents of the directory, but it’s an error condition: if a contract that we assume to be deployed (e.g. one of the implementation contracts) is not found on chain, the plugins will remove the entry from the relevant network file, and then exit with an error.)
In order to create the populated
.openzeppelin directory for your serverless instances, you can use
prepareUpgrade locally and then commit the generated files to source control, for example. This function deploys and stores an implementation contract that can be picked up by later calls to
deployProxy. However, you would also need an
prepareUpgrade doesn’t deploy for you, so every subsequent
deployProxy would deploy their own
admin. If you can confirm that this setup would work for you, we can add a new function in the API to deploy the admin by itself.
The feedback about documentation is appreciated.
I recognize that there is room for improvement but have you seen the API Reference pages? If so, what kind of documentation do you think is missing there?
I’m not sure what you mean by main doc, but last week we released updates to the site, including updated “Learn guides” such as Upgrading smart contracts which now explains how to use the upgrades plugins. They are also featured under “Tools & Libraries” in the landing page. There’s also mention of the plugins in other pages that are relevant, like the documentation for Proxy contracts.