@aztec-foundation/l1-artifacts 6.0.0-rc.6 → 6.0.0-rc.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. package/dest/HonkVerifierBytecode.d.ts +1 -1
  2. package/dest/HonkVerifierBytecode.js +1 -1
  3. package/l1-contracts/cache/solidity-files-cache.json +1 -1
  4. package/l1-contracts/foundry.toml +1 -0
  5. package/l1-contracts/generated/HonkVerifier.sol +45 -45
  6. package/l1-contracts/out/AddressSnapshotLib.sol/AddressSnapshotLib.json +1 -1
  7. package/l1-contracts/out/AttestationLib.sol/AttestationLib.json +1 -1
  8. package/l1-contracts/out/AttesterExitExtLib.sol/AttesterExitExtLib.json +1 -1
  9. package/l1-contracts/out/BN254Lib.sol/BN254Lib.json +1 -1
  10. package/l1-contracts/out/Ballot.sol/BallotLib.json +1 -1
  11. package/l1-contracts/out/BlobLib.sol/BlobLib.json +1 -1
  12. package/l1-contracts/out/Bn254LibWrapper.sol/Bn254LibWrapper.json +1 -1
  13. package/l1-contracts/out/CheckpointLog.sol/CompressedTempCheckpointLogLib.json +1 -1
  14. package/l1-contracts/out/CheckpointedUintLib.sol/CheckpointedUintLib.json +1 -1
  15. package/l1-contracts/out/CoinIssuer.sol/CoinIssuer.json +1 -1
  16. package/l1-contracts/out/CompressedTimeMath.sol/CompressedTimeMath.json +1 -1
  17. package/l1-contracts/out/Configuration.sol/CompressedConfigurationLib.json +1 -1
  18. package/l1-contracts/out/ConfigurationLib.sol/ConfigurationLib.json +1 -1
  19. package/l1-contracts/out/ConstantsGen.sol/Constants.json +1 -1
  20. package/l1-contracts/out/CoordinationSignatureLib.sol/CoordinationSignatureLib.json +1 -1
  21. package/l1-contracts/out/DataStructures.sol/DataStructures.json +1 -1
  22. package/l1-contracts/out/DateGatedRelayer.sol/DateGatedRelayer.json +1 -1
  23. package/l1-contracts/out/DeployAztecL1Contracts.s.sol/DeployAztecL1Contracts.json +1 -1
  24. package/l1-contracts/out/DeployRollupForUpgrade.s.sol/DeployRollupForUpgrade.json +1 -1
  25. package/l1-contracts/out/DeployRollupForUpgradeV6.s.sol/DeployRollupForUpgradeV6.json +1 -0
  26. package/l1-contracts/out/DeployRollupLib.sol/DeployRollupLib.json +1 -1
  27. package/l1-contracts/out/DeploymentConfiguration.sol/DeploymentConfiguration.json +1 -1
  28. package/l1-contracts/out/DeploymentConfiguration.sol/IDeploymentConfiguration.json +1 -1
  29. package/l1-contracts/out/DepositDelegationLib.sol/DepositDelegationLib.json +1 -1
  30. package/l1-contracts/out/EmpireBase.sol/EmpireBase.json +1 -1
  31. package/l1-contracts/out/EpochProofExtLib.sol/EpochProofExtLib.json +1 -1
  32. package/l1-contracts/out/EpochProofLib.sol/EpochProofLib.json +1 -1
  33. package/l1-contracts/out/Errors.sol/Errors.json +1 -1
  34. package/l1-contracts/out/EscapeHatch.sol/EscapeHatch.json +1 -1
  35. package/l1-contracts/out/FeeAssetHandler.sol/FeeAssetHandler.json +1 -1
  36. package/l1-contracts/out/FeeAssetHandler.sol/IFeeAssetHandler.json +1 -1
  37. package/l1-contracts/out/FeeConfig.sol/FeeConfigLib.json +1 -1
  38. package/l1-contracts/out/FeeConfig.sol/PriceLib.json +1 -1
  39. package/l1-contracts/out/FeeJuicePortal.sol/FeeJuicePortal.json +1 -1
  40. package/l1-contracts/out/FeeLib.sol/FeeLib.json +1 -1
  41. package/l1-contracts/out/FeeStructs.sol/FeeHeaderLib.json +1 -1
  42. package/l1-contracts/out/FeeStructs.sol/FeeStructsLib.json +1 -1
  43. package/l1-contracts/out/FieldLib.sol/FieldLib.json +1 -1
  44. package/l1-contracts/out/FlushEntryQueue.s.sol/FlushEntryQueue.json +1 -1
  45. package/l1-contracts/out/FlushRewarder.sol/FlushRewarder.json +1 -1
  46. package/l1-contracts/out/GSE.sol/GSE.json +1 -1
  47. package/l1-contracts/out/GSE.sol/GSECore.json +1 -1
  48. package/l1-contracts/out/GSE.sol/IGSE.json +1 -1
  49. package/l1-contracts/out/GSE.sol/IGSECore.json +1 -1
  50. package/l1-contracts/out/GSEPayload.sol/GSEPayload.json +1 -1
  51. package/l1-contracts/out/Governance.sol/Governance.json +1 -1
  52. package/l1-contracts/out/GovernanceProposer.sol/GovernanceProposer.json +1 -1
  53. package/l1-contracts/out/Hash.sol/Hash.json +1 -1
  54. package/l1-contracts/out/HonkVerifier.sol/HonkVerifier.json +1 -1
  55. package/l1-contracts/out/HonkVerifier.sol/IVerifier.json +1 -1
  56. package/l1-contracts/out/IBn254LibWrapper.sol/IBn254LibWrapper.json +1 -1
  57. package/l1-contracts/out/ICoinIssuer.sol/ICoinIssuer.json +1 -1
  58. package/l1-contracts/out/IDateGatedRelayer.sol/IDateGatedRelayer.json +1 -1
  59. package/l1-contracts/out/IEmpire.sol/IEmperor.json +1 -1
  60. package/l1-contracts/out/IEmpire.sol/IEmpire.json +1 -1
  61. package/l1-contracts/out/IEscapeHatch.sol/IEscapeHatch.json +1 -1
  62. package/l1-contracts/out/IEscapeHatch.sol/IEscapeHatchCore.json +1 -1
  63. package/l1-contracts/out/IFeeJuicePortal.sol/IFeeJuicePortal.json +1 -1
  64. package/l1-contracts/out/IFlushRewarder.sol/IFlushRewarder.json +1 -1
  65. package/l1-contracts/out/IGovernance.sol/IGovernance.json +1 -1
  66. package/l1-contracts/out/IGovernanceProposer.sol/IGovernanceProposer.json +1 -1
  67. package/l1-contracts/out/IInbox.sol/IInbox.json +1 -1
  68. package/l1-contracts/out/IInstance.sol/IInstance.json +1 -1
  69. package/l1-contracts/out/IMintableERC20.sol/IMintableERC20.json +1 -1
  70. package/l1-contracts/out/IOutbox.sol/IOutbox.json +1 -1
  71. package/l1-contracts/out/IPayload.sol/IPayload.json +1 -1
  72. package/l1-contracts/out/IProposerPayload.sol/IProposerPayload.json +1 -1
  73. package/l1-contracts/out/IRegistry.sol/IHaveVersion.json +1 -1
  74. package/l1-contracts/out/IRegistry.sol/IRegistry.json +1 -1
  75. package/l1-contracts/out/IRewardDistributor.sol/IRewardDistributor.json +1 -1
  76. package/l1-contracts/out/IRollup.sol/IRollup.json +1 -1
  77. package/l1-contracts/out/IRollup.sol/IRollupCore.json +1 -1
  78. package/l1-contracts/out/IRootRegistry.sol/IRootRegistry.json +1 -1
  79. package/l1-contracts/out/ISequencerRewardCalculator.sol/ISequencerRewardCalculator.json +1 -1
  80. package/l1-contracts/out/ISlasher.sol/ISlasher.json +1 -1
  81. package/l1-contracts/out/IStaking.sol/IStaking.json +1 -1
  82. package/l1-contracts/out/IStaking.sol/IStakingCore.json +1 -1
  83. package/l1-contracts/out/IValidatorSelection.sol/IValidatorSelection.json +1 -1
  84. package/l1-contracts/out/IValidatorSelection.sol/IValidatorSelectionCore.json +1 -1
  85. package/l1-contracts/out/IVerifier.sol/IVerifier.json +1 -1
  86. package/l1-contracts/out/Inbox.sol/Inbox.json +1 -1
  87. package/l1-contracts/out/InputsExtractor.sol/InputsExtractor.json +1 -1
  88. package/l1-contracts/out/InvalidateLib.sol/InvalidateLib.json +1 -1
  89. package/l1-contracts/out/MerkleLib.sol/MerkleLib.json +1 -1
  90. package/l1-contracts/out/MockERC20.sol/MockERC20.json +1 -1
  91. package/l1-contracts/out/MockERC721.sol/MockERC721.json +1 -1
  92. package/l1-contracts/out/MockFeeJuicePortal.sol/MockFeeJuicePortal.json +1 -1
  93. package/l1-contracts/out/MockVerifier.sol/MockVerifier.json +1 -1
  94. package/l1-contracts/out/MockZKPassportVerifier.sol/IZKPassportVerifier.json +1 -1
  95. package/l1-contracts/out/MockZKPassportVerifier.sol/MockZKPassportVerifier.json +1 -1
  96. package/l1-contracts/out/MultiAdder.sol/IMultiAdder.json +1 -1
  97. package/l1-contracts/out/MultiAdder.sol/MultiAdder.json +1 -1
  98. package/l1-contracts/out/Outbox.sol/Outbox.json +1 -1
  99. package/l1-contracts/out/OuterCount8.sol/HonkVerifier.json +1 -1
  100. package/l1-contracts/out/Proposal.sol/CompressedProposalLib.json +1 -1
  101. package/l1-contracts/out/ProposalLib.sol/ProposalLib.json +1 -1
  102. package/l1-contracts/out/ProposeLib.sol/ProposeLib.json +1 -1
  103. package/l1-contracts/out/ProposedHeaderLib.sol/ProposedHeaderLib.json +1 -1
  104. package/l1-contracts/out/RegisterNewRollupVersionPayload.sol/RegisterNewRollupVersionPayload.json +1 -1
  105. package/l1-contracts/out/Registry.sol/Registry.json +1 -1
  106. package/l1-contracts/out/RewardBooster.sol/IBooster.json +1 -1
  107. package/l1-contracts/out/RewardBooster.sol/IBoosterCore.json +1 -1
  108. package/l1-contracts/out/RewardBooster.sol/RewardBooster.json +1 -1
  109. package/l1-contracts/out/RewardDistributor.sol/RewardDistributor.json +1 -1
  110. package/l1-contracts/out/RewardExtLib.sol/RewardExtLib.json +1 -1
  111. package/l1-contracts/out/RewardLib.sol/BpsLib.json +1 -1
  112. package/l1-contracts/out/RewardLib.sol/RewardLib.json +1 -1
  113. package/l1-contracts/out/Rollup.sol/Rollup.json +1 -1
  114. package/l1-contracts/out/RollupConfiguration.sol/IRollupConfiguration.json +1 -1
  115. package/l1-contracts/out/RollupConfiguration.sol/RollupConfiguration.json +1 -1
  116. package/l1-contracts/out/RollupCore.sol/RollupCore.json +1 -1
  117. package/l1-contracts/out/RollupOperationsExtLib.sol/RollupOperationsExtLib.json +1 -1
  118. package/l1-contracts/out/STFLib.sol/STFLib.json +1 -1
  119. package/l1-contracts/out/SampleLib.sol/SampleLib.json +1 -1
  120. package/l1-contracts/out/SequencerRewardCalculatorLib.sol/SequencerRewardCalculatorLib.json +1 -1
  121. package/l1-contracts/out/SignatureLib.sol/SignatureLib.json +1 -1
  122. package/l1-contracts/out/SlashPayload.sol/SlashPayload.json +1 -1
  123. package/l1-contracts/out/SlashPayloadCloneable.sol/SlashPayloadCloneable.json +1 -1
  124. package/l1-contracts/out/SlashPayloadLib.sol/SlashPayloadLib.json +1 -1
  125. package/l1-contracts/out/SlashRoundLib.sol/CompressedSlashRoundMath.json +1 -1
  126. package/l1-contracts/out/Slasher.sol/Slasher.json +1 -1
  127. package/l1-contracts/out/SlasherDeploymentExtLib.sol/SlasherDeploymentExtLib.json +1 -1
  128. package/l1-contracts/out/SlashingProposer.sol/SlashingProposer.json +1 -1
  129. package/l1-contracts/out/StakingAssetHandler.sol/IStakingAssetHandler.json +1 -1
  130. package/l1-contracts/out/StakingAssetHandler.sol/StakingAssetHandler.json +1 -1
  131. package/l1-contracts/out/StakingLib.sol/StakingLib.json +1 -1
  132. package/l1-contracts/out/StakingQueue.sol/StakingQueueLib.json +1 -1
  133. package/l1-contracts/out/StakingQueueConfig.sol/StakingQueueConfigLib.json +1 -1
  134. package/l1-contracts/out/StdError.sol/stdError.json +1 -1
  135. package/l1-contracts/out/TestERC20.sol/TestERC20.json +1 -1
  136. package/l1-contracts/out/TestPayloads.sol/CallAssetPayload.json +1 -1
  137. package/l1-contracts/out/TestPayloads.sol/CallRevertingPayload.json +1 -1
  138. package/l1-contracts/out/TestPayloads.sol/EmptyPayload.json +1 -1
  139. package/l1-contracts/out/TestPayloads.sol/FakeRollup.json +1 -1
  140. package/l1-contracts/out/TestPayloads.sol/RevertingCall.json +1 -1
  141. package/l1-contracts/out/TestPayloads.sol/UpgradePayload.json +1 -1
  142. package/l1-contracts/out/TimeLib.sol/TimeLib.json +1 -1
  143. package/l1-contracts/out/Tips.sol/ChainTipsLib.json +1 -1
  144. package/l1-contracts/out/V6UpgradePayload.sol/V6UpgradePayload.json +1 -0
  145. package/l1-contracts/out/V6UpgradeSimulation.sol/V6UpgradeSimulation.json +1 -0
  146. package/l1-contracts/out/ValidatorOperationsExtLib.sol/ValidatorOperationsExtLib.json +1 -1
  147. package/l1-contracts/out/ValidatorSelectionLib.sol/ValidatorSelectionLib.json +1 -1
  148. package/l1-contracts/out/ZKPassportHelper.sol/ZKPassportHelper.json +1 -1
  149. package/l1-contracts/out/ZKPassportRootVerifier.sol/ZKPassportRootVerifier.json +1 -1
  150. package/l1-contracts/out/ZKPassportSubVerifier.sol/ZKPassportSubVerifier.json +1 -1
  151. package/l1-contracts/out/build-info/ba785d07f217e383.json +1 -0
  152. package/l1-contracts/out/deploy/HonkVerifier.sol/HonkVerifier.json +1 -0
  153. package/l1-contracts/out/deploy/HonkVerifier.sol/IVerifier.json +1 -0
  154. package/l1-contracts/out/generated/HonkVerifier.sol/HonkVerifier.json +1 -1
  155. package/l1-contracts/out/libraries/Errors.sol/Errors.json +1 -1
  156. package/l1-contracts/out/rollup/BlobLib.sol/BlobLib.json +1 -1
  157. package/l1-contracts/out/src/ZKPassportHelper.sol/ZKPassportHelper.json +1 -1
  158. package/l1-contracts/out/src/ZKPassportRootVerifier.sol/ZKPassportRootVerifier.json +1 -1
  159. package/l1-contracts/out/src/ZKPassportSubVerifier.sol/ZKPassportSubVerifier.json +1 -1
  160. package/l1-contracts/script/deploy/DeployRollupForUpgradeV6.s.sol +688 -0
  161. package/l1-contracts/script/deploy/HonkVerifier.sol +5723 -0
  162. package/l1-contracts/script/deploy/V6UpgradeSimulation.sol +285 -0
  163. package/l1-contracts/script/deploy/V6_UPGRADE_RUNBOOK.md +441 -0
  164. package/l1-contracts/src/periphery/V6UpgradePayload.md +113 -0
  165. package/l1-contracts/src/periphery/V6UpgradePayload.sol +441 -0
  166. package/package.json +1 -1
  167. package/l1-contracts/out/build-info/018c24616ac5aeef.json +0 -1
