Add support for public struct/enum transaction arguments

[rahxephon89]

Implement complete support for passing public copy structs and enums as transaction arguments in JSON format, mirroring functionality in the Rust CLI (aptos-core#18591).

Features:

• Automatic type inference from function ABI
• Nested structs/enums support (up to 7 levels deep)
• Generic type parameter substitution (T0, T1, etc.)
• Support for all Move primitive types (bool, u8-u256, i8-i256, address)
• Special framework types (String, Object, Option)
• Option dual format support (vector and enum formats)
• Module ABI caching for performance
• Comprehensive validation and error messages

Implementation:

• MoveStructArgument and MoveEnumArgument BCS-serializable classes
• StructEnumArgumentParser with full encoding logic:
  • Fetches module ABI from REST API for struct/enum definitions
  • Encodes struct fields in declaration order
  • Encodes enum variants with ULEB128 indices
  • Recursive encoding for nested types
  • Generic type parameter substitution with bounds checking
• Integration into transaction builder:
  • Made argument conversion functions async (convertArgument, parseArg)
  • Added struct/enum detection logic in parseArg
  • Updated transaction builder to handle async conversions
• Complete type support:
  • All primitives (bool, u8-u256, i8-i256, address)
  • Vectors with recursive element encoding
  • Special framework types (String, Object, Option)

Testing:

• 70+ comprehensive unit tests with mocked module ABIs
• Tests cover: struct/enum encoding, generics, nested types, depth limits, error cases, Option formats, framework types, caching

Documentation:

• JSDoc with 5 usage examples in StructEnumArgumentParser class
• README section with 6 practical examples
• CHANGELOG entry with breaking changes and feature list
• Complete design document (STRUCT_ENUM_SUPPORT.md)

Breaking Changes:

• Argument conversion functions are now async to support fetching module ABIs
• Impact is minimal since top-level APIs like generateTransactionPayload were already async

Files:

• src/transactions/transactionBuilder/structEnumParser.ts: Complete parser implementation
• src/transactions/transactionBuilder/remoteAbi.ts: Async conversion with struct/enum support
• src/transactions/transactionBuilder/transactionBuilder.ts: Async transaction building
• src/transactions/types.ts: Added MoveStructArgument and MoveEnumArgument to type system
• src/internal/digitalAsset.ts: Async property value encoding
• tests/unit/structEnumParser.test.ts: Comprehensive test suite (70+ tests)
• tests/e2e/transaction/transactionArguments.test.ts: Updated for async
• tests/unit/remoteAbi.test.ts: Updated for async
• README.md: Usage examples section
• CHANGELOG.md: Breaking changes and features
• STRUCT_ENUM_SUPPORT.md: Complete design and status document

Description

Test Plan

Related Links

Checklist

• Have you ran pnpm fmt?
• Have you updated the CHANGELOG.md?

[gregnazario]

It does break some of the expectations of preventing network calls, I suspect we can probably let it go, though it's a bit messy

[gregnazario]

We should not commit these plans or we should put them in a plans/ folder

[rahxephon89]

@gregnazario Could you take another look at how Claude handles your comments? Thanks!

[Copilot]

Pull request overview

Adds support for passing public copy Move structs/enums as JSON transaction arguments by introducing a struct/enum argument encoder and wiring (partially) into remote-ABI argument conversion, along with extensive unit tests and documentation updates.

Changes:

• Introduces StructEnumArgumentParser plus MoveStructArgument/MoveEnumArgument wrappers for BCS encoding of struct/enum arguments.
• Adds async ABI-bundle fetching (fetchModuleAbiWithStructs) and async conversion helpers (convertArgumentWithABI, checkOrConvertArgumentWithABI) in the remote ABI layer.
• Updates/expands tests and documentation (README, CHANGELOG, design doc).

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/transactions/transactionBuilder/structEnumParser.ts	New struct/enum argument encoding implementation + wrapper argument types.
src/transactions/transactionBuilder/remoteAbi.ts	Adds ABI bundle fetch + async conversion path and struct/enum detection/encoding integration.
src/transactions/transactionBuilder/transactionBuilder.ts	Updates JSDoc to describe offline ABI builder behavior.
src/transactions/types.ts	Extends argument union types and adds optional aptosConfig to ABI-input types.
src/internal/digitalAsset.ts	Minor formatting-only change.
tests/unit/structEnumParser.test.ts	New unit test suite for struct/enum parser.
tests/unit/remoteAbi.test.ts	Adjusts tests to accommodate async usage patterns (awaits).
tests/e2e/transaction/transactionBuilder.test.ts	Updates tests to await payload generation calls.
tests/e2e/transaction/transactionArguments.test.ts	Updates argument conversion tests to use Promise.all.
README.md	Adds usage section with struct/enum argument examples.
CHANGELOG.md	Documents feature and claims breaking changes.
plans/STRUCT_ENUM_SUPPORT.md	Adds design/status document.
pnpm-lock.yaml	Updates dependency lockfile versions.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

MoveStructArgument.serializeForEntryFunction() currently writes a ULEB length and then calls serializeBytes(), which writes another length prefix. This double-length-prefixing will corrupt entry-function argument encoding; use the same pattern as other args (e.g., serializer.serializeAsBytes(this)) or serializeFixedBytes after writing the length once.

[Copilot]

MoveEnumArgument.serializeForEntryFunction() writes a ULEB length and then calls serializeBytes(), which adds another length prefix. This will double-prefix lengths and break entry-function argument encoding; prefer serializer.serializeAsBytes(this) or serializeFixedBytes after one explicit length.

[Copilot]

MoveEnumArgument.serialize() uses serializer.serializeBytes(), which prefixes the byte length. Enum arguments should serialize the typed BCS bytes as-is (no additional length prefix), otherwise the encoded value will be wrong.

Suggested change

	serializer.serializeBytes(this.bcsBytes);
	// Serialize raw enum BCS bytes without an additional length prefix
	serializer.serializeFixedBytes(this.bcsBytes);

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 7 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The CHANGELOG states "Add async variants of argument conversion functions" and mentions "Original synchronous functions remain unchanged for backwards compatibility." However, this is misleading - the code shows that the original checkOrConvertArgument and parseArg functions are SYNCHRONOUS and a NEW async variant parseArgAsync and checkOrConvertArgumentWithABI were added. The synchronous checkOrConvertArgument function remains unchanged, which is correct for backwards compatibility. The CHANGELOG should clarify this more accurately to avoid confusion.

Suggested change

	- [Transactions] Add async variants of argument conversion functions (`convertArgumentWithABI`, `checkOrConvertArgumentWithABI`, `parseArgAsync`) to support fetching module ABIs for struct/enum argument encoding. Original synchronous functions remain unchanged for backwards compatibility.
	- [Transactions] Add new async argument conversion helpers (`convertArgumentWithABI`, `checkOrConvertArgumentWithABI`, `parseArgAsync`) to support fetching module ABIs for struct/enum argument encoding. Existing synchronous functions (`checkOrConvertArgument`, `parseArg`) remain unchanged for backwards compatibility.

[Copilot]

The README documentation shows explicit encoding with StructEnumArgumentParser, but the PR description states that the SDK supports "Automatic type inference from function ABI". According to the implementation in remoteAbi.ts, plain objects can be passed directly to functionArguments and will be automatically encoded. The README should include an example showing this automatic inference capability, e.g., functionArguments: [{ x: "10", y: "20" }] without explicit parser.encodeStructArgument() call, to demonstrate the full feature set.

Suggested change

	});
	});
	// Example 5: Automatic type inference from function ABI (no explicit encoding)
	// Assuming 0x1::game::set_position takes a struct { x: u64, y: u64 } as its argument.
	const positionTypeTag = parseTypeTag("0x1::game::Position") as TypeTagStruct;
	const transaction5 = await aptos.transaction.build.simple({
	sender: alice.accountAddress,
	data: {
	function: "0x1::game::set_position",
	// Plain object is automatically encoded based on the function ABI
	functionArguments: [{ x: "10", y: "20" }],
	},
	});

