docs: pause process with multisig (#1482)

Co-authored-by: Klaus @ LambdaClass <[email protected]> Co-authored-by: Marcos Nicolau <[email protected]> Co-authored-by: Urix <[email protected]>
yetanotherco · Nov 29, 2024 · 71a8435 · 71a8435
1 parent 1599024
commit 71a8435
Show file tree

Hide file tree

Showing 19 changed files with 290 additions and 0 deletions.
diff --git a/Makefile b/Makefile
@@ -117,6 +117,7 @@ unpause_batcher_payment_service:
 get_paused_state_batcher_payments_service:
 	@echo "Getting paused state of Batcher Payments Service contract..."
 	. contracts/scripts/get_paused_state_batcher_payments_service.sh
+
 anvil_upgrade_initialize_disable_verifiers:
 	@echo "Initializing disabled verifiers..."
 	. contracts/scripts/anvil/upgrade_disabled_verifiers_in_service_manager.sh

diff --git a/contracts/scripts/get_paused_state_batcher_payments_service.sh b/contracts/scripts/get_paused_state_batcher_payments_service.sh
@@ -0,0 +1,14 @@
+#!/bin/bash
+
+if  [ -z "$BATCHER_PAYMENT_SERVICE" ]; then
+    echo "BATCHER_PAYMENT_SERVICE env var is not set"
+    exit 1
+fi
+
+if  [ -z "$RPC_URL" ]; then
+    echo "RPC_URL env var is not set"
+    exit 1
+fi
+
+is_paused=$(cast call $BATCHER_PAYMENT_SERVICE "paused()(bool)" --rpc-url $RPC_URL)
+echo Batcher Payments Paused state: $is_paused
diff --git a/docs/0_internal/4_a_pause_contracts.md b/docs/0_internal/4_a_pause_contracts.md
@@ -0,0 +1,75 @@
+# Pause Contracts
+This doc contains a guide on how to use the Pausable functionality of Aligned.
+
+To run the make targets specified in this guide, you must first have the relevant following env vars under `contracts/scripts/.env`:
+```
+export RPC_URL=<rpc_url>
+export ALIGNED_SERVICE_MANAGER=<aligned_contract_address>
+export ALIGNED_SERVICE_MANAGER_PAUSER_PRIVATE_KEY=<aligned_service_manager_pauser_private_key>
+export BATCHER_PAYMENT_SERVICE=<payment_service_contract_address>
+export BATCHER_PAYMENT_SERVICE_PAUSER_PRIVATE_KEY=<batcher_payment_service_pauser_private_key>
+```
+
+## Aligned Service Manager
+
+Aligned Service Manager is granulary pausable, which means you can pause the whole contract, or only specific functions. For this,
+Aligned uses the Pauser Registry contract provided by Eigenlayer. This contract stores the role of different accounts, so
+you can have X pausers and Y unpausers.
+
+To interact with it you can:
+
+- Get current paused state:
+```
+make get_paused_state_aligned_service_manager
+```
+
+- Pause or Unpause the whole aligned service manager contract:
+```
+make pause_all_aligned_service_manager
+```
+```
+make unpause_all_aligned_service_manager
+```
+
+- Pause only specific functions, receiving a list of the functions to pause/remain paused:
+  For example, if you want to pause functions 0, 2 and 3, you can run
+```
+contracts/scripts/pause_aligned_service_manager.sh 0 2 3
+```
+Then, if you want to unpause, for example, function 2, you must run
+```
+contracts/scripts/unpause_aligned_service_manager.sh 0 3
+```
+
+Note: when executing a Pause, you can only ADD functions to the paused list, and when executing an Unpause, you can only REMOVE functions from the paused list. This is because the base pausable contract has different ACL for Pausers and Unpausers.
+
+Note: the list of pausable functions and their numbers can be seen in the `AlignedLayerServiceManager.sol` contract. But the list is the following:
+
+0. createNewTask
+1. respondToTaskV2
+2. verifyBatchInclusion
+3. withdraw
+4. depositToBatcher
+5. receive
+
+## BatcherPaymentsService
+
+BatcherPayments is also pausable, but without so much detail. You can either pause or unpause the contract running the following:
+
+- Get current paused state:
+```
+make get_paused_state_batcher_payments_service
+```
+
+```
+make pause_batcher_payment_service
+```
+```
+make unpause_batcher_payment_service
+```
+
+And this will either pause or unpause the following functions:
+- createNewTask
+- unlock
+- lock
+- withdraw
diff --git a/docs/0_internal/4_b_1_propose_pause.md b/docs/0_internal/4_b_1_propose_pause.md
@@ -0,0 +1,99 @@
+# Propose the Transaction for Pause using Multisig
+
+If you want to pause the contracts, you can propose the pause transaction using the multisig wallet.
+
+## Prerequisites
+
+- You need to have deployed the contracts following the [Deploy Contracts Guide](./2_deploy_contracts.md).
+
+## Propose transaction for Pause AlignedLayerServiceManager
+
+To propose the pause transaction you can follow the steps below:
+
+1. Go to [Safe](https://app.safe.global/home)
+
+2. Click on `New transaction` -> `Transaction Builder`
+
+   ![New transaction](./images/4_b_1_pause_1.png)
+
+   ![Transaction Builder](./images/4_b_1_pause_2.png)
+
+3. . Get the `AlignedLayerServiceManager` address from ```contracts/script/output/mainnet/alignedlayer_deployment_output.json``` or ```contracts/script/output/holesky/alignedlayer_deployment_output.json``` or ```contracts/script/output/sepolia/alignedlayer_deployment_output.json```
+
+4. Paste the `AlignedLayerServiceManager` address on `Enter Address or ENS Name`
+
+   ![Enter Address](./images/4_b_1_pause_3.png)
+
+5. As this is a Proxy contract, choose `Use Implementation ABI`
+
+   ![Use Implementation ABI](./images/4_b_1_pause_4.png)
+
+6. In `contract method selector` choose `pauseAll()`
+
+   ![Choose pause](./images/4_b_1_pause_5.png)
+
+7. Click on `+ Add new transaction`
+
+   You should see the new transaction to be executed
+
+8. Click on `Create batch` to create the transaction.
+
+9. Simulate the transaction by clicking on `Simulate`
+
+10. If everything is correct, click on `Send batch` to send the transaction.
+
+11. Simulate the transaction, and if everything is correct, click on `Sign`.
+
+   ![Send batch](./images/4_b_1_pause_6.png)
+
+> [!NOTE]
+> In the `call` field, you will see `fallback`.
+
+12. Wait for the transaction to be executed. You can check the transaction status on the `Transactions` tab.
+
+
+## Propose transaction for Pause BatcherPaymentService
+
+To propose the pause transaction you can follow the steps below:
+
+1. Create the pause transaction on [Safe](https://app.safe.global/home)
+
+2. Click on `New transaction` -> `Transaction Builder`
+
+   ![New transaction](./images/4_b_1_pause_1.png)
+
+   ![Transaction Builder](./images/4_b_1_pause_2.png)
+
+3. Get the `BatcherPaymentService` address from ```contracts/script/output/mainnet/alignedlayer_deployment_output.json``` or ```contracts/script/output/holesky/alignedlayer_deployment_output.json``` or ```contracts/script/output/sepolia/alignedlayer_deployment_output.json```
+
+4. Paste the `BatcherPaymentService` address on `Enter Address or ENS Name`
+
+   ![Enter Address](./images/4_b_1_pause_3.png)
+
+5. As this is a Proxy contract, choose `Use Implementation ABI`
+
+   ![Use Implementation ABI](./images/4_b_1_pause_4.png)
+
+6. In `contract method selector` choose `pause()`
+
+   ![Choose pause](./images/4_b_1_pause_8.png)
+
+7. Then click on `+ Add new transaction`
+
+   You should see the new transaction to be executed. Then click on `Create batch` to create the transaction.
+
+   ![Add new transaction](./images/4_b_1_pause_9.png)
+
+8. Review and confirm you are interacting with the correct `BatcherPaymentService` contract and you are calling the `pause` function.
+
+   ![Review transaction](./images/4_b_1_pause_10.png)
+
+9. Simulate the transaction by clicking on `Simulate`
+
+10. If everything is correct, click on `Send batch` to send the transaction.
+
+11. Review the transaction and click on `Sign` to sign the transaction.
+
+   ![Send batch](./images/4_b_1_pause_11.png)
+
+12. If the transaction is correctly created, you have to wait until the required Multisig member signs the transaction to send it. For this, you can follow [the following guide](./4_b_2_approve_pause.md)
diff --git a/docs/0_internal/4_b_2_approve_pause.md b/docs/0_internal/4_b_2_approve_pause.md
@@ -0,0 +1,54 @@
+# Approve the Pause Transaction
+
+Once the transaction is proposed, the multisig owners must approve the transaction.
+
+## Approve the Pause for AlignedLayerServiceManager
+
+1. Go to [Safe](https://app.safe.global/home) and connect your wallet.
+
+2. Go to the `Transactions` tab and find the transaction that was proposed.
+
+3. Get the ```pauseAll()``` signature by running:
+
+   ```bash
+   cast calldata "pauseAll()"
+   ```
+
+   It must show you ```0x595c6a67```.
+
+4. Click on the transaction, and then click on ```Advanced Details```.
+
+    ![Check details](images/4_b_2_approve_1.png)
+
+5. Copy the ```Raw Data```, paste it in a text editor and verify it is the same value as the one you got in step 3.
+
+6. If the data is correct, click on the `Confirm` button.
+
+7. Simulate the transaction. If everything is correct, click on the `Sign` button.
+
+   ![Sign transaction](images/4_b_2_approve_3.png)
+
+8. Once the transaction is executed, the pause will be effective.
+
+## Approve the Pause for BatcherPaymentService
+
+1. Go to [Safe](https://app.safe.global/home) and connect your wallet.
+
+2. Go to the `Transactions` tab and find the transaction that was proposed.
+
+3. Click on the transaction and validate the data is correct. 
+
+    The called function must be `pause` and the contract address must be the `BatcherPaymentService` address.
+
+   ![Check details](images/4_b_2_approve_2.png)
+
+   Get the `BatcherPaymentService` address from ```contracts/script/output/mainnet/alignedlayer_deployment_output.json``` or ```contracts/script/output/holesky/alignedlayer_deployment_output.json``` or ```contracts/script/output/sepolia/alignedlayer_deployment_output.json```
+
+4. If the data is correct, click on the `Confirm` button.
+
+5. Simulate the transaction. If everything is correct, click on the `Sign` button.
+
+   ![Sign transaction](images/4_b_2_approve_3.png)
+
+6. Once the transaction is executed, the pause will be effective.
+
diff --git a/docs/0_internal/4_b_pause_contracts_with_multisig.md b/docs/0_internal/4_b_pause_contracts_with_multisig.md
@@ -0,0 +1,47 @@
+# Pause Contracts with a Multisig
+
+> [!WARNING]  
+> Safe Multisig Wallet is not currently supported in Holesky Testnet.
+> For this reason, we deployed EigenLayer contracts in Sepolia to test the upgrade on AlignedLayer Contracts.
+
+> [!NOTE]
+> EigenLayer Sepolia contracts information is available in `contracts/script/output/sepolia/eigenlayer_deployment_output.json`.
+
+> [!NOTE]
+> You can find a guide on how to Deploy the contracts [here](./2_deploy_contracts.md).
+
+This guide is for pausing contracts deployed using a Multisig wallet. If you deployed the contract without a Multisig wallet, you can follow the [Pause Contracts](./4_a_pause_contracts.md) tutorial.
+
+In this guide we pause and unpause the AlignedLayerServiceManager and BatcherPaymentService contracts using a multisig wallet.
+
+## Prerequisites
+
+- You need to have installed
+    - git
+    - make
+    - [jq](https://jqlang.github.io/jq/download/)
+
+- Clone the repository
+
+   ```
+   git clone https://github.com/yetanotherco/aligned_layer.git
+   ```
+
+- Install foundry
+
+    ```shell
+    make install_foundry
+    foundryup -v nightly-a428ba6ad8856611339a6319290aade3347d25d9
+    ```
+
+## Steps for Pausing
+
+1. Propose the transaction with the multisig following the [Propose Pause Guide](./4_b_1_propose_pause.md).
+
+2. After the pause is proposed, multisig participants can approve the pause following the [Approve Pause Guide](./4_b_2_approve_pause.md).
+
+## Steps for Unpausing
+
+1. Propose the transaction with the multisig following the [Propose Unpause Guide](./4_b_3_propose_unpause.md).
+
+2. After the unpause is proposed, multisig participants can approve the unpause following the [Approve Unpause Guide](./4_b_4_approve_unpause.md).
diff --git a/docs/0_internal/images/4_b_1_pause_1.png b/docs/0_internal/images/4_b_1_pause_1.png
diff --git a/docs/0_internal/images/4_b_1_pause_10.png b/docs/0_internal/images/4_b_1_pause_10.png
diff --git a/docs/0_internal/images/4_b_1_pause_11.png b/docs/0_internal/images/4_b_1_pause_11.png
diff --git a/docs/0_internal/images/4_b_1_pause_2.png b/docs/0_internal/images/4_b_1_pause_2.png
diff --git a/docs/0_internal/images/4_b_1_pause_3.png b/docs/0_internal/images/4_b_1_pause_3.png
diff --git a/docs/0_internal/images/4_b_1_pause_4.png b/docs/0_internal/images/4_b_1_pause_4.png
diff --git a/docs/0_internal/images/4_b_1_pause_5.png b/docs/0_internal/images/4_b_1_pause_5.png
diff --git a/docs/0_internal/images/4_b_1_pause_6.png b/docs/0_internal/images/4_b_1_pause_6.png
diff --git a/docs/0_internal/images/4_b_1_pause_8.png b/docs/0_internal/images/4_b_1_pause_8.png
diff --git a/docs/0_internal/images/4_b_1_pause_9.png b/docs/0_internal/images/4_b_1_pause_9.png
diff --git a/docs/0_internal/images/4_b_2_approve_1.png b/docs/0_internal/images/4_b_2_approve_1.png
diff --git a/docs/0_internal/images/4_b_2_approve_2.png b/docs/0_internal/images/4_b_2_approve_2.png
diff --git a/docs/0_internal/images/4_b_2_approve_3.png b/docs/0_internal/images/4_b_2_approve_3.png