|
| 1 | +# SuperchainWETH: Failure Modes and Recovery Path Analysis |
| 2 | + |
| 3 | +| Author | Joxes, Gotzen, Parti | |
| 4 | +| --- | --- | |
| 5 | +| Created at | 2025-01-10 | |
| 6 | +| Initial Reviewers | Kelvin Fichter, Michael Amadi | |
| 7 | +| Needs Approval From | Kelvin Fichter | |
| 8 | +| Status | Implementing Actions | |
| 9 | + |
| 10 | +## Introduction |
| 11 | + |
| 12 | +This document covers the addition of SuperchainWETH, an interop-enabled version of the WETH contract that allows ETH to be moved across a set of interoperable chains. It act as a wrapper contract compliant with the SuperchainERC20 standard and also have built-in bridging logic. The following components are included: |
| 13 | + |
| 14 | +- **Contracts**: |
| 15 | + - Introducing the `SuperchainWETH` predeploy proxy and implementation contract. It enables wrapping ETH into SuperchainWETH and includes logic for direct ETH interop transfers. |
| 16 | + - Introducing the `ETHLiquidity` predeploy proxy and implementation contract. It is designed to facilitate the conversion of SuperchainWETH into native ETH—triggered when the supply increases through `crosschainMint` via `relayERC20`—by maintaining a large reserve of native ETH. |
| 17 | + |
| 18 | +Below are references for this project: |
| 19 | + |
| 20 | +- Design doc: |
| 21 | + - Introduction of SuperchainWETH: https://github.com/ethereum-optimism/design-docs/blob/main/protocol/interoperable-ether.md |
| 22 | + - Handling SuperchainWETH transfers: https://github.com/ethereum-optimism/design-docs/blob/main/protocol/interoperable-ether-transfers.md |
| 23 | +- Specs: https://github.com/ethereum-optimism/specs/blob/main/specs/interop/superchain-weth.md |
| 24 | +- Implementation: |
| 25 | + - `SuperchainWETH`: https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainWETH.sol |
| 26 | + - `ETHLiquidity`: https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol |
| 27 | + |
| 28 | + |
| 29 | +>🗂️ **For more context about the Interop project, refer to the following docs:** |
| 30 | +> 1. [Interop System Diagram](https://www.notion.so/16c8052fcbb24b93ad1a539b5f8db4c1?pvs=21) |
| 31 | +> 2. [Interop PID](https://www.notion.so/16c8052fcbb24b93ad1a539b5f8db4c1?pvs=21) |
| 32 | +> 3. [Interop Audit Request](https://docs.google.com/document/d/1Rcuzbsguh7koT2jFru5ft9T8zAvjBEzbt0zF5LNQQ08/edit?tab=t.0) |
| 33 | +
|
| 34 | + |
| 35 | + |
| 36 | +## Failure Modes and Recovery Paths |
| 37 | + |
| 38 | +### FM1: Insufficient ETH in `ETHLiquidity` |
| 39 | + |
| 40 | +- **Description:** If `ETHLiquidity` lacks sufficient ETH, mint calls will revert when the contract attempts to forward funds using `SafeSend`. This breaks bridging flows dependent on `relayETH` and `crosschainMint`. |
| 41 | +- **Risk Assessment:** Medium. |
| 42 | + - Potential Impact: High. Not having enough ETH balance in `ETHLiquidity` prevents relaying ETH or mint SuperchainWETH through `crosschainMint`, which would greatly degrade the user experience, as they would be temporarily stuck. The situation becomes even more serious if the affected cross-chain messages expire before the issue can be resolved, making it impossible to retry the relay and get the funds in destination chain. |
| 43 | + - Likelihood: Very low. `ETHLiquidity` starts with a maximum balance (`type(uint248).max`). |
| 44 | +- **Mitigations:** Our current codebase includes tests to check if the `mint` request exceeds the contract’s balance ([test](https://github.com/ethereum-optimism/optimism/blob/dd37e6192c37ed4c5b18df0269f065f378c495cc/packages/contracts-bedrock/test/L2/ETHLiquidity.t.sol#L103)). Initial ETH supply in `ETHLiquidity` is `type(uint248).max` ([test](https://github.com/ethereum-optimism/optimism/blob/dd37e6192c37ed4c5b18df0269f065f378c495cc/packages/contracts-bedrock/test/L2/ETHLiquidity.t.sol#L29)) and equally set in all chains. |
| 45 | +- **Detection:** Perform checks on the `ETHLiquidity` balance as a preventive monitoring measure. User-filed support tickets may flag this issue in case of failure. |
| 46 | +- **Recovery Path(s):** Coordinate an L2 hard fork to replenish the `ETHLiquidity` contract. Investigate the causes of the depletion to determine if other factors are involved. Messages will need to be retried for relaying; otherwise, use the `expireMessage` feature if it is available and integrated into `SuperchainWETH`. |
| 47 | + |
| 48 | +### FM2: Overflow during `burn` in `ETHLiquidity` due to max Balance |
| 49 | + |
| 50 | +- **Description:** If the `ETHLiquidity` contract has already reached the maximum allowed ETH balance (`type(uint256).max`), invoking the `sendETH` function (which triggers `crosschainBurn`) could cause an overflow. This occurs when `burn` is called with an amount that, when added to the current balance, exceeds the maximum `uint256` value. Such an overflow would cause a revert, since the proper Solidity version is used. |
| 51 | +- **Risk Assessment:** Low. |
| 52 | + - Potential Impact: Medium. Reverts during `sendETH` calls are expected when the requested amount exceeds the maximum value representable by a `uint256`. |
| 53 | + - Likelihood: Very low. `ETHLiquidity` starts with a maximum balance (`type(uint248).max`) which is still far from `uint256` limit. |
| 54 | +- **Mitigations:** Initial ETH supply in `ETHLiquidity` is `type(uint248).max` properly is checked ([test](https://github.com/ethereum-optimism/optimism/blob/dd37e6192c37ed4c5b18df0269f065f378c495cc/packages/contracts-bedrock/test/L2/ETHLiquidity.t.sol#L29)). |
| 55 | +- **Detection:** Perform checks on the `ETHLiquidity` balance as a preventive monitoring measure. User-filed support tickets may flag this issue in case of failure. |
| 56 | +- **Recovery Path(s):** Coordinate an L2 hard fork to adjust the `ETHLiquidity` contract’s state. Investigate the causes of this failure to determine if other factors are involved. |
| 57 | + |
| 58 | +### Generic items we need to take into account: |
| 59 | + |
| 60 | +See [fma-generic-contracts.md](https://github.com/ethereum-optimism/design-docs/blob/main/security/fma-generic-contracts.md). |
| 61 | + |
| 62 | +- [x] Check this box to confirm that these items have been considered and updated if necessary. |
| 63 | + |
| 64 | +See [relevant FMAs to SuperchainWETH, To Do] |
| 65 | + |
| 66 | +- [ ] Check this box to confirm that these items have been considered and updated if necessary. |
| 67 | + |
| 68 | +## Action Items |
| 69 | + |
| 70 | +- [x] Resolve all the comments. |
| 71 | +- [ ] FM1, FM2: Establish a balance monitoring measure in `ETHLiquidity` (optional). |
| 72 | +- [ ] Ensure the support team is aware of these failure modes and prepared to respond. |
| 73 | +- [ ] **Ensure that the actions items specified in each FMAs on which SuperchainWETH depends are completed.** |
| 74 | + |
| 75 | +## Audit Requirements |
| 76 | + |
| 77 | +Following the [Audit Framework](https://gov.optimism.io/t/op-labs-audit-framework-when-to-get-external-security-review-and-how-to-prepare-for-it/6864), SuperchainWETH fits within the second budget, which includes smart contract code that secures assets. That means the `SuperchainWETH.sol` and `ETHLiquidity.sol` and associated interop contract dependencies (`CrossL2Inbox`, `L2ToL2CrossDomainMessenger`, `SuperchainTokenBridge`, `L1BlockInterop`, `SystemConfigInterop`, `OptimismPortalInterop`) require an audit before going to production. |
0 commit comments