feat: OPCM v2 design doc #353

smartcontracts · 2025-11-06T22:22:30Z

This PR adds the design document for OPCM v2.

mds1 · 2025-11-11T21:45:35Z

protocol/opcm-v2.md

+struct GameConfig {
+    GameType gameType;
+    address implementation;
+    bytes32 prestate;
+}


Since proofs contracts are now MCP-compatible, won't there be a 1:1 mapping between game type and implementation address, so we can remove the implementation arg?

Yes, correct

mds1 · 2025-11-11T21:51:26Z

protocol/opcm-v2.md

+- **Add game types**: Implicit in `upgrade()` with modified games array
+- **Update prestates**: Implicit in `upgrade()` with modified games array


What do you think about preserving addGameType and updatePrestates as convenience functions? We often want to do just those actions (e.g. changing prestate for a hard fork) and it feels error prone and hard to review to pass a full Config into upgrade for that. These convenience functions would just gather the other inputs before calling upgrade

upgrade() already takes very minimal inputs, so this is already considered

mds1 · 2025-11-11T21:53:16Z

protocol/opcm-v2.md

+**Mitigation**: 
+- Comprehensive security audit with focus on the new flexible interfaces
+- Defensive coding practices throughout implementation
+- State diff review for the first OPCM v2 upgrade to verify correctness


Who needs to do state diff review—all signers, or just the devs creating the superchain-ops task?

Maybe just the devs creating the superchain ops task, the first time?

mds1 · 2025-11-11T21:53:50Z

protocol/opcm-v2.md

+**Mitigation**:
+- Ensure all existing OPCM v1 tests pass with v2 implementation
+- Comprehensive test coverage mapping v1 functionality to v2
+- Review session with all customer teams to validate their use cases are covered


I feel like an easy way to mitigate this is by not changing any external function signatures until the very end

protocol/opcm-v2.md

ajsutton · 2025-11-12T00:07:49Z

protocol/opcm-v2.md

+- Solidity function signatures/ABIs are the source of truth
+- Go code for constructing function calls is automatically generated


How do we plan to do this generation? We've been trying to move away from the Geth codegen tool because it creates some pretty awful code and is quite limiting in how you can actually make calls.

We've also seen issues where the struct definition is updated but the new fields aren't actually populated. We have some static analysis for this in op-deployer now but worth thinking about how we can ensure we get compiler errors if things are out of sync (including verifying the code was regenerated when required).

protocol/opcm-v2.md

ajsutton · 2025-11-12T00:11:54Z

protocol/opcm-v2.md

+- **Upgrades**: Only a subset of configuration is provided in the upgrade input; the remaining configuration is gathered automatically from the existing deployed contracts
+
+This asymmetry allows upgrades to specify only what changes, while deployments must provide complete configuration.


How is this expressed in code? How do you know what you need to provide when calling upgrade? The ABIs above pass the same Config object to both deploy and upgrade so it seems unclear how to know if an upgrade requires a new setting be specified or not.

Going to fix the ABIs here to be more explicit

Fixed, can you take another look?

I think what's confusing me is lines 83 and 84 have deploy(Config) and upgrade(Config) which makes it look like they take the same inputs. In which case, how do you know which parts of that Config are required to be specified for the upgrade being done?

https://github.com/ethereum-optimism/design-docs/pull/353/files/1acc722cdf458c0744e166c0c37443a4a8b3f3b4#diff-62c8771657b68fe38ae394ef3d255c7928c0b7853b0077ca70ff62007de8beeeR83

But maybe I'm looking at the wrong place for the ABI you updated.

ajsutton · 2025-11-12T00:15:06Z

protocol/opcm-v2.md

+- **Deploy new chains**: `deploy()` function
+- **Upgrade existing chains**: `upgrade()` function  
+- **Dynamic game types**: GameConfig array in Config struct
+- **Add game types**: Implicit in `upgrade()` with modified games array


Note that there isn't a way to iterate through the list of set dispute game implementations (it's a map). Apart from migrating to interop, OPCM doesn't support removing game types, but it's worth noting that upgrade won't remove existing game types if they aren't in the games array. That feels a little more surprising with this ABI but I don't think it's unreasonable.

You can remove games by directly calling DisputeGameFactory.setImplementation and setting a 0x00 implementation address.

Actually the same thing applies to any maps set as part of initialize methods. That could open up some foot guns because map entries get left around after an upgrade and we don't have a way to specify that they should be removed.

From discussion: For game types, we have a fixed list that is supported so they can just be removed upfront and then re-add what is specified to make this work.

For the generic case we should ensure that initialisers only set simple fields and don't write to maps so they are safe to call repeatedly.

