specs: add L2 contract upgrades overview and ConditionalDeployer#876
Closed
specs: add L2 contract upgrades overview and ConditionalDeployer#876
Conversation
This was referenced Jan 27, 2026
0xOneTony
reviewed
Jan 28, 2026
| #### i03-003: Non-Reverting Collision Handling | ||
|
|
||
| When a [CREATE2 Collision](#create2-collision) is detected (contract already deployed at the target address), the | ||
| ConditionalDeployer MUST return successfully without reverting and without modifying blockchain state. |
There was a problem hiding this comment.
maybe worth mentioning what address it will return in case of collision
Contributor
Author
There was a problem hiding this comment.
Do you think it should return the deployment address? In some ways it doesn't matter since we can't actually use the return value, as it needs to be pre-computed off-chain (all we can do is inject transactions, we can't read their results).
There was a problem hiding this comment.
I think the cleaner approach would be to just not return anything, as you mention for this use case we cannot use the address anyway and returning the address in cases where no contract is deployed (because it was deployed before) feels off.
| heights while improving the development and testing process. Upgrade transactions are defined in JSON bundles that are | ||
| tracked in git, generated from Solidity scripts, and executed deterministically at fork activation. | ||
|
|
||
| ## ConditionalDeployer |
There was a problem hiding this comment.
ConditionDeployer is gonna be a periphery contract rather than a Predeploy right?
Contributor
Author
There was a problem hiding this comment.
What do you mean by periphery contract, like a pre-install?
My thoughts:
- We should also add it to the L2Genesis, as we want it available in future hardforks.
- It doesn't need to be upgradable. If we need to replace it we can just deploy a different copy of it using the same method.
maurelian
force-pushed
the
l2cm-upgrades-spec/1-conditional-deployer
branch
3 times, most recently
from
90a65b3 to
e155ba0
Compare
Adds foundational specification for L2 predeploy contract upgrades: - Overview: Describes deterministic hard fork-driven upgrade mechanism - ConditionalDeployer: Idempotent CREATE2 deployment with collision handling Includes 4 invariants, 2 assumptions, and interface definition. Part 1 of 6-part specification.
maurelian
force-pushed
the
l2cm-upgrades-spec/1-conditional-deployer
branch
from
e155ba0 to
da00e93
Compare
maurelian
added a commit
that referenced
this pull request
Jan 29, 2026
Resolves review comments from PR stack #876-881: - ConditionalDeployer: clarify return value is for off-chain use only - ConditionalDeployer: document L2Genesis deployment as preinstall - L2ProxyAdmin: clarify backwards compatibility scope excludes legacy proxies
maurelian
added a commit
that referenced
this pull request
Feb 4, 2026
* specs: add L2 contract upgrades overview and ConditionalDeployer Adds foundational specification for L2 predeploy contract upgrades: - Overview: Describes deterministic hard fork-driven upgrade mechanism - ConditionalDeployer: Idempotent CREATE2 deployment with collision handling Includes 4 invariants, 2 assumptions, and interface definition. Part 1 of 6-part specification. * specs: add L2ProxyAdmin to upgrade spec Adds L2ProxyAdmin component for batch upgrade orchestration: - Defines upgradePredeploys() function for DELEGATECALL-based batch upgrades - Exclusive Depositor Account authorization - Backwards compatibility with existing ProxyAdmin interface Includes 4 invariants, 3 assumptions, and interface definition. Part 2 of 6-part specification. * specs: add L2ContractsManager to upgrade spec Adds L2ContractsManager component for upgrade execution logic: - Configuration gathering and preservation - Deterministic upgrade execution via DELEGATECALL - Feature flag support - Atomic upgrade operations Includes 6 invariants, 4 assumptions, and interface definition. Part 3 of 6-part specification. * specs: add Network Upgrade Transaction Bundle to upgrade spec Adds NUT Bundle component defining upgrade transaction format: - JSON bundle format and structure - Deterministic bundle generation process - Bundle verification against source code - Transaction ordering and nonce sequencing Includes 6 invariants, 4 assumptions, and bundle format specification. Part 4 of 6-part specification. * specs: add Custom Upgrade Block Gas Limit to upgrade spec Adds gas allocation mechanism for upgrade transactions: - 50M gas allocation for upgrade blocks - Independent of system transaction gas limits - Deterministic allocation at fork activation - Prevents out-of-gas failures during upgrades Includes 5 invariants, 3 assumptions, and allocation specification. Part 5 of 6-part specification. * specs: add Upgrade Process to complete upgrade spec Adds end-to-end upgrade lifecycle specification: - 7-phase upgrade workflow (Development → Verification) - Transaction execution sequence at fork activation - Atomic upgrade execution - Cross-chain consistency requirements - Fork activation and verification procedures Includes 5 invariants, 3 assumptions, and complete lifecycle definition. Part 6 of 6-part specification - completes L2 contract upgrades spec. * specs: refactor L2 contract upgrades to use contract-specific ID prefixes Replaces redundant a01-001/i01-001 format with contract-specific prefixes following the OptimismPortal pattern (aOP-001, iOP-001). Changes: - ConditionalDeployer: aCD-001 through aCD-002, iCD-001 through iCD-004 - L2ProxyAdmin: aL2PA-001 through aL2PA-003, iL2PA-001 through iL2PA-004 - L2ContractsManager: aL2CM-001 through aL2CM-004, iL2CM-001 through iL2CM-006 - Network Upgrade Transaction Bundle: aNUTB-001 through aNUTB-004, iNUTB-001 through iNUTB-006 - Custom Upgrade Block Gas Limit: aUBGL-001 through aUBGL-003, iUBGL-001 through iUBGL-005 - Upgrade Process: aUP-001 through aUP-003, iUP-001 through iUP-005 Updates all cross-references and regenerates Table of Contents with new IDs. * specs: condense Impact sections in L2 contract upgrades spec Trims all Impact sections to 1-2 sentences focusing on first-order consequences rather than spelling out cascading effects. Makes the spec more concise and easier to scan while preserving critical information. * specs: split L2 contract upgrades into two files Splits the L2 contract upgrades specification into two files to reduce PR size and improve organization: 1. l2-contract-upgrades.md - Overview + 3 contract specifications - ConditionalDeployer - L2ProxyAdmin - L2ContractsManager 2. l2-upgrade-execution.md - Execution mechanism (new file) - Network Upgrade Transaction Bundle - Custom Upgrade Block Gas Limit - Upgrade Process Files cross-reference each other for definitions. This split makes it easier to review contract specifications separately from the upgrade execution process. * specs: rename and reorganize L2 upgrade specifications 1. Renames l2-contract-upgrades.md → l2-upgrades-contracts.md - Updates title: L2 Contract Upgrades → L2 Upgrade Contracts - Updates all cross-references in l2-upgrade-execution.md 2. Reorders l2-upgrade-execution.md sections for better flow - Moves Upgrade Process to beginning (after Overview) - New order: Overview → Upgrade Process → Bundle → Gas Limit - Readers now see high-level process before technical details The new naming better reflects that l2-upgrades-contracts.md contains contract specifications while l2-upgrade-execution.md covers the execution mechanism. * specs: rename execution spec to use numeric prefix Renames l2-upgrade-execution.md to l2-upgrades-1-execution.md to match the naming convention where related specs use numeric suffixes. Updates cross-references in l2-upgrades-contracts.md accordingly. * feat(specs): add numerical prefix to contract spec filename Makes file ordering clearer when listed alphabetically. * specs: address PR review feedback on L2 upgrade contracts Resolves review comments from PR stack #876-881: - ConditionalDeployer: clarify return value is for off-chain use only - ConditionalDeployer: document L2Genesis deployment as preinstall - L2ProxyAdmin: clarify backwards compatibility scope excludes legacy proxies * feat(specs): refine L2 upgrade execution specification Condense Upgrade Lifecycle to focused Upgrade Release Process section with concrete details on bundle generation, canonicalization, and client integration. Remove redundant definition and streamline assumptions/invariants based on review. * fix(specs): correct typos and update dictionary Fix typos in L2 upgrade spec (everytime -> every time, consumre -> consume). Add technical terms to dictionary (NUTB, UBGL, misordered, alphanets). * Address feedback on one-time only tx * fix(specs): address PR review feedback on L2 upgrade bundle format - Remove unnecessary metadata fields (fork, generatedAt, sourceCommit, compiler.settings) - Keep metadata.version for compatibility tracking - Remove nonce field from transactions (use sequential nonces) - Mark value field as optional (defaults to "0") - Add from field as optional (needed for zero address upgrade path) - Add assumption about transaction payload identity across chains - Clarify contract mismatch handling in verification impact - Clarify L2CM receives pre-computed addresses vs computing them * fix(specs): update bundle verification to remove metadata field references Remove references to sourceCommit and compiler settings metadata fields in the Bundle Verification Process, aligning with their removal from the bundle format in the previous commit. * formatting fixes * fix(specs): address PR review feedback on L2 upgrade process - Clarify continuous release readiness approach (no bundle copying needed) - Specify client integration uses embedded JSON (Go/Rust) - Soften testing claims to reflect current state - Add note about historical gas availability behavior * Fix transaction spec for deployed contract calldata * fix(specs): address PR review feedback - typos and clarifications Fix typos and add requested clarifications from review comments. * fix(specs): clarify one-time txs should be hardcoded in client Per review feedback, these should not be in the bundle. * Apply suggestions from code review * fix(specs): address PR review feedback - add assumptions and invariants - Add iCD-005 invariant for contract availability after ConditionalDeployer deployment - Add note about L2ContractsManager execution ordering assumption - Clarify iUP-002 that transaction payloads must be deterministically generated - Add aNUTB-001b assumption that build toolchain (forge, solc) is not compromised - Broaden aL2PA-002 to cover all malicious code, not just storage modification - Update iL2CM-004 to reflect clear-and-reinitialize pattern using StorageSetter - Update gas allocation specification to reflect dynamic value from bundle JSON * fix: wrap long lines in l2-upgrades-1-execution.md * fix: ToC
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
Adds foundational specification for L2 predeploy contract upgrades:
Includes 4 invariants, 2 assumptions, and interface definition.
Part 1 of 6-part specification.
Stack: