From f03f795c4ee82b6812f369330fb45962a5bba215 Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Tue, 5 Nov 2024 16:06:07 -0500 Subject: [PATCH 01/18] opcm-redesign: Redesigning OPCM with Upgrades in mind. --- .../op-contracts-manager-arch-redesign.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 protocol/op-contracts-manager-arch-redesign.md diff --git a/protocol/op-contracts-manager-arch-redesign.md b/protocol/op-contracts-manager-arch-redesign.md new file mode 100644 index 00000000..f82bdea2 --- /dev/null +++ b/protocol/op-contracts-manager-arch-redesign.md @@ -0,0 +1,79 @@ +# Purpose + +The original OPContractsManager (OPCM) design, outlined [here](./op-contracts-manager-arch.md), defined a proxied contract that deployed the L1 contracts for standard OP Stack chains in a single transaction. + +Implementing upgrade functionality for OP Stack chains via OPCM is now a key goal. As we approach this feature, we've identified necessary adjustments to OPCM to support upgradability. Therefore, the purpose of this design document is to aid building OPCM upgradability features by making changes to OPCM's architecture. + +# Summary + +The summary of the changes to OPCM is as follows: + +- Remove proxy from OPCM +- Remove [initialize](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L210) functionality from OPCM and introduce standard constructor initialization. +- Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM +- Update `DeploySuperchain.s.sol`, `DeployImplementations.s.sol` and `DeployOPChain.s.sol` to work with the new paradigm of one OPCM per L1 smart contract release. +- **Optional**: Add authentication to OPCM in anticipation for upgrade features. + + +# Problem Statement + Context + +We’ve identified the need to implement an upgradability feature for OP Stack chains. This will involve two core components: [op-deployer](../ecosystem/op-deployer.md) and [OPCM](./op-contracts-manager-arch.md). As of November 5, 2024, both op-deployer and OPCM support only the deployment of new chains at fixed versions. +Each new chain version requires additional conditional logic in both op-deployer and the OPCM singleton. This creates logic that is difficult to maintain and reason about. This approach will become increasingly unwieldy as we integrate OP Stack upgrades into op-deployer and OPCM. + +## Examples of Unwanted Conditional Logic +- Deciding how to initialize the `SystemConfig` contract correctly via OPCM - [code](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L457-L462). This branching logic exists because OPCM needed to be able to deploy chains at older tags (e.g. op-contracts/v1.6.0) as well as later chains. The primary challenge here is that the `develop` branch in the monorepo naturally evolves, requiring deployment (OPCM and op-deployer) code to evolve with it, all while continuing to support older deployments. +- `// TODO: Add a link to an example in op-deployer that contains unwanted conditional logic.` + +Authentication was not originally implemented in OPCM because it solely supported deployments, with the rationale being that there was no immediate need to restrict access to the deploy function. However, with the introduction of upgrade functionality, it’s essential to establish a robust authentication mechanism within OPCM. We now need to determine appropriate access controls and define roles for authorized users who will be permitted to perform upgrades. + +# Alternatives Considered + +1. Continue with the approach of adding additional conditional logic for every new chain version that is released. As noted, this leads to a system that is complex and hard to maintain. +2. `// TODO - Add another alernative approach that was discussed here but wasn't chosen.` + +# Proposed Solution + +## OPCM Architecture Changes + +Having one OPCM per *L1 smart contract release version*** means that we can remove the proxy pattern that currently exists with OPCM. The high level architecture changes can be seen below: + +### Previous OPCM Deploys +Before OPCM was proxied so that it was upgradable. +```mermaid +flowchart LR + A[Any Account] -->|call| C[Proxy] + C -->|delegatecall| D[OPCM] +``` + +### New OPCM Deploys +Now OPCM is not proxied and therefore not upgradable. This is by design though as we want to release a new OPCM for each new L1 smart contract release. +```mermaid +flowchart LR + A[Any Account] -->|call| B[OPCM - op-contracts/v1.3.0] + C[Any Account] -->|call| D[OPCM - op-contracts/v1.6.0] +``` + +## Versioning + +Now that each OPCM deploy is going to be tethered directly to an L1 smart contract release version, for improved UX, we should provide public getters to expose two pieces of information: + +1. The current L1 smart contracts that are deployed via this version of OPCM e.g. `op-contracts/v1.6.0`. This means we will no longer need to pass the standard versions toml [file](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L61) around like [this](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L1060). The implementation addresses can be added to the OPCM contract as as immutable values. +2. The address of the previous OPCM contract + +This creates a linked list whereby a user can find all prior OPCMs starting from the current OPCM contract. This will prove useful for implementing upgrade functionality because with this information an OPCM can easily expose the version of L1 smart contracts that it supports upgrading **from** and **to**. + +## Authentication (Optional) + +As we know that upgrades are coming to OPCM we can preemtively add authentication to OPCM as part of this architecture redesign. + +It is our intention to keep the OPCM [deploy](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L226) function permissionless. + +- `//TODO Determine WHO should perform these upgrades` +- `//TODO Determine HOW these access controls should be implemented in OPCM` + + +# Risks & Uncertainties + +`// TODO` + +** *To view all official L1 smart releases, run `git tag -l | grep op-contracts` on the `develop` branch inside the [monorepo](https://github.com/ethereum-optimism/optimism).* \ No newline at end of file From 64f212c4a686165342b5f6a94e3ffef52f85a9ff Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Tue, 5 Nov 2024 16:16:28 -0500 Subject: [PATCH 02/18] fix: clearer intro. --- protocol/op-contracts-manager-arch-redesign.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/op-contracts-manager-arch-redesign.md b/protocol/op-contracts-manager-arch-redesign.md index f82bdea2..edd9ae3c 100644 --- a/protocol/op-contracts-manager-arch-redesign.md +++ b/protocol/op-contracts-manager-arch-redesign.md @@ -2,7 +2,7 @@ The original OPContractsManager (OPCM) design, outlined [here](./op-contracts-manager-arch.md), defined a proxied contract that deployed the L1 contracts for standard OP Stack chains in a single transaction. -Implementing upgrade functionality for OP Stack chains via OPCM is now a key goal. As we approach this feature, we've identified necessary adjustments to OPCM to support upgradability. Therefore, the purpose of this design document is to aid building OPCM upgradability features by making changes to OPCM's architecture. +Implementing upgrade functionality for OP Stack chains via OPCM is now a key goal. As we approach this feature, we've identified several interim adjustments to OPCM that will be necessary to eventually support upgradability. Therefore, the purpose of this design document is to aid building OPCM upgradability features by making changes to OPCM's architecture. # Summary From c636f518a89a2cc347c679e4a3c1e271703f10cc Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Tue, 5 Nov 2024 16:24:27 -0500 Subject: [PATCH 03/18] fix: adding link --- protocol/op-contracts-manager-arch-redesign.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/protocol/op-contracts-manager-arch-redesign.md b/protocol/op-contracts-manager-arch-redesign.md index edd9ae3c..1cdb5488 100644 --- a/protocol/op-contracts-manager-arch-redesign.md +++ b/protocol/op-contracts-manager-arch-redesign.md @@ -8,9 +8,9 @@ Implementing upgrade functionality for OP Stack chains via OPCM is now a key goa The summary of the changes to OPCM is as follows: -- Remove proxy from OPCM +- Remove the [proxy](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L545) from OPCM. - Remove [initialize](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L210) functionality from OPCM and introduce standard constructor initialization. -- Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM +- Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM. - Update `DeploySuperchain.s.sol`, `DeployImplementations.s.sol` and `DeployOPChain.s.sol` to work with the new paradigm of one OPCM per L1 smart contract release. - **Optional**: Add authentication to OPCM in anticipation for upgrade features. From 8026014bf531d19ac6cfeaa40a4fc797721bd25e Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Tue, 5 Nov 2024 16:25:49 -0500 Subject: [PATCH 04/18] fix: add simple example. --- protocol/op-contracts-manager-arch-redesign.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/op-contracts-manager-arch-redesign.md b/protocol/op-contracts-manager-arch-redesign.md index 1cdb5488..1d40156d 100644 --- a/protocol/op-contracts-manager-arch-redesign.md +++ b/protocol/op-contracts-manager-arch-redesign.md @@ -10,7 +10,7 @@ The summary of the changes to OPCM is as follows: - Remove the [proxy](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L545) from OPCM. - Remove [initialize](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L210) functionality from OPCM and introduce standard constructor initialization. -- Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM. +- Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM deployment e.g. OPCM address `0x1234...` deploys `op-contracts/v1.6.0`. - Update `DeploySuperchain.s.sol`, `DeployImplementations.s.sol` and `DeployOPChain.s.sol` to work with the new paradigm of one OPCM per L1 smart contract release. - **Optional**: Add authentication to OPCM in anticipation for upgrade features. From fc408482800af0316ec620aca063e77cefdefffb Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Tue, 5 Nov 2024 16:28:53 -0500 Subject: [PATCH 05/18] fix: adding more clarity. --- protocol/op-contracts-manager-arch-redesign.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/protocol/op-contracts-manager-arch-redesign.md b/protocol/op-contracts-manager-arch-redesign.md index 1d40156d..7971449b 100644 --- a/protocol/op-contracts-manager-arch-redesign.md +++ b/protocol/op-contracts-manager-arch-redesign.md @@ -1,6 +1,6 @@ # Purpose -The original OPContractsManager (OPCM) design, outlined [here](./op-contracts-manager-arch.md), defined a proxied contract that deployed the L1 contracts for standard OP Stack chains in a single transaction. +The original OPContractsManager (OPCM) design, outlined [here](./op-contracts-manager-arch.md), defined a singleton proxied contract that deployed the L1 contracts for standard OP Stack chains in a single transaction. Implementing upgrade functionality for OP Stack chains via OPCM is now a key goal. As we approach this feature, we've identified several interim adjustments to OPCM that will be necessary to eventually support upgradability. Therefore, the purpose of this design document is to aid building OPCM upgradability features by making changes to OPCM's architecture. @@ -8,6 +8,7 @@ Implementing upgrade functionality for OP Stack chains via OPCM is now a key goa The summary of the changes to OPCM is as follows: +- Move away from singleton OPCM approach in favor of one OPCM deployment per L1 smart contract release. - Remove the [proxy](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L545) from OPCM. - Remove [initialize](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L210) functionality from OPCM and introduce standard constructor initialization. - Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM deployment e.g. OPCM address `0x1234...` deploys `op-contracts/v1.6.0`. @@ -18,7 +19,7 @@ The summary of the changes to OPCM is as follows: # Problem Statement + Context We’ve identified the need to implement an upgradability feature for OP Stack chains. This will involve two core components: [op-deployer](../ecosystem/op-deployer.md) and [OPCM](./op-contracts-manager-arch.md). As of November 5, 2024, both op-deployer and OPCM support only the deployment of new chains at fixed versions. -Each new chain version requires additional conditional logic in both op-deployer and the OPCM singleton. This creates logic that is difficult to maintain and reason about. This approach will become increasingly unwieldy as we integrate OP Stack upgrades into op-deployer and OPCM. +Each new chain version requires additional conditional logic in both op-deployer and the OPCM singleton. This creates logic that is difficult to maintain and reason about. This approach will become increasingly unwieldy as we integrate OP Stack upgrade functionality into op-deployer and OPCM. ## Examples of Unwanted Conditional Logic - Deciding how to initialize the `SystemConfig` contract correctly via OPCM - [code](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L457-L462). This branching logic exists because OPCM needed to be able to deploy chains at older tags (e.g. op-contracts/v1.6.0) as well as later chains. The primary challenge here is that the `develop` branch in the monorepo naturally evolves, requiring deployment (OPCM and op-deployer) code to evolve with it, all while continuing to support older deployments. From 8e375c27d24f2f8052f53324ce8e70cdf65fde5b Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Tue, 5 Nov 2024 16:32:37 -0500 Subject: [PATCH 06/18] fix: linting --- protocol/op-contracts-manager-arch-redesign.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/protocol/op-contracts-manager-arch-redesign.md b/protocol/op-contracts-manager-arch-redesign.md index 7971449b..7affd0d3 100644 --- a/protocol/op-contracts-manager-arch-redesign.md +++ b/protocol/op-contracts-manager-arch-redesign.md @@ -58,8 +58,8 @@ flowchart LR Now that each OPCM deploy is going to be tethered directly to an L1 smart contract release version, for improved UX, we should provide public getters to expose two pieces of information: -1. The current L1 smart contracts that are deployed via this version of OPCM e.g. `op-contracts/v1.6.0`. This means we will no longer need to pass the standard versions toml [file](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L61) around like [this](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L1060). The implementation addresses can be added to the OPCM contract as as immutable values. -2. The address of the previous OPCM contract +1. The **current L1 smart contracts** that are deployed via this version of OPCM e.g. `op-contracts/v1.6.0`. This means we will no longer need to pass the standard versions toml [file](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L61) around like [this](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L1060). The implementation addresses can be added to the OPCM contract as as immutable values. +2. The **address of the previous OPCM** contract. This creates a linked list whereby a user can find all prior OPCMs starting from the current OPCM contract. This will prove useful for implementing upgrade functionality because with this information an OPCM can easily expose the version of L1 smart contracts that it supports upgrading **from** and **to**. From 201d78b9a2d2e53c7c2bfe719b3f5ad38d25ef6e Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Tue, 5 Nov 2024 17:18:49 -0500 Subject: [PATCH 07/18] fix: add in opcm mainnet. --- protocol/op-contracts-manager-arch-redesign.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/op-contracts-manager-arch-redesign.md b/protocol/op-contracts-manager-arch-redesign.md index 7affd0d3..23a0a574 100644 --- a/protocol/op-contracts-manager-arch-redesign.md +++ b/protocol/op-contracts-manager-arch-redesign.md @@ -39,7 +39,7 @@ Authentication was not originally implemented in OPCM because it solely supporte Having one OPCM per *L1 smart contract release version*** means that we can remove the proxy pattern that currently exists with OPCM. The high level architecture changes can be seen below: ### Previous OPCM Deploys -Before OPCM was proxied so that it was upgradable. +Before OPCM was proxied so that it was upgradable. e.g. [`0x18CeC91779995AD14c880e4095456B9147160790`](https://etherscan.io/address/0x18CeC91779995AD14c880e4095456B9147160790) ```mermaid flowchart LR A[Any Account] -->|call| C[Proxy] From 748629fa693797d4b6c5f33ac62f5cd6755ab4bc Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Wed, 6 Nov 2024 08:56:06 -0500 Subject: [PATCH 08/18] fix: small updates. --- ...gn.md => op-contracts-manager-single-release-redesign.md} | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) rename protocol/{op-contracts-manager-arch-redesign.md => op-contracts-manager-single-release-redesign.md} (95%) diff --git a/protocol/op-contracts-manager-arch-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md similarity index 95% rename from protocol/op-contracts-manager-arch-redesign.md rename to protocol/op-contracts-manager-single-release-redesign.md index 23a0a574..213dfc9c 100644 --- a/protocol/op-contracts-manager-arch-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -6,9 +6,8 @@ Implementing upgrade functionality for OP Stack chains via OPCM is now a key goa # Summary -The summary of the changes to OPCM is as follows: +OPCM will transition from its current singleton architecture to a multi-deployment model, with each deployment focused on a specific L1 smart contract release version. To achieve this, the following changes need to be implemented: -- Move away from singleton OPCM approach in favor of one OPCM deployment per L1 smart contract release. - Remove the [proxy](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L545) from OPCM. - Remove [initialize](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L210) functionality from OPCM and introduce standard constructor initialization. - Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM deployment e.g. OPCM address `0x1234...` deploys `op-contracts/v1.6.0`. @@ -18,7 +17,7 @@ The summary of the changes to OPCM is as follows: # Problem Statement + Context -We’ve identified the need to implement an upgradability feature for OP Stack chains. This will involve two core components: [op-deployer](../ecosystem/op-deployer.md) and [OPCM](./op-contracts-manager-arch.md). As of November 5, 2024, both op-deployer and OPCM support only the deployment of new chains at fixed versions. +We’ve identified the need to implement an upgradability feature for OP Stack chains. This will involve two core components: [op-deployer](../ecosystem/op-deployer.md) and [OPCM](./op-contracts-manager-arch.md). As of November 6, 2024, both op-deployer and OPCM support only the deployment of new chains at fixed versions. Each new chain version requires additional conditional logic in both op-deployer and the OPCM singleton. This creates logic that is difficult to maintain and reason about. This approach will become increasingly unwieldy as we integrate OP Stack upgrade functionality into op-deployer and OPCM. ## Examples of Unwanted Conditional Logic From cc07b0d375c4b456b1fb288a8eb341fa3edd08a9 Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Wed, 6 Nov 2024 09:18:50 -0500 Subject: [PATCH 09/18] fix: more clarity around op-deployer changes. --- protocol/op-contracts-manager-single-release-redesign.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index 213dfc9c..825bcc22 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -20,9 +20,13 @@ OPCM will transition from its current singleton architecture to a multi-deployme We’ve identified the need to implement an upgradability feature for OP Stack chains. This will involve two core components: [op-deployer](../ecosystem/op-deployer.md) and [OPCM](./op-contracts-manager-arch.md). As of November 6, 2024, both op-deployer and OPCM support only the deployment of new chains at fixed versions. Each new chain version requires additional conditional logic in both op-deployer and the OPCM singleton. This creates logic that is difficult to maintain and reason about. This approach will become increasingly unwieldy as we integrate OP Stack upgrade functionality into op-deployer and OPCM. -## Examples of Unwanted Conditional Logic +## Example of Unwanted Conditional Logic in OPCM - Deciding how to initialize the `SystemConfig` contract correctly via OPCM - [code](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L457-L462). This branching logic exists because OPCM needed to be able to deploy chains at older tags (e.g. op-contracts/v1.6.0) as well as later chains. The primary challenge here is that the `develop` branch in the monorepo naturally evolves, requiring deployment (OPCM and op-deployer) code to evolve with it, all while continuing to support older deployments. -- `// TODO: Add a link to an example in op-deployer that contains unwanted conditional logic.` + +## Example of Unwanted Complexity in op-deployer +- Each `op-deployer` releases currently bundles standard version TOML files from the superchain-registry. These files contain the addresses corresponding to each L1 smart contract release. Developers must [manually sync](https://github.com/ethereum-optimism/optimism/blob/bc9b6cd588588c9c4167c926a1782c658e5df921/op-chain-ops/Makefile#L50-L52) the TOML files before cutting a new release. Since these release addresses are tightly coupled to op-deployer, they need to be injected into OPCM. Without this injection, OPCM is unaware of the implementation addresses of any L1 smart contract releases. A system in which OPCM is 'release aware' simplifies the logic within op-deployer. In this setup, op-deployer would maintain a list of OPCM addresses and manage interactions with each address on a case-by-case basis. + +## Optional: Authentication Authentication was not originally implemented in OPCM because it solely supported deployments, with the rationale being that there was no immediate need to restrict access to the deploy function. However, with the introduction of upgrade functionality, it’s essential to establish a robust authentication mechanism within OPCM. We now need to determine appropriate access controls and define roles for authorized users who will be permitted to perform upgrades. From 620ec5153919bf46472a8e5f6af3a944f3aae34b Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Wed, 6 Nov 2024 09:32:42 -0500 Subject: [PATCH 10/18] fix: risks added. --- .../op-contracts-manager-single-release-redesign.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index 825bcc22..fe578f9a 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -21,19 +21,18 @@ We’ve identified the need to implement an upgradability feature for OP Stack c Each new chain version requires additional conditional logic in both op-deployer and the OPCM singleton. This creates logic that is difficult to maintain and reason about. This approach will become increasingly unwieldy as we integrate OP Stack upgrade functionality into op-deployer and OPCM. ## Example of Unwanted Conditional Logic in OPCM -- Deciding how to initialize the `SystemConfig` contract correctly via OPCM - [code](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L457-L462). This branching logic exists because OPCM needed to be able to deploy chains at older tags (e.g. op-contracts/v1.6.0) as well as later chains. The primary challenge here is that the `develop` branch in the monorepo naturally evolves, requiring deployment (OPCM and op-deployer) code to evolve with it, all while continuing to support older deployments. +- Deciding how to initialize the `SystemConfig` contract correctly via OPCM - [code](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L457-L462). This branching logic exists because OPCM needed to be able to deploy chains at older tags (e.g. `op-contracts/v1.6.0`) as well as later chains. The primary challenge here is that the `develop` branch in the monorepo naturally evolves, requiring deployment (OPCM and op-deployer) code to evolve with it, all while continuing to support older deployments. ## Example of Unwanted Complexity in op-deployer - Each `op-deployer` releases currently bundles standard version TOML files from the superchain-registry. These files contain the addresses corresponding to each L1 smart contract release. Developers must [manually sync](https://github.com/ethereum-optimism/optimism/blob/bc9b6cd588588c9c4167c926a1782c658e5df921/op-chain-ops/Makefile#L50-L52) the TOML files before cutting a new release. Since these release addresses are tightly coupled to op-deployer, they need to be injected into OPCM. Without this injection, OPCM is unaware of the implementation addresses of any L1 smart contract releases. A system in which OPCM is 'release aware' simplifies the logic within op-deployer. In this setup, op-deployer would maintain a list of OPCM addresses and manage interactions with each address on a case-by-case basis. -## Optional: Authentication +## Authentication (Optional) -Authentication was not originally implemented in OPCM because it solely supported deployments, with the rationale being that there was no immediate need to restrict access to the deploy function. However, with the introduction of upgrade functionality, it’s essential to establish a robust authentication mechanism within OPCM. We now need to determine appropriate access controls and define roles for authorized users who will be permitted to perform upgrades. +Authentication was not originally implemented in OPCM because it solely supported deployments, with the rationale being that there was no immediate need to restrict access to the deploy function. However, with the introduction of upgrade functionality, it’s essential to establish a robust authentication mechanism within OPCM. We now need to determine appropriate access controls and define roles for authorized users who will be permitted to perform upgrades. We can choose to implement this now to prepare for future use in OPCM upgrade features, or we may decide to postpone it until a later stage. # Alternatives Considered -1. Continue with the approach of adding additional conditional logic for every new chain version that is released. As noted, this leads to a system that is complex and hard to maintain. -2. `// TODO - Add another alernative approach that was discussed here but wasn't chosen.` +Continue with the approach of adding additional conditional logic for every new chain version that is released. As noted, this leads to a system that is complex and hard to maintain. # Proposed Solution @@ -78,6 +77,7 @@ It is our intention to keep the OPCM [deploy](https://github.com/ethereum-optimi # Risks & Uncertainties -`// TODO` +With more OPCM versions, we’ll need to write additional production Solidity code. While our engineering practices help minimize bugs, it is still worth considering whether increasing the surface area of onchain interactions is desirable. + ** *To view all official L1 smart releases, run `git tag -l | grep op-contracts` on the `develop` branch inside the [monorepo](https://github.com/ethereum-optimism/optimism).* \ No newline at end of file From ea3f67eb705508d5d25531d7fe0c120dfee0e073 Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Wed, 6 Nov 2024 12:43:02 -0500 Subject: [PATCH 11/18] fix: pr comments. --- .../op-contracts-manager-single-release-redesign.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index fe578f9a..9ba86592 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -2,7 +2,7 @@ The original OPContractsManager (OPCM) design, outlined [here](./op-contracts-manager-arch.md), defined a singleton proxied contract that deployed the L1 contracts for standard OP Stack chains in a single transaction. -Implementing upgrade functionality for OP Stack chains via OPCM is now a key goal. As we approach this feature, we've identified several interim adjustments to OPCM that will be necessary to eventually support upgradability. Therefore, the purpose of this design document is to aid building OPCM upgradability features by making changes to OPCM's architecture. +Implementing upgrade functionality for OP Stack chains via OPCM is now a key goal. As we approach this feature, we've identified several interim adjustments to OPCM that will that will not only enable future upgradability but also simplify its overall design. Therefore, the purpose of this design document is to streamline OPCM’s architecture, making it easier to build and integrate upgradability features. # Summary @@ -11,14 +11,13 @@ OPCM will transition from its current singleton architecture to a multi-deployme - Remove the [proxy](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L545) from OPCM. - Remove [initialize](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L210) functionality from OPCM and introduce standard constructor initialization. - Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM deployment e.g. OPCM address `0x1234...` deploys `op-contracts/v1.6.0`. -- Update `DeploySuperchain.s.sol`, `DeployImplementations.s.sol` and `DeployOPChain.s.sol` to work with the new paradigm of one OPCM per L1 smart contract release. +- Update `op-deployer`, `DeploySuperchain.s.sol`, `DeployImplementations.s.sol` and `DeployOPChain.s.sol` to work with the new multi-deployment paradigm of one OPCM per L1 smart contract release. - **Optional**: Add authentication to OPCM in anticipation for upgrade features. # Problem Statement + Context -We’ve identified the need to implement an upgradability feature for OP Stack chains. This will involve two core components: [op-deployer](../ecosystem/op-deployer.md) and [OPCM](./op-contracts-manager-arch.md). As of November 6, 2024, both op-deployer and OPCM support only the deployment of new chains at fixed versions. -Each new chain version requires additional conditional logic in both op-deployer and the OPCM singleton. This creates logic that is difficult to maintain and reason about. This approach will become increasingly unwieldy as we integrate OP Stack upgrade functionality into op-deployer and OPCM. +[OPCM](./op-contracts-manager-arch.md)'s architecture will quickly become untenable as more L1 smart contract releases are supported for deployment. Each new release version requires additional conditional logic in both [op-deployer](../ecosystem/op-deployer.md) and the OPCM singleton. This creates logic that is difficult to maintain and reason about. This approach will become increasingly unwieldy as we integrate OP Stack upgrade functionality into op-deployer and OPCM. Examples of how these complexities are introduced can be seen below: ## Example of Unwanted Conditional Logic in OPCM - Deciding how to initialize the `SystemConfig` contract correctly via OPCM - [code](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L457-L462). This branching logic exists because OPCM needed to be able to deploy chains at older tags (e.g. `op-contracts/v1.6.0`) as well as later chains. The primary challenge here is that the `develop` branch in the monorepo naturally evolves, requiring deployment (OPCM and op-deployer) code to evolve with it, all while continuing to support older deployments. @@ -38,7 +37,7 @@ Continue with the approach of adding additional conditional logic for every new ## OPCM Architecture Changes -Having one OPCM per *L1 smart contract release version*** means that we can remove the proxy pattern that currently exists with OPCM. The high level architecture changes can be seen below: +Having one OPCM per *L1 smart contract release version*[^1] means that we can remove the proxy pattern that currently exists with OPCM. The high level architecture changes can be seen below: ### Previous OPCM Deploys Before OPCM was proxied so that it was upgradable. e.g. [`0x18CeC91779995AD14c880e4095456B9147160790`](https://etherscan.io/address/0x18CeC91779995AD14c880e4095456B9147160790) @@ -80,4 +79,4 @@ It is our intention to keep the OPCM [deploy](https://github.com/ethereum-optimi With more OPCM versions, we’ll need to write additional production Solidity code. While our engineering practices help minimize bugs, it is still worth considering whether increasing the surface area of onchain interactions is desirable. -** *To view all official L1 smart releases, run `git tag -l | grep op-contracts` on the `develop` branch inside the [monorepo](https://github.com/ethereum-optimism/optimism).* \ No newline at end of file +[^1]: *To view all official L1 smart releases, run `git tag -l | grep op-contracts` on the `develop` branch inside the [monorepo](https://github.com/ethereum-optimism/optimism).* \ No newline at end of file From 5be2ed2dc27726cd5c166838110417ceb463c810 Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Wed, 6 Nov 2024 12:50:29 -0500 Subject: [PATCH 12/18] fix: clarity around versioning and removing authentication notes. --- ...contracts-manager-single-release-redesign.md | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index 9ba86592..fa47c8f1 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -10,9 +10,8 @@ OPCM will transition from its current singleton architecture to a multi-deployme - Remove the [proxy](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L545) from OPCM. - Remove [initialize](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L210) functionality from OPCM and introduce standard constructor initialization. -- Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM deployment e.g. OPCM address `0x1234...` deploys `op-contracts/v1.6.0`. +- Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM deployment e.g. `string constant l1ContractsVersion = "op-contracts/v1.6.0";` or something more nuanced that shows the relationship between the version string and the [standard release implementation addresses](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-mainnet.toml#L9). - Update `op-deployer`, `DeploySuperchain.s.sol`, `DeployImplementations.s.sol` and `DeployOPChain.s.sol` to work with the new multi-deployment paradigm of one OPCM per L1 smart contract release. -- **Optional**: Add authentication to OPCM in anticipation for upgrade features. # Problem Statement + Context @@ -25,10 +24,6 @@ OPCM will transition from its current singleton architecture to a multi-deployme ## Example of Unwanted Complexity in op-deployer - Each `op-deployer` releases currently bundles standard version TOML files from the superchain-registry. These files contain the addresses corresponding to each L1 smart contract release. Developers must [manually sync](https://github.com/ethereum-optimism/optimism/blob/bc9b6cd588588c9c4167c926a1782c658e5df921/op-chain-ops/Makefile#L50-L52) the TOML files before cutting a new release. Since these release addresses are tightly coupled to op-deployer, they need to be injected into OPCM. Without this injection, OPCM is unaware of the implementation addresses of any L1 smart contract releases. A system in which OPCM is 'release aware' simplifies the logic within op-deployer. In this setup, op-deployer would maintain a list of OPCM addresses and manage interactions with each address on a case-by-case basis. -## Authentication (Optional) - -Authentication was not originally implemented in OPCM because it solely supported deployments, with the rationale being that there was no immediate need to restrict access to the deploy function. However, with the introduction of upgrade functionality, it’s essential to establish a robust authentication mechanism within OPCM. We now need to determine appropriate access controls and define roles for authorized users who will be permitted to perform upgrades. We can choose to implement this now to prepare for future use in OPCM upgrade features, or we may decide to postpone it until a later stage. - # Alternatives Considered Continue with the approach of adding additional conditional logic for every new chain version that is released. As noted, this leads to a system that is complex and hard to maintain. @@ -64,16 +59,6 @@ Now that each OPCM deploy is going to be tethered directly to an L1 smart contra This creates a linked list whereby a user can find all prior OPCMs starting from the current OPCM contract. This will prove useful for implementing upgrade functionality because with this information an OPCM can easily expose the version of L1 smart contracts that it supports upgrading **from** and **to**. -## Authentication (Optional) - -As we know that upgrades are coming to OPCM we can preemtively add authentication to OPCM as part of this architecture redesign. - -It is our intention to keep the OPCM [deploy](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L226) function permissionless. - -- `//TODO Determine WHO should perform these upgrades` -- `//TODO Determine HOW these access controls should be implemented in OPCM` - - # Risks & Uncertainties With more OPCM versions, we’ll need to write additional production Solidity code. While our engineering practices help minimize bugs, it is still worth considering whether increasing the surface area of onchain interactions is desirable. From f35db7771a1155c4f484d2dfdee727bc68ea6cd7 Mon Sep 17 00:00:00 2001 From: blaine Date: Wed, 6 Nov 2024 15:14:17 -0500 Subject: [PATCH 13/18] Update protocol/op-contracts-manager-single-release-redesign.md Co-authored-by: Maurelian --- protocol/op-contracts-manager-single-release-redesign.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index fa47c8f1..73a5dc2e 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -2,7 +2,7 @@ The original OPContractsManager (OPCM) design, outlined [here](./op-contracts-manager-arch.md), defined a singleton proxied contract that deployed the L1 contracts for standard OP Stack chains in a single transaction. -Implementing upgrade functionality for OP Stack chains via OPCM is now a key goal. As we approach this feature, we've identified several interim adjustments to OPCM that will that will not only enable future upgradability but also simplify its overall design. Therefore, the purpose of this design document is to streamline OPCM’s architecture, making it easier to build and integrate upgradability features. +Implementing upgrade functionality for OP Stack chains via OPCM is now a key goal. As we approach this feature, we've identified several interim adjustments to OPCM that will not only enable future upgradability but also simplify its overall design. Therefore, the purpose of this design document is to streamline OPCM’s architecture, making it easier to build and integrate upgradability features. # Summary From 2011fb5d2c4fa482ecee2127d59376465129142d Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Wed, 6 Nov 2024 15:49:35 -0500 Subject: [PATCH 14/18] fix: pr comments. --- .../op-contracts-manager-single-release-redesign.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index 73a5dc2e..4cecb946 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -10,7 +10,7 @@ OPCM will transition from its current singleton architecture to a multi-deployme - Remove the [proxy](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L545) from OPCM. - Remove [initialize](https://github.com/ethereum-optimism/optimism/blob/28283a927e3124fa0b2cf8d47d1a734e95478215/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L210) functionality from OPCM and introduce standard constructor initialization. -- Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM deployment e.g. `string constant l1ContractsVersion = "op-contracts/v1.6.0";` or something more nuanced that shows the relationship between the version string and the [standard release implementation addresses](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-mainnet.toml#L9). +- Add versioning to OPCM to expose which L1 contracts are deployed for the specific OPCM deployment e.g. `string constant l1ContractsVersion = "op-contracts/v1.6.0";` or something more nuanced that shows the relationship between the version string and the [standard release implementation addresses](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-mainnet.toml#L9). This versioning is in addition to the [existing semvers](https://github.com/ethereum-optimism/optimism/blob/feat/isthmus-contracts/packages/contracts-bedrock/src/L1/OPContractsManager.sol#L133-L134) that exist on OPCM contracts today. - Update `op-deployer`, `DeploySuperchain.s.sol`, `DeployImplementations.s.sol` and `DeployOPChain.s.sol` to work with the new multi-deployment paradigm of one OPCM per L1 smart contract release. @@ -50,6 +50,8 @@ flowchart LR C[Any Account] -->|call| D[OPCM - op-contracts/v1.6.0] ``` +In the event that we deploy a buggy OPCM and need to provide a patch fix, we can simply deploy a new OPCM contract. The new contract will explicitly include the address of the contract it replaces, e.g. `address replaces = `. By doing this we can easily tell which OPCM contract is the latest version to use by process of elimination. + ## Versioning Now that each OPCM deploy is going to be tethered directly to an L1 smart contract release version, for improved UX, we should provide public getters to expose two pieces of information: @@ -61,7 +63,14 @@ This creates a linked list whereby a user can find all prior OPCMs starting from # Risks & Uncertainties -With more OPCM versions, we’ll need to write additional production Solidity code. While our engineering practices help minimize bugs, it is still worth considering whether increasing the surface area of onchain interactions is desirable. +## Further Commitment To Moving Logic On-Chain +Regardless of whether we continue with the singleton OPCM approach or adopt a different strategy, more Solidity production code will be necessary. While our engineering practices help minimize bugs, it is still worth considering whether increasing the surface area of on-chain interactions is desirable. + +## Documentation +Having multiple implementations of OPCM that exist in parallel will mean that tacking and documenting them is even more important. Keeping documentation up to date will be paramount in ensuring our customers have the best experience using these tools. + +## Superchain-Registry +If an OPCM release is approved by governance, any deployments made from this address can be considered trustworthy. One side effect of this is that certain superchain-registry checks may no longer be necessary. The full scope of superchain-registry changes is currently unknown. [^1]: *To view all official L1 smart releases, run `git tag -l | grep op-contracts` on the `develop` branch inside the [monorepo](https://github.com/ethereum-optimism/optimism).* \ No newline at end of file From 2a03b8c8532a4d5d15058a5bd0bc62b8c60f4244 Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Wed, 6 Nov 2024 16:00:07 -0500 Subject: [PATCH 15/18] fix: nit --- protocol/op-contracts-manager-single-release-redesign.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index 4cecb946..a0fa1444 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -35,7 +35,7 @@ Continue with the approach of adding additional conditional logic for every new Having one OPCM per *L1 smart contract release version*[^1] means that we can remove the proxy pattern that currently exists with OPCM. The high level architecture changes can be seen below: ### Previous OPCM Deploys -Before OPCM was proxied so that it was upgradable. e.g. [`0x18CeC91779995AD14c880e4095456B9147160790`](https://etherscan.io/address/0x18CeC91779995AD14c880e4095456B9147160790) +Before, OPCM was proxied so that it was upgradable. e.g. [`0x18CeC91779995AD14c880e4095456B9147160790`](https://etherscan.io/address/0x18CeC91779995AD14c880e4095456B9147160790) ```mermaid flowchart LR A[Any Account] -->|call| C[Proxy] @@ -43,7 +43,7 @@ flowchart LR ``` ### New OPCM Deploys -Now OPCM is not proxied and therefore not upgradable. This is by design though as we want to release a new OPCM for each new L1 smart contract release. +Now, OPCM is not proxied and therefore not upgradable. This is by design though as we want to release a new OPCM for each new L1 smart contract release. ```mermaid flowchart LR A[Any Account] -->|call| B[OPCM - op-contracts/v1.3.0] From 7f50c4f7bd700be7d8664306acc31885d2cb71c3 Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Thu, 7 Nov 2024 09:20:53 -0500 Subject: [PATCH 16/18] fix: alternative versioning condsidered. --- .../op-contracts-manager-single-release-redesign.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index a0fa1444..2ca2a36a 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -28,6 +28,18 @@ OPCM will transition from its current singleton architecture to a multi-deployme Continue with the approach of adding additional conditional logic for every new chain version that is released. As noted, this leads to a system that is complex and hard to maintain. +## Alternative Versioning + +With every official L1 smart contract release[^1], OPCM will need to be deployed. This is necessary because we **must** provide users with a way to deploy the new release and, in the future, upgrade from the prior release. The relationship where OPCM has a new version for each deployment means that the traditional semantic version used by Optimism contracts will be the same as the L1 smart contract release version. To prevent introducing cognitive overhead for developers, we will maintain separate versioning, even if they technically represent the same information. An example of how this might appear is provided below. + +```solidity +/// @custom:semver 3.1.0 +string public constant version = "3.1.0"; // <-- normal semver consistent with all out smart contracts + +// @notice L1 smart contracts release deployed by this version of OPCM. +string constant l1ContractsVersion = "op-contracts/v3.1.0"; // <-- opcm specific +``` + # Proposed Solution ## OPCM Architecture Changes From e0c9d70d83dd5fee34de5c12940b169794b68b9c Mon Sep 17 00:00:00 2001 From: blaine Date: Thu, 7 Nov 2024 09:21:53 -0500 Subject: [PATCH 17/18] Update op-contracts-manager-single-release-redesign.md --- protocol/op-contracts-manager-single-release-redesign.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index 2ca2a36a..a3736a7f 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -34,7 +34,7 @@ With every official L1 smart contract release[^1], OPCM will need to be deployed ```solidity /// @custom:semver 3.1.0 -string public constant version = "3.1.0"; // <-- normal semver consistent with all out smart contracts +string public constant version = "3.1.0"; // <-- normal semver consistent with all Optimism smart contracts // @notice L1 smart contracts release deployed by this version of OPCM. string constant l1ContractsVersion = "op-contracts/v3.1.0"; // <-- opcm specific @@ -85,4 +85,4 @@ Having multiple implementations of OPCM that exist in parallel will mean that ta If an OPCM release is approved by governance, any deployments made from this address can be considered trustworthy. One side effect of this is that certain superchain-registry checks may no longer be necessary. The full scope of superchain-registry changes is currently unknown. -[^1]: *To view all official L1 smart releases, run `git tag -l | grep op-contracts` on the `develop` branch inside the [monorepo](https://github.com/ethereum-optimism/optimism).* \ No newline at end of file +[^1]: *To view all official L1 smart releases, run `git tag -l | grep op-contracts` on the `develop` branch inside the [monorepo](https://github.com/ethereum-optimism/optimism).* From 5ee9be2e4d2301af2358a061883bc7f2ce84085f Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Thu, 7 Nov 2024 16:03:59 -0500 Subject: [PATCH 18/18] fix: design doc review ammendments. --- ...contracts-manager-single-release-redesign.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/protocol/op-contracts-manager-single-release-redesign.md b/protocol/op-contracts-manager-single-release-redesign.md index a3736a7f..0f52fc8c 100644 --- a/protocol/op-contracts-manager-single-release-redesign.md +++ b/protocol/op-contracts-manager-single-release-redesign.md @@ -62,16 +62,25 @@ flowchart LR C[Any Account] -->|call| D[OPCM - op-contracts/v1.6.0] ``` -In the event that we deploy a buggy OPCM and need to provide a patch fix, we can simply deploy a new OPCM contract. The new contract will explicitly include the address of the contract it replaces, e.g. `address replaces = `. By doing this we can easily tell which OPCM contract is the latest version to use by process of elimination. +### Managing Patches for OPCM Deployments + +In the event that we deploy a buggy OPCM and need to provide a patch fix, we can simply deploy a new OPCM contract. The canonical list of OPCM contracts will be maintained off-chain, most likely in the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry). +A hypothetical example of a scenario where a patch fix for an older OPCM is needed could be one where the upgrade functionality works for all chains except one, for whatever reason. In this case, we will need to fix the upgrade function. + +``` +opcm (op-contracts/v1.6.0) // Stable version. +opcm (op-contracts/v1.7.0) // Buggy and needs to be patched. This version is superseded by opcm (op-contracts/v1.7.1). + opcm (op-contracts/v1.7.1) // Patched version. +opcm (op-contracts/v1.8.0) // Next stable release. +``` ## Versioning Now that each OPCM deploy is going to be tethered directly to an L1 smart contract release version, for improved UX, we should provide public getters to expose two pieces of information: -1. The **current L1 smart contracts** that are deployed via this version of OPCM e.g. `op-contracts/v1.6.0`. This means we will no longer need to pass the standard versions toml [file](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L61) around like [this](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L1060). The implementation addresses can be added to the OPCM contract as as immutable values. -2. The **address of the previous OPCM** contract. +1. The **current L1 smart contracts release version** that are deployed via this version of OPCM e.g. `op-contracts/v1.6.0`. This means we will no longer need to pass the standard versions toml [file](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L61) around like [this](https://github.com/ethereum-optimism/optimism/blob/4c015e3a36f8910e2cf8b447d62ab4c44b944cca/packages/contracts-bedrock/scripts/deploy/DeployImplementations.s.sol#L1060). The implementation addresses can be added to the OPCM contract as as immutable values. -This creates a linked list whereby a user can find all prior OPCMs starting from the current OPCM contract. This will prove useful for implementing upgrade functionality because with this information an OPCM can easily expose the version of L1 smart contracts that it supports upgrading **from** and **to**. +We do not include references to previous OPCM versions or L1 smart contract releases, as this would introduce complexity if [patches](#managing-patches-for-opcm-deployments) need to be applied to older versions. # Risks & Uncertainties