@aptos-labs/ts-sdk 1.12.2 → 1.13.0

package/src/api/digitalAsset.ts

@@ -59,6 +59,9 @@ export class DigitalAsset {
    * If, for some reason, a creator account has 2 collections with the same name in v1 and v2,
    * can pass an optional `tokenStandard` parameter to query a specific standard
    *
+   * @example
+   * const collection = await aptos.getCollectionData({creatorAddress:"0x123",collectionName:"myCollection"})
+   *
    * @param args.creatorAddress the address of the collection's creator
    * @param args.collectionName the name of the collection
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
@@ -82,6 +85,9 @@ export class DigitalAsset {
   /**
    * Queries data of a specific collection by the collection ID.
    *
+   * @example
+   * const collection = await aptos.getCollectionDataByCollectionId({collectionId:"0x123"})
+   *
    * @param args.collectionId the ID of the collection, it's the same thing as the address of the collection object
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    * @returns GetCollectionDataResponse response type
@@ -104,6 +110,9 @@ export class DigitalAsset {
    * This is the same as the collection's object address in V2, but V1 does
    * not use objects, and does not have an address
    *
+   * @example
+   * const collection = await aptos.getCollectionId({creatorAddress:"0x123",collectionName:"myCollection"})
+   *
    * @param args.creatorAddress the address of the collection's creator
    * @param args.collectionName the name of the collection
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
@@ -127,6 +136,9 @@ export class DigitalAsset {
   /**
    * Gets digital asset data given the address of a digital asset.
    *
+   * @example
+   * const digitalAsset = await aptos.getDigitalAssetData({digitalAssetAddress:"0x123"})
+   *
    * @param args.tokenAddress The address of the digital asset
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    * @returns GetTokenDataResponse containing relevant data to the digital asset.
@@ -146,6 +158,9 @@ export class DigitalAsset {
   /**
    * Gets digital asset ownership data given the address of a digital asset.
    *
+   * @example
+   * const digitalAssetOwner = await aptos.getCurrentDigitalAssetOwnership({digitalAssetAddress:"0x123"})
+   *
    * @param args.tokenAddress The address of the digital asset
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    *
@@ -166,6 +181,9 @@ export class DigitalAsset {
   /**
    * Gets the digital assets that the given address owns.
    *
+   * @example
+   * const digitalAssets = await aptos.getOwnedDigitalAssets({ownerAddress:"0x123"})
+   *
    * @param args.ownerAddress The address of the owner
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    *
@@ -187,6 +205,9 @@ export class DigitalAsset {
   /**
    * Gets the activity data given the address of a digital asset.
    *
+   * @example
+   * const digitalAssetActivity = await aptos.getDigitalAssetActivity({digitalAssetAddress:"0x123"})
+   *
    * @param args.tokenAddress The address of the digital asset
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    *
@@ -208,6 +229,14 @@ export class DigitalAsset {
   /**
    * Creates a new collection within the specified account
    *
+   * @example
+   * const transaction = await aptos.createCollectionTransaction({
+   *  creator: alice,
+   *  description: "collectionDescription",
+   *  name: "collectionName",
+   *  uri: "collection-uri.com",
+   * });
+   *
    * @param args.creator the account of the collection's creator
    * @param args.description the description of the collection
    * @param args.name the name of the collection
@@ -246,6 +275,15 @@ export class DigitalAsset {
   /**
    * Create a transaction to mint a digital asset into the creators account within an existing collection.
    *
+   * @example
+   * const transaction = await aptos.mintDigitalAssetTransaction({
+   *  creator: alice,
+   *  description: "collectionDescription",
+   *  collection: "collectionName",
+   *  name: "digitalAssetName",
+   *  uri: "digital-asset-uri.com",
+   * });
+   *
    * @param args.creator the creator of the collection
    * @param args.collection the name of the collection the digital asset belongs to
    * @param args.description the description of the digital asset
@@ -274,6 +312,13 @@ export class DigitalAsset {
    * We can transfer a digital asset only when the digital asset is not frozen
    * (i.e. owner transfer is not disabled such as for soul bound digital assets)
    *
+   * @example
+   * const transaction = await aptos.transferDigitalAssetTransaction({
+   *  sender: alice,
+   *  digitalAssetAddress: "0x123",
+   *  recipient: "0x456",
+   * });
+   *
    * @param args.sender The sender account of the current digital asset owner
    * @param args.digitalAssetAddress The digital asset address
    * @param args.recipient The recipient account address
@@ -294,6 +339,16 @@ export class DigitalAsset {
   /**
    * Mint a soul bound digital asset into a recipient's account
    *
+   * @example
+   * const transaction = await aptos.mintSoulBoundTransaction({
+   *  account: alice,
+   *  collection: "collectionName",
+   *  description: "collectionDescription",
+   *  name: "digitalAssetName",
+   *  uri: "digital-asset-uri.com",
+   *  recipient: "0x123"
+   * });
+   *
    * @param args.account The account that mints the digital asset
    * @param args.collection The collection name that the digital asset belongs to
    * @param args.description The digital asset description
@@ -312,7 +367,7 @@ export class DigitalAsset {
     description: string;
     name: string;
     uri: string;
-    recipient: AccountAddress;
+    recipient: AccountAddressInput;
     propertyKeys?: Array<string>;
     propertyTypes?: Array<PropertyType>;
     propertyValues?: Array<PropertyValue>;
@@ -324,6 +379,12 @@ export class DigitalAsset {
   /**
    * Burn a digital asset by its creator
    *
+   * @example
+   * const transaction = await aptos.burnDigitalAssetTransaction({
+   *  creator: alice,
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.creator The creator account
    * @param args.digitalAssetAddress The digital asset address
    *
@@ -341,6 +402,12 @@ export class DigitalAsset {
   /**
    * Freeze digital asset transfer ability
    *
+   * @example
+   * const transaction = await aptos.freezeDigitalAssetTransaferTransaction({
+   *  creator: alice,
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.creator The creator account
    * @param args.digitalAssetAddress The digital asset address
    *
@@ -358,6 +425,12 @@ export class DigitalAsset {
   /**
    * Unfreeze digital asset transfer ability
    *
+   * @example
+   * const transaction = await aptos.unfreezeDigitalAssetTransaferTransaction({
+   *  creator: alice,
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.creator The creator account
    * @param args.digitalAssetAddress The digital asset address
    *
@@ -375,6 +448,13 @@ export class DigitalAsset {
   /**
    * Set the digital asset description
    *
+   * @example
+   * const transaction = await aptos.setDigitalAssetDescriptionTransaction({
+   *  creator: alice,
+   *  description: "digitalAssetDescription",
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.creator The creator account
    * @param args.description The digital asset description
    * @param args.digitalAssetAddress The digital asset address
@@ -394,6 +474,13 @@ export class DigitalAsset {
   /**
    * Set the digital asset name
    *
+   * @example
+   * const transaction = await aptos.setDigitalAssetNameTransaction({
+   *  creator: alice,
+   *  name: "digitalAssetName",
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.creator The creator account
    * @param args.name The digital asset name
    * @param args.digitalAssetAddress The digital asset address
@@ -413,6 +500,13 @@ export class DigitalAsset {
   /**
    * Set the digital asset name
    *
+   * @example
+   * const transaction = await aptos.setDigitalAssetURITransaction({
+   *  creator: alice,
+   *  uri: "digital-asset-uri.com",
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.creator The creator account
    * @param args.uri The digital asset uri
    * @param args.digitalAssetAddress The digital asset address
@@ -432,6 +526,15 @@ export class DigitalAsset {
   /**
    * Add a digital asset property
    *
+   * @example
+   * const transaction = await aptos.addDigitalAssetPropertyTransaction({
+   *  creator: alice,
+   *  propertyKey: "newKey",
+   *  propertyType: "BOOLEAN",
+   *  propertyValue: true,
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.account The account that mints the digital asset
    * @param args.digitalAssetAddress The digital asset address
    * @param args.propertyKey The property key for storing on-chain properties
@@ -455,6 +558,15 @@ export class DigitalAsset {
   /**
    * Remove a digital asset property
    *
+   * @example
+   * const transaction = await aptos.removeDigitalAssetPropertyTransaction({
+   *  creator: alice,
+   *  propertyKey: "newKey",
+   *  propertyType: "BOOLEAN",
+   *  propertyValue: true,
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.account The account that mints the digital asset
    * @param args.digitalAssetAddress The digital asset address
    * @param args.propertyKey The property key for storing on-chain properties
@@ -478,6 +590,15 @@ export class DigitalAsset {
   /**
    * Update a digital asset property
    *
+   * @example
+   * const transaction = await aptos.updateDigitalAssetPropertyTransaction({
+   *  creator: alice,
+   *  propertyKey: "newKey",
+   *  propertyType: "BOOLEAN",
+   *  propertyValue: false,
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.account The account that mints the digital asset
    * @param args.digitalAssetAddress The digital asset address
    * @param args.propertyKey The property key for storing on-chain properties
@@ -501,6 +622,15 @@ export class DigitalAsset {
   /**
    * Add a typed digital asset property
    *
+   * @example
+   * const transaction = await aptos.addDigitalAssetTypedPropertyTransaction({
+   *  creator: alice,
+   *  propertyKey: "typedKey",
+   *  propertyType: "STRING",
+   *  propertyValue: "hello",
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.account The account that mints the digital asset
    * @param args.digitalAssetAddress The digital asset address
    * @param args.propertyKey The property key for storing on-chain properties
@@ -524,6 +654,15 @@ export class DigitalAsset {
   /**
    * Update a typed digital asset property
    *
+   * @example
+   * const transaction = await aptos.updateDigitalAssetTypedPropertyTransaction({
+   *  creator: alice,
+   *  propertyKey: "typedKey",
+   *  propertyType: "U8",
+   *  propertyValue: 2,
+   *  digitalAssetAddress: "0x123",
+   * });
+   *
    * @param args.account The account that mints the digital asset
    * @param args.digitalAssetAddress The digital asset address
    * @param args.propertyKey The property key for storing on-chain properties

package/src/api/event.ts

@@ -23,6 +23,9 @@ export class Event {
   /**
    * Get module events by event type
    *
+   * @example
+   * const events = await aptos.getModuleEventsByEventType({eventType:"0x1::transaction_fee::FeeStatement"})
+   *
    * @param args.eventType - The event type
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    *
@@ -44,6 +47,9 @@ export class Event {
   /**
    * Get events by creation number and an account address
    *
+   * @example
+   * const events = await aptos.getAccountEventsByCreationNumber({accountAddress:"0x123",creationNumber: 0})
+   *
    * @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
@@ -66,6 +72,9 @@ export class Event {
   /**
    * Get events by event type and an account address
    *
+   * @example
+   * const events = await aptos.getAccountEventsByEventType({accountAddress:"0x123",eventType: "0x1::transaction_fee::FeeStatement"})
+   *
    * @param args.accountAddress - The account address
    * @param args.eventType - The event type
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
@@ -90,15 +99,11 @@ export class Event {
    * Get all 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
+   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    * @example
-   * ```
-   * { where:
-   *  {
-   *   transaction_version: { _eq: 123456 },
-   *  }
-   * }
-   * ```
+   * const events = await aptos.getEvents()
+   * // with filtering
+   * const events = await aptos.getEvents({options: { where: { account_address: { _eq: "0x123" } } }});
    *
    * @returns GetEventsQuery response type
    */

package/src/api/faucet.ts

@@ -17,6 +17,9 @@ export class Faucet {
    * This creates an account if it does not exist and mints the specified amount of
    * coins into that account
    *
+   * @example
+   * const transaction = await aptos.fundAccount({accountAddress:"0x123", 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

package/src/api/fungibleAsset.ts

@@ -23,7 +23,7 @@ import {
 import { ProcessorType } from "../utils/const";
 import { AptosConfig } from "./aptosConfig";
 import { waitForIndexerOnVersion } from "./utils";
-import { Account, AccountAddress } from "../core";
+import { Account, AccountAddressInput } from "../core";
 import { InputGenerateTransactionOptions } from "../transactions";
 import { SimpleTransaction } from "../transactions/instances/simpleTransaction";
 
@@ -36,7 +36,11 @@ export class FungibleAsset {
   /**
    * Queries all fungible asset metadata.
    *
+   * @example
+   * const fungibleAsset = await aptos.getFungibleAssetMetadata()
+   *
    * @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
    */
@@ -57,6 +61,9 @@ export class FungibleAsset {
    *
    * This query returns the fungible asset metadata for a specific fungible asset.
    *
+   * @example
+   * const fungibleAsset = await aptos.getFungibleAssetMetadataByAssetType({assetType:"0x123::test_coin::TestCoin"})
+   *
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    * @param args.assetType The asset type of the fungible asset.
    * e.g
@@ -89,7 +96,11 @@ export class FungibleAsset {
   /**
    * Queries all fungible asset activities
    *
+   * @example
+   * const fungibleAssetActivities = await aptos.getFungibleAssetActivities()
+   *
    * @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
    */
@@ -108,7 +119,11 @@ export class FungibleAsset {
   /**
    * Queries all fungible asset balances
    *
+   * @example
+   * const fungibleAssetBalances = await aptos.getCurrentFungibleAssetBalances()
+   *
    * @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
    */
@@ -125,10 +140,18 @@ export class FungibleAsset {
   }
 
   /**
-   *  Transfer `amount` of fungible asset from sender's primary store to recipient's primary store.
+   * Transfer `amount` of fungible asset from sender's primary store to recipient's primary store.
    *
    * Use this method to transfer any fungible asset including fungible token.
    *
+   * @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
@@ -139,8 +162,8 @@ export class FungibleAsset {
    */
   async transferFungibleAsset(args: {
     sender: Account;
-    fungibleAssetMetadataAddress: AccountAddress;
-    recipient: AccountAddress;
+    fungibleAssetMetadataAddress: AccountAddressInput;
+    recipient: AccountAddressInput;
     amount: AnyNumber;
     options?: InputGenerateTransactionOptions;
   }): Promise<SimpleTransaction> {

package/src/api/general.ts

@@ -42,7 +42,9 @@ export class General {
    *
    * @returns Aptos Ledger Info
    *
-   * @example An example of the returned data
+   * @example
+   * const ledgerInfo = await aptos.getLedgerInfo()
+   * // an example of the returned data
    * ```
    * {
    * "chain_id": 4,
@@ -64,6 +66,9 @@ export class General {
   /**
    * Queries for the chain id
    *
+   * @example
+   * const chainId = await aptos.getChainId()
+   *
    * @returns The chain id
    */
   async getChainId(): Promise<number> {
@@ -74,6 +79,9 @@ export class General {
   /**
    * Queries for block by transaction version
    *
+   * @example
+   * const block = await aptos.getBlockByVersion({ledgerVersion:5})
+   *
    * @param args.ledgerVersion Ledger version to lookup block information for
    * @param args.options.withTransactions If set to true, include all transactions in the block
    *
@@ -92,6 +100,9 @@ export class General {
   /**
    * Get block by block height
    *
+   * @example
+   * const block = await aptos.getBlockByVersion({blockHeight:5})
+   *
    * @param args.blockHeight Block height to lookup.  Starts at 0
    * @param args.options.withTransactions If set to true, include all transactions in the block
    *
@@ -104,17 +115,21 @@ export class General {
   /**
    * Queries for a table item for a table identified by the handle and the key for the item.
    * Key and value types need to be passed in to help with key serialization and value deserialization.
+   *
+   * @example https://api.devnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::coin::CoinInfo%3C0x1::aptos_coin::AptosCoin%3E
+   * const tableItem = await aptos.getTableItem({
+   *  handle: "0x123",
+   *  data: {
+   *   key_type: "address", // Move type of table key
+   *   value_type: "u128", // Move type of table value
+   *   key: "0x619dc29a0aac8fa146714058e8dd6d2d0f3bdf5f6331907bf91f3acd81e6935" // Value of table key
+   *  },
+   * })
+   *
    * @param args.handle A pointer to where that table is stored
    * @param args.data Object that describes table item
    * @param args.options.ledgerVersion The ledger version to query, if not provided it will get the latest version
    *
-   * @example https://api.devnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::coin::CoinInfo%3C0x1::aptos_coin::AptosCoin%3E
-   * {
-   *  data.key_type = "address" // Move type of table key
-   *  data.value_type = "u128" // Move type of table value
-   *  data.key = "0x619dc29a0aac8fa146714058e8dd6d2d0f3bdf5f6331907bf91f3acd81e6935" // Value of table key
-   * }
-   *
    * @returns Table item value rendered in JSON
    */
   async getTableItem<T>(args: { handle: string; data: TableItemRequest; options?: LedgerVersionArg }): Promise<T> {
@@ -125,14 +140,15 @@ export class General {
    * Queries for a Move view function
    * @param args.payload Payload for the view function
    * @param args.options.ledgerVersion The ledger version to query, if not provided it will get the latest version
+   *
    * @example
-   * `
-   * const payload: ViewRequest = {
-   *  function: "0x1::coin::balance",
-   *  typeArguments: ["0x1::aptos_coin::AptosCoin"],
-   *  functionArguments: [accountAddress],
-   * };
-   * `
+   * const data = await aptos.view({
+   *  payload: {
+   *   function: "0x1::coin::balance",
+   *   typeArguments: ["0x1::aptos_coin::AptosCoin"],
+   *   functionArguments: [accountAddress],
+   *  }
+   * })
    *
    * @returns an array of Move values
    */
@@ -146,6 +162,9 @@ export class General {
   /**
    * Queries top user transactions
    *
+   * @example
+   * const topUserTransactions = await aptos.getChainTopUserTransactions({limit:5})
+   *
    * @param args.limit The number of transactions to return
    * @returns GetChainTopUserTransactionsResponse
    */
@@ -161,18 +180,16 @@ export class General {
    * For more detailed queries specification see
    * {@link https://cloud.hasura.io/public/graphiql?endpoint=https://api.mainnet.aptoslabs.com/v1/graphql}
    *
-   * @param args.query.query A GraphQL query
-   * @param args.query.variables The variables for the query
    * @example
-   * ```
-   * {
+   * const topUserTransactions = await aptos.queryIndexer({
    *  query: `query MyQuery {
-        ledger_infos {
-          chain_id
-        }
-      }`;
-   * }
-   * ```
+   *   ledger_infos {
+   *     chain_id
+   *   }}`;
+   * })
+   *
+   * @param args.query.query A GraphQL query
+   * @param args.query.variables The variables for the query
    *
    * @return The provided T type
    */
@@ -187,6 +204,9 @@ 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.
+   *
+   * @example
+   * const version = await aptos.getIndexerLastSuccessVersion()
    */
   async getIndexerLastSuccessVersion(): Promise<bigint> {
     return getIndexerLastSuccessVersion({ aptosConfig: this.config });
@@ -195,6 +215,9 @@ export class General {
   /**
    * Query the processor status for a specific processor type.
    *
+   * @example
+   * const status = await aptos.getProcessorStatus({processorType:"account_transactions_processor"})
+   *
    * @param processorType The processor type to query
    * @returns
    */

package/src/api/staking.ts

@@ -21,6 +21,9 @@ export class Staking {
   /**
    * Queries current number of delegators in a pool.  Throws an error if the pool is not found.
    *
+   * @example
+   * const delegators = await aptos.getNumberOfDelegators({poolAddress:"0x123"})
+   *
    * @param args.poolAddress Pool address
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    * @returns The number of delegators for the given pool
@@ -40,6 +43,9 @@ export class Staking {
   /**
    * Queries current number of delegators in a pool.  Throws an error if the pool is not found.
    *
+   * @example
+   * const delegators = await aptos.getNumberOfDelegatorsForAllPools()
+   *
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
    * @returns GetNumberOfDelegatorsForAllPoolsResponse response type
    */
@@ -58,6 +64,9 @@ export class Staking {
   /**
    * Queries delegated staking activities
    *
+   * @example
+   * const delegators = await aptos.getDelegatedStakingActivities({delegatorAddress:"0x123",poolAddress:"0x456"})
+   *
    * @param args.delegatorAddress Delegator address
    * @param args.poolAddress Pool address
    * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying