AgentSkillsCN

upgrade-vs-immutable-decision

在决定Solana程序是否应保持可升级性，还是转为不可变时，需综合考量信任、运营与治理之间的权衡取舍。在部署前或密钥轮换之前，这一决策尤为重要。

SKILL.md
--- frontmatter
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

  1. •Map risks and needs
    • •Identify required future changes (features, bug fixes) and severity of potential bugs.
  2. •Choose model
    • •If stable and simple -> consider immutability.
    • •If evolving or complex -> keep upgradeable under multisig/DAO with policies.
  3. •Governance setup
    • •If upgradeable: configure multisig thresholds, access control, time-locks if available; document process.
  4. •Communication
    • •Publish program id, authority holder, policy (when upgrades happen, notice window, how to verify binaries/IDL).
  5. •Execution
    • •Rotate authority to final holder or set to BPFLoaderUpgradeab1e none for immutable; record tx.
  6. •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.