@aptos-labs/ts-sdk 6.3.0 → 7.0.0

package/src/transactions/transactionBuilder/structEnumParser.ts

@@ -0,0 +1,848 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Parser for public copy structs and enums as transaction arguments.
+ *
+ * This module enables the TypeScript SDK to accept public copy structs and enums
+ * as transaction arguments in JSON format, automatically encoding them to BCS.
+ *
+ * Key features:
+ * - Queries on-chain metadata for struct/enum definitions
+ * - Parses JSON input matching Move struct/enum types
+ * - Encodes arguments to BCS format
+ * - Supports nested structs/enums with depth limits
+ * - Handles Option<T> in both vector and enum formats
+ *
+ * @group Implementation
+ * @category Transactions
+ */
+
+import { AccountAddress } from "../../core/accountAddress.js";
+import { Serializer, Serializable } from "../../bcs/serializer.js";
+import { EntryFunctionArgument } from "../instances/transactionArgument.js";
+import {
+  TypeTag,
+  TypeTagBool,
+  TypeTagU8,
+  TypeTagU16,
+  TypeTagU32,
+  TypeTagU64,
+  TypeTagU128,
+  TypeTagU256,
+  TypeTagI8,
+  TypeTagI16,
+  TypeTagI32,
+  TypeTagI64,
+  TypeTagI128,
+  TypeTagI256,
+  TypeTagAddress,
+  TypeTagStruct,
+  TypeTagVector,
+  TypeTagGeneric,
+  StructTag,
+} from "../typeTag/index.js";
+import { parseTypeTag } from "../typeTag/parser.js";
+import { AptosConfig } from "../../api/aptosConfig.js";
+import { getModule } from "../../internal/account.js";
+import { MoveModuleBytecode } from "../../types/index.js";
+import {
+  Bool,
+  U8,
+  U16,
+  U32,
+  U64,
+  U128,
+  U256,
+  I8,
+  I16,
+  I32,
+  I64,
+  I128,
+  I256,
+} from "../../bcs/serializable/movePrimitives.js";
+import { MoveString, MoveOption } from "../../bcs/serializable/moveStructs.js";
+
+/**
+ * Maximum nesting depth for structs, enums, and vectors.
+ * Prevents stack overflow and excessively complex arguments.
+ * Matches the limit in the Rust CLI implementation.
+ */
+const MAX_NESTING_DEPTH = 7;
+
+/**
+ * Module path separator used in fully-qualified type names.
+ * Matches MODULE_SEPARATOR constant from Rust implementation.
+ */
+const MODULE_SEPARATOR = "::";
+
+/**
+ * Represents a BCS-serializable struct argument.
+ * Encodes struct fields in declaration order.
+ */
+export class MoveStructArgument extends Serializable implements EntryFunctionArgument {
+  /**
+   * The encoded BCS bytes for this struct.
+   */
+  private readonly bcsBytes: Uint8Array;
+
+  /**
+   * Creates a new struct argument from pre-encoded BCS bytes.
+   *
+   * @param bcsBytes - The BCS-encoded struct bytes
+   */
+  constructor(bcsBytes: Uint8Array) {
+    super();
+    this.bcsBytes = bcsBytes;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeFixedBytes(this.bcsBytes);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    // For entry functions, we need to prefix with the byte length
+    serializer.serializeU32AsUleb128(this.bcsBytes.length);
+    serializer.serializeFixedBytes(this.bcsBytes);
+  }
+
+  bcsToBytes(): Uint8Array {
+    // Return raw struct bytes without additional wrapping
+    return this.bcsBytes;
+  }
+}
+
+/**
+ * Represents a BCS-serializable enum argument.
+ * Encodes variant tag (ULEB128) followed by variant fields.
+ */
+export class MoveEnumArgument extends Serializable implements EntryFunctionArgument {
+  /**
+   * The encoded BCS bytes for this enum.
+   */
+  private readonly bcsBytes: Uint8Array;
+
+  /**
+   * Creates a new enum argument from pre-encoded BCS bytes.
+   *
+   * @param bcsBytes - The BCS-encoded enum bytes
+   */
+  constructor(bcsBytes: Uint8Array) {
+    super();
+    this.bcsBytes = bcsBytes;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeFixedBytes(this.bcsBytes);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    // For entry functions, we need to prefix with the byte length
+    serializer.serializeU32AsUleb128(this.bcsBytes.length);
+    serializer.serializeFixedBytes(this.bcsBytes);
+  }
+
+  bcsToBytes(): Uint8Array {
+    // Return raw enum bytes without additional wrapping
+    return this.bcsBytes;
+  }
+}
+
+/**
+ * Parser for struct and enum transaction arguments.
+ *
+ * This class enables passing public copy structs and enums as transaction arguments
+ * by automatically fetching module ABIs and encoding values to BCS format.
+ *
+ * @example
+ * ```typescript
+ * // Example 1: Encode a simple struct
+ * const parser = new StructEnumArgumentParser(config);
+ * const structTag = parseTypeTag("0x1::test::Point") as TypeTagStruct;
+ * const value = { x: "10", y: "20" };
+ * const encoded = await parser.encodeStructArgument(structTag, value);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Example 2: Encode an enum variant
+ * const parser = new StructEnumArgumentParser(config);
+ * const enumTag = parseTypeTag("0x1::test::Color") as TypeTagStruct;
+ * const value = { Red: {} }; // No fields
+ * const encoded = await parser.encodeEnumArgument(enumTag, value);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Example 3: Use in transaction builder
+ * const txn = await aptos.transaction.build.simple({
+ *   sender: alice.accountAddress,
+ *   data: {
+ *     function: "0x1::test::draw_line",
+ *     functionArguments: [
+ *       { start: { x: "0", y: "0" }, end: { x: "10", y: "10" } }, // Line struct
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Example 4: Generic structs with type substitution
+ * const parser = new StructEnumArgumentParser(config);
+ * const boxTag = parseTypeTag("0x1::test::Box<u64>") as TypeTagStruct;
+ * const value = { value: "42" };
+ * const encoded = await parser.encodeStructArgument(boxTag, value);
+ * // Generic parameter T0 is automatically substituted with u64
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Example 5: Option enum (dual format support)
+ * // Vector format (backward compatible):
+ * functionArguments: [[]];  // None
+ * functionArguments: [[42]]; // Some(42)
+ *
+ * // Enum format (new standard):
+ * functionArguments: [{ None: {} }];
+ * functionArguments: [{ Some: { "0": "42" } }];
+ * ```
+ *
+ * Features:
+ * - Automatic module ABI fetching and caching
+ * - Recursive encoding for nested structs/enums
+ * - Generic type parameter substitution (T0, T1, etc.)
+ * - Depth limit enforcement (max 7 levels)
+ * - Support for all Move primitive types
+ * - Vector encoding with element recursion
+ * - Special handling for String, Object<T>, Option<T>
+ *
+ * @group Implementation
+ * @category Transactions
+ */
+export class StructEnumArgumentParser {
+  private aptosConfig: AptosConfig;
+
+  /**
+   * Cache of module bytecode to avoid repeated fetches.
+   * Key: "address::module_name"
+   */
+  private moduleCache: Map<string, MoveModuleBytecode> = new Map();
+
+  constructor(aptosConfig: AptosConfig) {
+    this.aptosConfig = aptosConfig;
+  }
+
+  /**
+   * Pre-populates the module cache with modules from a ModuleAbiBundle.
+   * This optimization eliminates nested network calls by providing all necessary
+   * struct definitions upfront.
+   *
+   * @param modules - Map of module ID (address::name) to MoveModule
+   */
+  preloadModules(modules: Map<string, MoveModuleBytecode>): void {
+    for (const [moduleId, moduleBytecode] of modules.entries()) {
+      this.moduleCache.set(moduleId, moduleBytecode);
+    }
+  }
+
+  /**
+   * Parses a struct tag string into components.
+   *
+   * @param typeStr - Type string like "0x1::option::Option<u64>"
+   * @returns Parsed TypeTag
+   */
+  parseTypeString(typeStr: string): TypeTag {
+    // Use the SDK's built-in TypeTag parsing with generics support
+    return parseTypeTag(typeStr, { allowGenerics: true });
+  }
+
+  /**
+   * Checks if the nesting depth exceeds the maximum allowed.
+   *
+   * @param depth - Current nesting depth
+   * @param typeName - Type name for error messages
+   */
+  private checkDepth(depth: number, typeName: string): void {
+    if (depth > MAX_NESTING_DEPTH) {
+      throw new Error(`${typeName} nesting depth ${depth} exceeds maximum allowed depth of ${MAX_NESTING_DEPTH}`);
+    }
+  }
+
+  /**
+   * Fetches module bytecode from the chain.
+   * Results are cached to avoid repeated fetches.
+   *
+   * @param moduleAddress - Module address
+   * @param moduleName - Module name
+   * @returns Module bytecode
+   */
+  private async fetchModule(moduleAddress: AccountAddress, moduleName: string): Promise<MoveModuleBytecode> {
+    const cacheKey = `${moduleAddress.toString()}${MODULE_SEPARATOR}${moduleName}`;
+
+    // Check cache first
+    if (this.moduleCache.has(cacheKey)) {
+      return this.moduleCache.get(cacheKey)!;
+    }
+
+    // Fetch from chain
+    try {
+      const accountModules = await getModule({
+        aptosConfig: this.aptosConfig,
+        accountAddress: moduleAddress,
+        moduleName,
+      });
+
+      this.moduleCache.set(cacheKey, accountModules);
+      return accountModules;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to fetch module ${moduleAddress}${MODULE_SEPARATOR}${moduleName}: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Determines if a type is a struct or enum that requires special handling.
+   *
+   * @param typeTag - The type tag to check
+   * @returns true if this is a struct/enum requiring special parsing
+   */
+  isStructOrEnum(typeTag: TypeTag): boolean {
+    if (!(typeTag instanceof TypeTagStruct)) {
+      return false;
+    }
+
+    const qualifiedName = `${typeTag.value.address.toString()}${MODULE_SEPARATOR}${typeTag.value.moduleName.identifier}${MODULE_SEPARATOR}${typeTag.value.name.identifier}`;
+
+    // Special built-in types that are already handled
+    const builtinTypes = ["0x1::string::String", "0x1::object::Object", "0x1::option::Option"];
+
+    // If it's a built-in type, don't treat as custom struct/enum
+    for (const builtinType of builtinTypes) {
+      if (qualifiedName.startsWith(builtinType)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Encodes a struct argument to BCS bytes.
+   *
+   * @param structTag - The struct type tag
+   * @param value - JSON object with field values
+   * @param depth - Current nesting depth
+   * @returns BCS-encoded struct argument
+   */
+  async encodeStructArgument(structTag: TypeTagStruct, value: any, depth: number = 0): Promise<MoveStructArgument> {
+    this.checkDepth(depth, "Struct");
+
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new Error(`Expected object for struct argument, got ${typeof value}`);
+    }
+
+    // Fetch module to get struct definition
+    const module = await this.fetchModule(structTag.value.address, structTag.value.moduleName.identifier);
+
+    if (!module.abi) {
+      throw new Error(
+        `Module ${structTag.value.address}${MODULE_SEPARATOR}${structTag.value.moduleName.identifier} has no ABI`,
+      );
+    }
+
+    // Find the struct definition
+    const structDef = module.abi.structs.find((s) => s.name === structTag.value.name.identifier);
+
+    if (!structDef) {
+      throw new Error(
+        `Struct ${structTag.value.name.identifier} not found in module ${structTag.value.address}${MODULE_SEPARATOR}${structTag.value.moduleName.identifier}`,
+      );
+    }
+
+    if (structDef.is_enum) {
+      throw new Error(
+        `Type ${structTag.value.name.identifier} is an enum. Use enum variant syntax instead (e.g., {"VariantName": {...}})`,
+      );
+    }
+
+    if (structDef.is_native) {
+      throw new Error(`Struct ${structTag.value.name.identifier} is a native struct and cannot be used as an argument`);
+    }
+
+    // Encode each field in order
+    const serializer = new Serializer();
+
+    for (const field of structDef.fields) {
+      const fieldValue = value[field.name];
+      if (fieldValue === undefined) {
+        throw new Error(`Missing field '${field.name}' for struct ${structTag.value.name.identifier}`);
+      }
+
+      // Parse field type and substitute generics
+      const fieldTypeTag = this.parseTypeString(field.type);
+      const substitutedType = this.substituteTypeParams(fieldTypeTag, structTag);
+
+      // Encode field value
+      const encoded = await this.encodeValueByType(substitutedType, fieldValue, depth + 1);
+      serializer.serializeFixedBytes(encoded);
+    }
+
+    return new MoveStructArgument(serializer.toUint8Array());
+  }
+
+  /**
+   * Encodes an enum argument to BCS bytes.
+   *
+   * @param structTag - The enum type tag
+   * @param value - JSON object with variant name and fields
+   * @param depth - Current nesting depth
+   * @returns BCS-encoded enum argument
+   */
+  async encodeEnumArgument(structTag: TypeTagStruct, value: any, depth: number = 0): Promise<MoveEnumArgument> {
+    this.checkDepth(depth, "Enum");
+
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new Error(`Expected object for enum argument, got ${typeof value}`);
+    }
+
+    // Enum format: { "VariantName": { "field1": value1, ... } }
+    const variantNames = Object.keys(value);
+    if (variantNames.length !== 1) {
+      throw new Error(`Enum value must have exactly one variant, got ${variantNames.length}`);
+    }
+
+    const variantName = variantNames[0];
+    const variantFields = value[variantName];
+
+    // Special handling for Option<T> - uses vector encoding for backward compatibility
+    if (this.isOptionType(structTag)) {
+      return this.encodeOptionArgument(structTag, variantName, variantFields, depth);
+    }
+
+    // Fetch module to get enum definition
+    const module = await this.fetchModule(structTag.value.address, structTag.value.moduleName.identifier);
+
+    if (!module.abi) {
+      throw new Error(
+        `Module ${structTag.value.address}${MODULE_SEPARATOR}${structTag.value.moduleName.identifier} has no ABI`,
+      );
+    }
+
+    // Find the enum definition
+    const enumDef = module.abi.structs.find((s) => s.name === structTag.value.name.identifier);
+
+    if (!enumDef) {
+      throw new Error(
+        `Enum ${structTag.value.name.identifier} not found in module ${structTag.value.address}${MODULE_SEPARATOR}${structTag.value.moduleName.identifier}`,
+      );
+    }
+
+    if (!enumDef.is_enum) {
+      throw new Error(
+        `Type ${structTag.value.name.identifier} is a struct, not an enum. Provide field values directly as an object.`,
+      );
+    }
+
+    // For enums, fields array represents variants
+    // Find variant index by name
+    const variantIndex = enumDef.fields.findIndex((f) => f.name === variantName);
+
+    if (variantIndex === -1) {
+      const availableVariants = enumDef.fields.map((f) => f.name).join(", ");
+      throw new Error(
+        `Variant '${variantName}' not found in enum ${structTag.value.name.identifier}. Available variants: ${availableVariants}`,
+      );
+    }
+
+    const serializer = new Serializer();
+
+    // Encode variant index as ULEB128
+    serializer.serializeU32AsUleb128(variantIndex);
+
+    // Note: For enum variants with fields, the field information is in the variant's type string
+    // E.g., for "Some" variant of Option<T>, the type might be "T"
+    // However, the REST API may not provide complete field metadata for enum variants
+    // We need to handle the variantFields based on the type string
+
+    const variantDef = enumDef.fields[variantIndex];
+    // Substitute generic type parameters for the variant payload type so that
+    // generic enums (e.g. `Some(T0)`) are encoded against the instantiated type.
+    const variantType = this.substituteTypeParams(this.parseTypeString(variantDef.type), structTag);
+
+    // If variant has fields, encode them
+    if (typeof variantFields === "object" && variantFields !== null && !Array.isArray(variantFields)) {
+      // Variant has fields as an object
+      const fieldKeys = Object.keys(variantFields);
+
+      // Sort keys to ensure correct field order
+      // Enum variants with multiple fields should use numbered keys: {"0": val1, "1": val2, ...}
+      const sortedKeys = fieldKeys.sort((a, b) => {
+        const numA = parseInt(a, 10);
+        const numB = parseInt(b, 10);
+
+        // If keys are not numeric, maintain object key order (which may be wrong)
+        if (Number.isNaN(numA) || Number.isNaN(numB)) {
+          return 0;
+        }
+
+        return numA - numB;
+      });
+
+      // Validate that multi-field variants use sequential numeric keys
+      if (sortedKeys.length > 1) {
+        for (let i = 0; i < sortedKeys.length; i++) {
+          const expectedKey = i.toString();
+          if (sortedKeys[i] !== expectedKey) {
+            throw new Error(
+              `Enum variant with multiple fields must use sequential numeric keys starting from "0". ` +
+                `Expected key "${expectedKey}" at position ${i}, got "${sortedKeys[i]}". ` +
+                `Use format: { ${variantName}: { "0": value1, "1": value2, ... } }`,
+            );
+          }
+        }
+
+        // Note: The REST API doesn't provide individual field type information for enum variants.
+        // For multi-field variants, we use the variant's type for all fields (limitation).
+        // This may not work for variants with fields of different types.
+        // TODO: Use bytecode parsing to get exact field types when available
+      }
+
+      // Encode each field in order
+      for (const key of sortedKeys) {
+        const fieldValue = variantFields[key];
+        // Use the variant's type as the field type (simplified approach)
+        const encoded = await this.encodeValueByType(variantType, fieldValue, depth + 1);
+        serializer.serializeFixedBytes(encoded);
+      }
+    } else if (variantFields !== undefined && variantFields !== null) {
+      // Single value variant (not an object)
+      const encoded = await this.encodeValueByType(variantType, variantFields, depth + 1);
+      serializer.serializeFixedBytes(encoded);
+    }
+
+    return new MoveEnumArgument(serializer.toUint8Array());
+  }
+
+  /**
+   * Encodes Option<T> enum using vector encoding for backward compatibility.
+   */
+  private async encodeOptionArgument(
+    structTag: TypeTagStruct,
+    variant: string,
+    fieldValue: any,
+    depth: number,
+  ): Promise<MoveEnumArgument> {
+    if (structTag.value.typeArgs.length === 0) {
+      throw new Error("Option must have a type parameter");
+    }
+
+    const innerType = structTag.value.typeArgs[0];
+    const serializer = new Serializer();
+
+    if (variant === "None") {
+      // None: empty vector (length = 0)
+      serializer.serializeU32AsUleb128(0);
+    } else if (variant === "Some") {
+      // Some: vector with one element (length = 1)
+      serializer.serializeU32AsUleb128(1);
+
+      // Extract the value from the field
+      let value: any;
+      if (typeof fieldValue === "object" && fieldValue !== null && !Array.isArray(fieldValue)) {
+        // Handle {"0": value} format
+        value = fieldValue["0"] !== undefined ? fieldValue["0"] : fieldValue;
+      } else {
+        value = fieldValue;
+      }
+
+      const encoded = await this.encodeValueByType(innerType, value, depth + 1);
+      serializer.serializeFixedBytes(encoded);
+    } else {
+      throw new Error(`Unknown Option variant '${variant}'. Expected 'None' or 'Some'`);
+    }
+
+    return new MoveEnumArgument(serializer.toUint8Array());
+  }
+
+  /**
+   * Checks if a struct tag represents std::option::Option
+   */
+  private isOptionType(structTag: TypeTagStruct): boolean {
+    return (
+      structTag.value.address.toString() === "0x1" &&
+      structTag.value.moduleName.identifier === "option" &&
+      structTag.value.name.identifier === "Option"
+    );
+  }
+
+  /**
+   * Substitute generic type parameters with concrete types.
+   *
+   * Replaces generic type parameters (T0, T1, T2, etc.) with their concrete
+   * instantiations from the struct/enum type arguments.
+   *
+   * @example
+   * // Struct: Box<T0> { value: T0 }
+   * // Instantiation: Box<u64>
+   * // Field type T0 → u64
+   *
+   * @param fieldType - The type tag that may contain generic parameters
+   * @param structTag - The instantiated struct/enum with concrete type arguments
+   * @returns Type tag with all generic parameters replaced
+   */
+  private substituteTypeParams(fieldType: TypeTag, structTag: TypeTagStruct): TypeTag {
+    // Handle generic type parameter (T0, T1, T2, etc.)
+    if (fieldType instanceof TypeTagGeneric) {
+      const index = fieldType.value;
+      if (index >= structTag.value.typeArgs.length) {
+        throw new Error(
+          `Generic type parameter T${index} out of bounds. ${structTag.value.name.identifier} has ${structTag.value.typeArgs.length} type arguments.`,
+        );
+      }
+      return structTag.value.typeArgs[index];
+    }
+
+    // Handle vector types - recursively substitute inner type
+    if (fieldType instanceof TypeTagVector) {
+      const substitutedInner = this.substituteTypeParams(fieldType.value, structTag);
+      return new TypeTagVector(substitutedInner);
+    }
+
+    // Handle struct types - recursively substitute type arguments
+    if (fieldType instanceof TypeTagStruct) {
+      if (fieldType.value.typeArgs.length === 0) {
+        // No type arguments, return as-is
+        return fieldType;
+      }
+
+      // Substitute each type argument
+      const substitutedTypeArgs = fieldType.value.typeArgs.map((typeArg) =>
+        this.substituteTypeParams(typeArg, structTag),
+      );
+
+      // Create new struct tag with substituted type arguments
+      const newStructTag = new StructTag(
+        fieldType.value.address,
+        fieldType.value.moduleName,
+        fieldType.value.name,
+        substitutedTypeArgs,
+      );
+      return new TypeTagStruct(newStructTag);
+    }
+
+    // Primitive types and other non-generic types remain unchanged
+    return fieldType;
+  }
+
+  /**
+   * Encode a value based on its Move type.
+   */
+  private async encodeValueByType(typeTag: TypeTag, value: any, depth: number): Promise<Uint8Array> {
+    this.checkDepth(depth, "Type");
+
+    // Primitive types - use instanceof to avoid TypeScript control flow issues
+    if (typeTag instanceof TypeTagBool) {
+      if (typeof value !== "boolean") {
+        throw new Error(`Expected boolean for bool type, got ${typeof value}`);
+      }
+      return new Bool(value).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagU8) {
+      return new U8(this.parseNumber(value, "u8")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagU16) {
+      return new U16(this.parseNumber(value, "u16")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagU32) {
+      return new U32(this.parseNumber(value, "u32")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagU64) {
+      return new U64(this.parseNumberBigInt(value, "u64")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagU128) {
+      return new U128(this.parseNumberBigInt(value, "u128")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagU256) {
+      return new U256(this.parseNumberBigInt(value, "u256")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagI8) {
+      return new I8(this.parseNumber(value, "i8")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagI16) {
+      return new I16(this.parseNumber(value, "i16")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagI32) {
+      return new I32(this.parseNumber(value, "i32")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagI64) {
+      return new I64(this.parseNumberBigInt(value, "i64")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagI128) {
+      return new I128(this.parseNumberBigInt(value, "i128")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagI256) {
+      return new I256(this.parseNumberBigInt(value, "i256")).bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagAddress) {
+      const addr = AccountAddress.from(value);
+      return addr.bcsToBytes();
+    }
+    if (typeTag instanceof TypeTagVector) {
+      return this.encodeVector(typeTag, value, depth);
+    }
+    if (typeTag instanceof TypeTagStruct) {
+      return this.encodeStruct(typeTag, value, depth);
+    }
+
+    throw new Error(`Unsupported type: ${typeTag.toString()}`);
+  }
+
+  /**
+   * Encode a vector value.
+   */
+  private async encodeVector(vectorType: TypeTagVector, value: any, depth: number): Promise<Uint8Array> {
+    if (!Array.isArray(value)) {
+      // Special case: vector<u8> can be a string
+      if (vectorType.value instanceof TypeTagU8 && typeof value === "string") {
+        // Treat as UTF-8 encoded string. `serializeBytes` already writes the
+        // ULEB128 length prefix, so we must not write the length explicitly.
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(value);
+        const serializer = new Serializer();
+        serializer.serializeBytes(bytes);
+        return serializer.toUint8Array();
+      }
+
+      throw new Error(`Expected array for vector type, got ${typeof value}`);
+    }
+
+    const serializer = new Serializer();
+    serializer.serializeU32AsUleb128(value.length);
+
+    for (const item of value) {
+      const encoded = await this.encodeValueByType(vectorType.value, item, depth + 1);
+      serializer.serializeFixedBytes(encoded);
+    }
+
+    return serializer.toUint8Array();
+  }
+
+  /**
+   * Encode a struct value.
+   */
+  private async encodeStruct(structTag: TypeTagStruct, value: any, depth: number): Promise<Uint8Array> {
+    const qualifiedName = `${structTag.value.address.toString()}${MODULE_SEPARATOR}${structTag.value.moduleName.identifier}${MODULE_SEPARATOR}${structTag.value.name.identifier}`;
+
+    // Handle special framework types
+    if (qualifiedName === "0x1::string::String") {
+      if (typeof value !== "string") {
+        throw new Error(`Expected string for String type, got ${typeof value}`);
+      }
+      return new MoveString(value).bcsToBytes();
+    }
+
+    if (qualifiedName === "0x1::object::Object") {
+      const addr = AccountAddress.from(value);
+      return addr.bcsToBytes();
+    }
+
+    if (qualifiedName === "0x1::option::Option") {
+      // Handle Option<T> in both formats
+      if (Array.isArray(value)) {
+        // Vector format: [] or [value]
+        if (value.length === 0) {
+          return new MoveOption(null).bcsToBytes();
+        }
+        if (value.length === 1) {
+          // Encode the inner value
+          if (structTag.value.typeArgs.length === 0) {
+            throw new Error("Option must have a type parameter");
+          }
+          const innerType = structTag.value.typeArgs[0];
+          const encodedInner = await this.encodeValueByType(innerType, value[0], depth + 1);
+          const serializer = new Serializer();
+          serializer.serializeU32AsUleb128(1); // Some
+          serializer.serializeFixedBytes(encodedInner);
+          return serializer.toUint8Array();
+        }
+        throw new Error(`Option as vector must have 0 or 1 elements, got ${value.length}`);
+      }
+
+      if (typeof value === "object" && value !== null) {
+        // Enum format: {"None": {}} or {"Some": {"0": value}}
+        const variantNames = Object.keys(value);
+        if (variantNames.length === 1) {
+          const result = await this.encodeEnumArgument(structTag, value, depth);
+          return result.bcsToBytes();
+        }
+      }
+
+      throw new Error(`Invalid Option format. Expected array [] or [value], or enum {"None": {}} or {"Some": {...}}`);
+    }
+
+    // Check if this is an enum (single key = variant name)
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      const keys = Object.keys(value);
+      if (keys.length === 1) {
+        // Might be an enum variant
+        // Try to fetch the struct and check is_enum flag
+        try {
+          const module = await this.fetchModule(structTag.value.address, structTag.value.moduleName.identifier);
+          if (module.abi) {
+            const structDef = module.abi.structs.find((s) => s.name === structTag.value.name.identifier);
+            if (structDef?.is_enum) {
+              const result = await this.encodeEnumArgument(structTag, value, depth);
+              return result.bcsToBytes();
+            }
+          }
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        } catch (_e) {
+          // If we can't determine, treat as struct
+        }
+      }
+    }
+
+    // Regular struct
+    const result = await this.encodeStructArgument(structTag, value, depth);
+    return result.bcsToBytes();
+  }
+
+  /**
+   * Parse a number from JSON value.
+   */
+  private parseNumber(value: any, typeName: string): number {
+    if (typeof value === "number") {
+      return value;
+    }
+    if (typeof value === "string") {
+      const parsed = parseInt(value, 10);
+      if (Number.isNaN(parsed)) {
+        throw new Error(`Invalid ${typeName} value: ${value}`);
+      }
+      return parsed;
+    }
+    throw new Error(`Expected number or string for ${typeName}, got ${typeof value}`);
+  }
+
+  /**
+   * Parse a BigInt from JSON value.
+   */
+  private parseNumberBigInt(value: any, typeName: string): bigint {
+    if (typeof value === "bigint") {
+      return value;
+    }
+    if (typeof value === "number") {
+      return BigInt(value);
+    }
+    if (typeof value === "string") {
+      try {
+        return BigInt(value);
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (_e) {
+        throw new Error(`Invalid ${typeName} value: ${value}`);
+      }
+    }
+    throw new Error(`Expected number, bigint, or string for ${typeName}, got ${typeof value}`);
+  }
+}