v2.3.0 scripts: migrations, dry-run, detect changes

.husky/pre-commit

@@ -3,6 +3,6 @@
 
 find . -name '*.js' -not -path '*/node_modules/*' | xargs git diff --cached --name-only | xargs -r npx eslint --fix
 find . -name '*.js' -not -path '*/node_modules/*' | xargs git diff --cached --name-only | xargs -r npx prettier --write
-git diff --cached --name-only | grep -e contracts -e *.txt | xargs -r npx solhint --fix 
-git diff --cached --name-only | grep -e contracts -e *.txt | xargs -r npx prettier --write
+git diff --cached --name-only | grep -e ^contracts -e sol$ | xargs -r npx solhint --fix 
+git diff --cached --name-only | grep -e ^contracts -e sol$ | xargs -r npx prettier --write
 npm run natspec-interface-id:fix

docs/local-development.md

@@ -115,7 +115,7 @@ To get the examples how to use the admin to perform actions, refer to unit test
 ### Upgrade facets
 To test the upgrade functionality, you first need to setup an upgrader account as described in previous section.
 
-To perform the upgrade you then
+#### Using the upgrade facets method
 - Update some of the existing facets or create new one.
 - Update config file `scripts/config/facet-upgrade.js`:
  - "addOrUpgrade" is the list of facets that will be upgraded or added,
@@ -124,17 +124,25 @@ To perform the upgrade you then
  - "facetsToInit": list of facets that will be initialized on ProtocolInitializationFacet. 
  if facet initializer expects arguments, provide them here. For no-arg initializers pass an empty array.
  You don't have to provide ProtocolInitializationFacet args here because they are generated on cut function.
-- Update `version` in `package.json`. If the version in `package.json` matches the existing version in addresses file, you will have to explicitly confirm that you want to proceed.
-- Run `npm run upgrade-facets:local`. This will deploy new facets and make all necessary diamond cuts. It also updates the existing addresses file `addresses/<chain-id>-<environment>.json` (for example `addresses/31337-localhost.json` if you are using a default local hardhat node) and outputs the upgrade log to the console.
+- Run `npm run upgrade-facets:local --new-version version`. This will deploy new facets and make all necessary diamond cuts. It also updates the existing addresses file `addresses/<chain-id>-<environment>.json` (for example `addresses/31337-localhost.json` if you are using a default local hardhat node) and outputs the upgrade log to the console.
 
 Protocol initialization facet is explained in more detail on a separate page: [Protocol initialization handler facet](protocol-initialization-facet.md).
 
