feat(L1): add ProtocolVersions upgrade schedule contract by PelleKrab · Pull Request #353 · base/contracts

PelleKrab · 2026-06-26T01:21:48Z

Summary

Adds ProtocolVersions, a Security Council-controlled L1 contract that
maintains an ordered registry of L2 upgrade activation timestamps and
commits to a reproducible scheduleId hash chain.

Registry: upgrades are registered by name (e.g. "canyon") with an
owner-assigned protocol version; timestamps are set/cleared separately
by the owner
chainTeam role: a secondary address (appointed/revocable by the owner)
that can only push already-scheduled activations further into the future
via delayTimestamp, it cannot register, clear, or pull timestamps earlier
scheduleId: a cumulative keccak256 chain over (l2ChainId, address, ordered keys, current timestamps).
getSchedule: single eth_call view returning the full ordered schedule
(name, timestamp, protocol version, per-entry hash) for off-chain consumers

Test plan

forge test --match-path test/L1/ProtocolVersions.t.sol passes
Confirm scheduleId reproducibility manually: compute chain from
(l2ChainId, address, ordered keys, timestamps) and compare to
scheduleId() return value
Verify delayTimestamp cannot be used to pull an activation earlier
or to schedule a fresh one
Verify setTimestamp(id, 0) correctly clears a pending timestamp and
reverts the scheduleId to the post-registration value

Add the Security Council-controlled upgrade activation schedule contract, its interface, and tests. Maintains an ordered registry of upgrades and their L2 activation timestamps, committed via scheduleId. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

@notice

…o conventions Replace the history-dependent rolling hash with a per-upgrade cumulative hash chain reproducible from (l2ChainId, address, ordered keys, current timestamps). When a timestamp changes, only the affected suffix is recomputed (O(n-j) bubble-up) rather than hashing the full state on every mutation. - Add MIN_NOTICE (1 hour) guard on setTimestamp; expose it in the interface - Require non-zero protocolVersion; use _protocolVersions as existence sentinel, removing the separate _upgradeIndex mapping - Move all errors and events into IProtocolVersions; add MIN_NOTICE to interface - Replace assembly in _keyFromUpgradeId with bytes32(raw) Solidity cast - Rename constructor params to leading-underscore convention - Restructure test file into grouped contracts with snake_case naming, external visibility, and @notice on each test function per repo style Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Returns the full ordered upgrade schedule in a single eth_call — name, activation timestamp, protocol version, and cumulative scheduleId per entry. Name is recovered from the bytes32 key at read time via _nameFromKey, avoiding a separate storage mapping. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Replace the per-call keccak256(abi.encode(l2ChainId, address(this))) in _refreshScheduleId with a cached immutable _seed set once in the constructor, saving a hash + encode on every schedule mutation. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

cb-heimdall · 2026-06-26T01:21:52Z

🟡 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 1

Sum 2

Reflects bytecode change from caching hash chain seed as immutable. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

jackchuma

I think this is a great start, however ProtocolVersions seems a bit over-engineered. How simple can we make it? We really only need:

mapping of arbitrary upgradeId bytes32 => upgrade timestamp
We could probably also include another mapping to represent the upgrade schedule as a linked list instead of an array which will simplify lookups (gnosis safes are implemented this way)
mapping of upgradeId bytes32 => scheduleId bytes32

…s control - Replace Ownable with ProxyAdminOwnedBase; drop explicit _owner constructor param and ProtocolVersions_ZeroOwner error - Replace per-upgrade protocolVersion mapping with a single latestProtocolVersion uint256 updated on each registerUpgrade call - Remove redundant storage vars: lastUpdatedAtBlock, l2ChainId immutable, _scheduleId (scheduleId() now reads the tip of _upgradeScheduleId directly) - Remove redundant view functions: upgradeCount, upgradeIdAt, upgradeIds, getProtocolVersion (getSchedule() covers all registry reads) - Inline _registerUpgrade into registerUpgrade and _applyTimestamp into setTimestamp; inline onlyChainTeam guard into delayTimestamp - Drop ScheduleIdUpdated old-scheduleId param; enforce MIN_NOTICE in delayTimestamp Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

