| name | upgrade-vs-immutable-decision |
| description | 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. |
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.
