chore(gateway-contracts): clean pausing mechanism and add documentation (#894)

* chore(gateway-contracts): clean pausing mechanism and add documentation

Author: melanciani

gateway-contracts/.env.example

@@ -118,6 +118,16 @@ HOST_CHAIN_ACL_ADDRESS_3="0xabcdef1234567890abcdef1234567890abcdef12" # (address
 HOST_CHAIN_NAME_3="Host chain 2028" # (string)
 HOST_CHAIN_WEBSITE_3="https://host-chain-2028.com" # (string)
 
+# Pausers
+# The number of pausers must be lower or equal to the number of pausers' address defined below
+NUM_PAUSERS="2"
+
+# Pauser 1
+PAUSER_ADDRESS_0="0x6591319B97979Acc59b7191A8B4Ec381375bFc92" # accounts[23] (address)
+
+# Pauser 2
+PAUSER_ADDRESS_1="0xb19e21437c47A541842bB84b018d3955462B35De" # accounts[24] (address)
+
 # FHE Parameters
 FHE_PARAMS_NAME="TEST" # (string)
 FHE_PARAMS_DIGEST="0xd61fa44c57b6e7526a46e1072d63332ab4eb38e050fe54dd51fe995f9055c354" # (bytes32)
@@ -128,7 +138,6 @@ FHE_PARAMS_DIGEST="0xd61fa44c57b6e7526a46e1072d63332ab4eb38e050fe54dd51fe995f905
 # For tests, this address is read directly from the addresses/.env.gateway file, so the value in this file is ignored.
 GATEWAY_CONFIG_ADDRESS="0xC7D45661a345eC5cA0e8521CFEF7e32FDA0Daa68" # (address)
 
-# Pausers
-NUM_PAUSERS="1"
-PAUSER_ADDRESS_0="0xa44366bAA26296c1409AD1e284264212029F02f1" # accounts[2] (address)
-PAUSER_PRIVATE_KEY_0="0x7ae52cf0d3011ef7fecbe22d9537aeda1a9e42a0596e8def5d49970eb59e7a40" # accounts[2], private key (bytes32)
+# The first pauser's private key
+# This is required for local tests and running the pausing task. It must correspond to one of the pauser's private key
+PAUSER_PRIVATE_KEY="0x3588ffb4f4d9bea785a012b895543fe68f2d580a9d449decc91a25878064079a" # accounts[22], private key (bytes32)

gateway-contracts/Makefile

@@ -22,7 +22,7 @@ coverage: clean
 	DOTENV_CONFIG_PATH=$(ENV_PATH) npx hardhat coverage
 
 get-accounts:
-	DOTENV_CONFIG_PATH=$(ENV_PATH) npx hardhat get-accounts --num-accounts 20
+	DOTENV_CONFIG_PATH=$(ENV_PATH) npx hardhat get-accounts
 
 start-local-node: clean
 	DOTENV_CONFIG_PATH=$(ENV_PATH) npx hardhat node --port 8757
@@ -82,10 +82,14 @@ conformance: prettier update-bindings update-mocks update-selectors
 deploy-empty-proxies:
 	DOTENV_CONFIG_PATH=$(ENV_PATH) npx hardhat task:deployEmptyUUPSProxies
 
+# Deploy the pauser set contract
 deploy-pauser-set:
 	DOTENV_CONFIG_PATH=$(ENV_PATH) npx hardhat compile:specific --contract contracts/immutable
 	DOTENV_CONFIG_PATH=$(ENV_PATH) npx hardhat task:deployPauserSet
 
+# Deploy the contracts needed for deploying the gateway contracts
+deploy-setup-contracts: deploy-empty-proxies deploy-pauser-set
+
 # Ensure that the empty proxy addresses exists as these are required for contract compilation.
 # In addition, ensure that the addresses match the ones used in local development in order to
 # avoid discrepancies between local and CI (e.g., when generating and checking rust bindings).

gateway-contracts/contracts/GatewayConfig.sol

@@ -41,9 +41,8 @@ contract GatewayConfig is IGatewayConfig, Ownable2StepUpgradeable, UUPSUpgradeab
     /// @notice The contract's variable storage struct (@dev see ERC-7201)
     /// @custom:storage-location erc7201:fhevm_gateway.storage.GatewayConfig
     struct GatewayConfigStorage {
-        /// @notice The pauser's address
-        /// @notice TODO: deprecated, to remove for mainnet
-        address pauser;
+        /// @notice DEPRECATED: to remove for mainnet
+        address pauser; // DEPRECATED
         /// @notice The KMS nodes' transaction sender addresses
         mapping(address kmsTxSenderAddress => bool isKmsTxSender) _isKmsTxSender;
         /// @notice The KMS nodes' signer addresses

gateway-contracts/contracts/immutable/PauserSet.sol

@@ -23,18 +23,18 @@ contract PauserSet is IPauserSet, GatewayConfigChecks {
 
     /// @dev See {IPauserSet-addPauser}.
     function addPauser(address account) external onlyGatewayOwner {
-        if (account == address(0)) revert PauserCannotBeNull();
-        if (pausers[account]) revert AccountIsAlreadyPauser(account);
+        if (account == address(0)) revert InvalidNullPauser();
+        if (pausers[account]) revert AccountAlreadyPauser(account);
         pausers[account] = true;
-        emit NewPauser(account);
+        emit AddPauser(account);
     }
 
     /// @dev See {IPauserSet-removePauser}.
     function removePauser(address account) external onlyGatewayOwner {
-        if (account == address(0)) revert PauserCannotBeNull();
-        if (!pausers[account]) revert AccountIsNotPauser(account);
+        if (account == address(0)) revert InvalidNullPauser();
+        if (!pausers[account]) revert AccountNotPauser(account);
         pausers[account] = false;
-        emit RemovedPauser(account);
+        emit RemovePauser(account);
     }
 
     /// @dev See {IPauserSet-isPauser}.

gateway-contracts/contracts/interfaces/IGatewayConfig.sol

@@ -240,7 +240,7 @@ interface IGatewayConfig {
 
     /**
      * @notice Check if the account is a pauser.
-     * @return whether or not the account is a pauser.
+     * @return Whether or not the account is a pauser.
      */
     function isPauser(address account) external view returns (bool);
 

gateway-contracts/contracts/interfaces/IPauserSet.sol

@@ -11,30 +11,30 @@ interface IPauserSet {
      * @notice Emitted when a new pauser is added.
      * @param account The address of the new pauser.
      */
-    event NewPauser(address account);
+    event AddPauser(address account);
 
     /**
      * @notice Emitted when an old pauser is removed.
      * @param account The address of the old pauser.
      */
-    event RemovedPauser(address account);
+    event RemovePauser(address account);
 
     /**
      * @notice Error indicating that the given account is already a pauser.
      * @param account The address of the account.
      */
-    error AccountIsAlreadyPauser(address account);
+    error AccountAlreadyPauser(address account);
 
     /**
      * @notice Error indicating that the given account is not a pauser.
      * @param account The address of the account.
      */
-    error AccountIsNotPauser(address account);
+    error AccountNotPauser(address account);
 
     /**
      * @notice Error indicating that the given account is the null address.
      */
-    error PauserCannotBeNull();
+    error InvalidNullPauser();
 
     /**
      * @notice Adds a new account as pauser.

gateway-contracts/contracts/mocks/GatewayConfigMock.sol

@@ -4,18 +4,13 @@ import "../shared/Structs.sol";
 
 contract GatewayConfigMock {
     event InitializeGatewayConfig(
-        address pauser,
         ProtocolMetadata metadata,
         uint256 mpcThreshold,
         KmsNode[] kmsNodes,
         Coprocessor[] coprocessors,
         Custodian[] custodians
     );
 
-    event ReinitializeGatewayConfigV2(Custodian[] custodians);
-
-    event UpdatePauser(address newPauser);
-
     event UpdateMpcThreshold(uint256 newMpcThreshold);
 
     event UpdatePublicDecryptionThreshold(uint256 newPublicDecryptionThreshold);
@@ -29,7 +24,6 @@ contract GatewayConfigMock {
     event UnpauseAllGatewayContracts();
 
     function initializeFromEmptyProxy(
-        address initialPauser,
         ProtocolMetadata memory initialMetadata,
         uint256 initialMpcThreshold,
         uint256 initialPublicDecryptionThreshold,
@@ -38,22 +32,13 @@ contract GatewayConfigMock {
         Coprocessor[] memory initialCoprocessors,
         Custodian[] memory initialCustodians
     ) public {
-        address pauser;
         ProtocolMetadata memory metadata;
         uint256 mpcThreshold;
         KmsNode[] memory kmsNodes = new KmsNode[](1);
         Coprocessor[] memory coprocessors = new Coprocessor[](1);
         Custodian[] memory custodians = new Custodian[](1);
 
-        emit InitializeGatewayConfig(pauser, metadata, mpcThreshold, kmsNodes, coprocessors, custodians);
-    }
-
-    function reinitializeV2(Custodian[] memory custodians) public {
-        emit ReinitializeGatewayConfigV2(custodians);
-    }
-
-    function updatePauser(address newPauser) external {
-        emit UpdatePauser(newPauser);
+        emit InitializeGatewayConfig(metadata, mpcThreshold, kmsNodes, coprocessors, custodians);
     }
 
     function updateMpcThreshold(uint256 newMpcThreshold) external {

gateway-contracts/docs/getting-started/contracts/gateway_config.md

@@ -6,7 +6,7 @@ Several settings are stored in the contract, which can be separated in several c
 
 - [Protocol metadata](#protocol-metadata)
 - [Operators](#operators)
-- [Governance accounts](#governance-accounts)
+- [Governance](#governance)
 - [Host chains](#host-chains)
 
 Except for host chains, they are all set when deploying the `GatewayConfig` contract. Once set, some (but not all) of them can be updated.
@@ -108,34 +108,31 @@ Additionally, the transaction sender address is used for identifying an operator
 - `getKmsNode(address kmsTxSenderAddress)`: get a KMS node's metadata.
 - `getCoprocessor(address coprocessorTxSenderAddress)`: get a coprocessor's metadata.
 
-## Governance accounts
+## Governance
 
-The fhevm Gateway protocol is governed by two accounts:
+The fhevm Gateway protocol is governed by the following roles:
 
 - `owner`: account that can perform restricted actions
-- `pauser`: account that can pause contract functions
+- `pausers`: accounts that can pause contract functions
 
 ### Owner
 
 The owner is first set as the account that deploys the contracts (the deployer). It is allowed to perform several restricted actions :
 
 - upgrade the contracts
-- update the [pauser](#pauser)
+- update the pausers (see [Pausers](./pauser_set.md))
 - add [host chains](#host-chains)
 - trigger a KMS public material generation (see [KmsManagement](./kms_management.md#public-material-generation))
 - update KMS-related parameters (see [KmsManagement](./kms_management.md#store-parameters))
 
 The owner is handled by OpenZeppelin's `Ownable2StepUpgradeable` contract. In particular, this means that the deployer can transfer its ownership to another account in a two-step process.
 
-### Pauser
+### Pausers
 
-**Important**: currently, the pauser is not used as the pausing mechanism is not implemented yet.
+Details about pausers are available in the following documentation:
 
-The pauser is an account that can pause contract functions. A paused function means that any transaction sent to trigger it will be reverted.
-
-Nothing prevents the pauser from being the owner itself. However, in practice, it can be useful to use different accounts. For example, if they are both governed by multi-sig contracts, the pauser can be set to a lower threshold than the owner in order to pause the protocol quicker in case of emergency.
-
-Currently, it is set at deployment and can be updated by the owner later on.
+- [PauserSet](./pauser_set.md)
+- [Pausing](../pausing/pausing.md)
 
 ### Host chains
 

gateway-contracts/docs/getting-started/contracts/pauser_set.md

@@ -0,0 +1,20 @@
+# PauserSet contract
+
+This section describes the `PauserSet` contract. It is used to manage the pausers, addresses that are allowed to pause some of the Gateway contracts.
+
+## Pausers
+
+Pausers are account addresses registered in the `PauserSet` contract. They are expected to be hot wallets controlled by the [operators](./gateway_config.md#operators) of the fhevm Gateway protocol.
+
+They are allowed to pause some of the Gateway contracts. See [Pausing](../pausing/pausing.md) for more details.
+
+## PauserSet
+
+The `PauserSet` contract allows to:
+
+- add a pauser: `addPauser`
+- remove a pauser: `removePauser`
+- swap a pauser with another address: `swapPauser`
+- check if an address is a pauser: `isPauser`
+
+It is deployed as an immutable contract and its address is stored in the `GatewayConfig` contract.

gateway-contracts/docs/getting-started/deployment/env_variables.md

@@ -24,7 +24,6 @@ Here's the complete list of environment variables used for deploying the FHEVM g
 | ----------------------------------- | -------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
 | `PROTOCOL_NAME`                     | Name of the protocol to display              | string        | -                                                                                                   | -                                                                             |
 | `PROTOCOL_WEBSITE`                  | Website of the protocol to display           | string        | -                                                                                                   | -                                                                             |
-| `PAUSER_ADDRESS`                    | Address of the pauser                        | address       | -                                                                                                   | -                                                                             |
 | `MPC_THRESHOLD`                     | MPC threshold (cryptographic parameter)      | uint256       | -                                                                                                   | Must be strictly less than the number of KMS nodes registered                 |
 | `PUBLIC_DECRYPTION_THRESHOLD`       | Public decryption threshold                  | uint256       | -                                                                                                   | Must be non-null and less than or equal to the number of KMS nodes registered |
 | `USER_DECRYPTION_THRESHOLD`         | User decryption threshold                    | uint256       | -                                                                                                   | Must be non-null and less than or equal to the number of KMS nodes registered |
@@ -42,6 +41,8 @@ Here's the complete list of environment variables used for deploying the FHEVM g
 | `HOST_CHAIN_ACL_ADDRESS_{k}`        | ACL address of the host chain `k`            | address       | -                                                                                                   | If `k` >= `NUM_HOST_CHAINS`, the variable is ignored                          |
 | `HOST_CHAIN_NAME_{k}`               | Name of the host chain `k`                   | string        | -                                                                                                   | If `k` >= `NUM_HOST_CHAINS`, the variable is ignored                          |
 | `HOST_CHAIN_WEBSITE_{k}`            | Website of the host chain `k`                | string        | -                                                                                                   | If `k` >= `NUM_HOST_CHAINS`, the variable is ignored                          |
+| `NUM_PAUSERS`                       | Number of pausers to register                | -             | -                                                                                                   | Must be at least the number of pausers registered below                       |
+| `PAUSER_ADDRESS_{l}`                | Address of the pauser `l`                    | address       | -                                                                                                   | If `l` >= `NUM_PAUSERS`, the variable is ignored                              |
 | `FHE_PARAMS_NAME`                   | Name of the parameters to use for FHE keys   | string        | -                                                                                                   | Not used yet                                                                  |
 | `FHE_PARAMS_DIGEST`                 | Digest of the parameters to use for FHE keys | bytes32       | -                                                                                                   | Not used yet                                                                  |
 | `DEPLOYER_PRIVATE_KEY`              | Private key for contract deployment          | bytes32       | -                                                                                                   | -                                                                             |
@@ -68,12 +69,6 @@ PROTOCOL_NAME="Protocol" # (string)
 PROTOCOL_WEBSITE="https://protocol.com" # (string)
 ```
 
-- Pauser:
-
-```bash
-PAUSER_ADDRESS="0xa44366bAA26296c1409AD1e284264212029F02f1" # (address)
-```
-
 - KMS Thresholds:
 
 ```bash