[CLI][Move] support public structs/enums as txn args in CLI #18591

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
Medium risk because it changes move run/simulate/view argument parsing to conditionally perform REST lookups and BCS encoding for complex types, which could affect transaction construction and error handling.

Overview
Adds struct/enum txn-arg support in the CLI (JSON input). move run, move simulate, and move view now support JSON args that reference fully-qualified Move types and pass public structs/enums (including nested types and Option<T> in both legacy vector and new variant formats) by fetching on-chain module bytecode/ABI and encoding arguments to BCS via a new async StructArgParser.

Expands CLI e2e coverage and runner flexibility. Introduces a new Move test package and Python e2e cases for struct/enum args, pins Move CLI e2e compilation/publish to language version 2.4, and adds a --use-local-testnet mode to the e2e harness to run against a locally started testnet without Docker.

^{Written by Cursor Bugbot for commit 879aeae. 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

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.}

cursor · 2026-02-09T01:37:16Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+            } else {
+                // Module not in cache, need to fetch
+            }
+        } // Release read lock


Cache miss causes redundant network refetch for nonexistent types

Low Severity

In verify_struct_exists, when a module IS already cached and the struct/enum is confirmed NOT to exist (via ABI or compiled module check), the code falls through past line 118 and re-fetches the entire module from the network at line 126. The struct_exists = false result from a definitive ABI/compiled check is treated the same as the "couldn't check yet" case, causing a redundant REST API call that will reach the same conclusion.

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.}

cursor · 2026-02-09T10:05:06Z

crates/aptos/e2e/cases/struct_enum_args.py

+        if '"success": true' not in response.stdout:
+            raise TestError(f"{error_msg}: Transaction did not execute successfully on-chain")
+    except Exception as e:
+        raise TestError(error_msg) from e


Exception handler catches its own raised TestError

Low Severity

In run_move_function_with_json, the except Exception block at line 68 catches all exceptions, including the TestError raised at line 67 by the on-chain success check. This replaces the specific message "{error_msg}: Transaction did not execute successfully on-chain" with just the generic error_msg, making it harder to distinguish a transaction execution failure from a CLI invocation failure during debugging. The success check belongs outside the try block, or the except needs to re-raise TestError without wrapping.

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.}

cursor · 2026-02-09T10:06:19Z

crates/aptos/src/common/types.rs

+            _vector_depth: 0,
+            arg: bcs_bytes,
+        })
+    }


Duplicated Option array-to-variant conversion logic across files

Low Severity

The Option<T> array-to-variant conversion logic (empty array → "None", single-element array → "Some" with field "0") is duplicated between EntryFunctionArgumentsJSON::parse_option_vector_format in types.rs and StructArgParser::parse_option_value in struct_arg_parser.rs. The comment on parse_option_value even acknowledges this: "This helper extracts repeated logic for Option handling." The core mapping logic and error messages are nearly identical across both locations, differing only in return type wrapping (ArgWithType vs Vec<u8>).

Additional Locations (1)

crates/aptos/src/move_tool/struct_arg_parser.rs#L259-L316

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.}

cursor · 2026-02-09T10:33:50Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+            } else {
+                // Module not in cache, need to fetch
+            }
+        } // Release read lock


Cache miss causes redundant REST fetch for existing modules

Low Severity

In verify_struct_exists, when a module IS cached and the struct is conclusively NOT found (via ABI or compiled module check), struct_exists is false and the code falls through to re-fetch the module from chain. The comment says "fall through to deserialize" but this path also triggers when the ABI/bytecode definitively confirms the type doesn't exist. This results in a wasted REST API call and also overwrites the cache entry (potentially losing a previously deserialized compiled module if the fresh fetch only has ABI).

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.}

cursor · 2026-02-10T00:59:43Z

crates/aptos/e2e/main.py

+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                universal_newlines=True,
+            )


Subprocess pipes never drained causing potential deadlock

Medium Severity

The localnet subprocess is created with stdout=subprocess.PIPE and stderr=subprocess.PIPE, but neither pipe is ever read during normal test execution. Per Python docs, this can deadlock: when the OS pipe buffer fills up (~64KB on Linux), the child process blocks on writes. Since a running Aptos node can easily produce more than 64KB of log output during a full test run, the localnet could freeze, causing test failures or hangs. Using subprocess.DEVNULL or redirecting to log files would avoid this.

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.}

cursor · 2026-02-10T01:01:23Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+            } else {
+                // Module not in cache, need to fetch
+            }
+        } // Release read lock


Cache logic conflates "not found" with "couldn't check"

Medium Severity

In verify_struct_exists, when the module is cached and the struct is definitively not found via ABI or compiled module check, struct_exists is set to false — the same value used when verification isn't possible (no ABI, no compiled form). The code then falls through to re-fetch the module from chain, making an unnecessary API call before eventually returning the same "not found" error. The three distinct false cases — ABI says absent, compiled module says absent, and can't check — are conflated, causing redundant network round-trips for the error path.

