Merge branch 'main' into joby.thundil/retire-games-template

Author: jjtny1

.gitignore

@@ -26,3 +26,4 @@ yarn-error.log
 .gitmodules
 
 .DS_Store
+signer-tool/

Makefile

@@ -1,3 +1,5 @@
+FOUNDRY_COMMIT ?= 3b1129b5bc43ba22a9bcf4e4323c5a9df0023140
+
 PROJECT_DIR = $(network)/$(shell date +'%Y-%m-%d')-$(task)
 GAS_INCREASE_DIR = $(network)/$(shell date +'%Y-%m-%d')-increase-gas-limit
 FAULT_PROOF_UPGRADE_DIR = $(network)/$(shell date +'%Y-%m-%d')-upgrade-fault-proofs
@@ -116,7 +118,7 @@ checkout-base-contracts-commit:
 ##
 # Task Signer Tool
 ##
-SIGNER_TOOL_COMMIT=f33affd459859882b30fbda29e43abfded77903a
+SIGNER_TOOL_COMMIT=dc9dcd57e66cc71d8e8f40afc2d0bad454cba998
 SIGNER_TOOL_PATH=signer-tool
 
 .PHONY: checkout-signer-tool
@@ -130,14 +132,11 @@ checkout-signer-tool:
 	git fetch --depth=1 origin $(SIGNER_TOOL_COMMIT); \
 	git reset --hard FETCH_HEAD
 
-.PHONY: sign
-sign:
+.PHONY: sign-task
+sign-task: checkout-signer-tool
 	cd $(SIGNER_TOOL_PATH); \
 	npm ci; \
-	bun dev
-
-.PHONY: sign-task
-sign-task: checkout-signer-tool sign
+	npm run dev
 
 ##
 # Solidity Testing

README.md

@@ -48,6 +48,8 @@ Next, `cd` into the directory that was created for you and follow the steps list
 
 > **👥 For Signers:** Please read the [Signer Guide](SIGNER.md) for step-by-step instructions on using the validation UI.
 
+Please note, you will need to manually create validation file(s) for your task as they are bespoke to each task and therefore not created automatically as a part of the templates. We use one validation Markdown file per multisig involved in the task, so if there's only one multisig involved in your task, then you can simply create a `VALIDATION.md` file at the root of your task containing the validation instructions, while if there are multiple multisigs involved in the task, then create a `validations/` sub-directory at the root of your task containing the corresponding validation Markdown files. If you need examples to work from, you can browse through similar past tasks in this repo and adapt them to your specific task. Also, please note that we have tooling to generate these files (like the `task-signer-tool`) which removes the manual aspect of creating these validation files, we will soon update these instructions to reflect how this process can be automated.
+
 ## Directory structure
 
 Each task will have a directory structure similar to the following:
@@ -92,7 +94,7 @@ This template is increasing the throughput on Base Chain.
 1. Go to the folder that was created using the `make setup-gas-increase network=<network>` step
 1. Fill in all TODOs (search for "TODO" in the folder) in the `.env` and `README` files. Tip: you can run `make deps` followed by `make sign-upgrade` to produce a Tenderly simulation which will help fill in several of the TODOs in the README (and also `make sign-rollback`).
 1. Check in the task when it's ready to sign and collect signatures from signers
-1. Once executed, check in the records files and mark the task `DONE` in the README.
+1. Once executed, check in the records files and mark the task `EXECUTED` in the README.
 
 ## Using the fault proof upgrade template
 
@@ -108,7 +110,7 @@ This template is used to upgrade the fault proof contracts. This is commonly don
 1. Build the contracts with `forge build`
 1. Remove the unneeded validations from `VALIDATION.md` and update the relevant validations accordingly
 1. Check in the task when it's ready to sign and collect signatures from signers
-1. Once executed, check in the records files and mark the task `DONE` in the README.
+1. Once executed, check in the records files and mark the task `EXECUTED` in the README.
 
 ## Using the swap owner template
 
