@aptos-labs/ts-sdk 1.36.0-zeta.0 → 1.37.0

package/src/core/crypto/federatedKeyless.ts

@@ -15,6 +15,7 @@ import {
   verifyKeylessSignatureWithJwkAndConfig,
 } from "./keyless";
 import { AptosConfig } from "../../api";
+import { Signature } from "..";
 
 /**
  * Represents the FederatedKeylessPublicKey public key
@@ -76,11 +77,16 @@ export class FederatedKeylessPublicKey extends AccountPublicKey {
    */
   verifySignature(args: {
     message: HexInput;
-    signature: KeylessSignature;
+    signature: Signature;
     jwk: MoveJWK;
     keylessConfig: KeylessConfiguration;
   }): boolean {
-    return verifyKeylessSignatureWithJwkAndConfig({ ...args, publicKey: this });
+    try {
+      verifyKeylessSignatureWithJwkAndConfig({ ...args, publicKey: this });
+      return true;
+    } catch (error) {
+      return false;
+    }
   }
 
   serialize(serializer: Serializer): void {

package/src/core/crypto/keyless.ts

@@ -171,29 +171,19 @@ export class KeylessPublicKey extends AccountPublicKey {
    */
   verifySignature(args: {
     message: HexInput;
-    signature: KeylessSignature;
+    signature: Signature;
     jwk: MoveJWK;
     keylessConfig: KeylessConfiguration;
   }): boolean {
-    return verifyKeylessSignatureWithJwkAndConfig({ ...args, publicKey: this });
-  }
-
-  /**
-   * Serializes the current instance into a format suitable for transmission or storage.
-   * This function ensures that all relevant fields are properly serialized, including the proof and optional fields.
-   *
-   * @param serializer - The serializer instance used to perform the serialization.
-   * @param serializer.proof - The proof to be serialized.
-   * @param serializer.expHorizonSecs - The expiration horizon in seconds.
-   * @param serializer.extraField - An optional additional field for serialization.
-   * @param serializer.overrideAudVal - An optional override value for auditing.
-   * @param serializer.trainingWheelsSignature - An optional signature for training wheels.
-   * @group Implementation
-   * @category Serialization
-   */
-  serialize(serializer: Serializer): void {
-    serializer.serializeStr(this.iss);
-    serializer.serializeBytes(this.idCommitment);
+    try {
+      verifyKeylessSignatureWithJwkAndConfig({ ...args, publicKey: this });
+      return true;
+    } catch (error) {
+      if (error instanceof KeylessError) {
+        return false;
+      }
+      throw error;
+    }
   }
 
   /**
@@ -209,7 +199,7 @@ export class KeylessPublicKey extends AccountPublicKey {
   async verifySignatureAsync(args: {
     aptosConfig: AptosConfig;
     message: HexInput;
-    signature: KeylessSignature;
+    signature: Signature;
     options?: { throwErrorWithReason?: boolean };
   }): Promise<boolean> {
     return verifyKeylessSignature({
@@ -218,6 +208,24 @@ export class KeylessPublicKey extends AccountPublicKey {
     });
   }
 
+  /**
+   * Serializes the current instance into a format suitable for transmission or storage.
+   * This function ensures that all relevant fields are properly serialized, including the proof and optional fields.
+   *
+   * @param serializer - The serializer instance used to perform the serialization.
+   * @param serializer.proof - The proof to be serialized.
+   * @param serializer.expHorizonSecs - The expiration horizon in seconds.
+   * @param serializer.extraField - An optional additional field for serialization.
+   * @param serializer.overrideAudVal - An optional override value for auditing.
+   * @param serializer.trainingWheelsSignature - An optional signature for training wheels.
+   * @group Implementation
+   * @category Serialization
+   */
+  serialize(serializer: Serializer): void {
+    serializer.serializeStr(this.iss);
+    serializer.serializeBytes(this.idCommitment);
+  }
+
   /**
    * Deserializes a ZeroKnowledgeSig object from the provided deserializer.
    * This function allows you to reconstruct a ZeroKnowledgeSig instance from its serialized form.
@@ -332,7 +340,7 @@ export async function verifyKeylessSignature(args: {
   publicKey: KeylessPublicKey | FederatedKeylessPublicKey;
   aptosConfig: AptosConfig;
   message: HexInput;
-  signature: KeylessSignature;
+  signature: Signature;
   keylessConfig?: KeylessConfiguration;
   jwk?: MoveJWK;
   options?: { throwErrorWithReason?: boolean };
@@ -342,12 +350,24 @@ export async function verifyKeylessSignature(args: {
     publicKey,
     message,
     signature,
-    jwk = await fetchJWK({ aptosConfig: args.aptosConfig, publicKey: args.publicKey, kid: signature.getJwkKid() }),
+    jwk,
     keylessConfig = await getKeylessConfig({ aptosConfig }),
     options,
   } = args;
   try {
-    publicKey.verifySignature({ message, signature, jwk, keylessConfig });
+    if (!(signature instanceof KeylessSignature)) {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.SIGNATURE_TYPE_INVALID,
+        details: "Not a keyless signature",
+      });
+    }
+    verifyKeylessSignatureWithJwkAndConfig({
+      message,
+      publicKey,
+      signature,
+      jwk: jwk ? jwk : await fetchJWK({ aptosConfig, publicKey, kid: signature.getJwkKid() }),
+      keylessConfig,
+    });
     return true;
   } catch (error) {
     if (options?.throwErrorWithReason) {
@@ -371,12 +391,18 @@ export async function verifyKeylessSignature(args: {
 export function verifyKeylessSignatureWithJwkAndConfig(args: {
   publicKey: KeylessPublicKey | FederatedKeylessPublicKey;
   message: HexInput;
-  signature: KeylessSignature;
+  signature: Signature;
   keylessConfig: KeylessConfiguration;
   jwk: MoveJWK;
-}): boolean {
+}): void {
   const { publicKey, message, signature, keylessConfig, jwk } = args;
   const { verificationKey, maxExpHorizonSecs, trainingWheelsPubkey } = keylessConfig;
+  if (!(signature instanceof KeylessSignature)) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.SIGNATURE_TYPE_INVALID,
+      details: "Not a keyless signature",
+    });
+  }
   if (!(signature.ephemeralCertificate.signature instanceof ZeroKnowledgeSig)) {
     throw KeylessError.fromErrorType({
       type: KeylessErrorType.SIGNATURE_TYPE_INVALID,
@@ -431,7 +457,6 @@ export function verifyKeylessSignatureWithJwkAndConfig(args: {
       });
     }
   }
-  return true;
 }
 
 /**
@@ -1326,39 +1351,47 @@ export class Groth16VerificationKey {
   verifyProof(args: { publicInputsHash: bigint; groth16Proof: Groth16Zkp }): boolean {
     const { publicInputsHash, groth16Proof } = args;
 
-    // Get proof points
-    const proofA = groth16Proof.a.toProjectivePoint();
-    const proofB = groth16Proof.b.toProjectivePoint();
-    const proofC = groth16Proof.c.toProjectivePoint();
-
-    // Get verification key points
-    const vkAlpha1 = this.alphaG1.toProjectivePoint();
-    const vkBeta2 = this.betaG2.toProjectivePoint();
-    const vkGamma2 = this.gammaG2.toProjectivePoint();
-    const vkDelta2 = this.deltaG2.toProjectivePoint();
-    const vkIC = this.gammaAbcG1.map((g1) => g1.toProjectivePoint());
-
-    const { Fp12 } = bn254.fields;
-
-    // Check that the following pairing equation holds:
-    // e(A_1, B_2) = e(\alpha_1, \beta_2) + e(\ic_0 + public_inputs_hash \ic_1, \gamma_2) + e(C_1, \delta_2)
-    // Where A_1, B_2, C_1 are the proof points and \alpha_1, \beta_2, \gamma_2, \delta_2, \ic_0, \ic_1
-    // are the verification key points
-
-    // \ic_0 + public_inputs_hash \ic_1
-    let accum = vkIC[0].add(vkIC[1].multiply(publicInputsHash));
-    // e(\ic_0 + public_inputs_hash \ic_1, \gamma_2)
-    const pairingAccumGamma = bn254.pairing(accum, vkGamma2);
-    // e(A_1, B_2)
-    const pairingAB = bn254.pairing(proofA, proofB);
-    // e(\alpha_1, \beta_2)
-    const pairingAlphaBeta = bn254.pairing(vkAlpha1, vkBeta2);
-    // e(C_1, \delta_2)
-    const pairingCDelta = bn254.pairing(proofC, vkDelta2);
-    // Get the result of the right hand side of the pairing equation
-    const product = Fp12.mul(pairingAlphaBeta, Fp12.mul(pairingAccumGamma, pairingCDelta));
-    // Check if the left hand side equals the right hand side
-    return Fp12.eql(pairingAB, product);
+    try {
+      // Get proof points
+      const proofA = groth16Proof.a.toProjectivePoint();
+      const proofB = groth16Proof.b.toProjectivePoint();
+      const proofC = groth16Proof.c.toProjectivePoint();
+
+      // Get verification key points
+      const vkAlpha1 = this.alphaG1.toProjectivePoint();
+      const vkBeta2 = this.betaG2.toProjectivePoint();
+      const vkGamma2 = this.gammaG2.toProjectivePoint();
+      const vkDelta2 = this.deltaG2.toProjectivePoint();
+      const vkIC = this.gammaAbcG1.map((g1) => g1.toProjectivePoint());
+
+      const { Fp12 } = bn254.fields;
+
+      // Check that the following pairing equation holds:
+      // e(A_1, B_2) = e(\alpha_1, \beta_2) + e(\ic_0 + public_inputs_hash \ic_1, \gamma_2) + e(C_1, \delta_2)
+      // Where A_1, B_2, C_1 are the proof points and \alpha_1, \beta_2, \gamma_2, \delta_2, \ic_0, \ic_1
+      // are the verification key points
+
+      // \ic_0 + public_inputs_hash \ic_1
+      let accum = vkIC[0].add(vkIC[1].multiply(publicInputsHash));
+      // e(\ic_0 + public_inputs_hash \ic_1, \gamma_2)
+      const pairingAccumGamma = bn254.pairing(accum, vkGamma2);
+      // e(A_1, B_2)
+      const pairingAB = bn254.pairing(proofA, proofB);
+      // e(\alpha_1, \beta_2)
+      const pairingAlphaBeta = bn254.pairing(vkAlpha1, vkBeta2);
+      // e(C_1, \delta_2)
+      const pairingCDelta = bn254.pairing(proofC, vkDelta2);
+      // Get the result of the right hand side of the pairing equation
+      const product = Fp12.mul(pairingAlphaBeta, Fp12.mul(pairingAccumGamma, pairingCDelta));
+      // Check if the left hand side equals the right hand side
+      return Fp12.eql(pairingAB, product);
+    } catch (error) {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.PROOF_VERIFICATION_FAILED,
+        error,
+        details: "Error encountered when checking zero knowledge relation",
+      });
+    }
   }
 
   /**

package/src/core/crypto/multiEd25519.ts

@@ -106,7 +106,7 @@ export class MultiEd25519PublicKey extends AbstractMultiKey {
    * @group Implementation
    * @category Serialization
    */
-  verifySignature(args: { message: HexInput; signature: MultiEd25519Signature }): boolean {
+  verifySignature(args: { message: HexInput; signature: Signature }): boolean {
     const { message, signature } = args;
     if (!(signature instanceof MultiEd25519Signature)) {
       return false;
@@ -144,7 +144,7 @@ export class MultiEd25519PublicKey extends AbstractMultiKey {
   async verifySignatureAsync(args: {
     aptosConfig: AptosConfig;
     message: HexInput;
-    signature: MultiEd25519Signature;
+    signature: Signature;
   }): Promise<boolean> {
     return this.verifySignature(args);
   }

package/src/core/crypto/multiKey.ts

@@ -2,7 +2,7 @@ import { SigningScheme as AuthenticationKeyScheme, HexInput } from "../../types"
 import { Deserializer } from "../../bcs/deserializer";
 import { Serializer } from "../../bcs/serializer";
 import { AuthenticationKey } from "../authenticationKey";
-import { AccountPublicKey, PublicKey, VerifySignatureArgs } from "./publicKey";
+import { AccountPublicKey, PublicKey, VerifySignatureAsyncArgs } from "./publicKey";
 import { Signature } from "./signature";
 import { AnyPublicKey, AnySignature } from "./singleKey";
 import { AptosConfig } from "../../api";
@@ -208,21 +208,32 @@ export class MultiKey extends AbstractMultiKey {
   async verifySignatureAsync(args: {
     aptosConfig: AptosConfig;
     message: HexInput;
-    signature: MultiKeySignature;
+    signature: Signature;
+    options?: { throwErrorWithReason?: boolean };
   }): Promise<boolean> {
-    const { message, signature, aptosConfig } = args;
-    if (signature.signatures.length !== this.signaturesRequired) {
-      throw new Error("The number of signatures does not match the number of required signatures");
-    }
-    const signerIndices = signature.bitMapToSignerIndices();
-    for (let i = 0; i < signature.signatures.length; i += 1) {
-      const singleSignature = signature.signatures[i];
-      const publicKey = this.publicKeys[signerIndices[i]];
-      if (!(await publicKey.verifySignatureAsync({ aptosConfig, message, signature: singleSignature }))) {
-        return false;
+    const { signature } = args;
+    try {
+      if (!(signature instanceof MultiKeySignature)) {
+        throw new Error("Signature is not a MultiKeySignature");
+      }
+      if (signature.signatures.length !== this.signaturesRequired) {
+        throw new Error("The number of signatures does not match the number of required signatures");
+      }
+      const signerIndices = signature.bitMapToSignerIndices();
+      for (let i = 0; i < signature.signatures.length; i += 1) {
+        const singleSignature = signature.signatures[i];
+        const publicKey = this.publicKeys[signerIndices[i]];
+        if (!(await publicKey.verifySignatureAsync({ ...args, signature: singleSignature }))) {
+          return false;
+        }
+      }
+      return true;
+    } catch (error) {
+      if (args.options?.throwErrorWithReason) {
+        throw error;
       }
+      return false;
     }
-    return true;
   }
 
   /**

package/src/core/crypto/singleKey.ts

@@ -7,7 +7,7 @@ import {
 } from "../../types";
 import { AuthenticationKey } from "../authenticationKey";
 import { Ed25519PrivateKey, Ed25519PublicKey, Ed25519Signature } from "./ed25519";
-import { AccountPublicKey, PublicKey, VerifySignatureArgs, VerifySignatureAsyncArgs } from "./publicKey";
+import { AccountPublicKey, PublicKey } from "./publicKey";
 import { Secp256k1PrivateKey, Secp256k1PublicKey, Secp256k1Signature } from "./secp256k1";
 import { KeylessPublicKey, KeylessSignature } from "./keyless";
 import { Signature } from "./signature";
@@ -85,6 +85,9 @@ export class AnyPublicKey extends AccountPublicKey {
    */
   verifySignature(args: { message: HexInput; signature: AnySignature }): boolean {
     const { message, signature } = args;
+    if (this.publicKey instanceof KeylessPublicKey) {
+      throw new Error("Use verifySignatureAsync to verify Keyless signatures");
+    }
     return this.publicKey.verifySignature({
       message,
       signature: signature.signature,
@@ -106,8 +109,15 @@ export class AnyPublicKey extends AccountPublicKey {
   async verifySignatureAsync(args: {
     aptosConfig: AptosConfig;
     message: HexInput;
-    signature: AnySignature;
+    signature: Signature;
+    options?: { throwErrorWithReason?: boolean };
   }): Promise<boolean> {
+    if (!(args.signature instanceof AnySignature)) {
+      if (args.options?.throwErrorWithReason) {
+        throw new Error("Signature must be an instance of AnySignature");
+      }
+      return false;
+    }
     return await this.publicKey.verifySignatureAsync({
       ...args,
       signature: args.signature.signature,

package/src/internal/account.ts

@@ -9,9 +9,15 @@
  * @group Implementation
  */
 import { AptosConfig } from "../api/aptosConfig";
-import { getAptosFullNode, paginateWithCursor, paginateWithObfuscatedCursor } from "../client";
+import {
+  getAptosFullNode,
+  getPageWithObfuscatedCursor,
+  paginateWithCursor,
+  paginateWithObfuscatedCursor,
+} from "../client";
 import {
   AccountData,
+  CursorPaginationArgs,
   GetAccountCoinsDataResponse,
   GetAccountCollectionsWithOwnedTokenResponse,
   GetAccountOwnedTokensFromCollectionResponse,
@@ -32,7 +38,7 @@ import { AccountAddress, AccountAddressInput } from "../core/accountAddress";
 import { Account, Ed25519Account, MultiEd25519Account } from "../account";
 import { AnyPublicKey, Ed25519PublicKey, PrivateKey } from "../core/crypto";
 import { queryIndexer } from "./general";
-import { getModules as getModulesUtil, getModule as getModuleUtil, getInfo as getInfoUtil } from "./utils";
+import { getModule as getModuleUtil, getInfo as getInfoUtil } from "./utils";
 import {
   GetAccountCoinsCountQuery,
   GetAccountCoinsDataQuery,
@@ -93,9 +99,50 @@ export async function getInfo(args: {
 export async function getModules(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
-  options?: PaginationArgs & LedgerVersionArg;
+  options?: { limit?: number } & LedgerVersionArg;
 }): Promise<MoveModuleBytecode[]> {
-  return getModulesUtil(args);
+  const { aptosConfig, accountAddress, options } = args;
+  return paginateWithObfuscatedCursor<{}, MoveModuleBytecode[]>({
+    aptosConfig,
+    originMethod: "getModules",
+    path: `accounts/${AccountAddress.from(accountAddress).toString()}/modules`,
+    params: {
+      ledger_version: options?.ledgerVersion,
+      limit: options?.limit ?? 1000,
+    },
+  });
+}
+
+/**
+ * Retrieves the modules associated with a specified account address.
+ *
+ * @param args - The arguments for retrieving modules.
+ * @param args.aptosConfig - The configuration for connecting to the Aptos blockchain.
+ * @param args.accountAddress - The address of the account whose modules are to be retrieved.
+ * @param args.options - Optional parameters for pagination and ledger version.
+ * @param args.options.cursor - The starting point for pagination.  Note, this is obfuscated and is not an index.
+ * @param args.options.limit - The maximum number of modules to retrieve (default is 100).
+ * @param args.options.ledgerVersion - The specific ledger version to query.
+ * @group Implementation
+ */
+export async function getModulesPage(args: {
+  aptosConfig: AptosConfig;
+  accountAddress: AccountAddressInput;
+  options?: CursorPaginationArgs & LedgerVersionArg;
+}): Promise<{ modules: MoveModuleBytecode[]; cursor: string | undefined }> {
+  const { aptosConfig, accountAddress, options } = args;
+  const { response, cursor } = await getPageWithObfuscatedCursor<{}, MoveModuleBytecode[]>({
+    aptosConfig,
+    originMethod: "getModulesPage",
+    path: `accounts/${AccountAddress.from(accountAddress).toString()}/modules`,
+    params: {
+      ledger_version: options?.ledgerVersion,
+      cursor: options?.cursor,
+      limit: options?.limit ?? 100,
+    },
+  });
+
+  return { modules: response.data, cursor };
 }
 
 /**
@@ -153,7 +200,6 @@ export async function getTransactions(args: {
  * @param args.aptosConfig - The configuration settings for Aptos.
  * @param args.accountAddress - The address of the account to fetch resources for.
  * @param args.options - Optional pagination and ledger version parameters.
- * @param args.options.offset - The starting point for pagination.  Note, this is obfuscated and is not an index.
  * @param args.options.limit - The maximum number of resources to retrieve (default is 999).
  * @param args.options.ledgerVersion - The specific ledger version to query.
  * @group Implementation
@@ -161,7 +207,7 @@ export async function getTransactions(args: {
 export async function getResources(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
-  options?: PaginationArgs & LedgerVersionArg;
+  options?: { limit?: number } & LedgerVersionArg;
 }): Promise<MoveResource[]> {
   const { aptosConfig, accountAddress, options } = args;
   return paginateWithObfuscatedCursor<{}, MoveResource[]>({
@@ -170,12 +216,43 @@ export async function getResources(args: {
     path: `accounts/${AccountAddress.from(accountAddress).toString()}/resources`,
     params: {
       ledger_version: options?.ledgerVersion,
-      offset: options?.offset,
       limit: options?.limit ?? 999,
     },
   });
 }
 
+/**
+ * Retrieves a page of resources associated with a specific account address.
+ *
+ * @param args - The arguments for retrieving resources.
+ * @param args.aptosConfig - The configuration settings for Aptos.
+ * @param args.accountAddress - The address of the account to fetch resources for.
+ * @param args.options - Optional pagination and ledger version parameters.
+ * @param args.options.cursor - The starting point for pagination.  Note, this is obfuscated and is not an index.
+ * @param args.options.limit - The maximum number of resources to retrieve (default is 100).
+ * @param args.options.ledgerVersion - The specific ledger version to query.
+ * @group Implementation
+ */
+export async function getResourcesPage(args: {
+  aptosConfig: AptosConfig;
+  accountAddress: AccountAddressInput;
+  options?: CursorPaginationArgs & LedgerVersionArg;
+}): Promise<{ resources: MoveResource[]; cursor: string | undefined }> {
+  const { aptosConfig, accountAddress, options } = args;
+  const { response, cursor } = await getPageWithObfuscatedCursor<{}, MoveResource[]>({
+    aptosConfig,
+    originMethod: "getResourcesPage",
+    path: `accounts/${AccountAddress.from(accountAddress).toString()}/resources`,
+    params: {
+      ledger_version: options?.ledgerVersion,
+      cursor: options?.cursor,
+      limit: options?.limit ?? 100,
+    },
+  });
+
+  return { resources: response.data, cursor };
+}
+
 /**
  * Retrieves a specific resource of a given type for the specified account address.
  *

package/src/internal/utils/utils.ts

@@ -1,39 +1,9 @@
 import { AccountAddress, AccountAddressInput } from "../../core/accountAddress";
-import { MoveModuleBytecode, LedgerVersionArg, PaginationArgs, AccountData } from "../../types/types";
+import { MoveModuleBytecode, LedgerVersionArg, AccountData } from "../../types/types";
 import { AptosConfig } from "../../api/aptosConfig";
-import { getAptosFullNode, paginateWithObfuscatedCursor } from "../../client";
+import { getAptosFullNode } from "../../client";
 import { memoizeAsync } from "../../utils/memoize";
 
-/**
- * Retrieves the modules associated with a specified account address.
- *
- * @param args - The arguments for retrieving modules.
- * @param args.aptosConfig - The configuration for connecting to the Aptos blockchain.
- * @param args.accountAddress - The address of the account whose modules are to be retrieved.
- * @param args.options - Optional parameters for pagination and ledger version.
- * @param args.options.limit - The maximum number of modules to retrieve (default is 1000).
- * @param args.options.offset - The starting point for pagination.  Note, this is obfuscated and is not an index.
- * @param args.options.ledgerVersion - The specific ledger version to query.
- * @group Implementation
- */
-export async function getModules(args: {
-  aptosConfig: AptosConfig;
-  accountAddress: AccountAddressInput;
-  options?: PaginationArgs & LedgerVersionArg;
-}): Promise<MoveModuleBytecode[]> {
-  const { aptosConfig, accountAddress, options } = args;
-  return paginateWithObfuscatedCursor<{}, MoveModuleBytecode[]>({
-    aptosConfig,
-    originMethod: "getModules",
-    path: `accounts/${AccountAddress.from(accountAddress).toString()}/modules`,
-    params: {
-      ledger_version: options?.ledgerVersion,
-      offset: options?.offset,
-      limit: options?.limit ?? 1000,
-    },
-  });
-}
-
 /**
  * Retrieves account information for a specified account address.
  *

package/src/types/types.ts

@@ -237,6 +237,16 @@ export interface PaginationArgs {
   limit?: number;
 }
 
+/**
+ * Defines the parameters for paginating query results, including the starting position and maximum number of items to return.
+ * @param cursor Specifies the starting position of the query result. Default is at the beginning if undefined.  This is not a number and must come from the API.
+ * @param limit Specifies the maximum number of items to return. Default is 25.
+ */
+export interface CursorPaginationArgs {
+  cursor?: string;
+  limit?: number;
+}
+
 /**
  * Represents the arguments for specifying a token standard.
  *

package/src/utils/helpers.ts

@@ -4,6 +4,7 @@
 import { decode } from "js-base64";
 import { MoveFunctionId, MoveStructId } from "../types";
 import { AccountAddress } from "../core/accountAddress";
+import { createObjectAddress } from "../core/account/utils/address";
 
 /**
  * Sleep for the specified amount of time in milliseconds.
@@ -235,3 +236,52 @@ export function isValidFunctionInfo(functionInfo: string): boolean {
 export function truncateAddress(address: string, start: number = 6, end: number = 5) {
   return `${address.slice(0, start)}...${address.slice(-end)}`;
 }
+
+/**
+ * Constants for metadata address calculation
+ */
+const APTOS_COIN_TYPE_STR = "0x1::aptos_coin::AptosCoin";
+const APT_METADATA_ADDRESS_HEX = AccountAddress.A.toStringLong();
+
+/**
+ * Helper function to standardize Move type string by converting all addresses to short form,
+ * including addresses within nested type parameters
+ */
+function standardizeMoveTypeString(input: string): string {
+  // Regular expression to match addresses in the type string, including those within type parameters
+  // This regex matches "0x" followed by hex digits, handling both standalone addresses and those within <>
+  const addressRegex = /0x[0-9a-fA-F]+/g;
+
+  return input.replace(addressRegex, (match) => {
+    // Use AccountAddress to handle the address
+    return AccountAddress.from(match, { maxMissingChars: 63 }).toStringShort();
+  });
+}
+
+/**
+ * Calculates the paired FA metadata address for a given coin type.
+ * This function is tolerant of various address formats in the coin type string,
+ * including complex nested types.
+ *
+ * @example
+ * // All these formats are valid and will produce the same result:
+ * pairedFaMetadataAddress("0x1::aptos_coin::AptosCoin")  // simple form
+ * pairedFaMetadataAddress("0x0000000000000000000000000000000000000000000000000000000000000001::aptos_coin::AptosCoin")  // long form
+ * pairedFaMetadataAddress("0x00001::aptos_coin::AptosCoin")  // with leading zeros
+ * pairedFaMetadataAddress("0x1::coin::Coin<0x1412::a::struct<0x0001::aptos_coin::AptosCoin>>")  // nested type parameters
+ *
+ * @param coinType - The coin type string in any of these formats:
+ *   - Short form address: "0x1::aptos_coin::AptosCoin"
+ *   - Long form address: "0x0000000000000000000000000000000000000000000000000000000000000001::aptos_coin::AptosCoin"
+ *   - With leading zeros: "0x00001::aptos_coin::AptosCoin"
+ *   - With nested types: "0x1::coin::Coin<0x1412::a::struct<0x0001::aptos_coin::AptosCoin>>"
+ * @returns The calculated metadata address as an AccountAddress instance
+ */
+export function pairedFaMetadataAddress(coinType: `0x${string}::${string}::${string}`): AccountAddress {
+  // Standardize the coin type string to handle any address format
+  const standardizedMoveTypeName = standardizeMoveTypeString(coinType);
+
+  return standardizedMoveTypeName === APTOS_COIN_TYPE_STR
+    ? AccountAddress.A
+    : createObjectAddress(AccountAddress.A, standardizedMoveTypeName);
+}

package/src/version.ts

@@ -6,4 +6,4 @@
  *
  * hardcoded for now, we would want to have it injected dynamically
  */
-export const VERSION = "1.36.0";
+export const VERSION = "1.37.0";