JSONチュートリアルの引数

パッケージ情報

このセクションは以下のマニフェストを含むCliArgsサンプルパッケージを参照します。

Move.toml

[package]
name = "CliArgs"
version = "0.1.0"
upgrade_policy = "compatible"

[addresses]
test_account = "_"

[dependencies]
AptosFramework = { git = "https://github.com/aptos-labs/aptos-core.git", rev = "mainnet", subdir = "aptos-move/framework/aptos-framework" }

ここで、パッケージは名前付きアドレスtest_accountの下へデプロイされます

ヒント

以下のコマンドで作業ディレクトリをaptos-move/move-examples/cli_argsへ移動します。

cd <aptos-core-parent-directory>/aptos-core/aptos-move/move-examples/cli_args

パッケージのデプロイ

パッケージをデプロイするAceのバニティアドレスをマイニングして開始します。

aptos key generate \
    --vanity-prefix 0xace \
    --output-file ace.key

出力

{
  "Result": {
    "Account Address:": "0xacef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "PublicKey Path": "ace.key.pub",
    "PrivateKey Path": "ace.key"
  }
}

ヒント

正確なアカウントアドレスは実行ごとに異なりますが、バニティプレフィックスは変更しないでください。

Aceのアドレスをシェル変数へ保存して、後でインラインで呼び出せる様にします。

# Your exact address should vary
ace_addr=0xacef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46

フォーセット（devネットまたはテストネット）を利用しAceのアカウントへ資金を入金します。

aptos account fund-with-faucet --account $ace_addr

出力

{
  "Result": "Added 100000000 Octas to account acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46"
}

Aceのアカウントでパッケージを公開します。

aptos move publish \
    --named-addresses test_account=$ace_addr \
    --private-key-file ace.key \
    --assume-yes

出力

{
  "Result": {
    "transaction_hash": "0x1d7b074dd95724c5459a1c30fe4cb3875e7b0478cc90c87c8e3f21381625bec1",
    "gas_used": 1294,
    "gas_unit_price": 100,
    "sender": "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "sequence_number": 0,
    "success": true,
    "timestamp_us": 1685077849297587,
    "version": 528422121,
    "vm_status": "Executed successfully"
  }
}

エントリー関数

パッケージ内の唯一のモジュールcli_args.moveは、様々なデータ型のフィールドを持つ単純なHolderリソースを定義します。

cli_args.moveのホルダー

module test_account::cli_args {
    use std::signer;
    use aptos_std::type_info::{Self, TypeInfo};
    use std::string::String;