@@ -122,7 +124,7 @@ This template is used to perform ownership management on a Gnosis Safe multisig,
 1. Build the contracts with `forge build`.
 1. Simulate the task with `make sign` and update the generic validations in `VALIDATION.md` with the real values.
 1. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
-1. Once executed, check in the records files and mark the task `DONE` in the README.
+1. Once executed, check in the records files and mark the task `EXECUTED` in the README.
 
 ## Using the funding template
 
@@ -137,7 +139,7 @@ This template is used to fund addresses from a Gnosis Safe.
 1. Build the contracts with `forge build`.
 1. Simulate the task with `make sign` and update the generic validations in `VALIDATION.md` with the real values.
 1. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
-1. Once executed, check in the records files and mark the task `DONE` in the README.
+1. Once executed, check in the records files and mark the task `EXECUTED` in the README.
 
 ## Using the Base Bridge set partner threshold template
 
@@ -153,7 +155,7 @@ This template is used to update the partner threshold in [Base Bridge](https://g
 1. Build the contracts with `forge build`.
 1. Generate the validation file for signers with `make gen-validation`.
 1. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
-1. Once executed, check in the records files and mark the task `DONE` in the README.
+1. Once executed, check in the records files and mark the task `EXECUTED` in the README.
 
 ## Using the pause Base Bridge template
 
@@ -169,4 +171,4 @@ This template is used to pause or un-pause [Base Bridge](https://github.com/base
 1. Build the contracts with `forge build`.
 1. Generate the validation file for signers with `make gen-validation`.
 1. Check in the task when it's ready to sign and request the facilitators to collect signatures from signers.
-1. Once executed, check in the records files and mark the task `DONE` in the README.
+1. Once executed, check in the records files and mark the task `EXECUTED` in the README.

mainnet/2025-08-13-safe-swap-owner/.env

@@ -0,0 +1,4 @@
+OP_COMMIT=ef7a933ca7f3d27ac40406f87fea25e0c3ba2016
+BASE_CONTRACTS_COMMIT=132ba0f33cb455ffff783924588df8864767bd9c
+
+OWNER_SAFE=0xB5fa2Ea9845C67c76b1813D4778601F209875Bf6

mainnet/2025-08-13-safe-swap-owner/Makefile

@@ -0,0 +1,18 @@
+include ../../Makefile
+include ../.env
+include .env
+
+ifndef LEDGER_ACCOUNT
+override LEDGER_ACCOUNT = 0
+endif
+
+.PHONY: do-sign
+do-sign:
+	$(GOPATH)/bin/eip712sign --ledger --hd-paths "m/44'/60'/$(LEDGER_ACCOUNT)'/0/0" -- \
+	forge script --rpc-url $(L2_RPC_URL) SwapOwner \
+	--sig "sign(address[])" []
+
+.PHONY: execute
+execute:
+	forge script --rpc-url $(L2_RPC_URL) SwapOwner \
+	--sig "run(bytes)" $(SIGNATURES) --ledger --hd-paths "m/44'/60'/$(LEDGER_ACCOUNT)'/0/0" --broadcast

mainnet/2025-08-13-safe-swap-owner/OwnerDiff.json

@@ -0,0 +1,19 @@
+{
+  "OwnersToAdd": [
+    "0xB4AE52A401C34Ed24F49413170690255e737D414",
+    "0xB9F93278843351Dd1F1fB7045349aCA4401CB76e",
+    "0x8793C36f3721B751Aa03A365be4862ac4aCD21Ef",
+    "0x16eBE22A951D96A3CA15407b04dD873A14018992",
+    "0x7233C120cd9D601EC0ad4DBaA51aE55A4851FaC6",
+    "0x4Ae6Da8c76d4a628594a2154bDC31C9e04f43A48",
+    "0x14b849bcc8034b2cd4c4669f9CEB47b190F3fb1F"
+  ],
+  "OwnersToRemove": [
+    "0xC29A4a69886d5ee1E08BDBbdd4e35558A668ee04",
+    "0x23AB3425EC02328eBB0dB3d93213a2238A78a026",
+    "0x7CD1a2f18CBef60F63F6fe35FC02A6305a77E3E2",
+    "0xd458da0810f6924623575a4b965310F008c1C8fe",
+    "0xE4fdB41d002844cfb43d5d50DE7210625C6f5a09",
+    "0xA608EA330D51A5109454f3Ea4F5d0cdEc5a1aCAa"
+  ]
+}

mainnet/2025-08-13-safe-swap-owner/README.md

@@ -0,0 +1,146 @@
+# Swap Owner on Gnosis Safe
+
+Status: PENDING
+
+## Description
+
+This task contains a single script that can be used to swap an owner in a Gnosis Safe. 
+
+## Procedure
+
+### 1. Update repo:
+
+```bash
+cd <network>/<date>safe-swap-owner
+make deps
+```
+
+### 2. Setup Ledger
+
+Your Ledger needs to be connected and unlocked. The Ethereum
+application needs to be opened on Ledger with the message "Application
+is ready".
+
+### 3. Simulate, Validate, and Sign
+
+#### 3.1. Simulate and validate the transaction
+
+Make sure your ledger is still unlocked and run the following.
+
+```bash
+make do-sign
+```
+
+You will see a "Simulation link" from the output.
+
+Paste this URL in your browser. A prompt may ask you to choose a
+project, any project will do. You can create one if necessary.
+
+Click "Simulate Transaction".
+
+We will be performing 3 validations and extract the domain hash and
+message hash to approve on your Ledger:
+
+1. Validate integrity of the simulation.
+2. Validate correctness of the state diff.
+3. Validate and extract domain hash and message hash to approve.
+
+##### 3.1.1. Validate integrity of the simulation.
+
+Make sure you are on the "Summary" tab of the tenderly simulation, to
+validate integrity of the simulation, we need to check the following:
+
+1. "Network": Check the network is `<network>`.
+2. "Timestamp": Check the simulation is performed on a block with a
+   recent timestamp (i.e. close to when you run the script).
+3. "Sender": Check the address shown is your signer account.
+
+##### 3.1.2. Validate correctness of the state diff.
+
+Now click on the "State" tab, and refer to the [State Validations](./VALIDATION.md) instructions for the transaction you are signing.
+Once complete return to this document to complete the signing.
+
+### 4. Extract the domain hash and the message hash to approve.
+
+Now that we have verified the transaction performs the right
+operation, we need to extract the domain hash and the message hash to
+approve.
+
+Go back to the "Summary" tab, and find the
+`Safe.checkSignatures` call. This call's `data` parameter
+contains both the domain hash and the message hash that will show up
+in your Ledger.
+
+It will be a concatenation of `0x1901`, the domain hash, and the
+message hash: `0x1901[domain hash][message hash]`.
+
+Note down this value. You will need to compare it with the ones
+displayed on the Ledger screen at signing.
+
+Once the validations are done, it's time to actually sign the
+transaction.
+
+> [!WARNING]
+> This is the most security critical part of the playbook: make sure the
+> domain hash and message hash in the following three places match:
+>
+> 1. On your Ledger screen.
+> 2. In the terminal output.
+> 3. In the Tenderly simulation. You should use the same Tenderly
+>    simulation as the one you used to verify the state diffs, instead
+>    of opening the new one printed in the console.
+>
+
+After verification, sign the transaction. You will see the `Data`,
+`Signer` and `Signature` printed in the console. Format should be
+something like this:
+
+```shell
+Data:  <DATA>
+Signer: <ADDRESS>
+Signature: <SIGNATURE>
+```
+
+Double check the signer address is the right one.
+
+#### 4.1. Send the output to Facilitator(s)
+
+Nothing has occurred onchain - these are offchain signatures which
+will be collected by Facilitators for execution. Execution can occur
+by anyone once a threshold of signatures are collected, so a
+Facilitator will do the final execution for convenience.
+
+Share the `Data`, `Signer` and `Signature` with the Facilitator, and
+congrats, you are done!
+
+### [For Facilitator ONLY] How to execute
+
+#### Execute the transaction
+
+1. Collect outputs from all participating signers.
+1. Concatenate all signatures and export it as the `SIGNATURES`
+   environment variable, i.e. `export
+SIGNATURES="[SIGNATURE1][SIGNATURE2]..."`.
+1. Run the `make execute` command as described below to execute the transaction.
+
+For example, if the quorum is 2 and you get the following outputs:
+
+```shell
+Data:  0xDEADBEEF
+Signer: 0xC0FFEE01
+Signature: AAAA
+```
+
+```shell
+Data:  0xDEADBEEF
+Signer: 0xC0FFEE02
+Signature: BBBB
+```
+
+Then you should run:
+
+Coinbase facilitator:
+
+```bash
+SIGNATURES=AAAABBBB make execute
+```

mainnet/2025-08-13-safe-swap-owner/VALIDATION.md

@@ -0,0 +1,78 @@
+# Validation
+
+This document can be used to validate the state diff resulting from the execution of the swap owner transaction.
+
+For each contract listed in the state diff, please verify that no contracts or state changes shown in the Tenderly diff are missing from this document. Additionally, please verify that for each contract:
+
+- The following state changes (and no others) are made to that contract. This validates that no unexpected state changes occur.
+- All addresses (in section headers and storage values) match the provided name, using the Etherscan links provided. This validates the bytecode deployed at the addresses contains the correct logic.
+- All key values match the semantic meaning provided, which can be validated using the storage layout links provided.
+
+## State Changes
+
+### `<safe_address>` (Base `GnosisSafeProxy`)
+
+- **Key**: `owners[newOwner]` <br/>
+  **Before**: `0x0000000000000000000000000000000000000000000000000000000000000000` <br/>
+  **After**: `Next address in the list returned by getOwners()` <br/>
+  **Meaning**: Sets the address value at the mapping key `owners[newOwner]` to the next address in the list returned by `getOwners()`. This is the first step required to replace the `oldOwner` address in the linked list data structure of owners.  <br/>
+  **Verify**: You can verify the key derivation by running `cast index address <newOwner> 2` in your terminal. See the following section for an explanation of the storage and value calculations.
+- **Key**: `owners[prevOwner]` <br/>
+  **Before**: `oldOwner address` <br/>
+  **After**: `newOwner address` <br/>
+  **Meaning**: Points the address value at mapping key `owners[prevOwner]` to the `newOwner` address. This is the second step required to replace the `oldOwner` address in the linked list data structure of owners.  <br/>
+  **Verify**: You can verify the key derivation by running `cast index address <prevOwner> 2` in your terminal. See the following section for an explanation of the storage and value calculations.
+- **Key**: `owners[oldOwner]` <br/>
+  **Before**: `Next address in the list returned by getOwners()` <br/>
+  **After**: `0x0000000000000000000000000000000000000000000000000000000000000000` <br/>
+  **Meaning**: Clears the address value at the mapping key `owners[oldOwner]`. This removes the final reference to the `oldOwner` from the `owners` linked list.  <br/>
+  **Verify**: You can verify the key derivation by running `cast index address <oldOwner> 2` in your terminal. See the following section for an explanation of the storage and value calculations.
+- **Key**: `0x0000000000000000000000000000000000000000000000000000000000000005` <br/>
+  **Before**: `Current nonce value (in hexadecimal)` <br/>
+  **After**: `Current nonce value + 1 (in hexadecimal)` <br/>
+  **Meaning**: Increments the `nonce` value of the Gnosis Safe. <br/>
+  **Verify**: You can verify the value by running `cast storage <safe_address> 5 -r <rpc_url>` in your terminal. This value represents the _current_ nonce value.
+
+### `SwapOwner` Storage Calculations
+
+The [`swapOwner`](https://github.com/safe-global/safe-smart-account/blob/8823fa3e44936e2aecf23bb97662eb0ffeff2f93/contracts/base/OwnerManager.sol#L94) function in the Gnosis Safe implementation will perform [three storage changes](https://github.com/safe-global/safe-smart-account/blob/8823fa3e44936e2aecf23bb97662eb0ffeff2f93/contracts/base/OwnerManager.sol#L106-L108):
+
+- Point the `newOwner` address to the owner address that was previously pointed to by the `oldOwner` that is being removed.
+- Point the `prevOwner` address to the `newOwner` address.
+- Remove the pointer value stored at the mapping of the `oldOwner` address.
+
+These changes are needed on account of the data structure that holds the owners in the Gnosis Safe implementation being a singly-linked list. To calculate the expected storage locations of these mapping values, we can perform the following:
+
+#### Calculating `prevOwner`
+
+The `prevOwner` is identified by the script, but can be manually checked by running the cast command:
+
+```sh
+cast call <safe_address> "getOwners()(address[])" -r <rpc_url>
+
+[0x6CD3850756b7894774Ab715D136F9dD02837De50, 0x3cd692eCE8b6573A2220ae00d0dEb98f0DfFA9a1, 0x5FbEFA105bbd53b43bf537Cbc5cD30804Dd0c993, 0x3Dad2200849925Bb46d9bF05aFa5f7F213F4c18E, 0xB011a32ED8b4F70D9943A2199F539bbeCd7b62F7, 0xf9e320f3dA12E68af219d9E2A490Dd649f6B177c]
+```
+
+The order that the owner addresses are returned in indicates who the `prevOwner` and next owner values of the address to remove is. If the owner to remove is the 0th value, its `prevOwner` would be the special sentinel node value [`SENTINEL_OWNERS`](https://github.com/safe-global/safe-smart-account/blob/f9cc387f72640eb2c1d6ae8abe9d6ff25ca1ed3b/contracts/base/OwnerManager.sol#L17). Otherwise, if the owner to remove is the last value in the array, its next owner address would be the special sentinel node value [`SENTINEL_OWNERS`](https://github.com/safe-global/safe-smart-account/blob/f9cc387f72640eb2c1d6ae8abe9d6ff25ca1ed3b/contracts/base/OwnerManager.sol#L17).
+
+#### Calculating storage locations and values
+
+With the order of the owners identified, we can calculate the expected storage mapping locations and their values. For the first change, the expected storage slot and value will be the following:
+
+**Storage Slot**: `cast index address <newOwner> 2`
+
+**Value**: The address immediately following `oldOwner` in the `getOwners` list, or the `SENTINEL_OWNERS` special value if the address is the last in the array.
+
+For the second change, it will be:
+
+**Storage Slot**: `cast index address <prevOwner> 2`
+
+**Value**: `newOwner` address
+
+For the final storage change, it will be:
+
+**Storage Slot**: `cast index address <oldOwner> 2`
+
+**Value**: `address(0)`
+
+Note that for all the above storage calculations, we used storage slot 2 as that is the location of the `owners` mapping in the Gnosis Safe storage layout. This can be confirmed with the following command: `cast storage <safe_address> -r <rpc_url> -e <etherscan_api_key>`. Also note that while the storage changes may not appear in the same order in the Tenderly simulation, there should still be 3 storage changes related to the `owner` linked list and one change for the `nonce` value on the `GnosisSafeProxy`. There should be no additional changes to the proxy besides these ones!

mainnet/2025-08-13-safe-swap-owner/foundry.toml

@@ -0,0 +1,20 @@
+[profile.default]
+src = 'src'
+out = 'out'
+libs = ['lib']
+broadcast = 'records'
+fs_permissions = [ {access = "read-write", path = "./"} ]
+optimizer = true
+optimizer_runs = 999999
+solc_version = "0.8.15"
+via-ir = false
+remappings = [
+    '@eth-optimism-bedrock/=lib/optimism/packages/contracts-bedrock/',
+    '@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts',
+    '@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts',
+    '@rari-capital/solmate/=lib/solmate/',
+    '@base-contracts/=lib/base-contracts',
+    '@solady/=lib/solady/src/'
+]
+
+# See more config options https://github.com/foundry-rs/foundry/tree/master/config