Cumulus Runtime 升级机制深度揭秘Parachain 如何与 Relay Chain 协同完成 WASM 升级【免费下载链接】cumulusWrite Parachains on Substrate项目地址: https://gitcode.com/gh_mirrors/cum/cumulusCumulus 是构建 Substrate Parachain平行链的核心框架其 Runtime 升级机制是 Parachain 开发者必须掌握的关键能力Parachain 无法像独立链一样热替换WASM Runtime而是必须与 Relay Chain中继链严格协同通过提交代码 → 中继链确认 → GoAhead 信号 → 写入 :code的完整流程完成安全升级。本文将完整拆解这套机制的 5 个关键步骤、核心存储字段与安全保障设计帮助新手快速理解 Parachain Runtime 升级的底层原理。为什么 Parachain 的 Runtime 升级不一样在独立链上调用sudo_set_code提交新的 WASM 二进制下一区块即可生效。但 Parachain 的 Runtime也称Validation Function验证函数会被 Relay Chain 的验证节点拿去校验候选区块Candidate因此升级必须满足一个铁律Relay Chain 上的验证函数 与 Parachain 状态中的 Runtime必须在同一个 Relay 区块高度同步替换。如果两边不同步可能出现Parachain 已用新 Runtime 出块而 Relay Chain 仍用旧 Runtime 校验的致命分叉。Cumulus 的解决方案位于 pallets/parachain-system/src/lib.rs 中的cumulus-pallet-parachain-system它承担了文档中明确列出的职责之一coordinating upgrades with the Relay Chain与 Relay Chain 协调升级。升级流程全景图5 个关键步骤步骤 1在 Parachain 上提交新 WASM 代码Parachain 的frame_system的OnSetCode被替换为ParachainSetCode见ParachainSetCode的SetCodetrait 实现位于 pallets/parachain-system/src/lib.rs它不会直接写入代码而是调用schedule_code_upgrade做三重检查检查项失败错误含义Relay Chain 未下达升级禁令ProhibitedByPolkadotRelay Chain 通过UpgradeRestrictionSignal禁止了本次升级没有进行中的升级OverlappingUpgrades已有一个PendingValidationCode等待执行代码体积不超过max_code_sizeTooBigWASM 编译产物超出 Relay Chain 允许的体积上限此外Cumulus 还支持两阶段授权升级适合无法直接把完整 WASM 放入链上交易的场景Root 调用authorize_upgrade(code_hash, check_version)仅登记新 Runtime 的哈希任何人调用enact_authorized_upgrade(code)提交完整代码前像校验哈希一致若check_versiontrue还会通过can_set_code校验 spec name 未变且 spec version 递增通过后才真正调度升级。该交易还支持ValidateUnsigned验证允许以无签名交易提交。检查通过后触发ValidationFunctionStored事件升级进入已存储状态。步骤 2双份写入——同时通知 Relay Chain 与自身schedule_code_upgrade的核心是两处同步写入notify_polkadot_of_pending_upgrade(code)写入NewValidationCode存储并置位DidSetValidationCode。Collator 在构建候选区块时会通过collect_collation_info读取NewValidationCode并填入CollationInfo.new_validation_code最终由 client/collator/src/service.rs 随候选区块一起提交给 Relay Chain——这就是通知 Polkadot的实际通道。PendingValidationCode::put(code)在 Parachain 本地暂存新代码等待 Relay Chain 的许可才会真正替换 Runtime。步骤 3Relay Chain 排期与冷却期Relay Chain 收到携带新验证函数的候选区块后会按其自身的升级排期包含validation_upgrade_delay延迟期与validation_upgrade_cooldown冷却期见HostConfiguration字段在指定 Relay 区块执行升级。在这段窗口期内其他 Parachain 的升级可能被UpgradeRestriction信号暂时禁止防止升级风暴你的schedule_code_upgrade会因ProhibitedByPolkadot直接失败。步骤 4等待 GoAhead 信号自动生效每个 Parachain 区块都包含set_validation_data固有交易inherent它携带 Relay 父区块的状态证明。在 pallets/parachain-system/src/lib.rs 的该交易处理逻辑中Runtime 会从状态证明中读取UpgradeGoAhead信号GoAhead取出PendingValidationCode调用put_parachain_code将新 WASM 写入存储中的:code键sp_core::storage::well_known_keys::CODE触发on_validation_code_applied钩子并广播ValidationFunctionApplied { relay_chain_block_num }事件——从下一个区块起新 Runtime 正式生效Abort删除PendingValidationCode广播ValidationFunctionDiscarded事件升级被取消无信号维持等待状态。on_finalize中还会清理UpgradeGoAhead与UpgradeRestrictionSignal标记为 ephemeral不会持久化保证信号不跨区块残留。步骤 5验证升级是否成功通过事件链即可全程审计UpgradeAuthorized → ValidationFunctionStored → ValidationFunctionApplied若在等待期被 Relay Chain 叫停则看到ValidationFunctionDiscarded。相关存储字段还包括LastRelayChainBlockNumber、HostConfiguration等均可通过链上查询接口核对。核心存储字段速查表存储字段作用NewValidationCode通知 Collator/Relay Chain 的新代码每区块开始时清理PendingValidationCode本地暂存的待生效代码收到 GoAhead 后写入:codeUpgradeGoAheadRelay Chain 放行/中止升级的镜像信号临时值UpgradeRestrictionSignalRelay Chain 的升级禁令镜像临时值AuthorizedUpgrade两阶段授权升级中登记的code_hash与check_versionDidSetValidationCode标记本区块是否已通知 Relay Chain 有待升级代码存储版本的迁移逻辑如LastUpgrade字段被信号机制取代的历史见 pallets/parachain-system/src/migration.rs。实战验证Zombienet 自动化测试 项目内置了完整的升级端到端测试测试脚本 zombienet/tests/0004-runtime_upgrade.zndsl 的执行流程非常直观注册 Parachain → 出块 → 用 spec version 递增后的 WASM 执行 upgrade → 确认链继续正常出块并配合 zombienet/tests/runtime_upgrade.js 校验升级结果。这为新手提供了可复现的升级演练环境。常见失败原因与排查现象原因TooBig新 Runtime 编译产物超过 Relay Chain 的max_code_size需精简依赖OverlappingUpgrades上一次升级尚未结束未收到 GoAhead/Abort先等待信号落地ProhibitedByPolkadotRelay Chain 处于升级限制窗口稍后重试Unauthorizedenact_authorized_upgrade提交的代码哈希与authorize_upgrade登记的不一致总结Cumulus 的 Runtime 升级机制用本地暂存 双端同步 信号确认三步曲优雅解决了 Parachain 与 Relay Chain 的升级一致性问题✅schedule_code_upgrade统一入口 三重校验杜绝非法升级✅NewValidationCode/PendingValidationCode双存储分别面向 Relay Chain 与自身✅ GoAhead/Abort 信号驱动保证同一 Relay 区块高度原子化切换✅ 全程事件可审计ValidationFunctionStored→ValidationFunctionApplied支持两阶段授权升级降低提交风险。理解这套机制后你就能安全、可验证地为 Parachain 规划每一次 WASM Runtime 升级了。【免费下载链接】cumulusWrite Parachains on Substrate项目地址: https://gitcode.com/gh_mirrors/cum/cumulus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考