    struct Holder has key, drop {
        u8_solo: u8,
        bytes: vector<u8>,
        utf8_string: String,
        bool_vec: vector<bool>,
        address_vec_vec: vector<vector<address>>,
        type_info_1: TypeInfo,
        type_info_2: TypeInfo,
    } 

複数のネストされたベクターを持つ公開エントリ関数を使用して、フィールドを設定できます。

cli_args.moveのセッター関数

/// Set values in a `Holder` under `account`.
public entry fun set_vals<T1, T2>(
    account: signer,
    u8_solo: u8,
    bytes: vector<u8>,
    utf8_string: String,
    bool_vec: vector<bool>,
    address_vec_vec: vector<vector<address>>,
) acquires Holder {
    let account_addr = signer::address_of(&account);
    if (exists<Holder>(account_addr)) {
        move_from<Holder>(account_addr);
    };
    move_to(&account, Holder {
        u8_solo,
        bytes,
        utf8_string,
        bool_vec,
        address_vec_vec,
        type_info_1: type_info::type_of<T1>(),
        type_info_2: type_info::type_of<T2>(),
    });
} 

パッケージが公開された後set_vals()を呼び出すため、aptos move runを使用出来ます。

ヒント

コマンドラインからベクター(ネストされたベクトルを含む) を引数として渡すには、引用符でエスケープされたJSON構文を使用します。

ネストされたベクトル引数を持つ関数をCLIから実行する

aptos move run \
    --function-id $ace_addr::cli_args::set_vals \
    --type-args \
        0x1::account::Account \
        0x1::chain_id::ChainId \
    --args \
        u8:123 \
        "hex:0x1234" \
        "string:hello, world\! ♥" \
        "bool:[false, true, false, false]" \
        'address:[["0xace", "0xbee"], ["0xcad"], []]' \
    --private-key-file ace.key \
    --assume-yes

出力

{
  "Result": {
    "transaction_hash": "0x5e141dc6c28e86fa9f5594de93d07a014264ebadfb99be6db922a929eb1da24f",
    "gas_used": 504,
    "gas_unit_price": 100,
    "sender": "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "sequence_number": 1,
    "success": true,
    "timestamp_us": 1685077888820037,
    "version": 528422422,
    "vm_status": "Executed successfully"
  }
}

関数ID、型引数、引数は、JSONファイルで指定しても良いです。

entry_function_arguments.json

{
  "function_id": "<test_account>::cli_args::set_vals",
  "type_args": ["0x1::account::Account", "0x1::chain_id::ChainId"],
  "args": [
    {
      "type": "u8",
      "value": 123
    },
    {
      "type": "hex",
      "value": "0x1234"
    },
    {
      "type": "string",
      "value": "hello, world! ♥"
    },
    {
      "type": "bool",
      "value": [false, true, false, false]
    },
    {
      "type": "address",
      "value": [["0xace", "0xbee"], ["0xcad"], []]
    }
  ]
}

ここでのaptos move runの呼び出しは以下の様な感じです。

Running function with JSON input file

aptos move run \
    --json-file entry_function_arguments.json \
    --private-key-file ace.key \
    --assume-yes

出力

{
  "Result": {
    "transaction_hash": "0x60a32315bb48bf6d31629332f6b1a3471dd0cb016fdee8d0bb7dcd0be9833e60",
    "gas_used": 3,
    "gas_unit_price": 100,
    "sender": "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "sequence_number": 2,
    "success": true,
    "timestamp_us": 1685077961499641,
    "version": 528422965,
    "vm_status": "Executed successfully"
  }
}

ヒント

この例を自分で実行しようとしている場合は、 entry_function_arguments.jsonの<test_account>をAceの実際のアドレスへ置き換える事を忘れないで下さい。

View関数

Holderの値が設定されると、reveal()view関数を使用して最初の3つのフィールドをチェックし、型引数を最後の2つのフィールドと比較できます。

View関数

    struct RevealResult has drop {
        u8_solo: u8,
        bytes: vector<u8>,
        utf8_string: String,
        bool_vec: vector<bool>,
        address_vec_vec: vector<vector<address>>,
        type_info_1_match: bool,
        type_info_2_match: bool
    }

    #[view]
    /// Pack into a `RevealResult` the first three fields in host's
    /// `Holder`, as well as two `bool` flags denoting if `T1` & `T2`
    /// respectively match `Holder.type_info_1` & `Holder.type_info_2`,
    /// then return the `RevealResult`.
    public fun reveal<T1, T2>(host: address): RevealResult acquires Holder {
        let holder_ref = borrow_global<Holder>(host);
        RevealResult {
            u8_solo: holder_ref.u8_solo,
            bytes: holder_ref.bytes,
            utf8_string: holder_ref.utf8_string,
            bool_vec: holder_ref.bool_vec,
            address_vec_vec: holder_ref.address_vec_vec,
            type_info_1_match:
                type_info::type_of<T1>() == holder_ref.type_info_1,
            type_info_2_match:
                type_info::type_of<T2>() == holder_ref.type_info_2
        }
    }

} 

このビュー関数は、CLIまたはJSONファイルから特定された引数を使用して呼び出すことができます。

CLI経由の引数

aptos move view \
    --function-id $ace_addr::cli_args::reveal \
    --type-args \
        0x1::account::Account \
        0x1::account::Account \
    --args address:$ace_addr

JSONファイル経由の引数

aptos move view --json-file view_function_arguments.json

ヒント

この例を自分で実行しようとしている場合は、view_function_arguments.jsonの<test_account>をAceの実際のアドレスに置き換える事を忘れないで下さい(2回)。

view_function_arguments.json

{
  "function_id": "<test_account>::cli_args::reveal",
  "type_args": ["0x1::account::Account", "0x1::account::Account"],
  "args": [
    {
      "type": "address",
      "value": "<test_account>"
    }
  ]
}

出力

{
  "Result": [
    {
      "address_vec_vec": [
        [
          "0xace",
          "0xbee"
        ],
        [
          "0xcad"
        ],
        []
      ],
      "bool_vec": [
        false,
        true,
        false,
        false
      ],
      "bytes": "0x1234",
      "type_info_1_match": true,
      "type_info_2_match": false,
      "u8_solo": 123,
      "utf8_string": "hello, world! ♥"
    }
  ]
}

