From c8f73d5a14ecdf5518631a7182b358e73d2af769 Mon Sep 17 00:00:00 2001 From: agusduha Date: Fri, 7 Feb 2025 12:07:09 -0300 Subject: [PATCH] fix: dependency manager descope --- specs/interop/dependency-set.md | 38 +++--------- specs/interop/predeploys.md | 81 ------------------------- specs/interop/shared-lockbox-upgrade.md | 66 +++++--------------- specs/interop/shared-lockbox.md | 2 +- specs/interop/superchain-config.md | 16 +++-- 5 files changed, 36 insertions(+), 167 deletions(-) diff --git a/specs/interop/dependency-set.md b/specs/interop/dependency-set.md index 90435d34f..58c63bed1 100644 --- a/specs/interop/dependency-set.md +++ b/specs/interop/dependency-set.md @@ -6,9 +6,7 @@ - [Chain ID](#chain-id) - [Updating the Dependency Set](#updating-the-dependency-set) -- [Architecture](#architecture) - - [L2 DependencyManager](#l2-dependencymanager) - - [L1 SuperchainConfig](#l1-superchainconfig) + - [The CLUSTER_MANAGER Role](#the-cluster_manager-role) - [Future Considerations](#future-considerations) - [Layer 1 as Part of the Dependency Set](#layer-1-as-part-of-the-dependency-set) - [Security Considerations](#security-considerations) @@ -50,39 +48,21 @@ It is a known issue that not all software in the Ethereum ecosystem can handle 3 The dependency set is managed in the client software. Adding a chain to the dependency set is considered an upgrade to the network. It is not possible to remove chains from the dependency set. -During an upgrade, only the derivation pipeline (impersonating the `DEPOSITOR_ACCOUNT`) -can initiate dependency additions on L2. +The dependency set is managed by the L1 `SuperchainConfig` contract. It: -The dependency set is managed through a two-step process involving both L2 and L1 contracts: - -1. The L2 `DependencyManager` predeploy contract initiates the addition of a new dependency through a withdrawal transaction -2. The L1 `SuperchainConfig` contract processes this withdrawal and updates the L1-side dependency set - -## Architecture - -### L2 DependencyManager - -The L2 `DependencyManager` is a predeploy contract (0x4200000000000000000000000000000000000029) -that manages the L2-side dependency set. It: - -- Maintains the list of chain IDs in the dependency set -- Initiates withdrawal transactions to L1 when adding new dependencies -- Provides query methods to check dependency set membership and size - -More details can be found on the [Dependency Manager specification](./predeploys.md#dependencymanager). - -### L1 SuperchainConfig - -The L1 `SuperchainConfig` extends `SuperchainConfig` to manage the L1-side dependency set. It: - -- Processes withdrawal transactions from L2 `DependencyManager` - Maintains the L1-side dependency set - Manages authorized `OptimismPortal`s - Handles ETH liquidity migration to `SharedLockbox` when adding new dependencies -- Can only be updated by authorized portals through withdrawal transactions or the `CLUSTER_MANAGER` role +- Can only be updated by the `CLUSTER_MANAGER` role More details can be found on the [Superchain Config interop specification](./superchain-config.md#Overview). +### The CLUSTER_MANAGER Role + +The `CLUSTER_MANAGER` role is a privileged role in the `SuperchainConfig` contract that has the authority +to directly add chains to the dependency set. This role can add chains by calling `addDependency` and must +provide valid chain ID and `SystemConfig` contract addresses when doing so. + ## Future Considerations ### Layer 1 as Part of the Dependency Set diff --git a/specs/interop/predeploys.md b/specs/interop/predeploys.md index 0082eb8c3..62191d83e 100644 --- a/specs/interop/predeploys.md +++ b/specs/interop/predeploys.md @@ -65,15 +65,6 @@ - [`RelayedERC20`](#relayederc20) - [Diagram](#diagram) - [Invariants](#invariants-1) -- [DependencyManager](#dependencymanager) - - [Functions](#functions-4) - - [`addDependency`](#adddependency) - - [`isInDependencySet`](#isindependencyset) - - [`dependencySetSize`](#dependencysetsize) - - [`dependencySet`](#dependencyset) - - [Events](#events-3) - - [`DependencyAdded`](#dependencyadded) - - [Invariants](#invariants-2) - [Security Considerations](#security-considerations) @@ -825,78 +816,6 @@ The bridging of `SuperchainERC20` using the `SuperchainTokenBridge` will require - `sendERC20()` should emit a `SentERC20` event. ` - `relayERC20()` should emit a `RelayedERC20` event. -## DependencyManager - -| Constant | Value | -| -------- | -------------------------------------------- | -| Address | `0x4200000000000000000000000000000000000029` | - -The `DependencyManager` is a predeploy contract that manages the L2-side dependency set. It maintains the list of chain IDs -that are part of the dependency set and initiates withdrawal transactions to add new dependencies. - -### Functions - -#### `addDependency` - -Initiates the addition of a new chain to the dependency set through a withdrawal transaction. - -```solidity -function addDependency(uint256 _chainId) external; -``` - -- MUST only be callable by the `DEPOSITOR_ACCOUNT` -- MUST revert if the chain ID is already in the dependency set -- MUST revert if the chain ID is the same as the current chain -- MUST revert if adding the chain would exceed the maximum size (255) -- MUST initiate a withdrawal transaction to the L1 `SuperchainConfigInterop` - -#### `isInDependencySet` - -Returns whether a chain ID is in the dependency set. - -```solidity -function isInDependencySet(uint256 _chainId) public view returns (bool); -``` - -- MUST return true if the chain ID is the current chain's ID -- MUST return true if the chain ID is in the dependency set -- MUST return false otherwise - -#### `dependencySetSize` - -Returns the number of chains in the dependency set. - -```solidity -function dependencySetSize() external view returns (uint8); -``` - -#### `dependencySet` - -Returns the list of chain IDs in the dependency set. - -```solidity -function dependencySet() external view returns (uint256[] memory); -``` - -### Events - -#### `DependencyAdded` - -MUST be triggered when a new dependency is added to the set. - -```solidity -event DependencyAdded(uint256 indexed chainId); -``` - -### Invariants - -- Only the `DEPOSITOR_ACCOUNT` can add dependencies -- A chain cannot be added to its own dependency set -- A chain cannot be added more than once -- The dependency set cannot exceed 255 entries -- A chain's own chain ID is always implicitly part of its dependency set -- MUST initiate a withdrawal transaction to the L1 `SuperchainConfigInterop` when adding a new dependency - ## Security Considerations TODO diff --git a/specs/interop/shared-lockbox-upgrade.md b/specs/interop/shared-lockbox-upgrade.md index d6f055f06..5da64146b 100644 --- a/specs/interop/shared-lockbox-upgrade.md +++ b/specs/interop/shared-lockbox-upgrade.md @@ -6,8 +6,6 @@ - [Overview](#overview) - [Upgrade Process](#upgrade-process) - - [L2 Side: Initiate Dependency Addition](#l2-side-initiate-dependency-addition) - - [L1 Side: Process Addition](#l1-side-process-addition) - [ETH Migration](#eth-migration) - [Diagram](#diagram) - [Future Considerations / Additional Notes](#future-considerations--additional-notes) @@ -17,42 +15,16 @@ ## Overview When a new chain joins the op-governed dependency set, it must integrate with the `SharedLockbox` -to participate in unified ETH liquidity management. -This is an irreversible process that requires coordination between L1 and L2 components. +to participate in unified ETH liquidity management. This process is initiated by the `CLUSTER_MANAGER` role. ## Upgrade Process -### L2 Side: Initiate Dependency Addition - -1. The derivation pipeline (impersonating the `DEPOSITOR_ACCOUNT`) calls - `addDependency(address,uint256,address)` on the L2 `DependencyManager` predeploy with: - - - `_superchainConfig`: The L1 `SuperchainConfig` contract address - - `_chainId`: The chain ID to add to the dependency set - - `_systemConfig`: The L1 `SystemConfig` contract address for the chain being added - -2. The `DependencyManager` validates the request by: - - - Checking that the caller is the `DEPOSITOR_ACCOUNT` - - Ensuring the chain ID isn't already in the set or the current chain's ID - - Adding the chain ID to the internal dependency set if validation passes - -3. Upon successful validation, the `DependencyManager`: - - - Calls `initiateWithdrawal` on the `L2ToL1MessagePasser` predeploy - - Encodes a call to `SuperchainConfig.addDependency(_chainId, _systemConfig)` - - Emits a `DependencyAdded` event with the chain ID, system config, and superchain config addresses - -4. The withdrawal transaction is queued in the `L2ToL1MessagePasser`, ready to be proven and finalized on L1 - -### L1 Side: Process Addition - -1. The withdrawal transaction is proven and finalized through the `OptimismPortal` +1. The `CLUSTER_MANAGER` role calls `addDependency` on the `SuperchainConfig` + contract with the new chain ID and it's system config address 2. The `SuperchainConfig` processes the addition by: - - Validating the request came from an authorized portal or cluster manager - - If from a portal, verifying the L2 sender is the `DependencyManager` predeploy + - Validating the request came from the cluster manager - Verifying the chain ID isn't already in the dependency set - Adding the chain ID to the dependency set - Getting the chain's portal address from its `SystemConfig` @@ -63,9 +35,12 @@ This is an irreversible process that requires coordination between L1 and L2 com - Checking the portal isn't already authorized - Adding the portal to the authorized portals mapping - Triggering ETH migration via `migrateLiquidity()` + - In this step the `OptimismPortal`'s ETH balance is transferred to the `SharedLockbox` 4. The `OptimismPortal` migrates its ETH: - Sets migrated flag to true + - This is necessary to start using the `SharedLockbox` for ETH operations, + if not set the `OptimismPortal` will continue using it's own ETH balance. - Transfers entire ETH balance to `SharedLockbox` via `lockETH()` - `SharedLockbox` emits `ETHLocked` event - Portal emits `ETHMigrated` event @@ -76,7 +51,6 @@ After authorization, the `OptimismPortal`'s ETH liquidity is migrated to the `Sh 1. The `OptimismPortal`'s ETH balance is transferred to the `SharedLockbox` 2. The `OptimismPortal` is configured to use the `SharedLockbox` for all future ETH operations -3. The migration is marked as complete After migration: @@ -88,25 +62,12 @@ After migration: ```mermaid sequenceDiagram - participant Pipeline as Derivation Pipeline - participant DM as DependencyManager - participant L2MP as L2ToL1MessagePasser - participant User - participant Portal as OptimismPortal + participant ClusterManager participant Config as SuperchainConfig + participant Portal as OptimismPortal participant Lockbox as SharedLockbox - Note over Pipeline: Client Side - Note over DM: L2 Side - Pipeline->>DM: addDependency(superchainConfig, chainId, systemConfig) - DM->>DM: validate request - DM->>L2MP: initiateWithdrawal(SuperchainConfig.addDependency) - DM-->>DM: emits DependencyAdded - - Note over Portal: L1 Side - User->>Portal: prove withdrawal - User->>Portal: finalize withdrawal - Portal->>Config: addDependency(chainId, systemConfig) + ClusterManager->>Config: addDependency(chainId, systemConfig) Config->>Config: validate & add to set Config->>Config: authorize portal Config->>Portal: migrateLiquidity() @@ -114,10 +75,13 @@ sequenceDiagram Lockbox->>Config: authorizedPortals(portal) Lockbox-->>Lockbox: emits ETHLocked Portal-->>Portal: emits ETHMigrated + Config-->>Config: emits DependencyAdded ``` ## Future Considerations / Additional Notes -- Before calling `addDependency`, it MUST be ensured that the `chainId` and `systemConfig` match +- Before calling `addDependency`, it MUST be ensured that the `chainId` and `systemConfig` match. + This means that the `systemConfig` address is the correct one for the chain ID. There is no on-chain source of truth + for this information, so it is the responsibility of the `CLUSTER_MANAGER` to ensure the correct parameters are used. -- The `OptimismPortal` MUST be updated before finalizing the withdrawal transaction +- The `OptimismPortal` MUST be updated before initiating the migration diff --git a/specs/interop/shared-lockbox.md b/specs/interop/shared-lockbox.md index 14760fda5..8c483c1c0 100644 --- a/specs/interop/shared-lockbox.md +++ b/specs/interop/shared-lockbox.md @@ -56,7 +56,7 @@ function lockETH() external payable; **`unlockETH`** -Withdraws a specified amount of ETH from the lockbox's liquidity pool. +Withdraws a specified amount of ETH from the lockbox's liquidity pool to the `OptimismPortal` calling it. - Only authorized `OptimismPortal` addresses MUST be allowed to interact. - The function MUST NOT revert when called by an authorized `OptimismPortal` unless paused diff --git a/specs/interop/superchain-config.md b/specs/interop/superchain-config.md index 0a4ac479b..e4c6a4bb8 100644 --- a/specs/interop/superchain-config.md +++ b/specs/interop/superchain-config.md @@ -12,6 +12,7 @@ - [`authorizedPortals`](#authorizedportals) - [`dependencySet`](#dependencyset) - [`dependencySetSize`](#dependencysetsize) + - [`isInDependencySet`](#isindependencyset) - [Events](#events) - [`DependencyAdded`](#dependencyadded) - [Invariants](#invariants) @@ -63,8 +64,7 @@ between chains in the dependency set: ### `addDependency` -Adds a new chain to the dependency set. Can only be called by an authorized portal via a withdrawal transaction -initiated by the `DependencyManager`, or by the `CLUSTER_MANAGER` role. +Adds a new chain to the dependency set. Can only be called by the `CLUSTER_MANAGER` role. ```solidity function addDependency(uint256 _chainId, address _systemConfig) external; @@ -94,6 +94,14 @@ Returns the number of chains in the dependency set. function dependencySetSize() external view returns (uint8); ``` +### `isInDependencySet` + +Returns whether a chain ID is part of the dependency set. + +```solidity +function isInDependencySet(uint256 _chainId) external view returns (bool); +``` + ## Events ### `DependencyAdded` @@ -106,9 +114,7 @@ event DependencyAdded(uint256 indexed chainId, address indexed systemConfig, add ## Invariants -- If the chain is added through a withdrawal transaction, the L2 sender MUST be the `DependencyManager` predeploy contract. - -- If the chain is NOT added through a withdrawal transaction, the msg sender MUST be the `CLUSTER_MANAGER`. +- The sender MUST be the `CLUSTER_MANAGER`. - A chain CANNOT be added to the dependency set if: