From c58eb2fc987246287f95d91852a74f41ac75074a Mon Sep 17 00:00:00 2001 From: agusduha <agusnduha@gmail.com> Date: Fri, 13 Dec 2024 10:49:37 -0300 Subject: [PATCH 1/6] feat: add shared lockbox invariants --- specs/interop/dependency-set.md | 16 ++++--- specs/interop/optimism-portal-interop.md | 40 ++++++++++++++-- specs/interop/shared-lockbox-upgrade.md | 27 ++++++----- specs/interop/shared-lockbox.md | 52 ++++++++++++++++++-- specs/protocol/superchain-configuration.md | 55 ++++++++++++++++------ 5 files changed, 148 insertions(+), 42 deletions(-) diff --git a/specs/interop/dependency-set.md b/specs/interop/dependency-set.md index 8c6351237..2f0176035 100644 --- a/specs/interop/dependency-set.md +++ b/specs/interop/dependency-set.md @@ -6,6 +6,7 @@ - [Chain ID](#chain-id) - [Updating the Dependency Set](#updating-the-dependency-set) + - [Invariants](#invariants) - [Security Considerations](#security-considerations) - [Layer 1 as Part of the Dependency Set](#layer-1-as-part-of-the-dependency-set) @@ -47,17 +48,18 @@ It is a known issue that not all software in the Ethereum can handle 32 byte cha ## Updating the Dependency Set -The `SystemConfig` is updated to manage a new role, `dependencyManager`. -It can only updated by the `ProxyAdmin` during an contract upgrade. -The sole holder of this role is the only address -permissioned to update (remove/add to) the dependency set of that chain. +The `SystemConfig` is updated to have the `SuperchainConfig` address and to manage the dependency set. -The `SystemConfig` is also updated to manage the dependency set. -The address with the `dependency manager` role can add or remove -chains from the dependency set through the `SystemConfig`. +The `SuperchainConfig` can add or remove chains from the dependency set through the `SystemConfig`. The `SystemConfig` MUST enforce that the maximum size of the dependency set is `type(uint8).max` or 255. +### Invariants + +- Only the `SuperchainConfig` contract MUST be able to add a new dependency + +- Only the `SuperchainConfig` contract MUST be able to remove a dependency + ## Security Considerations ### Layer 1 as Part of the Dependency Set diff --git a/specs/interop/optimism-portal-interop.md b/specs/interop/optimism-portal-interop.md index 2f72cdfe5..d83f3c022 100644 --- a/specs/interop/optimism-portal-interop.md +++ b/specs/interop/optimism-portal-interop.md @@ -7,12 +7,15 @@ - [Overview](#overview) - [Interface and properties](#interface-and-properties) - [Integrating `SharedLockbox`](#integrating-sharedlockbox) + - [Invariants](#invariants) <!-- END doctoc generated TOC please keep comment here to allow auto update --> ## Overview The `OptimismPortal` contract is upgraded to integrate the `SharedLockbox` and start using the shared ETH liquidity. +This liquidity consists of every ETH balance migrated from each `OptimismPortal` +when joining the op-governed dependency set. ### Interface and properties @@ -26,19 +29,30 @@ The `OptimismPortal` contract will add the following storage layout and modified ### Integrating `SharedLockbox` -The integration with the `SharedLockbox` involves adding extra steps when executing deposit transactions +The integration with the `SharedLockbox` involves extra steps when executing deposit transactions or finalizing withdrawal transactions. -These steps include locking and unlocking ETH without altering other aspects of the current `OptimismPortal` implementation. +These steps are locking and unlocking ETH without altering other aspects of the current `OptimismPortal` implementation. To implement this solution, the following changes are needed: **`depositTransaction`** Calls `lockETH` on the `SharedLockbox` with the `msg.value`. -- The function MUST call `lockETH` on the `SharedLockbox` if: +- The function MUST call `lockETH` with `msg.value` on the `SharedLockbox` if: - The token is `ETHER`. - `msg.value` is greater than zero. +```mermaid +sequenceDiagram + participant User + participant OptimismPortal + participant SharedLockbox + + User->>OptimismPortal: depositTransaction(...) + OptimismPortal->>SharedLockbox: lockETH() + OptimismPortal->>OptimismPortal: emit TransactionDeposited() +``` + **`finalizeWithdrawalTransactionExternalProof`** Calls `unlockETH` on the `SharedLockbox` with the `tx.value`. @@ -47,3 +61,23 @@ Calls `unlockETH` on the `SharedLockbox` with the `tx.value`. - The token is `ETHER`. - `tx.value` is greater than zero. - The ETH is received by the `OptimismPortal` and then sent with the withdrawal transaction + +```mermaid +sequenceDiagram + participant User + participant OptimismPortal + participant SharedLockbox + + User->>OptimismPortal: finalizeWithdrawalTransactionExternalProof(...) + OptimismPortal->>SharedLockbox: unlockETH(uint256 value) + SharedLockbox->>OptimismPortal: donateETH() + OptimismPortal->>OptimismPortal: emit WithdrawalFinalized() +``` + +### Invariants + +- It MUST lock the ETH amount on the `SharedLockbox` when on a deposit transaction with value greater than zero + +- It MUST unlock the ETH amount being withdrawn from the `SharedLockbox` if it is greater than zero + +- It MUST NOT hold any ETH balance from any deposit transaction diff --git a/specs/interop/shared-lockbox-upgrade.md b/specs/interop/shared-lockbox-upgrade.md index 168385b09..a11ad41c5 100644 --- a/specs/interop/shared-lockbox-upgrade.md +++ b/specs/interop/shared-lockbox-upgrade.md @@ -5,7 +5,7 @@ **Table of Contents** - [Overview](#overview) - - [Add the chain to the op-governed dependency set](#add-the-chain-to-the-op-governed-dependency-set) + - [Add the chain to the op-governed dependency set in `SuperchainConfig`](#add-the-chain-to-the-op-governed-dependency-set-in-superchainconfig) - [Migrate ETH liquidity from `OptimismPortal` to `SharedLockbox`](#migrate-eth-liquidity-from-optimismportal-to-sharedlockbox) - [`LiquidityMigrator`](#liquiditymigrator) - [`OptimismPortal` code upgrade](#optimismportal-code-upgrade) @@ -17,13 +17,12 @@ ## Overview -Based on the assumption that a chain joining the dependency set is an irreversible process, -the on-chain chains list is simplified by assuming that joining the Shared Lockbox is -equivalent to joining the op-governed dependency set. +Based on the assumption that a chain joining the op-governed dependency set is an irreversible process, +it is assume that joining the Shared Lockbox is equivalent to it. The upgrade process consists of three main points: -- Add the chain to the op-governed dependency set +- Add the chain to the op-governed dependency set in `SuperchainConfig` - Move ETH liquidity from `OptimismPortal` to `SharedLockbox` - Upgrade the code of `OptimismPortal` to include the `SharedLockbox` integration @@ -33,17 +32,17 @@ This process also requires that: - `SuperchainConfig` is upgraded to manage the dependency set - `SystemConfig` is upgraded to the interop contract version -### Add the chain to the op-governed dependency set +### Add the chain to the op-governed dependency set in `SuperchainConfig` The `SuperchainConfig` contract will be responsible for storing and managing the dependency set. Its `addChain` function will be used to add the chain to the dependency set and call the `SystemConfig` of each chain to keep them in sync. It will also allowlist the corresponding `OptimismPortal`, enabling it to lock and unlock ETH from the `SharedLockbox`. -Once this process is complete, the system will be ready to process deposits and withdrawals. +Once `addChain` is called, the system will be ready to process deposits and withdrawals. ### Migrate ETH liquidity from `OptimismPortal` to `SharedLockbox` -The ETH will be transferred from the `OptimismPortal` to the `SharedLockbox` using an intermediate contract. +The ETH will be transferred from the `OptimismPortal` to the `SharedLockbox` using the `LiquidityMigrator` contract. This contract functions similarly to upgrades using the `StorageSetter`, being updated immediately before to the real implementation. Its sole purpose is to transfer the ETH balance. This approach eliminates the need for adding code to move the liquidity to the lockbox that won't be used again. @@ -60,21 +59,22 @@ This approach avoids adding extra code to the `initialize` function, which could Transfers the entire ETH balance from the `OptimismPortal` to the `SharedLockbox`. -- It MUST transfer the whole ETH balance to the `SharedLockbox` when called. - ```solidity function migrateETH() external; ``` +**Invariants** + +- It MUST migrate the whole `OptimismPortal` ETH balance to the `SharedLockbox` + +- It MUST emit `ETHMigrated` when migrating the balance + ### `OptimismPortal` code upgrade The `OptimismPortal` will start locking and unlocking ETH through the `SharedLockbox`. It will continue to handle deposits and withdrawals but won't directly hold the ETH liquidity. To set this up, the upgrade function will be called via `ProxyAdmin` to implement the new code, which includes the necessary `SharedLockbox` integration. -The `SharedLockbox` address will be set during the `initialize` function. After this step, -the `OptimismPortal` will not be able to process deposits and withdrawals until the chain is registered -in `SuperchainConfig`. ## Batch transaction process @@ -109,6 +109,7 @@ sequenceDiagram %% Step 1: Add chain to SuperchainConfig L1PAO->>SuperchainConfig: addChain(chainId, SystemConfig address) + SuperchainConfig->>SharedLockbox: authorizePortal(OptimismPortal address) %% Step 2: Upgrade OptimismPortal to intermediate implementation that transfers ETH L1PAO->>ProxyAdmin: upgradeAndCall() diff --git a/specs/interop/shared-lockbox.md b/specs/interop/shared-lockbox.md index 9f2ea3a10..054c33ad3 100644 --- a/specs/interop/shared-lockbox.md +++ b/specs/interop/shared-lockbox.md @@ -8,6 +8,9 @@ - [Design](#design) - [Interface and properties](#interface-and-properties) - [Events](#events) +- [Invariants](#invariants) + - [System level invariants](#system-level-invariants) + - [Contract level invariants](#contract-level-invariants) - [Reference implementation](#reference-implementation) <!-- END doctoc generated TOC please keep comment here to allow auto update --> @@ -15,7 +18,7 @@ ## Overview With interoperable ETH, withdrawals will fail if the referenced `OptimismPortal` lacks sufficient ETH. -This is due to having the possibility to move ETH liquidity accross the different chains and it could happen +This is due to having the possibility to move ETH liquidity across the different chains and it could happen that a chain ends up with more liquidity than its `OptimismPortal`. The `SharedLockbox` improves the Superchain's interoperable ETH withdrawal user experience and avoids this issue. To do so, it unifies ETH L1 liquidity in a single contract (`SharedLockbox`), enabling seamless withdrawals of ETH @@ -28,8 +31,9 @@ It implements two main functions: `lockETH` for depositing ETH into the lockbox, and `unlockETH` for withdrawing ETH from the lockbox. These functions are called by the `OptimismPortal` contracts to manage the shared ETH liquidity when making deposits or finalizing withdrawals. -These `OptimismPortal`s will be allowlisted by the `SuperchanConfig` using the `authorizePortal` function +These `OptimismPortal`s will be allowlisted by the `SuperchainConfig` using the `authorizePortal` function when a chain is added. +The `SharedLockbox` contract is proxied and managed by the L1 `ProxyAdmin`. ### Interface and properties @@ -38,7 +42,8 @@ when a chain is added. Deposits and locks ETH into the lockbox's liquidity pool. - The function MUST accept ETH. -- Only authorized `OptimismPortal` addresses SHOULD be allowed to interact. +- Only authorized `OptimismPortal` addresses MUST be allowed to interact. +- The function MUST NOT revert when called by an authorized `OptimismPortal` - The function MUST emit the `ETHLocked` event with the `portal` that called it and the `amount`. ```solidity @@ -49,7 +54,8 @@ function lockETH() external payable; Withdraws a specified amount of ETH from the lockbox's liquidity pool. -- Only authorized `OptimismPortal` addresses SHOULD be allowed to interact. +- Only authorized `OptimismPortal` addresses MUST be allowed to interact. +- The function MUST NOT revert when called by an authorized `OptimismPortal` - The function MUST emit the `ETHUnlocked` event with the `portal` that called it and the `amount`. ```solidity @@ -60,7 +66,7 @@ function unlockETH(uint256 _value) external; Grants authorization to a specific `OptimismPortal` contract. -- Only `SuperchainConfig` address SHOULD be allowed to interact. +- Only `SuperchainConfig` address MUST be allowed to interact. - The function MUST add the specified address to the mapping of authorized portals. - The function MUST emit the [`PortalAuthorized`](#events) event when a portal is successfully added. @@ -94,6 +100,42 @@ MUST be triggered when `authorizePortal` is called event PortalAuthorized(address indexed portal); ``` +## Invariants + +### System level invariants + +- The ETH held in the SharedLockbox MUST never be less than the amount deposited but not yet withdrawn by the `OptimismPortal`s + +- The ETH unlocked by any `OptimismPortal` MUST NOT exceed the available shared liquidity in the `SharedLockbox`. + +- The total withdrawable ETH amount present on all the dependency set’s chains MUST NEVER be more than the amount held + by the `SharedLockbox` of the cluster + > With "withdrawable amount", the ETH balance held on `ETHLiquidity` is excluded + +### Contract level invariants + +- It MUST allow only authorized portals to lock ETH + +- It MUST allow only authorized portals to unlock ETH + +- Only the `SuperchainConfig` contract MUST be able to authorize an `OptimismPortal` + +- It MUST be in paused state if the `SuperchainConfig` is paused + +- No Ether MUST flow out of the contract when in a paused state + +- No `OptimismPortal` can be authorized when in a paused state + +- It MUST NOT trigger a new deposit when ETH amount is being unlocked from the `SharedLockbox` by the `OptimismPortal` + +- It MUST emit: + + - An `ETHLocked` event when locking ETH + + - An `ETHUnlocked` event when unlocking ETH + + - A `PortalAuthorized` event when authorizing a new portal + ## Reference implementation An example implementation could look like this: diff --git a/specs/protocol/superchain-configuration.md b/specs/protocol/superchain-configuration.md index 99624b4a8..54cbbbd14 100644 --- a/specs/protocol/superchain-configuration.md +++ b/specs/protocol/superchain-configuration.md @@ -12,7 +12,13 @@ - [Scope of pausability](#scope-of-pausability) - [Dependency manager](#dependency-manager) - [Interface and properties](#interface-and-properties) + - [`SHARED_LOCKBOX`](#shared_lockbox) + - [`systemConfigs`](#systemconfigs) + - [`dependencySet`](#dependencyset) + - [`addChain`](#addchain) - [Events](#events) + - [`ChainAdded`](#chainadded) + - [Invariants](#invariants) <!-- END doctoc generated TOC please keep comment here to allow auto update --> @@ -67,6 +73,8 @@ When the Pause is activated, the following methods are disabled: 1. `StandardBridge.finalizeBridgeERC20()` 1. `StandardBridge.finalizeBridgeETH()` 1. `L1ERC721Bridge.finalizeBridgeERC721()` +1. `SharedLockbox.unlockETH()` +1. `SharedLockbox.authorizePortal()` ## Dependency manager @@ -78,33 +86,34 @@ It will also allow to add a chain to the op-governed cluster and update each cha The contract will add the following storage layout and function: -**`SHARED_LOCKBOX`** +#### `SHARED_LOCKBOX` - An immutable address pointing to the `SharedLockbox` contract. - This address MUST be immutable because there's only one `SharedLockbox` for each cluster. -**`systemConfigs`** +#### `systemConfigs` - A mapping that associates chain IDs with their respective SystemConfig addresses. - It will be used when updating dependencies along each chain. -**`dependencySet`** +#### `dependencySet` -- An `EnumerableSet` that stores the current list of chain IDs in the dependency set. +- Stores the current list of chain IDs in the op-governed dependency set. - It MUST contain all the chain IDs of the chains that integrate the corresponding Superchain network. -**`addChain`** +#### `addChain` The `addChain` function adds a new chain to the op-governed cluster. -- It SHOULD only be callable by the authorized `updater` role of the `SuperchainConfig`. -- It MUST NOT add a chain ID to the dependency set if it is already included. -- It MUST check that the new chain dependency set size is zero. -- It MUST update all chain dependencies through deposit txs to form a complete mesh graph. -- It MUST store the provided `SystemConfig` address in the `systemConfigs` mapping. -- It MUST allowlist the new chain's `OptimismPortal` in the `SharedLockbox`. -- It MUST emit the `ChainAdded` event with the `chainId` and - its corresponding `SystemConfig` and `OptimismPortal`. +It can only be called by the `upgrader` role (TBD) in the `SuperchainConfig` and ensures that the chain ID +is not already included in the dependency set. + +Before proceeding, it verifies that the new chain's dependency set size is zero. +The function updates all chain dependencies by executing deposit transactions to form a complete mesh graph, +stores the provided `SystemConfig` address in the `systemConfigs` mapping, and allowlists the +new chain's `OptimismPortal` in the `SharedLockbox`. + +Finally, it emits the `ChainAdded` event with the `chainId`, its corresponding `SystemConfig`, and `OptimismPortal`. ```solidity function addChain(uint256 _chainId, address _systemConfig) external; @@ -112,10 +121,28 @@ function addChain(uint256 _chainId, address _systemConfig) external; ### Events -**`ChainAdded`** +#### `ChainAdded` MUST be triggered when `addChain` is called ```solidity event ChainAdded(uint256 indexed chainId, address indexed systemConfig, address indexed portal); ``` + +### Invariants + +- Only the `upgrader` role (to be defined) MUST be able to add a new chain to the dependency set + +- The chain being added MUST NOT have any other dependencies before joining a cluster + +- The same chain MUST NOT be added more than once + +- It MUST add the new chain as a dependency on each chain of the cluster + +- It MUST add the whole cluster as dependency set for the new chain + +- It MUST NOT add the new chain to its own dependency set + +- It MUST authorize the new chain’s `OptimismPortal` to interact with the `SharedLockbox` of the cluster + +- It MUST emit a `ChainAdded` event when the chain is added From 40f7c9c93df5a64fcecaf942af8e8497b4ff57c4 Mon Sep 17 00:00:00 2001 From: agusduha <agusnduha@gmail.com> Date: Mon, 16 Dec 2024 10:42:29 -0300 Subject: [PATCH 2/6] fix: remove immutable variable --- specs/interop/optimism-portal-interop.md | 17 +++-------------- specs/interop/shared-lockbox-upgrade.md | 2 +- specs/protocol/superchain-configuration.md | 1 + 3 files changed, 5 insertions(+), 15 deletions(-) diff --git a/specs/interop/optimism-portal-interop.md b/specs/interop/optimism-portal-interop.md index d83f3c022..7e2acf643 100644 --- a/specs/interop/optimism-portal-interop.md +++ b/specs/interop/optimism-portal-interop.md @@ -5,7 +5,6 @@ **Table of Contents** - [Overview](#overview) - - [Interface and properties](#interface-and-properties) - [Integrating `SharedLockbox`](#integrating-sharedlockbox) - [Invariants](#invariants) @@ -17,21 +16,11 @@ The `OptimismPortal` contract is upgraded to integrate the `SharedLockbox` and s This liquidity consists of every ETH balance migrated from each `OptimismPortal` when joining the op-governed dependency set. -### Interface and properties - -The `OptimismPortal` contract will add the following storage layout and modified functions: - -**`SHARED_LOCKBOX`** - -- An immutable address pointing to the `SharedLockbox` contract. -- This address MUST be immutable because all `OptimismPortals` will point to the same `SharedLockbox`, - and this address SHOULD not change. - ### Integrating `SharedLockbox` -The integration with the `SharedLockbox` involves extra steps when executing deposit transactions -or finalizing withdrawal transactions. -These steps are locking and unlocking ETH without altering other aspects of the current `OptimismPortal` implementation. +The integration with the `SharedLockbox` locking ETH when executing deposit transactions and unlocking ETH +when finalizing withdrawal transactions, without altering other aspects of the current `OptimismPortal` implementation. + To implement this solution, the following changes are needed: **`depositTransaction`** diff --git a/specs/interop/shared-lockbox-upgrade.md b/specs/interop/shared-lockbox-upgrade.md index a11ad41c5..1f7700f66 100644 --- a/specs/interop/shared-lockbox-upgrade.md +++ b/specs/interop/shared-lockbox-upgrade.md @@ -18,7 +18,7 @@ ## Overview Based on the assumption that a chain joining the op-governed dependency set is an irreversible process, -it is assume that joining the Shared Lockbox is equivalent to it. +it is assumed that joining the Shared Lockbox is equivalent to it. The upgrade process consists of three main points: diff --git a/specs/protocol/superchain-configuration.md b/specs/protocol/superchain-configuration.md index 54cbbbd14..409b62546 100644 --- a/specs/protocol/superchain-configuration.md +++ b/specs/protocol/superchain-configuration.md @@ -47,6 +47,7 @@ StandardBridge --> SuperchainConfig L1ERC721Bridge --> SuperchainConfig L1CrossDomainMessenger --> SuperchainConfig OptimismPortal --> SuperchainConfig +SharedLockbox --> SuperchainConfig ``` ### Pausability From 641219ed739465412b0430b51445a21f928b9f3c Mon Sep 17 00:00:00 2001 From: agusduha <agusnduha@gmail.com> Date: Mon, 16 Dec 2024 14:24:17 -0300 Subject: [PATCH 3/6] feat: add upgrader role --- specs/protocol/superchain-configuration.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specs/protocol/superchain-configuration.md b/specs/protocol/superchain-configuration.md index 409b62546..a6c2adbd3 100644 --- a/specs/protocol/superchain-configuration.md +++ b/specs/protocol/superchain-configuration.md @@ -35,6 +35,7 @@ The `SuperchainConfig` contract manages the following configuration values: - `PAUSED_SLOT`: A boolean value indicating whether the Superchain is paused. - `GUARDIAN_SLOT`: The address of the guardian, which can pause and unpause the system. +- `UPGRADER_SLOT`: The address of the upgrader, which can add a chain to the depenceny set. ## Configuration data flow @@ -106,7 +107,7 @@ The contract will add the following storage layout and function: The `addChain` function adds a new chain to the op-governed cluster. -It can only be called by the `upgrader` role (TBD) in the `SuperchainConfig` and ensures that the chain ID +It can only be called by the `UPGRADER` role in the `SuperchainConfig` and ensures that the chain ID is not already included in the dependency set. Before proceeding, it verifies that the new chain's dependency set size is zero. @@ -132,7 +133,7 @@ event ChainAdded(uint256 indexed chainId, address indexed systemConfig, address ### Invariants -- Only the `upgrader` role (to be defined) MUST be able to add a new chain to the dependency set +- Only the `UPGRADER` role MUST be able to add a new chain to the dependency set - The chain being added MUST NOT have any other dependencies before joining a cluster From 9d40a53f44b10c9bf7234fcfeb5136552b8f5a38 Mon Sep 17 00:00:00 2001 From: agusduha <agusnduha@gmail.com> Date: Mon, 16 Dec 2024 14:49:07 -0300 Subject: [PATCH 4/6] feat: add authorized invariants to the portal --- specs/interop/optimism-portal-interop.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/specs/interop/optimism-portal-interop.md b/specs/interop/optimism-portal-interop.md index 7e2acf643..3fc70d4e8 100644 --- a/specs/interop/optimism-portal-interop.md +++ b/specs/interop/optimism-portal-interop.md @@ -30,6 +30,7 @@ Calls `lockETH` on the `SharedLockbox` with the `msg.value`. - The function MUST call `lockETH` with `msg.value` on the `SharedLockbox` if: - The token is `ETHER`. - `msg.value` is greater than zero. + - `OptimismPortal` address is authorized to interact with the `SharedLockbox`. ```mermaid sequenceDiagram @@ -49,6 +50,7 @@ Calls `unlockETH` on the `SharedLockbox` with the `tx.value`. - The function MUST call `unlockETH` on the `SharedLockbox` if: - The token is `ETHER`. - `tx.value` is greater than zero. + - `OptimismPortal` address is authorized to interact with the `SharedLockbox`. - The ETH is received by the `OptimismPortal` and then sent with the withdrawal transaction ```mermaid @@ -67,6 +69,11 @@ sequenceDiagram - It MUST lock the ETH amount on the `SharedLockbox` when on a deposit transaction with value greater than zero +- Only MUST lock ETH if the `OptimismPortal` is authorized to interact with the `SharedLockbox`. + - It MUST unlock the ETH amount being withdrawn from the `SharedLockbox` if it is greater than zero +- Only MUST unlock ETH if the `OptimismPortal` is authorized to interact with the `SharedLockbox`. + - It MUST NOT hold any ETH balance from any deposit transaction + if the `OptimismPortal` is authorized to interact with the `SharedLockbox`. From a4ae78dadf0e9a0c8f9a611af4fb3b1456e3014b Mon Sep 17 00:00:00 2001 From: agusduha <agusnduha@gmail.com> Date: Mon, 16 Dec 2024 15:59:09 -0300 Subject: [PATCH 5/6] fix: pr --- specs/interop/optimism-portal-interop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/interop/optimism-portal-interop.md b/specs/interop/optimism-portal-interop.md index 3fc70d4e8..7bc03306b 100644 --- a/specs/interop/optimism-portal-interop.md +++ b/specs/interop/optimism-portal-interop.md @@ -18,7 +18,7 @@ when joining the op-governed dependency set. ### Integrating `SharedLockbox` -The integration with the `SharedLockbox` locking ETH when executing deposit transactions and unlocking ETH +The integration with the `SharedLockbox` involves locking ETH when executing deposit transactions and unlocking ETH when finalizing withdrawal transactions, without altering other aspects of the current `OptimismPortal` implementation. To implement this solution, the following changes are needed: From d0b622dbc5bf323901f914096138ff7ee3d1f686 Mon Sep 17 00:00:00 2001 From: agusduha <agusnduha@gmail.com> Date: Tue, 17 Dec 2024 16:35:31 -0300 Subject: [PATCH 6/6] fix: add upgrader role and remove new portal invariants --- specs/interop/optimism-portal-interop.md | 18 ++++++++---------- specs/protocol/superchain-configuration.md | 9 +++++++++ 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/specs/interop/optimism-portal-interop.md b/specs/interop/optimism-portal-interop.md index 7bc03306b..b0a33eb87 100644 --- a/specs/interop/optimism-portal-interop.md +++ b/specs/interop/optimism-portal-interop.md @@ -6,6 +6,8 @@ - [Overview](#overview) - [Integrating `SharedLockbox`](#integrating-sharedlockbox) + - [`depositTransaction`](#deposittransaction) + - [`finalizeWithdrawalTransactionExternalProof`](#finalizewithdrawaltransactionexternalproof) - [Invariants](#invariants) <!-- END doctoc generated TOC please keep comment here to allow auto update --> @@ -16,6 +18,9 @@ The `OptimismPortal` contract is upgraded to integrate the `SharedLockbox` and s This liquidity consists of every ETH balance migrated from each `OptimismPortal` when joining the op-governed dependency set. +It is possible to upgrade to this version without being part of the op-governed dependency set. In this case, +the corresponding chain would need to deploy and manage its own `SharedLockbox` and `SuperchainConfig`. + ### Integrating `SharedLockbox` The integration with the `SharedLockbox` involves locking ETH when executing deposit transactions and unlocking ETH @@ -23,14 +28,13 @@ when finalizing withdrawal transactions, without altering other aspects of the c To implement this solution, the following changes are needed: -**`depositTransaction`** +#### `depositTransaction` Calls `lockETH` on the `SharedLockbox` with the `msg.value`. - The function MUST call `lockETH` with `msg.value` on the `SharedLockbox` if: - The token is `ETHER`. - `msg.value` is greater than zero. - - `OptimismPortal` address is authorized to interact with the `SharedLockbox`. ```mermaid sequenceDiagram @@ -43,14 +47,13 @@ sequenceDiagram OptimismPortal->>OptimismPortal: emit TransactionDeposited() ``` -**`finalizeWithdrawalTransactionExternalProof`** +#### `finalizeWithdrawalTransactionExternalProof` Calls `unlockETH` on the `SharedLockbox` with the `tx.value`. - The function MUST call `unlockETH` on the `SharedLockbox` if: - The token is `ETHER`. - `tx.value` is greater than zero. - - `OptimismPortal` address is authorized to interact with the `SharedLockbox`. - The ETH is received by the `OptimismPortal` and then sent with the withdrawal transaction ```mermaid @@ -69,11 +72,6 @@ sequenceDiagram - It MUST lock the ETH amount on the `SharedLockbox` when on a deposit transaction with value greater than zero -- Only MUST lock ETH if the `OptimismPortal` is authorized to interact with the `SharedLockbox`. - - It MUST unlock the ETH amount being withdrawn from the `SharedLockbox` if it is greater than zero -- Only MUST unlock ETH if the `OptimismPortal` is authorized to interact with the `SharedLockbox`. - -- It MUST NOT hold any ETH balance from any deposit transaction - if the `OptimismPortal` is authorized to interact with the `SharedLockbox`. +- It MUST NOT hold any ETH balance from any deposit transaction. diff --git a/specs/protocol/superchain-configuration.md b/specs/protocol/superchain-configuration.md index a6c2adbd3..8c42ffa31 100644 --- a/specs/protocol/superchain-configuration.md +++ b/specs/protocol/superchain-configuration.md @@ -13,6 +13,7 @@ - [Dependency manager](#dependency-manager) - [Interface and properties](#interface-and-properties) - [`SHARED_LOCKBOX`](#shared_lockbox) + - [`upgrader`](#upgrader) - [`systemConfigs`](#systemconfigs) - [`dependencySet`](#dependencyset) - [`addChain`](#addchain) @@ -84,6 +85,9 @@ The `SuperchainConfig` contract will manage and keep track of the dependency gra It will be queried as the source of truth to get which chains are part of the Superchain. It will also allow to add a chain to the op-governed cluster and update each chain’s dependency set. +The `SuperchainConfig` contract is updated with a new `UPGRADER` role that has the ability +to add a chain to the dependency set. + ### Interface and properties The contract will add the following storage layout and function: @@ -93,6 +97,11 @@ The contract will add the following storage layout and function: - An immutable address pointing to the `SharedLockbox` contract. - This address MUST be immutable because there's only one `SharedLockbox` for each cluster. +#### `upgrader` + +- An address with the ability to add a chain to the dependency set. +- The `upgrader` can only be set during initialization. + #### `systemConfigs` - A mapping that associates chain IDs with their respective SystemConfig addresses.