refactor(L1): merge SuperchainConfig into SystemConfig by jackchuma · Pull Request #432 · base/contracts

jackchuma · 2026-09-08T14:26:27Z

What changed? Why?

Merged the chain-local SuperchainConfig into SystemConfig, so SystemConfig now owns the Guardian and Incident Responder roles and the system-wide pause state. This removes the separate SuperchainConfig implementation, proxy, shared ProxyAdmin, and deployment/upgrade stage, while removing an indirection from pause checks.

The deployment config keys are renamed from superchainConfigGuardian and superchainConfigIncidentResponder to guardian and incidentResponder; the values now construct SystemConfig directly.

Notes to reviewers

This is a breaking ABI change. SystemConfig.initialize no longer accepts _superchainConfig; its constructor now accepts the Guardian and Incident Responder. superchainConfig() and the related passthrough getters on pausable contracts are removed, so consumers read pause state and roles from SystemConfig.
The old superchainConfig storage slot remains as a spacer to preserve layout, and pauseTimestamp is appended at slot 110. SystemConfig and the affected pausable contracts receive major-version changes.
OptimismPortal2 goes to 7.0.0 rather than 6.0.0. #438 took the portal to 6.0.0 on main for the ETHLockbox removal while this branch had independently taken it to 6.0.0 for dropping superchainConfig(), so after merging main the two differing ABIs would otherwise both declare 6.0.0.
Because the Guardian and Incident Responder are constructor immutables, SystemDeploy.deploy now rejects a supplied systemConfigImpl whose roles do not match the deploy input. Previously those inputs were read only when the script built the implementations itself, so a prebuilt implementation silently installed its own pause authorities.
Before migrating an existing system, SystemDeploy verifies that the legacy global and OptimismPortal pause records are clear, including expired pause records. A pause can still be submitted after that check and before the upgrade, and either the Guardian or the Incident Responder can submit it, so upgrades must be coordinated with both.

How has it been tested?

Ported pause, unpause, extend, expiration, role, and pause-expiry coverage from SuperchainConfig.t.sol to SystemConfig.t.sol.
Added deployment coverage for Guardian/Incident Responder constructor values and upgrade coverage that rejects legacy global and chain-specific pause records.
Added deployment coverage rejecting supplied SystemConfig implementations that carry the wrong Guardian, the wrong Incident Responder, or no Guardian at all.
Full suite: 1216 passed, 0 failed, 1 skipped. just lint-check, just snapshots, and the semver-lock diff check pass.

SuperchainConfig held the pause state and the Guardian/Incident Responder roles for a single chain, while every pausable contract reached it by hopping through SystemConfig. Collapsing the two removes a proxy, a shared ProxyAdmin, and an indirection from every `paused()` read. SystemConfig now owns: - `GUARDIAN` / `INCIDENT_RESPONDER` immutables, set via the constructor. - `pauseTimestamps` and the `pause`/`unpause`/`extend` API. - `paused(address)`, `pausable`, `expiration`, and `pauseExpiry` views. The former `superchainConfig` storage slot becomes `spacer_108_0_20` so existing deployments keep their layout, and `pauseTimestamps` is appended. Callers lose their `superchainConfig()` passthroughs (`config()` on DelayedWETH) and read pause state straight off SystemConfig, so their ABIs change and they take major version bumps. `initialize` also drops its `_superchainConfig` argument. Deploy tooling drops the whole superchain stage: no SuperchainConfig implementation, proxy, or dedicated ProxyAdmin, and no separate upgrade step for the shared proxy. The `superchainConfigGuardian` and `superchainConfigIncidentResponder` deploy-config keys are renamed to `guardian` and `incidentResponder` and now feed the SystemConfig constructor. Pause coverage from SuperchainConfig.t.sol moves into SystemConfig.t.sol. Co-authored-by: Cursor <cursoragent@cursor.com>

linear · 2026-09-08T14:26:31Z

CHAIN-4914

cb-heimdall · 2026-09-08T14:26:31Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 0

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

Co-authored-by: Codex <codex-noreply@coinbase.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Codex <codex-noreply@coinbase.com>

…merge-superchainconfig-into-systemconfig Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # snapshots/semver-lock.json # src/L1/SystemConfig.sol # test/deploy/SystemDeploy.t.sol

leopoldjoy · 2026-09-17T12:43:30Z

