@aptos-labs/ts-sdk/dist/transactions/transactionBuilder/structEnumParser.d.ts

Aptos TypeScript SDK

import { Serializer, Serializable } from "../../bcs/serializer.js";
import { EntryFunctionArgument } from "../instances/transactionArgument.js";
import { TypeTag, TypeTagStruct } from "../typeTag/index.js";
import { AptosConfig } from "../../api/aptosConfig.js";
import { MoveModuleBytecode } from "../../types/index.js";
/**
 * Represents a BCS-serializable struct argument.
 * Encodes struct fields in declaration order.
 */
export declare class MoveStructArgument extends Serializable implements EntryFunctionArgument {
    /**
     * The encoded BCS bytes for this struct.
     */
    private readonly bcsBytes;
    /**
     * Creates a new struct argument from pre-encoded BCS bytes.
     *
     * @param bcsBytes - The BCS-encoded struct bytes
     */
    constructor(bcsBytes: Uint8Array);
    serialize(serializer: Serializer): void;
    serializeForEntryFunction(serializer: Serializer): void;
    bcsToBytes(): Uint8Array;
}
/**
 * Represents a BCS-serializable enum argument.
 * Encodes variant tag (ULEB128) followed by variant fields.
 */
export declare class MoveEnumArgument extends Serializable implements EntryFunctionArgument {
    /**
     * The encoded BCS bytes for this enum.
     */
    private readonly bcsBytes;
    /**
     * Creates a new enum argument from pre-encoded BCS bytes.
     *
     * @param bcsBytes - The BCS-encoded enum bytes
     */
    constructor(bcsBytes: Uint8Array);
    serialize(serializer: Serializer): void;
    serializeForEntryFunction(serializer: Serializer): void;
    bcsToBytes(): Uint8Array;
}
/**
 * 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 declare class StructEnumArgumentParser {
    private aptosConfig;
    /**
     * Cache of module bytecode to avoid repeated fetches.
     * Key: "address::module_name"
     */
    private moduleCache;
    constructor(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;
    /**
     * Parses a struct tag string into components.
     *
     * @param typeStr - Type string like "0x1::option::Option<u64>"
     * @returns Parsed TypeTag
     */
    parseTypeString(typeStr: string): TypeTag;
    /**
     * Checks if the nesting depth exceeds the maximum allowed.
     *
     * @param depth - Current nesting depth
     * @param typeName - Type name for error messages
     */
    private checkDepth;
    /**
     * 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 fetchModule;
    /**
     * 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;
    /**
     * 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
     */
    encodeStructArgument(structTag: TypeTagStruct, value: any, depth?: number): Promise<MoveStructArgument>;
    /**
     * 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
     */
    encodeEnumArgument(structTag: TypeTagStruct, value: any, depth?: number): Promise<MoveEnumArgument>;
    /**
     * Encodes Option<T> enum using vector encoding for backward compatibility.
     */
    private encodeOptionArgument;
    /**
     * Checks if a struct tag represents std::option::Option
     */
    private isOptionType;
    /**
     * 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;
    /**
     * Encode a value based on its Move type.
     */
    private encodeValueByType;
    /**
     * Encode a vector value.
     */
    private encodeVector;
    /**
     * Encode a struct value.
     */
    private encodeStruct;
    /**
     * Parse a number from JSON value.
     */
    private parseNumber;
    /**
     * Parse a BigInt from JSON value.
     */
    private parseNumberBigInt;
}
//# sourceMappingURL=structEnumParser.d.ts.map