cursor · 2026-02-10T01:01:23Z

crates/aptos/src/common/types.rs

+        } else {
+            // Use synchronous parsing for command-line arguments
+            self.try_into()
+        }


REST client eagerly created for all JSON files

Low Severity

parse_with_optional_client creates a REST client whenever json_file.is_some(), but the client is only actually used when the JSON contains struct/enum args (detected later in check_input_style_async via has_struct_or_enum_args()). This means JSON files with only primitive args now require a configured REST URL, which is a behavioral regression for commands like Simulate --local where the REST endpoint may not be needed. The doc comment's claim that "The get_client closure is only called if async parsing is needed" is misleading — it's called for all JSON files.

cursor · 2026-02-10T01:01:23Z

crates/aptos/e2e/cases/struct_enum_args.py

+@test_case
+def test_option_variant_format(run_helper: RunHelper, test_name=None):
+    """Test Option<T> with new variant format: {"None": {}} and {"Some": {"0": value}}."""
+    account_address = str(run_helper.get_account_info().account_address)


Unused account_address variables in test functions

Low Severity

In test_option_variant_format and test_option_legacy_format, the account_address variable is assigned from run_helper.get_account_info().account_address but never referenced — the JSON content uses hardcoded "0x1::option::Option<u64>" strings instead. This is dead code left over from copy-pasting other test functions that do use the variable (like test_enum_simple_variant).

Additional Locations (1)

crates/aptos/e2e/cases/struct_enum_args.py#L176-L177

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.}

cursor · 2026-02-10T07:58:07Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+            } else {
+                // Module not in cache, need to fetch
+            }
+        } // Release read lock


Redundant re-fetch when cached module lacks struct

Low Severity

In verify_struct_exists, when the module is already cached and the ABI confirms a struct does not exist, the code falls through to re-fetch the entire module from the network (line 126). This redundant REST call will produce the same result. The fall-through logic doesn't distinguish "module cached but type missing" from "module not cached" or "need to deserialize," so it always re-fetches and re-caches. The three cases (not in cache, needs deserialization, and genuinely missing type) deserve separate handling.

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.}

cursor · 2026-02-11T00:10:56Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+            } else {
+                // Module not in cache, need to fetch
+            }
+        } // Release read lock


Cache hit with absent struct still re-fetches module

Low Severity

In verify_struct_exists, when the module is cached and the struct is verified absent via ABI or compiled module, struct_exists is false and the code falls through to re-fetch the module from chain instead of returning an error immediately. The comment on line 119 says "If we couldn't verify," but the same fallthrough path executes when verification succeeded and confirmed the struct doesn't exist.

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.}

cursor · 2026-02-11T09:24:57Z

crates/aptos/src/common/types.rs

+                 This should not happen if the CLI is properly configured."
+                    .to_string(),
+            ));
+        }


Struct args still fail in some commands

Medium Severity

EntryFunctionArgumentsJSON::try_into() now rejects any argument type containing ::. Commands that still call synchronous EntryFunctionArguments::try_into() never reach the new async parser, so --json-file with struct/enum args fails outside updated paths.

cursor · 2026-02-11T09:24:57Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+                .parse_value_by_type(&field_type, field_value, depth)
+                .await?;
+            encoded_fields.extend(encoded_value);
+        }


Unexpected struct fields are silently ignored

Medium Severity

The new parser validates required fields but never rejects extra keys in input objects. In both construct_struct_argument and construct_enum_argument, unknown fields are ignored, so malformed JSON can be accepted and encoded as a different value than the user supplied.

Additional Locations (1)

crates/aptos/src/move_tool/struct_arg_parser.rs#L549-L572

cursor · 2026-02-11T09:24:57Z

crates/aptos/e2e/main.py

+                [cli_path, "node", "run-local-testnet", "--with-faucet", "--force-restart", "--assume-yes"],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                universal_newlines=True,


Background localnet can block on log pipes

Medium Severity

subprocess.Popen(...) starts run-local-testnet with both stdout and stderr set to PIPE, but those streams are never drained during normal execution. A chatty localnet can fill OS pipe buffers and block, causing startup or later tests to hang unpredictably.

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.}

cursor · 2026-02-11T09:25:10Z

crates/aptos/e2e/main.py

+                [cli_path, "node", "run-local-testnet", "--with-faucet", "--force-restart", "--assume-yes"],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                universal_newlines=True,


Localnet process can block on full pipes

Medium Severity

subprocess.Popen starts run-local-testnet with stdout and stderr set to PIPE, but the code never drains those streams while the process runs. Since localnet is long-lived and chatty, pipe buffers can fill and block the child process, causing startup hangs or flaky timeouts in --use-local-testnet mode.

cursor · 2026-02-11T09:25:10Z

