Linera 上手实战：从零创建微链钱包、部署第一个 Wasm 应用并通过 GraphQL 查询

Linera 上手实战：从零创建微链钱包、部署第一个 Wasm 应用并通过 GraphQL 查询

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

导读

本指南基于 Linera 官方入门文档 hello_linera.md，带你走通 Linera 协议开发的第一条完整链路：初始化开发者钱包、接入最新 Testnet（测试网）或本地开发网络、编译counter示例应用、发布到链上，最后通过 GraphQL 查询应用状态。读完本篇，你将拥有一个属于自己的 Linera 微链（microchain）以及一个可查询、可交互的可运行应用。

前置准备：安装 Linera 工具链

在开始之前，需要先安装 Linera 开发工具链，详细步骤见 安装指南。概括来说，Linera 工具链由以下几个 crate 组成：

• linera-sdk：编写 Linera 应用（Wasm 合约）的核心 Rust 库；
• linera-service：提供linera主客户端，用于操作开发者钱包、启动本地测试网络；
• linera-storage-service：为本地测试与开发提供简单数据库，用于运行验证节点。

当前仓库对应的发布版本为0.16.0（见 RELEASE_VERSION），安装时建议使用与当前 Testnet 兼容的版本。安装完成后可用linera --version验证，并确保本机已添加wasm32-unknown-unknown编译目标（rustup target add wasm32-unknown-unknown）。

在最新 Testnet 上创建开发者钱包

与 Linera 网络交互的第一步，是获得一个开发者钱包、一条新的微链以及一些初始代币。这三者可以一次性通过查询 Testnet 的faucet（水龙头）服务获得：

linera wallet init --faucet https://faucet.testnet-conway.linera.net linera wallet request-chain --faucet https://faucet.testnet-conway.linera.net

其中testnet-conway对应当前发布域（见 RELEASE_DOMAIN）。两条命令的作用分别是：

1. linera wallet init：初始化本地钱包文件（含密钥库），并接入指定的 faucet 服务；
2. linera wallet request-chain：向 faucet 请求分配一条带有初始余额的新微链，并将其记录到钱包中。

如果执行时返回错误，请确认使用的 Linera 工具链版本与当前 Testnet 兼容，参考 安装指南 中的"从 crates.io 安装"一节，使用与 RELEASE_VERSION（0.16.0）一致的版本。

什么是 Linera Testnet？Linera Testnet 是用于测试的 Linera 协议部署。一次部署由多个 验证器（validators） 组成，每个验证器运行一个前端服务（即linera-proxy）、若干 worker（即linera-server）以及一个共享数据库（默认是linera-storage-service）。

使用本地测试网络

如果不想依赖公共 Testnet，也可以在本机启动一个完整的本地开发网络：

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

该命令会以默认分片（shard）数量启动一个验证器，并同时启动一个 faucet 服务（监听8080端口）。然后在另一个终端窗口中创建钱包：

linera wallet init --faucet http://localhost:8080 linera wallet request-chain --faucet http://localhost:8080

与 Testnet 唯一的区别只是 faucet 的地址从 HTTPS 域名换成了本地端口。

⚠️重要提醒：钱包仅在它所属网络的整个生命周期内有效。每当本地网络重启，都必须删除旧钱包文件并重新创建（详见下文"多钱包管理"中的环境变量方式，方便快速切换）。

使用多个开发者钱包与多个网络

默认情况下，linera命令会在由操作系统决定的配置路径下寻找钱包文件。如果你希望自己指定钱包文件的存放位置（例如为了同时维护多个网络的钱包），可以设置以下三个环境变量：

DIR=$HOME/my_directory mkdir -p $DIR export LINERA_WALLET="$DIR/wallet.json" export LINERA_KEYSTORE="$DIR/keystore.json" export LINERA_STORAGE="rocksdb:$DIR/wallet.db"

• LINERA_WALLET：钱包文件路径（保存链与应用的映射关系）；
• LINERA_KEYSTORE：密钥库文件路径（保存密钥对）；
• LINERA_STORAGE：客户端本地存储后端，示例中使用rocksdb:前缀指定 RocksDB 数据库文件。

由于钱包总是与创建它的网络绑定，选择独立目录存放不同网络的钱包，可以避免在 Testnet 与本地网络之间切换时互相污染。

⚠️开发者钱包 vs 生产钱包：由lineraCLI 创建的"开发者钱包"由开发者工具操作，仅用于测试与开发。生产环境的用户钱包通常由浏览器扩展、移动应用或硬件设备托管，二者不可混为一谈。