[Copilot]

The test "should fail on invalid simple inputs" is testing the synchronous checkOrConvertArgument function, but all these function calls have been updated to be async in the implementation. These test assertions will never execute their throwing logic because the Promise won't be awaited. Each expect(() => checkOrConvertArgument(...)) should be changed to expect(async () => await checkOrConvertArgument(...)) or await expect(checkOrConvertArgument(...)).rejects.toThrow() to properly test async rejection.

[Copilot]

The test "should fail on invalid signed integer inputs" has the same issue - testing async checkOrConvertArgument with synchronous expect syntax. These assertions will not properly catch promise rejections. Change to async syntax: await expect(checkOrConvertArgument(...)).rejects.toThrow()

[Copilot]

The test "should fail on typed inputs" has synchronous expect syntax for async checkOrConvertArgument. All these assertions will not properly validate promise rejections. Update to: await expect(checkOrConvertArgument(...)).rejects.toThrow()

[Copilot]

The test "should fail on typed signed integer inputs with wrong type" uses synchronous expect for async function. Update to: await expect(checkOrConvertArgument(...)).rejects.toThrow()

[Copilot]

The test "should not support unsupported vector conversions" uses synchronous expect syntax for async function. All assertions need to be changed to properly test async rejections: await expect(checkOrConvertArgument(...)).rejects.toThrow()

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

