Introduce table function API. Add getTableItemsData and `getTable…

…ItemsMetadata` queries (#385)

Introduce table function API wand add getTableItemsData and getTableItemsMetadata queries

CHANGELOG.md

@@ -10,6 +10,9 @@ All notable changes to the Aptos TypeScript SDK will be captured in this file. T
 - Separates the signing message functionality out of the transactionSubmission.ts file
 - Adds an Account implementation for MultiKey accounts
 - Upgrade `@aptos-labs/aptos-cli` package to version `0.1.7`
+- Introduce `table` function APIs
+- Add `getTableItemsData` and `getTableItemsMetadata` API queries
+- Add `decimal` prop back to `current_token_ownerships_v2.current_token_data` response
 
 # 1.14.0 (2024-05-09)
 

src/api/aptos.ts

@@ -12,6 +12,7 @@ import { General } from "./general";
 import { ANS } from "./ans";
 import { Staking } from "./staking";
 import { Transaction } from "./transaction";
+import { Table } from "./table";
 
 /**
  * This class is the main entry point into Aptos's
@@ -47,6 +48,8 @@ export class Aptos {
 
   readonly transaction: Transaction;
 
+  readonly table: Table;
+
   constructor(settings?: AptosConfig) {
     this.config = new AptosConfig(settings);
     this.account = new Account(this.config);
@@ -59,6 +62,7 @@ export class Aptos {
     this.general = new General(this.config);
     this.staking = new Staking(this.config);
     this.transaction = new Transaction(this.config);
+    this.table = new Table(this.config);
   }
 }
 
@@ -74,6 +78,7 @@ export interface Aptos
     FungibleAsset,
     General,
     Staking,
+    Table,
     Omit<Transaction, "build" | "simulate" | "submit" | "batch"> {}
 
 /**
@@ -107,3 +112,4 @@ applyMixin(Aptos, FungibleAsset, "fungibleAsset");
 applyMixin(Aptos, General, "general");
 applyMixin(Aptos, Staking, "staking");
 applyMixin(Aptos, Transaction, "transaction");
+applyMixin(Aptos, Table, "table");

src/api/general.ts

@@ -9,7 +9,6 @@ import {
   getIndexerLastSuccessVersion,
   getLedgerInfo,
   getProcessorStatus,
-  getTableItem,
   queryIndexer,
 } from "../internal/general";
 import { view } from "../internal/view";
@@ -22,7 +21,6 @@ import {
   LedgerInfo,
   LedgerVersionArg,
   MoveValue,
-  TableItemRequest,
 } from "../types";
 import { ProcessorType } from "../utils/const";
 import { InputViewFunctionData } from "../transactions";
@@ -112,30 +110,6 @@ export class General {
     return getBlockByHeight({ aptosConfig: this.config, ...args });
   }
 
-  /**
-   * 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
-   *
-   * @returns Table item value rendered in JSON
-   */
-  async getTableItem<T>(args: { handle: string; data: TableItemRequest; options?: LedgerVersionArg }): Promise<T> {
-    return getTableItem<T>({ aptosConfig: this.config, ...args });
-  }
-
   /**
    * Queries for a Move view function
    * @param args.payload Payload for the view function

src/api/table.ts

@@ -0,0 +1,108 @@
+import { getTableItem, getTableItemsData, getTableItemsMetadata } from "../internal/table";
+import {
+  TableItemRequest,
+  LedgerVersionArg,
+  AnyNumber,
+  PaginationArgs,
+  WhereArg,
+  OrderByArg,
+  GetTableItemsDataResponse,
+  GetTableItemsMetadataResponse,
+} from "../types";
+import { TableItemsBoolExp, TableMetadatasBoolExp } from "../types/generated/types";
+import { ProcessorType } from "../utils";
+import { AptosConfig } from "./aptosConfig";
+import { waitForIndexerOnVersion } from "./utils";
+
+/**
+ * A class to query all `Table` Aptos related queries
+ */
+export class Table {
+  readonly config: AptosConfig;
+
+  constructor(config: AptosConfig) {
+    this.config = config;
+  }
+
+  /**
+   * 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.
+   *
+   * Note, this query calls the fullnode server
+   *
+   * @example https://api.devnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::coin::CoinInfo%3C0x1::aptos_coin::AptosCoin%3E
+   * const tableItem = await aptos.getTableItem({
+   *  handle: "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca",
+   *  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
+   *
+   * @returns Table item value rendered in JSON
+   */
+  async getTableItem<T>(args: { handle: string; data: TableItemRequest; options?: LedgerVersionArg }): Promise<T> {
+    return getTableItem<T>({ aptosConfig: this.config, ...args });
+  }
+
+  /**
+   * Queries for a table items data.
+   *
+   * Optional `options.where` param can be passed to filter the response.
+   *
+   * Note, this query calls the indexer server
+   *
+   * @example
+   * const data = await aptos.getTableItemsData({
+   *  options: { where: {
+   *      table_handle: { _eq: "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca" },
+   *      transaction_version: { _eq: "0" }
+   *    }
+   *  },
+   * });
+   *
+   * @returns GetTableItemsDataResponse
+   */
+  async getTableItemsData(args: {
+    minimumLedgerVersion?: AnyNumber;
+    options?: PaginationArgs & WhereArg<TableItemsBoolExp> & OrderByArg<GetTableItemsDataResponse[0]>;
+  }): Promise<GetTableItemsDataResponse> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.DEFAULT,
+    });
+    return getTableItemsData({ aptosConfig: this.config, ...args });
+  }
+
+  /**
+   * Queries for a table items metadata.
+   *
+   * Optional `options.where` param can be passed to filter the response.
+   *
+   * Note, this query calls the indexer server
+   *
+   * @example
+   * const data = await aptos.getTableItemsMetadata({
+   *  options: { where: { handle: { _eq: "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca" } } },
+   * });
+   *
+   * @returns GetTableItemsMetadataResponse
+   */
+  async getTableItemsMetadata(args: {
+    minimumLedgerVersion?: AnyNumber;
+    options?: PaginationArgs & WhereArg<TableMetadatasBoolExp> & OrderByArg<GetTableItemsMetadataResponse[0]>;
+  }): Promise<GetTableItemsMetadataResponse> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.DEFAULT,
+    });
+    return getTableItemsMetadata({ aptosConfig: this.config, ...args });
+  }
+}