与 Linera 网络交互

钱包就绪后，可以通过两条命令确认网络工作正常——先将本地链与网络其余部分同步，再查询链上余额：

linera sync linera query-balance

如果一切正常，第二条命令会输出一个数字，例如10，表示 faucet 为你分配的初始代币余额。

构建示例应用：counter

Linera 上的应用以Wasm（WebAssembly）字节码形式运行，每个验证器与客户端都内置了 Wasm 虚拟机（VM）来执行这些字节码。也就是说，你写的应用会先编译成.wasm文件，再发布到链上。

先构建examples/目录下的counter示例应用（该示例的完整源码位于仓库 examples/counter）：

cd examples/counter && cargo build --release --target wasm32-unknown-unknown

编译产物为target/wasm32-unknown-unknown/release/counter_contract.wasm与counter_service.wasm两个文件。从 examples/counter/Cargo.toml 可以看到，counter 应用定义了两个二进制目标：counter_contract（合约，入口 src/contract.rs）与counter_service（服务，入口 src/service.rs）。

从源码结构看，counter 应用的代码组织遵循 Linera 应用的标准分层：

• ABI 层（src/lib.rs）：定义CounterAbi与操作类型CounterOperation::Increment { value }，声明合约操作返回u64，服务查询使用 GraphQL 的Request/Response；
• 状态层（src/state.rs）：通过RegisterView<u64>定义唯一状态字段value，并标注为 GraphQLSimpleObject，使value自动成为可查询字段；
• 合约层（src/contract.rs）：instantiate(value)用初始化参数写入计数器初始值，execute_operation处理Increment操作并返回新值；
• 服务层（src/service.rs）：基于async-graphql构建 schema，提供value查询，并定义了increment变更（mutation），通过schedule_operation把操作提交回合约执行。

合约与服务的单元测试也一并在仓库中提供（见 src/contract.rs 的operation/message/cross_application_call测试，以及 src/service.rs 的query测试），可作为编写自有应用时的参考模板。

发布你的应用

编译完成后，使用linera客户端的publish-and-create命令，将字节码发布到本地网络并创建应用实例。该命令需要提供三个要素：

1. 合约字节码（contract bytecode）的位置；
2. 服务字节码（service bytecode）的位置；
3. JSON 编码的初始化参数。

linera publish-and-create \ target/wasm32-unknown-unknown/release/counter_{contract,service}.wasm \ --json-argument "42"

其中counter_{contract,service}.wasm是 bash 的花括号展开语法，等价于依次传入两个 wasm 文件；--json-argument "42"指定初始化参数为42——对应instantiate中self.state.value.set(value)写入的初始计数。命令成功执行后，你的第一个 Linera 应用就发布到链上了！

查询你的应用

接下来验证应用是否可用。为此需要把linera客户端运行在service 模式下——此时客户端同时充当一个节点（node），具备执行区块、暴露 GraphQL API、监听验证器通知并自动更新本地链等能力（详见 节点服务）：

linera service --port 8080

在浏览器中打开http://localhost:8080，即可进入GraphiQL（GraphQL 交互式 IDE）。首先列出默认链上部署的所有应用：先通过linera wallet show查看你的 chain ID，然后执行：

query { applications(chainId: "...") { id description link } }

由于只部署了一个应用，返回结果只有一条记录。注意返回 JSON 底部的link字段——将它复制到新浏览器标签页打开，就能进入该应用的专属 GraphiQL 界面（其底层地址形如localhost:8080/chains/<chain-id>/applications/<application-id>）。最后，查询计数器当前值：

query { value }

结果返回42，正是我们在publish-and-create时指定的初始化参数。至此，你已经完成了"建钱包 → 连网络 → 编应用 → 发布 → 查询"的完整闭环。

如果你想进一步体验交互性，可以试试服务层暴露的变更操作：在 src/service.rs 中，MutationRoot定义了increment(value: u64)变更，它通过schedule_operation把CounterOperation::Increment提交回合约执行；执行后再查询value，就会看到计数增加。

小结

通过本指南，你掌握了 Linera 开发的基础工作流：

下一步可以继续阅读 核心概念：微链 理解 Linera 的并行执行模型，或通过 节点服务 深入了解 GraphQL API 的完整能力，也可以直接阅读 examples/counter/README.md 以及仓库中 examples 目录下的fungible、crowd-funding、matching-engine等更多示例应用。

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