@aptos-labs/ts-sdk 1.33.1 → 1.33.2-sc.0

package/src/transactions/scriptComposer/index.ts

@@ -0,0 +1,86 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import { ScriptComposerWasm } from "@aptos-labs/script-composer-pack";
+import { AptosApiType } from "../../utils";
+import { AptosConfig } from "../../api/aptosConfig";
+import { InputBatchedFunctionData } from "../types";
+import { fetchMoveFunctionAbi, getFunctionParts, standardizeTypeTags } from "../transactionBuilder";
+import { CallArgument } from "../../types";
+import { convertCallArgument } from "../transactionBuilder/remoteAbi";
+
+// A wrapper class around TransactionComposer, which is a WASM library compiled
+// from aptos-core/aptos-move/script-composer.
+//
+// This class allows the SDK caller to build a transaction that invokes multiple Move functions
+// and allow for arguments to be passed around.
+export class AptosScriptComposer {
+  private config: AptosConfig;
+
+  private builder?: any;
+
+  private static transactionComposer?: any;
+
+  constructor(aptosConfig: AptosConfig) {
+    this.config = aptosConfig;
+    this.builder = undefined;
+  }
+
+  // Initializing the wasm needed for the script composer, must be called
+  // before using the composer.
+  async init() {
+    if (!AptosScriptComposer.transactionComposer) {
+      const module = await import("@aptos-labs/script-composer-pack");
+      const { TransactionComposer, initSync } = module;
+      if (!ScriptComposerWasm.isInitialized) {
+        ScriptComposerWasm.init();
+      }
+      initSync({ module: ScriptComposerWasm.wasm });
+      AptosScriptComposer.transactionComposer = TransactionComposer;
+    }
+    this.builder = AptosScriptComposer.transactionComposer.single_signer();
+  }
+
+  // Add a move function invocation to the TransactionComposer.
+  //
+  // Similar to how to create an entry function, the difference is that input arguments could
+  // either be a `CallArgument` which represents an abstract value returned from a previous Move call
+  // or the regular entry function arguments.
+  //
+  // The function would also return a list of `CallArgument` that can be passed on to future calls.
+  async addBatchedCalls(input: InputBatchedFunctionData): Promise<CallArgument[]> {
+    const { moduleAddress, moduleName, functionName } = getFunctionParts(input.function);
+    const nodeUrl = this.config.getRequestUrl(AptosApiType.FULLNODE);
+
+    // Load the calling module into the builder.
+    await this.builder.load_module(nodeUrl, `${moduleAddress}::${moduleName}`);
+
+    // Load the calling type arguments into the loader.
+    if (input.typeArguments !== undefined) {
+      await Promise.all(input.typeArguments.map((typeTag) => this.builder.load_type_tag(nodeUrl, typeTag.toString())));
+    }
+    const typeArguments = standardizeTypeTags(input.typeArguments);
+    const functionAbi = await fetchMoveFunctionAbi(moduleAddress, moduleName, functionName, this.config);
+    // Check the type argument count against the ABI
+    if (typeArguments.length !== functionAbi.typeParameters.length) {
+      throw new Error(
+        `Type argument count mismatch, expected ${functionAbi.typeParameters.length}, received ${typeArguments.length}`,
+      );
+    }
+
+    const functionArguments: CallArgument[] = input.functionArguments.map((arg, i) =>
+      convertCallArgument(arg, functionName, functionAbi, i, typeArguments),
+    );
+
+    return this.builder.add_batched_call(
+      `${moduleAddress}::${moduleName}`,
+      functionName,
+      typeArguments.map((arg) => arg.toString()),
+      functionArguments,
+    );
+  }
+
+  build(): Uint8Array {
+    return this.builder.generate_batched_calls(true);
+  }
+}

package/src/transactions/transactionBuilder/helpers.ts

@@ -18,6 +18,8 @@ import { MoveFunction, MoveFunctionId } from "../../types";
  *
  * @param arg - The argument to check, which can be of various types.
  * @returns A boolean indicating whether the argument is a boolean.