@@ -0,0 +1,441 @@
1
+ # v6 rollup upgrade runbook
2
+
3
+ How to deploy the v6 rollup and get it made canonical. Covers `DeployRollupForUpgradeV6.s.sol`,
4
+ `V6UpgradePayload.sol` and `V6UpgradeSimulation.sol`.
5
+
6
+ Reviewing the payload rather than running the upgrade? Start at
7
+ [`src/periphery/V6UpgradePayload.md`](../../src/periphery/V6UpgradePayload.md) — what it intends,
8
+ guarantees, and deliberately leaves alone.
9
+
10
+ ## What this does
11
+
12
+ The deploy script deploys, in one broadcast of ten transactions:
13
+
14
+ 0. Six external libraries the `Rollup` links against (`AttesterExitExtLib`,
15
+ `ValidatorOperationsExtLib`, `SlasherDeploymentExtLib`, `RollupOperationsExtLib`, `RewardExtLib`,
16
+ `EpochProofExtLib`), via the CREATE2 deployer. They go out first and account for about 33M of the
17
+ roughly 58M gas the broadcast uses.
18
+ 1. `HonkVerifier` — the real epoch proof verifier, from the pinned `script/deploy/HonkVerifier.sol`
19
+ (see [Build](#1-build)), not from this tree's `generated/`.
20
+ 2. `Rollup` — owned by **governance** from construction. Deploying it also constructs its `Inbox`,
21
+ `Outbox`, `FeeJuicePortal`, `Slasher` + `SlashingProposer`, and a fresh `RewardBooster`.
22
+ **The owner argument is not only the owner:** it also becomes the Slasher's immutable
23
+ `GOVERNANCE`, which can execute any slash payload with no vote and no delay. Constructing with
24
+ the deploy key would hand that power to the key permanently — `transferOwnership` moves only the
25
+ `Ownable` half. This is why no owner-gated setup happens in the script.
26
+ 3. `EscapeHatch` — built here, but **installed by the payload**, since `setEscapeHatch` is
27
+ `onlyOwner` and the owner is governance.
28
+ 4. `V6UpgradePayload` — and, on a chain with a flush rewarder, a replacement `FlushRewarder`
29
+ deployed inside the payload's constructor.
30
+
31
+ Nothing is canonical yet. The payload is what governance executes later; it performs:
32
+
33
+ | # | Action | Why |
34
+ |---|---|---|
35
+ | 1 | `assertPredecessorIsCanonical()` | refuses to run if the rollup this payload succeeds is no longer canonical |
36
+ | 2 | `assertWithinExecutionWindow()` | mainnet only; Mon–Fri 08:00–17:00 London |
37
+ | 3 | `distributor.recoverFrom(v5, payload, amount)` | skipped when the reservation is zero |
38
+ | 4 | `payload.forwardEarmark()` | parks the drawn balance in v5's own earmarked bucket |
39
+ | 5 | `v5.setRewardConfig(...)` | retunes the OUTGOING rollup's split; skipped when the flag is off |
40
+ | 6 | `v6.setEscapeHatch(hatch)` | installs the hatch; `onlyOwner`, so only governance can |
41
+ | 7 | `Registry.addRollup(v6)` | makes v6 the canonical rollup |
42
+ | 8 | `GSE.addRollup(v6)` | lets existing attesters follow without redepositing |
43
+ | 9 | `oldFlushRewarder.recover(asset, newRewarder, rewardsAvailable())` | carries the entry-queue flush incentive across (skipped if there is no old rewarder) |
44
+ | 10 | `GSE.setProofOfPossessionGasLimit(300_000)` | raises the GSE's cap on BLS proof-of-possession verification from 250k; skipped when the configured value is zero |
45
+
46
+ Actions 3–5 all act on the **outgoing** rollup and must precede action 7. The distributor resolves
47
+ `canonicalRollup()` live off the registry, so once v6 is canonical the old rollup can no longer
48
+ reach the implicit pool, and the retune would be settling a chain that has already stopped.
49
+
50
+ Action 10 has no ordering constraint and goes last. The GSE verifies each new attester's proof of
51
+ possession in a sub-call capped at this much gas, and a deposit whose verification does not fit is
52
+ refunded and dropped from the entry queue. The cost varies per key, and since Osaka's modexp
53
+ repricing about 1 in 28.6k honestly generated keys exceed 250k; at 300k it is about 1 in 2.5M. The
54
+ cost of the raise is that a failing entry can burn at most 50k more gas in a flush. The GSE is
55
+ shared, so the new cap applies to the outgoing rollup too, from the moment the payload executes.
56
+
57
+ ## 1. Build
58
+
59
+ The verifier and the protocol constants are **pinned in git**, not built from this tree:
60
+
61
+ - `script/deploy/HonkVerifier.sol` — the epoch proof verifier from the v6 release build at
62
+ `42fae4eb3feb5a493f2e8a2baf78b4716e323c40`; its provenance comment names that commit.
63
+ `DeployRollupForUpgradeV6.s.sol` imports it as `./HonkVerifier.sol`.
64
+ - `src/core/libraries/ConstantsGen.sol` — from the same build.
65
+
66
+ The verifier is a function of the protocol circuits, and the circuits this branch would build
67
+ differ from the release's. A verifier built here has a different `VK_HASH` and rejects every proof
68
+ the v6 nodes produce, so **do not replace the pinned file with this tree's `generated/HonkVerifier.sol`**.
69
+ The verifier, `ConstantsGen.sol` and the three genesis roots in `_config()` come from one build and
70
+ move together.
71
+
72
+ No noir-projects bootstrap is needed. From a clean clone:
73
+
74
+ ```bash
75
+ git clone --branch <release branch> --depth 1 https://github.com/AztecProtocol/aztec-packages.git
76
+ cd aztec-packages
77
+ git submodule update --init --recursive --depth 1 -- l1-contracts/lib
78
+ cd l1-contracts
79
+ export FOUNDRY_SOLC_VERSION=0.8.30
80
+ forge script script/deploy/DeployRollupForUpgradeV6.s.sol --sig 'run()' \
81
+ --rpc-url $RPC # dry run; see Deploy for the broadcast flags
82
+ ```
83
+
84
+ - `FOUNDRY_SOLC_VERSION=0.8.30`: `foundry.toml` points `solc` at `./solc-0.8.30`, which only
85
+ `./bootstrap.sh` fetches; forge downloads the same binary (`0.8.30+commit.73712a01`). Use the
86
+ environment variable rather than `--use 0.8.30`: the flag covers compilation but not `--verify`,
87
+ which reads `foundry.toml` again and fails with `solc ./solc-0.8.30 does not exist`.
88
+ - The submodule step is required: `forge script` does not fetch `lib/` (only `forge build` does).
89
+ - Gas: forge sets each transaction's gas limit from its local simulation (`evm_version = 'prague'`),
90
+ which matches pre-Glamsterdam pricing, so the default limits are correct on mainnet before the
91
+ fork. Measured pre-fork on Sepolia: verifier 3.75M gas (limit 4.88M), rollup 11.98M (limit
92
+ 15.58M). A mainnet dry run (2026-10-08) estimated 58.4M gas across all ten transactions, each
93
+ limit under the cap, the largest being the rollup at 15.58M; budget roughly 0.25-0.4 ETH at
94
+ 4-6 gwei. Do **not** add `--gas-estimate-multiplier` before Glamsterdam: the rollup's limit would
95
+ exceed the EIP-7825 per-transaction cap of 16,777,216 and the node would reject it after the
96
+ verifier had already been sent. The rollup's default limit sits about 1.2M under that cap.
97
+ - After Glamsterdam, the default limits are far too low: on post-fork Sepolia the verifier creation
98
+ ran out of gas at its 4.88M limit. Measured there: verifier 26.7M, rollup 84.8M, escape hatch
99
+ 14.9M, payload 10.1M gas, deployed with `--gas-estimate-multiplier 1000` under a 200M block gas
100
+ limit. Re-check that path against mainnet's post-fork rules before using it.
101
+
102
+ > Run `forge script` on the deploy script, **not** `forge build`. A whole-project build also compiles
103
+ > `DeployRollupLib.sol`, which imports `@generated/HonkVerifier.sol` and fails on a clean clone.
104
+ > Do **not** hand-write a stub `generated/HonkVerifier.sol` to get past that: a stub compiles and
105
+ > deploys a verifier that accepts every proof.
106
+
107
+ Confirm the pin before broadcasting:
108
+
109
+ ```bash
110
+ grep -m1 VK_HASH script/deploy/HonkVerifier.sol
111
+ # 0x1fd4eb1d14be45e05dc78c448eb4f29d7f63e4de95129c4a5e1058cd9837f8a6
112
+ ```
113
+
114
+ ## 2. Fill in the inputs
115
+
116
+ All configuration is the `_config()` literal in `DeployRollupForUpgradeV6.s.sol`. Before a real
117
+ deploy these must be set:
118
+
119
+ | Field | Status | Notes |
120
+ |---|---|---|
121
+ | `vkTreeRoot` | set | `0x22fff5de…5913f219`, from the v6 release build at `42fae4eb`; see below |
122
+ | `protocolContractsHash` | set | `0x0f54271c…5c9854d7`, same build |
123
+ | `genesisArchiveRoot` | set | `0x29eb2c52…3d41e5c4`, same build. Must be below the BN254 scalar field modulus |
124
+ | `initialEthPerFeeAsset` | set | mainnet `5_934_240` (0.0000059342 ETH per AZTEC, from the AZTEC/ETH Uniswap v4 pool at block 26148995, 2026-10-08); Sepolia `10_000_000`. E12 ETH-per-fee-asset price |
125
+ | `sequencerRewardCalculator` | set | `address(0)` on both chains — v6 launches with no calculator, see below |
126
+ | `oldFlushRewarder` | set (mainnet) | `0x5B98cA4dcE7b59CCf241D12f81d3d2eCF14e410e`; zero on Sepolia |
127
+ | `earmarkAmountForPredecessor` | set | mainnet 1,800,000e18; Sepolia 5,000,000e18. Zero would omit both earmark actions |
128
+ | `retunePredecessorRewards` | set | `true` on both chains |
129
+ | `predecessorSequencerBps` | set | mainnet 7000 (v5 keeps the split it already runs); Sepolia 8000 |
130
+ | `predecessorCheckpointReward` | set | mainnet 50e18; Sepolia 100e18. Both down from the 500e18 v5 runs on |
131
+ | `enforcePayloadExecutionWindow` | set | `true` on mainnet, `false` on Sepolia |
132
+ | `proofOfPossessionGasLimit` | set | `300_000` on both chains; zero omits the action. The payload constructor reverts unless it exceeds the GSE's cap at deployment |
133
+
134
+ Neither chain has outstanding values. The three genesis values are not decisions but build outputs,
135
+ pinned with the verifier.
136
+
137
+ `run()` refuses to proceed while any of the three genesis roots is zero, so a forgotten root fails
138
+ loudly. A *stale* root does not: it is non-zero and deploys happily. Nothing guards the rest either
139
+ — `initialEthPerFeeAsset` deploys silently at whatever value is in the table.
140
+
141
+ ### Sequencer reward policy
142
+
143
+ Under AZIP-31 the rollup can call a governance-set `ISequencerRewardCalculator` once per epoch
144
+ proof, and `sequencerRewardCalculator` is the address it starts with.
145
+
146
+ **v6 launches with `address(0)` on both chains, so every proposer earns the default sequencer
147
+ share.** Installing a calculator later is a governance action, `setSequencerRewardCalculator`, and
148
+ needs no redeploy.
149
+
150
+ Nothing about the calculator path is loud, so if a later deploy does set one:
151
+
152
+ - A calculator that reverts, exhausts its stipend (`200k + 100k` per checkpoint), or answers in the
153
+ wrong shape causes every checkpoint to fall back to the default reward. There is no revert and no
154
+ event; the rollup simply pays as though no calculator were configured.
155
+ - Nothing at deploy time checks the address is a calculator, or a contract at all. A
156
+ wrong-but-plausible address has the same observable result as `address(0)`.
157
+ - Reward values are capped at read time at `min(default, entry)`, so a too-high entry cannot pay
158
+ anyone more than the default. Note this cap is now applied on read rather than at construction,
159
+ so lowering `sequencerBps` or `checkpointReward` later tightens existing entries automatically.
160
+
161
+ Read the value back with `getSequencerRewardCalculator()` after the deploy. Unlike the rest of this
162
+ table it is mutable after construction, so it is worth re-checking after any governance action that
163
+ touches rewards.
164
+
165
+ The three genesis values are produced by the protocol circuits / node build, not by anything in
166
+ `l1-contracts`. Get them from the same source the v6 release uses; do not carry v5's forward.
167
+
168
+ The values in `_config()` were read off a full build (`make fast`) of the v6 release at
169
+ `42fae4eb3feb5a493f2e8a2baf78b4716e323c40`, the same build the pinned verifier and
170
+ `ConstantsGen.sol` come from:
171
+
172
+ | Field | Value |
173
+ |---|---|
174
+ | `vkTreeRoot` | `0x22fff5de6ce590153df4468f7f0b152188a803d91b3c9c648b91d93d5913f219` |
175
+ | `protocolContractsHash` | `0x0f54271c52865841a77aaa66036eed901aff22fdce9f08e123ec8b205c9854d7` |
176
+ | `genesisArchiveRoot` | `0x29eb2c527f8d45276430363214e6c8d709ef3f657a3670ebac3179373d41e5c4` |
177
+ | verifier `VK_HASH` | `0x1fd4eb1d14be45e05dc78c448eb4f29d7f63e4de95129c4a5e1058cd9837f8a6` |
178
+
179
+ All three moved when the release build advanced to `42fae4eb`, which changes protocol circuit
180
+ sources, including `types/src/address/aztec_address.nr` and `types/src/constants.nr`. The verifier
181
+ did not: `VK_HASH` is unchanged and the pinned file only gained a new provenance comment. It still
182
+ differs from the verifier this branch's own circuits build, which is what the pin exists for.
183
+
184
+ Regenerate all of them, and re-pin the verifier and `ConstantsGen.sol`, if the release build moves
185
+ to a commit that changes the protocol circuits or protocol contracts: rebuilding the circuits moves
186
+ `vkTreeRoot` and the verifier, and rebuilding the protocol contracts moves all three roots. After
187
+ `make fast` on the release build, the first two come from the built packages and the third from the
188
+ protocol constants:
189
+
190
+ ```bash
191
+ # from labs/yarn-project/prover-node
192
+ node --input-type=module -e '
193
+ import { getVKTreeRoot } from "@aztec-labs/noir-protocol-circuits-types/vk-tree";
194
+ import { protocolContractsHash } from "@aztec-labs/protocol-contracts";
195
+ console.log(getVKTreeRoot().toString(), protocolContractsHash.toString());'
196
+
197
+ grep -A1 GENESIS_ARCHIVE_ROOT \
198
+ noir-projects/fnd/noir-protocol-circuits/crates/types/src/constants.nr
199
+ ```
200
+
201
+ ## 3. Pre-flight checks
202
+
203
+ Read the chain and confirm the assumptions the config is built on. Mainnet registry:
204
+ `0x35b22e09Ee0390539439E24f06Da43D83f90e298`.
205
+
206
+ ```bash
207
+ export RPC=<mainnet rpc>
208
+ REG=0x35b22e09Ee0390539439E24f06Da43D83f90e298
209
+ ROLLUP=$(cast call $REG "getCanonicalRollup()(address)" --rpc-url $RPC)
210
+ GSE=$(cast call $ROLLUP "getGSE()(address)" --rpc-url $RPC)
211
+ RD=$(cast call $REG "getRewardDistributor()(address)" --rpc-url $RPC)
212
+ TOKEN=$(cast call $ROLLUP "getFeeAsset()(address)" --rpc-url $RPC)
213
+ BONUS=$(cast call $GSE "BONUS_INSTANCE_ADDRESS()(address)" --rpc-url $RPC)
214
+
215
+ cast call $GSE "ACTIVATION_THRESHOLD()(uint256)" --rpc-url $RPC # expect 200_000e18
216
+ cast call $GSE "EJECTION_THRESHOLD()(uint256)" --rpc-url $RPC # expect 100_000e18
217
+ cast call $GSE "proofOfPossessionGasLimit()(uint64)" --rpc-url $RPC # expect 250000, below the configured 300000
218
+ cast call $GSE "owner()(address)" --rpc-url $RPC # governance, or action 10 reverts
219
+ cast call $ROLLUP "getActiveAttesterCount()(uint256)" --rpc-url $RPC
220
+ cast call $ROLLUP "getIsBootstrapped()(bool)" --rpc-url $RPC
221
+
222
+ # the reservation's headroom: the implicit pool plus what is already earmarked to the outgoing
223
+ # rollup must cover the earmark amount (1,800,000e18), or action 3 reverts
224
+ cast call $TOKEN "balanceOf(address)(uint256)" $RD --rpc-url $RPC
225
+ cast call $RD "totalEarmarkedBalance()(uint256)" --rpc-url $RPC
226
+ cast call $RD "specificRecipientBalance(address)(uint256)" $ROLLUP --rpc-url $RPC
227
+ cast call $RD "availableTo(address)(uint256)" $ROLLUP --rpc-url $RPC # >= 1,800,000e18
228
+
229
+ # how much the payload will actually move (balance minus unclaimed debt)
230
+ cast call 0x5B98cA4dcE7b59CCf241D12f81d3d2eCF14e410e "rewardsAvailable()(uint256)" --rpc-url $RPC
231
+ cast call 0x5B98cA4dcE7b59CCf241D12f81d3d2eCF14e410e "owner()(address)" --rpc-url $RPC # governance, or action 9 reverts
232
+ ```
233
+
234
+ Baseline measured 2026-09-15 (block 25980374), for comparison rather than as expected constants:
235
+ attesters 3187, all in the bonus instance; `isBootstrapped` true; distributor holds ~98.98M with
236
+ `totalEarmarkedBalance` 0; flush rewarder holds 390,000e18 of which 378,900e18 is movable.
237
+ Re-measured 2026-10-08 (block 26149128): attesters 3090; distributor holds 85.76M with
238
+ `totalEarmarkedBalance` 0; 363,900e18 movable from the flush rewarder.
239
+
240
+ `totalEarmarkedBalance` does **not** need to be 0. Earmarks are keyed by address and stay
241
+ claimable by their recipient whether or not it is canonical, and `subsidizeAddress` (which anyone
242
+ can call) raises the distributor's balance and `totalEarmarkedBalance` by the same amount, so it
243
+ cannot shrink the implicit pool. A donation earmarked to the outgoing rollup before execution
244
+ simply adds to the reservation. What matters is `availableTo($ROLLUP)` covering the earmark
245
+ amount, checked above.
246
+
247
+ ## 4. Dry run
248
+
249
+ Run without `--broadcast` first. This executes the whole script including `verify`,
250
+ `verifyFlushRewarder` and the governance simulation, against forked state, changing nothing:
251
+
252
+ ```bash
253
+ cd l1-contracts
254
+ export FOUNDRY_SOLC_VERSION=0.8.30
255
+ REGISTRY_ADDRESS=0x35b22e09Ee0390539439E24f06Da43D83f90e298 \
256
+ forge script script/deploy/DeployRollupForUpgradeV6.s.sol:DeployRollupForUpgradeV6 \
257
+ --rpc-url $RPC -vvv
258
+ ```
259
+
260
+ `V6UpgradeSimulation` wraps the payload in a `GSEPayload` exactly as `GovernanceProposer` does,
261
+ funds a simulation-only voter with a majority of power, votes, warps past the delays, executes,
262
+ asserts the post-state, then reverts the snapshot. It proves the **actions execute correctly**; it
263
+ does not predict whether a real proposal would pass.
264
+
265
+ A green dry run means the config is self-consistent and the payload works. It does not check the
266
+ genesis roots are the right ones — nothing on chain can.
267
+
268
+ ## 5. Deploy
269
+
270
+ ```bash
271
+ export FOUNDRY_SOLC_VERSION=0.8.30 ETHERSCAN_API_KEY=<key>
272
+ REGISTRY_ADDRESS=0x35b22e09Ee0390539439E24f06Da43D83f90e298 \
273
+ forge script script/deploy/DeployRollupForUpgradeV6.s.sol:DeployRollupForUpgradeV6 \
274
+ --slow \
275
+ --rpc-url $RPC --private-key $KEY --broadcast --verify -vvv
276
+ ```
277
+
278
+ `--slow` sends each transaction only after the previous one is mined, so a failure stops the
279
+ broadcast instead of leaving later transactions pending against a contract that does not exist.
280
+
281
+ `--verify` submits every contract the broadcast created to Etherscan, including the seven the
282
+ `Rollup` constructor deploys (`Slasher`, `SlashingProposer`, `SlashPayloadCloneable`,
283
+ `RewardBooster`, `Inbox`, `FeeJuicePortal`, `Outbox`). If verification fails or is skipped, re-run it
284
+ from the same checkout without sending anything: the same command with `--broadcast` replaced by
285
+ `--resume`. The verified `HonkVerifier` source is the pinned file, so anyone can read its `VK_HASH`
286
+ on Etherscan.
287
+
288
+ Record the logged addresses: `rollup`, `verifier`, `inbox`, `outbox`, `feeJuicePortal`, `slasher`,
289
+ `rewardBooster`, `escapeHatch`, `payload`, `newFlushRewarder`, `version`.
290
+
291
+ Re-run the checks against the deployed contracts at any time:
292
+
293
+ ```bash
294
+ forge script ... --sig 'verify(address)' <rollup>
295
+ forge script ... --sig 'verifyFlushRewarder(address,address)' <rollup> <payload>
296
+ forge script script/deploy/V6UpgradeSimulation.sol:V6UpgradeSimulation \
297
+ --sig 'simulate(address)' <payload> --rpc-url $RPC
298
+ ```
299
+
300
+ Sanity-check by hand that the rollup is inert and correctly owned:
301
+
302
+ ```bash
303
+ cast call <rollup> "getEscapeHatch()(address)" --rpc-url $RPC # ZERO until the payload executes
304
+ cast call <payload> "ESCAPE_HATCH()(address)" --rpc-url $RPC # the hatch it will install
305
+ cast call <rollup> "owner()(address)" --rpc-url $RPC # governance, from construction
306
+ cast call <rollup> "getVersion()(uint256)" --rpc-url $RPC # not already in the registry
307
+
308
+ # the rollup uses the pinned verifier. `verify` does not check this, and the verifier is immutable,
309
+ # so a wrong one cannot be fixed after the payload executes. The two hashes must be equal
310
+ # (HonkVerifier has no immutables, so its runtime code is exactly the compiled artifact).
311
+ cast call <rollup> "getEpochProofVerifier()(address)" --rpc-url $RPC # == the logged verifier
312
+ cast code <verifier> --rpc-url $RPC | cast keccak
313
+ forge inspect script/deploy/HonkVerifier.sol:HonkVerifier deployedBytecode | cast keccak
314
+
315
+ # the payload is bound to the rollup it succeeds; must equal the OUTGOING rollup, not the new one
316
+ cast call <payload> "PREDECESSOR()(address)" --rpc-url $RPC
317
+ cast call $REG "getCanonicalRollup()(address)" --rpc-url $RPC
318
+
319
+ # the proof-of-possession gas cap the payload will set on the GSE
320
+ cast call <payload> "PROOF_OF_POSSESSION_GAS_LIMIT()(uint64)" --rpc-url $RPC # 300000
321
+ ```
322
+
323
+ ## 6. Governance proposal
324
+
325
+ Propose the **payload address**, not the rollup. `GovernanceProposer` wraps it in a `GSEPayload`
326
+ automatically. After proposing, read the exact timings off the proposal rather than assuming:
327
+
328
+ ```bash
329
+ cast call <governance> "getProposal(uint256)" <id> --rpc-url $RPC
330
+ ```
331
+
332
+ On mainnet the configured delays are long (voting delay, then voting duration, then execution
333
+ delay — on the order of weeks in total), so expect the proposal to sit before it is executable.
334
+
335
+ Before execution, re-run the reservation-headroom and `rewardsAvailable` checks from step 3. Both
336
+ can move while the proposal is pending: the canonical rollup's reward claims draw the implicit pool
337
+ down, and `rewardsAvailable` is read at execution time. A non-zero or growing
338
+ `totalEarmarkedBalance` on its own is not a reason to hold the execution; see step 3.
339
+
340
+ ### Executing on mainnet: office hours only
341
+
342
+ The mainnet payload will only execute **Monday to Friday, 08:00–17:00 London**, DST included —
343
+ 08:00–17:00 UTC in winter, 07:00–16:00 UTC in summer. Outside that the window check (action 2) reverts and
344
+ the whole execution rolls back, including the `Executed` flag, so the proposal stays executable and
345
+ can simply be retried when the window next opens. Nothing is consumed by a rejected attempt.
346
+
347
+ Check before sending, rather than discovering it from a revert:
348
+
349
+ ```bash
350
+ # true when the window is open right now
351
+ cast call <payload> "isWithinExecutionWindow(uint256)(bool)" $(date +%s) --rpc-url $RPC
352
+
353
+ # and confirm the chain agrees the restriction applies
354
+ cast call <payload> "ENFORCE_EXECUTION_WINDOW()(bool)" --rpc-url $RPC
355
+ ```
356
+
357
+ The longest closed stretch is Friday 17:00 to Monday 08:00, well inside the grace period, so the
358
+ window cannot strand a proposal on its own. Sepolia is unrestricted.
359
+
360
+ ### Before signalling or voting, check the payload is still live
361
+
362
+ The payload only authorises a transition **from** the rollup that was canonical when it was
363
+ deployed, and it refuses to execute once that is no longer true. Both halves are readable on-chain,
364
+ and both should be checked before anything is committed to:
365
+
366
+ ```bash
367
+ # (a) the guard is actually in the action list — expect assertPredecessorIsCanonical first
368
+ cast call <payload> "getActions()((address,bytes)[])" --rpc-url $RPC
369
+
370
+ # (b) the rollup it is bound to is still canonical — these two must be equal
371
+ cast call <payload> "PREDECESSOR()(address)" --rpc-url $RPC
372
+ cast call $REG "getCanonicalRollup()(address)" --rpc-url $RPC
373
+ ```
374
+
375
+ A registration payload without that guard is the hazard the guard exists to remove: registration is
376
+ append-only with last-write-wins and `execute` is permissionless, so an accepted-but-abandoned
377
+ payload can be executed by anyone later and demote whatever replaced it — permanently, since
378
+ neither the registry nor the GSE re-admits a rollup it already holds.
379
+
380
+ **The consequence, which is intended but worth stating.** Once *any* other registration executes,
381
+ this payload is dead: it can never execute, even if its proposal was accepted and is still inside
382
+ its grace period. Registering v6 then requires deploying a fresh payload — which picks up the new
383
+ canonical rollup as its `PREDECESSOR` — and taking it through the full governance cycle again. So a
384
+ patched replacement for a bad v6 is not a quick swap; budget the whole cycle for it.
385
+
386
+ ## 7. After execution
387
+
388
+ ```bash
389
+ cast call $REG "getCanonicalRollup()(address)" --rpc-url $RPC # the new rollup
390
+ cast call $RD "canonicalRollup()(address)" --rpc-url $RPC # follows automatically
391
+ cast call <rollup> "getActiveAttesterCount()(uint256)" --rpc-url $RPC # inherits the bonus bucket
392
+ cast call $ROLLUP "getActiveAttesterCount()(uint256)" --rpc-url $RPC # outgoing rollup, expect 0
393
+ cast call <newFlushRewarder> "rewardsAvailable()(uint256)" --rpc-url $RPC
394
+
395
+ # the reservation: total distributor balance UNCHANGED, the amount moved between buckets
396
+ cast call $TOKEN "balanceOf(address)(uint256)" $RD --rpc-url $RPC # same as before
397
+ cast call $RD "totalEarmarkedBalance()(uint256)" --rpc-url $RPC # up by the amount
398
+ cast call $RD "specificRecipientBalance(address)(uint256)" $ROLLUP --rpc-url $RPC # up by the amount
399
+ cast call $TOKEN "balanceOf(address)(uint256)" <payload> --rpc-url $RPC # 0
400
+
401
+ # the retune, read off the OUTGOING rollup: (distributor, 7000, booster, 50e18)
402
+ cast call $ROLLUP "getRewardConfig()((address,uint32,address,uint96))" --rpc-url $RPC
403
+
404
+ # the proof-of-possession gas cap, shared by every rollup on the GSE
405
+ cast call $GSE "proofOfPossessionGasLimit()(uint64)" --rpc-url $RPC # 300000
406
+ ```
407
+
408
+ The distributor's **total balance not moving** is the check that matters for the reservation: the
409
+ funds change bucket, they do not leave. If the total fell, something claimed rather than earmarked.
410
+
411
+ The outgoing rollup dropping to **exactly 0** is expected, not a fault: every mainnet attester is
412
+ registered against the bonus instance (`moveWithLatestRollup = true`), and the bonus instance is
413
+ only visible to whichever rollup is currently canonical.
414
+
415
+ ## Deliberately not done
416
+
417
+ - **Protocol fee recipient and margin.** The rollup launches with `protocolFeeMarginBps = 0` and
418
+ `protocolFeeRecipient` set to a placeholder address. Both are `onlyOwner`, so they now require a
419
+ governance proposal. **Set the recipient before, or in the same payload as, any non-zero
420
+ margin** — otherwise the protocol fee tranche is transferred to an unrecoverable address on
421
+ every claim. The first margin increase is exempt from the 30-day cooldown but capped at
422
+ 5000 bps by the ×3/2 step on the fee multiplier.
423
+ - **Reward distributor migration.** Not needed: the distributor resolves the canonical rollup live
424
+ off the registry, so its implicit pool follows v6 the moment action 7 (`Registry.addRollup`)
425
+ executes. Balances earmarked to other addresses, including the reservation for the outgoing
426
+ rollup, stay with their recipients and are not part of what v6 inherits.
427
+ - **Registry address pinning.** `REGISTRY_ADDRESS` is an unvalidated env input. Everything else —
428
+ fee asset, staking asset, GSE, governance, reward distributor — is derived from it, so a wrong
429
+ registry silently changes all of them together. Double-check it on the command line.
430
+
431
+ ## Do not renounce ownership of the outgoing rollup
432
+
433
+ Retired rollups have had ownership renounced in the past. Two things break if that is done here:
434
+
435
+ - the outgoing `FlushRewarder` keeps its unclaimed `debt` and must stay callable for
436
+ `claimRewards()`;
437
+ - `updateStakingQueueConfig` is the only way to recover a rollup whose entry queue is wedged, and
438
+ it is `onlyOwner`.
439
+
440
+ Mainnet's outgoing rollup is already `isBootstrapped = true`, so its queue still flushes at
441
+ 1 validator/epoch from zero and it remains restartable. Renouncing ownership removes the fallback.
@@ -0,0 +1,113 @@
1
+ # V6UpgradePayload — what governance is being asked to approve
2
+
3
+ A single-use payload that makes the v6 rollup canonical, and nothing else. Deployed by
4
+ `script/deploy/DeployRollupForUpgradeV6.s.sol`; executed once, by governance, weeks later.
5
+
6
+ This is the reviewer's map. The contract's NatSpec carries the detail — this says what the payload
7
+ intends, what it guarantees, and what it deliberately leaves alone.
8
+
9
+ ## The actions, in order
10
+
11
+ Governance runs each as `target.call(data)` from its own address, in this order, in one transaction.
12
+
13
+ | # | Action | Present when | Why |
14
+ |---|---|---|---|
15
+ | 1 | `this.assertPredecessorIsCanonical()` | always | this payload only authorises a transition **from** the rollup that was canonical when it was deployed |
16
+ | 2 | `this.assertWithinExecutionWindow()` | `ENFORCE_EXECUTION_WINDOW` | mainnet only: UK weekdays 08:00–17:00 London, so an upgrade is not executed unattended |
17
+ | 3 | `distributor.recoverFrom(v5, payload, EARMARK_AMOUNT)` | `EARMARK_AMOUNT > 0` | draws the reservation for the outgoing rollup while it can still reach the implicit pool |
18
+ | 4 | `this.forwardEarmark()` | `EARMARK_AMOUNT > 0` | parks it in the outgoing rollup's own earmarked bucket |
19
+ | 5 | `v5.setRewardConfig(...)` | `RETUNE_PREDECESSOR_REWARDS` | retunes the outgoing rollup's reward split |
20
+ | 6 | `v6.setEscapeHatch(ESCAPE_HATCH)` | always | installs the escape hatch, before v6 is canonical |
21
+ | 7 | `Registry.addRollup(v6)` | always | makes v6 canonical |
22
+ | 8 | `GSE.addRollup(v6)` | always | existing attesters follow without withdrawing and redepositing |
23
+ | 9 | `oldFlushRewarder.recover(asset, newRewarder, rewardsAvailable())` | a rewarder exists | carries the entry-queue flush incentive to the replacement |
24
+ | 10 | `GSE.setProofOfPossessionGasLimit(PROOF_OF_POSSESSION_GAS_LIMIT)` | `PROOF_OF_POSSESSION_GAS_LIMIT > 0` | raises the cap on BLS proof-of-possession verification so honest keys with an expensive verification are not refunded and dropped |
25
+
26
+ Four to ten actions depending on chain. Sepolia has neither the window nor a rewarder.
27
+
28
+ Action 10 depends on nothing above it, and nothing above depends on it: the cap is only read when an
29
+ entry queue is flushed, which cannot happen inside this transaction. It goes last so the other
30
+ actions keep their positions whether or not it is present. The GSE is shared, so the new cap also
31
+ applies to the outgoing rollup's flushes from the moment the payload executes.
32
+
33
+ ## What it guarantees
34
+
35
+ - **Only the approved transition.** `PREDECESSOR` is read from the registry in the constructor and
36
+ compared at execution. If any other registration lands first, this payload can never execute.
37
+ - **All or nothing.** `Governance.execute` requires success per action inside one transaction, so a
38
+ failed check leaves *nothing* behind — not a registration, not a moved GSE, not a moved balance.
39
+ This holds regardless of where in the list the failure happens.
40
+ - **It stays readable when it is dead.** Both checks are actions rather than reverts inside
41
+ `getActions()`, so explorers, `GSEPayload.amIValid` and the deploy simulation can still read what
42
+ the payload would do after it can no longer do it.
43
+ - **The deploy key holds no power over v6, at any point.** The rollup is constructed owned by
44
+ governance rather than transferred afterwards. That matters beyond ownership: the same
45
+ constructor argument becomes the Slasher's immutable `GOVERNANCE`, which can slash any attester
46
+ with no vote and no delay, and `transferOwnership` cannot move it. Constructing with governance
47
+ is what keeps it out of the deploy key's hands — at the cost of the escape hatch having to be
48
+ installed here, by governance, rather than during the deploy.
49
+
50
+ ## What it deliberately does not do
51
+
52
+ - **No reward-distributor migration.** The distributor resolves the canonical rollup live off the
53
+ registry, so its implicit pool follows v6 the moment `Registry.addRollup` executes.
54
+ - **No protocol fee margin or recipient.** The rollup launches with margin `0` and a placeholder
55
+ recipient. Both are `onlyOwner` and now need their own proposal. **Set the recipient before, or
56
+ in the same payload as, any non-zero margin**, or the fee tranche goes to an unrecoverable
57
+ address on every claim.
58
+ - **It does not retire the outgoing rollup.** Its ownership must NOT be renounced: the old
59
+ `FlushRewarder` keeps unclaimed debt and must stay callable, and `updateStakingQueueConfig` is the
60
+ only way to recover a wedged entry queue.
61
+
62
+ ## What to check before signalling or voting
63
+
64
+ ```bash
65
+ cast call <payload> "PREDECESSOR()(address)" # must equal the CURRENT canonical rollup
66
+ cast call $REG "getCanonicalRollup()(address)"
67
+ cast call <payload> "getActions()((address,bytes)[])" # guard must be present, and first
68
+ cast call <rollup> "owner()(address)" # governance, from construction
69
+ cast call <slasher> "GOVERNANCE()(address)" # governance -- NOT the deploy key
70
+ cast call <payload> "PROOF_OF_POSSESSION_GAS_LIMIT()(uint64)" # 300000; 0 means no cap action
71
+ cast call <gse> "proofOfPossessionGasLimit()(uint64)" # the cap it replaces, 250000 today
72
+ ```
73
+
74
+ A registration payload without that guard is the hazard the guard exists to remove.
75
+
76
+ ## Known limits, stated rather than discovered
77
+
78
+ - **Once any other registration executes, this payload is dead.** Intended — voters re-approve
79
+ "v6 succeeds X" explicitly rather than letting execution order decide — but it means a patched
80
+ replacement needs a fresh deploy and a full governance cycle, not a quick swap.
81
+ - **Existing earmarks are left alone.** v6 inherits the implicit pool, `balance -
82
+ totalEarmarkedBalance`, and whatever is earmarked to other addresses at execution stays
83
+ earmarked to them. Earmarks are keyed by address, so a recipient that stops being canonical can
84
+ still claim its own, and governance can recover any of them via `recoverFrom`. The payload's own
85
+ reservation adds `EARMARK_AMOUNT` to v5's earmark, so `totalEarmarkedBalance` is non-zero after
86
+ execution by design. `subsidizeAddress` is permissionless but cannot shrink the implicit pool: it
87
+ raises the balance and the earmarked total by the same amount. The only thing that can make the
88
+ reservation revert is the implicit pool plus v5's existing earmark falling below
89
+ `EARMARK_AMOUNT` by execution.
90
+ - **The execution window hardcodes the UK DST rule.** Derived from the rule rather than tabulated,
91
+ so it has no expiry — but it would be wrong if the rule itself changed.
92
+ - **The proof-of-possession gas cap is checked against the GSE only at deployment.** The constructor
93
+ rejects a non-zero value that does not exceed the cap it reads then, since a lower cap would start
94
+ rejecting keys that verify today. If governance changes the cap while the proposal is pending,
95
+ the action still sets the value in the payload. It sets no upper bound: the value is a reviewed
96
+ literal in the deploy table, and a higher cap only raises what a failing entry can burn in a flush.
97
+ It also does not make every honest key fit: the verification cost has an unbounded tail, so 300k
98
+ lowers the rejection rate (about 1 in 2.5M keys, against 1 in 28.6k at 250k, under Osaka pricing)
99
+ rather than removing it.
100
+ - **`REGISTRY_ADDRESS` is an unvalidated deploy input.** Everything else is derived from it, so a
101
+ wrong registry changes all of them together and silently.
102
+
103
+ ## Where things are
104
+
105
+ | | |
106
+ |---|---|
107
+ | Contract | `src/periphery/V6UpgradePayload.sol` |
108
+ | Unit tests — actions, constructor, calendar | `test/periphery/V6UpgradePayload.t.sol` |
109
+ | Atomicity through real governance | `test/governance/scenario/V6UpgradeAtomicity.t.sol` |
110
+ | Deploy script and its config table | `script/deploy/DeployRollupForUpgradeV6.s.sol` |
111
+ | Config table deployed on both chains | `test/script/DeployRollupForUpgradeV6.t.sol` |
112
+ | Fork simulation of the full lifecycle | `script/deploy/V6UpgradeSimulation.sol` |
113
+ | How to run the upgrade | `script/deploy/V6_UPGRADE_RUNBOOK.md` |