Conversation
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.
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.
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.
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.
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.
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.
maurelian
commented
Jan 28, 2026
maurelian
commented
Jan 28, 2026
0xiamflux
reviewed
Jan 28, 2026
…ixes 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.
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.
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.
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.
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.
Makes file ordering clearer when listed alphabetically.
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
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.
maurelian
commented
Jan 29, 2026
maurelian
commented
Jan 29, 2026
maurelian
commented
Jan 29, 2026
maurelian
commented
Jan 29, 2026
maurelian
commented
Jan 29, 2026
maurelian
commented
Jan 29, 2026
maurelian
commented
Jan 29, 2026
0xiamflux
reviewed
Jan 29, 2026
0xiamflux
reviewed
Jan 29, 2026
0xiamflux
reviewed
Jan 29, 2026
Fix typos in L2 upgrade spec (everytime -> every time, consumre -> consume). Add technical terms to dictionary (NUTB, UBGL, misordered, alphanets).
geoknee
reviewed
Feb 2, 2026
geoknee
reviewed
Feb 2, 2026
maurelian
commented
Feb 2, 2026
maurelian
commented
Feb 2, 2026
maurelian
commented
Feb 2, 2026
sebastianst
reviewed
Feb 2, 2026
- 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
sebastianst
reviewed
Feb 2, 2026
…ences 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.
- 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
maurelian
commented
Feb 2, 2026
0xiamflux
reviewed
Feb 3, 2026
0xiamflux
reviewed
Feb 3, 2026
0xiamflux
reviewed
Feb 3, 2026
0xOneTony
reviewed
Feb 3, 2026
Fix typos and add requested clarifications from review comments.
Per review feedback, these should not be in the bundle.
- 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
smartcontracts
approved these changes
Feb 4, 2026
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
6 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.
No description provided.