Skip to content

Commit 79d78a6

Browse files
jackchumaCopilot
jackchuma
and
Copilot
authored
feat(CHAIN-548): add script for SmartEscrow ownership transfer initiation (#306)
* add script for SmartEscrow ownership transfer initiation * Update mainnet/2025-04-07-init-smart-escrow-ownership-transfer/VALIDATION.md Co-authored-by: Copilot <[email protected]> * use op library for address aliasing --------- Co-authored-by: Copilot <[email protected]>
1 parent d765e1d commit 79d78a6

File tree

6 files changed

+432
-0
lines changed

6 files changed

+432
-0
lines changed

‎mainnet/2025-04-07-init-smart-escrow-ownership-transfer/.env

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
OP_COMMIT=8d0dd96e494b2ba154587877351e87788336a4ec
2+
BASE_CONTRACTS_COMMIT=6ca464d118d2d33331ea44893f0930f753663f60
3+
4+
L1_SAFE=0x7bB41C3008B3f03FE483B28b8DB90e19Cf07595c
5+
TARGET=0xb3C2f9fC2727078EC3A2255410e83BA5B62c5B5f
6+
7+
OWNER_SAFE=0x0a7361e734cf3f0394B0FC4a45C74E7a4Ec70940
8+
CB_SIGNER_SAFE_ADDR=0x6e1DFd5C1E22A4677663A81D24C6BA03561ef0f6
9+
OP_SIGNER_SAFE_ADDR=0x2501c477D0A35545a387Aa4A3EEe4292A9a8B3F0

‎mainnet/2025-04-07-init-smart-escrow-ownership-transfer/Makefile

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
include ../../Makefile
2+
include ../.env
3+
include .env
4+
5+
L2_RPC_URL=https://mainnet.optimism.io
6+
7+
ifndef LEDGER_ACCOUNT
8+
override LEDGER_ACCOUNT = 0
9+
endif
10+
11+
.PHONY: sign-cb
12+
sign-cb:
13+
$(GOPATH)/bin/eip712sign --ledger --hd-paths "m/44'/60'/$(LEDGER_ACCOUNT)'/0/0" -- \
14+
forge script --rpc-url $(L2_RPC_URL) InitOwnershipTransfer \
15+
--sig "sign(address)" $(CB_SIGNER_SAFE_ADDR)
16+
17+
.PHONY: sign-op
18+
sign-op:
19+
$(GOPATH)/bin/eip712sign --ledger --hd-paths "m/44'/60'/$(LEDGER_ACCOUNT)'/0/0" -- \
20+
forge script --rpc-url $(L2_RPC_URL) InitOwnershipTransfer \
21+
--sig "sign(address)" $(OP_SIGNER_SAFE_ADDR)
22+
23+
.PHONY: approve-cb
24+
approve-cb:
25+
forge script --rpc-url $(L2_RPC_URL) InitOwnershipTransfer \
26+
--sig "approve(address,bytes)" $(CB_SIGNER_SAFE_ADDR) $(SIGNATURES) \
27+
--ledger --hd-paths "m/44'/60'/$(LEDGER_ACCOUNT)'/0/0" --broadcast -vvvv
28+
29+
.PHONY: approve-op
30+
approve-op:
31+
forge script --rpc-url $(L2_RPC_URL) InitOwnershipTransfer \
32+
--sig "approve(address,bytes)" $(OP_SIGNER_SAFE_ADDR) $(SIGNATURES) \
33+
--ledger --hd-paths "m/44'/60'/$(LEDGER_ACCOUNT)'/0/0" --broadcast -vvvv
34+
35+
.PHONY: execute
36+
execute:
37+
forge script --rpc-url $(L2_RPC_URL) InitOwnershipTransfer \
38+
--sig "run()" --ledger --hd-paths "m/44'/60'/$(LEDGER_ACCOUNT)'/0/0" --broadcast -vvvv

‎mainnet/2025-04-07-init-smart-escrow-ownership-transfer/README.md

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

‎mainnet/2025-04-07-init-smart-escrow-ownership-transfer/VALIDATION.md

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Validation
2+
3+
This document can be used to validate the inputs and result of the execution of the upgrade transaction which you are
4+
signing.
5+
6+
The steps are:
7+
8+
1. [Validate the Domain and Message Hashes](#expected-domain-and-message-hashes)
9+
2. [Verifying the state changes](#state-changes)
10+
11+
## Expected Domain and Message Hashes
12+
13+
First, we need to validate the domain and message hashes. These values should match both the values on your ledger and
14+
the values printed to the terminal when you run the task.
15+
16+
> [!CAUTION]
17+
>
18+
> Before signing, ensure the below hashes match what is on your ledger.
19+
>
20+
> ### Child Safe 1: `0x6e1DFd5C1E22A4677663A81D24C6BA03561ef0f6` (Base)
21+
>
22+
> - Domain Hash: `0x4ac8f60706331537a33c4a4cbda024cb722855e6b160a3e8b28ab487510598b1`
23+
> - Message Hash: `0x3a25fa618752b5d5408cef7c063ff8f08f6a833e3ac131666452d099c4cb1896`
24+
>
25+
> ### Child Safe 2: `0x2501c477D0A35545a387Aa4A3EEe4292A9a8B3F0` (Optimism Foundation)
26+
>
27+
> - Domain Hash: `0xb34978142f4478f3e5633915597a756daa58a1a59a3e0234f9acd5444f1ca70e`
28+
> - Message Hash: `0x810c12369f2efe81a2a6825b3b41e8d9b4315ba44fdf286ff23d5c4637755689`
29+
30+
# State Validations
31+
32+
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:
33+
34+
- The following state changes (and none others) are made to that contract. This validates that no unexpected state
35+
changes occur.
36+
- All addresses (in section headers and storage values) match the provided name, using the Etherscan and Superchain
37+
Registry links provided. This validates the bytecode deployed at the addresses contains the correct logic.
38+
- All key values match the semantic meaning provided, which can be validated using the storage layout links provided.
39+
40+
## State Overrides
41+
42+
### `0x0a7361e734cf3f0394B0FC4a45C74E7a4Ec70940` (`ProxyAdminOwner` on OP Mainnet)
43+
44+
- **Key**: `0x0000000000000000000000000000000000000000000000000000000000000004` <br/>
45+
**Override**: `0x0000000000000000000000000000000000000000000000000000000000000001` <br/>
46+
**Meaning**: Override the threshold to 1 so the transaction simulation can occur.
47+
48+
### Nested Safe
49+
50+
[For CB Signers] `0x6e1DFd5C1E22A4677663A81D24C6BA03561ef0f6` (`CB Nested Safe`)
51+
[For OP Signers] `0x2501c477D0A35545a387Aa4A3EEe4292A9a8B3F0` (`OP Nested Safe`)
52+
53+
- **Key**: `0x0000000000000000000000000000000000000000000000000000000000000003` <br/>
54+
**Override**: `0x0000000000000000000000000000000000000000000000000000000000000001` <br/>
55+
**Meaning**: Override the owner count to 1 so the transaction simulation can occur.
56+
57+
- **Key**: `0x0000000000000000000000000000000000000000000000000000000000000004` <br/>
58+
**Override**: `0x0000000000000000000000000000000000000000000000000000000000000001` <br/>
59+
**Meaning**: Override the threshold to 1 so the transaction simulation can occur.
60+
61+
- **Key**: `0x316a0aac0d94f5824f0b66f5bbe94a8c360a17699a1d3a233aafcf7146e9f11c` <br/>
62+
**Override**: `0x0000000000000000000000000000000000000000000000000000000000000001` <br/>
63+
**Meaning**: This is owners[0xca11bde05977b3631167028862be2a173976ca11] -> 1, so the key can be derived from cast index address 0xca11bde05977b3631167028862be2a173976ca11 2.
64+
65+
- **Key**: `0xe90b7bceb6e7df5418fb78d8ee546e97c83a08bbccc01a0644d599ccd2a7c2e0` <br/>
66+
**Override**: `0x000000000000000000000000ca11bde05977b3631167028862be2a173976ca11` <br/>
67+
**Meaning**: This is owners[1] -> 0xca11bde05977b3631167028862be2a173976ca11, so the key can be derived from cast index address 0x0000000000000000000000000000000000000001 2.
68+
69+
## Task State Changes
70+
71+
<pre>
72+
<code>
73+
----- DecodedStateDiff[0] -----
74+
Who: 0x0a7361e734cf3f0394B0FC4a45C74E7a4Ec70940
75+
Contract: ProxyAdminOwner - OP Mainnet
76+
Chain ID: 10
77+
Raw Slot: 0x0000000000000000000000000000000000000000000000000000000000000005
78+
Raw Old Value: 0x0000000000000000000000000000000000000000000000000000000000000002
79+
Raw New Value: 0x0000000000000000000000000000000000000000000000000000000000000003
80+
Decoded Kind: uint256
81+
Decoded Old Value: 2
82+
Decoded New Value: 3
83+
84+
Summary: Increment nonce in ProxyAdminOwner
85+
86+
----- DecodedStateDiff[1] -----
87+
Who: 0x0a7361e734cf3f0394B0FC4a45C74E7a4Ec70940
88+
Contract: ProxyAdminOwner - OP Mainnet
89+
Chain ID: 10
90+
Raw Slot: 0xe23f453082938f6d8fda616d15a8d5919aec431dff18fc69ddf7fd4cd01bd59e
91+
Raw Old Value: 0x0000000000000000000000000000000000000000000000000000000000000000
92+
Raw New Value: 0x0000000000000000000000000000000000000000000000000000000000000001
93+
Decoded Kind: uint256
94+
Decoded Old Value: 0
95+
Decoded New Value: 1
96+
97+
Summary: Transaction approval
98+
Detail: Approves the ownership transfer initiation transaction on behalf of the signing safe. The slot derivation depends on which safe is being signed for. This can be derived with `cast index bytes32 0xd806ab578902502aa5b3caf2d4a5d03b14a9e9522c8b9214ba4e05af1c39e2f4 $(cast index address $SIGNER_SAFE 8)`. For OP signers, the slot should be `0x8f6ea3dc592330bb5d3d2f07897e65e16fda3259be1ad4bc00d0033f29399eee`.
99+
----- DecodedStateDiff[2] -----
100+
Who: 0x6e1DFd5C1E22A4677663A81D24C6BA03561ef0f6 or 0x2501c477D0A35545a387Aa4A3EEe4292A9a8B3F0
101+
Contract: Signer Safe - OP Mainnet
102+
Chain ID: 10
103+
Raw Slot: 0x0000000000000000000000000000000000000000000000000000000000000005
104+
Raw Old Value: 0x0000000000000000000000000000000000000000000000000000000000000000
105+
Raw New Value: 0x0000000000000000000000000000000000000000000000000000000000000001
106+
Decoded Kind: uint256
107+
Decoded Old Value: 0
108+
Decoded New Value: 1
109+
110+
Summary: Increment nonce in Signer safe
111+
112+
----- DecodedStateDiff[3] -----
113+
Who: 0xb3C2f9fC2727078EC3A2255410e83BA5B62c5B5f
114+
Contract: SmartEscrow - OP Mainnet
115+
Chain ID: 10
116+
Raw Slot: 0x0000000000000000000000000000000000000000000000000000000000000001
117+
Raw Old Value: 0x0000000697800000000000000000000000000000000000000000000000000000
118+
Raw New Value: 0x000000069780000067fba22c8cc51c3008b3f03fe483b28b8db90e19cf076a6d
119+
Decoded Kind: uint48, uint48, address
120+
Decoded Old Value: 432000, 0, 0x0000000000000000000000000000000000000000
121+
Decoded New Value: 432000, 1744544300, 0x8cC51c3008b3f03Fe483B28B8Db90e19cF076a6d
122+
123+
Summary: Sets the pending default admin for SmartEscrow
124+
Detail: This is a packed storage slot containing three values: `_currentDelay`, `_pendingDefaultAdminSchedule` and `_pendingDefaultAdmin`. The `_currentDelay` is set to 432000 which is 5 days (in seconds). `_pendingDefaultAdminSchedule` gets set to `block.timestamp + _currentDelay`. NOTE: the `_pendingDefaultAdminSchedule` may be different from what you see in you Tenderly simulation - this is ok! It's derived based on the current block.timestamp. The `_pendingDefaultAdmin` address gets set to `0x8cC51c3008b3f03Fe483B28B8Db90e19cF076a6d` which is the aliased address of `0x7bB41C3008B3f03FE483B28b8DB90e19Cf07595c` (`ProxyAdminOwner`).
125+
126+
ATTENTION TASK REVIEWER: It is safe to continue if `_pendingDefaultAdminSchedule` is different than what is seen in the Tenderly state diff.
127+
128+
----- Additional Balance Changes -----
129+
Who: 0x420000000000000000000000000000000000001A
130+
Contract: L1FeeValue - OP Mainnet
131+
Chain ID: 10
132+
Old Balance: 1892652089755161
133+
New Balance: 1892663085405498
134+
135+
Summary: L1 fees collected from the transaction
136+
Detail: Note: these values may differ from what you see in the Tenderly simulation - that is ok!
137+
138+
----- Additional Nonce Changes -----
139+
Who: 0x6CD3850756b7894774Ab715D136F9dD02837De50
140+
141+
Details: Nonce Updates for all addresses listed above.
142+
Summary:
143+
- 0x6CD3850756b7894774Ab715D136F9dD02837De50 is the caller
144+
</pre>

‎mainnet/2025-04-07-init-smart-escrow-ownership-transfer/foundry.toml

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
[profile.default]
2+
src = 'src'
3+
out = 'out'
4+
libs = ['lib']
5+
broadcast = 'records'
6+
fs_permissions = [{ access = "read-write", path = "./" }]
7+
optimizer = true
8+
optimizer_runs = 999999
9+
solc_version = "0.8.15"
10+
via-ir = false
11+
remappings = [
12+
'@eth-optimism-bedrock/=lib/optimism/packages/contracts-bedrock/',
13+
'@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts',
14+
'@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts',
15+
'@rari-capital/solmate/=lib/solmate/',
16+
'@base-contracts/=lib/base-contracts',
17+
'solady/=lib/solady/src/',
18+
]
19+
20+
# See more config options https://github.com/foundry-rs/foundry/tree/master/config

0 commit comments

Comments
 (0)