スクリプト関数

パッケージにはsetter関数のラッパーであるスクリプト、set_vals.moveも含まれています。

スクリプト

script {
    use test_account::cli_args;
    use std::vector;
    use std::string::String;

    /// Get a `bool` vector where each element indicates `true` if the
    /// corresponding element in `u8_vec` is greater than `u8_solo`.
    /// Then pack `address_solo` in a `vector<vector<<address>>` and
    /// pass resulting argument set to public entry function.
    fun set_vals<T1, T2>(
        account: signer,
        u8_solo: u8,
        bytes: vector<u8>,
        utf8_string: String,
        u8_vec: vector<u8>,
        address_solo: address,
    ) {
        let bool_vec = vector::map_ref(&u8_vec, |e_ref| *e_ref > u8_solo);
        let addr_vec_vec = vector[vector[address_solo]];
        cli_args::set_vals<T1, T2>(account, u8_solo, bytes, utf8_string, bool_vec, addr_vec_vec);
    }
} 

まずパッケージをコンパイルします(これによりスクリプトがコンパイルされます)。

コンパイル

aptos move compile --named-addresses test_account=$ace_addr

出力

{
  "Result": [
    "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46::cli_args"
  ]
}

次はaptos move run-scriptを実行します。

CLI経由の引数

aptos move run-script \
    --compiled-script-path build/CliArgs/bytecode_scripts/set_vals.mv \
    --type-args \
        0x1::account::Account \
        0x1::chain_id::ChainId \
    --args \
        u8:123 \
        "hex:0x1234" \
        "string:hello, world\! ♥" \
        "u8:[122, 123, 124, 125]" \
        address:"0xace" \
    --private-key-file ace.key \
    --assume-yes

出力

{
  "Result": {
    "transaction_hash": "0x1d644eba8187843cc43919469112339bc2c435a49a733ac813b7bc6c79770152",
    "gas_used": 3,
    "gas_unit_price": 100,
    "sender": "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "sequence_number": 3,
    "success": true,
    "timestamp_us": 1685078415935612,
    "version": 528426413,
    "vm_status": "Executed successfully"
  }
}

JSONファイル経由の引数

aptos move run-script \
    --compiled-script-path build/CliArgs/bytecode_scripts/set_vals.mv \
    --json-file script_function_arguments.json \
    --private-key-file ace.key \
    --assume-yes

出力

{
  "Result": {
    "transaction_hash": "0x840e2d6a5ab80d5a570effb3665f775f1755e0fd8d76e52bfa7241aaade883d7",
    "gas_used": 3,
    "gas_unit_price": 100,
    "sender": "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "sequence_number": 4,
    "success": true,
    "timestamp_us": 1685078516832128,
    "version": 528427132,
    "vm_status": "Executed successfully"
  }
}

script_function_arguments.json

{
  "type_args": ["0x1::account::Account", "0x1::chain_id::ChainId"],
  "args": [
    {
      "type": "u8",
      "value": 123
    },
    {
      "type": "hex",
      "value": "0x1234"
    },
    {
      "type": "string",
      "value": "hello, world! ♥"
    },
    {
      "type": "u8",
      "value": [122, 123, 124, 125]
    },
    {
      "type": "address",
      "value": "0xace"
    }
  ]
}

このようなスクリプト関数の呼び出しは両方とも、以下のreveal()ビュー関数を出力します。

View関数呼び出し

aptos move view \
    --function-id $ace_addr::cli_args::reveal \
    --type-args \
        0x1::account::Account \
        0x1::chain_id::ChainId \
    --args address:$ace_addr

View関数の出力

{
  "Result": [
    {
      "address_vec_vec": [["0xace"]],
      "bool_vec": [false, false, true, true],
      "bytes": "0x1234",
      "type_info_1_match": true,
      "type_info_2_match": true,
      "u8_solo": 123,
      "utf8_string": "hello, world! ♥"
    }
  ]
}

注記

この記事の執筆時点では、aptosCLIはu8型のベクターのスクリプト関数引数のみをサポートしており、ベクターの深さは1までです。従ってvector<address>とvector<vector<u8>>は無効なスクリプト関数引数型です。