+ * @group Implementation
+ * @category Transactions
  */
 export function isBool(arg: SimpleEntryFunctionArgumentTypes): arg is boolean {
   return typeof arg === "boolean";
@@ -28,6 +30,8 @@ export function isBool(arg: SimpleEntryFunctionArgumentTypes): arg is boolean {
  *
  * @param arg - The value to be checked for string type.
  * @returns A boolean indicating whether the argument is a string.
+ * @group Implementation
+ * @category Transactions
  */
 export function isString(arg: any): arg is string {
   return typeof arg === "string";
@@ -38,6 +42,8 @@ export function isString(arg: any): arg is string {
  *
  * @param arg - The argument to check, which can be of various types.
  * @returns A boolean indicating whether the argument is a number.
+ * @group Implementation
+ * @category Transactions
  */
 export function isNumber(arg: SimpleEntryFunctionArgumentTypes): arg is number {
   return typeof arg === "number";
@@ -50,6 +56,8 @@ export function isNumber(arg: SimpleEntryFunctionArgumentTypes): arg is number {
  *
  * @param arg - The input value to be converted. This can be a number, a string representing a number, or any other type.
  * @returns Returns the converted number if the input is valid; otherwise, it returns undefined.
+ * @group Implementation
+ * @category Transactions
  */
 export function convertNumber(arg: SimpleEntryFunctionArgumentTypes): number | undefined {
   if (isNumber(arg)) {
@@ -66,6 +74,8 @@ export function convertNumber(arg: SimpleEntryFunctionArgumentTypes): number | u
  * Determines if the provided argument is a large number, which can be a number, bigint, or string representation of a number.
  *
  * @param arg - The argument to check, which can be of type number, bigint, or string.
+ * @group Implementation
+ * @category Transactions
  */
 export function isLargeNumber(arg: SimpleEntryFunctionArgumentTypes): arg is number | bigint | string {
   return typeof arg === "number" || typeof arg === "bigint" || typeof arg === "string";
@@ -76,6 +86,8 @@ export function isLargeNumber(arg: SimpleEntryFunctionArgumentTypes): arg is num
  *
  * @param arg - The argument to check for emptiness.
  * @returns A boolean indicating whether the argument is empty.
+ * @group Implementation
+ * @category Transactions
  */
 export function isEmptyOption(arg: SimpleEntryFunctionArgumentTypes): arg is null | undefined {
   return arg === null || arg === undefined;
@@ -86,6 +98,8 @@ export function isEmptyOption(arg: SimpleEntryFunctionArgumentTypes): arg is nul
  * This function helps validate that the argument conforms to the expected types for entry function parameters.
  *
  * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+ * @group Implementation
+ * @category Transactions
  */
 export function isEncodedEntryFunctionArgument(
   arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes,
@@ -95,6 +109,8 @@ export function isEncodedEntryFunctionArgument(
      * Determines if the provided argument is an instance of the Bool class.
      *
      * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsBool(arg) ||
     /**
@@ -102,12 +118,16 @@ export function isEncodedEntryFunctionArgument(
      * This function helps validate the type of the argument passed to ensure it is a U8 type.
      *
      * @param arg - The argument to be checked, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsU8(arg) ||
     /**
      * Determines if the provided argument is an instance of U16.
      *
      * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsU16(arg) ||
     /**
@@ -115,6 +135,8 @@ export function isEncodedEntryFunctionArgument(
      *
      * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
      * @returns A boolean indicating whether the argument is a U32 instance.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsU32(arg) ||
     /**
@@ -122,6 +144,8 @@ export function isEncodedEntryFunctionArgument(
      * This function helps validate that the argument conforms to the expected U64 type.
      *
      * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsU64(arg) ||
     /**
@@ -129,6 +153,8 @@ export function isEncodedEntryFunctionArgument(
      * This function helps validate the type of the argument passed to ensure it is a U128 type.
      *
      * @param arg - The argument to be checked, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsU128(arg) ||
     /**
@@ -136,6 +162,8 @@ export function isEncodedEntryFunctionArgument(
      *
      * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
      * @returns A boolean indicating whether the argument is a U256 instance.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsU256(arg) ||
     /**
@@ -143,12 +171,16 @@ export function isEncodedEntryFunctionArgument(
      * This function helps validate whether a given input corresponds to a valid BCS address type.
      *
      * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsAddress(arg) ||
     /**
      * Determine if the provided argument is an instance of MoveString.
      *
      * @param arg - The argument to check, which can be of types EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsString(arg) ||
     /**
@@ -156,51 +188,83 @@ export function isEncodedEntryFunctionArgument(
      * This function helps to validate the type of the argument being passed.
      *
      * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @group Implementation
+     * @category Transactions
      */
     isBcsFixedBytes(arg) ||
     arg instanceof MoveVector ||
     arg instanceof MoveOption
   );
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsBool(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is Bool {
   return arg instanceof Bool;
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsAddress(
   arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes,
 ): arg is AccountAddress {
   return arg instanceof AccountAddress;
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsString(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is MoveString {
   return arg instanceof MoveString;
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsFixedBytes(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is FixedBytes {
   return arg instanceof FixedBytes;
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsU8(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U8 {
   return arg instanceof U8;
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsU16(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U16 {
   return arg instanceof U16;
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsU32(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U32 {
   return arg instanceof U32;
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsU64(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U64 {
   return arg instanceof U64;
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsU128(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U128 {
   return arg instanceof U128;
 }
-
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export function isBcsU256(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U256 {
   return arg instanceof U256;
 }
@@ -212,6 +276,8 @@ export function isBcsU256(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionA
  * @param arg.bytecode - The bytecode of the script, present if the input is script data.
  * @param arg.function - The function associated with the transaction, which is relevant for standard payloads.
  * @param arg.args - The arguments for the function, applicable in the context of standard payloads.
+ * @group Implementation
+ * @category Transactions
  */
 export function isScriptDataInput(
   arg: InputGenerateTransactionPayloadDataWithRemoteABI | InputGenerateTransactionPayloadData,
@@ -225,6 +291,8 @@ export function isScriptDataInput(
  *
  * @param expectedType - The type that was expected for the argument.
  * @param position - The position of the argument that caused the type mismatch.
+ * @group Implementation
+ * @category Transactions
  */
 export function throwTypeMismatch(expectedType: string, position: number) {
   throw new Error(`Type mismatch for argument ${position}, expected '${expectedType}'`);
@@ -239,6 +307,8 @@ export function throwTypeMismatch(expectedType: string, position: number) {
  *
  * @param functionAbi - The ABI of the function to analyze.
  * @returns The index of the first non-signer argument, or the length of the parameters array if none are found.
+ * @group Implementation
+ * @category Transactions
  */
 export function findFirstNonSignerArg(functionAbi: MoveFunction): number {
   const index = functionAbi.params.findIndex((param) => param !== "signer" && param !== "&signer");
@@ -255,6 +325,8 @@ export function findFirstNonSignerArg(functionAbi: MoveFunction): number {
  * @param functionArg - The function identifier string in the format "moduleAddress::moduleName::functionName".
  * @returns An object containing the module address, module name, and function name.
  * @throws Error if the function identifier does not contain exactly three parts.
+ * @group Implementation
+ * @category Transactions
  */
 export function getFunctionParts(functionArg: MoveFunctionId) {
   const funcNameParts = functionArg.split("::");

package/src/transactions/transactionBuilder/remoteAbi.ts

@@ -45,7 +45,7 @@ import {
   throwTypeMismatch,
   convertNumber,
 } from "./helpers";
-import { MoveFunction } from "../../types";
+import { CallArgument, MoveFunction } from "../../types";
 
 const TEXT_ENCODER = new TextEncoder();
 
@@ -54,6 +54,8 @@ const TEXT_ENCODER = new TextEncoder();
  *
  * @param typeArguments - An optional array of type arguments that may include string representations.
  * @returns An array of TypeTag objects derived from the provided type arguments.
+ * @group Implementation
+ * @category Transactions
  */
 export function standardizeTypeTags(typeArguments?: Array<TypeArgument>): Array<TypeTag> {
   return (
@@ -75,6 +77,8 @@ export function standardizeTypeTags(typeArguments?: Array<TypeArgument>): Array<
  * @param moduleName - The name of the module containing the function.
  * @param functionName - The name of the function whose ABI is to be fetched.
  * @param aptosConfig - The configuration settings for Aptos.
+ * @group Implementation
+ * @category Transactions
  */
 export async function fetchFunctionAbi(
   moduleAddress: string,
@@ -92,6 +96,34 @@ export async function fetchFunctionAbi(
   return undefined;
 }
 
+/**
+ * Fetches a function ABI from the on-chain module ABI.  It doesn't validate whether it's a view or entry function.
+ * @param moduleAddress
+ * @param moduleName
+ * @param functionName
+ * @param aptosConfig
+ */
+export async function fetchMoveFunctionAbi(
+  moduleAddress: string,
+  moduleName: string,
+  functionName: string,
+  aptosConfig: AptosConfig,
+): Promise<FunctionABI> {
+  const functionAbi = await fetchFunctionAbi(moduleAddress, moduleName, functionName, aptosConfig);
+  if (!functionAbi) {
+    throw new Error(`Could not find function ABI for '${moduleAddress}::${moduleName}::${functionName}'`);
+  }
+  const params: TypeTag[] = [];
+  for (let i = 0; i < functionAbi.params.length; i += 1) {
+    params.push(parseTypeTag(functionAbi.params[i], { allowGenerics: true }));
+  }
+
+  return {
+    typeParameters: functionAbi.generic_type_params,
+    parameters: params,
+  };
+}
+
 /**
  * Fetches the ABI for an entry function from the specified module address.
  * This function validates if the ABI corresponds to an entry function and retrieves its parameters.
@@ -102,6 +134,8 @@ export async function fetchFunctionAbi(
  * @param aptosConfig - The configuration settings for Aptos.
  * @returns An object containing the number of signers, type parameters, and function parameters.
  * @throws Error if the ABI cannot be found or if the function is not an entry function.
+ * @group Implementation
+ * @category Transactions
  */
 export async function fetchEntryFunctionAbi(
   moduleAddress: string,
@@ -145,6 +179,8 @@ export async function fetchEntryFunctionAbi(
  * @param aptosConfig - The configuration settings for Aptos.
  * @returns An object containing the type parameters, parameters, and return types of the view function.
  * @throws Error if the ABI cannot be found or if the function is not a view function.
+ * @group Implementation
+ * @category Transactions
  */
 export async function fetchViewFunctionAbi(
   moduleAddress: string,
@@ -183,6 +219,32 @@ export async function fetchViewFunctionAbi(
   };
 }
 
+/**
+ * Converts a entry function argument into CallArgument, if necessary.
+ * This function checks the provided argument against the expected parameter type and converts it accordingly.
+ *
+ * @param functionName - The name of the function for which the argument is being converted.
+ * @param functionAbi - The ABI (Application Binary Interface) of the function, which defines its parameters.
+ * @param argument - The argument to be converted, which can be of various types. If the argument is already
+ *                   CallArgument returned from TransactionComposer it would be returned immediately.
+ * @param position - The index of the argument in the function's parameter list.
+ * @param genericTypeParams - An array of type tags for any generic type parameters.
+ */
+export function convertCallArgument(
+  argument: CallArgument | EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes,
+  functionName: string,
+  functionAbi: FunctionABI,
+  position: number,
+  genericTypeParams: Array<TypeTag>,
+): CallArgument {
+  if (argument instanceof CallArgument) {
+    return argument;
+  }
+  return CallArgument.newBytes(
+    convertArgument(functionName, functionAbi, argument, position, genericTypeParams).bcsToBytes(),
+  );
+}
+
 /**
  * Converts a non-BCS encoded argument into BCS encoded, if necessary.
  * This function checks the provided argument against the expected parameter type and converts it accordingly.
@@ -192,6 +254,8 @@ export async function fetchViewFunctionAbi(
  * @param arg - The argument to be converted, which can be of various types.
  * @param position - The index of the argument in the function's parameter list.
  * @param genericTypeParams - An array of type tags for any generic type parameters.
+ * @group Implementation
+ * @category Transactions
  */
 export function convertArgument(
   functionName: string,
@@ -217,6 +281,8 @@ export function convertArgument(
  * @param param - The expected type tag for the argument.
  * @param position - The position of the argument in the function call.
  * @param genericTypeParams - An array of generic type parameters that may be used for conversion.
+ * @group Implementation
+ * @category Transactions
  */
 export function checkOrConvertArgument(
   arg: SimpleEntryFunctionArgumentTypes | EntryFunctionArgumentTypes,
@@ -235,6 +301,8 @@ export function checkOrConvertArgument(
      * @param typeArgs - The expected type arguments.
      * @param arg - The argument to be checked.
      * @param position - The position of the argument in the context of the check.
+     * @group Implementation
+     * @category Transactions
      */
     checkType(param, arg, position);
     return arg;
@@ -253,6 +321,8 @@ export function checkOrConvertArgument(
  * @param param - The type tag that defines the expected type of the argument.
  * @param position - The position of the argument in the function call, used for error reporting.
  * @param genericTypeParams - An array of type tags for generic type parameters, used when the parameter type is generic.
+ * @group Implementation
+ * @category Transactions
  */
 function parseArg(
   arg: SimpleEntryFunctionArgumentTypes,
@@ -274,6 +344,8 @@ function parseArg(
      *
      * @param moveOption - The name of the move option that caused the type mismatch.
      * @param position - The position where the error occurred.
+     * @group Implementation
+     * @category Transactions
      */
     throwTypeMismatch("boolean", position);
   }
@@ -425,6 +497,8 @@ function parseArg(
  * @param param
  * @param arg
  * @param position
+ * @group Implementation
+ * @category Transactions
  */
 function checkType(param: TypeTag, arg: EntryFunctionArgumentTypes, position: number) {
   if (param.isBool()) {

package/src/transactions/transactionBuilder/signingMessage.ts

@@ -3,6 +3,8 @@
 
 /**
  * This file handles the generation of the signing message.
+ * @group Implementation
+ * @category Transactions
  */
 import { sha3_256 as sha3Hash } from "@noble/hashes/sha3";
 import { RAW_TRANSACTION_SALT, RAW_TRANSACTION_WITH_DATA_SALT } from "../../utils/const";
@@ -21,6 +23,8 @@ import { Serializable } from "../../bcs";
  *   - rawTransaction - The raw transaction data.
  *
  * @returns FeePayerRawTransaction | MultiAgentRawTransaction | RawTransaction
+ * @group Implementation
+ * @category Transactions
  */
 export function deriveTransactionType(transaction: AnyRawTransaction): AnyRawTransactionInstance {
   if (transaction.feePayerAddress) {
@@ -45,6 +49,8 @@ export function deriveTransactionType(transaction: AnyRawTransaction): AnyRawTra
  * @param domainSeparator - A domain separator that starts with 'APTOS::'.
  *
  * @returns The Uint8Array of the signing message.
+ * @group Implementation
+ * @category Transactions
  */
 export function generateSigningMessage(bytes: Uint8Array, domainSeparator: string): Uint8Array {
   const hash = sha3Hash.create();
@@ -76,6 +82,8 @@ export function generateSigningMessage(bytes: Uint8Array, domainSeparator: strin
  * @param serializable - An object that has a BCS serialized form.
  *
  * @returns The Uint8Array of the signing message.
+ * @group Implementation
+ * @category Transactions
  */
 export function generateSigningMessageForSerializable(serializable: Serializable): Uint8Array {
   return generateSigningMessage(serializable.bcsToBytes(), `APTOS::${serializable.constructor.name}`);
@@ -88,6 +96,8 @@ export function generateSigningMessageForSerializable(serializable: Serializable
  * @param transaction - A transaction that is to be signed, which can include a fee payer address or secondary signer addresses.
  *
  * @returns The Uint8Array of the signing message.
+ * @group Implementation
+ * @category Transactions
  */
 export function generateSigningMessageForTransaction(transaction: AnyRawTransaction): Uint8Array {
   const rawTxn = deriveTransactionType(transaction);