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.