IOTA 学习笔记（八）：本地启动 IOTA Localnet

上一期我们讲解了 IOTA CLI 的基础操作，包括网络环境管理、地址查询、对象查询和 Move 合约调用。掌握 CLI 后，我们就可以在本地搭建一个完整的 IOTA 测试网络——Localnet，为合约和交易调试提供可控环境。

本地网络非常适合初学者，因为它不依赖主网，也不消耗真实代币，可以随意重置状态、多次测试交易和合约逻辑。

1. 为什么使用 Localnet

使用 Localnet 有几个重要理由：

1. 安全可控：测试交易和合约不会影响主网状态。

2. 便于调试：可以观察对象、交易和 checkpoint 状态，排查函数执行问题。

3. 重复实验：可以随意重置网络，重复部署合约或测试交易。

4. 快速验证：在本地即可测试 Move 合约、对象创建、转移和共享对象逻辑。

简而言之，Localnet 是理解 IOTA 对象模型、交易和 Move 合约最直观的实验环境。

2. 启动 Localnet

Localnet 需要 IOTA CLI 已安装，并且本地节点支持 RPC 通信。

基本命令

iota-localnet start --force-regenesis

说明：

• start启动本地网络。

• --force-regenesis表示重新生成网络创世状态（Genesis），确保网络状态干净。

• 命令执行完成后，会在本地启动多个节点模拟验证者网络。

成功启动后，你会看到日志信息，例如：

IotaNode started! Creating checkpoint executor for epoch 0

这些日志表明 Localnet 节点已经启动，网络开始运行。

3. 配置 CLI 连接 Localnet

启动 Localnet 后，需要在 CLI 中创建并切换到对应的网络环境。

创建网络环境

iota client new-env --rpc http://127.0.0.1:9000 --alias localnet

这里--rpc指定本地节点 RPC 地址，--alias为环境起一个名字，例如localnet。

切换网络环境

iota client switch --env localnet

切换后，CLI 的所有操作都会在本地 Localnet 网络中执行。

查看网络信息

iota client info

输出示例：

Network: localnet RPC node: http://127.0.0.1:9000 Synced: true

4. 检查节点和 Checkpoint 状态

Localnet 会定期生成 checkpoint，用于标记已经最终确定的交易和状态。

查看 checkpoint

iota checkpoint list

输出示例：

Checkpoint sequence: 0, confirmed transactions: 2 Checkpoint sequence: 1, confirmed transactions: 5

• Checkpoint sequence表示网络中形成的稳定状态序号。

• confirmed transactions表示已经被最终确认的交易数量。

观察 checkpoint 有助于理解交易在 DAG 中如何被确认，以及对象状态如何随交易更新。

5. 地址、余额和对象查询

Localnet 中可以像主网一样操作地址和对象：

查看地址

iota wallet address list

查询余额

iota wallet balance --address <ADDRESS>

查询对象状态

iota object get <OBJECT_ID>

这些操作与主网基本一致，但在本地网络中无需担心真实代币或交易费用。

6. 提交交易和调用 Move 合约

在 Localnet 上可以提交交易、调用 Move 合约函数、测试对象操作逻辑。

转账交易示例

iota wallet send --to <ADDRESS> --amount 100

CLI 会自动选择本地 Coin 对象作为输入，并生成新的输出对象。

调用 Move 函数示例

iota move call --package <PACKAGE_ID> --module counter --function create

这会在本地创建新的 Counter 对象并分配给交易发送者。

7. 常见问题与排查

在 Localnet 中可能遇到的一些常见问题：

1. 节点启动失败或 RPC 不通

   • 检查端口占用

   • 确认本地节点已启动

   • 防火墙或 WSL 网络设置可能阻碍 RPC

2. Checkpoint 不更新

   • 节点可能未同步

   • 需要重新启动 Localnet 并使用--force-regenesis

3. 对象查询不到

   • 对象可能未被创建

   • 确认在正确的网络环境下操作

4. 交易失败

   • Gas 对象不足

   • 函数参数或对象引用错误

8. 小结

本期主要讲解了如何在本地启动 IOTA Localnet，并通过 CLI 配置、查询和操作本地网络。

Localnet 的价值在于：

• 提供一个可控实验环境

• 支持合约、对象和交易测试

• 可重复重置，方便调试

掌握 Localnet 使用后，开发者可以在本地验证对象创建、交易执行、Move 函数调用和 checkpoint 机制，为后续更复杂的合约开发打下基础。

下一期，我们将用 Localnet 演示一个最小 Counter 合约的完整流程，包括创建对象、调用函数、查看对象状态。