From 179cd2f5986f9552ebe6982f58cec94198cd1ee6 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Mon, 27 Jan 2025 11:24:14 -0600 Subject: [PATCH 01/17] WIP --- pages/stack/interop/_meta.json | 2 +- pages/stack/interop/superchain-weth.mdx | 15 ++++++++++----- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/pages/stack/interop/_meta.json b/pages/stack/interop/_meta.json index 2a45aa447..5282de6e2 100644 --- a/pages/stack/interop/_meta.json +++ b/pages/stack/interop/_meta.json @@ -3,7 +3,7 @@ "predeploy": "Interop predeploys", "message-passing": "Interop message passing", "op-supervisor": "OP Supervisor", - "superchain-weth": "SuperchainWETH (Interoperable ETH)", + "superchain-weth": "SuperchainWETH (Interoperable ETH)", "superchain-erc20": "SuperchainERC20", "security": "Cross-chain security", "tools": "Tools", diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index bef20fc98..5b052e3b7 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -6,13 +6,18 @@ description: Learn basic details about SuperchainWETH or Interoperable ETH. import { Callout } from 'nextra/components' -# SuperchainWETH (Interoperable ETH) +import { InteropCallout } from '@/components/WipCallout' + + + +# SuperchainWETH + +The [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract implements [ERC-7802](https://ethereum-magicians.org/t/erc-7802-crosschain-token-interface/21508) to enable ETH interoperability within the Superchain. + +ETH interoperability - - Interop is currently in active development and not yet ready for production use. The information provided here may change. Check back regularly for the most up-to-date information. - -Superchain WETH or Interoperable ETH is a specialized version of the standard WETH (Wrapped Ether) contract designed to enable seamless movement of ETH across the Superchain. It addresses the liquidity constraints and usability issues that arise when transferring ETH between different chains. +allows tokens to move securely across the Superchain by burning tokens on the source chain and minting an equivalent amount on the destination chain. This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. ## Features and benefits From 022ae2c984f61d4c23dad77f855282dc03584c37 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Mon, 27 Jan 2025 22:29:51 -0600 Subject: [PATCH 02/17] First draft --- pages/stack/interop/superchain-weth.mdx | 112 +++++++++++++----------- 1 file changed, 60 insertions(+), 52 deletions(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index 5b052e3b7..cc273041c 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -12,80 +12,88 @@ import { InteropCallout } from '@/components/WipCallout' # SuperchainWETH -The [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract implements [ERC-7802](https://ethereum-magicians.org/t/erc-7802-crosschain-token-interface/21508) to enable ETH interoperability within the Superchain. +The [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract works with [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol) +and [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) to enable ETH interoperability within the Superchain. +This is accomplished by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. +This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. -ETH interoperability - - -allows tokens to move securely across the Superchain by burning tokens on the source chain and minting an equivalent amount on the destination chain. This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. ## Features and benefits -* Enables seamless ETH transfers across different chains in the Superchain -* Maintains fungibility of ETH across the Superchain -* Provides liquidity for cross-chain transactions -* Improves user experience by abstracting complex bridging processes - - - The `SuperchainTokenBridge` can only rebalance assets across chains. It cannot mint or increase/decrease the total circulating supply. - +* Enables seamless ETH transfers across different chains in the Superchain +* Maintains fungibility of ETH across the Superchain +* Provides liquidity for cross-chain transactions +* Improves user experience by abstracting complex bridging processes ## How it works -Currently, L2-to-L2 ETH transfers between two interoperable chains require four separate transactions: +```mermaid -1. Wrap `ETH` to `SuperchainWETH`. -2. Call `SuperchainTokenBridge#SendERC20` to burn `SuperchainWETH` on source chain and relay a message to the destination chain that mints `SuperchainWETH` to the recipient (`crosschainBurn` is used). -3. Execute the message on the destination chain, triggering `SuperchainTokenBridge#RelayERC20` to mint `SuperchainWETH` to the recipient (`crosschainMint` is used). If the destination is a non-custom gas token chain, ETH is sourced from the `ETHLiquidity` contract. -4. Unwrap the received `SuperchainWETH` to `ETH`. +%%{ + init: { + "sequence": { + "wrap": true + } + } +}%% - -Abstraction is a possible future consideration to reduce this process to two transactions, which can be followed in the [design docs](https://github.com/ethereum-optimism/design-docs/pull/146/files). - - -```mermaid sequenceDiagram - participant User - participant Source Chain - participant Cross-Chain Messenger - participant Destination Chain - - User->>Source Chain: 1. Wrap ETH to SuperchainWETH - Source Chain->>Cross-Chain Messenger: 2. Burn SuperchainWETH and relay message - Cross-Chain Messenger->>Destination Chain: 3. Mint SuperchainWETH to recipient - User->>Destination Chain: 4. Unwrap SuperchainWETH to ETH + box rgba(0,0,0,0.1) Source Chain + participant src-liquidity as ETHLiquidity + participant src-weth as SuperchainWETH + end + actor user as User + participant any-offchain as User, Relayer, etc. + box rgba(0,0,0,0.1) Destination Chain + participant dst-l2Xl2 as L2ToL2CrossDomainMessenger + participant dst-weth as SuperchainWETH + participant dst-liquidity as ETHLiquidity + participant dst-final as ETH Destination + end + rect rgba(0,0,0,0.1) + note over src-weth, dst-l2Xl2: Initiating Message + user->>src-weth: 1. sendETH(to, chainId) with n ETH + src-weth->>src-liquidity: 2. Deposit n ETH + src-weth->>dst-l2Xl2: 3. Send relayETH to Superchain WETH on chainId + end + rect rgba(0,0,0,0.1) + note over any-offchain,dst-weth: Executing message + any-offchain->>dst-l2Xl2: 4. Relay the message + dst-l2Xl2->>dst-weth: 5. relayETH(from, to, amount) + dst-weth->>dst-liquidity: 6. Withdraw amount ETH + dst-weth->>dst-final: 7. Here are amount ETH + end ``` -_Figure 1: Superchain WETH transfer process between two interoperable L2 chains._ - - - `crosschainBurn` and `crosschainMint`can only be called by the `SuperchainTokenBridge`. - -## Major components +#### Initiating message -### `SuperchainWETH` contract +1. The user (or a contract operating on a user's behalf) calls `SuperchainWETH.sendETH` with a destination address and a chainId. + This call should have an attached amount of ETH. -This contract implements the core functionality for wrapping, unwrapping, and cross-chain transfer of ETH. It integrates with the `SuperchainTokenBridge` for interoperable actions. +2. `SuperchainWETH` sends the amount of ETH to `ETHLiquidity`, removing it from circulation on the source chain. -* Contract address: `0x4200000000000000000000000000000000000024` +3. `SuperchainWETH` on the source chain sends a [`relayETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol#L125-L145) call to the `SuperchainWETH` on the destination chain using [`L2ToL2CrossDomainMessenger`](./message-passing). -### `ETHLiquidity` contract +#### Executing message -A predeploy contract with a large pool of ETH that provides liquidity for cross-chain transfers. It allows "burning" and "minting" of ETH for cross-chain transfers. ETH is associated with bridge ETH from the L1 lockbox, making ETH available to interop chains through a shared lockbox rather than fragmented amongst the existing portal contracts. +4. Some offchain entity submits a transaction with the executing message. + Any address can submit such a transaction, but it has to have ETH on the destination chain to do so. + We expect that in many cases this will be a relayer rather than the user, because the user won't have ETH on the destination chain yet. -* Contract address: `0x4200000000000000000000000000000000000025` +5. `L2ToL2CrossDomainMessenger` on the destination chain calls `SuperchainWETH` with the source of the ETH, the destination address, and the amount. -### `L2ToL2CrossDomainMessenger` contract + `SuperchainWETH` runs several sanity checks: -This predeploy contract facilitates general message passing between different chains in the Superchain. It also securely transfers ERC20 tokens between L2 chains. + - The `relayETH` call has to come directly from `L2ToL2CrossDomainMessenger`. + - The introp message has to have been sent by `SuperchainWETH` -* Contract address: `0x4200000000000000000000000000000000000023` +6. `SuperchainWETH` withdraws the requested amount of ETH from `ETHLiquidity`. + It is the only contract allowed to withdraw from `ETHLiquidity`, which adds to the ETH in circulation on the destination chain. - - `SuperchainWETH` implements strict access controls to ensure security (e.g., only `SuperchainWETH` can call `ETHLiquidity` functions). - +7. `SuperchainWETH` uses [`SafeSend`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/SafeSend.sol) to send the ETH. + This means that even if the destination is a smart contract, its custom logic does not get called, [in contrast to normal ETH transfers](https://docs.base.org/base-learn/docs/address-and-payable/#receiving-ether-with-payable-addresses). ## Next steps -* Explore the [`SuperchainWETH`](https://specs.optimism.io/interop/superchain-weth.html) specs for in-depth implementation details. -* Review the [Superchain Interop Explainer](../explainer) for answers to common questions about interoperability. +* Explore [the `SuperchainWETH` specs](https://specs.optimism.io/interop/superchain-weth.html) for in-depth implementation details. +* Read the [interop message passing](./message-passing) page for more information about how `L2ToL2CrossDomainMessenger` passes messages. From 281e9d52245ae6e2702c86174e0716ca63275832 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Mon, 27 Jan 2025 22:38:20 -0600 Subject: [PATCH 03/17] Update _meta.json --- pages/stack/interop/_meta.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/_meta.json b/pages/stack/interop/_meta.json index 5282de6e2..2a45aa447 100644 --- a/pages/stack/interop/_meta.json +++ b/pages/stack/interop/_meta.json @@ -3,7 +3,7 @@ "predeploy": "Interop predeploys", "message-passing": "Interop message passing", "op-supervisor": "OP Supervisor", - "superchain-weth": "SuperchainWETH (Interoperable ETH)", + "superchain-weth": "SuperchainWETH (Interoperable ETH)", "superchain-erc20": "SuperchainERC20", "security": "Cross-chain security", "tools": "Tools", From 3383714d0c263b3fc8287706bf2c770445d10921 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Mon, 27 Jan 2025 22:55:11 -0600 Subject: [PATCH 04/17] fix --- pages/stack/interop/superchain-weth.mdx | 47 ++++++++++++------------- words.txt | 4 +-- 2 files changed, 24 insertions(+), 27 deletions(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index cc273041c..a7d8833b2 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -12,22 +12,21 @@ import { InteropCallout } from '@/components/WipCallout' # SuperchainWETH -The [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract works with [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol) +The [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract works with [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol) and [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) to enable ETH interoperability within the Superchain. This is accomplished by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. - ## Features and benefits -* Enables seamless ETH transfers across different chains in the Superchain -* Maintains fungibility of ETH across the Superchain -* Provides liquidity for cross-chain transactions -* Improves user experience by abstracting complex bridging processes +* Enables seamless ETH transfers across different chains in the Superchain +* Maintains fungibility of ETH across the Superchain +* Provides liquidity for cross-chain transactions +* Improves user experience by abstracting complex bridging processes ## How it works -```mermaid +```mermaid %%{ init: { @@ -67,33 +66,33 @@ sequenceDiagram #### Initiating message -1. The user (or a contract operating on a user's behalf) calls `SuperchainWETH.sendETH` with a destination address and a chainId. - This call should have an attached amount of ETH. +1. The user (or a contract operating on a user's behalf) calls `SuperchainWETH.sendETH` with a destination address and a chainId. + This call should have an attached amount of ETH. -2. `SuperchainWETH` sends the amount of ETH to `ETHLiquidity`, removing it from circulation on the source chain. +2. `SuperchainWETH` sends the amount of ETH to `ETHLiquidity`, removing it from circulation on the source chain. -3. `SuperchainWETH` on the source chain sends a [`relayETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol#L125-L145) call to the `SuperchainWETH` on the destination chain using [`L2ToL2CrossDomainMessenger`](./message-passing). +3. `SuperchainWETH` on the source chain sends a [`relayETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol#L125-L145) call to the `SuperchainWETH` on the destination chain using [`L2ToL2CrossDomainMessenger`](./message-passing). #### Executing message -4. Some offchain entity submits a transaction with the executing message. - Any address can submit such a transaction, but it has to have ETH on the destination chain to do so. - We expect that in many cases this will be a relayer rather than the user, because the user won't have ETH on the destination chain yet. +4. Some offchain entity submits a transaction with the executing message. + Any address can submit such a transaction, but it has to have ETH on the destination chain to do so. + We expect that in many cases this will be a relayer rather than the user, because the user won't have ETH on the destination chain yet. -5. `L2ToL2CrossDomainMessenger` on the destination chain calls `SuperchainWETH` with the source of the ETH, the destination address, and the amount. +5. `L2ToL2CrossDomainMessenger` on the destination chain calls `SuperchainWETH` with the source of the ETH, the destination address, and the amount. - `SuperchainWETH` runs several sanity checks: + `SuperchainWETH` runs several sanity checks: - - The `relayETH` call has to come directly from `L2ToL2CrossDomainMessenger`. - - The introp message has to have been sent by `SuperchainWETH` + * The `relayETH` call has to come directly from `L2ToL2CrossDomainMessenger`. + * The introp message has to have been sent by `SuperchainWETH` -6. `SuperchainWETH` withdraws the requested amount of ETH from `ETHLiquidity`. - It is the only contract allowed to withdraw from `ETHLiquidity`, which adds to the ETH in circulation on the destination chain. +6. `SuperchainWETH` withdraws the requested amount of ETH from `ETHLiquidity`. + It is the only contract allowed to withdraw from `ETHLiquidity`, which adds to the ETH in circulation on the destination chain. -7. `SuperchainWETH` uses [`SafeSend`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/SafeSend.sol) to send the ETH. - This means that even if the destination is a smart contract, its custom logic does not get called, [in contrast to normal ETH transfers](https://docs.base.org/base-learn/docs/address-and-payable/#receiving-ether-with-payable-addresses). +7. `SuperchainWETH` uses [`SafeSend`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/SafeSend.sol) to send the ETH. + This means that even if the destination is a smart contract, its custom logic does not get called, [in contrast to normal ETH transfers](https://docs.base.org/base-learn/docs/address-and-payable/#receiving-ether-with-payable-addresses). ## Next steps -* Explore [the `SuperchainWETH` specs](https://specs.optimism.io/interop/superchain-weth.html) for in-depth implementation details. -* Read the [interop message passing](./message-passing) page for more information about how `L2ToL2CrossDomainMessenger` passes messages. +* Explore [the `SuperchainWETH` specs](https://specs.optimism.io/interop/superchain-weth.html) for in-depth implementation details. +* Read the [interop message passing](./message-passing) page for more information about how `L2ToL2CrossDomainMessenger` passes messages. diff --git a/words.txt b/words.txt index d17d59bbc..49e052095 100644 --- a/words.txt +++ b/words.txt @@ -166,6 +166,7 @@ Inator inator INFLUXDBV influxdbv +introp IPCDISABLE ipcdisable ipcfile @@ -281,7 +282,6 @@ pprof Precommitments precommitments preconfigured -Preconfigured predeploy Predeployed predeployed @@ -314,7 +314,6 @@ QRNG Quicknode quicknode quickstarts -rebalance Regenesis regenesis REJOURNAL @@ -377,7 +376,6 @@ Superchain superchain Superchain's Superchainerc -superchainerc Superchains Superscan Supersim From 88867c08d49435b4658c47b556a4102ef8f33f98 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Tue, 28 Jan 2025 12:49:28 -0600 Subject: [PATCH 05/17] Renamed to Interoperable ETH --- pages/stack/interop/_meta.json | 2 +- pages/stack/interop/superchain-weth.mdx | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/pages/stack/interop/_meta.json b/pages/stack/interop/_meta.json index 2a45aa447..7e9c7649a 100644 --- a/pages/stack/interop/_meta.json +++ b/pages/stack/interop/_meta.json @@ -3,7 +3,7 @@ "predeploy": "Interop predeploys", "message-passing": "Interop message passing", "op-supervisor": "OP Supervisor", - "superchain-weth": "SuperchainWETH (Interoperable ETH)", + "superchain-weth": "Interoperable ETH", "superchain-erc20": "SuperchainERC20", "security": "Cross-chain security", "tools": "Tools", diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index a7d8833b2..540524057 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -1,7 +1,7 @@ --- -title: SuperchainWETH (Interoperable ETH) +title: Interoperable ETH lang: en-US -description: Learn basic details about SuperchainWETH or Interoperable ETH. +description: Learn basic details about Interoperable ETH. --- import { Callout } from 'nextra/components' @@ -10,11 +10,10 @@ import { InteropCallout } from '@/components/WipCallout' -# SuperchainWETH +# Interoperable ETH -The [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract works with [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol) -and [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) to enable ETH interoperability within the Superchain. -This is accomplished by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. +InteroperableETH is implemented using the [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract, along with[`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), and [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) to enable ETH interoperability within the Superchain. +IteroperableETH works by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. ## Features and benefits From dcbaa665a52b75ed5d58af2242869ac7c4d0d0a4 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Tue, 28 Jan 2025 13:14:14 -0600 Subject: [PATCH 06/17] Update words.txt Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- words.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/words.txt b/words.txt index 49e052095..d49a9461f 100644 --- a/words.txt +++ b/words.txt @@ -166,7 +166,7 @@ Inator inator INFLUXDBV influxdbv -introp +interop IPCDISABLE ipcdisable ipcfile From 1d16205f7ffca72e74b3157f3a245abf52ff6bc8 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Tue, 28 Jan 2025 13:14:42 -0600 Subject: [PATCH 07/17] Update pages/stack/interop/superchain-weth.mdx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- pages/stack/interop/superchain-weth.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index 540524057..cf7551394 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -12,8 +12,8 @@ import { InteropCallout } from '@/components/WipCallout' # Interoperable ETH -InteroperableETH is implemented using the [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract, along with[`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), and [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) to enable ETH interoperability within the Superchain. -IteroperableETH works by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. +InteroperableETH is implemented using the [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract, along with [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), and [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) to enable ETH interoperability within the Superchain. +InteroperableETH works by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. ## Features and benefits From fe08265dd8b6e32f85c901a0ef6651b7b7519ba3 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Tue, 28 Jan 2025 15:16:55 -0600 Subject: [PATCH 08/17] Explain L1 lockbox --- pages/stack/interop/superchain-weth.mdx | 45 ++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index cf7551394..0bb42b97a 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -12,7 +12,13 @@ import { InteropCallout } from '@/components/WipCallout' # Interoperable ETH -InteroperableETH is implemented using the [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol) contract, along with [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), and [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) to enable ETH interoperability within the Superchain. +InteroperableETH is implemented using three contacts: + +- [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/contracts-bedrock/src/L2/SuperchainWETH.sol) is the bridge that lets you move ETH from one Superchain blockchain to another. +- [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol) holds a practically infinite amount of ETH (it starts with 2248 WEI). + It is used by `SuperchainWETH` as a liquidity repository to be able to provide ETH on the destination chain. +- [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) is used to [pass messages between different chains](./message-passing). + InteroperableETH works by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. @@ -91,6 +97,43 @@ sequenceDiagram 7. `SuperchainWETH` uses [`SafeSend`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/SafeSend.sol) to send the ETH. This means that even if the destination is a smart contract, its custom logic does not get called, [in contrast to normal ETH transfers](https://docs.base.org/base-learn/docs/address-and-payable/#receiving-ether-with-payable-addresses). + +## L1 Treasury + +All the ETH in circulation on the Superchain (all the ETH except for what is held by `ETHLiquidity`) needs to be backed by real ETH held on L1. +This is done by the . + +Here is an example of how this works. + +| Step | User on L1 | Lockbox | User on chain A | ETHLiquidity on chain A | User on chain B | ETHLiquidity on chain B | +| -: | -: | -: | -:| -: | -: | -: | +| 1 | 7 | 200 | 0 | 100000 | 0 | 100000 +| 2 | 4 | 203 | 3 | 100000 | 0 | 100000 +| 3 | 4 | 203 | 2 | 100001 | 0 | 100000 +| 4 | 4 | 203 | 2 | 100001 | 1 | 99999 +| 5 | 4 | 203 | 2 | 100001 | 0 | 99999 +| 6 | 5 | 202 | 2 | 100001 | 0 | 99999 + +1. The initial state. The user has 7 ETH on L1, and nothing on chains A and B. + +2. The user bridges 3 ETH to chain A. + The user sends 3 ETH on L1 to the bridge, which is locked in the lockbox. + The bridge on chain A then mints 3 ETH for the user. + +3. The user sent the initiating message to `SuperchainWETH` on chain A, along with 1 ETH to bridge to chain B. + This 1 ETH is sent to `ETHLiquidity` on chain A. + +4. Somebody (the user, a relayer action on behalf of the user, etc.) sent the corresponding executing message to chain B. + `SuperchainWETH` transfers 1 ETH from `ETHLiquidity` on chain B to the user. + +5. The user decides to withdraw 1 ETH from chain B back into L1. + Normally a user would do this through a third party bridge, which is faster and usually cheaper, but for illustration purposes this user uses the standard OP bridge. + The user starts with an initiating message on chain B, which burns 1 ETH and sends a message to L1. + +6. After the week long [challenge period](/connect/resources/glossary#challenge-period), the user finalizes the withdrawal on L1. + The lock box releases 1 ETH, which is then sent to the user. + + ## Next steps * Explore [the `SuperchainWETH` specs](https://specs.optimism.io/interop/superchain-weth.html) for in-depth implementation details. From 275eb3eeef5c801c509c4fc19c42f1bbb9641314 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Tue, 28 Jan 2025 15:36:30 -0600 Subject: [PATCH 09/17] Update superchain-weth.mdx --- pages/stack/interop/superchain-weth.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index 0bb42b97a..d1127399b 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -12,7 +12,7 @@ import { InteropCallout } from '@/components/WipCallout' # Interoperable ETH -InteroperableETH is implemented using three contacts: +InteroperableETH is implemented using three contracts: - [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/contracts-bedrock/src/L2/SuperchainWETH.sol) is the bridge that lets you move ETH from one Superchain blockchain to another. - [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol) holds a practically infinite amount of ETH (it starts with 2248 WEI). @@ -89,7 +89,7 @@ sequenceDiagram `SuperchainWETH` runs several sanity checks: * The `relayETH` call has to come directly from `L2ToL2CrossDomainMessenger`. - * The introp message has to have been sent by `SuperchainWETH` + * The interop message has to have been sent by `SuperchainWETH` 6. `SuperchainWETH` withdraws the requested amount of ETH from `ETHLiquidity`. It is the only contract allowed to withdraw from `ETHLiquidity`, which adds to the ETH in circulation on the destination chain. @@ -101,7 +101,8 @@ sequenceDiagram ## L1 Treasury All the ETH in circulation on the Superchain (all the ETH except for what is held by `ETHLiquidity`) needs to be backed by real ETH held on L1. -This is done by the . +This is done using a lockbox contract on L1 that holds all the ETH ever bridged to Superchain chains and not yet withdrawn. +New ETH can only be minted on L2 when it is locked on L1, and it is burned on L2 before it can be released from the lockbox. Here is an example of how this works. From a10b0531cd2c7b589546f69da718d42c4510bb25 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Tue, 28 Jan 2025 21:06:46 -0600 Subject: [PATCH 10/17] More @zainbacchus input --- pages/stack/interop/superchain-weth.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index d1127399b..51072a10d 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -15,8 +15,8 @@ import { InteropCallout } from '@/components/WipCallout' InteroperableETH is implemented using three contracts: - [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/contracts-bedrock/src/L2/SuperchainWETH.sol) is the bridge that lets you move ETH from one Superchain blockchain to another. -- [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol) holds a practically infinite amount of ETH (it starts with 2248 WEI). - It is used by `SuperchainWETH` as a liquidity repository to be able to provide ETH on the destination chain. +- [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), which holds a large amount of ETH used to provide liquidity. + It is used by `SuperchainWETH` as a liquidity repository to be able to provide ETH on the destination chain when transfering. - [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) is used to [pass messages between different chains](./message-passing). InteroperableETH works by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. @@ -100,8 +100,8 @@ sequenceDiagram ## L1 Treasury -All the ETH in circulation on the Superchain (all the ETH except for what is held by `ETHLiquidity`) needs to be backed by real ETH held on L1. -This is done using a lockbox contract on L1 that holds all the ETH ever bridged to Superchain chains and not yet withdrawn. +All the ETH in circulation on the Superchain (all the ETH except for what is held by `ETHLiquidity`) needs to be backed by ETH held on L1. +This is done using a lockbox contract on L1 that holds all the ETH ever bridged to [chains in the Superchain interop cluster](explainer#superchain-interop-cluster) and not yet withdrawn. New ETH can only be minted on L2 when it is locked on L1, and it is burned on L2 before it can be released from the lockbox. Here is an example of how this works. From e08eaeffc2837cbb1224be38aa98ebb2e54a9887 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Tue, 28 Jan 2025 21:19:19 -0600 Subject: [PATCH 11/17] coderabbit suggestions --- pages/stack/interop/superchain-weth.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index 51072a10d..6a5bde767 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -15,8 +15,8 @@ import { InteropCallout } from '@/components/WipCallout' InteroperableETH is implemented using three contracts: - [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/contracts-bedrock/src/L2/SuperchainWETH.sol) is the bridge that lets you move ETH from one Superchain blockchain to another. -- [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), which holds a large amount of ETH used to provide liquidity. - It is used by `SuperchainWETH` as a liquidity repository to be able to provide ETH on the destination chain when transfering. +- [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), which serves as a liquidity provider for ETH transfers. + It is used by `SuperchainWETH` as a liquidity repository to be able to provide ETH on the destination chain when transferring. - [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) is used to [pass messages between different chains](./message-passing). InteroperableETH works by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. @@ -82,7 +82,7 @@ sequenceDiagram 4. Some offchain entity submits a transaction with the executing message. Any address can submit such a transaction, but it has to have ETH on the destination chain to do so. - We expect that in many cases this will be a relayer rather than the user, because the user won't have ETH on the destination chain yet. + We expect that usually this will be a relayer rather than the user because the user won't have ETH on the destination chain yet. 5. `L2ToL2CrossDomainMessenger` on the destination chain calls `SuperchainWETH` with the source of the ETH, the destination address, and the amount. @@ -100,7 +100,7 @@ sequenceDiagram ## L1 Treasury -All the ETH in circulation on the Superchain (all the ETH except for what is held by `ETHLiquidity`) needs to be backed by ETH held on L1. +Every ETH in circulation on the Superchain (all the ETH except for those held by `ETHLiquidity`) needs to be backed by ETH held on L1. This is done using a lockbox contract on L1 that holds all the ETH ever bridged to [chains in the Superchain interop cluster](explainer#superchain-interop-cluster) and not yet withdrawn. New ETH can only be minted on L2 when it is locked on L1, and it is burned on L2 before it can be released from the lockbox. @@ -128,7 +128,7 @@ Here is an example of how this works. `SuperchainWETH` transfers 1 ETH from `ETHLiquidity` on chain B to the user. 5. The user decides to withdraw 1 ETH from chain B back into L1. - Normally a user would do this through a third party bridge, which is faster and usually cheaper, but for illustration purposes this user uses the standard OP bridge. + Normally, a user would do this through a third-party bridge, which is faster and usually cheaper, but for illustration purposes this user uses the standard OP bridge. The user starts with an initiating message on chain B, which burns 1 ETH and sends a message to L1. 6. After the week long [challenge period](/connect/resources/glossary#challenge-period), the user finalizes the withdrawal on L1. From a267c49250d4c027ec40de8ad76b56b6b15bdb58 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Tue, 28 Jan 2025 21:19:48 -0600 Subject: [PATCH 12/17] pnpm fix --- pages/stack/interop/superchain-weth.mdx | 50 ++++++++++++------------- words.txt | 1 - 2 files changed, 24 insertions(+), 27 deletions(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index 6a5bde767..aa71875b1 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -14,10 +14,10 @@ import { InteropCallout } from '@/components/WipCallout' InteroperableETH is implemented using three contracts: -- [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/contracts-bedrock/src/L2/SuperchainWETH.sol) is the bridge that lets you move ETH from one Superchain blockchain to another. -- [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), which serves as a liquidity provider for ETH transfers. - It is used by `SuperchainWETH` as a liquidity repository to be able to provide ETH on the destination chain when transferring. -- [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) is used to [pass messages between different chains](./message-passing). +* [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/contracts-bedrock/src/L2/SuperchainWETH.sol) is the bridge that lets you move ETH from one Superchain blockchain to another. +* [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), which serves as a liquidity provider for ETH transfers. + It is used by `SuperchainWETH` as a liquidity repository to be able to provide ETH on the destination chain when transferring. +* [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) is used to [pass messages between different chains](./message-passing). InteroperableETH works by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. @@ -97,7 +97,6 @@ sequenceDiagram 7. `SuperchainWETH` uses [`SafeSend`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/SafeSend.sol) to send the ETH. This means that even if the destination is a smart contract, its custom logic does not get called, [in contrast to normal ETH transfers](https://docs.base.org/base-learn/docs/address-and-payable/#receiving-ether-with-payable-addresses). - ## L1 Treasury Every ETH in circulation on the Superchain (all the ETH except for those held by `ETHLiquidity`) needs to be backed by ETH held on L1. @@ -107,33 +106,32 @@ New ETH can only be minted on L2 when it is locked on L1, and it is burned on L2 Here is an example of how this works. | Step | User on L1 | Lockbox | User on chain A | ETHLiquidity on chain A | User on chain B | ETHLiquidity on chain B | -| -: | -: | -: | -:| -: | -: | -: | -| 1 | 7 | 200 | 0 | 100000 | 0 | 100000 -| 2 | 4 | 203 | 3 | 100000 | 0 | 100000 -| 3 | 4 | 203 | 2 | 100001 | 0 | 100000 -| 4 | 4 | 203 | 2 | 100001 | 1 | 99999 -| 5 | 4 | 203 | 2 | 100001 | 0 | 99999 -| 6 | 5 | 202 | 2 | 100001 | 0 | 99999 - -1. The initial state. The user has 7 ETH on L1, and nothing on chains A and B. +| ---: | ---------: | ------: | --------------: | ----------------------: | --------------: | ----------------------: | +| 1 | 7 | 200 | 0 | 100000 | 0 | 100000 | +| 2 | 4 | 203 | 3 | 100000 | 0 | 100000 | +| 3 | 4 | 203 | 2 | 100001 | 0 | 100000 | +| 4 | 4 | 203 | 2 | 100001 | 1 | 99999 | +| 5 | 4 | 203 | 2 | 100001 | 0 | 99999 | +| 6 | 5 | 202 | 2 | 100001 | 0 | 99999 | -2. The user bridges 3 ETH to chain A. - The user sends 3 ETH on L1 to the bridge, which is locked in the lockbox. - The bridge on chain A then mints 3 ETH for the user. +1. The initial state. The user has 7 ETH on L1, and nothing on chains A and B. -3. The user sent the initiating message to `SuperchainWETH` on chain A, along with 1 ETH to bridge to chain B. - This 1 ETH is sent to `ETHLiquidity` on chain A. +2. The user bridges 3 ETH to chain A. + The user sends 3 ETH on L1 to the bridge, which is locked in the lockbox. + The bridge on chain A then mints 3 ETH for the user. -4. Somebody (the user, a relayer action on behalf of the user, etc.) sent the corresponding executing message to chain B. - `SuperchainWETH` transfers 1 ETH from `ETHLiquidity` on chain B to the user. +3. The user sent the initiating message to `SuperchainWETH` on chain A, along with 1 ETH to bridge to chain B. + This 1 ETH is sent to `ETHLiquidity` on chain A. -5. The user decides to withdraw 1 ETH from chain B back into L1. - Normally, a user would do this through a third-party bridge, which is faster and usually cheaper, but for illustration purposes this user uses the standard OP bridge. - The user starts with an initiating message on chain B, which burns 1 ETH and sends a message to L1. +4. Somebody (the user, a relayer action on behalf of the user, etc.) sent the corresponding executing message to chain B. + `SuperchainWETH` transfers 1 ETH from `ETHLiquidity` on chain B to the user. -6. After the week long [challenge period](/connect/resources/glossary#challenge-period), the user finalizes the withdrawal on L1. - The lock box releases 1 ETH, which is then sent to the user. +5. The user decides to withdraw 1 ETH from chain B back into L1. + Normally, a user would do this through a third-party bridge, which is faster and usually cheaper, but for illustration purposes this user uses the standard OP bridge. + The user starts with an initiating message on chain B, which burns 1 ETH and sends a message to L1. +6. After the week long [challenge period](/connect/resources/glossary#challenge-period), the user finalizes the withdrawal on L1. + The lock box releases 1 ETH, which is then sent to the user. ## Next steps diff --git a/words.txt b/words.txt index d49a9461f..5d13f78ef 100644 --- a/words.txt +++ b/words.txt @@ -166,7 +166,6 @@ Inator inator INFLUXDBV influxdbv -interop IPCDISABLE ipcdisable ipcfile From 83e9c15830c638f55b0650150b31ffe033bc61f2 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Wed, 29 Jan 2025 10:37:50 -0600 Subject: [PATCH 13/17] Apply suggestions from code review Co-authored-by: Blessing Krofegha --- pages/stack/interop/superchain-weth.mdx | 50 ++++++++++++++----------- 1 file changed, 28 insertions(+), 22 deletions(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index aa71875b1..64f0f8161 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -12,15 +12,15 @@ import { InteropCallout } from '@/components/WipCallout' # Interoperable ETH -InteroperableETH is implemented using three contracts: +InteroperableETH enables seamless ETH transfers across Superchain blockchains. It is implemented using three key contracts: -* [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/contracts-bedrock/src/L2/SuperchainWETH.sol) is the bridge that lets you move ETH from one Superchain blockchain to another. -* [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol), which serves as a liquidity provider for ETH transfers. - It is used by `SuperchainWETH` as a liquidity repository to be able to provide ETH on the destination chain when transferring. -* [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) is used to [pass messages between different chains](./message-passing). +* [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/contracts-bedrock/src/L2/SuperchainWETH.sol): A bridge contract that facilitates ETH transfers between Superchain blockchains. +* [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol): A liquidity provider for ETH transfers. +`SuperchainWETH` uses this contract as a liquidity repository to ensure ETH availability on the destination chain. +* [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol): A messaging contract that [facilitates cross-chain communication](/message-passing). -InteroperableETH works by depositing ETH on the source chain's `ETHLiquidity` and withdrawing an equivalent amount on the destination chain. -This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. +InteroperableETH deposits ETH into the `ETHLiquidity` contract on the source chain and withdraws an equivalent amount on the destination chain. +This mechanism improves capital efficiency and eliminates liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. ## Features and benefits @@ -74,33 +74,39 @@ sequenceDiagram 1. The user (or a contract operating on a user's behalf) calls `SuperchainWETH.sendETH` with a destination address and a chainId. This call should have an attached amount of ETH. -2. `SuperchainWETH` sends the amount of ETH to `ETHLiquidity`, removing it from circulation on the source chain. +2. `SuperchainWETH` transfers the specified ETH amount to `ETHLiquidity`, removing it from circulation on the source chain. -3. `SuperchainWETH` on the source chain sends a [`relayETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol#L125-L145) call to the `SuperchainWETH` on the destination chain using [`L2ToL2CrossDomainMessenger`](./message-passing). +3. `SuperchainWETH` on the source chain sends a [`relayETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol#L125-L145) message to `SuperchainWETH` on the destination chain using the [`L2ToL2CrossDomainMessenger`](/message-passing). #### Executing message -4. Some offchain entity submits a transaction with the executing message. - Any address can submit such a transaction, but it has to have ETH on the destination chain to do so. - We expect that usually this will be a relayer rather than the user because the user won't have ETH on the destination chain yet. +4. An off-chain entity submits a transaction to execute the message. + Any address can submit this transaction, but it must have ETH on the destination chain. + Typically, a relayer submits the transaction, since the user does not yet have ETH on the destination chain. -5. `L2ToL2CrossDomainMessenger` on the destination chain calls `SuperchainWETH` with the source of the ETH, the destination address, and the amount. +5. `L2ToL2CrossDomainMessenger` on the destination chain calls `SuperchainWETH` with the following details: - `SuperchainWETH` runs several sanity checks: +* Source of the ETH +* Destination address +* Amount of ETH - * The `relayETH` call has to come directly from `L2ToL2CrossDomainMessenger`. - * The interop message has to have been sent by `SuperchainWETH` + `SuperchainWETH` performs several sanity checks: -6. `SuperchainWETH` withdraws the requested amount of ETH from `ETHLiquidity`. - It is the only contract allowed to withdraw from `ETHLiquidity`, which adds to the ETH in circulation on the destination chain. + * The `relayETH` call must originate from `L2ToL2CrossDomainMessenger`. + * The interop message must have been sent by `SuperchainWETH` -7. `SuperchainWETH` uses [`SafeSend`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/SafeSend.sol) to send the ETH. - This means that even if the destination is a smart contract, its custom logic does not get called, [in contrast to normal ETH transfers](https://docs.base.org/base-learn/docs/address-and-payable/#receiving-ether-with-payable-addresses). +6. `SuperchainWETH` withdraws the specified amount of ETH from `ETHLiquidity`. + Only `SuperchainWETH` can withdraw from `ETHLiquidity`, ensuring that the ETH is correctly reintroduced into circulation on the destination chain. + +7. `SuperchainWETH` uses [`SafeSend`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/SafeSend.sol) to send ETH. + This ensures that even if the destination is a smart contract, its custom logic is not executed. +This behavior differs from [standard ETH transfers](https://docs.base.org/base-learn/docs/address-and-payable/#receiving-ether-with-payable-addresses), where smart contracts can trigger custom logic upon receiving ETH. ## L1 Treasury -Every ETH in circulation on the Superchain (all the ETH except for those held by `ETHLiquidity`) needs to be backed by ETH held on L1. -This is done using a lockbox contract on L1 that holds all the ETH ever bridged to [chains in the Superchain interop cluster](explainer#superchain-interop-cluster) and not yet withdrawn. +Every ETH in circulation on the Superchain—excluding ETH held by `ETHLiquidity`—must be backed by ETH on L1. + +This is enforced by a lockbox contract on L1, which holds all ETH bridged to [Superchain interop cluster chains](https://github.com/ethereum-optimism/docs/pull/1297/explainer#superchain-interop-cluster) that has not yet been withdrawn. New ETH can only be minted on L2 when it is locked on L1, and it is burned on L2 before it can be released from the lockbox. Here is an example of how this works. From 28994873a0620576234813b8a7479e0fccceffea Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Wed, 29 Jan 2025 10:49:23 -0600 Subject: [PATCH 14/17] Based on @krofax 's comments --- pages/stack/interop/superchain-weth.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index 64f0f8161..14517e949 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -72,7 +72,7 @@ sequenceDiagram #### Initiating message 1. The user (or a contract operating on a user's behalf) calls `SuperchainWETH.sendETH` with a destination address and a chainId. - This call should have an attached amount of ETH. + ETH, in the amount to transfer must be attached to this call. 2. `SuperchainWETH` transfers the specified ETH amount to `ETHLiquidity`, removing it from circulation on the source chain. From 58773ee42e79a2bfb3b0fbf945d3416db006e66d Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Wed, 29 Jan 2025 17:56:10 +0100 Subject: [PATCH 15/17] Update pages/stack/interop/superchain-weth.mdx --- pages/stack/interop/superchain-weth.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index 14517e949..4439352e4 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -106,7 +106,7 @@ This behavior differs from [standard ETH transfers](https://docs.base.org/base-l Every ETH in circulation on the Superchain—excluding ETH held by `ETHLiquidity`—must be backed by ETH on L1. -This is enforced by a lockbox contract on L1, which holds all ETH bridged to [Superchain interop cluster chains](https://github.com/ethereum-optimism/docs/pull/1297/explainer#superchain-interop-cluster) that has not yet been withdrawn. +This is enforced by a lockbox contract on L1, which holds all ETH bridged to [Superchain interop cluster chains](/explainer#superchain-interop-cluster) that has not yet been withdrawn. New ETH can only be minted on L2 when it is locked on L1, and it is burned on L2 before it can be released from the lockbox. Here is an example of how this works. From d28d0cf9a8e7ff5f7973bab70a40ff503f18f4f0 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Wed, 29 Jan 2025 17:57:03 +0100 Subject: [PATCH 16/17] Update pages/stack/interop/superchain-weth.mdx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- pages/stack/interop/superchain-weth.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index 4439352e4..643901526 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -14,7 +14,7 @@ import { InteropCallout } from '@/components/WipCallout' InteroperableETH enables seamless ETH transfers across Superchain blockchains. It is implemented using three key contracts: -* [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/contracts-bedrock/src/L2/SuperchainWETH.sol): A bridge contract that facilitates ETH transfers between Superchain blockchains. +* [`SuperchainWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol): A bridge contract that facilitates ETH transfers between Superchain blockchains. * [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol): A liquidity provider for ETH transfers. `SuperchainWETH` uses this contract as a liquidity repository to ensure ETH availability on the destination chain. * [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol): A messaging contract that [facilitates cross-chain communication](/message-passing). From 2d6501cb880536e54149d2633f03815fbbfd8090 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Wed, 29 Jan 2025 18:03:12 +0100 Subject: [PATCH 17/17] Update pages/stack/interop/superchain-weth.mdx --- pages/stack/interop/superchain-weth.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/superchain-weth.mdx b/pages/stack/interop/superchain-weth.mdx index 643901526..f255a2c26 100644 --- a/pages/stack/interop/superchain-weth.mdx +++ b/pages/stack/interop/superchain-weth.mdx @@ -142,4 +142,4 @@ Here is an example of how this works. ## Next steps * Explore [the `SuperchainWETH` specs](https://specs.optimism.io/interop/superchain-weth.html) for in-depth implementation details. -* Read the [interop message passing](./message-passing) page for more information about how `L2ToL2CrossDomainMessenger` passes messages. +* Read the [interop message passing](/message-passing) page for more information about how `L2ToL2CrossDomainMessenger` passes messages.