[CLI][Move] support public structs/enums as txn args in CLI by rahxephon89 · Pull Request #18591 · aptos-labs/aptos-core

rahxephon89 · 2026-02-04T04:49:08Z

Description

This PR:

adds support of public structs/enums as txn args for Aptos CLI;
adds support of running local net for cli e2e tests without using a docker.

How Has This Been Tested?

Newly added cli e2e tests.

Key Areas to Review

Type of Change

Which Components or Systems Does This Change Impact?

Checklist

I have read and followed the CONTRIBUTING doc
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I identified and added all stakeholders and component owners affected by this change as reviewers
I tested both happy and unhappy path of the functionality
I have made corresponding changes to the documentation

Note

Medium Risk
Touches CLI transaction argument parsing and encoding, adding async REST-dependent logic that could break move run/view/simulate for JSON inputs if type detection or BCS encoding is incorrect. Local-testnet orchestration changes also affect e2e execution flow and process lifecycle management.

Overview
Adds public struct/enum transaction argument support to the Aptos CLI when using --json-file, including enum variant/object syntax and Option<T> in both legacy vector ([] / [v]) and new variant ({"None":{}} / {"Some":{"0":v}}) formats. This introduces an async parsing path that fetches on-chain module bytecode/ABI to validate types and BCS-encode nested structs/enums, implemented via a new StructArgParser with module caching and depth limits.

Updates aptos move run, move simulate, and move view to use the async parser only when JSON input is present, and hard-errors if struct/enum types are encountered in the previous synchronous conversion path. Adds a new Move test package and Python e2e cases to exercise struct/enum/Option argument handling, and extends the e2e harness with --use-local-testnet (auto-start or manual) to run tests without Docker. Also introduces shared MODULE_SEPARATOR/std-type constants in move-core-types and adds async-recursion to the CLI crate.

^{Written by Cursor Bugbot for commit 0904383. This will update automatically on new commits. Configure here.}

rahxephon89 · 2026-02-04T04:49:29Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

[CLI][Move] support public structs/enums as txn args in CLI #18591 👈 (View in Graphite)
[compiler][vm] add visibility modifier to structs/enums: step 5 #18489
[compiler][vm] add visibility modifier to structs/enums: step 4 #18165 : 1 other dependent PR (#18381 )
[compiler][vm] add visibility modifier to structs/enums: step 3 #18117
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

crates/aptos/src/move_tool/struct_arg_parser.rs

crates/aptos/src/move_tool/mod.rs

crates/aptos/src/move_tool/struct_arg_parser.rs

crates/aptos/src/move_tool/mod.rs

crates/aptos/e2e/main.py

crates/aptos/src/move_tool/struct_arg_parser.rs

crates/aptos/e2e/cases/move.py

crates/aptos/src/move_tool/mod.rs

crates/aptos/src/common/types.rs

aptos-move/move-examples/cli-e2e-tests/common/sources/cli_e2e_tests.move

crates/aptos/e2e/main.py