Note that there isn't a way to iterate through the list of set dispute game implementations (it's a map).

We should consider changing that mapping into an enumerable set so that it becomes iterable, we've found this structure to be quite useful elsewhere.

mslipper · 2025-11-12T12:56:26Z

protocol/opcm-v2.md

+    bytes32 prestate;
+}
+
+struct Config {


If we add a new field/change an existing field on the Config struct, won't we still have to update OP Deployer to plumb that field through the intent and into the OPCM? Is the idea that the codegen would make this process easier?

Yes, we would still have to update op-deployer no matter what. Idea is to codegen this, yep.

mslipper · 2025-11-12T12:57:17Z

protocol/opcm-v2.md

+Required reviewers:
+- **Proofs team representative**: Primary stakeholder for interface flexibility requirements
+- **Protocol team lead**: For overall architectural alignment
+- **EVM Safety team representative**: For security and safety validation


We need somebody from platforms as well to make sure it'll integrate well with deployer.

mslipper · 2025-11-12T12:58:00Z

protocol/opcm-v2.md

+### Architecture Overview
+
+OPCM v2 consolidates the 5 separate functions of v1 into 2 primary functions:
+- `deploy(Config memory config)`: Deploys a new OP Stack chain


Does this include deploying blueprints?

I'd expect that Blueprints will still be deployed in DeployImplementations.

I'd expect that Blueprints will still be deployed in DeployImplementations.

Correct

mslipper · 2025-11-12T12:59:01Z

protocol/opcm-v2.md

+
+**Phase 1: Chain World Assembly (Load-or-Deploy Pattern)**
+
+Both functions begin by gathering the complete set of contracts for the chain—the "chain world"—which includes SystemConfig, OptimismPortal, AnchorStateRegistry, and all other chain contracts.


Does this include the Superchain contracts? How do we upgrade those?

good callout. The doc mentions 5 functions (deploy(), upgrade(), addGameType(), updatePrestate(), interopMigrate()), but there is now also upgradeSuperchainConfig().

Good callout, we are maintaining a separate upgradeSuperchain function too

mslipper · 2025-11-12T16:01:45Z

One other thing - what's the rollout plan here? Would love for us to validate that this solves the Proofs team's problems as early as possible.

maurelian · 2025-11-14T15:21:03Z

protocol/opcm-v2.md

+
+### Implementation Flow
+
+Both `deploy()` and `upgrade()` follow a unified three-phase flow:


Does upgrade() now operate on a single chain or do they still accept an array as input?

IIRC from the prototype it's a single chain, which makes sense in order to make deploy() and upgrade() consistent. We can always do the loop using multicall.

upgrade() operates on a single chain, you can loop via multicall

What is the rationale for this change? @maurelian do you recall the original rationale for accepting an array?

I figured there wasn't any real benefit to an input with an array vs just calling the function multiple times in the same txn. If someone has an obvious reason why an array is valuable, happy to consider.

maurelian · 2025-11-14T15:23:53Z

protocol/opcm-v2.md

+
+Generate the Go glue code between OPCM and op-deployer from Solidity interfaces:
+- Solidity function signatures/ABIs are the source of truth
+- Go code for constructing function calls is automatically generated


Will this enable us to get rid of the Solidity scripts in scripts/deploy?

Many of them, yes

maurelian · 2025-11-14T15:26:33Z

protocol/opcm-v2.md

+
+Both functions begin by gathering the complete set of contracts for the chain—the "chain world"—which includes SystemConfig, OptimismPortal, AnchorStateRegistry, and all other chain contracts.
+
+The load-or-deploy pattern attempts to load each contract address from an expected source (e.g., a known deployment address for upgrades, or a predictable location). If the contract cannot be found at the expected location, it is deployed instead. This unified pattern means the same chain world loading function serves both deploy and upgrade operations.


If the contract cannot be found at the expected location, it is deployed instead.

It feels odd to just casually say "if the contract cannot be found". ie. If a system is already deployed, then all the contracts should exist, and having one not exist would be a very strange thing. Is this meant to imply a situation where a net-new contract is being added during an upgrade?

Yes, meant to imply a net-new contract being added during an upgrade

maurelian · 2025-11-14T15:33:24Z

protocol/opcm-v2.md

+
+### Constraints
+
+- Must integrate with existing op-deployer Go tooling


Are we aiming to maintain the existing op-deployer cli interface here? If we are planning to break anything here, we should consult with users to see what hardcoded invocations they might have in scripts and how easily they can update them.

We are aiming to maintain the existing interface for now, but then deprecate that interface in favor of a simpler one

maurelian · 2025-11-14T15:38:17Z

protocol/opcm-v2.md

+**Risk**: We might inadvertently miss some existing functionality that OPCM v1 provides when transitioning to the new 2-function interface.
+
+**Mitigation**:
+- Ensure all existing OPCM v1 tests pass with v2 implementation


Are we planning to use the 'strangler pattern' here, so that both OPCMs exist and are tested in parallel during development of V2? This was used successfully when migrating the deploy scripts to the new pattern without the I/O contracts.

Yep, we are doing that

maurelian · 2025-11-14T15:39:33Z

protocol/opcm-v2.md

+
+1. **Alternative designs**: Are there alternative architectural approaches we may have missed that would better solve these problems?
+
+2. **Shipping timeline**: When should we ship this? Is U18 (upgrade 18) the target, or should it be later?


U18 is going to audit with the enabling changes, but it seems unlikely to me that OPCM v2 itself will be ready at the same time as other keystone features that justify releasing U18.

Agree, we will probably aim for U19

bitwiseguy · 2025-11-17T14:41:20Z

protocol/opcm-v2.md

+
+**Rejection rationale**: The core OPCM design is good. We don't want to replace it; we want to improve specific aspects. A complete redesign would be throwing out the baby with the bathwater. The v2 approach preserves what works while fixing what doesn't.
+
+## Risks and Uncertainties


Per-tx gas usage is called out above, but might want to add a risk/uncertainty for gas usage in upgrade() and deploy() txs unless we've already measured the new versions of those functions. For example, would be good to determine if there is a limit on number of dispute games that can be deployed in a single upgrade() or deploy() tx before it reaches the 16.77Mgas/tx fusaka limit. Any other config/operations that should be limited to ensure fusaka-compatibility?

We have a test in place to make sure we remain below the Fusaka limit!

smartcontracts added 2 commits November 6, 2025 17:11

feat: OPCM v2 design doc

4c603a4

This PR adds the design document for OPCM v2.

feat: explain implementation flow

1acc722

mds1 reviewed Nov 11, 2025

View reviewed changes

ajsutton reviewed Nov 12, 2025

View reviewed changes

mslipper reviewed Nov 12, 2025

View reviewed changes

maurelian reviewed Nov 14, 2025

View reviewed changes

bitwiseguy reviewed Nov 17, 2025

View reviewed changes

fix: pr feedback

b4d849a

smartcontracts mentioned this pull request Nov 18, 2025

feat: OPCM v2 ethereum-optimism/optimism#18079

Open

		- Add game types: Implicit in `upgrade()` with modified games array
		- Update prestates: Implicit in `upgrade()` with modified games array

		- Solidity function signatures/ABIs are the source of truth
		- Go code for constructing function calls is automatically generated

		- Upgrades: Only a subset of configuration is provided in the upgrade input; the remaining configuration is gathered automatically from the existing deployed contracts

		This asymmetry allows upgrades to specify only what changes, while deployments must provide complete configuration.


		Phase 1: Chain World Assembly (Load-or-Deploy Pattern)

		Both functions begin by gathering the complete set of contracts for the chain—the "chain world"—which includes SystemConfig, OptimismPortal, AnchorStateRegistry, and all other chain contracts.


		### Implementation Flow

		Both `deploy()` and `upgrade()` follow a unified three-phase flow:


		Both functions begin by gathering the complete set of contracts for the chain—the "chain world"—which includes SystemConfig, OptimismPortal, AnchorStateRegistry, and all other chain contracts.

		The load-or-deploy pattern attempts to load each contract address from an expected source (e.g., a known deployment address for upgrades, or a predictable location). If the contract cannot be found at the expected location, it is deployed instead. This unified pattern means the same chain world loading function serves both deploy and upgrade operations.


		### Constraints

		- Must integrate with existing op-deployer Go tooling


		1. Alternative designs: Are there alternative architectural approaches we may have missed that would better solve these problems?

		2. Shipping timeline: When should we ship this? Is U18 (upgrade 18) the target, or should it be later?


		Rejection rationale: The core OPCM design is good. We don't want to replace it; we want to improve specific aspects. A complete redesign would be throwing out the baby with the bathwater. The v2 approach preserves what works while fixing what doesn't.

		## Risks and Uncertainties

feat: OPCM v2 design doc #353

Are you sure you want to change the base?

feat: OPCM v2 design doc #353

Uh oh!

Conversation

smartcontracts commented Nov 6, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maurelian Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mslipper commented Nov 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maurelian Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

maurelian Nov 14, 2025 •

edited

Loading

maurelian Nov 14, 2025 •

edited

Loading