企业官网建设流程全解析

Linera Protocol 仓库深度指南：从零搭建本地微链测试网络并运行跨链转账

【免费下载链接】linera-protocolMain repository for the Linera protocol项目地址: https://gitcode.com/GitHub_Trending/li/linera-protocol

导读

Linera 是一条专为高扩展性、安全且低延迟 Web3 应用而设计的去中心化区块链基础设施，其核心思想是将区块链的计算与验证按"微链"（microchain）拆分，从而让每条链独立并行出块。本指南以本仓库根目录 README.md 为骨架，完整还原"编译二进制 → 拉起本地测试网络 → 创建钱包 → 申请微链 → 跨链转账"的全流程，并结合 linera-service 的命令行实现、Cargo.toml 的工作区依赖与 INSTALL.md 的安装前提做源码级补充。读完本文，你将能在本机用lineraCLI 工具在几分钟内搭起一条含水龙头（faucet）的本地 Linera 网络，并熟练使用钱包、链、账户三层抽象完成代币的跨链转移。

一、Linera 协议是什么：一条为并行而生的链

Linera 在 README.md 中被定位为 "decentralized blockchain infrastructure designed for highly scalable, secure, low-latency Web3 applications"。与单链或简单分片的方案不同，Linera 把"链"的粒度切得非常细——每个用户（或应用）可以拥有自己的微链，多条微链之间互不阻塞，跨链消息通过验证者网络异步转发。这种架构直接对应本仓库中的两个核心 crate：

• linera-chain 负责微链的数据模型：块（block）、证书（certificate）以及跨链消息（cross-chain messaging）的持久化结构与逻辑；
• linera-core 实现协议核心，包括客户端与服务端逻辑、节点同步等。

从工作区配置 Cargo.toml 可以看到，本仓库是一个包含 30 多个成员 crate 的 Cargo workspace，版本号统一为0.16.0（见 workspace.package），许可证为 Apache-2.0。下面按 README 的仓库结构说明，从低到高梳理这条依赖链，方便你定位后续命令背后的代码。

1.1 分层依赖：从密码学到应用 SDK

README 在 "Repository Structure" 一节按依赖图从低到高列出了主要 crate，结合工作区配置可以归纳为五层：

说明：linera-views的过程宏实现在linera-views-derive，linera-sdk的过程宏实现在linera-sdk-derive，这一点在 README 中有明确交代（README.md、README.md），也是你在阅读视图宏与合约宏生成代码时的入口。

1.2 CLI 二进制从哪来：linera-service

README 快速上手的第一步是编译并运行linera命令，这个命令来自 linera-service。其 CLI 入口在 linera-service/src/cli/options.rs，由 clap 解析：

• 顶层Options组装了客户端通用选项（linera_client::Options）、钱包/密钥库/存储通用选项（CommonCliOptions），以及块缓存、执行状态缓存大小等调优参数；
• 子命令枚举ClientCommand定义在 linera-service/src/cli/command.rs，覆盖转账、开链、查余额、同步、发布应用、查询验证者等全套操作；
• 钱包相关子命令WalletCommand也在同一文件中（command.rs），下文要用到的wallet init、wallet show、wallet request-chain均在此列。

因此，"先编译、再export PATH"是让linera进入$PATH的前提，而非下载某个预置二进制。

二、安装前提与编译准备

2.1 平台要求与依赖

本仓库的开发依赖细节记录在 INSTALL.md。核心要点如下：

• 磁盘空间：Rust 编译需要足够的空闲磁盘空间（这是 README 指向 INSTALL.md 的首要原因）；
• Windows 用户：应使用 WSL，并遵循 Linux 安装步骤；
• macOS（Intel/M1/M2）：需要 Xcode 命令行工具（xcode-select --install）、Homebrew、Rust（brew install rustup-init后rustup target add wasm32-unknown-unknown）、Clang/LLVM（brew install llvm@18并按提示更新 PATH）以及 Protoc（brew install protobuf）；
• Linux：需要 Git、Rust（rustup 安装后务必执行rustup target add wasm32-unknown-unknown）以及 Protoc（INSTALL.md 给出了下载 protoc v21.11 到$HOME/.local的完整命令）。

之所以要求wasm32-unknown-unknowntarget，是因为 Linera 应用以 Wasm 字节码形式运行（见 linera-sdk 与 linera-execution/src/wasm），而 Protoc 则是 linera-rpc/proto/rpc.proto、linera-storage-service/proto/key_value_store.proto 等 gRPC 定义生成 Rust 代码的编译期依赖。

2.2 Nix 开发环境（可选）