src/internal/account.ts

@@ -13,7 +13,7 @@ import { AptosApiError, getAptosFullNode, paginateWithCursor } from "../client";
 import { AccountAddress, AccountAddressInput } from "../core/accountAddress";
 import { Account } from "../account";
 import { AnyPublicKey, Ed25519PublicKey, PrivateKey } from "../core/crypto";
-import { getTableItem, queryIndexer } from "./general";
+import { queryIndexer } from "./general";
 import {
   AccountData,
   GetAccountCoinsDataResponse,
@@ -54,6 +54,7 @@ import {
 import { memoizeAsync } from "../utils/memoize";
 import { Secp256k1PrivateKey, AuthenticationKey, Ed25519PrivateKey } from "../core";
 import { CurrentFungibleAssetBalancesBoolExp } from "../types/generated/types";
+import { getTableItem } from "./table";
 
 export async function getInfo(args: {
   aptosConfig: AptosConfig;

src/internal/general.ts

@@ -9,16 +9,14 @@
  */
 
 import { AptosConfig } from "../api/aptosConfig";
-import { getAptosFullNode, postAptosFullNode, postAptosIndexer } from "../client";
+import { getAptosFullNode, postAptosIndexer } from "../client";
 import {
   AnyNumber,
   Block,
   GetChainTopUserTransactionsResponse,
   GetProcessorStatusResponse,
   GraphqlQuery,
   LedgerInfo,
-  LedgerVersionArg,
-  TableItemRequest,
 } from "../types";
 import { GetChainTopUserTransactionsQuery, GetProcessorStatusQuery } from "../types/generated/operations";
 import { GetChainTopUserTransactions, GetProcessorStatus } from "../types/generated/queries";
@@ -64,23 +62,6 @@ export async function getBlockByHeight(args: {
   return data;
 }
 
-export async function getTableItem<T>(args: {
-  aptosConfig: AptosConfig;
-  handle: string;
-  data: TableItemRequest;
-  options?: LedgerVersionArg;
-}): Promise<T> {
-  const { aptosConfig, handle, data, options } = args;
-  const response = await postAptosFullNode<TableItemRequest, any>({
-    aptosConfig,
-    originMethod: "getTableItem",
-    path: `tables/${handle}/item`,
-    params: { ledger_version: options?.ledgerVersion },
-    body: data,
-  });
-  return response.data as T;
-}
-
 export async function getChainTopUserTransactions(args: {
   aptosConfig: AptosConfig;
   limit: number;

src/internal/queries/currentTokenOwnershipFieldsFragment.graphql

@@ -25,6 +25,7 @@ fragment CurrentTokenOwnershipFields on current_token_ownerships_v2 {
     token_properties
     token_standard
     token_uri
+    decimals
     current_collection {
       collection_id
       collection_name

src/internal/queries/getTableItemsData.graphql

@@ -0,0 +1,15 @@
+query getTableItemsData(
+  $where_condition: table_items_bool_exp!
+  $offset: Int
+  $limit: Int
+  $order_by: [table_items_order_by!]
+) {
+  table_items(where: $where_condition, offset: $offset, limit: $limit, order_by: $order_by){
+    decoded_key
+    decoded_value
+    key
+    table_handle
+    transaction_version
+    write_set_change_index
+  }
+}

src/internal/queries/getTableItemsMetadata.graphql

@@ -0,0 +1,12 @@
+query getTableItemsMetadata(
+  $where_condition: table_metadatas_bool_exp!
+  $offset: Int
+  $limit: Int
+  $order_by: [table_metadatas_order_by!]
+) {
+  table_metadatas(where: $where_condition, offset: $offset, limit: $limit, order_by: $order_by){
+     handle
+    key_type
+    value_type
+  }
+}

src/internal/table.ts

@@ -0,0 +1,82 @@
+import { AptosConfig } from "../api/aptosConfig";
+import { postAptosFullNode } from "../client";
+import {
+  TableItemRequest,
+  LedgerVersionArg,
+  PaginationArgs,
+  WhereArg,
+  OrderByArg,
+  GetTableItemsDataResponse,
+  GetTableItemsMetadataResponse,
+} from "../types";
+import { GetTableItemsDataQuery, GetTableItemsMetadataQuery } from "../types/generated/operations";
+import { GetTableItemsData, GetTableItemsMetadata } from "../types/generated/queries";
+import { TableItemsBoolExp, TableMetadatasBoolExp } from "../types/generated/types";
+import { queryIndexer } from "./general";
+
+export async function getTableItem<T>(args: {
+  aptosConfig: AptosConfig;
+  handle: string;
+  data: TableItemRequest;
+  options?: LedgerVersionArg;
+}): Promise<T> {
+  const { aptosConfig, handle, data, options } = args;
+  const response = await postAptosFullNode<TableItemRequest, any>({
+    aptosConfig,
+    originMethod: "getTableItem",
+    path: `tables/${handle}/item`,
+    params: { ledger_version: options?.ledgerVersion },
+    body: data,
+  });
+  return response.data as T;
+}
+
+export async function getTableItemsData(args: {
+  aptosConfig: AptosConfig;
+  options?: PaginationArgs & WhereArg<TableItemsBoolExp> & OrderByArg<GetTableItemsDataResponse[0]>;
+}) {
+  const { aptosConfig, options } = args;
+
+  const graphqlQuery = {
+    query: GetTableItemsData,
+    variables: {
+      where_condition: options?.where,
+      offset: options?.offset,
+      limit: options?.limit,
+      order_by: options?.orderBy,
+    },
+  };
+
+  const data = await queryIndexer<GetTableItemsDataQuery>({
+    aptosConfig,
+    query: graphqlQuery,
+    originMethod: "getTableItemsData",
+  });
+
+  return data.table_items;
+}
+
+export async function getTableItemsMetadata(args: {
+  aptosConfig: AptosConfig;
+  options?: PaginationArgs & WhereArg<TableMetadatasBoolExp> & OrderByArg<GetTableItemsMetadataResponse[0]>;
+}): Promise<GetTableItemsMetadataResponse> {
+  const { aptosConfig, options } = args;
+
+  const graphqlQuery = {
+    query: GetTableItemsMetadata,
+    variables: {
+      where_condition: options?.where,
+      offset: options?.offset,
+      limit: options?.limit,
+      order_by: options?.orderBy,
+    },
+  };
+
+  const data = await queryIndexer<GetTableItemsMetadataQuery>({
+    aptosConfig,
+    query: graphqlQuery,
+    originMethod: "getTableItemsMetadata",
+  });
+
+  return data.table_metadatas;
+}