去年有个朋友拉我聊说团队准备发一条自己的链问我从哪下手。我给的回答很直接去研究 Substrate别从零造轮子。后来他花了两个月真把一条带自定义业务模块的链跑起来了跟我说这个框架把造链门槛拉低了不止一个量级。Substrate 是 Parity 团队开源的区块链开发框架也是 Polkadot 底层依赖的技术。和普通区块链源码不同它是一整套可自由组合的积木节点网络、共识、账本、治理、升级全都模块化。你要做的不是从零写链而是挑选模块、配置参数、写自己的业务逻辑。这篇文章适合两类人刚入门想搞懂 Substrate 值不值得学的新手以及已经跑过 demo、想深入了解机制与避坑经验的开发者。我会从设计逻辑讲起再落到真实操作把我踩过的坑尽量交代清楚。1. 项目整体设计与核心概念拆解1.1 从造链的痛点说起传统上想发一条链无非几条路fork 比特币或以太坊的源码或者在某条现成链上发智能合约。fork 源码这条路我身边做过的团队大多叫苦不迭。老代码是围绕特定场景设计的你改一行出块逻辑可能要牵扯出同步机制、难度调整、交易池策略的一堆兼容性问题。我见过有人 fork 比特币源码后想缩短出块时间结果难度调整逻辑跟着崩光调参就折腾了一个月。另一个绕不开的问题是升级。传统区块链想升级基本只能靠分叉要协调全节点要处理社区分歧一不小心就分裂成两条链。以太坊从 PoW 转到 PoS过渡了多少年这不是技术做不到而是链本身缺乏一套原地升级的机制。智能合约方案也有天花板业务逻辑受限于合约语言性能瓶颈明显而且无法定制链本身的行为——比如你想自定义共识、控制出块间隔合约根本管不到链底层。当业务场景已经超越发 token 跑一个合约的时候你就需要一条真正属于自己的链。1.2 Substrate 的设计内核一切可插拔Substrate 的答案很直接把区块链底层的所有通用组件全部抽象成模块让你在模块之上写业务。整体架构分三层。核心客户端负责 P2P 网络、区块同步、数据库存储这些底层地基。Runtime 是区块链的状态转换函数决定了每出一个区块链上状态该怎么变化。FRAME 是一套构建 Runtime 的工具库里面是一个个可复用的 Pallet模块。我常用一个类比开餐厅。核心客户端相当于你租下的店面和水电基础设施固定不动Runtime 相当于菜单和服务流程决定了这家店的风格FRAME 里的 Pallet 就是半成品食材包——做川菜拿一个辣椒模块开甜品店拿一个糖分模块自由组合。这套设计最大的好处是业务逻辑和底层升级解耦。Runtime 会被编译成 Wasm 字节码作为链状态的一部分存到链上节点执行逻辑以链上 Wasm 为准。这意味着你的链可以通过链上治理机制更新 Runtime不需要硬分叉。这在传统区块链里几乎不可想象。1.3 对比为什么不用 fork 的方式fork 和 Substrate 的本质区别在改造成本在哪里。fork 是拿到一栋装修好的房子你每改一处都要担心承重墙能不能敲。Substrate 是一套标准化积木你要改的只是某个积木的内部结构接口保持稳定就行。Parity 官方维护了一个 node-template 模板几乎包含了主链的全套基础模块克隆下来就能跑起一条可用的开发链。之后你只需要往 Runtime 里逐步添加或替换模块要理解搭链这件事从模板开始要比从零开始容易太多。这里说句公道话Substrate 的学习曲线不算平缓涉及 Rust、Wasm、密码学、共识协议四座大山叠一起。但它把最复杂、最容易出错的底层封装得足够好让你能聚焦在业务逻辑上。我个人的判断是对于想做应用链的团队Substrate 是当前所有方案里投入产出比最高的选择。2. 核心组件与关键技术点解析2.1 Runtime 与 FRAMESubstrate 的灵魂Runtime 是整个链的决定性部分它定义了链上有哪些资产、哪些业务操作、状态怎么变化。理解一个关键点Runtime 编译成 Wasm 后同样作为链的一部分存储下来。节点跑的时候优先读链上的 Wasm而不是节点二进制里内置的那份。这条设计就引出了我之前说的能力你的链上逻辑可以在运行时被替换。新 Runtime 通过一笔特殊的升级交易提交上链后节点自动从后续区块开始使用新逻辑。不需要停链不需要协调所有节点手动换版本。想想传统区块链为了一个参数修改要吵多久的社区分歧对比很明显。FRAME 里的 Pallet 我列几个最常见的pallet_system系统基础提供账户、区块号、Nonce 管理pallet_balances账户余额与转账逻辑pallet_contracts支持 Wasm 智能合约的执行环境pallet_democracy链上民主投票治理pallet_stakingPoS 抵押与验证人选举写业务就是写一个新的 Pallet。Pallet 本质上是一组由 Rust 宏驱动的代码结构包含存储项、事件、错误和可调用函数。第 3 节我会给一个完整的代码示例。2.2 共识的组合逻辑BABE GRANDPASubstrate 默认共识由两层组成BABE 负责出块GRANDPA 负责最终性。为什么要拆成两套机制打个比方BABE 是生产线上的工人持续不断地生产出区块GRANDPA 是质检主管负责在已经产出的区块里确认哪些是最终合格的、不可逆的。质检不需要检查每一个产品只要确认批次的一致性就能定论。这个分离设计精妙在网络分区时可以体现一边出块一边等待最终性确认网络恢复后再统一最终性不会因为一次分区就导致整条链停摆。你收到新区块时可以先视为暂时的等 GRANDPA 完成一轮投票后再完全放心。如果你不想用默认的 PoS 共识Substrate 也支持替换。常见的替代方案包括aura固定验证人轮流出块常用于许可链、manual-seal出块完全手动触发只适合本地测试和演示。选哪个共识取决于你的业务需要验证人开放还是封闭这个决策在前期就该想清楚。2.3 账户与余额模型Substrate 的账户模型核心是一个地址两类信息AccountId是地址本身AccountInfo里存 Nonce、余额等状态。初次接触时最需要留意的概念是Existential Deposit存续保证金简称 ED。如果账户余额被转账转得低于这个阈值系统会直接销毁这个账户从而防止链上垃圾账户无限膨胀。我第一次跑 demo 时吃过这个亏把一个账户的余额全部转到另一个账户结果原账户直接消失了。查了文档才知道是 ED 机制在起作用。这个机制在真实业务里影响也很大尤其是做空投或小额转账时必须确保目标账户余额不跌破 ED否则钱到了账户却没了用户会找你哭。2.4 链下工作机隐藏的预言机能力链下工作机Off-chain Workers是一个容易被新手忽略、但实用性很高的特性。它是在节点本地运行的一段代码可以访问本地存储也能发起 HTTP 请求访问外部网络。抓取到结果后可以构造交易提交上链。这相当于给了链一个外部世界的入口。举个例子做一个天气保险应用链下工作机定期抓取气象 API 数据当降雨量达到理赔阈值时自动生成索赔交易上链。这种主动抓取外部数据的逻辑在纯智能合约环境里几乎做不了——合约没法主动发起 HTTP 请求。需要特别注意链下工作机跑在节点本地不代表全网共识认可的结果。它提交的数据不一定可信需要设计锚定或者多节点交叉验证的机制。理解这一点你才不会被它的预言机光环坑到。3. 实操从零构建一条带业务模块的链3.1 环境准备与快速启动先解决环境问题。Substrate 开发需要 Rust 工具链而且要用 nightly 版本而不是 stable。# 安装 rust curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh # 添加 nightly 工具链并添加 Wasm 编译目标 rustup toolchain install nightly-2023-11-01 rustup target add wasm32-unknown-unknown --toolchain nightly-2023-11-01这里有个血的教训不要装最新 nightly而是固定一个官方文档写明兼容的版本。Substrate 对 Rust 版本非常敏感工具链一升级编译经常炸出莫名其妙的错误。盯着文档选一个已知稳定版本能省掉大量排查时间。然后拉模板工程git clone https://github.com/substrate-developer-hub/substrate-node-template cd substrate-node-template cargo build --release第一次编译极慢慢到让人怀疑机器卡死。我等过一个多小时期间几次想 CtrlC。这主要是 Wasm runtime 在编译会消耗远超普通 Rust 项目的内存。内存建议 16GB 以上8GB 的机器大概率会 OOM。项目结构重点注意两块runtime/src/lib.rs是所有 Pallet 组装的地方pallets/目录下面放你自己的业务模块node/是节点可执行程序。3.2 编写第一个 Pallet链上存证模块存证是最容易上手的业务用户提交一段数据的哈希链上记录提交者和时间方便事后验证归属权。这个场景覆盖了 Pallet 三大基本组件Storage、Callable、Event。创建pallets/poe目录Cargo.toml定义依赖[package] name pallet-poe version 0.1.0 edition 2021 [dependencies] frame-support { version 4.0.0-dev, default-features false, git https://github.com/paritytech/substrate.git, branch polkadot-v1.0.0 } frame-system { version 4.0.0-dev, default-features false, git https://github.com/paritytech/substrate.git, branch polkadot-v1.0.0 }然后是核心的lib.rs代码做了精简便于理解#![cfg_attr(not(feature std), no_std)] pub use pallet::*; #[frame_support::pallet] pub mod pallet { use frame_support::pallet_prelude::*; use frame_system::pallet_prelude::*; #[pallet::pallet] pub struct PalletT(_); #[pallet::config] pub trait Config: frame_system::Config {} // 存储映射存证内容 Hash -提交者账户 所在区块号 #[pallet::storage] pub type ProofsT: Config StorageMap_, Blake2_128Concat, Vecu8, (T::AccountId, T::BlockNumber); #[pallet::event] #[pallet::generate_deposit(pub(super) fn deposit_event)] pub enum EventT: Config { ClaimCreated(T::AccountId, Vecu8), } #[pallet::error] pub enum ErrorT { AlreadyClaimed, NoSuchClaim, NotClaimOwner, } #[pallet::call] implT: Config PalletT { // 提交存证 #[pallet::weight(10_000)] pub fn create_claim( origin: OriginForT, claim: Vecu8, ) - DispatchResult { let sender ensure_signed(origin)?; ensure!(!Proofs::T::contains_key(claim), Error::T::AlreadyClaimed); let block frame_system::pallet::Pallet::T::block_number(); Proofs::T::insert(claim, (sender.clone(), block)); Self::deposit_event(Event::ClaimCreated(sender, claim)); Ok(()) } } }这段代码做的事情很直白定义存储映射键是存证内容值是提交者和区块号create_claim是一个可由签名交易调用的函数先检查重复再写入最后发事件。几个关键细节Blake2_128Concat是存储键的哈希方式避免键明文暴露同时保留了可遍历性。选哈希器不是小事它影响链上存储的效率和安全性。ensure_signed保证调用者必须签名。如果没有这一步任何人都能伪造代他人提交的交易。#[pallet::weight(10_000)]决定交易费用示例里偷懒写死了真实项目不能这么干后面我会专门讲这个问题。3.3 把 Pallet 接进 Runtime光写 Pallet 还不行得告诉链我要用这个模块。打开runtime/src/lib.rs做三件事// 第一引入你写的 pallet pub use pallet_poe; // 第二为 Runtime 实现这个 pallet 的 Config impl pallet_poe::Config for Runtime { type RuntimeEvent RuntimeEvent; type WeightInfo (); } // 第三在 construct_runtime! 宏里注册 construct_runtime!( pub enum Runtime { System: frame_system, Balances: pallet_balances, Poe: pallet_poe, } );这一步常见的坑有三个construct_runtime!宏里面System必须保持在最前面它规定了 Pallet 在整体枚举中分配到的索引前端的各种调用的编码都依赖这个顺序。别漏掉runtime/Cargo.toml里的 feature 配置。每个 pallet 都要在stdfeature 下面声明pallet-poe/std否则编出来的节点在处理一些类型时会出现不一致报错信息还不容易看懂。改了 Runtime 之后整个项目要重新编译涉及的 crate 多又是一轮漫长的等待做好心理准备。3.4 编译、测试与启动本地节点回到项目根目录重新编译cargo build --release把新 Pallet 加进去会重新构建 Wasm runtime耗时较长。编译成功后启动开发链./target/release/node-template --dev --tmp--dev模式使用单验证人、无许可出块是最适合本地调试的模式--tmp表示区块数据存到临时目录退出即清理不会把调试数据留在机器上。启动后用官方自带的substrate-front-end-template连接本地节点。在网页界面上就能发起一次poe.createClaim交易提交存证内容然后观察事件日志和存储变化。这里有个实测经验启动完第一件事去查看链的 metadata 元数据。元数据描述了链上所有可用的外部调用和类型定义是前端和链交互的接口说明书。每次 Runtime 升级元数据都可能变化前端必须同步更新否则会出现类型解析不匹配的问题。4. 常见问题与排查技巧实录4.1 编译慢和内存不足这是所有 Substrate 初学者遇到的第一座大山没有例外。解决方案分几步走优先加大物理内存或者至少配置足够的交换分区。Wasm 编译是内存大户8GB 以下的机器几乎必挂。用 release profile 编译不要开 dev。dev 编译更快但生成的节点性能和体积都差而且中途出现的错误也更多。不要频繁执行cargo clean。增量编译能省大量时间clean 一次意味着从头再来。只改少量代码时明确自己改的是 runtime 还是 node。打包编译时依赖范围不同盲目全量构建纯属浪费时间。我踩过最惨的一次是笔记本 8GB 内存直接编译到系统卡死交换分区也撑不住最后只能重启。后来换了云主机加了 16GB 交换空间才搞定。这件事上别省钱。4.2 Runtime 升级失败Runtime 升级本身技术上是简单的把新编译出的 Wasm 作为特殊交易提交到链上。但踩坑点几乎都在兼容性上。我遇到过的情况新 Runtime 里删除了某个旧存储项但旧数据还留在链上节点读取存储时类型解析失败链直接卡住。正确的做法是改代码前先梳理存储变更。是新增、修改类型、还是删除存储项不同情况处理方式完全不同。如果涉及存储结构迁移必须在on_runtime_upgrade钩子里写迁移逻辑把旧数据读出来、转换、写入新存储。先在本地 dev 链完整走一遍升级流程再用测试网。不要上来就在正式链上做实验。另一个容易忽视的点transaction_version交易版本要跟着改。如果你改了任何外部调用的参数结构但没更新交易版本旧前端签名的交易格式可能和新链对不上出现签名验证失败这类让人一头雾水的报错。4.3 权重与交易费示例里我写了固定 weight真实项目绝对不行。Substrate 的权重系统决定了交易执行的资源消耗最终会转换成用户支付的手续费。如果 weight 定低了恶意用户可以用极低成本提交高计算量的交易把链的性能拖垮定高了普通用户每笔交易都要多付冤枉钱。评估 weight 有两种方式手动估算根据代码逻辑预估读写了多少次存储reads、多少次写入writes再用T::DbWeight::get().reads_writes(1, 1)这类表达式来标注。自动基准测试frame-benchmarking工具可以在本地跑基准测试通过实际测量生成每个函数的 weight精确度远超手动估算。我的经验是先写功能正确性验证通过后再补 benchmark。前期手动估算就行功能不完整就在 weight 上花大力气属于本末倒置。有一点必须提醒weight 表达式中的DbWeight类型是可以配置的不同链的读写成本不同。正式上线前要把这个参数调准偏差太大会直接影响出块质量和用户体验。4.4 前端接入的坑如果你准备做可用的产品前端接入早晚要面对。最大的坑是类型映射链上的复杂类型——BoundedVec、DispatchResult、自定义枚举——在 JavaScript 侧需要对应的类型定义。polkadot.js 一般会靠元数据自动生成接口大部分情况能处理。但遇到自定义结构的类型时需要手写types配置否则前端解析出来就是乱码或者抛错。建议在开发早期就和前端约好一个共享的类型定义文件否则联调阶段会耗费大量时间在为什么这里的类型对不上上。另一个经验测试链和正式链的前端配置不要混用。我在本地 dev 链调试好后切成测试网发现大量接口报错查了半天是两条链的元数据版本和类型定义不同。后来我把类型定义按链拆开配置才彻底解决。前端与链节点的配合是这类框架项目里最常被低估的时间黑洞。最后分享一个我养成的习惯每次改代码前先把链的状态用工具导出备份再跑升级测试。这个习惯帮我避免了至少两次因为存储不兼容导致链直接跑不起来的悲剧。Substrate 框架虽然把造链门槛拉低了但也正因为能力多踩坑的空间也随之变大。保持对底层机制的好奇心遇到问题先看文档再动手这条路会越走越顺。
去年有个朋友拉我聊说团队准备发一条自己的链问我从哪下手。我给的回答很直接去研究 Substrate别从零造轮子。后来他花了两个月真把一条带自定义业务模块的链跑起来了跟我说这个框架把造链门槛拉低了不止一个量级。Substrate 是 Parity 团队开源的区块链开发框架也是 Polkadot 底层依赖的技术。和普通区块链源码不同它是一整套可自由组合的积木节点网络、共识、账本、治理、升级全都模块化。你要做的不是从零写链而是挑选模块、配置参数、写自己的业务逻辑。这篇文章适合两类人刚入门想搞懂 Substrate 值不值得学的新手以及已经跑过 demo、想深入了解机制与避坑经验的开发者。我会从设计逻辑讲起再落到真实操作把我踩过的坑尽量交代清楚。1. 项目整体设计与核心概念拆解1.1 从造链的痛点说起传统上想发一条链无非几条路fork 比特币或以太坊的源码或者在某条现成链上发智能合约。fork 源码这条路我身边做过的团队大多叫苦不迭。老代码是围绕特定场景设计的你改一行出块逻辑可能要牵扯出同步机制、难度调整、交易池策略的一堆兼容性问题。我见过有人 fork 比特币源码后想缩短出块时间结果难度调整逻辑跟着崩光调参就折腾了一个月。另一个绕不开的问题是升级。传统区块链想升级基本只能靠分叉要协调全节点要处理社区分歧一不小心就分裂成两条链。以太坊从 PoW 转到 PoS过渡了多少年这不是技术做不到而是链本身缺乏一套原地升级的机制。智能合约方案也有天花板业务逻辑受限于合约语言性能瓶颈明显而且无法定制链本身的行为——比如你想自定义共识、控制出块间隔合约根本管不到链底层。当业务场景已经超越发 token 跑一个合约的时候你就需要一条真正属于自己的链。1.2 Substrate 的设计内核一切可插拔Substrate 的答案很直接把区块链底层的所有通用组件全部抽象成模块让你在模块之上写业务。整体架构分三层。核心客户端负责 P2P 网络、区块同步、数据库存储这些底层地基。Runtime 是区块链的状态转换函数决定了每出一个区块链上状态该怎么变化。FRAME 是一套构建 Runtime 的工具库里面是一个个可复用的 Pallet模块。我常用一个类比开餐厅。核心客户端相当于你租下的店面和水电基础设施固定不动Runtime 相当于菜单和服务流程决定了这家店的风格FRAME 里的 Pallet 就是半成品食材包——做川菜拿一个辣椒模块开甜品店拿一个糖分模块自由组合。这套设计最大的好处是业务逻辑和底层升级解耦。Runtime 会被编译成 Wasm 字节码作为链状态的一部分存到链上节点执行逻辑以链上 Wasm 为准。这意味着你的链可以通过链上治理机制更新 Runtime不需要硬分叉。这在传统区块链里几乎不可想象。1.3 对比为什么不用 fork 的方式fork 和 Substrate 的本质区别在改造成本在哪里。fork 是拿到一栋装修好的房子你每改一处都要担心承重墙能不能敲。Substrate 是一套标准化积木你要改的只是某个积木的内部结构接口保持稳定就行。Parity 官方维护了一个 node-template 模板几乎包含了主链的全套基础模块克隆下来就能跑起一条可用的开发链。之后你只需要往 Runtime 里逐步添加或替换模块要理解搭链这件事从模板开始要比从零开始容易太多。这里说句公道话Substrate 的学习曲线不算平缓涉及 Rust、Wasm、密码学、共识协议四座大山叠一起。但它把最复杂、最容易出错的底层封装得足够好让你能聚焦在业务逻辑上。我个人的判断是对于想做应用链的团队Substrate 是当前所有方案里投入产出比最高的选择。2. 核心组件与关键技术点解析2.1 Runtime 与 FRAMESubstrate 的灵魂Runtime 是整个链的决定性部分它定义了链上有哪些资产、哪些业务操作、状态怎么变化。理解一个关键点Runtime 编译成 Wasm 后同样作为链的一部分存储下来。节点跑的时候优先读链上的 Wasm而不是节点二进制里内置的那份。这条设计就引出了我之前说的能力你的链上逻辑可以在运行时被替换。新 Runtime 通过一笔特殊的升级交易提交上链后节点自动从后续区块开始使用新逻辑。不需要停链不需要协调所有节点手动换版本。想想传统区块链为了一个参数修改要吵多久的社区分歧对比很明显。FRAME 里的 Pallet 我列几个最常见的pallet_system系统基础提供账户、区块号、Nonce 管理pallet_balances账户余额与转账逻辑pallet_contracts支持 Wasm 智能合约的执行环境pallet_democracy链上民主投票治理pallet_stakingPoS 抵押与验证人选举写业务就是写一个新的 Pallet。Pallet 本质上是一组由 Rust 宏驱动的代码结构包含存储项、事件、错误和可调用函数。第 3 节我会给一个完整的代码示例。2.2 共识的组合逻辑BABE GRANDPASubstrate 默认共识由两层组成BABE 负责出块GRANDPA 负责最终性。为什么要拆成两套机制打个比方BABE 是生产线上的工人持续不断地生产出区块GRANDPA 是质检主管负责在已经产出的区块里确认哪些是最终合格的、不可逆的。质检不需要检查每一个产品只要确认批次的一致性就能定论。这个分离设计精妙在网络分区时可以体现一边出块一边等待最终性确认网络恢复后再统一最终性不会因为一次分区就导致整条链停摆。你收到新区块时可以先视为暂时的等 GRANDPA 完成一轮投票后再完全放心。如果你不想用默认的 PoS 共识Substrate 也支持替换。常见的替代方案包括aura固定验证人轮流出块常用于许可链、manual-seal出块完全手动触发只适合本地测试和演示。选哪个共识取决于你的业务需要验证人开放还是封闭这个决策在前期就该想清楚。2.3 账户与余额模型Substrate 的账户模型核心是一个地址两类信息AccountId是地址本身AccountInfo里存 Nonce、余额等状态。初次接触时最需要留意的概念是Existential Deposit存续保证金简称 ED。如果账户余额被转账转得低于这个阈值系统会直接销毁这个账户从而防止链上垃圾账户无限膨胀。我第一次跑 demo 时吃过这个亏把一个账户的余额全部转到另一个账户结果原账户直接消失了。查了文档才知道是 ED 机制在起作用。这个机制在真实业务里影响也很大尤其是做空投或小额转账时必须确保目标账户余额不跌破 ED否则钱到了账户却没了用户会找你哭。2.4 链下工作机隐藏的预言机能力链下工作机Off-chain Workers是一个容易被新手忽略、但实用性很高的特性。它是在节点本地运行的一段代码可以访问本地存储也能发起 HTTP 请求访问外部网络。抓取到结果后可以构造交易提交上链。这相当于给了链一个外部世界的入口。举个例子做一个天气保险应用链下工作机定期抓取气象 API 数据当降雨量达到理赔阈值时自动生成索赔交易上链。这种主动抓取外部数据的逻辑在纯智能合约环境里几乎做不了——合约没法主动发起 HTTP 请求。需要特别注意链下工作机跑在节点本地不代表全网共识认可的结果。它提交的数据不一定可信需要设计锚定或者多节点交叉验证的机制。理解这一点你才不会被它的预言机光环坑到。3. 实操从零构建一条带业务模块的链3.1 环境准备与快速启动先解决环境问题。Substrate 开发需要 Rust 工具链而且要用 nightly 版本而不是 stable。# 安装 rust curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh # 添加 nightly 工具链并添加 Wasm 编译目标 rustup toolchain install nightly-2023-11-01 rustup target add wasm32-unknown-unknown --toolchain nightly-2023-11-01这里有个血的教训不要装最新 nightly而是固定一个官方文档写明兼容的版本。Substrate 对 Rust 版本非常敏感工具链一升级编译经常炸出莫名其妙的错误。盯着文档选一个已知稳定版本能省掉大量排查时间。然后拉模板工程git clone https://github.com/substrate-developer-hub/substrate-node-template cd substrate-node-template cargo build --release第一次编译极慢慢到让人怀疑机器卡死。我等过一个多小时期间几次想 CtrlC。这主要是 Wasm runtime 在编译会消耗远超普通 Rust 项目的内存。内存建议 16GB 以上8GB 的机器大概率会 OOM。项目结构重点注意两块runtime/src/lib.rs是所有 Pallet 组装的地方pallets/目录下面放你自己的业务模块node/是节点可执行程序。3.2 编写第一个 Pallet链上存证模块存证是最容易上手的业务用户提交一段数据的哈希链上记录提交者和时间方便事后验证归属权。这个场景覆盖了 Pallet 三大基本组件Storage、Callable、Event。创建pallets/poe目录Cargo.toml定义依赖[package] name pallet-poe version 0.1.0 edition 2021 [dependencies] frame-support { version 4.0.0-dev, default-features false, git https://github.com/paritytech/substrate.git, branch polkadot-v1.0.0 } frame-system { version 4.0.0-dev, default-features false, git https://github.com/paritytech/substrate.git, branch polkadot-v1.0.0 }然后是核心的lib.rs代码做了精简便于理解#![cfg_attr(not(feature std), no_std)] pub use pallet::*; #[frame_support::pallet] pub mod pallet { use frame_support::pallet_prelude::*; use frame_system::pallet_prelude::*; #[pallet::pallet] pub struct PalletT(_); #[pallet::config] pub trait Config: frame_system::Config {} // 存储映射存证内容 Hash -提交者账户 所在区块号 #[pallet::storage] pub type ProofsT: Config StorageMap_, Blake2_128Concat, Vecu8, (T::AccountId, T::BlockNumber); #[pallet::event] #[pallet::generate_deposit(pub(super) fn deposit_event)] pub enum EventT: Config { ClaimCreated(T::AccountId, Vecu8), } #[pallet::error] pub enum ErrorT { AlreadyClaimed, NoSuchClaim, NotClaimOwner, } #[pallet::call] implT: Config PalletT { // 提交存证 #[pallet::weight(10_000)] pub fn create_claim( origin: OriginForT, claim: Vecu8, ) - DispatchResult { let sender ensure_signed(origin)?; ensure!(!Proofs::T::contains_key(claim), Error::T::AlreadyClaimed); let block frame_system::pallet::Pallet::T::block_number(); Proofs::T::insert(claim, (sender.clone(), block)); Self::deposit_event(Event::ClaimCreated(sender, claim)); Ok(()) } } }这段代码做的事情很直白定义存储映射键是存证内容值是提交者和区块号create_claim是一个可由签名交易调用的函数先检查重复再写入最后发事件。几个关键细节Blake2_128Concat是存储键的哈希方式避免键明文暴露同时保留了可遍历性。选哈希器不是小事它影响链上存储的效率和安全性。ensure_signed保证调用者必须签名。如果没有这一步任何人都能伪造代他人提交的交易。#[pallet::weight(10_000)]决定交易费用示例里偷懒写死了真实项目不能这么干后面我会专门讲这个问题。3.3 把 Pallet 接进 Runtime光写 Pallet 还不行得告诉链我要用这个模块。打开runtime/src/lib.rs做三件事// 第一引入你写的 pallet pub use pallet_poe; // 第二为 Runtime 实现这个 pallet 的 Config impl pallet_poe::Config for Runtime { type RuntimeEvent RuntimeEvent; type WeightInfo (); } // 第三在 construct_runtime! 宏里注册 construct_runtime!( pub enum Runtime { System: frame_system, Balances: pallet_balances, Poe: pallet_poe, } );这一步常见的坑有三个construct_runtime!宏里面System必须保持在最前面它规定了 Pallet 在整体枚举中分配到的索引前端的各种调用的编码都依赖这个顺序。别漏掉runtime/Cargo.toml里的 feature 配置。每个 pallet 都要在stdfeature 下面声明pallet-poe/std否则编出来的节点在处理一些类型时会出现不一致报错信息还不容易看懂。改了 Runtime 之后整个项目要重新编译涉及的 crate 多又是一轮漫长的等待做好心理准备。3.4 编译、测试与启动本地节点回到项目根目录重新编译cargo build --release把新 Pallet 加进去会重新构建 Wasm runtime耗时较长。编译成功后启动开发链./target/release/node-template --dev --tmp--dev模式使用单验证人、无许可出块是最适合本地调试的模式--tmp表示区块数据存到临时目录退出即清理不会把调试数据留在机器上。启动后用官方自带的substrate-front-end-template连接本地节点。在网页界面上就能发起一次poe.createClaim交易提交存证内容然后观察事件日志和存储变化。这里有个实测经验启动完第一件事去查看链的 metadata 元数据。元数据描述了链上所有可用的外部调用和类型定义是前端和链交互的接口说明书。每次 Runtime 升级元数据都可能变化前端必须同步更新否则会出现类型解析不匹配的问题。4. 常见问题与排查技巧实录4.1 编译慢和内存不足这是所有 Substrate 初学者遇到的第一座大山没有例外。解决方案分几步走优先加大物理内存或者至少配置足够的交换分区。Wasm 编译是内存大户8GB 以下的机器几乎必挂。用 release profile 编译不要开 dev。dev 编译更快但生成的节点性能和体积都差而且中途出现的错误也更多。不要频繁执行cargo clean。增量编译能省大量时间clean 一次意味着从头再来。只改少量代码时明确自己改的是 runtime 还是 node。打包编译时依赖范围不同盲目全量构建纯属浪费时间。我踩过最惨的一次是笔记本 8GB 内存直接编译到系统卡死交换分区也撑不住最后只能重启。后来换了云主机加了 16GB 交换空间才搞定。这件事上别省钱。4.2 Runtime 升级失败Runtime 升级本身技术上是简单的把新编译出的 Wasm 作为特殊交易提交到链上。但踩坑点几乎都在兼容性上。我遇到过的情况新 Runtime 里删除了某个旧存储项但旧数据还留在链上节点读取存储时类型解析失败链直接卡住。正确的做法是改代码前先梳理存储变更。是新增、修改类型、还是删除存储项不同情况处理方式完全不同。如果涉及存储结构迁移必须在on_runtime_upgrade钩子里写迁移逻辑把旧数据读出来、转换、写入新存储。先在本地 dev 链完整走一遍升级流程再用测试网。不要上来就在正式链上做实验。另一个容易忽视的点transaction_version交易版本要跟着改。如果你改了任何外部调用的参数结构但没更新交易版本旧前端签名的交易格式可能和新链对不上出现签名验证失败这类让人一头雾水的报错。4.3 权重与交易费示例里我写了固定 weight真实项目绝对不行。Substrate 的权重系统决定了交易执行的资源消耗最终会转换成用户支付的手续费。如果 weight 定低了恶意用户可以用极低成本提交高计算量的交易把链的性能拖垮定高了普通用户每笔交易都要多付冤枉钱。评估 weight 有两种方式手动估算根据代码逻辑预估读写了多少次存储reads、多少次写入writes再用T::DbWeight::get().reads_writes(1, 1)这类表达式来标注。自动基准测试frame-benchmarking工具可以在本地跑基准测试通过实际测量生成每个函数的 weight精确度远超手动估算。我的经验是先写功能正确性验证通过后再补 benchmark。前期手动估算就行功能不完整就在 weight 上花大力气属于本末倒置。有一点必须提醒weight 表达式中的DbWeight类型是可以配置的不同链的读写成本不同。正式上线前要把这个参数调准偏差太大会直接影响出块质量和用户体验。4.4 前端接入的坑如果你准备做可用的产品前端接入早晚要面对。最大的坑是类型映射链上的复杂类型——BoundedVec、DispatchResult、自定义枚举——在 JavaScript 侧需要对应的类型定义。polkadot.js 一般会靠元数据自动生成接口大部分情况能处理。但遇到自定义结构的类型时需要手写types配置否则前端解析出来就是乱码或者抛错。建议在开发早期就和前端约好一个共享的类型定义文件否则联调阶段会耗费大量时间在为什么这里的类型对不上上。另一个经验测试链和正式链的前端配置不要混用。我在本地 dev 链调试好后切成测试网发现大量接口报错查了半天是两条链的元数据版本和类型定义不同。后来我把类型定义按链拆开配置才彻底解决。前端与链节点的配合是这类框架项目里最常被低估的时间黑洞。最后分享一个我养成的习惯每次改代码前先把链的状态用工具导出备份再跑升级测试。这个习惯帮我避免了至少两次因为存储不兼容导致链直接跑不起来的悲剧。Substrate 框架虽然把造链门槛拉低了但也正因为能力多踩坑的空间也随之变大。保持对底层机制的好奇心遇到问题先看文档再动手这条路会越走越顺。
