@aptos-labs/ts-sdk 1.29.1 → 1.31.0

package/src/api/event.ts

@@ -15,21 +15,62 @@ import { AptosConfig } from "./aptosConfig";
 import { waitForIndexerOnVersion } from "./utils";
 
 /**
- * A class to query all `Event` Aptos related queries
+ * A class to query all `Event` Aptos related queries.
  */
 export class Event {
+  /**
+   * Initializes a new instance of the Aptos client with the provided configuration.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   * @param config.network - The network to connect to (e.g., Testnet, Mainnet).
+   * @param config.nodeUrl - The URL of the Aptos node to connect to.
+   * @param config.faucetUrl - The URL of the faucet to use for funding accounts.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a new Aptos client with Testnet configuration
+   *     const config = new AptosConfig({ network: Network.TESTNET }); // Specify your own network if needed
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(readonly config: AptosConfig) {}
 
   /**
-   * Get module events by event type
+   * Retrieve module events based on a specified event type.
+   * This function allows you to query for events that are associated with a particular module event type in the Aptos blockchain.
+   *
+   * @param args - The arguments for retrieving module events.
+   * @param args.eventType - The event type to filter the results.
+   * @param args.minimumLedgerVersion - Optional ledger version to sync up to before querying.
+   * @param args.options - Optional pagination and ordering parameters for the event results.
+   *
+   * @returns Promise<GetEventsResponse> - A promise that resolves to the retrieved events.
    *
    * @example
-   * const events = await aptos.getModuleEventsByEventType({eventType:"0x1::transaction_fee::FeeStatement"})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.eventType - The event type
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @returns Promise<GetEventsResponse>
+   * async function runExample() {
+   *   // Retrieve module events for a specific event type
+   *   const events = await aptos.getModuleEventsByEventType({
+   *     eventType: "0x1::transaction_fee::FeeStatement", // specify the event type
+   *     minimumLedgerVersion: 1, // optional: specify minimum ledger version if needed
+   *   });
+   *
+   *   console.log(events); // log the retrieved events
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getModuleEventsByEventType(args: {
     eventType: MoveStructId;
@@ -45,16 +86,33 @@ export class Event {
   }
 
   /**
-   * Get events by creation number and an account address
+   * Retrieve events associated with a specific account address and creation number.
+   *
+   * @param args - The parameters for retrieving account events.
+   * @param args.accountAddress - The account address to query events for.
+   * @param args.creationNumber - The event creation number to filter the events.
+   * @param args.minimumLedgerVersion - Optional minimum ledger version to sync up to before querying.
+   *
+   * @returns Promise<GetEventsResponse>
    *
    * @example
-   * const events = await aptos.getAccountEventsByCreationNumber({accountAddress:"0x123",creationNumber: 0})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.accountAddress - The account address
-   * @param args.creationNumber - The event creation number
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @returns Promise<GetEventsResponse>
+   * async function runExample() {
+   *   // Get events for the account at creation number 0
+   *   const events = await aptos.getAccountEventsByCreationNumber({
+   *     accountAddress: "0x1", // replace with a real account address
+   *     creationNumber: 0,
+   *   });
+   *
+   *   console.log(events);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getAccountEventsByCreationNumber(args: {
     accountAddress: AccountAddressInput;
@@ -70,16 +128,34 @@ export class Event {
   }
 
   /**
-   * Get events by event type and an account address
+   * Retrieve events associated with a specific account address and event type.
+   *
+   * @param args.accountAddress - The account address to query events for.
+   * @param args.eventType - The type of event to filter by.
+   * @param args.minimumLedgerVersion - Optional ledger version to sync up to before querying.
+   * @param args.options - Optional pagination and ordering parameters for the event query.
+   *
+   * @returns Promise<GetEventsResponse>
    *
    * @example
-   * const events = await aptos.getAccountEventsByEventType({accountAddress:"0x123",eventType: "0x1::transaction_fee::FeeStatement"})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.accountAddress - The account address
-   * @param args.eventType - The event type
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @returns Promise<GetEventsResponse>
+   * async function runExample() {
+   *   // Get events for a specific account and event type
+   *   const events = await aptos.getAccountEventsByEventType({
+   *     accountAddress: "0x1", // replace with a real account address
+   *     eventType: "0x1::transaction_fee::FeeStatement", // replace with a real event type
+   *     minimumLedgerVersion: 1, // optional, specify if needed
+   *   });
+   *
+   *   console.log(events);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getAccountEventsByEventType(args: {
     accountAddress: AccountAddressInput;
@@ -96,16 +172,43 @@ export class Event {
   }
 
   /**
-   * Get all events
+   * Retrieve all events from the Aptos blockchain.
+   * An optional `where` clause can be provided to filter the results based on specific criteria.
+   *
+   * @param args Optional parameters for the query.
+   * @param args.minimumLedgerVersion Optional ledger version to sync up to before querying.
+   * @param args.options Optional pagination and filtering options.
+   * @param args.options.where Optional condition to filter events.
+   * @param args.options.offset Optional pagination offset.
+   * @param args.options.limit Optional maximum number of events to return.
+   * @param args.options.orderBy Optional ordering of the results.
+   *
+   * @returns GetEventsQuery response type containing the events.
    *
-   * An optional `where` can be passed in to filter out the response.
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    * @example
-   * const events = await aptos.getEvents()
-   * // with filtering
-   * const events = await aptos.getEvents({options: { where: { account_address: { _eq: "0x123" } } }});
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Retrieve all events
+   *   const events = await aptos.getEvents();
+   *
+   *   // Retrieve events with filtering by account address
+   *   const whereCondition = {
+   *     account_address: { _eq: "0x123" }, // replace with a real account address
+   *   };
+   *   const filteredEvents = await aptos.getEvents({
+   *     options: { where: whereCondition },
+   *   });
    *
-   * @returns GetEventsQuery response type
+   *   console.log(events);
+   *   console.log(filteredEvents);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getEvents(args?: {
     minimumLedgerVersion?: AnyNumber;

package/src/api/faucet.ts

@@ -12,19 +12,56 @@ import { ProcessorType } from "../utils";
  * A class to query all `Faucet` related queries on Aptos.
  */
 export class Faucet {
+  /**
+   * Initializes a new instance of the Aptos client with the specified configuration.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Aptos client
+   *     const config = new AptosConfig({ network: Network.TESTNET }); // specify your own network if needed
+   *
+   *     // Initialize the Aptos client with the configuration
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(readonly config: AptosConfig) {}
 
   /**
-   * This creates an account if it does not exist and mints the specified amount of
-   * coins into that account
+   * This function creates an account if it does not exist and mints the specified amount of coins into that account.
+   *
+   * @param args - The arguments for funding the account.
+   * @param args.accountAddress - The address of the account to fund.
+   * @param args.amount - The amount of tokens to fund the account with.
+   * @param args.options - Configuration options for waiting for the transaction.
+   * @returns Transaction hash of the transaction that funded the account.
    *
    * @example
-   * const transaction = await aptos.fundAccount({accountAddress:"0x123", amount: 100})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Fund an account with a specified amount of tokens
+   *   const transaction = await aptos.fundAccount({
+   *     accountAddress: "0x1", // replace with your account address
+   *     amount: 100,
+   *   });
    *
-   * @param args.accountAddress Address of the account to fund
-   * @param args.amount Amount of tokens to fund the account with
-   * @param args.options Configuration options for waitForTransaction
-   * @returns Transaction hash of the transaction that funded the account
+   *   console.log("Transaction hash:", transaction.hash);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async fundAccount(args: {
     accountAddress: AccountAddressInput;

package/src/api/fungibleAsset.ts

@@ -29,21 +29,56 @@ import { InputGenerateTransactionOptions } from "../transactions";
 import { SimpleTransaction } from "../transactions/instances/simpleTransaction";
 
 /**
- * A class to query all `FungibleAsset` related queries on Aptos.
+ * A class for querying and managing fungible asset-related operations on the Aptos blockchain.
  */
 export class FungibleAsset {
+  /**
+   * Initializes a new instance of the Aptos class with the provided configuration.
+   * This allows you to interact with the Aptos blockchain using the specified network settings.
+   *
+   * @param config - The configuration settings for connecting to the Aptos network.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Aptos client
+   *     const config = new AptosConfig({ network: Network.TESTNET }); // Specify your own network if needed
+   *
+   *     // Initialize the Aptos client with the configuration
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(readonly config: AptosConfig) {}
 
   /**
    * Queries all fungible asset metadata.
    *
+   * @param args Optional parameters for the query.
+   * @param args.minimumLedgerVersion Optional ledger version to sync up to before querying.
+   * @param args.options Optional configuration for pagination and filtering.
+   *
+   * @returns A list of fungible asset metadata.
+   *
    * @example
-   * const fungibleAsset = await aptos.getFungibleAssetMetadata()
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
-   * @param args.options Optional configuration for pagination and filtering
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @returns A list of fungible asset metadata
+   * async function runExample() {
+   *   // Fetching fungible asset metadata
+   *   const fungibleAssets = await aptos.getFungibleAssetMetadata();
+   *   console.log(fungibleAssets);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getFungibleAssetMetadata(args?: {
     minimumLedgerVersion?: AnyNumber;
@@ -58,20 +93,32 @@ export class FungibleAsset {
   }
 
   /**
-   * Queries a fungible asset metadata by the asset type
+   * Queries the fungible asset metadata for a specific asset type.
+   * This function helps retrieve detailed information about a fungible asset based on its type.
+   *
+   * @param args - The parameters for the query.
+   * @param args.assetType - The asset type of the fungible asset, e.g., "0x1::aptos_coin::AptosCoin" for Aptos Coin.
+   * @param args.minimumLedgerVersion - Optional ledger version to sync up to before querying.
    *
-   * This query returns the fungible asset metadata for a specific fungible asset.
+   * @returns A fungible asset metadata item.
    *
    * @example
-   * const fungibleAsset = await aptos.getFungibleAssetMetadataByAssetType({assetType:"0x123::test_coin::TestCoin"})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
-   * @param args.assetType The asset type of the fungible asset.
-   * e.g
-   * "0x1::aptos_coin::AptosCoin" for Aptos Coin
-   * "0xc2948283c2ce03aafbb294821de7ee684b06116bb378ab614fa2de07a99355a8" - address format if this is fungible asset
+   * async function runExample() {
+   *   // Retrieve fungible asset metadata by asset type
+   *   const fungibleAsset = await aptos.getFungibleAssetMetadataByAssetType({
+   *     assetType: "0x1::aptos_coin::AptosCoin" // replace with your asset type
+   *   });
    *
-   * @returns A fungible asset metadata item
+   *   console.log(fungibleAsset);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getFungibleAssetMetadataByAssetType(args: {
     assetType: string;
@@ -95,17 +142,33 @@ export class FungibleAsset {
   }
 
   /**
-   * Queries a fungible asset metadata by the creator address
+   * Retrieves fungible asset metadata based on the creator address.
    *
-   * This query returns the fungible asset metadata for a specific fungible asset.
+   * This function allows you to query metadata for a specific fungible asset created by a given address.
+   *
+   * @param args - The parameters for the query.
+   * @param args.creatorAddress - The creator address of the fungible asset.
+   * @param args.minimumLedgerVersion - Optional ledger version to sync up to before querying.
+   *
+   * @returns A fungible asset metadata item.
    *
    * @example
-   * const fungibleAsset = await aptos.getFungibleAssetMetadataByCreatorAddress({creatorAddress:"0x123"})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
-   * @param args.creatorAddress The creator address of the fungible asset.
+   * async function runExample() {
+   *   // Retrieve fungible asset metadata by creator address
+   *   const fungibleAsset = await aptos.getFungibleAssetMetadataByCreatorAddress({
+   *     creatorAddress: "0x123", // replace with a real creator address
+   *   });
    *
-   * @returns A fungible asset metadata item
+   *   console.log(fungibleAsset);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getFungibleAssetMetadataByCreatorAddress(args: {
     creatorAddress: AccountAddressInput;
@@ -129,15 +192,27 @@ export class FungibleAsset {
   }
 
   /**
-   * Queries all fungible asset activities
+   * Queries all fungible asset activities and returns a list of their metadata.
+   *
+   * @param args Optional parameters for the query.
+   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying.
+   * @param args.options Optional configuration for pagination and filtering.
+   * @returns A list of fungible asset metadata.
    *
    * @example
-   * const fungibleAssetActivities = await aptos.getFungibleAssetActivities()
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
-   * @param args.options Optional configuration for pagination and filtering
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @returns A list of fungible asset metadata
+   * async function runExample() {
+   *   // Fetching fungible asset activities
+   *   const fungibleAssetActivities = await aptos.getFungibleAssetActivities();
+   *   console.log(fungibleAssetActivities);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getFungibleAssetActivities(args?: {
     minimumLedgerVersion?: AnyNumber;
@@ -152,15 +227,29 @@ export class FungibleAsset {
   }
 
   /**
-   * Queries all fungible asset balances
+   * Queries all fungible asset balances.
+   *
+   * @param args Optional parameters for the query.
+   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying.
+   * @param args.options Optional configuration for pagination and filtering.
+   *
+   * @returns A list of fungible asset metadata.
    *
    * @example
-   * const fungibleAssetBalances = await aptos.getCurrentFungibleAssetBalances()
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
-   * @param args.options Optional configuration for pagination and filtering
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @returns A list of fungible asset metadata
+   * async function runExample() {
+   *   // Fetching current fungible asset balances
+   *   const fungibleAssetBalances = await aptos.getCurrentFungibleAssetBalances();
+   *
+   *   console.log(fungibleAssetBalances);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getCurrentFungibleAssetBalances(args?: {
     minimumLedgerVersion?: AnyNumber;
@@ -175,25 +264,39 @@ export class FungibleAsset {
   }
 
   /**
-   * Transfer `amount` of fungible asset from sender's primary store to recipient's primary store.
+   * Transfer a specified amount of fungible asset from the sender's primary store to the recipient's primary store.
+   * This method allows you to transfer any fungible asset, including fungible tokens.
+   *
+   * @param args - The arguments for the transfer operation.
+   * @param args.sender - The sender account.
+   * @param args.fungibleAssetMetadataAddress - The fungible asset account address. For example, if you’re transferring USDT,
+   * this would be the USDT address.
+   * @param args.recipient - The recipient account address.
+   * @param args.amount - The number of assets to transfer.
+   * @param args.options - Optional parameters for generating the transaction.
    *
-   * Use this method to transfer any fungible asset including fungible token.
+   * @returns A SimpleTransaction that can be simulated or submitted to the chain.
    *
    * @example
-   * const transaction = await aptos.transferFungibleAsset({
-   *  sender: alice,
-   *  fungibleAssetMetadataAddress: "0x123",
-   *  recipient: "0x456",
-   *  amount: 5
-   * })
-   *
-   * @param sender The sender account
-   * @param fungibleAssetMetadataAddress The fungible asset account address.
-   * For example if you’re transferring USDT this would be the USDT address
-   * @param recipient The recipient account address
-   * @param amount Number of assets to transfer
-   *
-   * @returns A SimpleTransaction that can be simulated or submitted to chain.
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Transfer fungible asset from sender to recipient
+   *   const transaction = await aptos.transferFungibleAsset({
+   *     sender: Account.generate(), // replace with a real sender account
+   *     fungibleAssetMetadataAddress: "0x123", // replace with a real fungible asset address
+   *     recipient: "0x456", // replace with a real recipient account
+   *     amount: 5
+   *   });
+   *
+   *   console.log(transaction);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async transferFungibleAsset(args: {
     sender: Account;