+    /// @notice Rejects a migration from SuperchainConfig until its global and chain-specific pause records are cleared.
+    /// @dev A pause submitted after this check and before the upgrade can be lost; coordinate migrations with
+    /// guardians.
+    function _assertLegacySuperchainConfigNotPaused(ISystemConfig _systemConfigProxy) internal view {


Please update the PR description and this migration warning to say that upgrades must be coordinated with both the Guardian and Incident Responder, since either role can pause during this window.

leopoldjoy · 2026-09-17T12:43:30Z

-        DeployUtils.assertValidContractAddress(_impls.superchainConfigImpl);
        DeployUtils.assertValidContractAddress(_impls.l1ERC721BridgeImpl);
        DeployUtils.assertValidContractAddress(_impls.optimismPortalImpl);
        DeployUtils.assertValidContractAddress(_impls.systemConfigImpl);


Please validate the SystemConfig implementation’s immutable Guardian and Incident Responder against the expected roles before deploying or upgrading, otherwise a stale or supplied implementation can install incorrect pause authorities.

leopoldjoy · 2026-09-17T12:43:30Z


-    /// @notice Returns the SuperchainConfig contract.
-    /// @return ISuperchainConfig The SuperchainConfig contract.
-    function superchainConfig() external view returns (ISuperchainConfig) {


Removing superchainConfig() is a breaking ABI change, so OptimismPortal2 should receive a major version bump like the other affected contracts.

leopoldjoy · 2026-09-17T12:43:30Z

        assertEq(address(l1ERC721Bridge.otherBridge()), Predeploys.L2_ERC721_BRIDGE);
        assertEq(address(l1ERC721Bridge.systemConfig()), address(systemConfig));
-        assertEq(address(l1ERC721Bridge.superchainConfig()), address(systemConfig.superchainConfig()));
+        assertEq(address(l1ERC721Bridge.systemConfig()), address(systemConfig));


Please remove this duplicate SystemConfig assertion; the same redundant replacement also appears in L1StandardBridge.t.sol and DelayedWETH.t.sol.

main bumped OptimismPortal2 5.2.0 -> 6.0.0 in #438 for the ETHLockbox removal, and this branch independently bumped 5.2.0 -> 6.0.0 for dropping `superchainConfig()`. After merging main both ABIs declare 6.0.0 while differing by that getter, which is the same divergence #438 and #440 set out to remove. Major rather than minor: the removal is a breaking ABI change, matching the reason Co-authored-by: Cursor <cursoragent@cursor.com> #438 took the portal major in the first place.

Porting the `superchainConfig()` assertions onto `systemConfig()` left three getter tests asserting the same address twice in a row. Co-authored-by: Cursor <cursoragent@cursor.com>

The Guardian and Incident Responder are now constructor immutables on the SystemConfig implementation, so when `deploy` is handed a prebuilt implementation set it never reads `implementationsInput.guardian` or `.incidentResponder` at all. A stale implementation therefore installs its own pause authorities and the deploy input silently has no effect. Require a supplied implementation to carry the configured roles, and apply the same non-zero Guardian check that freshly deployed implementations already get, so a chain cannot deploy with nobody able to unpause it. Co-authored-by: Cursor <cursoragent@cursor.com>

Legacy `SuperchainConfig.pause` is gated on `_assertOnlyGuardianOrIncidentResponder`, so the Incident Responder can also open a pause in the window between the check and the upgrade. Co-authored-by: Cursor <cursoragent@cursor.com>

A `just snapshots-check-no-build` run after the test-profile build rewrote the ProtocolVersions and TEEProverRegistry initCodeHashes from those artifacts, and they were committed alongside the OptimismPortal2 bump. Regenerated with `just semver-lock`, which force-builds the source graph first. Co-authored-by: Cursor <cursoragent@cursor.com>

jackchuma and others added 5 commits September 8, 2026 15:51

fix(L1): preserve pause state during upgrade

f2c1c5c

Co-authored-by: Codex <codex-noreply@coinbase.com>

fix(L1): preserve legacy pause records during migration

b3bf1dc

Co-authored-by: Codex <codex-noreply@coinbase.com>

chore(L1): refresh SystemConfig semver-lock hash

daada0f

Co-authored-by: Cursor <cursoragent@cursor.com>

docs(L1): document legacy pause migration risk

8c9f1a2

Co-authored-by: Codex <codex-noreply@coinbase.com>

Merge remote-tracking branch 'origin/main' into jackchuma/chain-4914-…

47de7d2

…merge-superchainconfig-into-systemconfig Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # snapshots/semver-lock.json # src/L1/SystemConfig.sol # test/deploy/SystemDeploy.t.sol

leopoldjoy reviewed Sep 17, 2026

View reviewed changes

jackchuma and others added 5 commits September 17, 2026 11:13

test(L1): drop duplicated systemConfig assertions

a487d75

Porting the `superchainConfig()` assertions onto `systemConfig()` left three getter tests asserting the same address twice in a row. Co-authored-by: Cursor <cursoragent@cursor.com>

Navigation Menu

Uh oh!

refactor(L1): merge SuperchainConfig into SystemConfig - #432

refactor(L1): merge SuperchainConfig into SystemConfig#432
jackchuma wants to merge 11 commits into
mainfrom
jackchuma/chain-4914-merge-superchainconfig-into-systemconfig

jackchuma commented Sep 8, 2026 •

edited

Loading

Uh oh!

linear Bot commented Sep 8, 2026

Uh oh!

cb-heimdall commented Sep 8, 2026

Uh oh!

leopoldjoy Sep 17, 2026

Uh oh!

leopoldjoy Sep 17, 2026

Uh oh!

leopoldjoy Sep 17, 2026

Uh oh!

leopoldjoy Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

jackchuma commented Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed? Why?

Notes to reviewers

How has it been tested?

Uh oh!

linear Bot commented Sep 8, 2026

Uh oh!

cb-heimdall commented Sep 8, 2026

🟡 Heimdall Review Status

Uh oh!

leopoldjoy Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

leopoldjoy Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

leopoldjoy Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

leopoldjoy Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jackchuma commented Sep 8, 2026 •

edited

Loading