使用 Move 合约

Aptos CLI 主要用于编译,测试和形式化验证 Move 合约.如果你还没有安装 Aptos CLI,可以按照安装 Aptos CLI 的步骤进行安装.

你可以使用右侧的目录跳转到特定部分.

要了解如何使用 CLI 在链上链接 Move 合约,你可以按照这个”CLI 参数”教程进行操作.

注意

在本文档中,有些命令部分需要你根据自己的情况进行修改.这些变量将用尖括号括起来 <像这样>.

1. 编译 Move

你可以通过运行以下命令编译 Move 包:

aptos move compile --package-dir <your-package-directory>

注意

包目录是包含 Move.toml 文件的文件夹.

根据你的 Move.toml 文件中的设置,你可能需要向编译命令传递额外的信息.

例如,如果你查看 hello_blockchain 示例 Move 合约,在 Move.toml 文件中指定了一个名为 hello_blockchain 的地址变量.

[addresses]
hello_blockchain = "_"

因此,要编译它,你需要使用 --named-addresses 参数传入 hello_blockchain 的值. 你可以使用完整的地址,例如 0x123456...7890 或 CLI 中配置文件的名称,例如 default 或 superuser.

在我们的示例中,我们将使用 default:

aptos move compile --package-dir aptos-move/move-examples/hello_blockchain/ --named-addresses hello_blockchain=default

你可以通过运行 aptos move compile --help 了解编译 Move 合约时的可选参数.

2. 对 Move 合约进行单元测试

Aptos CLI 也可以通过运行以下命令，在本地编译并运行单元测试：

aptos move test --package-dir <your-package-directory>

此命令会同时编译并运行测试，因此需要使用与编译时相同的全部可选参数。

要了解测试 Move 合约的可选参数，请运行 aptos move test --help。

输出调试信息

编写测试时，输出调试信息或堆栈跟踪会很有帮助。使用 aptos move test 时，可通过 debug::print 和 debug::print_stack_trace 输出信息。有关使用示例，请参阅 DebugDemo.move。

要查看 DebugDemo.move 包的测试输出：

1. 克隆 aptos-core。
2. 运行 cd crates/aptos/debug-move-example，进入 debug-move-example。
3. 运行 aptos move test。

您应看到：

Running Move unit tests
[debug] 0000000000000000000000000000000000000000000000000000000000000001
Call Stack:
    [0] 0000000000000000000000000000000000000000000000000000000000000001::Message::sender_can_set_message

        Code:
            [4] CallGeneric(0)
            [5] MoveLoc(0)
            [6] LdConst(0)
          > [7] Call(1)
            [8] Ret

        Locals:
            [0] -
            [1] 0000000000000000000000000000000000000000000000000000000000000001

Operand Stack:

有关如何使用 Move 编写单元测试，请参考此 Move 教程（第 2 步重点介绍单元测试）。

3. 生成测试覆盖率报告

Aptos CLI 可用于分析并改进 Move 模块的测试。要使用此功能，请执行以下操作：

在 Move 包目录中运行以下命令，即可查看测试的代码覆盖率：

aptos move test --coverage

若要将覆盖率聚焦于特定包，可以使用 --filter 选项。若要进一步限定为特定 Move 模块，请使用 --module 参数。

若需更详细或更高级的覆盖率信息（例如编译后字节码中的测试覆盖率），可以运行 aptos move coverage。使用该命令时，CLI 会提示您提供更多细节，选择想了解哪些覆盖率信息。

要了解测试覆盖率的可选参数，请运行 aptos move test --help 和 aptos move coverage --help。

4. 发布 Move 合约

要发布 Move 合约，请运行：

aptos move publish --package-dir <your-package-directory>

请注意，在主网上发布时，通过 --named-addresses 等可选参数传入的凭证必须对应主网上的账户，而不能使用测试凭证。

该包将发布到 CLI 的默认配置文件。您可以在命令中使用 --profile 覆盖该设置，指定发布所用的账户。要为特定账户生成新的配置文件，请使用 aptos init --profile <name_of_profile> 并按提示操作。

还请注意：发布 Move 模块时，如果一个包中包含多个模块，则该包内的所有模块必须使用同一个账户。若使用不同账户，发布会在交易层失败。

注意

默认情况下，CLI 会将交易发送到远程全节点进行模拟。

若要在本地模拟，请在命令中添加 --local 选项。您也可以使用 --profile-gas 选项分析 Gas 用量。

详情请参阅本地模拟、基准测试和 Gas 分析。

警告

Move 合约默认会发布其源代码。若要避免发布源代码，请使用 --included-artifacts none 参数进行发布。

Aptos 区块链本身按开放原则设计。请注意，即使无法访问源代码，仍可根据已发布的 Move 字节码重新生成 Move 源代码。

5. 运行已发布的合约

现在您已发布 Move 包，可以直接通过 CLI 运行它。

首先需要通过以下格式构造 function-id：

<the-address-you-published-to>::<module_name>::<function_name>

然后可使用 --args 参数传入参数。

例如，假设您已将 hello_blockchain 示例包 发布到地址为 b9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb 的账户，则可通过以下命令运行其 set_message 函数：

aptos move run --function-id 0xb9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb::message::set_message --args string:hello!

结果应为：

{
  "Result": {
    "changes": [
      {
        "address": "b9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb",
        "data": {
          "authentication_key": "0xb9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb",
          "self_address": "0xb9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb",
          "sequence_number": "3"
        },
        "event": "write_resource",
        "resource": "0x1::account::Account"
      },
      {
        "address": "b9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb",
        "data": {
          "coin": {
            "value": "9777"
          },
          "deposit_events": {
            "counter": "1",
            "guid": {
              "id": {
                "addr": "0xb9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb",
                "creation_num": "1"
              }
            }
          },
          "withdraw_events": {
            "counter": "1",
            "guid": {
              "id": {
                "addr": "0xb9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb",
                "creation_num": "2"
              }
            }
          }
        },
        "event": "write_resource",
        "resource": "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>"
      },
      {
        "address": "b9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb",
        "data": {
          "counter": "4"
        },
        "event": "write_resource",
        "resource": "0x1::guid::Generator"
      },
      {
        "address": "b9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb",
        "data": {
          "message": "hello!",
          "message_change_events": {
            "counter": "0",
            "guid": {
              "id": {
                "addr": "0xb9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb",
                "creation_num": "3"
              }
            }
          }
        },
        "event": "write_resource",
        "resource": "0xb9bd2cfa58ca29bce1d7add25fce5c62220604cd0236fe3f90d9de91ed9fb8cb::Message::MessageHolder"
      }
    ],
    "gas_used": 41,
    "success": true,
    "version": 3488,
    "vm_status": "Executed successfully"
  }
}

6. (可选)形式化验证 Move 脚本

对于需要保证代码按预期工作的情况(超出单元测试的范围),你可以使用 Move Prover 来形式化验证你的 Move 合约代码.

你可以按照这些步骤安装 Move Prover.

安装 Move Prover 后,你可以通过运行以下命令从 Aptos CLI 使用它:

aptos move prove --package-dir <your-package-directory>

要了解如何形式化验证你的代码,请按照这里的深入 Move 教程进行操作(步骤 7 和 8 介绍了如何在示例代码中使用 Move Prover 和编写形式规范).