+#### Using the migrations
+If you are testing an upgrade of official release, you can simply run
+```
+npx hardhat migrate version --network local --env ""
+```
+
+If you are testing an unreleased version (potentially including your changes), first prepare a migration script in [migrations](../scripts/migrations/) named `migrate_<version>.js` with all the logic needed for the migration. Then run the migration the same way as for the official releases.
+
+
 ### Upgrade clients
 To test the upgrade functionality, you first need to setup an upgrader account as described in section [Manage roles](local-development.md#optional-manage-roles)
 
 To perform the upgrade you then
 - Update some of the existing clients
-- Run `npm run upgrade-clients:local`. This will deploy new clients and set implementation address on beacon. It also updates the existing addresses file `addresses/<chain-id>-<environment>.json` (for example `addresses/31337-localhost.json` if you are using a default local hardhat node) and outputs the upgrade log to the console.
+- Run `npm run upgrade-clients:local --new-version version`. This will deploy new clients and set implementation address on beacon. It also updates the existing addresses file `addresses/<chain-id>-<environment>.json` (for example `addresses/31337-localhost.json` if you are using a default local hardhat node) and outputs the upgrade log to the console.
 
 ### Using the protocol
 You can find the examples how to use all functions of the protocol in our test files in folder `test/protocol`.

docs/tasks.md

@@ -26,13 +26,13 @@ This builds the contracts and runs the code coverage. This is slower than testin
 ```npm run coverage```
 
 ### Deploy suite
-Deploy suite deploys protocol diamond, all facets, client and beacon, and initializes protcol diamond. We provide different npm scripts for different use cases.
+Deploy suite deploys protocol diamond, all facets, client and beacon, and initializes protocol diamond. We provide different npm scripts for different use cases.
 
 - **Hardhat network**. This deploys the built contracts to local network (mainly to test deployment script). Deployed contracts are discarded afterwards. 
 ```npm run deploy-suite:hardhat```
 - **local network**. This deploys the built contracts to independent instance of local network (e.g. `npx hardhat node`), so the deployed contracts can be used with other contracts/dapps in development. Step-by-step manual to use it is available [here](local-development.md). 
 ```npm run deploy-suite:local```
-- **internal test node**. This deploys the built contracts to custom test network. You need to modifiy `.env` with appropriate values for this to work. 
+- **internal test node**. This deploys the built contracts to custom test network. You need to modify `.env` with appropriate values for this to work. 
 ```npm run deploy-suite:test```
 - **Polygon Mumbai**. This deploys the built contracts to Polygon Mumbai. The Boson Protocol team uses separate sets of contracts on Polygon Mumbai for the test and staging environments. 
 ```npm run deploy-suite:polygon:mumbai-test``` 
@@ -56,40 +56,59 @@ After the protocol contracts are deployed, they should be verified on a block ex
 ### Upgrade facets
 Upgrade existing facets, add new facets or remove existing facets. We provide different npm scripts for different use cases. A script for Hardhat network does not exist. Since contracts are discarded after the deployment, they cannot be upgraded.
 
+> With v2.2.1, we introduced the migration scripts, which handle the upgrade. For versions above v2.2.1, use of migration script is preferred over the use of upgrade script, since those scripts also take care of any actions that needs to be done right before or after the upgrade. Refer to [migration section](#migrate) for details. 
+
 For upgrade to succeed you need an account with UPGRADER role. Refer to [Manage roles](#manage-roles) to see how to grant it.
 
 - **local network**. This upgrades the existing diamond on a independent instance of local network (e.g. `npx hardhat node`). Upgrade process is described [here](local-development.md#upgrade-facets). 
-```npm run upgrade-facets:local```
-- **internal test node**. This upgrades the existing diamond on a custom test network. You need to modifiy `.env` with appropriate values for this to work. 
-```npm run upgrade-facets:test```
+```npm run upgrade-facets:local --new-version version```
+- **internal test node**. This upgrades the existing diamond on a custom test network. You need to modify `.env` with appropriate values for this to work. 
+```npm run upgrade-facets:test -- --new-version version```
 - **Polygon Mumbai**. This upgrades the existing diamond on Polygon Mumbai. The Boson Protocol team uses separate sets of contracts on Polygon Mumbai for the test and staging environments. 
-```npm run upgrade-facets:polygon:mumbai-test``` 
-```npm run upgrade-facets:polygon:mumbai-staging```
+```npm run upgrade-facets:polygon:mumbai-test --new-version version``` 
+```npm run upgrade-facets:polygon:mumbai-staging --new-version version```
 - **Polygon Mainnet**. This upgrades the existing diamond on Polygon Mainnet. 
-```npm run upgrade-facets:polygon:mainnet```
+```npm run upgrade-facets:polygon:mainnet --new-version version```
 - **Ethereum Mainnet**. This upgrades the existing diamond on Ethereum Mainnet. 
-```npm run upgrade-facets:ethereum:mainnet```
+```npm run upgrade-facets:ethereum:mainnet --new-version version```
 
-Each upgrade requires correct config parameters. We provide [correct configurations for all release versions](). 
+Each upgrade requires correct config parameters. 
+- **<= v2.2.0**: Correct configurations for releases up to v2.2.0 are available [here](../test/upgrade/00_config.js). 
+- **>= v2.2.1**: Configurations for releases above v2.2.0 are part of their respective [migration scripts](../scripts/migrations/). 
+
 If you want to upgrade to any intermediate version (for example to a release candidate), you can use the same config as for the actual release, however it might result in interface clashes, which prevent subsequent upgrades. Workaround for this problem is to temporarily disable `onlyUninitialized` modifier on all contracts that clash. Since this is generally an unsafe operation, you should never do that in the production environment. Production should always be upgraded only to actual releases.
 
+### Migrate
+
+Migration scripts are available from release v2.2.1. They are used to migrate to a higher version of the protocol. They include the configuration needed for the upgrade, and they execute all required pre- and post- upgrade actions. The upgrade is done with the same script as in [Upgrade facets](#upgrade-facets) task. The main difference between migration and just plain upgrade script is that migration scripts are easier to use and leave less room for errors. Additionally, they allow to simulate the migration before actually performing it so any problems can be detected in advance.
+
+To use them, execute the following command
+```
+npx hardhat migrate version --network network --env environment [--dry-run]
+```
+
+- **version**: tag to which you want to migrate (e.g. v2.3.0). If the remote tag exists, it will overwrite the local one.
+- **network**: network where migration takes place. Must be defined in hardhat config. Current options are `localhost`, `test`, `mumbai`, `polygon`, `mainnet`.
+- **environment**: custom name for environment, used to distinguish if multiple instances are deployed on the same network. Typically one of `test`, `staging` and `prod`.
+- `--dry-run` is an optional flag. If added, the script locally simulates the migration process as it would happen on the actual network and environment, but none of contracts is really deployed and upgraded. It's recommended to run it before the upgrade. This script forks the latest possible block, which can result in performance issues. If you experience them, modify `scripts/migrations/dry-run.js` to use hardhat's default value (~30 less than actual block).
+
 ### Upgrade clients
 Upgrade existing clients (currently only BosonVoucher). Script deploys new implementation and updates address on beacon. 
 We provide different npm scripts for different use cases. A script for Hardhat network does not exist. Since contracts are discarded after the deployment, they cannot be upgraded. 
 For upgrade to succeed you need an account with UPGRADER role. Refer to [Manage roles](#manage-roles) to see how to grant it. 
 If you are not sure which contracts were changed since last deployment/upgrade, refer to [Detect changed contract](#detect-changed-contract) to see how to get the list of changed contracts.
 
 - **local network**. This upgrades the clients on a independent instance of local network (e.g. `npx hardhat node`). Upgrade process is described [here](local-development.md#upgrade-clients). 
-```npm run upgrade-clients:local```
+```npm run upgrade-clients:local --new-version version```
 - **internal test node**. This upgrades the clients on a custom test network. You need to modifiy `.env` with appropriate values for this to work. 
-```npm run upgrade-clients:test```
+```npm run upgrade-clients:test --new-version version```
 - **Polygon Mumbai**. This upgrades the clients on Polygon Mumbai. The Boson Protocol team uses separate sets of contracts on Polygon Mumbai for the test and staging environments. 
-```npm run upgrade-clients:polygon:mumbai-test``` 
-```npm run upgrade-clients:polygon:mumbai-staging```
+```npm run upgrade-clients:polygon:mumbai-test --new-version version``` 
+```npm run upgrade-clients:polygon:mumbai-staging --new-version version```
 - **Polygon Mainnet**. This upgrades the clients on Polygon Mainnet. 
-```npm run upgrade-clients:polygon:mainnet```
+```npm run upgrade-clients:polygon:mainnet --new-version version```
 - **Ethereum Mainnet**. This upgrades the clients on Ethereum Mainnet. 
-```npm run upgrade-clients:ethereum:mainnet```
+```npm run upgrade-clients:ethereum:mainnet --new-version version```
 
 ### Deploy mock authentication token
 Boson protocol support LENS and ENS as authentication method for seller's admin account. Public networks have LENS and ENS already deployed, but to use that funcionality on custom local or test nodes, you need to deploy the mock contract first. We provide the scripts for the following networks:

hardhat.config.js

@@ -6,6 +6,8 @@ const { task } = require("hardhat/config");
 require("@nomicfoundation/hardhat-toolbox");
 require("@nomiclabs/hardhat-web3");
 require("hardhat-contract-sizer");
+require("hardhat-preprocessor");
+require("hardhat-change-network");
 
 const lazyImport = async (module) => {
  return await require(module);
@@ -100,10 +102,25 @@ task("split-unit-tests-into-chunks", "Splits unit tests into chunks")
 task("migrate", "Migrates the protocol to a new version")
  .addPositionalParam("newVersion", "The version to migrate to")
  .addParam("env", "The deployment environment")
- .setAction(async ({ newVersion, env }) => {
- const { migrate } = await lazyImport(`./scripts/migrations/migrate_${newVersion}.js`);
+ .addFlag("dryRun", "Test the migration without deploying")
+ .setAction(async ({ newVersion, env, dryRun }) => {
+ let balanceBefore, getBalance;
+ if (dryRun) {
+ let setupDryRun;
+ ({ setupDryRun, getBalance } = await lazyImport(`./scripts/migrations/dry-run.js`));
+ ({ env, upgraderBalance: balanceBefore } = await setupDryRun(env));
+ }
 
+ const { migrate } = await lazyImport(`./scripts/migrations/migrate_${newVersion}.js`);
  await migrate(env);
+
+ if (dryRun) {
+ const balanceAfter = await getBalance();
+ const etherSpent = balanceBefore.sub(balanceAfter);
+
+ const formatUnits = require("ethers").utils.formatUnits;
+ console.log("Ether spent: ", formatUnits(etherSpent, "ether"));
+ }
  });
 
 module.exports = {

package.json

@@ -39,20 +39,20 @@
  "deploy-suite:polygon:mumbai-test": "npx hardhat clean && npx hardhat compile && npx hardhat deploy-suite --network mumbai --env test >> logs/mumbai-test.deploy.contracts.txt",
  "deploy-suite:polygon:mumbai-staging": "npx hardhat clean && npx hardhat compile && npx hardhat deploy-suite --network mumbai --env staging >> logs/mumbai-staging.deploy.contracts.txt",
  "deploy-suite:polygon:mainnet": "npx hardhat clean && npx hardhat compile && npx hardhat deploy-suite --network polygon --env prod >> logs/polygon.deploy.contracts.txt",
- "verify-suite:ethereum:mainnet": "npx hardhat verify-suite --network mainnet --chain-id 1 --env prod --env prod >> logs/mainnet.verify.contracts.txt",
+ "verify-suite:ethereum:mainnet": "npx hardhat verify-suite --network mainnet --chain-id 1 --env prod >> logs/mainnet.verify.contracts.txt",
  "verify-suite:polygon:mumbai-test": "npx hardhat verify-suite --network mumbai --chain-id 80001 --env test >> logs/mumbai-test.verify.contracts.txt",
  "verify-suite:polygon:mumbai-staging": "npx hardhat verify-suite --network mumbai --chain-id 80001 --env staging >> logs/mumbai-staging.verify.contracts.txt",
  "verify-suite:polygon:mainnet": "npx hardhat verify-suite --network polygon --chain-id 137 --env prod >> logs/polygon.verify.contracts.txt",
  "deploy-mocks:hardhat": "npx hardhat clean && npx hardhat compile && npx hardhat deploy-mock-nft-auth --network hardhat",
  "deploy-mocks:local": "npx hardhat clean && npx hardhat compile && npx hardhat deploy-mock-nft-auth --network localhost",
  "deploy-mocks:test": "npx hardhat clean && npx hardhat compile && npx hardhat deploy-mock-nft-auth --network test >> logs/test.deploy.mocks.txt",
- "upgrade-facets:local": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-facets --network localhost",
+ "upgrade-facets:local": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-facets --network localhost --env ''",
  "upgrade-facets:test": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-facets --network test --env test >> logs/test.upgrade.contracts.txt",
  "upgrade-facets:ethereum:mainnet": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-facets --network mainnet --env prod >> logs/mainnet.upgrade.contracts.txt",
  "upgrade-facets:polygon:mumbai-test": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-facets --network mumbai --env test >> logs/mumbai-test.upgrade.contracts.txt",
  "upgrade-facets:polygon:mumbai-staging": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-facets --network mumbai --env staging >> logs/mumbai-staging.upgrade.contracts.txt",
  "upgrade-facets:polygon:mainnet": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-facets --network polygon --env prod >> logs/polygon.upgrade.contracts.txt",
- "upgrade-clients:local": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-clients --network localhost",
+ "upgrade-clients:local": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-clients --network localhost --env ''",
  "upgrade-clients:test": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-clients --network test --env test >> logs/test.upgrade.contracts.txt",
  "upgrade-clients:ethereum:mainnet": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-clients --network mainnet --env prod >> logs/mainnet.upgrade.contracts.txt",
  "upgrade-clients:polygon:mumbai-test": "npx hardhat clean && npx hardhat compile && npx hardhat upgrade-clients --network mumbai --env test >> logs/mumbai-test.upgrade.contracts.txt",
@@ -89,6 +89,7 @@
  "ethereum-input-data-decoder": "^0.4.2",
  "glob": "^10.2.7",
  "hardhat": "^2.14.1",
+ "hardhat-change-network": "^0.0.7",
  "hardhat-contract-sizer": "^2.7.0",
  "hardhat-preprocessor": "^0.1.5",
  "husky": "^8.0.3",