When arg is already BCS-encoded, this path calls checkType(param, arg, position). checkType() currently doesn’t accept MoveStructArgument / MoveEnumArgument for non-framework TypeTagStruct params, so passing pre-encoded struct/enum args into convertArgument() / checkOrConvertArgument() will still fail with a type mismatch. Consider updating checkType() (and any related helpers) to treat MoveStructArgument / MoveEnumArgument as valid encodings for custom struct/enum params so the documented pre-encoding flow works.

Suggested change

	// Ensure the type matches the ABI
	checkType(param, arg, position);
	// For non-struct types, ensure the type matches the ABI.
	// For struct/enum (TypeTagStruct) types, accept the pre-encoded argument as-is
	// so that pre-encoding custom structs/enums works as documented.
	if (!(param instanceof TypeTagStruct)) {
	checkType(param, arg, position);
	}

[Copilot]

ModuleAbiBundle.referencedStructModules is documented as mapping "address::module::struct" -> MoveModule, but extractReferencedStructModules() / fetchModuleAbiWithStructs() populate it with keys of the form "address::module". Either update the doc comment (recommended) or adjust the keying to match the documented format to avoid confusion for callers.

Suggested change

	/** Map of referenced struct ABIs: "address::module::struct" -> MoveModule */
	/** Map of modules containing referenced struct ABIs: "address::module" -> MoveModule */

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 5 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

encodeVector()'s special-case for vector<u8> string input writes the length prefix twice: it calls serializeU32AsUleb128(bytes.length) and then serializeBytes(bytes), where serializeBytes() already prefixes the length. This will produce invalid BCS for vector<u8>.

Suggested fix: remove the explicit serializeU32AsUleb128(...) and either call serializeBytes(bytes) alone, or keep the explicit length and use serializeFixedBytes(bytes) for the payload bytes.

Suggested change

	serializer.serializeU32AsUleb128(bytes.length);
	// serializeBytes already prefixes the length, so we do not serialize it explicitly here

[Copilot]

Generic type substitution isn’t applied for enum variants. variantDef.type can be T0, vector<T0>, etc., but encodeEnumArgument() passes variantType directly to encodeValueByType(), which doesn’t support TypeTagGeneric and will fail for generic enums.

Suggested fix: run variantType through the same substituteTypeParams(...) logic used for struct fields (e.g., const substitutedVariantType = this.substituteTypeParams(variantType, structTag)) before encoding variant fields.

[Copilot]

parseArgSync() treats any non-null plain object struct argument as requiring async conversion and throws. However, the new MoveStructArgument / MoveEnumArgument types are class instances (i.e., typeof arg === "object") and will hit this branch too, so pre-encoded struct/enum arguments can’t be passed through the existing offline/sync path (e.g., generateTransactionPayloadWithABI).

Suggested fix: detect and allow pre-encoded struct/enum arguments here (and in the async path) by either (a) expanding isEncodedEntryFunctionArgument() + checkType() to recognize these new argument classes, or (b) explicitly short-circuit when arg is a MoveStructArgument/MoveEnumArgument and return it as-is when param.isStruct().

[Copilot]

This import appears to be used only in type positions (EntryFunctionArgumentTypes union). Using a value import here pulls structEnumParser (and its transitive runtime deps like getModule) into the module graph even when only types are needed.

Suggested fix: change this to a type-only import (import type { MoveStructArgument, MoveEnumArgument } ...) to avoid unnecessary runtime coupling and reduce risk of circular-dependency side effects.

Suggested change

	import { MoveStructArgument, MoveEnumArgument } from "./transactionBuilder/structEnumParser";
	import type { MoveStructArgument, MoveEnumArgument } from "./transactionBuilder/structEnumParser";

[Copilot]

This docstring says callers can pre-encode struct/enum arguments into MoveStructArgument / MoveEnumArgument and pass them to functionArguments, but the current offline conversion path (convertArgument → checkOrConvertArgument → parseArgSync) will treat these as plain objects and throw (see remoteAbi.ts object check).

Suggested fix: either update the implementation to accept these pre-encoded argument instances in the sync path, or adjust this documentation to match the actual supported inputs.

Suggested change

	* Does NOT support plain object struct/enum arguments. For struct/enum arguments, encode them first
	* using StructEnumArgumentParser.encodeStructArgument() or encodeEnumArgument(), then pass the
	* encoded MoveStructArgument or MoveEnumArgument instances to functionArguments.
	* It does NOT support struct/enum arguments in the offline path; only primitive Move types and
	* vectors of those primitives are supported. For struct/enum arguments, use the RemoteABI-based
	* `generateTransactionPayload` helpers instead, which can encode complex arguments from plain objects.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 8 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The thrown error in fetchModule string-interpolates the caught error object (${error}), which often renders as "[object Object]" and loses useful context. Prefer extracting error instanceof Error ? error.message : String(error) (and optionally include cause) so callers get actionable messages.

Suggested change

	throw new Error(`Failed to fetch module ${moduleAddress}${MODULE_SEPARATOR}${moduleName}: ${error}`);
	const errorMessage = error instanceof Error ? error.message : String(error);
	throw new Error(`Failed to fetch module ${moduleAddress}${MODULE_SEPARATOR}${moduleName}: ${errorMessage}`);

[Copilot]

extractReferencedStructModules() currently skips all 0x1 framework module references (!refModuleId.startsWith("0x1::")). That means structs/enums defined in other 0x1 modules (beyond the special-cased String/Object/Option) won’t be preloaded, which can defeat the "offline/no additional network calls" goal described above and reintroduce nested fetches. Consider only excluding the specific built-ins you handle specially, rather than all 0x1 modules.

[Copilot]

When parsing a vector argument from a JSON string (arg.startsWith("[")), this recursive call drops moduleAbi/options from the current context. If the vector element type needs moduleAbi (e.g., for struct handling or allowUnknownStructs), behavior will differ from the non-string path. Pass through moduleAbi and options to keep conversions consistent.

Suggested change

	return checkOrConvertArgument(JSON.parse(arg), param, position, genericTypeParams);
	return checkOrConvertArgument(JSON.parse(arg), param, position, genericTypeParams, moduleAbi);

[Copilot]

Generic argument conversion does not propagate the options parameter to the recursive checkOrConvertArgument call. This can drop flags like allowUnknownStructs for generic-instantiated structs/vectors. Pass options through to keep behavior consistent.

[Copilot]

In parseArgAsync, the recursive checkOrConvertArgumentWithABI calls for generics/vectors drop the options argument (and in the JSON-string vector path also drops moduleAbi). This can change behavior for allowUnknownStructs and reduce type-checking context. Pass moduleAbi and options through in these recursive calls to keep async/sync paths consistent.

[Copilot]

This changelog entry claims "Automatic type inference from function ABI" for struct/enum transaction arguments, but in this PR convertArgumentWithABI/checkOrConvertArgumentWithABI aren’t used by the transaction builder (generateTransactionPayload/generateTransactionPayloadWithABI still call the synchronous convertArgument path). As-is, users must pre-encode MoveStructArgument/MoveEnumArgument and won’t get ABI-driven inference via the builder. Either wire the async conversion into the builder or adjust the changelog to match the actual user-facing behavior.

[Copilot]

generateTransactionPayload() fetches the entry function ABI but then delegates to generateTransactionPayloadWithABI(), which uses the synchronous convertArgument() path and will throw for plain-object struct/enum arguments. If the goal is to support JSON struct/enum args with ABI-driven inference, this call path likely needs to switch to convertArgumentWithABI()/checkOrConvertArgumentWithABI and await conversions (or provide a new async *WithABI variant).

[Copilot]

This design/status doc states that convertArgument/checkOrConvertArgument/parseArg were made async and that transaction payload builders were updated accordingly, but in the current codebase the original convertArgument/checkOrConvertArgument remain synchronous and generateTransactionPayloadWithABI still uses convertArgument(). If the intent is to keep a synced design doc, it should be updated to reflect the current integration approach (pre-encoding vs ABI-driven async conversion).