除传统安装外，仓库还提供了实验性 Nix 支持（flake.nix、shell.nix）。在仓库根目录执行：

nix develop

即可进入可复现的开发环境，随后正常使用cargo build或cargo install。如果安装了 direnv，也可以直接direnv allow在进入项目目录时自动加载该环境（INSTALL.md）。

2.3 编译二进制

# 在仓库根目录 cargo build -p linera-storage-service -p linera-service --bins

这条命令来自 README.md 的注释。它编译两个目标：linera-service（提供lineraCLI 与验证者/代理二进制）和linera-storage-service（独立存储服务，本地网络测试中作为链状态存储的后端）。由于工作区在 dev profile 下对linera-wasmer与wasmtime两个 VM 运行时 crate 强制opt-level = 3（Cargo.toml），首次编译耗时较长属正常现象，请耐心等待。

三、快速上手：拉起本地测试网络

3.1 环境准备三步

编译完成后，把二进制加入$PATH，并导入linera_spawn辅助函数（它来自linera net helper，用于以可等待进程的方式启动本地网络，源码入口在 command.rs 附近）：

export PATH="$PWD/target/debug:$PATH" source /dev/stdin <<<"$(linera net helper 2>/dev/null)"

3.2 启动本地测试网络与水龙头

linera_spawn \ linera net up --with-faucet --faucet-port 8080

执行成功后，环境变量LINERA_TMP_DIR会被设置（所有临时文件都放在该目录下），并同时启动：

• 一个本地验证者网络（含代理/前端与存储服务）；
• 一个水龙头（faucet），监听--faucet-port指定的端口（这里为 8080），用于给新钱包发放初始微链与代币。

如果使用公共测试网，则不需要net up，而是：

LINERA_TMP_DIR=$(mktemp -d) FAUCET_URL=https://faucet.testnet-XXX.linera.net # 替换 XXX 为实际网络代号

然后从# Remember the URL of the faucet之后的步骤继续（README.md）。

3.3 启用应用日志（可选）

用户应用的日志默认关闭，可通过环境变量打开：

export LINERA_APPLICATION_LOGS=true

该开关对应 CLI 中的application_logs配置，会被传递到存储运行环境（见 linera-service/src/cli/options.rs 中run_with_storage对日志参数的处理），调试合约时非常有用。

四、钱包、链与账户：Linera 的三层抽象

在跑命令之前，先厘清 Linera 的数据模型。源码中linera-base的标识符模块定义了三个核心概念（linera-base/src/identifiers.rs）：

• 链（Chain）：由ChainId标识的微链，是出块与状态的基本单元；
• 账户（Account）：表示为OWNER@CHAIN-ID或单独CHAIN-ID（后者即链账户，chain account）。query-balance、transfer的--from/--to参数都接受这种写法（command.rs）；
• 钱包（Wallet）：本地的密钥与链集合，持久化为wallet.json与keystore.json两个文件，并配一个链状态存储。

这正是 README 中linera wallet show能展示"钱包跟踪的多个链"、query-balance "$CHAIN1"与query-balance "$ACCOUNT1@$CHAIN1"两种查询语义不同的原因。

4.1 配置钱包相关环境变量

export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json" export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json" export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"

• LINERA_WALLET/LINERA_KEYSTORE：钱包与密钥库文件路径；
• LINERA_STORAGE：本地链状态存储，格式为<后端>:<路径>，这里使用 RocksDB。linera-storage-service进程正是为了服务这种本地存储后端而存在的。

4.2 初始化钱包并从水龙头领取微链

linera wallet init --faucet $FAUCET_URL

wallet init支持两种初始化方式：--faucet <URL>从水龙头拉取创世配置，或--genesis <PATH>直接加载创世配置文件（command.rs）。注意源码注释明确："Either this or--faucetmust be specified"，且--genesis优先于--faucet。对本地测试网，走--faucet即可。

接着申请两条微链：

INFO1=($(linera wallet request-chain --faucet $FAUCET_URL)) INFO2=($(linera wallet request-chain --faucet $FAUCET_URL)) CHAIN1="${INFO1[0]}" ACCOUNT1="${INFO1[1]}" CHAIN2="${INFO2[0]}" ACCOUNT2="${INFO2[1]}"

wallet request-chain会向水龙头申请一条新微链并把结果（链 ID、账户地址）打印到标准输出，因此可以用 bash 数组直接捕获。除了--faucet（也支持环境变量LINERA_FAUCET_URL），它还支持--set-default（将该链设为钱包默认链）与--fund-owner-account（把代币记到所有者账户而非链账户，见 command.rs）。

