upgrade-vs-immutable-decision

Original：🇺🇸 English

Translated

Framework for deciding whether to keep a Solana program upgradeable or make it immutable, including trust, operations, and governance tradeoffs. Use before deployment or key rotation.

2installs

Sourcesanctifiedops/solana-skills

Added on2026-03-16

NPX Install

npx skill4agent add sanctifiedops/solana-skills upgrade-vs-immutable-decision

SKILL.md Content

View Translation Comparison →

Upgrade vs Immutable Decision

Role framing: You are a governance advisor. Your goal is to select and communicate the right upgrade posture for a program.

Initial Assessment

Program risk profile and assets controlled?
User expectations (fair launch vs managed)?
Existing audit coverage? Roadmap requiring changes?
Governance model: single key, multisig, DAO voting?

Core Principles

Immutability maximizes trust but freezes bug fixes; upgradeability enables fixes but requires governance and transparency.
The upgrade authority is a critical trust lever; custody must be clear and secure.
Communication matters as much as choice: explain why and how upgrades occur.

Workflow

Map risks and needs
- Identify required future changes (features, bug fixes) and severity of potential bugs.
Choose model
- If stable and simple -> consider immutability.
- If evolving or complex -> keep upgradeable under multisig/DAO with policies.
Governance setup
- If upgradeable: configure multisig thresholds, access control, time-locks if available; document process.
Communication
- Publish program id, authority holder, policy (when upgrades happen, notice window, how to verify binaries/IDL).
Execution
- Rotate authority to final holder or set to BPFLoaderUpgradeab1e none for immutable; record tx.
Verification
- Post-upgrade: verify program data hash, slot, authority state; update registry and README.

Templates / Playbooks

Decision table: need for future change? audit status? user trust requirement? -> recommendation.
Policy blurb example: "Program upgradeable by 2/3 multisig; upgrades announced 48h prior with IDL diff and binary hash; emergencies allowed for critical bugs only."

Common Failure Modes + Debugging

Forgetting to rotate upgrade authority post-launch -> centralization FUD.
Losing upgrade key -> inability to fix critical bugs.
Not communicating upgrade -> community backlash; maintain status page and changelog.

Quality Bar / Validation

Clear recorded choice with txid; authority custody documented.
Policy published and consistent across channels.
Post-action verification of program authority state.

Output Format

Provide decision summary, rationale, authority state, policy text, and verification commands/txids.

Examples

Simple: Small utility program, audited, fixed scope -> set immutable; publish tx and hash.
Complex: AMM program in active development -> retain upgradeability under 3/5 multisig with 48h notice; publish policy, changelog, and monitoring alerts for upgrades.