filecoin-project / filecoin-project/solstice

Define operator-facing SWA/SRA upgrade process (runbook + scripting), learning from FWSS/PDP

Open
#26 0 comments 0 reactions 1 assignee Assigned to @BigLep View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.