Skip to content

docs(l1): fix stale v6 upgrade runbook and comments - #25626

Open
spalladino wants to merge 1 commit into
v6from
spl/v6-upgrade-docs-fixes
Open

spalladino wants to merge 1 commit into
v6from
spl/v6-upgrade-docs-fixes

Conversation

@spalladino

Copy link
Copy Markdown
Contributor

Docs and comments only, on top of #25601, from reviewing that PR. No Solidity code changes.

Context

Some of the runbook and comments in #25601 predate later design changes, and a few runbook steps would mislead an operator on deploy day:

  • The deploy script header still describes a deploy-key-owned rollup that is later handed to governance. The rollup is owned by governance from construction.
  • The runbook requires totalEarmarkedBalance to be 0 before execution. That contradicts the payload, which earmarks 1.8M to v5 by design, and it is not needed: earmarks stay claimable by their recipient after it stops being canonical, and subsidizeAddress raises the balance and the earmarked total equally, so it cannot shrink the implicit pool. Anyone could send a 1-token earmark to v5 and an operator following the runbook would hold a valid upgrade.
  • The PR description and script header say verify() reads back every value. It does not check the entry-queue config, the reward-boost parameters, ethereumSlotDuration, or the verifier's bytecode.

Approach

  • Deploy script and payload NatSpec: describe the governance-owned-from-construction flow, and list what verify() does not check.
  • Runbook pre-flight: replace the zero-earmark check with a headroom check (availableTo(v5) must cover the 1.8M reservation), add an owner check for the old flush rewarder, define $TOKEN, and record a 2026-10-08 baseline.
  • Runbook deploy: list the six external-library deployments that precede the verifier (ten transactions, ~58.4M gas from a mainnet dry run, each under the EIP-7825 cap), and add a manual check that the deployed verifier's runtime code hash equals the pinned artifact, since verify() does not cover it and the verifier is immutable.
  • Fix action numbers (the window check is action 2; Registry.addRollup is action 7), drop a duplicated owner check, and replace placeholder cast commands in the post-execution checks with real ones, including reading v5's retuned reward config.
  • V6UpgradePayload.md: rewrite the earmark limitation to match the distributor's behavior.

The Sepolia comments in the config table (entry-queue "v5 Sepolia production" values, "all of it un-earmarked") were flagged as possibly stale against live Sepolia, but reviewers disagreed and I did not verify them, so they are unchanged here.

Base automatically changed from amin/v6-upgrade-payload to v6 October 8, 2026 18:09
@just-mitch
just-mitch removed their request for review October 8, 2026 20:20
- Deploy script header described the old deployer-owned-then-transferred
  flow; the rollup is owned by governance from construction.
- State which values verify() does not read back.
- Runbook: drop the incorrect 'totalEarmarkedBalance must be 0'
  precondition (earmarks stay claimable and subsidizeAddress cannot shrink
  the implicit pool); check availableTo(v5) covers the reservation instead.
- Runbook: list the six library deployments and the measured gas, add a
  verifier bytecode check, fix action numbers, fill in placeholder commands.
@spalladino
spalladino force-pushed the spl/v6-upgrade-docs-fixes branch from cb767bf to efeb2d4 Compare October 9, 2026 19:13
@spalladino
spalladino enabled auto-merge (squash) October 9, 2026 19:15

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant