|
| 1 | +# Upgrade Fault Proofs |
| 2 | + |
| 3 | +Status: PENDING |
| 4 | + |
| 5 | +## Description |
| 6 | + |
| 7 | +This task contains two scripts. One for deploying new versions of the `FaultDisputeGame` and `PermissionedDisputeGame` contracts, and one for updating the `DisputeGameFactory` contract to reference the new dispute game contracts. |
| 8 | + |
| 9 | +## Procedure |
| 10 | + |
| 11 | +### 1. Update repo: |
| 12 | + |
| 13 | +```bash |
| 14 | +cd contract-deployments |
| 15 | +git pull |
| 16 | +cd <network>/<date>-upgrade-fault-proofs |
| 17 | +make deps |
| 18 | +``` |
| 19 | + |
| 20 | +### 2. Setup Ledger |
| 21 | + |
| 22 | +Your Ledger needs to be connected and unlocked. The Ethereum |
| 23 | +application needs to be opened on Ledger with the message "Application |
| 24 | +is ready". |
| 25 | + |
| 26 | +### 3. Run relevant script(s) |
| 27 | + |
| 28 | +#### 3.1 Deploy new Dispute Game Implementations |
| 29 | + |
| 30 | +```bash |
| 31 | +make deploy |
| 32 | +``` |
| 33 | + |
| 34 | +This will output the new addresses of the `FaultDisputeGame` and `PermissionedDisputeGame` contracts to an `addresses.json` file. You will need to commit this file to the repo before signers can sign. |
| 35 | + |
| 36 | +#### 3.2 Sign the transaction |
| 37 | + |
| 38 | +**If on testnet**: |
| 39 | + |
| 40 | +```bash |
| 41 | +make sign |
| 42 | +``` |
| 43 | + |
| 44 | +**If on mainnet**: |
| 45 | + |
| 46 | +Coinbase signer: |
| 47 | + |
| 48 | +```bash |
| 49 | +make sign-cb |
| 50 | +``` |
| 51 | + |
| 52 | +Op signer: |
| 53 | + |
| 54 | +```bash |
| 55 | +make sign-op |
| 56 | +``` |
| 57 | + |
| 58 | +You will see a "Simulation link" from the output. |
| 59 | + |
| 60 | +Paste this URL in your browser. A prompt may ask you to choose a |
| 61 | +project, any project will do. You can create one if necessary. |
| 62 | + |
| 63 | +Click "Simulate Transaction". |
| 64 | + |
| 65 | +We will be performing 3 validations and extract the domain hash and message hash to approve on your Ledger: |
| 66 | + |
| 67 | +1. Validate integrity of the simulation. |
| 68 | +2. Validate correctness of the state diff. |
| 69 | +3. Validate and extract domain hash and message hash to approve. |
| 70 | + |
| 71 | +##### 3.2.1 Validate integrity of the simulation. |
| 72 | + |
| 73 | +Make sure you are on the "Overview" tab of the tenderly simulation, to |
| 74 | +validate integrity of the simulation, we need to check the following: |
| 75 | + |
| 76 | +1. "Network": Check the network is Sepolia or Mainnet. |
| 77 | +2. "Timestamp": Check the simulation is performed on a block with a |
| 78 | + recent timestamp (i.e. close to when you run the script). |
| 79 | +3. "Sender": Check the address shown is your signer account. If not see the derivation path Note above. |
| 80 | + |
| 81 | +##### 3.2.2. Validate correctness of the state diff. |
| 82 | + |
| 83 | +Now click on the "State" tab, and refer to the [State Validations](./VALIDATION.md) instructions for the transaction you are signing. |
| 84 | +Once complete return to this document to complete the signing. |
| 85 | + |
| 86 | +##### 3.2.3. Extract the domain hash and the message hash to approve. |
| 87 | + |
| 88 | +Now that we have verified the transaction performs the right |
| 89 | +operation, we need to extract the domain hash and the message hash to |
| 90 | +approve. |
| 91 | + |
| 92 | +Go back to the "Overview" tab, and find the |
| 93 | +`GnosisSafe.checkSignatures` call. This call's `data` parameter |
| 94 | +contains both the domain hash and the message hash that will show up |
| 95 | +in your Ledger. |
| 96 | + |
| 97 | +It will be a concatenation of `0x1901`, the domain hash, and the |
| 98 | +message hash: `0x1901[domain hash][message hash]`. |
| 99 | + |
| 100 | +Note down this value. You will need to compare it with the ones |
| 101 | +displayed on the Ledger screen at signing. |
| 102 | + |
| 103 | +Once the validations are done, it's time to actually sign the |
| 104 | +transaction. |
| 105 | + |
| 106 | +> [!WARNING] |
| 107 | +> This is the most security critical part of the playbook: make sure the |
| 108 | +> domain hash and message hash in the following two places match: |
| 109 | +> |
| 110 | +> 1. On your Ledger screen. |
| 111 | +> 2. In the Tenderly simulation. You should use the same Tenderly |
| 112 | +> simulation as the one you used to verify the state diffs, instead |
| 113 | +> of opening the new one printed in the console. |
| 114 | +> |
| 115 | +> There is no need to verify anything printed in the console. There is |
| 116 | +> no need to open the new Tenderly simulation link either. |
| 117 | +
|
| 118 | +After verification, sign the transaction. You will see the `Data`, |
| 119 | +`Signer` and `Signature` printed in the console. Format should be |
| 120 | +something like this: |
| 121 | + |
| 122 | +```shell |
| 123 | +Data: <DATA> |
| 124 | +Signer: <ADDRESS> |
| 125 | +Signature: <SIGNATURE> |
| 126 | +``` |
| 127 | + |
| 128 | +Double check the signer address is the right one. |
| 129 | + |
| 130 | +##### 3.2.4 Send the output to Facilitator(s) |
| 131 | + |
| 132 | +Nothing has occurred onchain - these are offchain signatures which |
| 133 | +will be collected by Facilitators for execution. Execution can occur |
| 134 | +by anyone once a threshold of signatures are collected, so a |
| 135 | +Facilitator will do the final execution for convenience. |
| 136 | + |
| 137 | +Share the `Data`, `Signer` and `Signature` with the Facilitator, and |
| 138 | +congrats, you are done! |
| 139 | + |
| 140 | +### [For Facilitator ONLY] How to execute |
| 141 | + |
| 142 | +#### Execute the transaction |
| 143 | + |
| 144 | +1. IMPORTANT: Ensure op-challenger has been updated before executing. |
| 145 | +1. Collect outputs from all participating signers. |
| 146 | +1. Concatenate all signatures and export it as the `SIGNATURES` |
| 147 | + environment variable, i.e. `export |
| 148 | +SIGNATURES="[SIGNATURE1][SIGNATURE2]..."`. |
| 149 | +1. Run the `make execute` or `make approve` command as described below to execute the transaction. |
| 150 | + |
| 151 | +For example, if the quorum is 2 and you get the following outputs: |
| 152 | + |
| 153 | +```shell |
| 154 | +Data: 0xDEADBEEF |
| 155 | +Signer: 0xC0FFEE01 |
| 156 | +Signature: AAAA |
| 157 | +``` |
| 158 | + |
| 159 | +```shell |
| 160 | +Data: 0xDEADBEEF |
| 161 | +Signer: 0xC0FFEE02 |
| 162 | +Signature: BBBB |
| 163 | +``` |
| 164 | + |
| 165 | +If on testnet, then you should run: |
| 166 | + |
| 167 | +Coinbase facilitator: |
| 168 | + |
| 169 | +```bash |
| 170 | +SIGNATURES=AAAABBBB make execute |
| 171 | +``` |
| 172 | + |
| 173 | +If on mainnet, then you should run: |
| 174 | + |
| 175 | +Coinbase facilitator: |
| 176 | + |
| 177 | +```bash |
| 178 | +SIGNATURES=AAAABBBB make approve-cb |
| 179 | +``` |
| 180 | + |
| 181 | +Optimism facilitator: |
| 182 | + |
| 183 | +```bash |
| 184 | +SIGNATURES=AAAABBBB make approve-op |
| 185 | +``` |
| 186 | + |
| 187 | +#### If on mainnet, execute the transaction |
| 188 | + |
| 189 | +Once the signatures have been submitted approving the transaction for all nested Safes run: |
| 190 | + |
| 191 | +```bash |
| 192 | +make execute |
| 193 | +``` |
0 commit comments