@aptos-labs/ts-sdk 1.29.1 → 1.31.0

package/src/core/hex.ts

@@ -6,7 +6,7 @@ import { ParsingError, ParsingResult } from "./common";
 import { HexInput } from "../types";
 
 /**
- * This enum is used to explain why parsing might have failed.
+ * Provides reasons for parsing failures related to hexadecimal values.
  */
 export enum HexInvalidReason {
   TOO_SHORT = "too_short",
@@ -15,28 +15,26 @@ export enum HexInvalidReason {
 }
 
 /**
- * NOTE: Do not use this class when working with account addresses, use AccountAddress.
+ * NOTE: Do not use this class when working with account addresses; use AccountAddress instead.
+ * When accepting hex data as input to a function, prefer to accept HexInput and
+ *
+ * A helper class for working with hex data. Hex data, when represented as a string,
+ * generally looks like this, for example: 0xaabbcc, 45cd32, etc.
  *
- * NOTE: When accepting hex data as input to a function, prefer to accept HexInput and
  * then use the static helper methods of this class to convert it into the desired
  * format. This enables the greatest flexibility for the developer.
  *
- * Hex is a helper class for working with hex data. Hex data, when represented as a
- * string, generally looks like this, for example: 0xaabbcc, 45cd32, etc.
- *
- * You might use this class like this:
- *
- * ```ts
+ * Example usage:
+ * ```typescript
  * getTransactionByHash(txnHash: HexInput): Promise<Transaction> {
  *   const txnHashString = Hex.fromHexInput(txnHash).toString();
  *   return await getTransactionByHashInner(txnHashString);
  * }
  * ```
- *
  * This call to `Hex.fromHexInput().toString()` converts the HexInput to a hex string
  * with a leading 0x prefix, regardless of what the input format was.
  *
- * These are some other ways to chain the functions together:
+ * Other ways to chain the functions together:
  * - `Hex.fromHexString({ hexInput: "0x1f" }).toUint8Array()`
  * - `new Hex([1, 3]).toStringWithoutPrefix()`
  */
@@ -46,7 +44,7 @@ export class Hex {
   /**
    * Create a new Hex instance from a Uint8Array.
    *
-   * @param data Uint8Array
+   * @param data - The Uint8Array containing the data to initialize the Hex instance.
    */
   constructor(data: Uint8Array) {
     this.data = data;
@@ -57,8 +55,7 @@ export class Hex {
   // ===
 
   /**
-   * Get the inner hex data. The inner data is already a Uint8Array so no conversion
-   * is taking place here, it just returns the inner data.
+   * Get the inner hex data as a Uint8Array. The inner data is already a Uint8Array, so no conversion takes place.
    *
    * @returns Hex data as Uint8Array
    */
@@ -89,11 +86,13 @@ export class Hex {
   // ===
 
   /**
-   * Static method to convert a hex string to Hex
+   * Converts a hex string into a Hex instance, allowing for both prefixed and non-prefixed formats.
+   *
+   * @param str - A hex string, with or without the 0x prefix.
    *
-   * @param str A hex string, with or without the 0x prefix
+   * @throws ParsingError - If the hex string is too short, has an odd number of characters, or contains invalid hex characters.
    *
-   * @returns Hex
+   * @returns Hex - The resulting Hex instance created from the provided string.
    */
   static fromHexString(str: string): Hex {
     let input = str;
@@ -124,11 +123,11 @@ export class Hex {
   }
 
   /**
-   * Static method to convert an instance of HexInput to Hex
-   *
-   * @param hexInput A HexInput (string or Uint8Array)
+   * Converts an instance of HexInput, which can be a string or a Uint8Array, into a Hex instance.
+   * This function is useful for transforming hexadecimal representations into a structured Hex object for further manipulation.
    *
-   * @returns Hex
+   * @param hexInput - A HexInput which can be a string or Uint8Array.
+   * @returns A Hex instance created from the provided hexInput.
    */
   static fromHexInput(hexInput: HexInput): Hex {
     if (hexInput instanceof Uint8Array) return new Hex(hexInput);
@@ -140,13 +139,14 @@ export class Hex {
   // ===
 
   /**
-   * Check if the string is valid hex.
+   * Check if the provided string is a valid hexadecimal representation.
    *
-   * @param str A hex string representing byte data.
+   * @param str - A hex string representing byte data.
    *
-   * @returns valid = true if the string is valid, false if not. If the string is not
-   * valid, invalidReason and invalidReasonMessage will be set explaining why it is
-   * invalid.
+   * @returns An object containing:
+   *  - valid: A boolean indicating whether the string is valid.
+   *  - invalidReason: The reason for invalidity if the string is not valid.
+   *  - invalidReasonMessage: A message explaining why the string is invalid.
    */
   static isValid(str: string): ParsingResult<HexInvalidReason> {
     try {
@@ -162,8 +162,7 @@ export class Hex {
   }
 
   /**
-   * Return whether Hex instances are equal. Hex instances are considered equal if
-   * their underlying byte data is identical.
+   * Determine if two Hex instances are equal by comparing their underlying byte data.
    *
    * @param other The Hex instance to compare to.
    * @returns true if the Hex instances are equal, false if not.

package/src/internal/account.ts

@@ -52,10 +52,18 @@ import {
   GetAccountTransactionsCount,
 } from "../types/generated/queries";
 import { memoizeAsync } from "../utils/memoize";
-import { Secp256k1PrivateKey, AuthenticationKey, Ed25519PrivateKey } from "../core";
+import { Secp256k1PrivateKey, AuthenticationKey, Ed25519PrivateKey, createObjectAddress } from "../core";
 import { CurrentFungibleAssetBalancesBoolExp } from "../types/generated/types";
 import { getTableItem } from "./table";
+import { APTOS_COIN } from "../utils";
 
+/**
+ * Retrieves account information for a specified account address.
+ *
+ * @param args - The arguments for retrieving account information.
+ * @param args.aptosConfig - The configuration object for Aptos.
+ * @param args.accountAddress - The address of the account to retrieve information for.
+ */
 export async function getInfo(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -69,6 +77,17 @@ export async function getInfo(args: {
   return data;
 }
 
+/**
+ * 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.
+ * @param args.options.ledgerVersion - The specific ledger version to query.
+ */
 export async function getModules(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -88,11 +107,15 @@ export async function getModules(args: {
 }
 
 /**
- * Queries for a move module given account address and module name
+ * Queries for a move module given an account address and module name.
+ * This function can help you retrieve the module's ABI and other relevant information.
  *
- * @param args.accountAddress Hex-encoded 32 byte Aptos account address
- * @param args.moduleName The name of the module
- * @param args.query.ledgerVersion Specifies ledger version of transactions. By default, latest version will be used
+ * @param args - The arguments for retrieving the module.
+ * @param args.aptosConfig - The configuration for the Aptos client.
+ * @param args.accountAddress - The account address in hex-encoded 32 byte format.
+ * @param args.moduleName - The name of the module to retrieve.
+ * @param args.options - Optional parameters for the request.
+ * @param args.options.ledgerVersion - Specifies the ledger version of transactions. By default, the latest version will be used.
  * @returns The move module.
  */
 export async function getModule(args: {
@@ -114,6 +137,16 @@ export async function getModule(args: {
   )();
 }
 
+/**
+ * Retrieves the bytecode of a specified module from a given account address.
+ *
+ * @param args - The parameters for retrieving the module bytecode.
+ * @param args.aptosConfig - The configuration for connecting to the Aptos network.
+ * @param args.accountAddress - The address of the account from which to retrieve the module.
+ * @param args.moduleName - The name of the module to retrieve.
+ * @param args.options - Optional parameters for specifying the ledger version.
+ * @param args.options.ledgerVersion - The specific ledger version to query.
+ */
 async function getModuleInner(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -131,6 +164,17 @@ async function getModuleInner(args: {
   return data;
 }
 
+/**
+ * Retrieves a list of transactions associated with a specific account address.
+ * This function allows you to paginate through the transactions for better performance and usability.
+ *
+ * @param args - The arguments for retrieving transactions.
+ * @param args.aptosConfig - The configuration settings for Aptos.
+ * @param args.accountAddress - The account address for which to retrieve transactions.
+ * @param args.options - Optional pagination parameters.
+ * @param args.options.offset - The starting point for pagination.
+ * @param args.options.limit - The maximum number of transactions to retrieve.
+ */
 export async function getTransactions(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -145,6 +189,17 @@ export async function getTransactions(args: {
   });
 }
 
+/**
+ * Retrieves a list 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.offset - The starting point for pagination.
+ * @param args.options.limit - The maximum number of resources to retrieve (default is 999).
+ * @param args.options.ledgerVersion - The specific ledger version to query.
+ */
 export async function getResources(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -163,6 +218,15 @@ export async function getResources(args: {
   });
 }
 
+/**
+ * Retrieves a specific resource of a given type for the specified account address.
+ *
+ * @param args - The arguments for retrieving the resource.
+ * @param args.aptosConfig - The configuration settings for Aptos.
+ * @param args.accountAddress - The address of the account from which to retrieve the resource.
+ * @param args.resourceType - The type of the resource to retrieve, specified as a MoveStructId.
+ * @param args.options - Optional parameters for specifying the ledger version.
+ */
 export async function getResource<T extends {}>(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -179,6 +243,16 @@ export async function getResource<T extends {}>(args: {
   return data.data as T;
 }
 
+/**
+ * Retrieves the original account address associated with a given authentication key, which is useful for handling key rotations.
+ *
+ * @param args - The arguments for the lookup.
+ * @param args.aptosConfig - The configuration for the Aptos client.
+ * @param args.authenticationKey - The authentication key for which to look up the original address.
+ * @param args.options - Optional parameters for specifying the ledger version.
+ * @returns The original account address or the provided authentication key address if not found.
+ * @throws Throws an error if the lookup fails for reasons other than the address not being found.
+ */
 export async function lookupOriginalAccountAddress(args: {
   aptosConfig: AptosConfig;
   authenticationKey: AccountAddressInput;
@@ -225,6 +299,14 @@ export async function lookupOriginalAccountAddress(args: {
   }
 }
 
+/**
+ * Retrieves the count of tokens owned by a specific account address.
+ *
+ * @param args - The arguments for retrieving the account tokens count.
+ * @param args.aptosConfig - The configuration settings for the Aptos network.
+ * @param args.accountAddress - The address of the account for which to count the tokens.
+ * @returns The count of tokens owned by the specified account.
+ */
 export async function getAccountTokensCount(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -249,13 +331,26 @@ export async function getAccountTokensCount(args: {
     originMethod: "getAccountTokensCount",
   });
 
-  // commonjs (aka cjs) doesnt handle Nullish Coalescing for some reason
+  // commonjs (aka cjs) doesn't handle Nullish Coalescing for some reason
   // might be because of how ts infer the graphql generated scheme type
   return data.current_token_ownerships_v2_aggregate.aggregate
     ? data.current_token_ownerships_v2_aggregate.aggregate.count
     : 0;
 }
 
+/**
+ * Retrieves the tokens owned by a specified account address.
+ *
+ * @param args - The arguments for retrieving the account's tokens.
+ * @param args.aptosConfig - The configuration for the Aptos client.
+ * @param args.accountAddress - The address of the account whose tokens are being queried.
+ * @param args.options - Optional parameters for filtering and pagination.
+ * @param args.options.tokenStandard - The specific token standard to filter the results.
+ * @param args.options.offset - The number of records to skip before starting to collect the result set.
+ * @param args.options.limit - The maximum number of records to return.
+ * @param args.options.orderBy - The criteria for ordering the results.
+ * @returns A promise that resolves to the current token ownerships of the specified account.
+ */
 export async function getAccountOwnedTokens(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -293,6 +388,16 @@ export async function getAccountOwnedTokens(args: {
   return data.current_token_ownerships_v2;
 }
 
+/**
+ * Retrieves the tokens owned by a specific account from a particular collection address.
+ *
+ * @param args - The parameters required to fetch the owned tokens.
+ * @param args.aptosConfig - The Aptos configuration object.
+ * @param args.accountAddress - The address of the account whose tokens are being queried.
+ * @param args.collectionAddress - The address of the collection from which tokens are being retrieved.
+ * @param args.options - Optional parameters for filtering and pagination, including token standard, pagination arguments, and
+ * order by options.
+ */
 export async function getAccountOwnedTokensFromCollectionAddress(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -337,6 +442,18 @@ export async function getAccountOwnedTokensFromCollectionAddress(args: {
   return data.current_token_ownerships_v2;
 }
 
+/**
+ * Retrieves the collections owned by a specified account along with the tokens in those collections.
+ *
+ * @param args - The arguments for the function.
+ * @param args.aptosConfig - The configuration for the Aptos client.
+ * @param args.accountAddress - The address of the account whose collections are being queried.
+ * @param args.options - Optional parameters for filtering and pagination.
+ * @param args.options.tokenStandard - An optional token standard to filter the collections.
+ * @param args.options.offset - An optional offset for pagination.
+ * @param args.options.limit - An optional limit for the number of results returned.
+ * @param args.options.orderBy - An optional parameter to specify the order of the results.
+ */
 export async function getAccountCollectionsWithOwnedTokens(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -377,6 +494,14 @@ export async function getAccountCollectionsWithOwnedTokens(args: {
   return data.current_collection_ownership_v2_view;
 }
 
+/**
+ * Retrieves the count of transactions associated with a specified account.
+ *
+ * @param args - The arguments for the function.
+ * @param args.aptosConfig - The configuration settings for Aptos.
+ * @param args.accountAddress - The address of the account for which to retrieve the transaction count.
+ * @returns The number of transactions associated with the specified account.
+ */
 export async function getAccountTransactionsCount(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -396,11 +521,86 @@ export async function getAccountTransactionsCount(args: {
     originMethod: "getAccountTransactionsCount",
   });
 
-  // commonjs (aka cjs) doesnt handle Nullish Coalescing for some reason
+  // commonjs (aka cjs) doesn't handle Nullish Coalescing for some reason
   // might be because of how ts infer the graphql generated scheme type
   return data.account_transactions_aggregate.aggregate ? data.account_transactions_aggregate.aggregate.count : 0;
 }
 
+/**
+ * Retrieves the amount of a specific coin held by an account.
+ *
+ * @param args - The parameters for the request.
+ * @param args.aptosConfig - The Aptos configuration object.
+ * @param args.accountAddress - The address of the account to query.
+ * @param args.coinType - Optional; the type of coin to check the amount for.
+ * @param args.faMetadataAddress - Optional; the address of the fungible asset metadata.
+ * @returns The amount of the specified coin held by the account, or 0 if none is found.
+ * @throws Error if neither coinType nor faMetadataAddress is provided.
+ */
+export async function getAccountCoinAmount(args: {
+  aptosConfig: AptosConfig;
+  accountAddress: AccountAddressInput;
+  coinType?: MoveStructId;
+  faMetadataAddress?: AccountAddressInput;
+}): Promise<number> {
+  const { aptosConfig, accountAddress, coinType, faMetadataAddress } = args;
+
+  let coinAssetType: string | undefined = coinType;
+  let faAddress: string;
+
+  if (coinType !== undefined && faMetadataAddress !== undefined) {
+    faAddress = AccountAddress.from(faMetadataAddress).toStringLong();
+  } else if (coinType !== undefined && faMetadataAddress === undefined) {
+    // TODO Move to a separate function as defined in the AIP for coin migration
+    if (coinType === APTOS_COIN) {
+      faAddress = AccountAddress.A.toStringLong();
+    } else {
+      faAddress = createObjectAddress(AccountAddress.A, coinType).toStringLong();
+    }
+  } else if (coinType === undefined && faMetadataAddress !== undefined) {
+    const addr = AccountAddress.from(faMetadataAddress);
+    faAddress = addr.toStringLong();
+    if (addr === AccountAddress.A) {
+      coinAssetType = APTOS_COIN;
+    }
+    // The paired CoinType should be populated outside of this function in another
+    // async call. We cannot do this internally due to dependency cycles issue.
+  } else {
+    throw new Error("Either coinType, fungibleAssetAddress, or both must be provided");
+  }
+  const address = AccountAddress.from(accountAddress).toStringLong();
+
+  // Search by fungible asset address, unless it has a coin it migrated from
+  let where: any = { asset_type: { _eq: faAddress } };
+  if (coinAssetType !== undefined) {
+    where = { asset_type: { _in: [coinAssetType, faAddress] } };
+  }
+
+  const data = await getAccountCoinsData({
+    aptosConfig,
+    accountAddress: address,
+    options: {
+      where,
+    },
+  });
+
+  // commonjs (aka cjs) doesn't handle Nullish Coalescing for some reason
+  // might be because of how ts infer the graphql generated scheme type
+  return data[0] ? data[0].amount : 0;
+}
+
+/**
+ * Retrieves the current fungible asset balances for a specified account.
+ *
+ * @param args - The arguments for retrieving account coins data.
+ * @param args.aptosConfig - The configuration for connecting to the Aptos network.
+ * @param args.accountAddress - The address of the account for which to retrieve coin data.
+ * @param args.options - Optional parameters for pagination and filtering the results.
+ * @param args.options.offset - The number of items to skip before starting to collect the result set.
+ * @param args.options.limit - The maximum number of items to return.
+ * @param args.options.orderBy - The criteria for ordering the results.
+ * @param args.options.where - Conditions to filter the results based on the current fungible asset balances.
+ */
 export async function getAccountCoinsData(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -433,6 +633,14 @@ export async function getAccountCoinsData(args: {
   return data.current_fungible_asset_balances;
 }
 
+/**
+ * Retrieves the count of fungible asset coins held by a specified account.
+ *
+ * @param args - The arguments for the function.
+ * @param args.aptosConfig - The configuration settings for the Aptos network.
+ * @param args.accountAddress - The address of the account for which to retrieve the coin count.
+ * @throws Error if the count of account coins cannot be retrieved.
+ */
 export async function getAccountCoinsCount(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -458,6 +666,18 @@ export async function getAccountCoinsCount(args: {
   return data.current_fungible_asset_balances_aggregate.aggregate.count;
 }
 
+/**
+ * Retrieves the objects owned by a specified account.
+ *
+ * @param args - The parameters for the request.
+ * @param args.aptosConfig - The configuration for the Aptos client.
+ * @param args.accountAddress - The address of the account whose owned objects are to be retrieved.
+ * @param args.options - Optional parameters for pagination and ordering of the results.
+ * @param args.options.offset - The number of items to skip before starting to collect the result set.
+ * @param args.options.limit - The maximum number of items to return.
+ * @param args.options.orderBy - The criteria to order the results by.
+ * @returns A promise that resolves to the current objects owned by the specified account.
+ */
 export async function getAccountOwnedObjects(args: {
   aptosConfig: AptosConfig;
   accountAddress: AccountAddressInput;
@@ -488,13 +708,19 @@ export async function getAccountOwnedObjects(args: {
 }
 
 /**
- * NOTE: There is a potential issue once unified single signer scheme will be adopted
- * by the community.
+ * Derives an account from the provided private key and Aptos configuration.
+ * This function helps in obtaining the account details associated with a given private key,
+ * considering both unified and legacy authentication schemes.
  *
- * Becuase on could create 2 accounts with the same private key with this new authenticator type,
- * we’ll need to determine the order in which we lookup the accounts. First unified
- * scheme and then legacy scheme vs first legacy scheme and then unified scheme.
+ * NOTE: There is a potential issue once the unified single signer scheme is adopted by the community.
+ * Because one could create two accounts with the same private key with this new authenticator type,
+ * we’ll need to determine the order in which we look up the accounts: first unified scheme and then legacy scheme,
+ * or first legacy scheme and then unified scheme.
  *
+ * @param args - The arguments for deriving the account.
+ * @param args.aptosConfig - The Aptos configuration used for account lookup.
+ * @param args.privateKey - The private key used to derive the account.
+ * @throws Error if the account cannot be derived from the private key.
  */
 export async function deriveAccountFromPrivateKey(args: {
   aptosConfig: AptosConfig;
@@ -538,6 +764,16 @@ export async function deriveAccountFromPrivateKey(args: {
   throw new Error(`Can't derive account from private key ${privateKey}`);
 }
 
+/**
+ * Checks if an account exists by verifying its information against the Aptos blockchain.
+ *
+ * @param args - The arguments for the function.
+ * @param args.aptosConfig - The configuration for connecting to the Aptos blockchain.
+ * @param args.authKey - The authentication key used to derive the account address.
+ * @returns A promise that resolves to a boolean indicating whether the account exists.
+ *
+ * @throws Throws an Error if there is an issue while looking for account information.
+ */
 export async function isAccountExist(args: { aptosConfig: AptosConfig; authKey: AuthenticationKey }): Promise<boolean> {
   const { aptosConfig, authKey } = args;
   const accountAddress = await lookupOriginalAccountAddress({