crates/aptos/src/move_tool/struct_arg_parser.rs

+                    )));
+                }
+                vec![field_values.values().next().unwrap().clone()]
+            };


Option Some field name is never validated

Low Severity

For Option::Some in variant-object format, parsing ignores field keys and takes field_values.values().next(). Inputs like {"Some":{"wrong_key":"42"}} are accepted as valid Some(42). This silently accepts malformed JSON instead of validating the expected "0" field for the variant payload.

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

rahxephon89 force-pushed the teng/public-struct-txn-args branch from 810bb48 to fb023bd Compare February 9, 2026 01:24

rahxephon89 force-pushed the teng/txn-args-CLI branch from 0904383 to 1158753 Compare February 9, 2026 01:24

cursor bot reviewed Feb 9, 2026

View reviewed changes

rahxephon89 force-pushed the teng/public-struct-txn-args branch from fb023bd to f37f6c7 Compare February 9, 2026 08:54

rahxephon89 force-pushed the teng/txn-args-CLI branch from 1158753 to 081bb83 Compare February 9, 2026 08:54

rahxephon89 force-pushed the teng/public-struct-txn-args branch from f37f6c7 to a354293 Compare February 9, 2026 09:47

rahxephon89 force-pushed the teng/txn-args-CLI branch from 081bb83 to 4c7df6b Compare February 9, 2026 09:47

rahxephon89 force-pushed the teng/public-struct-txn-args branch from a354293 to 8fd8607 Compare February 9, 2026 09:51

rahxephon89 force-pushed the teng/txn-args-CLI branch from 4c7df6b to 2918dfa Compare February 9, 2026 09:51

cursor bot reviewed Feb 9, 2026

View reviewed changes

rahxephon89 force-pushed the teng/txn-args-CLI branch from 2918dfa to d5cbfd1 Compare February 9, 2026 10:20

rahxephon89 force-pushed the teng/public-struct-txn-args branch from 8fd8607 to 05382f0 Compare February 9, 2026 10:20

cursor bot reviewed Feb 9, 2026

View reviewed changes

rahxephon89 force-pushed the teng/public-struct-txn-args branch from 05382f0 to 12b69f7 Compare February 10, 2026 00:45

rahxephon89 force-pushed the teng/txn-args-CLI branch from d5cbfd1 to 21f01a8 Compare February 10, 2026 00:45

cursor bot reviewed Feb 10, 2026

View reviewed changes

rahxephon89 force-pushed the teng/public-struct-txn-args branch from 12b69f7 to 82b0fc2 Compare February 10, 2026 07:45

rahxephon89 force-pushed the teng/txn-args-CLI branch from 21f01a8 to eeed102 Compare February 10, 2026 07:45

cursor bot reviewed Feb 10, 2026

View reviewed changes

rahxephon89 force-pushed the teng/txn-args-CLI branch from eeed102 to d8acf6c Compare February 10, 2026 23:52

rahxephon89 force-pushed the teng/public-struct-txn-args branch from 82b0fc2 to 428e114 Compare February 10, 2026 23:52

cursor bot reviewed Feb 11, 2026

View reviewed changes

rahxephon89 added 2 commits February 11, 2026 01:17

cli support

04b1b43

cli support

879aeae

rahxephon89 force-pushed the teng/txn-args-CLI branch from d8acf6c to 879aeae Compare February 11, 2026 09:18

rahxephon89 force-pushed the teng/public-struct-txn-args branch from 428e114 to 4f22f38 Compare February 11, 2026 09:18

cursor bot reviewed Feb 11, 2026

View reviewed changes

[CLI][Move] support public structs/enums as txn args in CLI #18591

Are you sure you want to change the base?

[CLI][Move] support public structs/enums as txn args in CLI #18591

Uh oh!

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!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 9, 2026

Choose a reason for hiding this comment

Cache miss causes redundant network refetch for nonexistent types

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 9, 2026

Choose a reason for hiding this comment

Exception handler catches its own raised TestError

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 9, 2026

Choose a reason for hiding this comment

Duplicated Option array-to-variant conversion logic across files

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 9, 2026

Choose a reason for hiding this comment

Cache miss causes redundant REST fetch for existing modules

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 10, 2026

Choose a reason for hiding this comment

Subprocess pipes never drained causing potential deadlock

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 10, 2026

Choose a reason for hiding this comment

Cache logic conflates "not found" with "couldn't check"

Uh oh!

cursor bot Feb 10, 2026

Choose a reason for hiding this comment

REST client eagerly created for all JSON files

Uh oh!

cursor bot Feb 10, 2026

Choose a reason for hiding this comment

Unused account_address variables in test functions

Uh oh!

cursor bot left a comment

rahxephon89 commented Feb 4, 2026 •

edited by cursor bot

Loading

rahxephon89 commented Feb 4, 2026 •

edited

Loading

Unused `account_address` variables in test functions