diff --git a/.github/ISSUE_TEMPLATE/pdpverifier-upgrade.md b/.github/ISSUE_TEMPLATE/pdpverifier-upgrade.md index 236a84a7..923caa75 100644 --- a/.github/ISSUE_TEMPLATE/pdpverifier-upgrade.md +++ b/.github/ISSUE_TEMPLATE/pdpverifier-upgrade.md @@ -12,24 +12,26 @@ Track the successive rollout of `PDPVerifier` from `vA.B.C` to `vX.Y.Z`, with Ca This issue is the full operational checklist for the rollout and release closeout. +## Rollout Status + +| Network | Announced | Executable on or after | Executed | Notes | +| --- | --- | --- | --- | --- | +| Calibration | Pending | TBD | Pending | Upgrade first; fill in the planned-upgrade transaction and timestamp when announced. | +| Mainnet | Pending | TBD | Pending | Upgrade after Calibration execution and smoke tests pass. | + ## Operational Notes - Use this single issue to track the full rollout across both networks. +- Confirm the live proxy `VERSION()` separately; it may lag the release baseline if recent releases did not include a PDPVerifier deployment. - Record major steps as issue comments as you go rather than editing every detail into the top post. - The live proxy already supports planned upgrades, first use `tools/announce-planned-upgrade.sh`, wait until the announced epoch, then use `tools/upgrade.sh`. - Do not deploy until all bytecode-affecting PRs are merged to `main`. -- Tag the exact deployed commit first if you want the git tag to match the on-chain bytecode exactly. -- If changelog-only updates happen after deploy, commit them after tagging. +- If the release tag must match the exact on-chain bytecode, tag the deploy commit before changelog-only closeout changes. Otherwise, tag the finalized release-notes commit and record the implementation deploy commit separately. - The current `tools/deploy-calibnet.sh` and `tools/deploy-mainnet.sh` also deploy a fresh proxy. For upgrades, the safest path is still: - deploy the implementation manually with `forge create` - generate SAFE calldata with `tools/upgrade.sh` - `tools/upgrade.sh` prints the SAFE contract's on-chain nonce. The Safe UI may queue the transaction at a higher nonce if there are already pending transactions. That does not change the contract calldata. -Suggested PR titles: -- Changelog draft: `docs(changelog): draft vX.Y.Z release notes` -- Changelog finalization: `docs(changelog): finalize vX.Y.Z release notes` -- Issue-template update: `docs: update PDPVerifier upgrade issue template` - Suggested release tag: - `vX.Y.Z` @@ -40,10 +42,23 @@ Suggested release tag: - SAFE owner: `0x3569b2600877a9F42d9Ebdd205386F3F3788F3E5` - Mainnet RPC: `https://api.node.glif.io/rpc/v1` - Calibration RPC: `https://api.calibration.node.glif.io/rpc/v1` +- Default planned-upgrade notice window: `2880` epochs (~1 day at 30 seconds/epoch) ## Release Preparation -### 1. Freeze the Deploy Commit +### 1. Prepare and Merge Release PRs + +- [ ] Release-prep PR opened and reviewed + - Include the `PDPVerifier.VERSION` bump if the deployed contract version is changing. + - Draft `CHANGELOG.md` release notes before deployment. + - Use `## [X.Y.Z] - TBD` until the rollout executes. + - Leave implementation addresses, verification links, and deployment transactions as `TBD` until known. + - Include expected integration impact, constructor values, and any required caller changes before starting Calibration. + - Suggested PR title: `docs(changelog): draft vX.Y.Z release notes and version bump` +- [ ] Release-prep PR merged to `main` + - Any `PDPVerifier.VERSION` bump is bytecode-affecting and must be merged before selecting the deploy commit or deploying any implementation. + +### 2. Freeze the Deploy Commit - [ ] Final deploy commit on `main` confirmed @@ -60,13 +75,11 @@ git rev-parse HEAD rg -n 'string public constant VERSION' src/PDPVerifier.sol ``` -### 2. Confirm Constructor Values +### 3. Confirm Constructor Values - [ ] Calibration constructor values confirmed - [ ] `initializerVersion` - - [ ] `USDFC_TOKEN_ADDRESS` - - [ ] `USDFC_SYBIL_FEE` - - [ ] `PAYMENTS_CONTRACT_ADDRESS` + - [ ] `challengeFinality` - [ ] Current Calibration proxy initializer counter read ```bash @@ -76,9 +89,7 @@ RPC_URL="https://api.calibration.node.glif.io/rpc/v1" \ - [ ] Mainnet constructor values confirmed - [ ] `initializerVersion` - - [ ] `USDFC_TOKEN_ADDRESS` - - [ ] `USDFC_SYBIL_FEE` - - [ ] `PAYMENTS_CONTRACT_ADDRESS` + - [ ] `challengeFinality` - [ ] Current Mainnet proxy initializer counter read ```bash @@ -86,12 +97,13 @@ RPC_URL="https://api.node.glif.io/rpc/v1" \ ./tools/get-initialized-counter.sh 0xBADd0B92C1c71d02E7d520f64c0876538fa2557F ``` -If the command returns `1`, deploy the next implementation with `initializerVersion = 2`. +Deploy the next implementation with `initializerVersion = `. -### 3. Confirm the Live Proxy Owner and Version +### 4. Confirm the Live Proxy Owner and Version - [ ] Current Calibration proxy owner confirmed - [ ] Current Calibration proxy version confirmed +- [ ] Current Calibration planned-upgrade slot checked ```bash cast call --rpc-url https://api.calibration.node.glif.io/rpc/v1 \ @@ -102,10 +114,15 @@ cast call --rpc-url https://api.calibration.node.glif.io/rpc/v1 \ cast call --rpc-url https://api.calibration.node.glif.io/rpc/v1 \ 0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C \ "VERSION()(string)" + +cast call --rpc-url https://api.calibration.node.glif.io/rpc/v1 \ + 0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C \ + "nextUpgrade()(address,uint96)" ``` - [ ] Current Mainnet proxy owner confirmed - [ ] Current Mainnet proxy version confirmed +- [ ] Current Mainnet planned-upgrade slot checked ```bash cast call --rpc-url https://api.node.glif.io/rpc/v1 \ @@ -116,6 +133,10 @@ cast call --rpc-url https://api.node.glif.io/rpc/v1 \ cast call --rpc-url https://api.node.glif.io/rpc/v1 \ 0xBADd0B92C1c71d02E7d520f64c0876538fa2557F \ "VERSION()(string)" + +cast call --rpc-url https://api.node.glif.io/rpc/v1 \ + 0xBADd0B92C1c71d02E7d520f64c0876538fa2557F \ + "nextUpgrade()(address,uint96)" ``` If the owner is a SAFE or other contract owner, use `tools/upgrade.sh` to generate calldata for the owner workflow rather than broadcasting directly. @@ -138,19 +159,15 @@ forge create \ --chain-id 314159 \ src/PDPVerifier.sol:PDPVerifier \ --constructor-args \ - 2 \ - 0xb3042734b608a1B16e9e86B374A3f3e389B4cDf0 \ - 100000000000000000 \ - 0x09a0fDc2723fAd1A7b8e3e00eE5DF73841df55a0 + \ + 10 ``` - [ ] Sanity-check `VERSION()` and immutable values on the Calibration implementation ```bash cast call --rpc-url "$RPC_URL" "VERSION()(string)" -cast call --rpc-url "$RPC_URL" "USDFC_TOKEN_ADDRESS()(address)" -cast call --rpc-url "$RPC_URL" "USDFC_SYBIL_FEE()(uint256)" -cast call --rpc-url "$RPC_URL" "PAYMENTS_CONTRACT_ADDRESS()(address)" +cast call --rpc-url "$RPC_URL" "getChallengeFinality()(uint256)" ``` - [ ] Verify the Calibration implementation on Sourcify @@ -158,11 +175,9 @@ cast call --rpc-url "$RPC_URL" "PAYMENTS_CONTRACT_ADDRESS()(address)" - [ ] Verify the Calibration implementation on Filfox (optional) ```bash -CONSTRUCTOR_ARGS=$(cast abi-encode "constructor(uint64,address,uint256,address)" \ - 2 \ - 0xb3042734b608a1B16e9e86B374A3f3e389B4cDf0 \ - 100000000000000000 \ - 0x09a0fDc2723fAd1A7b8e3e00eE5DF73841df55a0 | sed 's/^0x//') +CONSTRUCTOR_ARGS=$(cast abi-encode "constructor(uint64,uint256)" \ + \ + 10 | sed 's/^0x//') forge verify-contract \ --chain 314159 \ @@ -189,6 +204,33 @@ filfox-verifier forge \ --chain 314159 ``` +- [ ] Calibration planned-upgrade announcement payload generated + +Choose an `AFTER_EPOCH` that satisfies the required notice window and will still be in the future when the Safe transaction executes. The default notice window is `2880` Filecoin epochs (~1 day); adjust intentionally if the release needs a longer window. + +```bash +CURRENT=$(cast block-number --rpc-url "$RPC_URL") +NOTICE_EPOCHS=2880 +AFTER_EPOCH=$((CURRENT + NOTICE_EPOCHS)) + +RPC_URL="$RPC_URL" \ +SAFE_ADDRESS="0x3569b2600877a9F42d9Ebdd205386F3F3788F3E5" \ +PDP_VERIFIER_PROXY_ADDRESS="0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C" \ +NEW_PDP_VERIFIER_IMPLEMENTATION_ADDRESS="" \ +AFTER_EPOCH="$AFTER_EPOCH" \ +./tools/announce-planned-upgrade.sh +``` + +If the Safe UI asks whether to use the implementation ABI for the proxy, use the implementation ABI, but keep the transaction target as the proxy. + +- [ ] Stage the Calibration planned-upgrade SAFE transaction +- [ ] Execute the Calibration planned-upgrade SAFE transaction +- [ ] Record the Calibration planned-upgrade announcement transaction hash and update the rollout status table +- [ ] Confirm `nextUpgrade()` matches `` and `AFTER_EPOCH` +- [ ] Wait until the chain reaches `AFTER_EPOCH` + +Optional parallel work while waiting: deploy and verify the Mainnet implementation, then stage the Mainnet planned-upgrade announcement with an `AFTER_EPOCH` after the Calibration window. Do not generate, stage, or execute the final Mainnet `upgradeToAndCall` payload until the Calibration upgrade executes and smoke tests pass. + - [ ] Calibration SAFE upgrade transaction payload generated - If SAFE/contract-owner helper changes are needed first: `tools: support SAFE-owned PDP upgrades` @@ -215,9 +257,12 @@ If building the transaction via the Safe UI ABI form: - [ ] Calibration implementation address, verification links, and calldata shared for independent review - [ ] Stage the Calibration SAFE transaction - [ ] Confirm the Calibration execution window +- [ ] Confirm `nextUpgrade()` still matches `` and `AFTER_EPOCH` +- [ ] Confirm current epoch is greater than or equal to `AFTER_EPOCH` - [ ] Execute the Calibration SAFE upgrade transaction in the Safe UI - [ ] Verify the Calibration proxy implementation slot - [ ] Verify the Calibration proxy is on `vX.Y.Z` +- [ ] Verify `nextUpgrade()` cleared to the zero address and `0` ```bash cast rpc --rpc-url https://api.calibration.node.glif.io/rpc/v1 \ @@ -229,6 +274,10 @@ cast rpc --rpc-url https://api.calibration.node.glif.io/rpc/v1 \ cast call --rpc-url https://api.calibration.node.glif.io/rpc/v1 \ 0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C \ "VERSION()(string)" + +cast call --rpc-url https://api.calibration.node.glif.io/rpc/v1 \ + 0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C \ + "nextUpgrade()(address,uint96)" ``` - [ ] Run lightweight read-only smoke tests on Calibration @@ -275,14 +324,14 @@ Check that: - the old and new pagination calls agree - `findPieceIdsByCid()` returns the expected piece ID(s) -- [ ] Post Calibration completion/update communication +- [ ] Record Calibration result in an issue comment; send external update if needed - If release notes need to be drafted or refreshed first: `docs(changelog): draft vX.Y.Z release notes` - [ ] Confirm no blocker remains for Mainnet rollout ## Mainnet Rollout -- [ ] Calibration rollout completed successfully -- [ ] Draft and send initial upgrade communication +- [ ] Calibration rollout completed successfully, including smoke tests +- [ ] Send rollout communication if not already covered by the planned-upgrade announcement - If release notes need to be drafted or refreshed first: `docs(changelog): draft vX.Y.Z release notes` - [ ] Deploy the new `PDPVerifier` implementation to Mainnet - Record deployer address, implementation address, and deployment transaction hash @@ -300,19 +349,15 @@ forge create \ --chain-id 314 \ src/PDPVerifier.sol:PDPVerifier \ --constructor-args \ - 2 \ - 0x80B98d3aa09ffff255c3ba4A241111Ff1262F045 \ - 100000000000000000 \ - 0x23b1e018F08BB982348b15a86ee926eEBf7F4DAa + \ + 150 ``` - [ ] Sanity-check `VERSION()` and immutable values on the Mainnet implementation ```bash cast call --rpc-url "$RPC_URL" "VERSION()(string)" -cast call --rpc-url "$RPC_URL" "USDFC_TOKEN_ADDRESS()(address)" -cast call --rpc-url "$RPC_URL" "USDFC_SYBIL_FEE()(uint256)" -cast call --rpc-url "$RPC_URL" "PAYMENTS_CONTRACT_ADDRESS()(address)" +cast call --rpc-url "$RPC_URL" "getChallengeFinality()(uint256)" ``` - [ ] Verify the Mainnet implementation on Sourcify @@ -320,11 +365,9 @@ cast call --rpc-url "$RPC_URL" "PAYMENTS_CONTRACT_ADDRESS()(address)" - [ ] Verify the Mainnet implementation on Filfox (optional) ```bash -CONSTRUCTOR_ARGS=$(cast abi-encode "constructor(uint64,address,uint256,address)" \ - 2 \ - 0x80B98d3aa09ffff255c3ba4A241111Ff1262F045 \ - 100000000000000000 \ - 0x23b1e018F08BB982348b15a86ee926eEBf7F4DAa | sed 's/^0x//') +CONSTRUCTOR_ARGS=$(cast abi-encode "constructor(uint64,uint256)" \ + \ + 150 | sed 's/^0x//') forge verify-contract \ --chain 314 \ @@ -351,6 +394,33 @@ filfox-verifier forge \ --chain 314 ``` +- [ ] Mainnet planned-upgrade announcement payload generated + +Choose an `AFTER_EPOCH` that satisfies the required notice window and will still be in the future when the Safe transaction executes. The default notice window is `2880` Filecoin epochs (~1 day); adjust intentionally if the release needs a longer window. + +```bash +CURRENT=$(cast block-number --rpc-url "$RPC_URL") +NOTICE_EPOCHS=2880 +AFTER_EPOCH=$((CURRENT + NOTICE_EPOCHS)) + +RPC_URL="$RPC_URL" \ +SAFE_ADDRESS="0x3569b2600877a9F42d9Ebdd205386F3F3788F3E5" \ +PDP_VERIFIER_PROXY_ADDRESS="0xBADd0B92C1c71d02E7d520f64c0876538fa2557F" \ +NEW_PDP_VERIFIER_IMPLEMENTATION_ADDRESS="" \ +AFTER_EPOCH="$AFTER_EPOCH" \ +./tools/announce-planned-upgrade.sh +``` + +If the Safe UI asks whether to use the implementation ABI for the proxy, use the implementation ABI, but keep the transaction target as the proxy. + +- [ ] Stage the Mainnet planned-upgrade SAFE transaction +- [ ] Execute the Mainnet planned-upgrade SAFE transaction +- [ ] Record the Mainnet planned-upgrade announcement transaction hash and update the rollout status table +- [ ] Confirm `nextUpgrade()` matches `` and `AFTER_EPOCH` +- [ ] Wait until the chain reaches `AFTER_EPOCH` + +- [ ] Confirm Calibration upgrade and smoke tests completed successfully before proceeding to final Mainnet upgrade execution + - [ ] Mainnet SAFE upgrade transaction payload generated - If SAFE/contract-owner helper changes are needed first: `tools: support SAFE-owned PDP upgrades` @@ -371,9 +441,12 @@ If building the Safe transaction with ABI inputs: - [ ] Stage the Mainnet SAFE transaction - [ ] Collect SAFE signer approvals - [ ] Confirm the Mainnet execution date/time +- [ ] Confirm `nextUpgrade()` still matches `` and `AFTER_EPOCH` +- [ ] Confirm current epoch is greater than or equal to `AFTER_EPOCH` - [ ] Execute the Mainnet SAFE upgrade transaction - [ ] Verify the Mainnet proxy implementation slot - [ ] Verify the Mainnet proxy is on `vX.Y.Z` +- [ ] Verify `nextUpgrade()` cleared to the zero address and `0` ```bash cast rpc --rpc-url https://api.node.glif.io/rpc/v1 \ @@ -385,24 +458,34 @@ cast rpc --rpc-url https://api.node.glif.io/rpc/v1 \ cast call --rpc-url https://api.node.glif.io/rpc/v1 \ 0xBADd0B92C1c71d02E7d520f64c0876538fa2557F \ "VERSION()(string)" + +cast call --rpc-url https://api.node.glif.io/rpc/v1 \ + 0xBADd0B92C1c71d02E7d520f64c0876538fa2557F \ + "nextUpgrade()(address,uint96)" ``` - [ ] Publish completion/update communication ## Release Closeout -- [ ] Tag the deployed commit as `vX.Y.Z` +- [ ] Update `CHANGELOG.md` release date, deployed addresses, verification links, and deployment transactions +- [ ] Final release-note PR merged to `main` + - Suggested PR title: `docs(changelog): finalize vX.Y.Z release notes` +- [ ] Tag `vX.Y.Z` + - The tag may point at a changelog-only commit after deployment. + - Record the implementation deploy commit separately if it differs from the tag commit. ```bash git tag -a vX.Y.Z -m "vX.Y.Z" git push origin vX.Y.Z ``` -- [ ] Update `CHANGELOG.md` release date and deployed addresses -- [ ] Finalize release notes on `main` - - Suggested PR title: `docs(changelog): finalize vX.Y.Z release notes` - Prefer Blockscout links in the deployed-address section because they give a better verification view than Filfox. - [ ] Sync PDPVerifier source, ABI, and deployments in `filecoin-services` + - Pin `service_contracts/lib/pdp` to the exact PDP release tag. + - Regenerate/check the PDPVerifier ABI if needed. + - Update implementation addresses in deployment references. + - Update proxy addresses only if a proxy address actually changed. - [ ] Create follow-up issue in `fwss-subgraph` - [ ] Close this rollout issue - If the issue template needs improvement afterward: `docs: update PDPVerifier upgrade issue template` @@ -420,11 +503,10 @@ Fill these in as comments or update them here once known. - Previous implementation address: - New implementation address: - Deployment transaction hash: +- Planned-upgrade announcement transaction hash: - Constructor values: - `initializerVersion`: - - `USDFC_TOKEN_ADDRESS`: - - `USDFC_SYBIL_FEE`: - - `PAYMENTS_CONTRACT_ADDRESS`: + - `challengeFinality`: - Verification links: - Sourcify: - Blockscout: @@ -439,11 +521,10 @@ Fill these in as comments or update them here once known. - Previous implementation address: - New implementation address: - Deployment transaction hash: +- Planned-upgrade announcement transaction hash: - Constructor values: - `initializerVersion`: - - `USDFC_TOKEN_ADDRESS`: - - `USDFC_SYBIL_FEE`: - - `PAYMENTS_CONTRACT_ADDRESS`: + - `challengeFinality`: - Verification links: - Sourcify: - Blockscout: