Please note that this is a Proposal Preview and is not an actual proposal. It is meant to allow the Collective to provide feedback and ask questions before an official proposal is published.
Executive Summary
This proposal preview outlines the implementation of a new system for upgrading L1 contracts across the Superchain.
Motivation
The current L1 contract upgrade process is heavily manual, resulting in significant effort from developers and signers, while also being more prone to error.
A typical upgrade requires performing the following steps (examples from the Holocene upgrade are provided for reference):
- Once development is complete, a commit is tagged in the monorepo as a release candidate (Holocene example).
- New contracts are deployed from that commit in advance of the upgrade (for Holocene, this meant deploying the new
SystemConfigimplementation contract here). - The transactions which implement the upgrade path are defined as a JSON bundle (Holocene example) in the
superchain-opsrepo. There is no single standard way of generating this bundle. While that is acceptable from a safety perspective as the important thing is in the validation of the resulting execution, however from a process and upgrade development standpoint it is inefficient and time consuming for the developer. - That JSON bundle is read and executed by a script. Each upgrade has custom checks (Holocene example) included in that script to enforce its safety. During the signing process, the upgrade transaction is simulated (locally by forge), and the checks are run against the result of that simulation.
- State diff validation checks are also written in a markdown document (Holocene example). Signers use this document to guide a manual review of the state diff which is shown in a Tenderly simulation. The state diff resulting from the actual Holocene upgrade transaction can be seen here, a very similar view was generated prior to the upgrade, and each entry in the state diff was checked against the Validations.md file.
- Finally, the signers sign the upgrade transaction. Those signatures are combined and submitted to the Safes, resulting in the execution of the upgrade.
As the number of chains in the superchain increases, the above process will not scale well. Moreover it separates the development and testing of the system from that of the actual upgrade flow, which makes it difficult to fully test the upgrade path, and the system which results from the upgrade.
Proposed Process
The new process will look like the following, with references from the forthcoming upgrade 13.
- The upgrade path will be implemented in the
OPContractManager’supgrade()function. This has a major benefit of more tightly coupling the implementation and testing of the upgrade path with the contracts themselves. For example, the monorepo now forks the currently running version of OP Mainnet, runs the upgrade, and then executes the test suite against the resulting system. - The
OPContractsManageris deployed to Sepolia and Mainnet. All addresses required for the upgrade are deployed at the same time with a singleop-deployercommand, and are contained in its Implementations struct. The addresses in that struct are the release candidates for each contract. A benefit here is that release version signalling is moved on-chain, making it an integral part of the upgrade process. No other contracts need to be deployed in advance. - The upgrade task will be developed in the
superchain-opsrepo. Unlike the many calls in the JSON bundle in the above process, only a single call to theupgrade()function is necessary. In the future that call will be automatically generated from a human readable config file. - The validations in steps 4 and 5 are unchanged for now.
- The streamlining of this process will make it easier to create the
superchain-opstasks, and will enable us to include the exact calldata which signers will use to execute the upgrade, in the governance proposal.
Technical details
The specific protocol changes includes in this proposal are:
- OP Contracts Manager (OPCM): Each release will have its own OPCM that can deploy new proxies and upgrade existing OP Chains. It is important to note that the OP Contracts Manager is not considered to be part of the protocol; it has no special role, and no contracts reference it. It is more like an on-chain script for orchestrating deployments and upgrades.
- In-protocol Contract Modifications: The changes to the L1 contracts covered by this proposal are relatively minor. They help to improve our engineering process, but do not affect governance approved features and functionality:
- Stack too deep fixes in three PRs: 1, 2, 3. These changes enable us to generate code coverage measurements.
- Contracts have been updated to call interfaces for external interactions rather than implementations (example PR). This greatly reduces the compilation time and speeds up our development process.
- Removal of CustomGasToken logic in two PRs: 1, 2. The CustomGasToken functionality had not been governance approved nor deployed, but was included in the contracts in the monorepo before the decision was made to remove it.
All of the changes above have been audited. Minor fixes resulting from that audit are being finalized and the report will be made available when it is ready.
Impact summary
The adoption of this proposal will improve the safety and reliability of upgrades. This should in-turn enable smaller and more frequent upgrade to occur, thus increasing the speed of iteration and improvement.