…y pattern Replace the string-based upgrade registry (bytes32 key from packed upgradeId) with a purely numeric scheme: each upgrade gets an ascending uint256 id equal to its registration index. Human-readable names are kept off-chain; the id is permanent and stable because the registry is strictly append-only. Convert the constructor to an initializer so the contract can be deployed behind an OP proxy. _seed is now stored (not immutable) so it can be set inside initialize() against the proxy's address(this), binding the schedule commitment to the proxy address that callers interact with. Replace the mapping-based storage (_registered, _timestamps, _upgradeScheduleId keyed by bytes32) with parallel arrays indexed by id, simplifying the hash chain and eliminating the three-mapping structure. Drop getTimestamp(string) and the duplicate-registration guard; add setLatestProtocolVersion() so the informational field can be updated independently of registrations. Add LatestProtocolVersionUpdated and ScheduleIdUpdated events; update the interface to inherit IProxyAdminOwnedBase and IReinitializableBase. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Seven findings from a multi-angle review; fixes applied: * emit LatestProtocolVersionUpdated in registerUpgrade — previously only setLatestProtocolVersion fired the event, so indexers missed every version bump that came through registration. * Guard scheduleId() before initialization — returns bytes32(0) while _seed is unset, which could be picked up as a valid schedule commitment; now reverts with ProtocolVersions_NotInitialized. * Dedicate ProtocolVersions_InsufficientNotice for setTimestamp — the MIN_NOTICE check in setTimestamp reused DelayMustBeLater with current=0 as the floor, which was misleading; a new error carries only the offending timestamp. * Split delayTimestamp compound condition — the combined || condition reported current as the floor even when only the MIN_NOTICE leg fired; each constraint now reverts independently with the correct floor value. * Extract _setTimestamp internal — setTimestamp and delayTimestamp duplicated the activation-already-passed check and the write+emit+refresh triple; _setTimestamp holds those shared invariants and each public function keeps only its distinct preconditions. * Drop redundant zero-write in registerUpgrade — push(bytes32(0)) wrote zero to a slot that _refreshScheduleId immediately overwrites; replaced with push() (no argument) to save one SSTORE. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

…elper, init guard Rename latestProtocolVersion → minimumProtocolVersion throughout (state variable, event, setter, interface, tests). The field represents the minimum version nodes must run, not an informational latest; the old name implied recommendation rather than a floor. Remove the protocolVersion parameter from registerUpgrade. Upgrade registration is purely a scheduling concern (assign id, extend hash chain); the minimum version is set independently via setMinimumProtocolVersion. Drops the InvalidProtocolVersion check from registerUpgrade and removes the protocolVersion field from the UpgradeRegistered event. Extract _writeTimestamp(id, newTs) as the shared write helper for setTimestamp and delayTimestamp. Each public function owns its complete validation sequence; _writeTimestamp is a pure write (store + emit TimestampSet + refreshScheduleId). Eliminates the mixed-responsibility _setTimestamp that owned some validation but not all, which caused the ActivationAlreadyPassed check to appear in two places. Guard registerUpgrade against pre-initialization calls. _seed is zero between upgradeTo and initialize; any registerUpgrade call in that window would compute hash chain links from a zero seed, permanently desynchronizing scheduleId from its reproducible derivation (l2ChainId, address(this)). Revert with NotInitialized when _seed == 0, consistent with the existing guard in scheduleId(). Regenerate ABI, storage layout, and semver-lock snapshots. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

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

jackchuma · 2026-07-07T12:23:34Z

+        // Cannot delay an activation that has already passed.
+        if (uint64(block.timestamp) >= current) revert ProtocolVersions_ActivationAlreadyPassed(id, current);
+        // The role can only push the activation later, never to the same time or earlier.
+        if (newTimestamp <= current) revert ProtocolVersions_DelayMustBeLater(current, newTimestamp);


I'm debating if we need this. Since the following if statement is enforcing a min notice, maybe it's ok to allow newTimestamp to be <= current. What do you think?

We should be good to remove it from a technical standpoint. Although I think it is best to keep it, as SC should be the only one who moves the timestamps back based on prev. discussions about what chain team should be able to control.

@Custom

Deploy the ProtocolVersions impl + per-chain proxy as part of SystemDeploy and initialize it via initialize(l2ChainId), rather than excluding it from initializer tracking. Adds it to Types.Implementations/DeployOutput, artifact saves, getImplementations, and _assertValidImplementations. Tags the contract @Custom:proxied true so the initializer test verifies both impl and proxy, and wires it into Setup (via getAddress for fork safety). Updates the ProtocolVersions sourceCodeHash in semver-lock accordingly. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

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

