企业官网建设流程全解析

从独立链到Parachain：Cumulus solo-to-para迁移完全实践指南

【免费下载链接】cumulusWrite Parachains on Substrate项目地址: https://gitcode.com/gh_mirrors/cum/cumulus

Cumulus 是构建 Substrate Parachain 的官方框架。本文带你快速掌握 Cumulus solo-to-para 迁移：把一条独立运行的 Substrate 链（Solo Chain）无缝升级为 Polkadot / Kusama 中继链上的 Parachain，无需停止服务，状态完整保留。

什么是 Cumulus solo-to-para 迁移

在 Polkadot 生态中，很多项目最初以独立链（Solo Chain）形式开发测试，待功能成熟后再接入中继链成为 Parachain。问题在于：两条链的运行时（Runtime）并不相同——Parachain 版本会多出parachain-system、collator-selection、aura-ext等与中继链交互的模块。

Cumulus 为此提供了专门的 pallets/solo-to-para/ 迁移工具。它的核心思路：

• 在独立链上提交一次受保护的迁移交易（仅 root 权限可调用）；
• 交易携带两份数据：新的Parachain 运行时 Wasm和当前链的head data（头部状态）；
• 中继链确认并下发 "go-ahead" 信号后，链在新块自动切换到 Parachain 运行时，状态原样保留。

工作原理：schedule_migration 三步拆解

核心实现在 pallets/solo-to-para/src/lib.rs，只有一个外部可调用的交易：

pub fn schedule_migration(origin, code: Vec<u8>, head_data: Vec<u8>) -> DispatchResult { ensure_root(origin)?; parachain_system::Pallet::<T>::schedule_code_upgrade(code)?; Self::store_pending_custom_validation_head_data(head_data); Ok(()) }

它做了两件事，理解这两步就理解了整个迁移：

1. 调度运行时升级：调用parachain-system的schedule_code_upgrade（见 pallets/parachain-system/src/lib.rs），把 Parachain Wasm 写入PendingValidationCode存储，同时通过NewValidationCode通知中继链"我要升级了"。升级必须与中继链在同一中继链块同步生效。
2. 暂存 head data：把独立链的头部数据存入PendingCustomValidationHeadData。当parachain-system触发on_validation_code_applied事件（即中继链放行、新代码生效的那一刻），head data 才被正式应用——保证旧链状态平滑"接管"为新 Parachain 的初始状态。

迁移操作步骤：从准备到生效

第 1 步：编译 Parachain 运行时 Wasm

使用 Cumulus 提供的 parachain-template/ 模板构建运行时，产出 Wasm 二进制。注意它必须小于中继链HostConfiguration中的max_code_size上限，否则会报TooBig错误。

第 2 步：在独立链上获取 root 权限

迁移交易要求ensure_root，通常通过pallet-sudo完成（这正是该 Pallet 的Config必须依赖pallet_sudo::Config的原因）。

第 3 步：提交 schedule_migration

# 伪代码示意：通过 CLI 以 sudo 身份提交 sudo sudo_as! 或直接以 root 调用 pallet-solo-to-para schedule_migration <parachain-wasm> <solo-head-data>

提交成功后会看到CustomValidationHeadDataStored事件；中继链放行升级时再看到CustomValidationHeadDataApplied事件，迁移即完成。🎉

第 4 步：验证迁移结果

检查链上是否出现CustomValidationHeadDataApplied事件，并确认区块头中的 Parachain 状态（如ParachainHead）与迁移前独立链的 head 一致。

如何验证迁移成功：Zombienet 端到端测试

Cumulus 仓库内置了一条完整的迁移测试用例，非常适合学习验证方法：

• 网络配置：zombienet/tests/0005-migrate_solo_to_para.toml —— 启动一条 Rococo 本地中继链，并运行同一个 Parachain ID (2000) 的两套节点：eve以正确 genesis 注册为 Parachain，dave则以不同 genesis 值模拟"独立链"；
• 自动化脚本：zombienet/tests/migrate_solo_to_para.js —— 读取独立链（dave）的genesis-state，将其作为 custom head data 提交到 Parachain，然后断言：迁移后 Parachain 不会多生产区块，说明状态被正确继承而非重置。

测试断言定义在 zombienet/tests/0005-migrate_solo_to_para.zndsl：

alice: parachain 2000 is registered within 225 seconds alice: parachain 2000 block height is at least 10 within 250 seconds dave: js-script ./migrate_solo_to_para.js with "dave,2000-1,eve" within 200 seconds

想本地复现，可先获取代码：

git clone https://gitcode.com/gh_mirrors/cum/cumulus

迁移排错清单：常见错误与解决方案

⚠️ 提醒：迁移交易一经提交不可逆，务必先在本地（Rococo-local / 测试网）完整演练一遍。

相关模块与延伸阅读

• 迁移 Pallet 源码：pallets/solo-to-para/src/lib.rs
• 运行时升级核心：pallets/parachain-system/src/lib.rs
• Parachain 框架文档：docs/overview.md
• 快速上手模板：parachain-template/
• 迁移端到端测试：zombienet/tests/0005-migrate_solo_to_para.toml

掌握 Cumulus solo-to-para 迁移后，你的项目就可以从独立 Substrate 链平滑"毕业"为 Polkadot 生态中的一条正式 Parachain，安全、连续、零停机。🚀

【免费下载链接】cumulusWrite Parachains on Substrate项目地址: https://gitcode.com/gh_mirrors/cum/cumulus