design doc for the ocpm superchain upgrade fix #310
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
maurelian
reviewed
Jul 29, 2025
maurelian
reviewed
Jul 29, 2025
Co-authored-by: Maurelian <[email protected]>
maurelian
reviewed
Jul 29, 2025
maurelian
reviewed
Jul 29, 2025
maurelian
reviewed
Jul 29, 2025
Co-authored-by: Maurelian <[email protected]>
Co-authored-by: Maurelian <[email protected]>
mds1
reviewed
Jul 29, 2025
| - The SuperchainConfig's implementation is Impl0 | ||
| - The OPCM has stored Impl1 as the implementation to upgrade to | ||
|
|
||
| If ChainA's proxyAdmin (also the SuperchainConfig's ProxyAdmin) calls the OPCM's `upgrade()` function, the check above (if (superchainProxyAdmin.getProxyImplementation(address(superchainConfig)) != impls.superchainConfigImpl)) will be true and it will upgrade the SuperchainConfig to Impl1 and also upgrade ChainA's L1 contracts. |
There was a problem hiding this comment.
We say ProxyAdmin a lot in this section, but is it correct that really it's the ProxyAdmin Owner that matter?
mds1
reviewed
Jul 29, 2025
| - The OPCM's `upgrade()` function is called and the SuperchainConfig's implementation is upgraded to Impl2 | ||
| - A new chain, ChainC comes in or is behind and has to use the old OPCM first | ||
|
|
||
| When it calls the OPCM's `upgrade()` function, the check above (if (superchainProxyAdmin.getProxyImplementation(address(superchainConfig)) != impls.superchainConfigImpl)) will be true and it will attempt to upgrade the SuperchainConfig which will fail since it's ProxyAdmin will not be the SuperchainConfig's ProxyAdmin. |
There was a problem hiding this comment.
Nit, implicit here is that ChainC has a different ProxyAdmin Owner (PAO)—let's state that explicitly for clarity
We should also explain what happens when ChainC has the same PAO
mds1
reviewed
Jul 29, 2025
Comment on lines
83
to
90
| A proposed solution for this is to change the check: | ||
| - Create a variable `bool isSuperchainUpgraded` in the OPCMUpgrader contract. | ||
| - When `OPCM.upgrade()` is called, it delegates call to `OPCMUpgrader.upgrade()` as usual. | ||
| - `OPCMUpgrader.upgrade()` calls back into itself (to be able to access it's storage) and checks if the superchainConfig is already upgraded by checking the `isSuperchainUpgraded` variable. | ||
| - If it is not upgraded, it calls back into itself once more to set the `isSuperchainUpgraded` variable to true and then upgrade the superchainConfig. | ||
| - If it is already upgraded, it will skip the upgrade and continue execution. | ||
|
|
||
| While at it, it is proposed to also add support for different superchainConfigs i.e different Superchains. We can easily do this by replacing the `isSuperchainUpgraded` variable with a mapping `mapping(ISuperchainConfig superchainConfig => bool isSuperchainUpgraded)`. This way we can check which superchainConfig is being upgraded and set the `isSuperchainUpgraded` variable to true for that superchainConfig while also preventing the same superchainConfig from being upgraded again. |
There was a problem hiding this comment.
Hmm the control flow here feels a bit confusing and error prone. Is there a solution where we add inputs so the caller can simply specify whether they want to try upgrading the superchainConfig, with the following logic:
- Add
bool shouldUpgradeSuperchainConfigas an input to theupgrademethod` - If
isRc == false, this input value MUST be true. Revert if this condition is violated - Otherwise, proceed to do the upgrade as normal and try upgrading superchainConfig when requested
- Note: Downside here is that chains with their own superchainConfig must remember to manually pass in
truefor this new bool
Alternatively, can we just make the (superchainProxyAdmin.getProxyImplementation(address(superchainConfig)) != impls.superchainConfigImpl)) check smarter to do a greater than/less than semver comparison instead of strict inequality?
There was a problem hiding this comment.
Yeah but we want to try not changing the interface at all
There was a problem hiding this comment.
Got it, so would it be fair to say there's two solutions here:
- Short term patches for the existing OPCM where we don't want to change the interface
- Longer term solution (i.e. for all future OPCMs) where we are ok with breaking the interface to simplify things. In these future OPCMs, we can read the PAO from any contract, therefore we can keep the interfaces the same and just have smarter internal logic about when to upgrade?
maurelian
reviewed
Jul 31, 2025
| } | ||
| ``` | ||
|
|
||
| ## Requirements and Expected behaviour |
There was a problem hiding this comment.
We should remove this section since we added a similar one above.
maurelian
reviewed
Jul 31, 2025
maurelian
reviewed
Aug 11, 2025
maurelian
reviewed
Aug 11, 2025
Co-authored-by: Maurelian <[email protected]>
Co-authored-by: Maurelian <[email protected]>
maurelian
reviewed
Aug 11, 2025
|
|
||
| ## Proposed Solution | ||
|
|
||
| A proposed solution for this is to change the check to version comparisons. We can hardcode an expected version for the SuperchainConfig and compare it to the actual version. If the actual version is equal to the expected version, we can upgrade the SuperchainConfig. Otherwise we continue the execution. |
There was a problem hiding this comment.
To clarify, which of the following will be the upgrade condition
- The current
superchainConfig.version()value is equal to the previous OR - The current
superchainConfig.version()value is not equal to the current
?
maurelian
reviewed
Aug 11, 2025
| } | ||
| } | ||
| ``` | ||
| - It is also important to note that for any superchain asides the one with its superchainConfig hardcoded in the OPCM, in order to upgrade the superchainConfig, one of it's L1 chains which has the same ProxyAdmin as the SuperchainConfig's ProxyAdmin will need to be upgraded in the same transaction i.e the `OpChainConfig` should not be empty. This is because if the `OpChainConfig` is empty, the function defaults to using a hardcoded superchainConfig and superchainProxyAdmin. |
There was a problem hiding this comment.
I think that this is very important. It means that:
- we do not support a SuperchainConfig having a ProxyAdmin which is not also the owner of an OP Chain
- it is not possible to upgrade a SuperchainConfig without upgrading at least one OP Chain.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
design doc for the ocpm superchain upgrade fix