Skip to content

Commit f91f648

Browse files
Joxessmds1
Joxess
and
mds1
authored
feat: Add new FMA Shared Lockbox (#193)
* docs: create fma-shared-lockbox.md * improve order * add reviewers Co-authored-by: Matt Solomon <[email protected]> * fix typo Co-authored-by: Matt Solomon <[email protected]> * add test requirements in fm2 Co-authored-by: Matt Solomon <[email protected]> * fix typo Co-authored-by: Matt Solomon <[email protected]> * remove L2-initiated upgrade feature references * add superchain-ops suggestion Co-authored-by: Matt Solomon <[email protected]> * add implementation PR * add opcm script requirements for fm3 * improve fm4 * improve fm3 mitigation section * add automated pause possibility as action item * improve action items * add generic fma * update status Co-authored-by: Matt Solomon <[email protected]> --------- Co-authored-by: Matt Solomon <[email protected]>
1 parent f76a23a commit f91f648

File tree

1 file changed

+128
-0
lines changed

1 file changed

+128
-0
lines changed

‎security/fma-shared-lockbox.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Shared Lockbox: Failure Modes and Recovery Path Analysis
2+
3+
| Author | Joxes, Agusduha |
4+
| --- | --- |
5+
| Created at | 2025-01-28 |
6+
| Initial Reviewers | Josep Bove |
7+
| Needs Approval From | Matt Solomon, Kelvin Fichter |
8+
| Status | Implementing Actions |
9+
10+
## Introduction
11+
12+
This document covers the changes introduced by the addition of the Shared Lockbox design, a singleton contract that stores all ETH liquidity for a given set of interoperable chains. It addresses the [ETH withdrawals problem](https://github.com/ethereum-optimism/specs/issues/362) by the introduction of [SuperchainWETH](https://github.com/ethereum-optimism/specs/blob/main/specs/interop/superchain-weth.md). The following components are:
13+
14+
- **Contracts**:
15+
- Introducing `SharedLockbox`: Stores all ETH liquidity for an interoperable graph. Only authorized `OptimismPortal` addresses can call `lockETH` and `unlockETH`.
16+
- Introducing `SuperchainConfigInterop`: A proxy and implementation contract on L1 that extends from `SuperchainConfig`. It tracks the official "mesh" of authorized chains and their protals using the `SharedLockbox` and grants the `clusterManager` the right to add new chains.
17+
- Updates to the `OptimismPortal2`: Contain the `lockETH` and `unlockETH` functions, enabled when the `Sharedlockbox` is used.
18+
- Updates to the `OptimismPortalInterop`: Extended functionality on top of `OptimismPortal2` to handle migrating its ETH liquidity to the `SharedLockbox` and locking/unlocking.
19+
20+
Below are references for this project:
21+
22+
- Specs PR: https://github.com/ethereum-optimism/specs/pull/465
23+
- Implementation PR: https://github.com/ethereum-optimism/optimism/pull/13144
24+
25+
Note that the inclusion of the dependency set in the fault-proof mechanism is relevant for the `SharedLockbox`, and it must function prior to the migration process of the contracts (analyzed here) to secure state transitions and thus withdrawals when a chain is added to any dependency set. The discussion around its design and implementation is still ongoing.
26+
27+
> 🗂️
28+
> **For more context about the Interop project, refer to the following docs:**
29+
> 1. [Interop System Diagram](https://www.notion.so/16c8052fcbb24b93ad1a539b5f8db4c1?pvs=21)
30+
> 2. [Interop PID](https://www.notion.so/16c8052fcbb24b93ad1a539b5f8db4c1?pvs=21)
31+
> 3. [Interop Audit Request](https://docs.google.com/document/d/1Rcuzbsguh7koT2jFru5ft9T8zAvjBEzbt0zF5LNQQ08/edit?tab=t.0)
32+
33+
## Failure Modes and Recovery Paths
34+
35+
### FM1: Unauthorized access to `unlockETH` function
36+
37+
- **Description:** If an attacker bypasses access controls for `unlockETH`, the deposit and withdrawal invariants can be broken, potentially resulting in the worst-case scenario of draining all ETH liquidity from the `SharedLockbox`.
38+
- **Risk Assessment:** High.
39+
- Potential Impact: Critical. Unauthorized ETH unlocking would result in a direct loss of ETH from the `SharedLockbox`.
40+
- Likelihood: Low. Access controls are specified in `if (!superchainConfig().authorizedPortals(msg.sender)) revert Unauthorized()`, but errors or misconfigurations remain possible.
41+
- **Mitigation:** There should be tests for `lockETH` and `unlockETH` checks. Access control must be strictly enforced, permitting only approved `OptimismPortal` contracts via the `authorizedPortals` mapping in `SuperchainConfigInterop`.
42+
- **Detection:** Monitor `ETHUnlocked` events to verify consistency with authorized portal addresses. Set up alerts for suspected unauthorized activity from non-approved addresses.
43+
- **Recovery Path(s):** Pause the system through `SuperchainConfig` to halt the `SharedLockbox` upon detection of unauthorized access.
44+
45+
### FM2: Compromised or poorly implemented `clusterManager` on L1
46+
47+
- **Description:** The `clusterManager` role in `SuperchainConfigInterop` is the entity in charge to call `addDependency`. If compromised, an attacker could add malicious or arbitrary chain IDs and authorize their own portal.
48+
- **Risk Assessment:** High.
49+
- Potential Impact: Critical. A malicious addition to the dependency set could allow an attacker to `unlockETH` from the `SharedLockbox`.
50+
- Likelihood: Low. The `clusterManager` should be a highly secured role (e.g., a multi-sig or governance key).
51+
- **Mitigations:** Tests to ensure `addDependency` cannot be called by unauthorized accounts. Strictly secure the `clusterManager` key.
52+
- **Detection:** Track the `DependencyAdded` event for calls from `clusterManager`. Compare newly added chain IDs to an approved list.
53+
- **Recovery Path(s):** Pause the system through `SuperchainConfig`. Since removal functions are unavailable, an upgrade directly over `SuperchainConfigInterop` to clear storage slots will be required.
54+
55+
### FM3: Unauthorized or incorrectly initialized `superchainConfig` address in `OptimismPortalInterop`.
56+
57+
- **Description:** In both `SharedLockbox` and `OptimismPortalInterop`, the address of the `SuperchainConfig` is stored in a special storage slot. If it’s set incorrectly or to a malicious address, the entire access-control scheme breaks.
58+
- **Risk Assessment:** High.
59+
- Potential Impact: Critical. Since the entire access-control scheme depends on `SuperchainConfig`, all funds could potentially be extracted from the `OptimismPortal`.
60+
- Likelihood: Low. Storage slots and values are carefully set during protocol upgrades.
61+
- **Mitigations:** There should be tests for the initialization step to ensure that `superchainConfig` is only set once, and the security team must validate—using a checklist-style review—that the storage slot for `superchainConfig` is not unintentionally changed before any upgrade.
62+
- **Detection:** Implement a verification step in the OPCM scripts to check that the final `superchainConfig` address in newly deployed or upgraded contracts matches the expected address.
63+
- **Recovery Path(s):** Pause the system, to upgrade the contract to set `superchainConfig` correctly.
64+
65+
### FM4: Solidity Compiler generates an exploitable Bytecode
66+
67+
- **Description:** Smart contracts are typically audited based on their source code, assuming that the Solidity compiler (`solc`) produces a correct and verifiable output. Relying solely on source code audits, without verifying the actual bytecode, could introduce undetected vulnerabilities.
68+
- **Risk Assessment:** High.
69+
- Potential Impact: Critical. If the Solidity compiler generates incorrect or exploitable bytecode, it could introduce a hidden attack vector.
70+
- Likelihood: Low. The Solidity compiler is widely used and battle-tested, but compiler bugs have occurred in the past.
71+
- **Mitigations:** Use a Solidity version that has been in production for at least 6 months per the [Solidity Upgrades guidelines](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/meta/SOLIDITY_UPGRADES.md). Actively track Solidity compiler CVEs and from existing resources such as [Solidity Security Alerts](https://soliditylang.org/blog/category/security-alerts/) and [Solidity Bugs Viewer](https://00xsev.github.io/solidityBugsByVersion/) to ensure the chosen compiler version remains robust and secure.
72+
- **Detection:** Monitor for new vulnerabilities in the compiler and for emerging Solidity bugs.
73+
- **Recovery Path(s):** Pause the system if a Solidity compiler bug is identified.
74+
75+
### FM5: Buggy upgrade over the `SharedLockbox`
76+
77+
- **Description:** The `SharedLockbox` is a proxied contract, which means its implementation can be upgraded. While this provides flexibility for fixes and improvements, a buggy or malicious upgrade could introduce vulnerabilities that compromise all ETH liquidity.
78+
- **Risk Assessment:** High.
79+
- Potential Impact: Critical. If an upgrade introduces a bug or an exploitable backdoor, all ETH stored in the `SharedLockbox` could be drained.
80+
- Likelihood: Low to Medium. Upgrades are controlled by Security Council, after governance approval. However, upgrade mistakes or compromised keys remain a risk.
81+
- **Mitigations:** Refer to [fma-generic-contracts](https://github.com/ethereum-optimism/design-docs/blob/main/security/fma-generic-contracts.md), items applies to this case. Any new implementation must go through the audit and testing. Upgrades should not be regular in this contract and it should maintain minimal code. Upgrade procedures and keys must follows the proper security practices.
82+
- **Detection:** Verify proxy and implementation contracts through automated checks in the superchain-ops task
83+
- **Recovery Path(s):** Refer to [fma-generic-contracts](https://github.com/ethereum-optimism/design-docs/blob/main/security/fma-generic-contracts.md). Pause the system through `SuperchainConfig` to halt the `SharedLockbox`.
84+
85+
### FM6: Unable to add new Chains by Reaching the `uint8` limit in `addDependency`
86+
87+
- **Description:** The `SuperchainConfigInterop` limit the number of dependencies to `type(uint8).max` (= 255). Once the set size reaches 255, any further `addDependency` call will revert.
88+
- **Risk Assessment:** Low.
89+
- Potential Impact: Medium. Future expansions of the interoperable set are blocked.
90+
- Likelihood: Low. 255 chains are already quite large, but could be a problem if the interoperable set wants to grow beyond that.
91+
- **Mitigations:** There should be a defined path to upgrade to increase the type from `uint8` to `uint16` or another approach. Current dependency set size should be monitored.
92+
- **Detection:** A simple periodic check of `dependencySetSize` in `SuperchainConfigInterop` should be sufficient to ensure the limit is not approaching. Reverts on calls to `addDependency` would indicate this issue.
93+
- **Recovery Path(s):** An upgrade over `SuperchainConfigInterop` is needed to support a larger capacity.
94+
95+
### FM7: `ETHMigrated` flag remains `false` in the `OptimismPortalInterop` after migration
96+
97+
- **Description:** During the `migrateLiquidity` call, the `OptimismPortalInterop` sets an internal `migrated = true` flag. If that flag is never set, the portal incorrectly tries to handle ETH locally (even though liquidity is already in the `SharedLockbox`).
98+
- **Risk Assessment:** Low.
99+
- Potential Impact: Medium. This situation will cause deposits and withdrawals to fail.
100+
- Likelihood: Very Low. The logic is straightforward, so only an upgrade or a code bug might cause it.
101+
- **Mitigations:** There should be tests for `migrateLiquidity` to set as `true`.
102+
- **Detection:** Check whether the `migrated` function is marked as `false` after `ETHMigrated` event is emitted. Watch for unexpected reverts on user withdrawals.
103+
- **Recovery Path(s):** Perform an upgrade to set the flag correctly.
104+
105+
### Generic items we need to take into account:
106+
107+
See [fma-generic-contracts.md](https://github.com/ethereum-optimism/design-docs/blob/main/security/fma-generic-contracts.md).
108+
109+
- [x] Check this box to confirm that these items have been considered and updated if necessary.
110+
111+
## Action Items
112+
113+
- [ ] Resolve all the comments.
114+
- [ ] FM1: Provide tests. (Wonderland)
115+
- [ ] FM1: Provide monitoring solutions.
116+
- [ ] FM2: Provide tests. (Wonderland)
117+
- [ ] FM2: Provide monitoring solutions.
118+
- [ ] FM3: Provide tests. (Wonderland)
119+
- [ ] FM3: Implement OPCM scripts that verify `superchainConfig`.
120+
- [ ] FM3: Ensure that the security team has a procedure in place to check storage slots before performing any upgrades.
121+
- [ ] FM4: Ensure that the security team is aware of how sensitive `SharedLockbox` is to potential compiler bugs.
122+
- [ ] FM1, FM2, FM3, FM4, FM5: Consider potential options for implementing automated pause mechanisms for the `SharedLockbox`, given the impact of these failures modes.
123+
- [ ] FM7: Provide tests.
124+
- [ ] Confirm the interop fault proofs are consistent with the Shared Lockbox and dependency set management implementation so that FM discussed are aligned with it and new ones aren’t expected.
125+
126+
## Audit Requirements
127+
128+
The `OptimismPortal2.sol`, `OptimismPortalInterop.sol`, `SharedLockbox.sol`, `SystemConfigInterop.sol`, and `SuperchainConfigInterop.sol` require an audit before production.

0 commit comments

Comments
 (0)