feat(smart-contract): Add doc and sample deploy upgrade with multisig

Author: CryptITAustria

infrastructure/smart-contracts/README.md

@@ -22,4 +22,33 @@ To deploy on a local node start the node with `pnpm run local` and change the `d
 - Change the proxy address to the contract that needs to be upgraded
 - Change the contract name to the new contract version (`esXai` -> `esXai2`) in ` const esXai2 = await ethers.getContractFactory("esXai2");`
 - Create a new upgrade command in `package.json`
-- Run the script with `pnpm run upgrade-esxai`
+- Run the script with `pnpm run upgrade-esxai`
+
+
+## MultiSig deployments
+
+### Upgrade an existing proxy to a new implementation
+
+If the beacon proxy admin owner is a multisig we use `upgrades.upgradeProxy` anymore as it will throw the error `Caller is not owner` fro the beacon proxy contract.
+For multisig deployments we need to call `upgrades.prepareUpgrade`, then take the implementation and build the transaction on the multisig contract.
+If there is an initialize function to be called with the upgrade, we will call `upgradeAndCall` to the beacon proxy contract, this will require sending the encoded function call. For this we have a helper function `./utils/getUpgradeTransactionData.mjs`. It will create the encoded function call data to be sent with the multisig transaction.
+From `upgrades.prepareUpgrade` we will get the new implementation address to upgrade to, we have to verify this implementation.
+
+### Deploy a new contract
+
+Deploy a new proxy will use the existing beacon proxy admin contract which is owned by the multisig, this wokrs the same no matter who the beacon proxy admin is.
+
+### How to upgrade using the multisig account
+
+- Login on the multisig webapp
+- Create a new transaction (transaction builder)
+- Enter Beacon proxy contract address 
+  - `0xD88c8E0aE21beA6adE41A41130Bb4cd43e6b1723` ArbitrumOne
+  - `0x2b0AE314A4CE6BE6E47a88b758a0b6cD7C143C5A` ArbitrumSepolia
+- Enter Beacon proxy ABI
+- Select Contract method to call:
+  - `upgrade` for upgrades without calling any initializer
+  - `upgradeAndCall` for upgrades with calling an initializer or migration function
+- Enter proxy address of the contract to upgrade
+- Enter the new implementation address (from running `upgrades.prepareUpgrade`)
+- When calling `upgradeAndCall` enter the **data** generated from encoding the function signature with the call data (`getUpgradeTransactionData.mjs`)

infrastructure/smart-contracts/scripts/prepareUpgrade.mjs

@@ -0,0 +1,49 @@
+import hardhat from "hardhat";
+import { getUpgradeAndCallData } from "./utils/getUpgradeTransactionData.mjs";
+const { ethers, upgrades } = hardhat;
+
+const PROXY_TO_UPGRADE_ADDRESS = "0xProxyAddressToUpgrade";
+const NEW_IMPLEMENTATION_NAME = "ContractName";
+
+async function main() {
+    const [deployer] = (await ethers.getSigners());
+    const deployerAddress = await deployer.getAddress();
+    console.log("Deployer address", deployerAddress);
+
+    console.log(`Deploy implementation ${NEW_IMPLEMENTATION_NAME}...`);
+    
+    const contractInstance = await ethers.getContractFactory(NEW_IMPLEMENTATION_NAME);
+    const implementationAddress = await upgrades.prepareUpgrade(PROXY_TO_UPGRADE_ADDRESS, contractInstance);
+
+    console.log(`DEPLOYED IMPLEMENTATION ${NEW_IMPLEMENTATION_NAME}`);
+    console.log(implementationAddress);
+
+    const upgradeTXData = getUpgradeAndCallData(
+        {
+            upgradeCallFunctionName: "initialize",
+            upgradeCallFunctionSignature: "function initialize(address _esXaiBurnFoundationRecipient, uint256 _esXaiBurnFoundationBasePoints)",
+            upgradeCallFunctionParams: ["0xaf88d065e77c8cC2239327C5EDb3A432268e5831", 100n]
+        }
+    );
+
+    console.log("MultiSig transaction builder arguments:");
+    console.log(`Proxy: ${PROXY_TO_UPGRADE_ADDRESS}`);
+    console.log(`Implementation: ${implementationAddress}`);
+    console.log(`data: ${upgradeTXData}`);
+
+    console.log("verifying implementation...");
+
+    await run("verify:verify", {
+        address: implementationAddress,
+        constructorArguments: [],
+    });
+
+    console.log("verified")
+}
+
+// We recommend this pattern to be able to use async/await everywhere
+// and properly handle errors.
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

infrastructure/smart-contracts/scripts/utils/getUpgradeTransactionData.mjs

@@ -0,0 +1,28 @@
+import hardhat from "hardhat";
+const { ethers } = hardhat;
+
+/**
+ * Create upgrade call data
+ * 
+ * @param {string} [opts.upgradeCallFunctionName] - e.g. "initialize"
+ * @param {string} [opts.upgradeCallFunctionSignature] - e.g. "function initialize(address,uint256)"
+ * @param {Array}  [opts.upgradeCallFunctionParams] - e.g. ["0x1234...", 42]
+ * @returns {string} The ABI-encoded transaction data
+ */
+export function getUpgradeAndCallData(
+  {
+    upgradeCallFunctionName,
+    upgradeCallFunctionSignature,
+    upgradeCallFunctionParams
+  } = {}
+) {
+
+  const initIface = new ethers.Interface([upgradeCallFunctionSignature]);
+  const initData = initIface.encodeFunctionData(
+    upgradeCallFunctionName,
+    upgradeCallFunctionParams
+  );
+
+  return initData;
+
+}