junxzm1990 · 2026-02-06T17:30:03Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+    fn check_depth(depth: u8, type_name: &str) -> CliTypedResult<()> {
+        if depth > MAX_NESTING_DEPTH {
+            return Err(CliError::CommandArgumentError(format!(
+                "{} nesting depth {} exceeds maximum allowed depth of {}",


Suggested change

"{} nesting depth {} exceeds maximum allowed depth of {}",

"`{}` nesting depth {} exceeds maximum allowed depth of {}",

junxzm1990 · 2026-02-06T17:39:23Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+    }
+
+    /// Construct a struct argument by parsing fields and encoding to BCS.
+    pub async fn construct_struct_argument(


I am curious about the necessity of getting struct def from rest API for verifying the args. It seems to bring in extra complexities.

if we cannot get the abi, we have to deserialize the module to get enough information

junxzm1990 · 2026-02-06T17:42:09Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+    ) -> CliTypedResult<Vec<u8>> {
+        // Check nesting depth limit
+        Self::check_depth(depth, "Struct")?;
+        let module = self.verify_struct_exists(struct_tag).await?;


There is repeated work by verify_struct_exists and the code below (e.g., potential deserialization of the bytecode module). Maybe creating a separate data struct for onchain modules, where we can cache and reuse the analysis results along the way.

junxzm1990 · 2026-02-06T17:44:53Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+}
+
+/// Convert MoveType to TypeTag.
+fn convert_move_type_to_type_tag(move_type: &MoveType) -> CliTypedResult<TypeTag> {


It's worth checking if we already have APIs to do this and other convertions defined in this file.

code refactored

junxzm1990 · 2026-02-06T18:32:23Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+    }
+
+    /// Parse a value based on its Move type and encode to BCS.
+    fn parse_value_by_type<'a>(


Can we simply make it a async fn so that we can simplify the return type?

Also, some abstraction would help this function to be more readable and maintainable.

junxzm1990 · 2026-02-06T18:34:59Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+                )));
+            }
+
+            match move_type {


Do we have existing APIs doing this thing?

code refactored

junxzm1990 · 2026-02-06T18:35:47Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+                    })?;
+                    bcs::to_bytes(&v).map_err(|e| CliError::BCS("bool", e))
+                },
+                MoveType::U8 => {


The parsing here and below has an inconsistent error handling with MoveType::Bool.

do you mean the error type is different?

junxzm1990 · 2026-02-06T18:39:49Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+                        // 1. Array format (legacy): [] or [value]
+                        // 2. Enum format (new): {"None": {}} or {"Some": {"0": value}}
+
+                        if value.is_array() {


I remember to have seen similar code in several other places? Maybe making a function for it?

code refactored

junxzm1990 · 2026-02-06T18:40:43Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+                        }
+                    }
+
+                    match qualified_name.as_str() {


Can we have a more systematic and generic way to handle these special cases? I suppose they will grow as time goes by.

this corresponds to allowed structs so I will keep it as it is and add TODO once we have a more general way to handle them

junxzm1990 · 2026-02-06T18:42:44Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+    let s = if value.is_string() {
+        value.as_str().unwrap()
+    } else if value.is_number() {
+        &value.to_string()


We use value.as_str().unwrap() above and &value.to_string() here. Is it intended?

code refactored

junxzm1990 · 2026-02-06T18:47:58Z

@rahxephon89 I did a first look at the PR. The code makes sense but can benefit from some clean-up and refactoring. I will take another look afterward.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

crates/aptos/src/common/types.rs

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

crates/aptos/src/move_tool/struct_arg_parser.rs

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

crates/aptos/src/move_tool/struct_arg_parser.rs

crates/aptos/e2e/main.py

cursor

Cursor Bugbot has reviewed your changes and found 4 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

crates/aptos/e2e/cases/struct_enum_args.py

crates/aptos/e2e/cases/move.py

cursor

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

crates/aptos/e2e/cases/struct_enum_args.py

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

crates/aptos/src/move_tool/struct_arg_parser.rs

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

crates/aptos/src/move_tool/struct_arg_parser.rs

rahxephon89 mentioned this pull request Feb 4, 2026

[compiler][vm] add visibility modifier to structs/enums: step 5 #18489

Open

22 tasks

rahxephon89 changed the title ~~cli support~~ [experiment] support public structs/enums as txn args in CLI Feb 4, 2026

rahxephon89 force-pushed the teng/txn-args-CLI branch from 88acdd2 to dfd47a0 Compare February 4, 2026 17:28

rahxephon89 force-pushed the teng/public-struct-txn-args branch 2 times, most recently from fc1c26d to d31e4d0 Compare February 5, 2026 01:06

rahxephon89 force-pushed the teng/txn-args-CLI branch 2 times, most recently from 155b20c to 398a435 Compare February 5, 2026 04:25

rahxephon89 force-pushed the teng/public-struct-txn-args branch 2 times, most recently from f37ad1b to b30d55a Compare February 5, 2026 05:31

rahxephon89 force-pushed the teng/txn-args-CLI branch 2 times, most recently from 170c1ef to e22d876 Compare February 5, 2026 07:00

rahxephon89 force-pushed the teng/public-struct-txn-args branch 2 times, most recently from 8f27993 to dd7a3d2 Compare February 5, 2026 18:45

rahxephon89 force-pushed the teng/txn-args-CLI branch 2 times, most recently from bfc10dc to ff0ca1f Compare February 5, 2026 19:01

rahxephon89 changed the title ~~[experiment] support public structs/enums as txn args in CLI~~ [CLI][Move] support public structs/enums as txn args in CLI Feb 5, 2026

rahxephon89 marked this pull request as ready for review February 5, 2026 19:07

rahxephon89 requested review from banool and gregnazario as code owners February 5, 2026 19:07

cursor bot reviewed Feb 5, 2026

View reviewed changes

rahxephon89 force-pushed the teng/public-struct-txn-args branch from dd7a3d2 to 966306b Compare February 5, 2026 22:35

rahxephon89 force-pushed the teng/txn-args-CLI branch from ff0ca1f to 12c09c2 Compare February 5, 2026 22:35

cursor bot reviewed Feb 5, 2026

View reviewed changes

crates/aptos/src/common/types.rs Outdated Show resolved Hide resolved

rahxephon89 force-pushed the teng/txn-args-CLI branch from 12c09c2 to f69d861 Compare February 6, 2026 03:09

rahxephon89 force-pushed the teng/public-struct-txn-args branch from 966306b to a6c536f Compare February 6, 2026 03:09

cursor bot reviewed Feb 6, 2026

View reviewed changes

aptos-move/move-examples/cli-e2e-tests/common/sources/cli_e2e_tests.move Outdated Show resolved Hide resolved

cursor bot reviewed Feb 6, 2026

View reviewed changes

crates/aptos/e2e/main.py Outdated Show resolved Hide resolved

rahxephon89 force-pushed the teng/txn-args-CLI branch from f69d861 to faf499b Compare February 6, 2026 08:48

junxzm1990 reviewed Feb 6, 2026

View reviewed changes

cli support

df9d6ee

rahxephon89 force-pushed the teng/txn-args-CLI branch from 5e897f2 to dac7a55 Compare February 7, 2026 03:25

rahxephon89 force-pushed the teng/public-struct-txn-args branch from a6c536f to 810bb48 Compare February 7, 2026 03:25

cursor bot reviewed Feb 7, 2026

View reviewed changes

crates/aptos/src/common/types.rs Outdated Show resolved Hide resolved

rahxephon89 force-pushed the teng/txn-args-CLI branch from dac7a55 to b89306f Compare February 7, 2026 07:09

cursor bot reviewed Feb 7, 2026

View reviewed changes

crates/aptos/src/move_tool/struct_arg_parser.rs Outdated Show resolved Hide resolved

crates/aptos/src/move_tool/struct_arg_parser.rs Show resolved Hide resolved

rahxephon89 force-pushed the teng/txn-args-CLI branch from b89306f to de9d553 Compare February 7, 2026 08:00

cursor bot reviewed Feb 7, 2026

View reviewed changes

crates/aptos/src/move_tool/struct_arg_parser.rs Show resolved Hide resolved

crates/aptos/e2e/main.py Show resolved Hide resolved

rahxephon89 force-pushed the teng/txn-args-CLI branch from de9d553 to a91387e Compare February 7, 2026 08:54

cursor bot reviewed Feb 7, 2026

View reviewed changes

crates/aptos/e2e/cases/struct_enum_args.py Show resolved Hide resolved

crates/aptos/e2e/cases/struct_enum_args.py Show resolved Hide resolved

crates/aptos/e2e/cases/struct_enum_args.py Show resolved Hide resolved

crates/aptos/e2e/cases/move.py Outdated Show resolved Hide resolved

rahxephon89 force-pushed the teng/txn-args-CLI branch from a91387e to ccaeb25 Compare February 7, 2026 09:23

cursor bot reviewed Feb 7, 2026

View reviewed changes

crates/aptos/e2e/cases/struct_enum_args.py Show resolved Hide resolved

crates/aptos/e2e/cases/struct_enum_args.py Show resolved Hide resolved

crates/aptos/e2e/cases/struct_enum_args.py Show resolved Hide resolved

rahxephon89 force-pushed the teng/txn-args-CLI branch from ccaeb25 to 3a1dc50 Compare February 7, 2026 09:49

cursor bot reviewed Feb 7, 2026

View reviewed changes

crates/aptos/src/move_tool/struct_arg_parser.rs Show resolved Hide resolved

rahxephon89 force-pushed the teng/txn-args-CLI branch from 3a1dc50 to 498bca7 Compare February 7, 2026 19:55

cursor bot reviewed Feb 7, 2026

View reviewed changes

crates/aptos/src/move_tool/struct_arg_parser.rs Show resolved Hide resolved

cli support

0904383

rahxephon89 force-pushed the teng/txn-args-CLI branch from 498bca7 to 0904383 Compare February 7, 2026 21:09

rahxephon89 requested a review from junxzm1990 February 8, 2026 09:32

	"{} nesting depth {} exceeds maximum allowed depth of {}",
	"`{}` nesting depth {} exceeds maximum allowed depth of {}",

Conversation

rahxephon89 commented Feb 4, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How Has This Been Tested?

Key Areas to Review

Type of Change

Which Components or Systems Does This Change Impact?

Checklist

Uh oh!

rahxephon89 commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

junxzm1990 commented Feb 6, 2026

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

rahxephon89 commented Feb 4, 2026 •

edited by cursor bot

Loading

rahxephon89 commented Feb 4, 2026 •

edited

Loading