|
| 1 | +# Upgrade Fault Proofs |
| 2 | + |
| 3 | +Status: READY TO SIGN |
| 4 | + |
| 5 | +## Description |
| 6 | + |
| 7 | +This task contains two scripts for our required onchain updates for the OP Stack's [Upgrade 15](https://docs.optimism.io/notices/upgrade-15). 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 sepolia/2025-04-14-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 | +```bash |
| 39 | +make sign |
| 40 | +``` |
| 41 | + |
| 42 | +You will see a "Simulation link" from the output. |
| 43 | + |
| 44 | +Paste this URL in your browser. A prompt may ask you to choose a |
| 45 | +project, any project will do. You can create one if necessary. |
| 46 | + |
| 47 | +Click "Simulate Transaction". |
| 48 | + |
| 49 | +We will be performing 3 validations and extract the domain hash and message hash to approve on your Ledger: |
| 50 | + |
| 51 | +1. Validate integrity of the simulation. |
| 52 | +2. Validate correctness of the state diff. |
| 53 | +3. Validate and extract domain hash and message hash to approve. |
| 54 | + |
| 55 | +##### 3.2.1 Validate integrity of the simulation. |
| 56 | + |
| 57 | +Make sure you are on the "Overview" tab of the tenderly simulation, to |
| 58 | +validate integrity of the simulation, we need to check the following: |
| 59 | + |
| 60 | +1. "Network": Check the network is Sepolia. |
| 61 | +2. "Timestamp": Check the simulation is performed on a block with a |
| 62 | + recent timestamp (i.e. close to when you run the script). |
| 63 | +3. "Sender": Check the address shown is your signer account. If not see the derivation path Note above. |
| 64 | + |
| 65 | +##### 3.2.2. Validate correctness of the state diff. |
| 66 | + |
| 67 | +Now click on the "State" tab, and refer to the [State Validations](./validations/SafeA.md) instructions for the transaction you are signing. |
| 68 | +Once complete return to this document to complete the signing. |
| 69 | + |
| 70 | +##### 3.2.3. Extract the domain hash and the message hash to approve. |
| 71 | + |
| 72 | +Now that we have verified the transaction performs the right |
| 73 | +operation, we need to extract the domain hash and the message hash to |
| 74 | +approve. |
| 75 | + |
| 76 | +Go back to the "Overview" tab, and find the |
| 77 | +`GnosisSafe.checkSignatures` call. This call's `data` parameter |
| 78 | +contains both the domain hash and the message hash that will show up |
| 79 | +in your Ledger. |
| 80 | + |
| 81 | +It will be a concatenation of `0x1901`, the domain hash, and the |
| 82 | +message hash: `0x1901[domain hash][message hash]`. |
| 83 | + |
| 84 | +Note down this value. You will need to compare it with the ones |
| 85 | +displayed on the Ledger screen at signing. |
| 86 | + |
| 87 | +Once the validations are done, it's time to actually sign the |
| 88 | +transaction. |
| 89 | + |
| 90 | +> [!WARNING] |
| 91 | +> This is the most security critical part of the playbook: make sure the |
| 92 | +> domain hash and message hash in the following two places match: |
| 93 | +> |
| 94 | +> 1. On your Ledger screen. |
| 95 | +> 2. In the Tenderly simulation. You should use the same Tenderly |
| 96 | +> simulation as the one you used to verify the state diffs, instead |
| 97 | +> of opening the new one printed in the console. |
| 98 | +> |
| 99 | +> There is no need to verify anything printed in the console. There is |
| 100 | +> no need to open the new Tenderly simulation link either. |
| 101 | +
|
| 102 | +After verification, sign the transaction. You will see the `Data`, |
| 103 | +`Signer` and `Signature` printed in the console. Format should be |
| 104 | +something like this: |
| 105 | + |
| 106 | +```shell |
| 107 | +Data: <DATA> |
| 108 | +Signer: <ADDRESS> |
| 109 | +Signature: <SIGNATURE> |
| 110 | +``` |
| 111 | + |
| 112 | +Double check the signer address is the right one. |
| 113 | + |
| 114 | +##### 3.2.4 Send the output to Facilitator(s) |
| 115 | + |
| 116 | +Nothing has occurred onchain - these are offchain signatures which |
| 117 | +will be collected by Facilitators for execution. Execution can occur |
| 118 | +by anyone once a threshold of signatures are collected, so a |
| 119 | +Facilitator will do the final execution for convenience. |
| 120 | + |
| 121 | +Share the `Data`, `Signer` and `Signature` with the Facilitator, and |
| 122 | +congrats, you are done! |
| 123 | + |
| 124 | +### [For Facilitator ONLY] How to execute |
| 125 | + |
| 126 | +#### Approve the transaction |
| 127 | + |
| 128 | +1. Collect outputs from all participating signers. |
| 129 | +1. Concatenate all signatures and export it as the `SIGNATURES` |
| 130 | + environment variable, i.e. `export |
| 131 | +SIGNATURES="[SIGNATURE1][SIGNATURE2]..."`. |
| 132 | +1. Run the `make approve` command as described below to approve the transaction. |
| 133 | + |
| 134 | +For example, if the quorum is 2 and you get the following outputs: |
| 135 | + |
| 136 | +```shell |
| 137 | +Data: 0xDEADBEEF |
| 138 | +Signer: 0xC0FFEE01 |
| 139 | +Signature: AAAA |
| 140 | +``` |
| 141 | + |
| 142 | +```shell |
| 143 | +Data: 0xDEADBEEF |
| 144 | +Signer: 0xC0FFEE02 |
| 145 | +Signature: BBBB |
| 146 | +``` |
| 147 | + |
| 148 | +```bash |
| 149 | +SIGNATURES=AAAABBBB make approve |
| 150 | +``` |
| 151 | + |
| 152 | +As the facilitator, you are then expected to sign / approve on behalf of the rest of our testnet multisigs that mirror our mainnet hierarchy. |
| 153 | + |
| 154 | +```bash |
| 155 | +make sign-b |
| 156 | +``` |
| 157 | + |
| 158 | +```bash |
| 159 | +SIGNATURES=AAAA make approve-b |
| 160 | +``` |
| 161 | + |
| 162 | +```bash |
| 163 | +make sign-nested-b |
| 164 | +``` |
| 165 | + |
| 166 | +```bash |
| 167 | +SIGNATURES=AAAA make approve-nested-b |
| 168 | +``` |
| 169 | + |
| 170 | +```bash |
| 171 | +make approve-coordinator |
| 172 | +``` |
| 173 | + |
| 174 | +#### Execute the transaction |
| 175 | + |
| 176 | +IMPORTANT: Ensure op-challenger has been updated before executing. |
| 177 | + |
| 178 | +Once the signatures have been submitted approving the transaction for all nested Safes run: |
| 179 | + |
| 180 | +```bash |
| 181 | +make execute |
| 182 | +``` |
0 commit comments