Upgrading

Upgrading the Aavegotchi Diamond

As per EIP-2535 Diamond Standard upgrades are done by calling the diamondCut function to add/replace/remove any number of functions and facets in a single transaction.

Upgrading can be done safely and easily as long as some important rules are followed.

Rules

1. Make sure that an upgrade is atomic, meaning that all changes are done in a single transaction to ensure the diamond does not get into an inconsistent state. This is done by calling diamondCut once with all functions to add/replace/remove.

2. The diamond and all the facets share the same contract storage address space. Do not corrupt state variables by sticking new state variables in the middle of structs. Do not change the bit size of an existing state variable if that overlaps with an existing state variable.

3. New state variables can be added to the end of structs.

4. Existing state variables can have their name changed.

More info on upgrade rules found here: https://eip2535diamonds.substack.com/p/diamond-upgrades?s=w

Upgrade Procedure

1. Modify the existing source code of the diamond and its facets.

2. Write an upgrade script that calls the diamondCut function to add/replace/remove functions.

3. Write any new tests and run tests to make sure they pass.

4. Commit and push changes to git.

5. Get any needed code review or code audit.

6. Execute the upgrade script.

7. Immediately tag the source code with the transaction hash that made the upgrade. Commit and push the tag to git. This records and associates the diamond and facet source code with the upgrade.

8. Use the hardhat etherscan plugin to verify the source code of any new facets that were used to add/replace functions.

Example upgrade command: npx hardhat run scripts/upgrade.js --network kovan