查看钱包当前跟踪的链：

linera wallet show

4.3 查询余额

linera query-balance "$CHAIN1" linera query-balance "$CHAIN2"

query-balance会先模拟执行本地收件箱中的待处理消息生成一个块，再从本地状态读取指定账户的原生代币余额（command.rs 的注释明确说明了这一行为）。因此它依赖钱包本地状态已经同步；如需先与验证者同步，可执行linera sync（command.rs）再查询。

五、跨链转账实战

5.1 链间转账

linera transfer 10 --from "$CHAIN1" --to "$CHAIN2" linera transfer 5 --from "$CHAIN2" --to "$CHAIN1"

transfer子命令的定义在 command.rs：位置参数amount是转账金额，--from是发送方账户（必须是钱包拥有的链之一），--to是接收方账户。转账本身是一条跨链消息：发送链上产生的块会把消息放入发件箱（outbox），验证者网络将其转发到目标链的收件箱（inbox），目标链在后续块中执行。这个机制正是 linera-chain 与 [linera-chain/src/outbox.rs) 两个模块的实现主题。

转账后再查余额验证结果：

linera query-balance "$CHAIN1" linera query-balance "$CHAIN2"

5.2 账户间转账

链间转账之后，README 演示了把代币从链账户转入用户账户，再在用户账户之间划转：

linera transfer 5 --from "$CHAIN1" --to "$ACCOUNT1@$CHAIN1" linera transfer 2 --from "$ACCOUNT1@$CHAIN1" --to "$ACCOUNT2@$CHAIN2"

这里--to "$ACCOUNT1@$CHAIN1"表示把代币记到 CHAIN1 上由 ACCOUNT1 所有者的账户名下（而不是链账户）。由于两笔转账都在本地钱包拥有的链上发起，且钱包持有对应私钥，因此无需额外授权即可签名出块。最后再查一次账户余额：

linera query-balance "$ACCOUNT1@$CHAIN1" linera query-balance "$ACCOUNT2@$CHAIN2"

小技巧：query-balance与local-balance的区别值得留意。local-balance直接读取本地状态，不反映仍在收件箱中等待处理的消息；而query-balance会先处理待定消息再读余额。官方推荐流程是linera sync后再用query-balance或process-inbox && local-balance获取"合并后的余额"（command.rs）。

5.3 结果验证与后续

以上全部命令组合起来，就是一段完整、可复现的本地网络冒烟测试：建网 → 领两条链 → 链间互转 10/5 单位 → 账户间划转 5/2 单位 → 全程查询余额确认。README 还提示，更复杂的用例可以在开发者手册以及本仓库的 examples 示例应用中找到。

六、示例应用：从钱包到合约

examples目录中的每个子项目都是一个完整的 Linera 应用（均带Cargo.toml与测试），可作为从"CLI 转账"进阶到"编写合约"的跳板：

• counter：最经典的计数器合约，适合作为第一个阅读的 SDK 用例；
• fungible：可替换代币（含 web-frontend）；
• non-fungible、gen-nft：NFT 相关；
• amm、matching-engine、rfq：DeFi 场景（自动做市、撮合引擎、报价请求）；
• social：社交类应用；
• crowd-funding：众筹；
• llm、agent、task-processor：AI/任务处理方向的应用；
• call-evm-counter、ethereum-tracker、bridge-demo：与 EVM 链交互/桥接场景。

这些示例以path依赖的形式注册在工作区中（Cargo.toml），比如fungible = { path = "./examples/fungible" }，意味着你可以直接cargo build -p fungible编译并部署到本地测试网。

七、参与贡献

如果你希望为本仓库贡献代码，README.md 给出的流程是：Fork 仓库 → 创建功能分支（git checkout -b feature/amazing-feature）→ 提交改动 → push 分支 → 提交 Pull Request。更详细的规范请参阅 CONTRIBUTING.md。

总结

本文以仓库根 README.md 为主线，走完了 Linera 本地开发的完整闭环：理解架构与 crate 分层 → 安装依赖并编译 →linera net up拉起本地网络与水龙头 → 初始化钱包、申请微链 → 执行链间与账户间转账并验证余额 → 进阶到examples示例应用。无论你是想快速体验微链架构，还是准备用linera-sdk编写第一个 Wasm 应用，这套流程都是后续所有开发工作的起点；对应的命令实现、环境变量与数据模型，均可在 linera-service/src/cli 与 linera-base/src/identifiers.rs 中追根溯源。

【免费下载链接】linera-protocolMain repository for the Linera protocol项目地址: https://gitcode.com/GitHub_Trending/li/linera-protocol