docs: add runbook for confidential transfer with multisig (#29)

* docs: add runbook for confidential transfer with multisig

* feat: new generalized helper contract

* feat: updated helper contract implementation

* feat: allow both PRIVATE_KEY and MNEMONIC as env vars, PRIVATE_KEY taking precedence

* chore: update env variables names

* feat: update runbook for Safe and Aragon, and quick workaround

* docs: replace wrapper by confidential token terminology

* docs: minor improvement

* chore: fix indentation in helper contract

* chore: add prettier formatting for the helper contract

* chore: redeploy helper contracts and improved docs

* docs: minor improvement, advising against second transfer method

---------

Co-authored-by: jat <153528475+jatZama@users.noreply.github.com>
Co-authored-by: jatZama <josephandre.turk@zama.ai>

Author: melanciani

.prettierrc.yml

@@ -12,7 +12,6 @@ overrides:
   - files: "*.sol"
     options:
       compiler: "0.8.24"
-      parser: "solidity-parse"
       tabWidth: 4
   - files: "*.md"
     options:

contracts/fhevm-cli/.env.example

@@ -1,3 +1,7 @@
+# At least one of PRIVATE_KEY or MNEMONIC must be set.
+# PRIVATE_KEY takes precedence if both are provided.
 PRIVATE_KEY=
-MAINNET_RPC_URL=
-TESTNET_RPC_URL=
+MNEMONIC=
+MAINNET_ETHEREUM_RPC_URL=
+TESTNET_ETHEREUM_RPC_URL=
+ETHERSCAN_API_KEY=

contracts/fhevm-cli/.prettierrc

@@ -0,0 +1,12 @@
+{
+  "plugins": ["prettier-plugin-solidity"],
+  "overrides": [
+    {
+      "files": "*.sol",
+      "options": {
+        "printWidth": 120,
+        "tabWidth": 4
+      }
+    }
+  ]
+}

contracts/fhevm-cli/README.md

@@ -20,7 +20,7 @@ npx hardhat vars set ZAMA_FHEVM_API_KEY <your-api-key>
 
 # Request a user decryption
 
-Before running this command, ensure you have filled needed environement variables values inside your `.env` file: i.e `PRIVATE_KEY` for the user's private key requesting the user decryption, as well as `MAINNET_RPC_URL` (for mainnet) or `TESTNET_RPC_URL` (for testnet).
+Before running this command, ensure you have filled needed environement variables values inside your `.env` file: i.e `PRIVATE_KEY` for the user's private key (or alternatively, `MNEMONIC`) requesting the user decryption, as well as `MAINNET_ETHEREUM_RPC_URL` (for mainnet) or `TESTNET_ETHEREUM_RPC_URL` (for testnet).
 
 To request a user decryption, use a command similar to this example:
 
@@ -32,7 +32,7 @@ Replace the `handle` flag value from previous command by a handle you are allowe
 
 # Request an encryption
 
-Before running this command, ensure you have filled needed environement variables values inside your `.env` file: i.e just `MAINNET_RPC_URL` (for mainnet) or `TESTNET_RPC_URL` (for testnet).
+Before running this command, ensure you have filled needed environement variables values inside your `.env` file: i.e just `MAINNET_ETHEREUM_RPC_URL` (for mainnet) or `TESTNET_ETHEREUM_RPC_URL` (for testnet).
 
 To request an input encryption, use a command similar to this example:
 
@@ -44,7 +44,7 @@ Replace the `input-value` flag value from previous command by the custom value y
 
 # Request a public decryption
 
-Before running this command, ensure you have filled needed environement variables values inside your `.env` file: i.e just `MAINNET_RPC_URL` (for mainnet) or `TESTNET_RPC_URL` (for testnet).
+Before running this command, ensure you have filled needed environement variables values inside your `.env` file: i.e just `MAINNET_ETHEREUM_RPC_URL` (for mainnet) or `TESTNET_ETHEREUM_RPC_URL` (for testnet).
 
 To request a public decryption, use a command similar to this example:
 

contracts/fhevm-cli/contracts/FHEVMMultiSigHelper.sol

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: BSD-3-Clause-Clear
+pragma solidity ^0.8.24;
+
+import "@fhevm/solidity/lib/Impl.sol";
+import "@fhevm/solidity/config/ZamaConfig.sol";
+
+interface ISafe {
+    function getOwners() external view returns (address[] memory);
+}
+
+/// Helper contract to facilitate usage of fhevm with multisig accounts
+contract FHEVMMultiSigHelper {
+    /// @notice Returned if the list of input handles is empty
+    error EmptyInputHandles();
+
+    /// @notice Returned if the list of owners is empty
+    error EmptyOwners();
+
+    /// @notice Returned if the multisig address is null
+    error NullMultisig();
+
+    /// @notice Returned if one of the handles is null
+    error UninitializedHandle();
+
+    constructor() {
+        FHE.setCoprocessor(ZamaConfig.getEthereumCoprocessorConfig());
+    }
+
+    /// @notice Helper method to allow a list of handles to the owners of a Safe multisig contract and to the Safe itself
+    /// @param safeMultisig The Safe account address
+    /// @param inputHandles The list of initialized handles that we want to allow to the Safe and its owners, must be non-empty
+    /// @param inputProof The input proof corresponding to the list of inputHandles, must be non-empty
+    /// @dev It is possible to use this method with any (initialized, non-null) handle type
+    function allowForSafeMultiSig(
+        address safeMultisig,
+        bytes32[] memory inputHandles,
+        bytes memory inputProof
+    ) external {
+        address[] memory owners = ISafe(safeMultisig).getOwners();
+        uint256 numOwners = owners.length;
+        _allowHandlesForMultiSigAndOwners(safeMultisig, inputHandles, inputProof, owners, numOwners);
+    }
+
+    /// @notice More general helper method to allow a list of handles  to a custom list of owners and a multisig,
+    /// @notice but requires the user to manually input correct list of owners as argument
+    /// @notice WARNING: the user is responsible to enter the correct list of owners corresponding to the multisig
+    /// @notice Can also be used with non-Safe multisigs (eg Aragon, CoinbaseSmartWallet, etc)
+    /// @param multisig The multisig account address (could be a non-Safe account)
+    /// @param owners The list of owners, must be non-empty
+    /// @param inputHandles The list of initialized handles that we want to allow to the owners, must be non-empty
+    /// @param inputProof The input proof corresponding to the list of inputHandles, must be non-empty
+    /// @dev It is possible to use this same function with any (initialized, non-null) handle type
+    function allowForCustomMultiSigOwners(
+        address multisig,
+        address[] memory owners,
+        bytes32[] memory inputHandles,
+        bytes memory inputProof
+    ) external {
+        uint256 numOwners = owners.length;
+        if (numOwners == 0) revert EmptyOwners();
+        _allowHandlesForMultiSigAndOwners(multisig, inputHandles, inputProof, owners, numOwners);
+    }
+
+    /// @notice Internal function to allow list of input handles to the multisig account and its owners
+    /// @param multisig The multisig account address (could be a non-Safe account)
+    /// @param inputHandles The list of initialized handles that we want to allow to the owners, must be non-empty
+    /// @param inputProof The input proof corresponding to the list of inputHandles, must be non-empty
+    /// @param owners The list of owners, must be non-empty
+    /// @param numOwners The number of owners
+    function _allowHandlesForMultiSigAndOwners(
+        address multisig,
+        bytes32[] memory inputHandles,
+        bytes memory inputProof,
+        address[] memory owners,
+        uint256 numOwners
+    ) internal {
+        if (multisig == address(0)) revert NullMultisig();
+        uint256 inputHandlesLength = inputHandles.length;
+        if (inputHandlesLength == 0) revert EmptyInputHandles();
+        for (uint256 idxHandle = 0; idxHandle < inputHandlesLength; idxHandle++) {
+            bytes32 inputHandle = inputHandles[idxHandle];
+            if (inputHandle == bytes32(0)) revert UninitializedHandle();
+            Impl.verify(inputHandle, inputProof, FheType(uint8(inputHandle[30])));
+            Impl.allow(inputHandle, multisig);
+            for (uint256 idxOwner; idxOwner < numOwners; idxOwner++) {
+                Impl.allow(inputHandle, owners[idxOwner]);
+            }
+        }
+    }
+}

contracts/fhevm-cli/hardhat.config.ts

@@ -1,13 +1,35 @@
 import "@fhevm/hardhat-plugin";
 import "@nomicfoundation/hardhat-chai-matchers";
 import "@nomicfoundation/hardhat-ethers";
-import "dotenv/config";
+import "@nomicfoundation/hardhat-verify";
+import dotenv from "dotenv";
 import { HardhatUserConfig } from "hardhat/config";
+import { HttpNetworkAccountsUserConfig } from "hardhat/types/config";
+import { resolve } from "path";
 
+import "./tasks/allow";
+import "./tasks/deployment/multisig";
+import "./tasks/deployment/verify";
 import "./tasks/encrypt";
 import "./tasks/publicDecrypt";
 import "./tasks/userDecrypt";
 
+const NUM_ACCOUNTS = 10;
+
+const dotenvConfigPath: string = process.env.DOTENV_CONFIG_PATH || "./.env";
+dotenv.config({ path: resolve(__dirname, dotenvConfigPath) });
+
+const privateKey = process.env.PRIVATE_KEY;
+
+const mnemonic = process.env.MNEMONIC;
+if (!privateKey && !mnemonic) {
+  throw new Error("Please set either PRIVATE_KEY or MNEMONIC in your .env file");
+}
+
+const accounts: HttpNetworkAccountsUserConfig = privateKey
+  ? [privateKey]
+  : { count: NUM_ACCOUNTS, mnemonic: mnemonic!, path: "m/44'/60'/0'/0" };
+
 const config: HardhatUserConfig = {
   solidity: {
     version: "0.8.28",
@@ -18,15 +40,20 @@ const config: HardhatUserConfig = {
   networks: {
     // ChainID must be specified in order to be able to verify contracts using the fhevm hardhat plugin
     mainnet: {
-      url: process.env.MAINNET_RPC_URL || "",
+      url: process.env.MAINNET_ETHEREUM_RPC_URL || "",
       chainId: 1,
+      accounts,
     },
     // ChainID must be specified in order to be able to verify contracts using the fhevm hardhat plugin
     testnet: {
-      url: process.env.TESTNET_RPC_URL || "",
+      url: process.env.TESTNET_ETHEREUM_RPC_URL || "",
       chainId: 11155111,
+      accounts,
     },
   },
+  etherscan: {
+    apiKey: process.env.ETHERSCAN_API_KEY!,
+  },
 };
 
 export default config;