@jackchuma

…no-op setTimestamp Apply @jackchuma review nits on ProtocolVersions: - Rename the chainTeam role to incidentResponder; delaying a bad hardfork activation is an incident-response action. NatSpec scopes the power so the shared name doesn't imply SuperchainConfig's pause authority. - Drop the redundant chainTeam deploy config key and source the role from superchainConfigIncidentResponder (same entity). - setTimestamp: short-circuit no-op writes ahead of the change-validation guards so idempotent resubmissions succeed. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Run ProtocolVersions tests through CommonTest so they use the SystemDeploy-created proxy and implementation. Reorder ProtocolVersions members to match the Solidity style guide and restrict implementation internals to private. Co-authored-by: Codex <codex-noreply@coinbase.com>

Events before errors, and mutating externals before view getters, mirroring the ProtocolVersions contract body and the repo style-guide ordering. ABI is generator-sorted, so no snapshot or semver-lock impact. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Replace the per-upgrade IUpgradeSignal reads (getTimestamp/getProtocolVersion by name) with the new ProtocolVersions interface from base/contracts#353: - read the full id-ordered schedule with one getSchedule() call and the global minimumProtocolVersion() in a single pinned L1 block read - map schedule entries onto the node hardfork ladder in activation (timestamp) order: id 0 (lowest timestamp) aligns with the oldest contract-backed hardfork; entries newer than the known ladder are logged and ignored, and unregistered hardforks produce no signal - attach the global minimum protocol version to every mapped signal so the existing validation and sink pipeline is unchanged - bump the supported node protocol version from 7 to packed semver 1.1.0 - drop the now-impossible TimestampOverflow error (timestamps are uint64 onchain)

PelleKrab and others added 5 commits June 25, 2026 18:10

chore(L1): apply forge fmt and update semver-lock for ProtocolVersions

e30e60c

Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

PelleKrab requested a review from jackchuma June 26, 2026 01:21

chore(L1): update semver-lock for ProtocolVersions

50a37cd

Reflects bytecode change from caching hash chain seed as immutable. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

jackchuma reviewed Jul 6, 2026

View reviewed changes

PelleKrab and others added 3 commits July 6, 2026 12:54

PelleKrab force-pushed the dynamic-hardfork-protocol-id branch from 3405a31 to 358db8c Compare July 6, 2026 23:07

PelleKrab force-pushed the dynamic-hardfork-protocol-id branch from 358db8c to c034032 Compare July 6, 2026 23:17

test: exclude ProtocolVersions from initializer tracking

1f39756

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

jackchuma reviewed Jul 7, 2026

View reviewed changes

PelleKrab and others added 4 commits July 7, 2026 09:50

refactor(L1): simplify ProtocolVersions schedule seed

766f563

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

fix(L1): apply ProtocolVersions review nits

29fff2f

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

refactor(L1): reduce ProtocolVersions API surface

2257727

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

PelleKrab force-pushed the dynamic-hardfork-protocol-id branch from 3fbdf54 to 2257727 Compare July 7, 2026 23:03

PelleKrab mentioned this pull request Jul 8, 2026

feat(L1): bind aggregate proofs to ProtocolVersions schedule #359

Open

5 tasks

jackchuma reviewed Jul 9, 2026

View reviewed changes

Comment thread scripts/deploy/DeployConfig.s.sol Outdated

Comment thread src/L1/ProtocolVersions.sol Outdated

PelleKrab force-pushed the dynamic-hardfork-protocol-id branch from 0570814 to 7cb1c5d Compare July 9, 2026 17:18

PelleKrab force-pushed the dynamic-hardfork-protocol-id branch from 7cb1c5d to e1ebc49 Compare July 9, 2026 17:39

jackchuma reviewed Jul 10, 2026

View reviewed changes

Comment thread scripts/deploy/SystemDeploy.s.sol

fix(deploy): upgrade ProtocolVersions proxy

21e6cc7

Uh oh!

Conversation

PelleKrab commented Jun 26, 2026

Summary

Test plan

Uh oh!

cb-heimdall commented Jun 26, 2026

🟡 Heimdall Review Status

Uh oh!

jackchuma left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jackchuma Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

PelleKrab Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants