filecoin-project / filecoin-project/solstice
Define operator-facing SWA/SRA upgrade process (runbook + scripting), learning from FWSS/PDP
- Dominant language
- Solidity
- Stars
- 0
- Forks
- 2
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 18
Description
## Context
We have an open issue for the contract-level upgrade *mechanism* (#5, proxy pattern choice), but nothing yet for the operational upgrade *process*: how does an operator actually take a code change from merged PR to a live, executed upgrade on calibnet and mainnet for SWA and SRA?
filecoin-services has already built this out for FWSS/PDPVerifier, through real operational pain (see the 2026-05-28 hotfix postmortem that led to the still-open [upgrade-hardening-decision-doc](https://github.com/FilOzone/filecoin-services/blob/main/upgrade-hardening-decision-doc.md)). We should learn from what exists there rather than rediscover the same lessons the hard way, while adapting for the fact that SWA/SRA upgrades go through the two-Safe `UnanimousGovernance` flow (both Safes approve, FIP required, held before binding) rather than FWSS's model.
## What filecoin-services has that's worth adapting
- **[`UPGRADE-CHECKLIST.md`](https://github.com/FilOzone/filecoin-services/blob/main/service_contracts/tools/UPGRADE-CHECKLIST.md)** — a phased runbook (issue/PR/branch → deploy → calibnet announce+execute → mainnet announce+execute → promote/close out), with explicit gates at each phase (storage-layout check, upgrade test suite, rollback plan, cross-repo impact, technical-owner sign-off).
- **A `Deploy Contract` GitHub Actions workflow** — `workflow_dispatch` with network/contract/dry-run inputs, so deployment is a scripted, auditable, repeatable action rather than someone running commands by hand off their own machine.
- **A release-issue-generation workflow** that auto-creates the tracking issue for a given release from a template, so every upgrade has a consistent, complete checklist instead of relying on someone remembering all the steps.
- **CI-enforced storage-layout safety** (`check_storage_layout.sh`, see #5's comment thread) as a hard gate, not just a checklist item someone can skip.
- **A live, unresolved discussion on upgrade-delay/timelock hardening** (the decision doc linked above) — worth reading even though it's not fully settled, since it lays out the tradeoffs (ramp vs. step vs. flat delay, rollback bypass, panic-module needs) that will come up again here.
## What's needed here, minimum bar
At minimum: a written set of steps an operator can follow to take an accepted SWA or SRA code change live on calibnet and mainnet, through the two-Safe governance flow, including storage-layout verification, an upgrade-specific test pass, rollback plan, and post-upgrade validation. Beyond the minimum: as much of that as possible should be scripted (deploy workflow, announce/execute automation) rather than manual, for the same reasons FWSS moved that direction.
## Open questions
- How does this interact with #5 (upgrade pattern/proxy choice) — do we need that decided first, or can the process be drafted in parallel and adapted once the mechanism lands?
- Does this belong in this repo, or in the governance repository (#8), given it's an operational runbook rather than contract code? filecoin-services keeps its runbook alongside the contracts (`service_contracts/tools/`), which argues for keeping it here too.
- Should we reuse/fork filecoin-services' actual scripts (deploy workflow, storage-layout check) directly, or build fresh ones tailored to the two-Safe flow? Related to the "shared tooling between repos" question raised in #5.
cc @wjmelements @rvagg
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.