經(jīng)常有朋友問(wèn)我Polkadot SDK也就是以前的Substrate到底怎么上手尤其是想把一條平行鏈跑起來(lái)卻不知道從哪一步開始。網(wǎng)上教程一堆但要么太老要么是照著文檔念一遍真正自己動(dòng)手的時(shí)候全是坑。這篇文章就是我反復(fù)搭環(huán)境、編譯、跑通測(cè)試網(wǎng)之后整理出來(lái)的一份可以照著抄的完整流程希望能幫你少走點(diǎn)彎路。先說(shuō)清楚這篇文章要解決什么問(wèn)題。Polkadot SDK本身是一個(gè)區(qū)塊鏈開發(fā)框架平行鏈模板則是官方準(zhǔn)備的一個(gè)“差不多能用的鏈”它已經(jīng)接好了共識(shí)、P2P網(wǎng)絡(luò)、賬戶系統(tǒng)、余額模塊、權(quán)限治理模塊等一堆基礎(chǔ)功能。你要做的不是從零寫一條鏈而是把這個(gè)模板拿過(guò)來(lái)編譯成一條真正能跑的平行鏈節(jié)點(diǎn)然后和Rococo測(cè)試網(wǎng)或者本地中繼鏈連接上。整個(gè)過(guò)程涉及工具鏈配置、代碼編譯、鏈配置、節(jié)點(diǎn)啟動(dòng)、平行鏈注冊(cè)等環(huán)節(jié)每個(gè)環(huán)節(jié)都有不少容易踩的坑。這篇文章適合兩類人一類是完全沒(méi)碰過(guò)Rust和Substrate但想用Polkadot SDK做開發(fā)的人另一類是已經(jīng)跑過(guò)獨(dú)立Substrate節(jié)點(diǎn)但對(duì)“平行鏈”這層概念還比較模糊想把連接中繼鏈這步徹底搞明白的人。我會(huì)盡量把每一步背后的原因也講清楚而不只是告訴你“敲這個(gè)命令”。1. 項(xiàng)目設(shè)計(jì)與核心思路拆解1.1 為什么用模板而不是從零寫鏈剛接觸Polkadot生態(tài)時(shí)我也有過(guò)“從零手寫一條鏈”的想法試過(guò)之后才發(fā)現(xiàn)完全沒(méi)必要。平行鏈本質(zhì)上是一條“插進(jìn)中繼鏈”的區(qū)塊鏈它的區(qū)塊頭要提交給中繼鏈驗(yàn)證所以除了普通區(qū)塊鏈的共識(shí)、存儲(chǔ)、交易池之外還得實(shí)現(xiàn)平行鏈特定的接口比如驗(yàn)證人怎么校驗(yàn)?zāi)愕膮^(qū)塊、出塊人怎么從中繼鏈拿到可用性數(shù)據(jù)。這些東西如果自己寫光是把接口定義理解清楚就得花不少時(shí)間。官方提供的平行鏈模板polkadot-sdk倉(cāng)庫(kù)里的substrate-parachain-template現(xiàn)在叫parachain-template已經(jīng)把這些問(wèn)題都處理好了。它默認(rèn)實(shí)現(xiàn)了CollatorSelection收集人選擇和Session會(huì)話管理兩個(gè)關(guān)鍵pallet也就是說(shuō)你拿到的模板已經(jīng)具備“跑起來(lái)然后注冊(cè)成平行鏈”的基礎(chǔ)條件。直接基于它改能夠把所有精力放在業(yè)務(wù)邏輯上。這里也順帶提一個(gè)重要的選擇用polkadot-sdk而不是老版本的substrate。Polkadot SDK是2024年以后的統(tǒng)一版本號(hào)發(fā)布方式以前分的substrate、polkadot、cumulus三個(gè)倉(cāng)庫(kù)合并成了一個(gè)倉(cāng)庫(kù)。查資料時(shí)如果看到2023年之前的文檔很多路徑和依賴名稱都對(duì)不上這點(diǎn)必須有心理準(zhǔn)備。1.2 模板整體架構(gòu)速覽拿到的模板代碼大致分為三層最底層是runtime封裝了鏈上的業(yè)務(wù)邏輯比如余額怎么轉(zhuǎn)賬、質(zhì)押怎么結(jié)算、Staking怎么驗(yàn)證全部以pallet的形式掛載在runtime里。中間層是node節(jié)點(diǎn)負(fù)責(zé)把runtime跑起來(lái)處理網(wǎng)絡(luò)、同步、交易池之類的底層工作最終生成一個(gè)可執(zhí)行文件。最上層是pallets自定義業(yè)務(wù)模塊默認(rèn)會(huì)有一個(gè)template示例pallet方便你往里面添加自己的邏輯。這個(gè)概念怎么理解呢你可以把runtime想象成一臺(tái)手表的機(jī)芯決定“時(shí)間怎么計(jì)算”而節(jié)點(diǎn)是表殼和指針負(fù)責(zé)把機(jī)芯展示出來(lái)。平時(shí)你開發(fā)業(yè)務(wù)就是在機(jī)芯里面加零件節(jié)點(diǎn)層基本不用動(dòng)。2. 環(huán)境準(zhǔn)備與工具鏈安裝2.1 Rust工具鏈的具體配置方法Polkadot SDK是Rust寫的所以你首先得裝Rust。我建議用rustup來(lái)管理版本選擇上別用最新的stable而是用官方推薦的nightly-2024-XX-XX某個(gè)固定版本。理由很實(shí)在Polkadot SDK的編譯依賴許多只有nightly才有的特性但最新nightly又經(jīng)常引入不兼容的改動(dòng)所以官方模板里會(huì)鎖定一個(gè)測(cè)試過(guò)的nightly版本。打開模板目錄或下載好代碼后里面有個(gè)文件叫rust-toolchain.toml內(nèi)容大概是這樣[toolchain] channel nightly-2024-03-01 components [rustfmt, clippy] targets [wasm32-unknown-unknown] profile minimal這個(gè)文件告訴rustup進(jìn)入當(dāng)前目錄時(shí)自動(dòng)切換到你鎖定的nightly版本。所以推薦的做法是先把官方模板克隆下來(lái)再執(zhí)行rustup安裝不要自己手動(dòng)選版本。如果已經(jīng)裝了其他版本也沒(méi)關(guān)系rustup會(huì)按需下載。執(zhí)行安裝curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup show執(zhí)行rustup show會(huì)按照rust-toolchain.toml自動(dòng)下載對(duì)應(yīng)工具鏈。這一步可能需要幾分鐘取決于網(wǎng)絡(luò)狀況。另外提醒一句編譯wasm需要wasm32-unknown-unknown目標(biāo)這個(gè)目標(biāo)不能少否則后面編譯runtime會(huì)直接報(bào)錯(cuò)找不到目標(biāo)。2.2 系統(tǒng)依賴與資源預(yù)估編譯Polkadot SDK內(nèi)存吃得很兇代碼編譯期的峰值內(nèi)存可以達(dá)到8GB到16GB。建議虛擬機(jī)或云服務(wù)器至少4核8GB起步16GB會(huì)更穩(wěn)。磁盤方面一個(gè)release編譯目標(biāo)目錄大概會(huì)占10到15GB預(yù)留30GB以上比較穩(wěn)妥。系統(tǒng)依賴是另一個(gè)容易卡住的點(diǎn)。Ubuntu/Debian上執(zhí)行apt update apt install -y git clang curl libssl-dev protobuf-compiler build-essentialmacOS上需要保證Xcode Command Line Tools已經(jīng)安裝同時(shí)用Homebrew安裝protobuf和clangxcode-select --install brew install protobuf clang這里重點(diǎn)說(shuō)一下protobuf-compiler。Polkadot SDK在編譯過(guò)程中會(huì)用到Prost生成Rust的protobuf代碼如果系統(tǒng)里沒(méi)有protoc編譯到某個(gè)依賴時(shí)就會(huì)莫名其妙地報(bào)protoc: not found或者failed to execute protoc。這個(gè)錯(cuò)誤很常見但排錯(cuò)方向卻很少被人提及先把protobuf裝好能免掉一個(gè)大麻煩。2.3 源碼獲取與依賴加速獲取模板代碼最直接的方式是直接克隆官方倉(cāng)庫(kù)git clone https://github.com/paritytech/polkadot-sdk.git但polkadot-sdk整個(gè)倉(cāng)庫(kù)體積非常大如果沒(méi)有特殊需求建議只拉取模板子目錄。官方也提供了模板的獨(dú)立模板倉(cāng)庫(kù)substrate-parachain-template的歷史版本但要注意版本匹配。我更推薦的做法是克隆polkadot-sdk然后切到模板目錄下工作因?yàn)檫@樣能保證使用的依賴代碼版本和自己倉(cāng)庫(kù)的同步更新一致后續(xù)升級(jí)依賴時(shí)也不容易出錯(cuò)。依賴下載靠cargo從crates.io拉在國(guó)內(nèi)網(wǎng)絡(luò)下慢得讓人絕望。強(qiáng)烈建議配置~/.cargo/config.toml使用國(guó)內(nèi)鏡像源比如字節(jié)跳動(dòng)的鏡像[source.crates-io] replace-with rsproxy-sparse [source.rsproxy-sparse] registry sparsehttps://rsproxy.cn/index/另外polkadot-sdk里有一些依賴是GitHub依賴不走crates.io所以如果拉取時(shí)卡住還得結(jié)合代理或者多試幾次。這里提醒一下不要在公網(wǎng)上討論代理工具但本地開發(fā)時(shí)自己做好網(wǎng)絡(luò)加速是完全合理的工程實(shí)踐。3. 模板結(jié)構(gòu)解析與核心文件說(shuō)明3.1 頂層目錄分布我把負(fù)責(zé)人目錄列出來(lái)這樣進(jìn)入倉(cāng)庫(kù)之后你能快速找到方向。parachain-template/ ├── node/ │ ├── src/ │ │ ├── command.rs # CLI入口和參數(shù)解析 │ │ ├── rpc.rs # RPC接口 │ │ ├── chain_spec.rs # 鏈配置初始賬戶、初始token、初始收集人 │ │ ├── service.rs # 節(jié)點(diǎn)服務(wù)組裝最重要文件之一 │ │ └── main.rs ├── pallets/ │ └── template/ ├── runtime/ │ └── src/ │ ├── lib.rs # runtime組裝文件所有pallet都要在這掛載 │ ├── config.rs # 各pallet的Config實(shí)現(xiàn) │ ├── genesis_config.rs # 創(chuàng)世配置 │ └── weights.rs # 權(quán)重計(jì)算 ├── specs/ # 鏈的規(guī)格文件 ├── rust-toolchain.toml └── Cargo.toml一眼看過(guò)去最需要關(guān)心的是runtime/src/lib.rs、runtime/src/config.rs、node/src/chain_spec.rs這三個(gè)文件。模板自帶的所有能力、初始配置基本都在這幾個(gè)文件里。3.2 關(guān)鍵文件的作用很多人剛拿到代碼時(shí)會(huì)問(wèn)為什么平行鏈需要這么多配置文件普通的一條鏈不是編譯完就直接跑嗎這里說(shuō)一下根本原因。平行鏈需要向中繼鏈注冊(cè)自己的“身份”中繼鏈要驗(yàn)證它、要給它分配平行鏈編號(hào)、要讓它接入共享安全。所以在啟動(dòng)和連接的整個(gè)過(guò)程中需要一份描述自己是誰(shuí)、初始狀態(tài)是什么的ChainSpec文件。同時(shí)因?yàn)槠叫墟湹某鰤K邏輯依賴中繼鏈的驗(yàn)證人集合所以節(jié)點(diǎn)的服務(wù)邏輯service.rs會(huì)比普通節(jié)點(diǎn)復(fù)雜得多。chain_spec.rs里需要重點(diǎn)關(guān)注這幾個(gè)部分parachain_id你的平行鏈在中繼鏈上的編號(hào)比如2000。collator賬號(hào)負(fù)責(zé)出塊的收集人至少要有幾個(gè)初始賬號(hào)。sudo賬號(hào)擁有超級(jí)權(quán)限用來(lái)執(zhí)行注冊(cè)、升級(jí)、轉(zhuǎn)賬等治理操作。endowed_accounts初始擁有token的賬戶列表。這些值不只是一堆配置它們會(huì)直接影響你能不能成功出塊、能不能進(jìn)行后續(xù)的升級(jí)操作。后面實(shí)操部分我會(huì)具體演示怎么改。3.3 為什么默認(rèn)是“收集人”而不是“驗(yàn)證人”這是初學(xué)平行鏈時(shí)最?；煜母拍?。普通鏈有驗(yàn)證人負(fù)責(zé)打包和驗(yàn)證區(qū)塊但平行鏈自己不維護(hù)一條“完整驗(yàn)證人鏈”它的出塊節(jié)點(diǎn)叫“收集人”Collator。收集人的職責(zé)是從交易池拿交易聚合出區(qū)塊再把區(qū)塊頭和有效性證明提交給中繼鏈的驗(yàn)證人。中繼鏈上的驗(yàn)證人負(fù)責(zé)做最終校驗(yàn)。所以模板的service.rs里運(yùn)行的是收集人節(jié)點(diǎn)而不是驗(yàn)證人節(jié)點(diǎn)。啟動(dòng)命令也是polkadot-parachain這樣的節(jié)點(diǎn)其實(shí)模板的二進(jìn)制就叫parachain-template-node它與中繼鏈節(jié)點(diǎn)連接時(shí)是通過(guò)“平行鏈-中繼鏈”專用的共識(shí)協(xié)議的。這一點(diǎn)如果沒(méi)理解透很可能在配置節(jié)點(diǎn)時(shí)下意識(shí)去找“驗(yàn)證人密鑰”但找半天也找不到正確配置。4. 編譯全流程與常見報(bào)錯(cuò)處理4.1 第一次編譯前的編譯選項(xiàng)在項(xiàng)目根目錄執(zhí)行cargo build --release第一次編譯WebAssembly和native代碼大概需要40分鐘到1小時(shí)時(shí)間長(zhǎng)短主要取決于CPU性能也有一部分磁盤IO影響。官方文檔建議使用--release這會(huì)讓二進(jìn)制小很多、運(yùn)行效率高很多。如果只是想快速檢查代碼是否編譯通過(guò)可以用cargo check --release只需驗(yàn)證類型和依賴不產(chǎn)生最終二進(jìn)制會(huì)快很多。我在第一次編譯時(shí)遇到最多的是“內(nèi)存不足”。如果當(dāng)前機(jī)器只有8GB內(nèi)存建議臨時(shí)增加swap交換分區(qū)否則編譯到一半會(huì)被Linux的OOM Killer殺掉。增加swap的方法fallocate -l 8G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile注意這只是開發(fā)環(huán)境下的臨時(shí)方案生產(chǎn)環(huán)境還是得保證足夠內(nèi)存。編譯過(guò)程中還有一點(diǎn)容易被忽視就是CPU核心數(shù)過(guò)高反而可能出問(wèn)題。Cargo默認(rèn)會(huì)占用所有可用核心但在一些云服務(wù)器上多核心編譯反而因?yàn)閮?nèi)存不夠而頻繁觸發(fā)交換。這里可以用一個(gè)參數(shù)限制并發(fā)cargo build --release -j 8這樣能限制同時(shí)編譯的任務(wù)數(shù)量減少內(nèi)存峰值。我自己實(shí)測(cè)下來(lái)16GB內(nèi)存的機(jī)器用默認(rèn)并行度沒(méi)問(wèn)題8GB內(nèi)存建議限制到-j4或-j8。4.2 被頻繁踩坑的編譯報(bào)錯(cuò)及定位方法我整理了一份高頻報(bào)錯(cuò)表幫你在卡住時(shí)快速定位報(bào)錯(cuò)信息出現(xiàn)原因解決辦法failed to run custom build command for ... libp2p缺少protocapt install protobuf-compiler或brew install protobuffailed to select a version for ...依賴版本沖突檢查Cargo.toml依賴版本和Cargo.lock是否匹配刪除Cargo.lock后重新生成thewasm32-unknown-unknowntarget is not installed缺wasm目標(biāo)rustup target add wasm32-unknown-unknowntoolchain nightly-... is not installedrust-toolchain沒(méi)生效執(zhí)行rustup show確認(rèn)自動(dòng)安裝手動(dòng)rustup toolchain install nightly-xxxxcannot find attribute macroconstruct_runtimein this scoperuntime版本不匹配或宏導(dǎo)入錯(cuò)誤檢查Cargo.toml中substrate-wasm-builder和frame的版本清理后重編recursion limit reached while expanding the macro依賴宏遞歸過(guò)深在對(duì)應(yīng)lib.rs或主入口加#![recursion_limit 256]報(bào)錯(cuò)信息只是個(gè)線索真正排錯(cuò)時(shí)要多看日志前幾百行上下文。比如failed to run custom build command之后往往有一大堆上一級(jí)依賴信息排查時(shí)從最底層的第一個(gè)error開始解決不要從最上面的warning開始。4.3 二進(jìn)制產(chǎn)物的驗(yàn)證編譯完成后在target/release下會(huì)有一個(gè)parachain-template-node可執(zhí)行文件或者polkadot-parachain取決于模板名稱。執(zhí)行./target/release/parachain-template-node --version如果輸出版本號(hào)比如parachain-template-node 0.1.0說(shuō)明本地代碼和工具鏈基本正常接下來(lái)可以生成鏈規(guī)格和啟動(dòng)節(jié)點(diǎn)。5. 平行鏈的啟動(dòng)與連接中繼鏈5.1 生成鏈規(guī)格ChainSpec平行鏈啟動(dòng)前要生成一份描述創(chuàng)世狀態(tài)的JSON文件它包含初始賬戶、初始余額、初始收集人列表等信息。生成命令是./target/release/parachain-template-node build-spec --disable-default-bootnode plain-parachain.json--disable-default-bootnode非常重要如果不加生成的規(guī)格里會(huì)包含一堆模板自帶的默認(rèn)節(jié)點(diǎn)官方測(cè)試節(jié)點(diǎn)這些節(jié)點(diǎn)在國(guó)內(nèi)網(wǎng)絡(luò)環(huán)境下根本連不通會(huì)拖慢啟動(dòng)過(guò)程。生成完之后可以打開JSON看一眼搜索parachainId確認(rèn)編號(hào)是否符合預(yù)期。默認(rèn)可能不是2000可以根據(jù)后續(xù)中繼鏈要求改。建議在生成時(shí)直接指定鏈名或編號(hào)比如./target/release/parachain-template-node build-spec --disable-default-bootnode --chain mychain mychain-spec.json但這一步只能改部分配置要在創(chuàng)世就注入自己的賬戶最可靠的方式還是直接改chain_spec.rs源碼后重新編譯或者用build-spec生成后手動(dòng)修改JSON里genesis下的字段。5.2 本地中繼鏈還是公共測(cè)試網(wǎng)連接中繼鏈有兩條路一條是連官方公共測(cè)試網(wǎng)Rococo另一條是本地起一條中繼鏈用polkadot二進(jìn)制配合rococo-custom或dev鏈。對(duì)初學(xué)者我更推薦先本地起一條中繼鏈來(lái)練兵。本地中繼鏈的好處太多了出塊速度可控一般設(shè)為2秒或6秒一個(gè)塊出問(wèn)題好排查。擁有sudo權(quán)限可以自己執(zhí)行平行鏈注冊(cè)、轉(zhuǎn)交中繼鏈token等操作。不會(huì)因?yàn)楣矞y(cè)試網(wǎng)上的排隊(duì)、資源不足影響你的研發(fā)節(jié)奏。本地方案的步驟如下構(gòu)建或下載一個(gè)polkadot的release二進(jìn)制中繼鏈節(jié)點(diǎn)。生成中繼鏈規(guī)格指定一個(gè)或兩個(gè)驗(yàn)證人。啟動(dòng)中繼鏈節(jié)點(diǎn)。構(gòu)建平行鏈節(jié)點(diǎn)并啟動(dòng)它。在中繼鏈上注冊(cè)平行鏈通過(guò)sudo調(diào)用registrar.registerParachain。這里中繼鏈的二進(jìn)制可以直接從官方Release頁(yè)面下載預(yù)編譯版本也可以自己用cargo build --release -p polkadot編譯但耗時(shí)比平行鏈本身還長(zhǎng)所以首次就別自己折騰了。5.3 啟動(dòng)平行鏈節(jié)點(diǎn)并連接本地中繼鏈先啟動(dòng)中繼鏈。用預(yù)生成的rococo-custom-2.json兩個(gè)驗(yàn)證人或dev模式。如果只用單驗(yàn)證人可以執(zhí)行polkadot --chain rococo-custom-2.json --alice --tmp --port 30333 --rpc-port 9944這里的--alice會(huì)為Alice預(yù)置驗(yàn)證人密鑰--tmp指定臨時(shí)數(shù)據(jù)目錄每次重啟會(huì)清空狀態(tài)。重新開一個(gè)終端啟動(dòng)平行鏈節(jié)點(diǎn)./target/release/parachain-template-node \ --alice \ --collator \ --force-authoring \ --tmp \ --port 40333 \ --rpc-port 8844 \ --ws-port 9945 \ -- --execution wasm \ --chain /path/to/relay-chain-spec.json \ --port 30344 \ --rpc-port 9946 \ --tmp注意這條命令中有個(gè)非常容易忽略的細(xì)節(jié)在--后面指定的是中繼鏈相關(guān)參數(shù)--前面的參數(shù)是平行鏈自身參數(shù)。平行鏈節(jié)點(diǎn)實(shí)際上是一個(gè)“二元節(jié)點(diǎn)”既要跑自己的平行鏈邏輯又要作為全節(jié)點(diǎn)連接中繼鏈所以有兩組參數(shù)。很多新手在日志里看到大量中繼鏈同步信息卻看不到自己的區(qū)塊生產(chǎn)多半就是這兩組參數(shù)混在一起導(dǎo)致的。啟動(dòng)之后如果一切正常日志里會(huì)出現(xiàn) Idle空閑中等待交易或Prepared block for proposing說(shuō)明平行鏈運(yùn)行起來(lái)了但還沒(méi)有真正開始出塊因?yàn)橹欣^鏈上還沒(méi)注冊(cè)它。5.4 通過(guò)Polkadot JS注冊(cè)平行鏈并轉(zhuǎn)交充值注冊(cè)這一步核心操作是通過(guò)中繼鏈的registrar模塊的registerParachain調(diào)用完成。操作時(shí)要持有中繼鏈上的sudo賬號(hào)通常是Alice。流程是打開Polkadot JS Apps連接到中繼鏈RPC本地ws://127.0.0.1:9944。在Developer-Extrinsics中找到registrar的registerParachain。填入平行鏈ID與前面ChainSpec里的ID一致比如2000。填入平行鏈的創(chuàng)世狀態(tài)genesis state和驗(yàn)證人代碼validation code也就是runtime編譯出來(lái)的wasm。這兩個(gè)數(shù)據(jù)怎么拿需要用到平行鏈節(jié)點(diǎn)提供的RPC對(duì)應(yīng)兩個(gè)調(diào)用# 獲取創(chuàng)世狀態(tài) curl http://127.0.0.1:8844 -H Content-Type: application/json -d {jsonrpc:2.0,method:chain_getBlock,params:[],id:1}不過(guò)更直接的方法是平行鏈節(jié)點(diǎn)自己提供了一種便捷命令來(lái)導(dǎo)出創(chuàng)世狀態(tài)和wasm# 導(dǎo)出創(chuàng)世狀態(tài) ./target/release/parachain-template-node export-genesis-state genesis-state # 導(dǎo)出wasm驗(yàn)證代碼 ./target/release/parachain-template-node export-genesis-wasm genesis-wasm把兩個(gè)文件內(nèi)容填到Polkadot JS的對(duì)應(yīng)字段里就完成了注冊(cè)。這里有個(gè)細(xì)節(jié)如果文件內(nèi)容是二進(jìn)制格式Polkadot JS有時(shí)不接受需要轉(zhuǎn)成hex格式。可以用xxd -p genesis-wasm | tr -d \n轉(zhuǎn)換。完成注冊(cè)后等待幾個(gè)區(qū)塊平行鏈就會(huì)開始出塊。再回到平行鏈節(jié)點(diǎn)的日志可以看到開頭的出塊日志說(shuō)明平行鏈已經(jīng)從“準(zhǔn)備中”變成了“運(yùn)行中”。6. 自定義平行鏈模板加一個(gè)屬于自己的pallet6.1 為什么必須先跑通模板再加業(yè)務(wù)很多朋友一上來(lái)就想在模板里加自己的業(yè)務(wù)邏輯結(jié)果連基礎(chǔ)鏈都沒(méi)跑通出了問(wèn)題根本分不清是模板問(wèn)題還是自己代碼問(wèn)題。我個(gè)人強(qiáng)烈建議的路徑是先原封不動(dòng)編譯、跑通、注冊(cè)再去添加業(yè)務(wù)。等到模板跑通之后業(yè)務(wù)添加就相對(duì)自由了。最簡(jiǎn)單的方式是在pallets/template里改這個(gè)目錄已經(jīng)寫好了Extrinsic的示例你可以順著它的寫法定義自己的Call、Storage、Event。6.2 修改chain_spec設(shè)置初始賬戶如果想讓某個(gè)賬戶在創(chuàng)世時(shí)就有余額需要修改node/src/chain_spec.rs里的endowed_accounts列表。找到這行類似vec![ get_account_id_from_seed::sr25519::Public(Alice), get_account_id_from_seed::sr25519::Public(Bob), ]添加你自己的地址只需要在列表里加一個(gè)SS58格式地址vec![ get_account_id_from_seed::sr25519::Public(Alice), YOUR_SS58_ADDRESS.into(), ]這里要注意地址格式。Polkadot生態(tài)的SS58地址在不同鏈上前綴不一樣平行鏈的默認(rèn)前綴是42所以添加自己的地址時(shí)保持和模板里Alice、Bob的地址前綴一樣即可5開頭的通用地址。如果你用了其他工具導(dǎo)入了地址注意檢查SS58前綴。改完重新編譯cargo build --release再用build-spec重新生成鏈規(guī)格后面注冊(cè)的創(chuàng)世狀態(tài)就會(huì)帶上這些初始余額。6.3 在runtime中掛載自定義pallet的流程如果你想完全新建一個(gè)pallet而不是改示例步驟如下第一步在pallets/下創(chuàng)建新目錄比如pallets/my_pallet仿照pallets/template寫好Cargo.toml、src/lib.rs。第二步在自己的pallet的Cargo.toml里保持依賴版本和workspace一致。這一步最容易出錯(cuò)因?yàn)閜olkadot-sdk統(tǒng)一使用workspace true的方式引用依賴新建的pallet也會(huì)自動(dòng)繼承workspace。如果版本不一致比如frame-support使用了default-features false卻沒(méi)同時(shí)開啟std編譯時(shí)就會(huì)遇到一堆trait未實(shí)現(xiàn)錯(cuò)誤。第三步在runtime/Cargo.toml加上對(duì)應(yīng)的依賴格式參照現(xiàn)有的pallet-template。第四步在runtime/src/lib.rs里用construct_runtime!宏注冊(cè)。格式construct_runtime!( pub enum Runtime { ... MyPallet: pallet_my_pallet, } );最后在runtime/src/config.rs如果你的模板版本是在單獨(dú)的config.rs文件里實(shí)現(xiàn)Config中實(shí)現(xiàn)pallet_my_pallet::Config通常寫一個(gè)空實(shí)現(xiàn)就夠了比如impl pallet_my_pallet::Config for Runtime { type RuntimeEvent RuntimeEvent; }重新編譯檢查是否通過(guò)。如果通過(guò)說(shuō)明你的pallet已經(jīng)成功掛載可以開始在里面寫業(yè)務(wù)了。7. 常見問(wèn)題排查與調(diào)試技巧7.1 區(qū)塊高度不增長(zhǎng)這是最常見的現(xiàn)象。平行鏈注冊(cè)完成日志卻一直是Idle不出塊。排查思路按順序來(lái)先確認(rèn)中繼鏈?zhǔn)欠裾３鰤K。如果中繼鏈卡住了平行鏈也不可能出塊。然后看平行鏈的區(qū)塊頭是否已提交給中繼鏈。打開Polkadot JS進(jìn)入Parachains-Overview如果顯示你的平行鏈“是”出塊狀態(tài)說(shuō)明正常如果顯示“準(zhǔn)備中”說(shuō)明注冊(cè)還沒(méi)生效或驗(yàn)證人沒(méi)被分配到。再看平行鏈節(jié)點(diǎn)日志中是否有Could not create proposal如果有多半是交易池有無(wú)效交易或構(gòu)建區(qū)塊時(shí)補(bǔ)了無(wú)效的Runtime調(diào)用。檢查錢包余額。平行鏈需要在中繼鏈上有一定的余額來(lái)支付注冊(cè)和出塊手續(xù)費(fèi)如果你的平行鏈賬戶被清空了它可能無(wú)法繼續(xù)提交區(qū)塊頭。大部分情況下問(wèn)題出在中繼鏈驗(yàn)證人的抵押數(shù)量不夠或者平行鏈賬戶沒(méi)有足夠的token來(lái)支付“抵押存款”。解決方法是在中繼鏈上給平行鏈賬戶轉(zhuǎn)賬或者以sudo身份修改平行鏈相關(guān)的存款參數(shù)。7.2 驗(yàn)證人收不到平行鏈狀態(tài)有時(shí)中繼鏈節(jié)點(diǎn)日志顯示一切正常但平行鏈就是不被認(rèn)可。這時(shí)可以先看RPCcurl http://127.0.0.1:9944 -H Content-Type: application/json -d {jsonrpc:2.0,method:chain_getHeader,params:[],id:1}如果中繼鏈返回正常的head信息但平行鏈節(jié)點(diǎn)返回的head始終停留在一個(gè)高度那說(shuō)明平行鏈出塊后沒(méi)有把區(qū)塊頭廣播給中繼鏈。重點(diǎn)檢查平行鏈啟動(dòng)命令中--后面的中繼鏈規(guī)格文件是否使用了--chain指定了正確的中繼鏈。如果平行鏈并不知道自己連接的是哪條中繼鏈它無(wú)法正確上傳塊頭。另外如果用了多個(gè)--tmp參數(shù)容易造成平行鏈和中繼鏈的數(shù)據(jù)目錄混亂出現(xiàn)奇怪的連接問(wèn)題。建議每個(gè)節(jié)點(diǎn)都顯式指定數(shù)據(jù)目錄--base-path /tmp/parachain-alice中繼鏈節(jié)點(diǎn)同樣指定--base-path /tmp/relay-alice避免多個(gè)進(jìn)程共用一個(gè)臨時(shí)目錄報(bào)沖突。7.3 同步卡住或者大量“Import failed”同步卡住通常表現(xiàn)為區(qū)塊高度停滯或日志刷屏。優(yōu)先看是否遇到“bad justification”或“dispute”。這往往是因?yàn)槠叫墟満椭欣^鏈的runtime版本不匹配。舉個(gè)具體的例子中繼鏈升級(jí)了新版本而平行鏈的驗(yàn)證人代碼wasm還是老版本導(dǎo)致驗(yàn)證人校驗(yàn)不一致。解決方法是重新生成平行鏈的wasm并更新到中繼鏈注冊(cè)時(shí)直接使用新的wasm而不是沿用舊文件。注意平行鏈的wasm文件大小是否合理如果生成出來(lái)很小幾百字節(jié)很可能沒(méi)有正確導(dǎo)出wasm需要重新查編譯路徑。7.4 日志級(jí)別調(diào)整排查問(wèn)題時(shí)默認(rèn)日志不夠詳細(xì)可以把日志級(jí)別調(diào)高RUST_LOGparachain_templatedebug,pallet_collator_selectiondebug,auradebug,consensusdebug ./target/release/parachain-template-node ...但這些模塊名在不同版本里有細(xì)微差異建議先執(zhí)行一次RUST_LOGdebug看輸出再針對(duì)性縮小范圍。日志調(diào)優(yōu)能省下大量猜測(cè)時(shí)間這條經(jīng)驗(yàn)真的重要。8. 模板的二開經(jīng)驗(yàn)分享走到這里你已經(jīng)擁有了一條能出塊的平行鏈無(wú)論是連本地中繼鏈還是Rococo都能跑通。下面是我在二開過(guò)程中的一點(diǎn)體會(huì)。模板默認(rèn)帶的業(yè)務(wù)非常少只有余額、權(quán)限、資產(chǎn)、示例pallet這些基礎(chǔ)功能。真正做應(yīng)用時(shí)你會(huì)想往里加更多模塊比如NFT、DeFi、游戲道具等。這時(shí)候建議維護(hù)兩個(gè)分支一個(gè)upstream分支只跟蹤官方SDK的更新另一個(gè)develop分支存放自己的業(yè)務(wù)代碼。每次官方更新了bug修復(fù)或新版本把upstream合并到develop解決完沖突再繼續(xù)開發(fā)。別在模板主分支直接寫業(yè)務(wù)否則后續(xù)升級(jí)依賴時(shí)會(huì)很痛苦。依賴升級(jí)的時(shí)間點(diǎn)也值得講究。不要一看到有新版本就立刻升而是要認(rèn)真看changelog。如果只是修復(fù)了某個(gè)pallet的bug或優(yōu)化了性能可以先不升如果涉及安全補(bǔ)丁或新的共識(shí)機(jī)制比如異步支持、新的彈性擴(kuò)容那就值得花時(shí)間升。實(shí)測(cè)中最穩(wěn)妥的方式是每三四個(gè)月統(tǒng)一升一次每次留出1到2天的兼容性調(diào)試時(shí)間。最后再分享一個(gè)小技巧。如果你打算長(zhǎng)期做Polkadot SDK開發(fā)本地建議預(yù)先構(gòu)建一份編譯緩存就是第一次完整編譯后不要輕易清掉target目錄也不要頻繁切換nightly版本。Rust的增量編譯在這里效果雖然一般但依賴緩存總比重頭拉取強(qiáng)太多。每次切版本或清target少則半小時(shí)多則一整天這筆時(shí)間成本實(shí)在不劃算。整個(gè)過(guò)程走完差不多就能理解平行鏈在Polkadot生態(tài)里的定位了。它和中繼鏈的關(guān)系就像一臺(tái)臺(tái)業(yè)務(wù)服務(wù)器接入了一個(gè)統(tǒng)一的共享共識(shí)網(wǎng)絡(luò)。模板給了你骨架剩下的血肉需要你自己去長(zhǎng)。編譯、連接、注冊(cè)、二開每一步都有坑但每跨過(guò)一個(gè)坑你對(duì)這套系統(tǒng)的理解就深一層。遇到問(wèn)題時(shí)多留心排查路徑的先后順序大多數(shù)問(wèn)題其實(shí)都能靠日志定位到根因。