Back to Details

upgrade-vs-immutable-decision

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Upgrade vs Immutable Decision

可升级 vs 不可变决策

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?
  • 程序风险概况及管控的资产情况？
  • 用户预期（公平启动 vs 托管式运营）？
  • 现有审计覆盖范围？是否有需要变更的路线图？
  • 治理模式：单密钥、multisig、DAO投票？

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.
  1. 梳理风险与需求
    • 识别未来所需的变更（功能、漏洞修复）以及潜在漏洞的严重程度。
  2. 选择模式
    • 若程序稳定且逻辑简单 -> 考虑设为不可变。
    • 若程序仍在演进或逻辑复杂 -> 保留可升级性，由multisig/DAO配合相关政策管控。
  3. 治理设置
    • 若选择可升级：配置多签阈值、访问控制，若支持则设置时间锁；并记录流程文档。
  4. 沟通说明
    • 发布程序ID、权限持有者、升级政策（升级触发时机、通知窗口期、如何验证二进制文件/IDL）。
  5. 执行操作
    • 将权限轮换至最终持有者，或设置为BPFLoaderUpgradeab1e none以实现不可变；记录交易（tx）信息。
  6. 验证确认
    • 操作完成后：验证程序数据哈希、插槽（slot）、权限状态；更新注册表与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."
  • 决策表：是否需要未来变更？审计状态如何？用户信任要求？ -> 给出推荐方案。
  • 政策示例文案："程序由2/3多签控制升级；升级需提前48小时公告，附带IDL差异与二进制哈希；仅允许在紧急修复关键漏洞时例外。"

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.
  • 启动后忘记轮换升级权限 -> 引发关于中心化的质疑（FUD）。
  • 丢失升级密钥 -> 无法修复关键漏洞。
  • 未及时沟通升级事宜 -> 引发社区反对；需维护状态页面与变更日志。

Quality Bar / Validation

质量标准/验证要求

  • Clear recorded choice with txid; authority custody documented.
  • Policy published and consistent across channels.
  • Post-action verification of program authority state.
  • 明确记录决策及交易ID（txid）；权限托管情况已文档化。
  • 升级政策已发布且在各渠道保持一致。
  • 操作完成后已验证程序权限状态。

Output Format

输出格式

Provide decision summary, rationale, authority state, policy text, and verification commands/txids.
提供决策摘要、理由、权限状态、政策文本，以及验证命令/交易ID。

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.
  • 简单场景：小型工具类程序，已完成审计，范围固定 -> 设为不可变；发布交易与哈希信息。
  • 复杂场景：仍在活跃开发中的AMM程序 -> 保留可升级性，由3/5多签管控并要求48小时通知；发布政策、变更日志，并设置升级监控告警。