feat: ETH lockbox redesign

protocol/eth-shared-lockbox.md

@@ -6,7 +6,7 @@ This document discusses possible solutions to address the constraints on ETH wit
 
 # Summary
 
-With interoperable ETH, withdrawals may fail if the referenced `OptimismPortal` lacks sufficient ETH—especially for large amounts or on OP Chains with low liquidity—since ETH liquidity isn't shared at the L1 level. To prevent users from being stuck, several solutions have been explored. Currently, the Superchain design favors the `SharedLockbox` and extends the `SuperchainConfig` as a *dependency set manager*, which is considered the most effective solution.
+With interoperable ETH, withdrawals may fail if the referenced `OptimismPortal` lacks sufficient ETH—especially for large amounts or on OP Chains with low liquidity—since ETH liquidity isn't shared at the L1 level. To prevent users from being stuck, several solutions have been explored. Currently, the Superchain design favors the `ETHLockbox`, which is considered the most effective solution.
 
 # Problem Statement + Context
 
@@ -35,125 +35,82 @@ OP Chains will be governed within a common Chain Cluster governance entity (the
 
 ### Shared Bridging and SuperchainWETH usage
 
-In any OP Chain that joins the cluster, it is assumed that `SuperchainWETH` has been deployed in advance prior to being added to the interoperable graph. As a result, the equivalence between ETH deposits and withdrawal history and the actual ETH supply will vary from the outset. In a world with freedom of movement, all real ETH liquidity is theoretically shared across the entire cluster eventually, regardless of how deposits are handled.
+In any OP Chain that joins the cluster, it is assumed that `SuperchainWETH` has been deployed in advance prior to being added to the interoperable graph. As a result, the equivalence between ETH deposits and withdrawal history and the actual ETH supply will vary from the outset. In a world with freedom of movement, all real ETH liquidity is theoretically shared across the entire cluster eventually, regardless of how deposits are handled.
 
 # Solution
 
-The existing problem and considerations motivate us to propose an L1 shared liquidity design through the introduction of a new `SharedLockbox` on L1, which serves as a singleton contract for ETH, given a defined set of interoperable chains. To ensure consistency, the `SuperchainConfig` is extended to act as the *dependency set manager*, controlling the op-governed dependency set that the lockbox uses as a source of truth. New ETH deposits will be directed to the lockbox, with the same process applied to ETH withdrawals.
+The existing problem and considerations motivate us to propose an L1 shared liquidity design through the introduction of a new `ETHLockbox` on L1, which serves as a singleton contract for ETH, given a defined set of interoperable chains. New ETH deposits will be directed to the lockbox, with the same process applied to ETH withdrawals.
 
 ### Spec changes
 
 The core proposed changes are as follows:
 
-- **Modify the `SuperchainConfig` contract**: Extend this contract to manage the dependency set of each chain, interacting with each `SystemConfig`.
-- **Introduce the `SharedLockbox` contract**: This contract acts as an escrow for ETH, receiving deposits and allowing withdrawals from approved `OptimismPortal` contracts. The `SuperchainConfig` contract serves as the source of truth of the lockbox.
-- **Modify the `OptimismPortal`**: To forward ETH into the `SharedLockbox` when `depositTransaction` is called, with the inverse process applying when `finalizeWithdrawal` is called.
+- **Introduce the `ETHLockbox` contract**: This contract acts as an escrow for ETH, receiving deposits and allowing withdrawals from approved `OptimismPortal` contracts. It is proxied and owned by the L1 `ProxyAdmin` contract.
+- **Modify the `OptimismPortal`**: To forward ETH into the `ETHLockbox` when `depositTransaction` is called, with the inverse process applying when `finalizeWithdrawal` is called.
 
-### Managing op-governed dependency set through `SuperchainConfig`
+### `ETHLockbox` implementation
 
-The `SuperchainConfig` contract will serve as the single point for managing the dependency set of a cluster and will be managed by the admin as occurs in other L1 OP contracts. This contract interacts with every `SystemConfig` contract involved. Since the dependency graph follows a simple dependency, it only stores a mapping (or array) of chains added, e.g. given a `chainId`.
-
-```solidity
-// Mapping from chainId to SystemConfig address
-mapping(uint256 _chainId => ISystemConfig) public systemConfigs;
-
-// Current dependency set list
-EnumerableSet.UintSet private _dependencySet;
-```
-
-Adding a new chain can be done by introducing a new function called `addChain`. The process would look as follows:
-
-1. The `updater` calls the function with `chainId` and `SystemConfig`.
-2. An external call is made to each `SystemConfig` from already added chains with the new `chainId`.
-3. The new `SystemConfig` is called to add all previously existing `chainId` from `SuperchainConfig` to itself.
-4. Each call concludes by emitting a `DepositedTransaction` event.
-5. The `OptimismPortal` address is stored in the `Sharedlockbox` mapping.
-6. Each chain asynchronously includes each new deposit and updates `dependencySet` in `L1Block`.
-
-The [Superchain Registry](https://github.com/ethereum-optimism/superchain-registry) or the [OP Contracts Manager](https://specs.optimism.io/experimental/op-contracts-manager.html?highlight=chain#chain-id-source-of-truth) can be used as the source of truth to add chains that have been verified beforehand as compatible.
-
-A code example would look like this:
+A minimal set of functions should include:
 
-```solidity
-function addChain(uint256 _chainId, address _systemConfig) external {
-  require(msg.sender == updater(), "Unauthorized");
-  // Add to the dependency set and check it is not already added (`add()` returns false if it already exists)
-  require(_dependencySet.add(_chainId), "Chain already added");
+- `lockETH`: Accepts ETH from the `depositTransaction` originating from a valid `OptimismPortal`.
+- `unlockETH`: Releases ETH from the `finalizeWithdrawalTransaction` originating from a valid `OptimismPortal`.
 
-  // Store the system config
-  systemConfigs[_chainId] = _systemConfig;
+Access control for `lockETH` and `unlockETH` is validated against the mapping of authorized `OptimismPortal` addresses.
 
-  // Loop through the dependency set and update the dependency for each chain
-  for (uint256 i; i < _dependencySet.length() - 1; i++) {
+The `ProxyAdmin` owner can add `OptimismPortal` addresses to the `ETHLockbox` contract. This role can be introspected in the `ETHLockbox` contract.
 
-    uint256 currentId = _dependencySet.at(i);
+### `OptimismPortal` upgrade process
 
-    // Skip recently added chain
-    if (_chainId == currentId) continue;
+A ETH migration function can be added to the `OptimismPortal` to allow transferring all ETH to the `ETHLockbox` at any time. The `ETHLockbox` address is set during initialization of the `OptimismPortal` and cannot be changed afterwards.
 
-    systemConfigs[currentId].addDependency(_chainId);
+The migration process would work as follows:
 
-    systemConfigs[_chainId].addDependency(currentId);
-  }
+- Only the `ProxyAdmin` owner can trigger the migration
+- The `OptimismPortal` MUST be first authorized in the `ETHLockbox`
+- Transfer the entire ETH balance of the `OptimismPortal` to the pre-configured `ETHLockbox`
 
-  address portal = _systemConfig.optimismPortal();
+### `ETHLockbox` merge process
 
-  // Authorize the portal on the shared lockbox
-  SHARED_LOCKBOX.authorizePortal(portal);
+The `ETHLockbox` includes a migration function to allow transferring all ETH to another existing lockbox. This enables merging liquidity pools by migrating ETH from one lockbox to another, allowing multiple portals to use the same shared liquidity.
 
-  emit ChainAdded(_chainId, _systemConfig, portal);
-}
-```
+The merge process has two parts:
 
-Note that, under the specified flow, the dependency set consistently maintains the form of a [complete graph](https://en.wikipedia.org/wiki/Complete_graph) at all times.
+1. Destination lockbox preparation:
 
-### `SharedLockbox` implementation
+- Only the `ProxyAdmin` owner can approve a specific source lockbox to send ETH
+- This prevents receiving ETH from unauthorized or incorrect lockboxes
 
-A minimal set of functions should include:
+2. Source lockbox migration:
 
-- `lockETH`: Accepts ETH from the `depositTransaction` originating from a valid `OptimismPortal`.
-- `unlockETH`: Releases ETH from the `finalizeWithdrawalTransaction` originating from a valid `OptimismPortal`.
+- Only the `ProxyAdmin` owner can trigger the migration
+- The destination lockbox is provided as a parameter during migration
+- The `ProxyAdmin` owner of the source lockbox must be the same as the `ProxyAdmin` owner of the destination lockbox
+- Transfer the entire ETH balance to the specified destination lockbox
+- After migration, the source lockbox will no longer be used by any `OptimismPortal`
 
-Access control for `lockETH` and `unlockETH` is validated against the mapping of authorized `OptimismPortal` addresses.
+This ensures a secure way to consolidate ETH liquidity from multiple lockboxes into a single one. After migration, the portal previously using the source lockbox would need to be updated to point to the destination lockbox.
 
-### `OptimismPortal` upgrade process
+## Diagram
 
-A one-time L1 liquidity migration is required for each approved chain. By using an intermediate contract denominated `LiquidityMigrator` during the upgrade, all ETH held by the `OptimismPortal` can be transferred to the `SharedLockbox`. This intermediate contract functions similarly to `StorageSetter` and is used for the sole purpose of transferring the ETH balance. After this migration, the `OptimismPortal` is upgraded to the new version with the desired functionality.
+```mermaid
+flowchart TD
+  SuperchainConfig ~~~ OptimismPortal --> SuperchainConfig
+  OptimismPortal ~~~ SuperchainConfig
 
-Importantly, the entire upgrade process—including migrating the ETH to the `SharedLockbox` and updating the `OptimismPortal` to the latest version—can be executed in a single batched transaction. This approach ensures migration without the necessity of maintaining a persistent migration function in the final contract.
+  SuperchainConfig ~~~ OptimismPortal' --> SuperchainConfig
+  OptimismPortal' ~~~ SuperchainConfig
 
-Note that migration processes may not be uniform and may vary according to the status of the chain seeking to join the OP-governed interoperable set. As stated in the previous section, chains are expected to ensure they reach the approved, OP Stack version. In practice, different migration paths could be implemented, for example, to allow chains to use the `SharedLockbox` from inception or migrate from a previous one, for example.
+  SuperchainConfig ~~~ OptimismPortal'' --> SuperchainConfig
+  OptimismPortal'' ~~~ SuperchainConfig
 
-```mermaid
-sequenceDiagram
-    participant L1PAO as L1 ProxyAdmin Owner
-    participant ProxyAdmin as ProxyAdmin
-    participant SuperchainConfig
-    participant OptimismPortalProxy as OptimismPortal
-    participant LiquidityMigrator
-    participant SharedLockbox
-
-    Note over L1PAO: Start batch
-
-    %% Step 1: Add chain to SuperchainConfig
-    L1PAO->>SuperchainConfig: addChain(chainId, SystemConfig address)
-
-    %% Step 2: Upgrade OptimismPortal to intermediate implementation that transfers ETH
-    L1PAO->>ProxyAdmin: upgradeAndCall()
-    ProxyAdmin->>OptimismPortalProxy: Upgrade to LiquidityMigrator
-    OptimismPortalProxy->>LiquidityMigrator: Call migrateETH()
-    OptimismPortalProxy->>SharedLockbox: Transfer entire ETH balance
-
-    %% Step 3: Upgrade OptimismPortal to final implementation
-    L1PAO->>ProxyAdmin: upgrade()
-    ProxyAdmin->>OptimismPortalProxy: Upgrade to new OptimismPortal implementation
-
-    Note over L1PAO: End batch
+  OptimismPortal --> ETHLockbox
+  OptimismPortal' --> ETHLockbox'
+  OptimismPortal'' --> ETHLockbox'
 ```
 
 ## Impact
 
-The following components require an audit of the new and modified contracts: `OptimismPortal`, `SharedLockbox`, and `SuperchainConfig`. This also includes the scripts necessary to perform the migration.
+The following components require an audit of the new and modified contracts: `OptimismPortal` and `ETHLockbox`.
 
 # Alternatives Considered
 
@@ -169,13 +126,10 @@ The problem with L2 reverts is that it breaks the ETH withdrawal guarantee invar
 
 [Another solution](https://github.com/ethereum-optimism/specs/issues/362#issuecomment-2332481041) involves allowing ETH withdrawals to be finalized by taking ETH from one or more `OptimismPortal` contracts. In a cluster, this is done by authorizing withdrawals across the set of chains. For example, if we have a dependency set composed by Chain A, B and C, a withdrawal initiated from A could be finalized by using funds from B and C if needed.
 
-The implementation would require iterating through the dependency set, determined on L1 to find the next `OptimismPortal` with available funds. This also means `OptimismPortal` would need to have authorization and validation logic to allow to extraction ETH given an arbitrary request dictated by the loop.
+The implementation would require iterating through the dependency set, determined on L1 to find the next `OptimismPortal` with available funds. This also means `OptimismPortal` would need to have authorization and validation logic to allow to extraction ETH given an arbitrary request dictated by the loop.
 **Implementation and security considerations**
 Since both approaches rely on multiple `OptimismPortal` contracts and access controls, the Shared Lockbox design stays as the minimal way to implement a shared liquidity approach. Instead, allowing a looping withdrawal into each `OptimismPortal` increases the code complexity and surface of bugs during the iterative checking.
 
 # Risks & Uncertainties
 
 - **Scalable security**: With interop, withdrawals are a critical flow to protect, especially for ETH, since it tentatively becomes the most bridged asset across the Superchain. This means proof systems, dedicated monitoring services, the Security Council, and the Guardian need to be proven to tolerate the growing number of chains.
-- **Necessity of gas optimizations**: the `addChain` function calls every `SystemConfig`, which will increase in number over time. This could lead to significant gas expenditure as the number of chains continues to grow. One possible solution could be to extend the current `addDependency`/`removeDependency` to accept an array of `chainId` values in a single deposit call. The same reasoning could apply to `L1Block`.
-- **Chain list consistency around OP contracts**: OP Chains can have different statuses over time, being potentially reflected under the presence of several lists, such as those in the `OPCM`, the `SuperchainConfig` and other registries. It would make sense to coordinate on implementing the most ideal chain registry for all expected use cases, including those described in this doc.
-- **`chainId` authenticity**: As mentioned above, dependency set management relies on the `chainId` value. This necessitates ensuring that each `chainId` is unique within the chain list and correctly references a `SystemConfig`. This also raises the question of whether `chainId` should be stored directly within the `SystemConfig` for added verification.