@aptos-labs/ts-sdk 1.29.1 → 1.30.0

package/src/api/general.ts

@@ -25,35 +25,61 @@ import { ProcessorType } from "../utils/const";
 import { InputViewFunctionData, InputViewFunctionJsonData } from "../transactions";
 
 /**
- * A class to query all `General` Aptos related queries
+ * A class to query various Aptos-related information and perform operations on the Aptos blockchain.
  */
 export class General {
   readonly config: AptosConfig;
 
+  /**
+   * Initializes a new instance of the Aptos client with the specified configuration.
+   * This allows users to interact with the Aptos blockchain using the provided settings.
+   *
+   * @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.
+   *
+   * @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 the network
+   *         nodeUrl: "https://testnet.aptos.dev" // specify the node URL
+   *     });
+   *
+   *     // Initialize the Aptos client with the configuration
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(config: AptosConfig) {
     this.config = config;
   }
 
   /**
-   * Queries for the Aptos ledger info
+   * Queries for the Aptos ledger information.
    *
-   * @returns Aptos Ledger Info
+   * @returns The Aptos Ledger Info, which includes details such as chain ID, epoch, and ledger version.
    *
    * @example
-   * const ledgerInfo = await aptos.getLedgerInfo()
-   * // an example of the returned data
-   * ```
-   * {
-   * "chain_id": 4,
-   * "epoch": "8",
-   * "ledger_version": "714",
-   * "oldest_ledger_version": "0",
-   * "ledger_timestamp": "1694695496521775",
-   * "node_role": "validator",
-   * "oldest_block_height": "0",
-   * "block_height": "359",
-   * "git_hash": "c82193f36f4e185fed9f68c4ad21f6c6dd390c6e"
+   * ```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() {
+   *   // Fetching the ledger information
+   *   const ledgerInfo = await aptos.getLedgerInfo();
+   *
+   *   console.log(ledgerInfo);
    * }
+   * runExample().catch(console.error);
    * ```
    */
   async getLedgerInfo(): Promise<LedgerInfo> {
@@ -61,12 +87,24 @@ export class General {
   }
 
   /**
-   * Queries for the chain id
+   * Retrieves the chain ID of the Aptos blockchain.
    *
    * @example
-   * const chainId = await aptos.getChainId()
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @returns The chain id
+   * async function runExample() {
+   *   // Fetching the chain ID
+   *   const chainId = await aptos.getChainId();
+   *   console.log("Chain ID:", chainId);
+   * }
+   * runExample().catch(console.error);
+   *
+   * @returns The chain ID of the Aptos blockchain.
+   * ```
    */
   async getChainId(): Promise<number> {
     const result = await this.getLedgerInfo();
@@ -74,15 +112,29 @@ export class General {
   }
 
   /**
-   * Queries for block by transaction version
+   * Retrieves block information by the specified ledger version.
+   *
+   * @param args - The arguments for retrieving the block.
+   * @param args.ledgerVersion - The ledger version to lookup block information for.
+   * @param args.options - Optional parameters for the request.
+   * @param args.options.withTransactions - If set to true, include all transactions in the block.
+   *
+   * @returns Block information with optional transactions.
    *
    * @example
-   * const block = await aptos.getBlockByVersion({ledgerVersion:5})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.ledgerVersion Ledger version to lookup block information for
-   * @param args.options.withTransactions If set to true, include all transactions in the block
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @returns Block information with optional transactions
+   * async function runExample() {
+   *   // Retrieve block information for a specific ledger version
+   *   const block = await aptos.getBlockByVersion({ ledgerVersion: 5 });
+   *   console.log(block);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getBlockByVersion(args: {
     ledgerVersion: AnyNumber;
@@ -95,15 +147,29 @@ export class General {
   }
 
   /**
-   * Get block by block height
+   * Retrieve a block by its height, allowing for the inclusion of transactions if specified.
+   *
+   * @param args - The parameters for the block retrieval.
+   * @param args.blockHeight - The block height to look up, starting at 0.
+   * @param args.options - Optional settings for the retrieval.
+   * @param args.options.withTransactions - If set to true, includes all transactions in the block.
+   *
+   * @returns The block with optional transactions included.
    *
    * @example
-   * const block = await aptos.getBlockByVersion({blockHeight:5})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.blockHeight Block height to lookup.  Starts at 0
-   * @param args.options.withTransactions If set to true, include all transactions in the block
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @returns Block with optional transactions
+   * async function runExample() {
+   *   // Retrieve the block at height 5, including transactions
+   *   const block = await aptos.getBlockByHeight({ blockHeight: 5, options: { withTransactions: true } });
+   *   console.log(block);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getBlockByHeight(args: { blockHeight: AnyNumber; options?: { withTransactions?: boolean } }): Promise<Block> {
     return getBlockByHeight({ aptosConfig: this.config, ...args });
@@ -156,13 +222,27 @@ export class General {
   }
 
   /**
-   * Queries top user transactions
+   * Queries the top user transactions based on the specified limit.
+   *
+   * @param args - The arguments for querying top user transactions.
+   * @param args.limit - The number of transactions to return.
+   * @returns GetChainTopUserTransactionsResponse
    *
    * @example
-   * const topUserTransactions = await aptos.getChainTopUserTransactions({limit:5})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.limit The number of transactions to return
-   * @returns GetChainTopUserTransactionsResponse
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Fetch the top user transactions with a limit of 5
+   *   const topUserTransactions = await aptos.getChainTopUserTransactions({ limit: 5 });
+   *
+   *   console.log(topUserTransactions);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getChainTopUserTransactions(args: { limit: number }): Promise<GetChainTopUserTransactionsResponse> {
     return getChainTopUserTransactions({
@@ -172,22 +252,35 @@ export class General {
   }
 
   /**
-   * A generic function for retrieving data from Aptos Indexer.
-   * For more detailed queries specification see
-   * {@link https://cloud.hasura.io/public/graphiql?endpoint=https://api.mainnet.aptoslabs.com/v1/graphql}
+   * Retrieves data from the Aptos Indexer using a GraphQL query.
+   * This function allows you to execute complex queries to fetch specific data from the Aptos blockchain.
+   *
+   * @param args.query.query - A GraphQL query string.
+   * @param args.query.variables - The variables for the query (optional).
+   *
+   * @return The provided T type.
    *
    * @example
-   * const topUserTransactions = await aptos.queryIndexer({
-   *  query: `query MyQuery {
-   *   ledger_infos {
-   *     chain_id
-   *   }}`;
-   * })
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param args.query.query A GraphQL query
-   * @param args.query.variables The variables for the query
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @return The provided T type
+   * async function runExample() {
+   *   // Querying the Aptos Indexer for ledger information
+   *   const topUserTransactions = await aptos.queryIndexer({
+   *     query: `query MyQuery {
+   *       ledger_infos {
+   *         chain_id
+   *       }
+   *     }`
+   *   });
+   *
+   *   console.log(topUserTransactions);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async queryIndexer<T extends {}>(args: { query: GraphqlQuery }): Promise<T> {
     return queryIndexer<T>({
@@ -197,12 +290,23 @@ export class General {
   }
 
   /**
-   * Queries for the last successful indexer version
-   *
-   * This is useful to tell what ledger version the indexer is updated to, as it can be behind the full nodes.
+   * Queries for the last successful indexer version, providing insight into the ledger version the indexer is updated to, which
+   * may lag behind the full nodes.
    *
    * @example
-   * const version = await aptos.getIndexerLastSuccessVersion()
+   * ```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() {
+   *   // Get the last successful indexer version
+   *   const version = await aptos.getIndexerLastSuccessVersion();
+   *   console.log(`Last successful indexer version: ${version}`);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getIndexerLastSuccessVersion(): Promise<bigint> {
     return getIndexerLastSuccessVersion({ aptosConfig: this.config });
@@ -211,11 +315,23 @@ export class General {
   /**
    * Query the processor status for a specific processor type.
    *
+   * @param processorType The processor type to query.
+   * @returns The status of the specified processor type.
+   *
    * @example
-   * const status = await aptos.getProcessorStatus({processorType:"account_transactions_processor"})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * @param processorType The processor type to query
-   * @returns
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Get the processor status for the account transactions processor
+   *   const status = await aptos.getProcessorStatus("account_transactions_processor");
+   *   console.log(status);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getProcessorStatus(processorType: ProcessorType): Promise<GetProcessorStatusResponse[0]> {
     return getProcessorStatus({ aptosConfig: this.config, processorType });

package/src/api/keyless.ts

@@ -18,19 +18,65 @@ import { AptosConfig } from "./aptosConfig";
  * A class to query all `Keyless` related queries on Aptos.
  *
  * More documentation on how to integrate Keyless Accounts see the below
- * https://aptos.dev/guides/keyless-accounts/#aptos-keyless-integration-guide
+ * [Aptos Keyless Integration Guide](https://aptos.dev/guides/keyless-accounts/#aptos-keyless-integration-guide).
  */
 export class Keyless {
+  /**
+   * 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 new configuration for the Aptos client
+   *     const config = new AptosConfig({ network: Network.TESTNET }); // Specify your desired network
+   *
+   *     // 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) {}
 
   /**
    * Fetches the pepper from the Aptos pepper service API.
    *
-   * @param args.jwt JWT token
-   * @param args.ephemeralKeyPair the EphemeralKeyPair used to generate the nonce in the JWT token
-   * @param args.derivationPath a derivation path used for creating multiple accounts per user via the BIP-44 standard. Defaults
+   * @param args - The arguments for fetching the pepper.
+   * @param args.jwt - JWT token.
+   * @param args.ephemeralKeyPair - The EphemeralKeyPair used to generate the nonce in the JWT token.
+   * @param args.derivationPath - A derivation path used for creating multiple accounts per user via the BIP-44 standard. Defaults
    * to "m/44'/637'/0'/0'/0".
    * @returns The pepper which is a Uint8Array of length 31.
+   *
+   * @example
+   * ```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() {
+   *   const ephemeralKeyPair = new EphemeralKeyPair(); // create a new ephemeral key pair
+   *   const jwt = "your_jwt_token"; // replace with a real JWT token
+   *
+   *   // Fetching the pepper using the provided JWT and ephemeral key pair
+   *   const pepper = await aptos.getPepper({
+   *     jwt,
+   *     ephemeralKeyPair,
+   *     // derivationPath: "m/44'/637'/0'/0'/0" // specify your own if needed
+   *   });
+   *
+   *   console.log("Fetched pepper:", pepper);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getPepper(args: {
     jwt: string;
@@ -43,12 +89,37 @@ export class Keyless {
   /**
    * Fetches a proof from the Aptos prover service API.
    *
-   * @param args.jwt JWT token
-   * @param args.ephemeralKeyPair the EphemeralKeyPair used to generate the nonce in the JWT token
-   * @param args.uidKey a key in the JWT token to use to set the uidVal in the IdCommitment
-   * @param args.pepper the pepper used for the account.  If not provided it will be fetched from the Aptos pepper service
+   * @param args - The arguments for fetching the proof.
+   * @param args.jwt - JWT token.
+   * @param args.ephemeralKeyPair - The EphemeralKeyPair used to generate the nonce in the JWT token.
+   * @param args.pepper - The pepper used for the account. If not provided, it will be fetched from the Aptos pepper service.
+   * @param args.uidKey - A key in the JWT token to use to set the uidVal in the IdCommitment.
    *
    * @returns The proof which is represented by a ZeroKnowledgeSig.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network, EphemeralKeyPair, getPepper } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   const jwt = "your_jwt_token"; // replace with a real JWT token
+   *   const ephemeralKeyPair = new EphemeralKeyPair(); // create a new ephemeral key pair
+   *
+   *   // Fetch the proof using the getProof function
+   *   const proof = await aptos.getProof({
+   *     jwt,
+   *     ephemeralKeyPair,
+   *     pepper: await getPepper({}), // fetch the pepper if not provided
+   *     uidKey: "sub", // specify the uid key
+   *   });
+   *
+   *   console.log("Fetched proof:", proof);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getProof(args: {
     jwt: string;
@@ -77,19 +148,44 @@ export class Keyless {
   }): Promise<FederatedKeylessAccount>;
 
   /**
-   * Derives the Keyless Account from the JWT token and corresponding EphemeralKeyPair.  It will lookup the pepper from
-   * the pepper service if not explicitly provided.  It will compute the proof via the proving service.  It will ch
-   *
-   * @param args.jwt JWT token
-   * @param args.ephemeralKeyPair the EphemeralKeyPair used to generate the nonce in the JWT token
-   * @param args.jwkAddress the where the JWKs used to verify signatures are found.  Setting the value derives a FederatedKeylessAccount
-   * @param args.uidKey a key in the JWT token to use to set the uidVal in the IdCommitment
-   * @param args.pepper the pepper
-   * @param args.proofFetchCallback a callback function that if set, the fetch of the proof will be done in the background. Once
-   * fetching finishes the callback function will be called.  This should be used to provide a more responsive user experience as now
-   * they are not blocked on fetching the proof. Thus the function will return much more quickly.
-   *
-   * @returns A KeylessAccount that can be used to sign transactions
+   * Derives a Keyless Account from the provided JWT token and corresponding EphemeralKeyPair. This function computes the proof
+   * via the proving service and can fetch the pepper from the pepper service if not explicitly provided.
+   *
+   * @param args - The arguments required to derive the Keyless Account.
+   * @param args.jwt - The JWT token used for deriving the account.
+   * @param args.ephemeralKeyPair - The EphemeralKeyPair used to generate the nonce in the JWT token.
+   * @param args.jwkAddress - The address the where the JWKs used to verify signatures are found.  Setting the value derives a
+   * FederatedKeylessAccount
+   * @param args.uidKey - An optional key in the JWT token to set the uidVal in the IdCommitment.
+   * @param args.pepper - An optional pepper value.
+   * @param args.proofFetchCallback - An optional callback function for fetching the proof in the background, allowing for a more
+   * responsive user experience.
+   *
+   * @returns A KeylessAccount that can be used to sign transactions.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network, deriveKeylessAccount } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   const jwt = "your_jwt_token"; // replace with a real JWT token
+   *   const ephemeralKeyPair = new EphemeralKeyPair(); // create a new ephemeral key pair
+   *
+   *   // Deriving the Keyless Account
+   *   const keylessAccount = await deriveKeylessAccount({
+   *     jwt,
+   *     ephemeralKeyPair,
+   *     uidKey: "your_uid_key", // optional
+   *     pepper: "your_pepper", // optional
+   *   });
+   *
+   *   console.log("Keyless Account derived:", keylessAccount);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async deriveKeylessAccount(args: {
     jwt: string;

package/src/api/object.ts

@@ -12,18 +12,62 @@ import { getObjectDataByObjectAddress } from "../internal/object";
  * A class to query all `Object` related queries on Aptos.
  */
 export class AptosObject {
+  /**
+   * Creates an instance of the Aptos client with the provided configuration.
+   * This allows interaction with the Aptos blockchain using the specified settings.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   * @param config.network - The network to connect to (e.g., mainnet, testnet).
+   * @param config.nodeUrl - The URL of the Aptos node to connect to.
+   * @param config.faucetUrl - The URL of the faucet for funding accounts (optional).
+   *
+   * @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 the desired network
+   *         nodeUrl: "https://testnet.aptos.dev", // Replace with your node URL
+   *     });
+   *
+   *     // Create an instance of the Aptos client
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client created successfully", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(readonly config: AptosConfig) {}
 
   /**
-   * Fetch the object data based on the oabject address
+   * Fetches the object data based on the specified object address.
+   *
+   * @param args.objectAddress - The object address to retrieve data for.
+   * @param args.minimumLedgerVersion - Optional minimum ledger version to wait for.
+   * @param args.options - Optional configuration options for pagination and ordering.
+   *
+   * @returns The object data corresponding to the provided address.
    *
    * @example
-   * const object = await aptos.getObjectDataByObjectAddress({objectAddress:"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.objectAddress The object address
-   * @param args.options Configuration options for waitForTransaction
+   * async function runExample() {
+   *   // Fetching object data by object address
+   *   const objectData = await aptos.getObjectDataByObjectAddress({
+   *     objectAddress: "0x1", // replace with a real object address
+   *   });
    *
-   * @returns The object data
+   *   console.log(objectData);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getObjectDataByObjectAddress(args: {
     objectAddress: AccountAddressInput;