[abi] Allow passing module ABI, which is the same as from surf

Author: gregnazario

CHANGELOG.md

@@ -12,6 +12,7 @@ All notable changes to the Aptos TypeScript SDK will be captured in this file. T
 - Add support for skipping struct type tag validation.
 - Add support for known enum structs: DelegationKey and RateLimiter.
 - Deprecated `fetchMoveFunctionAbi` and `convertCallArgument`
+- Allow passing in `MoveModule` as ABI for a function, rather than the parsed ABI
 
 # 1.35.0 (2025-02-11)
 

src/transactions/transactionBuilder/remoteAbi.ts

@@ -152,7 +152,24 @@ export async function fetchEntryFunctionAbi(
   functionName: string,
   aptosConfig: AptosConfig,
 ): Promise<EntryFunctionABI> {
-  const functionAbi = await fetchFunctionAbi(moduleAddress, moduleName, functionName, aptosConfig);
+  const moduleAbi = await fetchModuleAbi(moduleAddress, moduleName, aptosConfig);
+  if (!moduleAbi) throw new Error(`Could not find module ABI for '${moduleAddress}::${moduleName}'`);
+  return parseEntryFunctionAbi({
+    moduleAbi,
+    moduleAddress,
+    moduleName,
+    functionName,
+  });
+}
+
+export function parseEntryFunctionAbi(args: {
+  moduleAbi: MoveModule;
+  moduleAddress: string;
+  moduleName: string;
+  functionName: string;
+}): EntryFunctionABI {
+  const { moduleAbi, moduleAddress, moduleName, functionName } = args;
+  const functionAbi = moduleAbi.exposed_functions.find((func) => func.name === functionName);
 
   // If there's no ABI, then the function is invalid
   if (!functionAbi) {
@@ -197,7 +214,24 @@ export async function fetchViewFunctionAbi(
   functionName: string,
   aptosConfig: AptosConfig,
 ): Promise<ViewFunctionABI> {
-  const functionAbi = await fetchFunctionAbi(moduleAddress, moduleName, functionName, aptosConfig);
+  const moduleAbi = await fetchModuleAbi(moduleAddress, moduleName, aptosConfig);
+  if (!moduleAbi) throw new Error(`Could not find module ABI for '${moduleAddress}::${moduleName}'`);
+  return parseViewFunctionAbi({
+    moduleAbi,
+    moduleAddress,
+    moduleName,
+    functionName,
+  });
+}
+
+export function parseViewFunctionAbi(args: {
+  moduleAbi: MoveModule;
+  moduleAddress: string;
+  moduleName: string;
+  functionName: string;
+}): ViewFunctionABI {
+  const { moduleAbi, moduleAddress, moduleName, functionName } = args;
+  const functionAbi = moduleAbi.exposed_functions.find((func) => func.name === functionName);
 
   // If there's no ABI, then the function is invalid
   if (!functionAbi) {

src/transactions/transactionBuilder/transactionBuilder.ts

@@ -76,13 +76,23 @@ import {
   InputViewFunctionDataWithRemoteABI,
   InputViewFunctionDataWithABI,
   FunctionABI,
+  ViewFunctionABI,
+  EntryFunctionABI,
 } from "../types";
-import { convertArgument, fetchEntryFunctionAbi, fetchViewFunctionAbi, standardizeTypeTags } from "./remoteAbi";
+import {
+  convertArgument,
+  fetchEntryFunctionAbi,
+  fetchViewFunctionAbi,
+  parseEntryFunctionAbi,
+  parseViewFunctionAbi,
+  standardizeTypeTags,
+} from "./remoteAbi";
 import { memoizeAsync } from "../../utils/memoize";
 import { isScriptDataInput } from "./helpers";
 import { SimpleTransaction } from "../instances/simpleTransaction";
 import { MultiAgentTransaction } from "../instances/multiAgentTransaction";
 import { getFunctionParts } from "../../utils/helpers";
+import { MoveModule } from "../../types";
 
 /**
  * Builds a transaction payload based on the provided arguments and returns a transaction payload.
@@ -145,6 +155,7 @@ export async function generateTransactionPayload(
     aptosConfig: args.aptosConfig,
     abi: args.abi,
     fetch: fetchEntryFunctionAbi,
+    parse: parseEntryFunctionAbi,
   });
 
   // Fill in the ABI
@@ -179,9 +190,16 @@ export function generateTransactionPayloadWithABI(args: InputMultiSigDataWithABI
 export function generateTransactionPayloadWithABI(
   args: InputGenerateTransactionPayloadDataWithABI,
 ): AnyTransactionPayloadInstance {
-  const functionAbi = args.abi;
   const { moduleAddress, moduleName, functionName } = getFunctionParts(args.function);
 
+  // Parse the ABI if it's the whole module (aka surf)
+  let functionAbi: EntryFunctionABI | undefined;
+  if ("exposed_functions" in args.abi) {
+    functionAbi = parseEntryFunctionAbi({ moduleAbi: args.abi, moduleAddress, moduleName, functionName });
+  } else {
+    functionAbi = args.abi;
+  }
+
   // Ensure that all type arguments are typed properly
   const typeArguments = standardizeTypeTags(args.typeArguments);
 
@@ -263,6 +281,7 @@ export async function generateViewFunctionPayload(args: InputViewFunctionDataWit
     aptosConfig: args.aptosConfig,
     abi: args.abi,
     fetch: fetchViewFunctionAbi,
+    parse: parseViewFunctionAbi,
   });
 
   // Fill in the ABI
@@ -286,9 +305,16 @@ export async function generateViewFunctionPayload(args: InputViewFunctionDataWit
  * @category Transactions
  */
 export function generateViewFunctionPayloadWithABI(args: InputViewFunctionDataWithABI): EntryFunction {
-  const functionAbi = args.abi;
   const { moduleAddress, moduleName, functionName } = getFunctionParts(args.function);
 
+  // Parse the ABI if it's the whole module (aka surf)
+  let functionAbi: ViewFunctionABI | undefined;
+  if ("exposed_functions" in args.abi) {
+    functionAbi = parseViewFunctionAbi({ moduleAbi: args.abi, moduleAddress, moduleName, functionName });
+  } else {
+    functionAbi = args.abi;
+  }
+
   // Ensure that all type arguments are typed properly
   const typeArguments = standardizeTypeTags(args.typeArguments);
 
@@ -771,6 +797,7 @@ export function generateUserTransactionHash(args: InputSubmitTransactionData): s
  * @param aptosConfig - Configuration settings for Aptos.
  * @param abi - An optional ABI to use if already available.
  * @param fetch - A function to fetch the ABI if it is not provided.
+ * @param parse - A function to parse the ABI if as MoveModule ABI is provided.
  * @group Implementation
  * @category Transactions
  */
@@ -782,17 +809,23 @@ async function fetchAbi<T extends FunctionABI>({
   aptosConfig,
   abi,
   fetch,
+  parse,
 }: {
   key: string;
   moduleAddress: string;
   moduleName: string;
   functionName: string;
   aptosConfig: AptosConfig;
-  abi?: T;
+  abi?: T | MoveModule;
   fetch: (moduleAddress: string, moduleName: string, functionName: string, aptosConfig: AptosConfig) => Promise<T>;
+  parse: (args: { moduleAddress: string; moduleName: string; functionName: string; moduleAbi: MoveModule }) => T;
 }): Promise<T> {
   if (abi !== undefined) {
-    return abi;
+    if ("exposed_functions" in abi) {
+      return parse({ moduleAddress, moduleName, functionName, moduleAbi: abi });
+    } else {
+      return abi;
+    }
   }
 
   // We fetch the entry function ABI, and then pretend that we already had the ABI

src/transactions/types.ts

@@ -16,7 +16,15 @@ import {
   TransactionPayloadMultiSig,
   TransactionPayloadScript,
 } from "./instances";
-import { AnyNumber, HexInput, MoveFunctionGenericTypeParam, MoveFunctionId, MoveStructId, MoveValue } from "../types";
+import {
+  AnyNumber,
+  HexInput,
+  MoveFunctionGenericTypeParam,
+  MoveFunctionId,
+  MoveModule,
+  MoveStructId,
+  MoveValue,
+} from "../types";
 import { TypeTag } from "./typeTag";
 import { AccountAuthenticator } from "./authenticator/account";
 import { SimpleTransaction } from "./instances/simpleTransaction";
@@ -159,7 +167,7 @@ export type InputEntryFunctionData = {
   function: MoveFunctionId;
   typeArguments?: Array<TypeArgument>;
   functionArguments: Array<EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes>;
-  abi?: EntryFunctionABI;
+  abi?: EntryFunctionABI | MoveModule;
 };
 
 /**
@@ -175,7 +183,7 @@ export type InputGenerateTransactionPayloadDataWithABI = InputEntryFunctionDataW
  * @category Transactions
  */
 export type InputEntryFunctionDataWithABI = Omit<InputEntryFunctionData, "abi"> & {
-  abi: EntryFunctionABI;
+  abi: EntryFunctionABI | MoveModule;
 };
 
 /**
@@ -241,7 +249,7 @@ export type InputViewFunctionData = {
   function: MoveFunctionId;
   typeArguments?: Array<TypeArgument>;
   functionArguments?: Array<EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes>;
-  abi?: ViewFunctionABI;
+  abi?: ViewFunctionABI | MoveModule;
 };
 
 /**
@@ -278,7 +286,7 @@ export type InputViewFunctionDataWithRemoteABI = InputViewFunctionData & { aptos
  * @group Implementation
  * @category Transactions
  */
-export type InputViewFunctionDataWithABI = InputViewFunctionData & { abi: ViewFunctionABI };
+export type InputViewFunctionDataWithABI = InputViewFunctionData & { abi: ViewFunctionABI | MoveModule };
 
 /**
  * Data needed for a generic function ABI, applicable to both view and entry functions.

tests/e2e/transaction/transactionBuilder.test.ts

@@ -3,29 +3,32 @@
 
 import {
   Account,
-  Deserializer,
-  U64,
   AccountAddress,
-  EntryFunctionABI,
-  parseTypeTag,
   AccountAuthenticator,
   AccountAuthenticatorEd25519,
-  FeePayerRawTransaction,
-  MultiAgentRawTransaction,
-  RawTransaction,
-  TransactionPayloadEntryFunction,
-  TransactionPayloadMultiSig,
-  TransactionPayloadScript,
   buildTransaction,
   deriveTransactionType,
+  Deserializer,
+  EntryFunctionABI,
+  FeePayerRawTransaction,
   generateRawTransaction,
   generateSignedTransaction,
   generateSignedTransactionForSimulation,
   generateTransactionPayload,
   generateTransactionPayloadWithABI,
-  SignedTransaction,
   generateUserTransactionHash,
   KeylessPublicKey,
+  MoveAbility,
+  MoveFunctionVisibility,
+  MoveModule,
+  MultiAgentRawTransaction,
+  parseTypeTag,
+  RawTransaction,
+  SignedTransaction,
+  TransactionPayloadEntryFunction,
+  TransactionPayloadMultiSig,
+  TransactionPayloadScript,
+  U64,
 } from "../../../src";
 import { FUND_AMOUNT, longTestTimeout } from "../../unit/helper";
 import { getAptosClient } from "../helper";
@@ -104,7 +107,24 @@ describe("transaction builder", () => {
   describe("generate transaction payload with preset ABI", () => {
     const functionAbi: EntryFunctionABI = {
       typeParameters: [],
-      parameters: [parseTypeTag("address"), parseTypeTag("0x1::object::Object<T0>", { allowGenerics: true })],
+      parameters: [parseTypeTag("address"), parseTypeTag("0x1::object::ObjectCore")],
+    };
+    const moduleAbi: MoveModule = {
+      address: contractPublisherAccount.accountAddress.toString(),
+      name: "transfer",
+      friends: [],
+      structs: [],
+      exposed_functions: [
+        {
+          name: "transfer",
+          visibility: MoveFunctionVisibility.PUBLIC,
+          is_entry: true,
+          is_view: false,
+          generic_type_params: [],
+          params: ["&signer", "address", "0x1::object::Object<0x1::object::ObjectCore>"],
+          return: [],
+        },
+      ],
     };
 
     test("it generates a multi sig transaction payload", async () => {
@@ -138,6 +158,21 @@ describe("transaction builder", () => {
       });
       expect(payload2 instanceof TransactionPayloadEntryFunction).toBeTruthy();
     });
+
+    test("it generates an entry function transaction payload with mixed arguments and a module / surf ABI", async () => {
+      const payload = generateTransactionPayloadWithABI({
+        function: `${contractPublisherAccount.accountAddress}::transfer::transfer`,
+        functionArguments: [AccountAddress.ONE, "0x1"],
+        abi: moduleAbi,
+      });
+      expect(payload instanceof TransactionPayloadEntryFunction).toBeTruthy();
+      const payload2 = generateTransactionPayloadWithABI({
+        function: `${contractPublisherAccount.accountAddress}::transfer::transfer`,
+        functionArguments: ["0x1", AccountAddress.ONE],
+        abi: moduleAbi,
+      });
+      expect(payload2 instanceof TransactionPayloadEntryFunction).toBeTruthy();
+    });
   });
   describe("generate raw transaction", () => {
     test("it generates a raw transaction with script payload", async () => {

tests/unit/remoteAbi.test.ts

@@ -126,6 +126,18 @@ describe("Remote ABI", () => {
       expect(checkOrConvertArgument(null, parseTypeTag("0x1::option::Option<u8>"), 0, [])).toEqual(
         new MoveOption<U8>(),
       );
+      expect(checkOrConvertArgument(undefined, parseTypeTag("0x1::option::Option<signer>"), 0, [])).toEqual(
+        new MoveOption<U8>(),
+      );
+      expect(checkOrConvertArgument(null, parseTypeTag("0x1::option::Option<signer>"), 0, [])).toEqual(
+        new MoveOption<U8>(),
+      );
+      expect(checkOrConvertArgument(undefined, parseTypeTag("0x1::option::Option<&signer>"), 0, [])).toEqual(
+        new MoveOption<U8>(),
+      );
+      expect(checkOrConvertArgument(null, parseTypeTag("0x1::option::Option<&signer>"), 0, [])).toEqual(
+        new MoveOption<U8>(),
+      );
 
       // Objects are account addresses, and it doesn't matter about the type used
       expect(checkOrConvertArgument("0x1", parseTypeTag("0x1::object::Object<0x1::string::String>"), 0, [])).toEqual(