@aptos-labs/ts-sdk 7.3.0 → 7.5.0

package/src/internal/transaction.ts

@@ -19,14 +19,18 @@ import {
   type HexInput,
   type PaginationArgs,
   type TransactionResponse,
+  type WriteSetChange,
+  type WriteSetChangeDeleteTableItem,
+  type WriteSetChangeWriteTableItem,
   WaitForTransactionOptions,
   CommittedTransactionResponse,
   Block,
 } from "../types/index.js";
-import { DEFAULT_TXN_TIMEOUT_SEC, ProcessorType } from "../utils/const.js";
+import { DEFAULT_INDEXER_SYNC_TIMEOUT_SEC, DEFAULT_TXN_TIMEOUT_SEC, ProcessorType } from "../utils/const.js";
 import { sleep } from "../utils/helpers.js";
 import { memoizeAsync } from "../utils/memoize.js";
 import { getIndexerLastSuccessVersion, getProcessorStatus } from "./general.js";
+import { getTableItemsData, getTableItemsMetadata } from "./table.js";
 
 /**
  * Retrieve a list of transactions based on the specified options.
@@ -313,29 +317,34 @@ export async function waitForTransaction(args: {
 }
 
 /**
- * Waits for the indexer to sync up to the specified ledger version. The timeout is 3 seconds.
+ * Waits for the indexer to sync up to the specified ledger version.
  *
  * @param args - The arguments for the function.
  * @param args.aptosConfig - The configuration object for Aptos.
  * @param args.minimumLedgerVersion - The minimum ledger version that the indexer should sync to.
  * @param args.processorType - (Optional) The type of processor to check the last success version from.
+ * @param args.timeoutMilliseconds - (Optional) How long to wait before throwing. Defaults to 10 seconds.
  * @group Implementation
  */
 export async function waitForIndexer(args: {
   aptosConfig: AptosConfig;
   minimumLedgerVersion: AnyNumber;
   processorType?: ProcessorType;
+  timeoutMilliseconds?: number;
 }): Promise<void> {
   const { aptosConfig, processorType } = args;
   const minimumLedgerVersion = BigInt(args.minimumLedgerVersion);
-  const timeoutMilliseconds = 3000; // 3 seconds
+  const timeoutMilliseconds = args.timeoutMilliseconds ?? DEFAULT_INDEXER_SYNC_TIMEOUT_SEC * 1000;
   const startTime = Date.now();
   let indexerVersion = BigInt(-1);
 
   while (indexerVersion < minimumLedgerVersion) {
     // check for timeout
     if (Date.now() - startTime > timeoutMilliseconds) {
-      throw new Error("waitForLastSuccessIndexerVersionSync timeout");
+      throw new Error(
+        `waitForLastSuccessIndexerVersionSync timeout after ${timeoutMilliseconds}ms: indexer at version ${indexerVersion}, needed ${minimumLedgerVersion}. ` +
+          `If this is a faucet/fundAccount call, you can skip the wait with { waitForIndexer: false }.`,
+      );
     }
 
     if (processorType === undefined) {
@@ -400,6 +409,147 @@ export class FailedTransactionError extends Error {
   }
 }
 
+function isWriteTableItemChange(change: WriteSetChange): change is WriteSetChangeWriteTableItem {
+  return change.type === "write_table_item";
+}
+
+function isDeleteTableItemChange(change: WriteSetChange): change is WriteSetChangeDeleteTableItem {
+  return change.type === "delete_table_item";
+}
+
+function isTableItemChange(
+  change: WriteSetChange,
+): change is WriteSetChangeWriteTableItem | WriteSetChangeDeleteTableItem {
+  return isWriteTableItemChange(change) || isDeleteTableItemChange(change);
+}
+
+const INDEXER_PAGE_SIZE = 100;
+
+async function getTransactionTableItems(args: { aptosConfig: AptosConfig; transactionVersion: string }) {
+  const { aptosConfig, transactionVersion } = args;
+  const tableItems = [];
+
+  for (let offset = 0; ; offset += INDEXER_PAGE_SIZE) {
+    const page = await getTableItemsData({
+      aptosConfig,
+      options: {
+        where: {
+          transaction_version: { _eq: transactionVersion },
+        },
+        orderBy: [{ write_set_change_index: "asc" }],
+        offset,
+        limit: INDEXER_PAGE_SIZE,
+      },
+    });
+    tableItems.push(...page);
+
+    if (page.length < INDEXER_PAGE_SIZE) {
+      return tableItems;
+    }
+  }
+}
+
+async function getTableMetadataForHandles(args: { aptosConfig: AptosConfig; handles: string[] }) {
+  const { aptosConfig, handles } = args;
+  const tableMetadata = [];
+
+  for (let offset = 0; offset < handles.length; offset += INDEXER_PAGE_SIZE) {
+    const pageHandles = handles.slice(offset, offset + INDEXER_PAGE_SIZE);
+    const page = await getTableItemsMetadata({
+      aptosConfig,
+      options: {
+        where: {
+          handle: { _in: pageHandles },
+        },
+        limit: INDEXER_PAGE_SIZE,
+      },
+    });
+    tableMetadata.push(...page);
+  }
+
+  return tableMetadata;
+}
+
+/**
+ * Populates missing decoded data on a committed transaction's table item changes.
+ *
+ * Fullnodes generally return `null` for table item `data` because decoding requires
+ * table metadata. This function retrieves the decoded rows and metadata from the
+ * indexer, matches them by write-set change index, and mutates the supplied
+ * transaction with the available decoded data.
+ *
+ * Already-decoded changes are preserved. If the indexer has no matching row or
+ * metadata for a change, that change is left unchanged.
+ *
+ * @param args - The arguments for enriching the transaction.
+ * @param args.aptosConfig - The configuration for the Aptos indexer.
+ * @param args.transaction - The committed transaction to enrich.
+ * @returns The supplied transaction with available table item data populated.
+ * @group Implementation
+ */
+export async function enrichTransactionWithTableItemData<T extends CommittedTransactionResponse>(args: {
+  aptosConfig: AptosConfig;
+  transaction: T;
+}): Promise<T> {
+  const { aptosConfig, transaction } = args;
+  const missingTableItemChanges = transaction.changes
+    .filter(isTableItemChange)
+    .filter((change) => change.data === null || change.data === undefined);
+
+  if (missingTableItemChanges.length === 0) {
+    return transaction;
+  }
+
+  const handles = [...new Set(missingTableItemChanges.map((change) => change.handle))];
+  await waitForIndexer({
+    aptosConfig,
+    minimumLedgerVersion: BigInt(transaction.version),
+    processorType: ProcessorType.DEFAULT,
+  });
+
+  const [tableItems, tableMetadata] = await Promise.all([
+    getTransactionTableItems({
+      aptosConfig,
+      transactionVersion: transaction.version,
+    }),
+    getTableMetadataForHandles({
+      aptosConfig,
+      handles,
+    }),
+  ]);
+
+  const itemsByChangeIndex = new Map(tableItems.map((item) => [Number(item.write_set_change_index), item] as const));
+  const metadataByHandle = new Map(tableMetadata.map((metadata) => [metadata.handle, metadata] as const));
+
+  transaction.changes.forEach((change, changeIndex) => {
+    if (!isTableItemChange(change) || (change.data !== null && change.data !== undefined)) {
+      return;
+    }
+
+    const item = itemsByChangeIndex.get(changeIndex);
+    const metadata = metadataByHandle.get(change.handle);
+    if (item === undefined || metadata === undefined) {
+      return;
+    }
+
+    if (isWriteTableItemChange(change)) {
+      change.data = {
+        key: item.decoded_key,
+        key_type: metadata.key_type,
+        value: item.decoded_value,
+        value_type: metadata.value_type,
+      };
+    } else {
+      change.data = {
+        key: item.decoded_key,
+        key_type: metadata.key_type,
+      };
+    }
+  });
+
+  return transaction;
+}
+
 /**
  * Retrieves a block from the Aptos blockchain by its ledger version.
  * This function allows you to obtain detailed information about a specific block, including its transactions if requested.

package/src/internal/transactionSubmission.ts

@@ -510,6 +510,7 @@ function getPackagePublishAbi(): EntryFunctionABI {
  * @param args.account - The address of the account sending the transaction.
  * @param args.metadataBytes - The metadata associated with the package, represented as hexadecimal input.
  * @param args.moduleBytecode - An array of module bytecode, each represented as hexadecimal input.
+ * @param args.withFeePayer - Whether to build a sponsored transaction.
  * @param args.options - Optional parameters for generating the transaction.
  * @group Implementation
  */
@@ -518,15 +519,17 @@ export async function publicPackageTransaction(args: {
   account: AccountAddressInput;
   metadataBytes: HexInput;
   moduleBytecode: Array<HexInput>;
+  withFeePayer?: boolean;
   options?: InputGenerateTransactionOptions;
 }): Promise<SimpleTransaction> {
-  const { aptosConfig, account, metadataBytes, moduleBytecode, options } = args;
+  const { aptosConfig, account, metadataBytes, moduleBytecode, withFeePayer, options } = args;
 
   const totalByteCode = moduleBytecode.map((bytecode) => MoveVector.U8(bytecode));
 
   return generateTransaction({
     aptosConfig,
     sender: AccountAddress.from(account),
+    withFeePayer,
     data: {
       function: "0x1::code::publish_package_txn",
       functionArguments: [MoveVector.U8(metadataBytes), new MoveVector(totalByteCode)],

package/src/transactions/management/transactionWorker.ts

@@ -157,6 +157,35 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
     }
   }
 
+  /**
+   * Emits the submission result as soon as the pending transaction settles.
+   * @private
+   */
+  private trackTransactionSubmission(
+    pendingTransaction: Promise<PendingTransactionResponse>,
+    sequenceNumber: bigint,
+  ): void {
+    const notification = pendingTransaction.then(
+      (transaction) => {
+        this.addToTransactionHistory(this.sentTransactions, [transaction.hash, sequenceNumber, null]);
+        this.emit(TransactionWorkerEventsEnum.TransactionSent, {
+          message: `transaction hash ${transaction.hash} has been committed to chain`,
+          transactionHash: transaction.hash,
+        });
+      },
+      (error) => {
+        this.addToTransactionHistory(this.sentTransactions, ["rejected", sequenceNumber, error]);
+        this.emit(TransactionWorkerEventsEnum.TransactionSendFailed, {
+          message: `failed to commit transaction ${this.sentTransactions.length} with error ${error}`,
+          error,
+        });
+      },
+    );
+    // Event listeners are user-provided and must not create an unhandled rejection
+    // in this detached notification chain.
+    notification.catch(() => {});
+  }
+
   /**
    * Initializes a new instance of the class, providing a framework for receiving payloads to be processed.
    *
@@ -196,6 +225,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * This function continues to submit transactions until there are no more to process.
    *
    * @throws {Error} Throws an error if the transaction submission fails.
+   * @event TransactionWorkerEventsEnum.TransactionSent - Emitted when a transaction is sent to the chain.
+   * @event TransactionWorkerEventsEnum.TransactionSendFailed - Emitted when a transaction fails to send.
    * @group Implementation
    * @category Transactions
    */
@@ -211,6 +242,7 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
           transaction,
           signer: this.account,
         });
+        this.trackTransactionSubmission(pendingTransaction, sequenceNumber);
         await this.outstandingTransactions.enqueue([pendingTransaction, sequenceNumber]);
       }
     } catch (error: any) {
@@ -222,14 +254,11 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   }
 
   /**
-   * Reads the outstanding transaction queue and submits the transactions to the chain.
-   * This function processes each transaction, checking their status and emitting events based on whether they were successfully
-   * sent or failed.
+   * Reads the outstanding transaction queue and checks each successfully submitted transaction's execution status.
    *
    * @throws {Error} Throws an error if the process execution fails.
-   * @event TransactionWorkerEventsEnum.TransactionSent - Emitted when a transaction has been successfully committed to the chain.
-   * @event TransactionWorkerEventsEnum.TransactionSendFailed - Emitted when a transaction fails to commit, along with the error
-   * reason.
+   * @event TransactionWorkerEventsEnum.TransactionExecuted - Emitted when a transaction executes successfully.
+   * @event TransactionWorkerEventsEnum.TransactionExecutionFailed - Emitted when a transaction fails during execution.
    * @event TransactionWorkerEventsEnum.ExecutionFinish - Emitted when the execution of transactions is complete.
    * @group Implementation
    * @category Transactions
@@ -257,25 +286,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
           const sentTransaction = sentTransactions[i];
           sequenceNumber = sequenceNumbers[i];
           if (sentTransaction.status === promiseFulfilledStatus) {
-            // transaction sent to chain
-            this.addToTransactionHistory(this.sentTransactions, [sentTransaction.value.hash, sequenceNumber, null]);
             // check sent transaction execution
-            this.emit(TransactionWorkerEventsEnum.TransactionSent, {
-              message: `transaction hash ${sentTransaction.value.hash} has been committed to chain`,
-              transactionHash: sentTransaction.value.hash,
-            });
             await this.checkTransaction(sentTransaction, sequenceNumber);
-          } else {
-            // send transaction failed
-            this.addToTransactionHistory(this.sentTransactions, [
-              sentTransaction.status,
-              sequenceNumber,
-              sentTransaction.reason,
-            ]);
-            this.emit(TransactionWorkerEventsEnum.TransactionSendFailed, {
-              message: `failed to commit transaction ${this.sentTransactions.length} with error ${sentTransaction.reason}`,
-              error: sentTransaction.reason,
-            });
           }
         }
         this.emit(TransactionWorkerEventsEnum.ExecutionFinish, {

package/src/transactions/transactionBuilder/index.ts

@@ -6,3 +6,4 @@ export * from "./transactionBuilder.js";
 export * from "./remoteAbi.js";
 export * from "./signingMessage.js";
 export * from "./structEnumParser.js";
+export * from "./scriptAbi.js";