如果你关注区块链应用开发Substrate 这几年已经不是一个陌生词了。我第一次真正上手它是被搭一条自定义链只需要写业务逻辑这句话打动的。当时团队要做一条存证链要求链上逻辑完全自主可控、可升级而且不能沿用以太坊那套合约模式。调研一圈之后发现Substrate 几乎是为这个场景量身定制的它把共识、P2P 网络、状态存储这些底层通通封装好开发者集中精力写 Runtime 里的业务模块。这篇文章我就以自己从零搭建、写 pallet、上线前测试的完整经历为主线把 Substrate 到底怎么用、怎么避坑、哪些环节最容易翻车一次讲清楚。1. 先搞清楚 Substrate 到底解决了什么问题1.1 两条老路为什么走不通在做自定义链这件事上传统有两条路线。一条是彻底从零开始写链共识、网络层、状态数据库、交易池、账本存储全部自己实现。我会告诉你这条路不是不能走但是周期按年算。另一个更常见的选择是 fork 一条现成的链比如 fork Bitcoin 或以太坊。问题在于一旦 fork上游的安全更新、性能优化、新功能你全都接不到了除非你养一个专职团队持续做代码合并。现实中多数团队没有这个人力fork 完之后就是自生自灭。Substrate 走的是第三条路。它把区块链里高度标准化的底层组件全部做成可配置的模块让你不需要关心区块头怎么序列化、交易被广播后如何传播这类问题。同时它又不像合约平台那样限制你的业务表达链本身的交易类型、存储结构、手续费模型都能自定。我第一次在这个框架里看到Runtime 编译成 WASM 上传到链上的设计时确实有种这才是为应用链准备的东西的感觉。1.2 Runtime 与节点分离的价值Substrate 最有辨识度的设计是节点客户端和 Runtime 的分离。节点管的是底层执行环境负责导入区块、处理网络共识而 Runtime 是真正的业务层它那套代码会被同时编译成两种形态一种是直接跑在节点里的原生代码另一种是编译成 WASM 的链上版本。链上时刻保存着 Runtime 的 WASM 字节码当新版本通过升级机制写进链上后节点后续执行区块会自动加载新 WASM 来跑逻辑。这意味着无分叉升级成为可能。传统链一旦部署业务逻辑就锁死了要改只能硬分叉。Substrate 下只要 Runtime 版本号更新旧节点会从链上拉取新的 WASM 并继续同步不会产生分叉。这一点对任何商业场景都是刚需毕竟没有哪套业务逻辑是一上线就永远正确的。不仅仅是升级模块复用在 Substrate 生态里也是真真切切的。官方维护的 FRAME 框架里已经有 system、balances、sudo、transaction payment 等成熟模块业务上只需要专注自己的部分其余直接装配进去。这种乐高积木式的开发方式后来也是我们团队能快速交付的关键。2. 环境准备与第一个节点启动2.1 Rust 工具链的版本坑如果你直接把官网文档里的安装命令复制粘贴大概率会在编译阶段遇到一堆报错。Substrate 对 Rust 工具链版本非常敏感它要求特定版本的 nightly 编译器而不是最新的 nightly。社区里有一个通用的排错原则先看仓库根目录下有没有rust-toolchain.toml文件如果有就老老实实按它锁定的版本装。我当时拿到 substrate-node-template 模板第一件做对的事就是先检查这个文件。文件里会写[toolchain] channel nightly-2024-07-17 components [rustfmt, rust-src] targets [wasm32-unknown-unknown]wasm32-unknown-unknown这个 target 一定不能漏装因为 Runtime 要编成 WASM。一旦环境对不上后面在cargo build --release阶段会报各种莫名其妙的链接错误排查起来非常痛苦。安装完指定 nightly 后建议再执行一次rustup target add wasm32-unknown-unknown和cargo install sccachesccache 是后面优化编译速度的关键工具这点后面详细说。2.2 从模板到 dev 链的首次启动环境就绪后克隆官方模板git clone https://github.com/substrate-developer-hub/substrate-node-template.git cd substrate-node-template cargo build --release第一次编译是整个生命周期里最考验耐心的一步。在这台配置一般的机器上大概16G内存6核新环境全量编译耗时在40到60分钟期间主要卡在substrate系列底层依赖的编译上。如果你的机器内存小于8G强烈建议先把 swap 空间临时加大否则 Rust 编译内存溢出会直接 OOM 挂掉。编译完成后启动开发链./target/release/node-template --dev--dev模式会自动生成一个带预置账户的开发数据库并且默认单节点出块不需要外部验证人。观察日志输出能看到Preparing start round、Importing block这样的日志说明链已经正常出块了。如果出现Retrying这种网络相关日志先别慌单节点 dev 模式偶尔因为时间偏差也会重试连接只要区块高度在涨就没问题。2.3 源码结构速览node / runtime / pallets首次打开仓库千万别一头扎进 lib.rs 里读代码先理清目录结构。整个模板分三大部分node/节点可执行程序负责网络、共识、RPC 服务等底层功能大部分场景不需要改动。runtime/链上的业务运行环境里面通过construct_runtime!宏声明这条链包含哪些模块是调度中心。pallets/业务模块源码。模板自带的pallet-template就是我们写自定义逻辑的起点。我见过不少同事一开始把node/里的代码改得乱七八糟其实 90% 的业务开发都只发生在runtime/和pallets/。节点代码动得越少越好它属于基础设施我们团队后来甚至直接把它当成黑盒只在必要的时候升级依赖版本。3. Runtime 是灵魂pallet 与 extrinsic 的工作方式3.1 把业务逻辑想象成乐高积木Substrate 的业务层由若干 pallet 并列组成。pallet 可以理解成打包好的业务模块每个模块提供一组存储项和一组可被外部调用的函数。比如balancespallet 管账户余额systempallet 管账户身份和区块基础数据sudopallet 允许超级管理员执行敏感操作。要什么功能就往construct_runtime!宏里加什么这比传统开发里的引依赖还要清爽因为这些 pallet 是真真切切和链上存储绑定在一起的。自己写的业务 pallet 结构上也是同一个套路。最外层是#[frame_support::pallet]宏声明紧跟着的是Configtrait。这个 Config 是 pallet 与 Runtime 之间的接口约定常见的是把 RuntimeEvent 类型传进来这样 pallet 里 emit 的事件才能被外界看见。初学者容易在这里卡住因为 trait 关联类型和各种宏组合看起来很吓人但本质上就是依赖注入那一套理解了就好。3.2 存储抽象StorageValue / StorageMap / StorageDoubleMappallet 里的数据要持久化不能直接丢在全局变量里。Substrate 的 FRAME 提供了几种存储声明宏最常用的三个StorageValue存储单个值比如当前存证数量。StorageMap键值对映射比如存证哈希 - 存证人账户地址。StorageDoubleMap双键映射适合账号 - 资产凭证 - 数量这类结构。每个存储项在链上都对应一段确定的存储 key帧中会生成对应的 getter 函数。写业务时要注意 key 的哈希算法选择比如StorageMap默认常用Blake2_128Concat它的好处是抗哈希冲突、安全性高Twox64Concat速度极快但碰撞性弱一般只建议用于内部索引类数据如果把用户输入的敏感内容直接放进 Twox key有被碰撞攻击的风险。这块不用背记住一个原则对外不可信的数据用 Blake2内部自生成的序号可以用 Twox。3.3 一个 extrinsic 从哪里来到哪里去extrinsic 是 Substrate 中交易/调用的统称也就是用户发给链上的指令。一个典型流程是这样的用户构造一笔调用签名后广播到网络节点把它放进交易池并在出块时打包进区块Runtime 根据调用字段找到对应 pallet 里的执行函数执行存储读写执行成功后触发事件失败则回滚该笔调用的所有状态变更。写 pallet 时#[pallet::call]宏下面定义的函数就是 extrinsic。每个函数必须用#[pallet::weight]标注权重它决定这笔调用会消耗多少手续费。权重不是摆设它直接关系到链的安全如果某笔调用执行成本无限高交易池就可能被恶意高耗能调用阻塞。养成习惯每次新增 call都先估一下最坏情况的计算开销宁可权重设高一点。4. 亲手写一个存证 pallet完整实操记录4.1 pallet 骨架config / storage / call / error从模板开发一个文件存证功能是最经典的练手。需求很简单用户提交一段内容哈希链上记录提交人和时间证明这个内容在某个时间点已经存在。之后任何人都可以查询某段哈希的存证信息原提交人可以选择撤销。首先在pallets/下新建一个proof-of-existence目录按照模板 pallet 的格式搭建骨架。pallet 顶层结构大致如下#[frame_support::pallet] pub mod pallet { use frame_support::pallet_prelude::*; use frame_system::pallet_prelude::*; use sp_std::vec::Vec; #[pallet::config] pub trait Config: frame_system::Config { type RuntimeEvent: FromEventSelf IsTypeSelf as frame_system::Config::RuntimeEvent; } #[pallet::pallet] pub struct PalletT(_); #[pallet::storage] #[pallet::getter(fn proofs)] pub type ProofsT: Config StorageMap _, Blake2_128Concat, Vecu8, (T::AccountId, BlockNumberForT), ; #[pallet::event] #[pallet::generate_deposit] pub enum EventT: Config { ProofClaimed(T::AccountId, Vecu8), ProofRevoked(T::AccountId, Vecu8), } #[pallet::error] pub enum ErrorT { AlreadyClaimed, NoPermission, NotExist, } }这个骨架里有几个容易忽略的细节。#[pallet::getter(fn proofs)]会自动生成一个查询函数允许 RPC 和 runtime 内部直接按 key 读取存储省去手写查询。BlockNumberForT替代老的T::BlockNumber新版本里不要再用后者否则会有 deprecation 警告。sp_std::vec::Vec是为了兼容 no_std 环境Runtime 在 WASM 中运行不能直接依赖标准库的某些特性。4.2 实现 claim 与 revoke接下来是核心逻辑。claim接受一个内容哈希存储映射新增一条记录revoke要求调用者是原存证人才可以删除记录。#[pallet::call] implT: Config PalletT { #[pallet::call_index(0)] #[pallet::weight(10_000)] pub fn claim(origin: OriginForT, hash: Vecu8) - DispatchResult { let sender ensure_signed(origin)?; ensure!(!Proofs::T::contains_key(hash), Error::T::AlreadyClaimed); let block_number frame_system::Pallet::T::block_number(); Proofs::T::insert(hash, (sender.clone(), block_number)); Self::deposit_event(Event::ProofClaimed(sender, hash)); Ok(()) } #[pallet::call_index(1)] #[pallet::weight(10_000)] pub fn revoke(origin: OriginForT, hash: Vecu8) - DispatchResult { let sender ensure_signed(origin)?; let (owner, _) Proofs::T::get(hash).ok_or(Error::T::NotExist)?; ensure!(owner sender, Error::T::NoPermission); Proofs::T::remove(hash); Self::deposit_event(Event::ProofRevoked(sender, hash)); Ok(()) } }这里有几个专业细节值得展开。ensure!和ensure_signed!是 FRAME 提供的守卫宏条件不满足就返回对应错误浅显的原理是快速失败。call_index是这个 call 在 pallet 内的序号一旦上线稳定后不要随意改动否则会导致链上已有交易解码错乱。我见过有团队在开发中改这个序号引发链上数据错乱属于低级但致命的失误。hash参数的上限问题也要提前想清楚。如果允许用户传入任意长度 Vec那存储会被无限大的 key 撑爆。生产环境必须用BoundedVecu8, ConstU3264或者直接统一哈希长度比如让用户传进 32 字节的[u8; 32]。框架给了BoundedVec就是为了防止这类无界存储写案例时忽略真实上线前一定要补上。4.3 挂载到 runtime 并跑通测试pallet 写完后需要把它注册进 runtime。以模板为例在runtime/src/lib.rs里做三件事。先声明模块类型impl pallet_proof_of_existence::Config for Runtime { type RuntimeEvent RuntimeEvent; }再把它加进construct_runtime!construct_runtime!( pub struct Runtime { System: frame_system, ... ProofOfExistence: pallet_proof_of_existence, } );最后在Cargo.toml的 runtime 部分加入依赖。完成这三步再编译如果有RuntimeEvent类型对不上的问题会在编译期直接报出来。框架的宏检查很严格这反而是好事很多业务逻辑错误在编译期就被拦截了。测试方面推荐在 pallet 内直接写#[cfg(test)]单元测试。基本套路是用new_test_ext()构造一个测试环境然后调用 pallet 的函数看看存储和事件是否符合预期。一个最简单但最关键的测试用例是同一个哈希不能被重复存证这个用例把AlreadyClaimed这个错误路径覆盖掉实际问题排查时能帮你快速确认业务守卫逻辑是否挂上了。5. 编译、测试与升级三个真实项目里绕不开的坎5.1 为什么 cargo build --release 这么慢Substrate 的编译链之重用过的人都有体会。底层依赖包括 substrate 自身的 nodes、primitives、frame以及 tokio、serde 这些重型 Rust 库第一次全量编译动辄一小时。我们团队踩了一段时间后总结出一套提速方案。第一安装 sccache 并配置环境变量让本地编译缓存复用中间产物。第二把target目录单独指到一块空间充足的磁盘并用CARGO_INCREMENTAL0减少增量编译带来的内存压力。最重要的是只有确定要跑通端到端流程时才做完整 release 编译平时写业务代码可以用SKIP_WASM_BUILD1跳过 WASM 构建只编 native 版本。原理解释一下WASM 构建是 Runtime 编译里最耗时的一环开发验证阶段链路还在频繁变动这时候纠结 WASM 纯粹是浪费时间。当然这仅限本地开发真正准备链上升级和测试网验证时必须完整编译。5.2 单元测试的正确姿势Substrate 里写业务测试有两个最容易出问题的点。一是测试环境初始化要用frame_support::test宏配合sp_io::TestExternalities。模板在src/tests.rs里已经写了模板照抄再加自己的用例即可。二是要理解调用失败时存储变更会回滚。我在多笔调用组合测试里经常遇到上一笔已经写入的数据下一笔怎么不见了的疑问实际是上一笔由于一个 error 被整体回滚了。这是交易级原子性在起作用避免出现写入一半的状态。console.log 式的调试在链上开发依旧有效。在 pallet 测试代码里用frame_support::print或标准的log宏输出中间变量确认执行路径是否正确。不过要注意这类输出只在测试环境能看到正式链上不会打到日志里。5.3 链上升级set_code 与存储迁移Substrate 的无分叉升级不是改完代码自动上天必须主动触发。最朴素的方式是通过systempallet 的set_code接口把新 Runtime 的 WASM 提交上去。开发阶段通常用sudo调用该接口一旦代码出问题还能用 sudo 回滚到旧版本。真正复杂的是存储迁移。如果新 Runtime 新增了存储项、改写了存储结构光 set_code 不够旧数据对不上新结构节点同步后很可能在读取时 panic。框架提供了#[pallet::hooks]里的on_runtime_upgrade钩子专门用来做数据迁移。这个钩子在 Runtime 升级后、业务块执行前被调用你在这里遍历旧存储、构造新存储、返回消耗的权重。搬迁数据的写法要格外小心。这里有一个行业共识级的建议迁移逻辑一定要先在本地旧版本链上跑通一遍用 try-runtime 工具在真实历史状态上模拟升级流程确认没有 panic、存储键没有覆盖再拿到生产网上执行。我们团队早期跳过这一步直接升级测试网结果存储 map 的 key 哈希算法从 Twox 改成 Blake2 后所有数据都查不到了前后花了一整天才排查出来。凡是涉及存储 key 格式变化的升级没有捷径测试前置。6. 我踩过的坑与选型建议6.1 版本漂移带来的连环问题Substrate 的版本演进速度非常快一个库的接口在几个月内就可能废弃。最典型的例子是 pallet 宏从#[pallet]变成#[frame_support::pallet]以及BlockNumberFor替换T::BlockNumber。如果你在网上搜代码示例很可能搜到的是两年前的旧写法粘进新版本编辑器会直接报错。避免版本问题有一个硬措施锁定依赖版本。模板根目录的Cargo.toml里依赖版本都是固定的不要轻易cargo updaterust-toolchain.toml里的 nightly 版本也要保持和模板一致。每次想要升级依赖先在本地另开分支跑一遍全量测试确认没有兼容问题再合并。我们团队踩过最惨的一次是依赖整体升了三个小版本结果 consensus 配置的 trait 约束变了链启动后直接 panic回滚也费了不少功夫。6.2 什么时候别用 Substrate抛开技术热情Substrate 并不适合所有项目。如果你的业务就是一个简单的 Token 转账应用实体用户不多直接用合约平台反而更省心。Substrate 的学习曲线陡、编译链重、运维成本高团队没有 Rust 功底会非常痛苦。我们评估一个新项目是否上链时第一条就是问业务逻辑是否真的有不可篡改、账本共享、自定义交易类型这类强需求。没有的话用传统数据库反而更高效。反过来如果你的业务需要自定义手续费模型、共识算法、隐私机制或者是 Polkadot 生态里的平行链那 Substrate 几乎是绕不开的答案。它给了你完整的链级设计自由而不是只能在合约层面翻花活。最后再分享一个小技巧如果你第一次接触 Substrate不要一上来就规划复杂的大 pallet。先用模板跑通 dev 链然后照抄一个最简单功能的 pallet 挂上去亲眼看自己的业务逻辑在链上产生区块、触发事件。这个手感建立起来之后再去啃宏、存储、升级这些更深的机制效率和信心都会完全不一样。
Substrate实战：从零搭建自定义存证链与Pallet开发全攻略
如果你关注区块链应用开发Substrate 这几年已经不是一个陌生词了。我第一次真正上手它是被搭一条自定义链只需要写业务逻辑这句话打动的。当时团队要做一条存证链要求链上逻辑完全自主可控、可升级而且不能沿用以太坊那套合约模式。调研一圈之后发现Substrate 几乎是为这个场景量身定制的它把共识、P2P 网络、状态存储这些底层通通封装好开发者集中精力写 Runtime 里的业务模块。这篇文章我就以自己从零搭建、写 pallet、上线前测试的完整经历为主线把 Substrate 到底怎么用、怎么避坑、哪些环节最容易翻车一次讲清楚。1. 先搞清楚 Substrate 到底解决了什么问题1.1 两条老路为什么走不通在做自定义链这件事上传统有两条路线。一条是彻底从零开始写链共识、网络层、状态数据库、交易池、账本存储全部自己实现。我会告诉你这条路不是不能走但是周期按年算。另一个更常见的选择是 fork 一条现成的链比如 fork Bitcoin 或以太坊。问题在于一旦 fork上游的安全更新、性能优化、新功能你全都接不到了除非你养一个专职团队持续做代码合并。现实中多数团队没有这个人力fork 完之后就是自生自灭。Substrate 走的是第三条路。它把区块链里高度标准化的底层组件全部做成可配置的模块让你不需要关心区块头怎么序列化、交易被广播后如何传播这类问题。同时它又不像合约平台那样限制你的业务表达链本身的交易类型、存储结构、手续费模型都能自定。我第一次在这个框架里看到Runtime 编译成 WASM 上传到链上的设计时确实有种这才是为应用链准备的东西的感觉。1.2 Runtime 与节点分离的价值Substrate 最有辨识度的设计是节点客户端和 Runtime 的分离。节点管的是底层执行环境负责导入区块、处理网络共识而 Runtime 是真正的业务层它那套代码会被同时编译成两种形态一种是直接跑在节点里的原生代码另一种是编译成 WASM 的链上版本。链上时刻保存着 Runtime 的 WASM 字节码当新版本通过升级机制写进链上后节点后续执行区块会自动加载新 WASM 来跑逻辑。这意味着无分叉升级成为可能。传统链一旦部署业务逻辑就锁死了要改只能硬分叉。Substrate 下只要 Runtime 版本号更新旧节点会从链上拉取新的 WASM 并继续同步不会产生分叉。这一点对任何商业场景都是刚需毕竟没有哪套业务逻辑是一上线就永远正确的。不仅仅是升级模块复用在 Substrate 生态里也是真真切切的。官方维护的 FRAME 框架里已经有 system、balances、sudo、transaction payment 等成熟模块业务上只需要专注自己的部分其余直接装配进去。这种乐高积木式的开发方式后来也是我们团队能快速交付的关键。2. 环境准备与第一个节点启动2.1 Rust 工具链的版本坑如果你直接把官网文档里的安装命令复制粘贴大概率会在编译阶段遇到一堆报错。Substrate 对 Rust 工具链版本非常敏感它要求特定版本的 nightly 编译器而不是最新的 nightly。社区里有一个通用的排错原则先看仓库根目录下有没有rust-toolchain.toml文件如果有就老老实实按它锁定的版本装。我当时拿到 substrate-node-template 模板第一件做对的事就是先检查这个文件。文件里会写[toolchain] channel nightly-2024-07-17 components [rustfmt, rust-src] targets [wasm32-unknown-unknown]wasm32-unknown-unknown这个 target 一定不能漏装因为 Runtime 要编成 WASM。一旦环境对不上后面在cargo build --release阶段会报各种莫名其妙的链接错误排查起来非常痛苦。安装完指定 nightly 后建议再执行一次rustup target add wasm32-unknown-unknown和cargo install sccachesccache 是后面优化编译速度的关键工具这点后面详细说。2.2 从模板到 dev 链的首次启动环境就绪后克隆官方模板git clone https://github.com/substrate-developer-hub/substrate-node-template.git cd substrate-node-template cargo build --release第一次编译是整个生命周期里最考验耐心的一步。在这台配置一般的机器上大概16G内存6核新环境全量编译耗时在40到60分钟期间主要卡在substrate系列底层依赖的编译上。如果你的机器内存小于8G强烈建议先把 swap 空间临时加大否则 Rust 编译内存溢出会直接 OOM 挂掉。编译完成后启动开发链./target/release/node-template --dev--dev模式会自动生成一个带预置账户的开发数据库并且默认单节点出块不需要外部验证人。观察日志输出能看到Preparing start round、Importing block这样的日志说明链已经正常出块了。如果出现Retrying这种网络相关日志先别慌单节点 dev 模式偶尔因为时间偏差也会重试连接只要区块高度在涨就没问题。2.3 源码结构速览node / runtime / pallets首次打开仓库千万别一头扎进 lib.rs 里读代码先理清目录结构。整个模板分三大部分node/节点可执行程序负责网络、共识、RPC 服务等底层功能大部分场景不需要改动。runtime/链上的业务运行环境里面通过construct_runtime!宏声明这条链包含哪些模块是调度中心。pallets/业务模块源码。模板自带的pallet-template就是我们写自定义逻辑的起点。我见过不少同事一开始把node/里的代码改得乱七八糟其实 90% 的业务开发都只发生在runtime/和pallets/。节点代码动得越少越好它属于基础设施我们团队后来甚至直接把它当成黑盒只在必要的时候升级依赖版本。3. Runtime 是灵魂pallet 与 extrinsic 的工作方式3.1 把业务逻辑想象成乐高积木Substrate 的业务层由若干 pallet 并列组成。pallet 可以理解成打包好的业务模块每个模块提供一组存储项和一组可被外部调用的函数。比如balancespallet 管账户余额systempallet 管账户身份和区块基础数据sudopallet 允许超级管理员执行敏感操作。要什么功能就往construct_runtime!宏里加什么这比传统开发里的引依赖还要清爽因为这些 pallet 是真真切切和链上存储绑定在一起的。自己写的业务 pallet 结构上也是同一个套路。最外层是#[frame_support::pallet]宏声明紧跟着的是Configtrait。这个 Config 是 pallet 与 Runtime 之间的接口约定常见的是把 RuntimeEvent 类型传进来这样 pallet 里 emit 的事件才能被外界看见。初学者容易在这里卡住因为 trait 关联类型和各种宏组合看起来很吓人但本质上就是依赖注入那一套理解了就好。3.2 存储抽象StorageValue / StorageMap / StorageDoubleMappallet 里的数据要持久化不能直接丢在全局变量里。Substrate 的 FRAME 提供了几种存储声明宏最常用的三个StorageValue存储单个值比如当前存证数量。StorageMap键值对映射比如存证哈希 - 存证人账户地址。StorageDoubleMap双键映射适合账号 - 资产凭证 - 数量这类结构。每个存储项在链上都对应一段确定的存储 key帧中会生成对应的 getter 函数。写业务时要注意 key 的哈希算法选择比如StorageMap默认常用Blake2_128Concat它的好处是抗哈希冲突、安全性高Twox64Concat速度极快但碰撞性弱一般只建议用于内部索引类数据如果把用户输入的敏感内容直接放进 Twox key有被碰撞攻击的风险。这块不用背记住一个原则对外不可信的数据用 Blake2内部自生成的序号可以用 Twox。3.3 一个 extrinsic 从哪里来到哪里去extrinsic 是 Substrate 中交易/调用的统称也就是用户发给链上的指令。一个典型流程是这样的用户构造一笔调用签名后广播到网络节点把它放进交易池并在出块时打包进区块Runtime 根据调用字段找到对应 pallet 里的执行函数执行存储读写执行成功后触发事件失败则回滚该笔调用的所有状态变更。写 pallet 时#[pallet::call]宏下面定义的函数就是 extrinsic。每个函数必须用#[pallet::weight]标注权重它决定这笔调用会消耗多少手续费。权重不是摆设它直接关系到链的安全如果某笔调用执行成本无限高交易池就可能被恶意高耗能调用阻塞。养成习惯每次新增 call都先估一下最坏情况的计算开销宁可权重设高一点。4. 亲手写一个存证 pallet完整实操记录4.1 pallet 骨架config / storage / call / error从模板开发一个文件存证功能是最经典的练手。需求很简单用户提交一段内容哈希链上记录提交人和时间证明这个内容在某个时间点已经存在。之后任何人都可以查询某段哈希的存证信息原提交人可以选择撤销。首先在pallets/下新建一个proof-of-existence目录按照模板 pallet 的格式搭建骨架。pallet 顶层结构大致如下#[frame_support::pallet] pub mod pallet { use frame_support::pallet_prelude::*; use frame_system::pallet_prelude::*; use sp_std::vec::Vec; #[pallet::config] pub trait Config: frame_system::Config { type RuntimeEvent: FromEventSelf IsTypeSelf as frame_system::Config::RuntimeEvent; } #[pallet::pallet] pub struct PalletT(_); #[pallet::storage] #[pallet::getter(fn proofs)] pub type ProofsT: Config StorageMap _, Blake2_128Concat, Vecu8, (T::AccountId, BlockNumberForT), ; #[pallet::event] #[pallet::generate_deposit] pub enum EventT: Config { ProofClaimed(T::AccountId, Vecu8), ProofRevoked(T::AccountId, Vecu8), } #[pallet::error] pub enum ErrorT { AlreadyClaimed, NoPermission, NotExist, } }这个骨架里有几个容易忽略的细节。#[pallet::getter(fn proofs)]会自动生成一个查询函数允许 RPC 和 runtime 内部直接按 key 读取存储省去手写查询。BlockNumberForT替代老的T::BlockNumber新版本里不要再用后者否则会有 deprecation 警告。sp_std::vec::Vec是为了兼容 no_std 环境Runtime 在 WASM 中运行不能直接依赖标准库的某些特性。4.2 实现 claim 与 revoke接下来是核心逻辑。claim接受一个内容哈希存储映射新增一条记录revoke要求调用者是原存证人才可以删除记录。#[pallet::call] implT: Config PalletT { #[pallet::call_index(0)] #[pallet::weight(10_000)] pub fn claim(origin: OriginForT, hash: Vecu8) - DispatchResult { let sender ensure_signed(origin)?; ensure!(!Proofs::T::contains_key(hash), Error::T::AlreadyClaimed); let block_number frame_system::Pallet::T::block_number(); Proofs::T::insert(hash, (sender.clone(), block_number)); Self::deposit_event(Event::ProofClaimed(sender, hash)); Ok(()) } #[pallet::call_index(1)] #[pallet::weight(10_000)] pub fn revoke(origin: OriginForT, hash: Vecu8) - DispatchResult { let sender ensure_signed(origin)?; let (owner, _) Proofs::T::get(hash).ok_or(Error::T::NotExist)?; ensure!(owner sender, Error::T::NoPermission); Proofs::T::remove(hash); Self::deposit_event(Event::ProofRevoked(sender, hash)); Ok(()) } }这里有几个专业细节值得展开。ensure!和ensure_signed!是 FRAME 提供的守卫宏条件不满足就返回对应错误浅显的原理是快速失败。call_index是这个 call 在 pallet 内的序号一旦上线稳定后不要随意改动否则会导致链上已有交易解码错乱。我见过有团队在开发中改这个序号引发链上数据错乱属于低级但致命的失误。hash参数的上限问题也要提前想清楚。如果允许用户传入任意长度 Vec那存储会被无限大的 key 撑爆。生产环境必须用BoundedVecu8, ConstU3264或者直接统一哈希长度比如让用户传进 32 字节的[u8; 32]。框架给了BoundedVec就是为了防止这类无界存储写案例时忽略真实上线前一定要补上。4.3 挂载到 runtime 并跑通测试pallet 写完后需要把它注册进 runtime。以模板为例在runtime/src/lib.rs里做三件事。先声明模块类型impl pallet_proof_of_existence::Config for Runtime { type RuntimeEvent RuntimeEvent; }再把它加进construct_runtime!construct_runtime!( pub struct Runtime { System: frame_system, ... ProofOfExistence: pallet_proof_of_existence, } );最后在Cargo.toml的 runtime 部分加入依赖。完成这三步再编译如果有RuntimeEvent类型对不上的问题会在编译期直接报出来。框架的宏检查很严格这反而是好事很多业务逻辑错误在编译期就被拦截了。测试方面推荐在 pallet 内直接写#[cfg(test)]单元测试。基本套路是用new_test_ext()构造一个测试环境然后调用 pallet 的函数看看存储和事件是否符合预期。一个最简单但最关键的测试用例是同一个哈希不能被重复存证这个用例把AlreadyClaimed这个错误路径覆盖掉实际问题排查时能帮你快速确认业务守卫逻辑是否挂上了。5. 编译、测试与升级三个真实项目里绕不开的坎5.1 为什么 cargo build --release 这么慢Substrate 的编译链之重用过的人都有体会。底层依赖包括 substrate 自身的 nodes、primitives、frame以及 tokio、serde 这些重型 Rust 库第一次全量编译动辄一小时。我们团队踩了一段时间后总结出一套提速方案。第一安装 sccache 并配置环境变量让本地编译缓存复用中间产物。第二把target目录单独指到一块空间充足的磁盘并用CARGO_INCREMENTAL0减少增量编译带来的内存压力。最重要的是只有确定要跑通端到端流程时才做完整 release 编译平时写业务代码可以用SKIP_WASM_BUILD1跳过 WASM 构建只编 native 版本。原理解释一下WASM 构建是 Runtime 编译里最耗时的一环开发验证阶段链路还在频繁变动这时候纠结 WASM 纯粹是浪费时间。当然这仅限本地开发真正准备链上升级和测试网验证时必须完整编译。5.2 单元测试的正确姿势Substrate 里写业务测试有两个最容易出问题的点。一是测试环境初始化要用frame_support::test宏配合sp_io::TestExternalities。模板在src/tests.rs里已经写了模板照抄再加自己的用例即可。二是要理解调用失败时存储变更会回滚。我在多笔调用组合测试里经常遇到上一笔已经写入的数据下一笔怎么不见了的疑问实际是上一笔由于一个 error 被整体回滚了。这是交易级原子性在起作用避免出现写入一半的状态。console.log 式的调试在链上开发依旧有效。在 pallet 测试代码里用frame_support::print或标准的log宏输出中间变量确认执行路径是否正确。不过要注意这类输出只在测试环境能看到正式链上不会打到日志里。5.3 链上升级set_code 与存储迁移Substrate 的无分叉升级不是改完代码自动上天必须主动触发。最朴素的方式是通过systempallet 的set_code接口把新 Runtime 的 WASM 提交上去。开发阶段通常用sudo调用该接口一旦代码出问题还能用 sudo 回滚到旧版本。真正复杂的是存储迁移。如果新 Runtime 新增了存储项、改写了存储结构光 set_code 不够旧数据对不上新结构节点同步后很可能在读取时 panic。框架提供了#[pallet::hooks]里的on_runtime_upgrade钩子专门用来做数据迁移。这个钩子在 Runtime 升级后、业务块执行前被调用你在这里遍历旧存储、构造新存储、返回消耗的权重。搬迁数据的写法要格外小心。这里有一个行业共识级的建议迁移逻辑一定要先在本地旧版本链上跑通一遍用 try-runtime 工具在真实历史状态上模拟升级流程确认没有 panic、存储键没有覆盖再拿到生产网上执行。我们团队早期跳过这一步直接升级测试网结果存储 map 的 key 哈希算法从 Twox 改成 Blake2 后所有数据都查不到了前后花了一整天才排查出来。凡是涉及存储 key 格式变化的升级没有捷径测试前置。6. 我踩过的坑与选型建议6.1 版本漂移带来的连环问题Substrate 的版本演进速度非常快一个库的接口在几个月内就可能废弃。最典型的例子是 pallet 宏从#[pallet]变成#[frame_support::pallet]以及BlockNumberFor替换T::BlockNumber。如果你在网上搜代码示例很可能搜到的是两年前的旧写法粘进新版本编辑器会直接报错。避免版本问题有一个硬措施锁定依赖版本。模板根目录的Cargo.toml里依赖版本都是固定的不要轻易cargo updaterust-toolchain.toml里的 nightly 版本也要保持和模板一致。每次想要升级依赖先在本地另开分支跑一遍全量测试确认没有兼容问题再合并。我们团队踩过最惨的一次是依赖整体升了三个小版本结果 consensus 配置的 trait 约束变了链启动后直接 panic回滚也费了不少功夫。6.2 什么时候别用 Substrate抛开技术热情Substrate 并不适合所有项目。如果你的业务就是一个简单的 Token 转账应用实体用户不多直接用合约平台反而更省心。Substrate 的学习曲线陡、编译链重、运维成本高团队没有 Rust 功底会非常痛苦。我们评估一个新项目是否上链时第一条就是问业务逻辑是否真的有不可篡改、账本共享、自定义交易类型这类强需求。没有的话用传统数据库反而更高效。反过来如果你的业务需要自定义手续费模型、共识算法、隐私机制或者是 Polkadot 生态里的平行链那 Substrate 几乎是绕不开的答案。它给了你完整的链级设计自由而不是只能在合约层面翻花活。最后再分享一个小技巧如果你第一次接触 Substrate不要一上来就规划复杂的大 pallet。先用模板跑通 dev 链然后照抄一个最简单功能的 pallet 挂上去亲眼看自己的业务逻辑在链上产生区块、触发事件。这个手感建立起来之后再去啃宏、存储、升级这些更深的机制效率和信心都会完全不一样。
