IOTA 学习笔记（七）：IOTA CLI 基础操作

上一期我们讲解了 IOTA Move 语言的基础概念，包括 module、struct、function、ability、UID 和 TxContext。理解了对象模型和 Move 的基本概念之后，我们就需要知道如何通过实际工具操作链上对象、调用合约和提交交易。

IOTA 官方提供了 CLI（Command Line Interface）工具，它是开发者与 IOTA 网络交互的基础入口。CLI 可以用来管理地址、查询对象、提交交易、调用 Move 合约函数以及配置本地或远程网络环境。对于初学者来说，熟悉 CLI 是理解 IOTA 流程的第一步。

---

1. 安装和检查 CLI

IOTA CLI 可以通过官方文档提供的安装方式获取。安装完成后，可以用以下命令检查版本：

iota --version

例如，输出可能是：

iota 1.23.2-rc-f91ea9c244d3

确认 CLI 正常运行后，就可以进行下一步配置。

---

2. 创建和管理网络环境

在 IOTA 中，CLI 允许创建不同的网络环境（environment），方便切换不同节点或本地测试网络。

创建新网络环境

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

输出包括：

• 节点 RPC 地址

• 网络名称

• 当前钱包或账户信息

• 节点同步状态

---

3. 地址管理

IOTA CLI 可以创建和查看地址，用于存放对象或代币。

创建新地址

iota wallet address generate

输出示例：

Address: iota1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

这个地址可以用作：

• 接收代币

• 存放合约创建的对象

• 作为交易发送者

查看已有地址

iota wallet address list

显示钱包中所有生成的地址及对应余额。

---

4. 查询余额

IOTA CLI 可以查询指定地址的余额：

iota wallet balance --address <ADDRESS>

输出类似：

Address: iota1qxxxx...
Balance: 1000000

在对象模型下，这个余额通常是多个 Coin 对象的总和。

---

5. 查询链上对象

对象是当前 IOTA 的链上状态基本单位。CLI 提供查询对象的命令：

iota object get <OBJECT_ID>

输出示例：

Object ID: 0xabc123...
Type: Counter
Owner: iota1q...
Version: 3
Data:
  value: 10
Previous Transaction: 0xdef456...

通过 CLI，可以观察对象的当前状态和历史版本。

查看共享对象

共享对象也可以通过对象 ID 查询。由于共享对象可能涉及多用户访问，CLI 会显示当前状态、版本和所有者集合。

---

6. 提交交易

CLI 还可以用来提交交易，包括简单转账、调用 Move 函数和发送 PTB（Programmable Transaction Block）。

转账交易

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

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

调用 Move 合约函数

iota move call --package <PACKAGE_ID> --module <MODULE> --function <FUNCTION> --args <ARGUMENTS>

示例：

iota move call --package 0xabc123 --module counter --function create

这会调用 counter 模块中的 create 函数，创建一个新的 Counter 对象并分配给当前交易发送者。

---

7. Gas 对象与资源管理

在执行交易或调用 Move 函数时，CLI 会自动选择 Gas 对象。Gas 对象记录了交易消耗的资源量，用于保证交易可执行。

常用命令：

iota wallet gas list

显示当前钱包可用的 Gas 对象及其状态。

---

8. 查看交易状态

提交交易后，可以通过交易 ID 查询状态：

iota transaction get <TX_ID>

输出包括：

• 交易对象列表

• 输入对象

• 输出对象

• 执行状态（成功或失败）

• gas 消耗

• 所关联的 Checkpoint

---

9. 常见问题与排查

在使用 CLI 过程中，初学者常见问题包括：

1. 节点 RPC 不通

   • 检查本地节点是否启动

   • 确认端口和防火墙设置

   • 使用 iota client info 验证

2. Object ID 无法查询

   • 确认对象是否已经被创建

   • 检查使用的环境是否正确（本地网络或主网）

3. 交易提交失败

   • 检查 Gas 对象是否足够

   • 确认对象权限或所有权

   • 查看 Move 函数参数是否匹配

4. 本地网络报错 checkpoint

   • 本地节点未完全同步

   • 网络状态被重置，需要重新生成 genesis 或重启 Localnet

---

10. 小结

IOTA CLI 是开发者学习和操作当前 IOTA 网络的第一步。通过 CLI 可以：

• 创建和管理网络环境

• 管理地址

• 查询余额和对象状态

• 调用 Move 合约函数

• 提交交易并观察执行结果

• 查询交易状态和 checkpoint

掌握 CLI 使用，可以让抽象的对象模型和 Move 合约变得可操作，为后续本地网络实验和合约开发打下基础。

下一期，我们将讲解如何 在本地启动 IOTA Localnet，为测试合约和交易提供可控环境。