Rust智能合约入门：别把链上代码想得太神秘

开场三问：今天要解决什么、为什么用 Rust、你卡在哪？

问题 1：这玩意儿解决啥问题？ 你想把一段业务规则放到链上，自助执行、公开透明，谁都改不了。智能合约就是这台“自助服务机”，负责管账、发币、跑游戏逻辑。

问题 2：为什么用 Rust？ 你希望代码既快又稳，别在关键时候内存乱飞。Rust 的零成本抽象和所有权系统，让你在链上这种资源紧张、审计严格的场景里放心交付。

问题 3：你卡在哪？ 大概率卡在第一步：环境不知道怎么搭、工具名字听过没用过，更别说把 wasm 包构建出来。下面我们用最小计数器合约，帮你把第一块砖落下。

快速类比：把区块链 runtime 当成物业智能门禁

把链上 runtime 想成小区物业的智能门禁系统。你的合约就是门禁里的“规则板”——谁刷卡进、什么时候开门、扣谁物业费都写在这里。Rust 编译出的 wasm 包，就像物业要求的标准化门禁芯片：体积要小、行为要可验证、别乱访问邻居的电表。学会写智能合约，其实就是学会把生活里的“门禁规则”翻译成 Rust 代码再塞进芯片里。

原理速写：五个关键点先钉牢

• Rust 智能合约最终编译成 wasm32-unknown-unknown 目标，运行在链上沙箱里。
• 合约需要有固定入口，例如 ink! 的 #[ink::contract] 模块或 CosmWasm 的 instantiate/execute/query 函数。
• 状态存储受限，必须通过框架提供的存储 API 读写，避免裸操作内存。
• 调用者通过交易触发消息，合约逻辑必须保持纯 deterministic（同样输入永远得出同样输出）。
• Gas/weight 是硬指标，任何循环、序列化、日志都要用数据驱动的方式精打细算。

框架地图：ink!、CosmWasm、Anchor 怎么选？

入门门槛：开工前要知道的底子

你至少得熟悉 Rust 基础语法（所有权、借用、模式匹配）、Cargo 工作空间、以及链上的基本概念（交易、状态、Gas）。如果这些概念还模糊，先花半天把 Rustlings 跑完，再回来看合约代码会轻松很多。

工具链准备：命令一步到位

本文示例在 macOS 14.6 (ARM)、Rust 1.80.1 stable、cargo-contract 4.0.0 上验证。按照下面命令安装即可：

rustup default stable
rustup target add wasm32-unknown-unknown
cargo install cargo-contract --force

运行完会看到 rustup 下载 wasm 工具链，并由 cargo 安装最新的 cargo-contract。

额外建议装上 wasm-opt（Binaryen）用来瘦身 wasm，CosmWasm 开发者还会用 cosmwasm-check 验证包体，Anchor 场景需要 solana-cli。

实战步骤：最小 ink! 计数器

我们用 ink! 做一个链上计数器：可以初始化、增加、读取。流程分四步。

第 1 步：初始化工程

cargo contract new ink-counter
cd ink-counter

执行完会生成一个带测试的 ink! 工程骨架。

第 2 步：确认 Cargo.toml

[package]
name = "ink-counter"
version = "0.1.0"
edition = "2021"

[lib]
name = "ink_counter"
path = "lib.rs"
crate-type = ["cdylib", "rlib"]

[dependencies]
ink = { version = "5", default-features = false, features = ["std"] }

[dev-dependencies]
ink = { version = "5", default-features = false, features = ["std", "ink-as-dependency"] }

[features]
default = ["std"]
std = [
    "ink/std",
]

这个配置把项目锁定在 ink! 5 系列，开启 std 以便本地调试。

第 3 步：编写合约代码

#![cfg_attr(not(feature = "std"), no_std)]

#[ink::contract]
mod ink_counter {
    #[ink(storage)]
    pub struct InkCounter {
        value: u32,
    }

    impl InkCounter {
        #[ink(constructor)]
        pub fn new(init: u32) -> Self {
            Self { value: init }
        }

        #[ink(message)]
        pub fn increment(&mut self) {
            self.value = self.value.saturating_add(1);
        }

        #[ink(message)]
        pub fn get(&self) -> u32 {
            self.value
        }
    }

    #[cfg(test)]
    mod tests {
        use super::*;

        #[ink::test]
        fn counter_works() {
            let mut contract = InkCounter::new(10);
            contract.increment();
            assert_eq!(contract.get(), 11);
        }
    }
}

测试默认走 cargo test，跑完会看到 test counter_works ... ok。

第 4 步：构建并检查 wasm 包

cargo contract build --release

完成后输出目录 target/ink/ 下会生成 .wasm、.contract。日志里会看到编译耗时和最终包体大小。

失败复现与修复

如果忘记安装 wasm 目标，cargo contract build 会报错：

error: the target `wasm32-unknown-unknown` is not installed

重新执行 rustup target add wasm32-unknown-unknown 后再编译即可，别忘了确认命令成功。

性能与权衡：WASM 合约的得与失

好处是 wasm 模块体积小、验证快、节点间可以确定性复现；代价是运行时没有标准库的全部能力，调用外部服务必须通过链上 Host 接口。建议在本地启用 wasm-opt -Oz target/ink/ink_counter.wasm 做瘦身，可为每次调用节省 5%~15% 的 Gas，但要留意极端优化可能导致编译时间变长。

常见坑预警

• 忘记在 lib.rs 顶部写 #![cfg_attr(not(feature = "std"), no_std)]，导致链上环境加载失败。
• increment 写成 self.value += 1 却忽略溢出，建议使用 saturating_add 或自定义错误返回。
• 单元测试没有加 #[ink::test] 导致跑的是普通 Rust 测试环境，错过了 storage 模拟。
• 构建后直接部署真网，忽略 cargo contract upload --suri //Alice --execute 这类本地仿真命令，容易浪费费用。
• 多人协作时没锁定 ink! 版本，依赖升级会改变宏生成代码，最好写进 Cargo.lock 并提醒团队。

总结与下一步

• Rust 智能合约可以看作“把规则写进链上门禁芯片”，核心是 wasm 目标与框架 API。
• ink! 帮你处理 runtime 接口和存储细节，你要做的是写清入口函数和状态机。
• 搭建环境、跑通最小计数器后，就能把业务需求拆成一个个消息函数去实现。

下一步行动：

• 用 cargo contract test 补全失败路径测试，看借用检查如何防止状态被意外持有。
• 把 increment 替换成 set、reset 等消息，体验 storage 操作。
• 对比 CosmWasm、Anchor 的入门模板，挑一个你未来业务要落地的链做第二个练习。