@aptos-labs/ts-sdk 0.0.7 → 0.0.8

package/src/transactions/management/accountSequenceNumber.ts

@@ -0,0 +1,186 @@
+/**
+ * A wrapper that handles and manages an account sequence number.
+ *
+ * Submit up to `maximumInFlight` transactions per account in parallel with a timeout of `sleepTime`
+ * If local assumes `maximumInFlight` are in flight, determine the actual committed state from the network
+ * If there are less than `maximumInFlight` due to some being committed, adjust the window
+ * If `maximumInFlight` are in flight, wait `sleepTime` seconds before re-evaluating
+ * If ever waiting more than `maxWaitTime` restart the sequence number to the current on-chain state
+ *
+ * Assumptions:
+ * Accounts are expected to be managed by a single AccountSequenceNumber and not used otherwise.
+ * They are initialized to the current on-chain state, so if there are already transactions in
+ * flight, they may take some time to reset.
+ * Accounts are automatically initialized if not explicitly
+ *
+ * Notes:
+ * This is co-routine safe, that is many async tasks can be reading from this concurrently.
+ * The state of an account cannot be used across multiple AccountSequenceNumber services.
+ * The synchronize method will create a barrier that prevents additional nextSequenceNumber
+ * calls until it is complete.
+ * This only manages the distribution of sequence numbers it does not help handle transaction
+ * failures.
+ * If a transaction fails, you should call synchronize and wait for timeouts.
+ */
+
+import { AptosConfig } from "../../api/aptosConfig";
+import { Account } from "../../core";
+import { getInfo } from "../../internal/account";
+import { sleep } from "../../utils/helpers";
+
+// returns `now` time in seconds
+const now = () => Math.floor(Date.now() / 1000);
+
+export class AccountSequenceNumber {
+  readonly aptosConfig: AptosConfig;
+
+  readonly account: Account;
+
+  // sequence number on chain
+  lastUncommintedNumber: bigint | null = null;
+
+  // local sequence number
+  currentNumber: bigint | null = null;
+
+  /**
+   * We want to guarantee that we preserve ordering of workers to requests.
+   *
+   * `lock` is used to try to prevent multiple coroutines from accessing a shared resource at the same time,
+   * which can result in race conditions and data inconsistency.
+   * This code actually doesn't do it though, since we aren't giving out a slot, it is still somewhat a race condition.
+   *
+   * The ideal solution is likely that each thread grabs the next number from a incremental integer.
+   * When they complete, they increment that number and that entity is able to enter the `lock`.
+   * That would guarantee ordering.
+   */
+  lock = false;
+
+  maxWaitTime: number;
+
+  maximumInFlight: number;
+
+  sleepTime: number;
+
+  constructor(
+    aptosConfig: AptosConfig,
+    account: Account,
+    maxWaitTime: number,
+    maximumInFlight: number,
+    sleepTime: number,
+  ) {
+    this.aptosConfig = aptosConfig;
+    this.account = account;
+    this.maxWaitTime = maxWaitTime;
+    this.maximumInFlight = maximumInFlight;
+    this.sleepTime = sleepTime;
+  }
+
+  /**
+   * Returns the next available sequence number for this account
+   *
+   * @returns next available sequence number
+   */
+  async nextSequenceNumber(): Promise<bigint | null> {
+    /* eslint-disable no-await-in-loop */
+    while (this.lock) {
+      await sleep(this.sleepTime);
+    }
+
+    this.lock = true;
+    let nextNumber = BigInt(0);
+    try {
+      if (this.lastUncommintedNumber === null || this.currentNumber === null) {
+        await this.initialize();
+      }
+
+      if (this.currentNumber! - this.lastUncommintedNumber! >= this.maximumInFlight) {
+        await this.update();
+
+        const startTime = now();
+        while (this.currentNumber! - this.lastUncommintedNumber! >= this.maximumInFlight) {
+          await sleep(this.sleepTime);
+          if (now() - startTime > this.maxWaitTime) {
+            /* eslint-disable no-console */
+            console.warn(
+              `Waited over 30 seconds for a transaction to commit, resyncing ${this.account.accountAddress.toString()}`,
+            );
+            await this.initialize();
+          } else {
+            await this.update();
+          }
+        }
+      }
+      nextNumber = this.currentNumber!;
+      this.currentNumber! += BigInt(1);
+    } catch (e) {
+      console.error("error in getting next sequence number for this account", e);
+    } finally {
+      this.lock = false;
+    }
+    return nextNumber;
+  }
+
+  /**
+   * Initializes this account with the sequence number on chain
+   */
+  async initialize(): Promise<void> {
+    const { sequence_number: sequenceNumber } = await getInfo({
+      aptosConfig: this.aptosConfig,
+      accountAddress: this.account.accountAddress,
+    });
+    this.currentNumber = BigInt(sequenceNumber);
+    this.lastUncommintedNumber = BigInt(sequenceNumber);
+  }
+
+  /**
+   * Updates this account sequence number with the one on-chain
+   *
+   * @returns on-chain sequence number for this account
+   */
+  async update(): Promise<bigint> {
+    const { sequence_number: sequenceNumber } = await getInfo({
+      aptosConfig: this.aptosConfig,
+      accountAddress: this.account.accountAddress,
+    });
+    this.lastUncommintedNumber = BigInt(sequenceNumber);
+    return this.lastUncommintedNumber;
+  }
+
+  /**
+   * Synchronizes local sequence number with the seqeunce number on chain for this account.
+   *
+   * Poll the network until all submitted transactions have either been committed or until
+   * the maximum wait time has elapsed
+   */
+  async synchronize(): Promise<void> {
+    if (this.lastUncommintedNumber === this.currentNumber) return;
+
+    /* eslint-disable no-await-in-loop */
+    while (this.lock) {
+      await sleep(this.sleepTime);
+    }
+
+    this.lock = true;
+
+    try {
+      await this.update();
+      const startTime = now();
+      while (this.lastUncommintedNumber !== this.currentNumber) {
+        if (now() - startTime > this.maxWaitTime) {
+          /* eslint-disable no-console */
+          console.warn(
+            `Waited over 30 seconds for a transaction to commit, resyncing ${this.account.accountAddress.toString()}`,
+          );
+          await this.initialize();
+        } else {
+          await sleep(this.sleepTime);
+          await this.update();
+        }
+      }
+    } catch (e) {
+      console.error("error in synchronizing this account sequence number with the one on chain", e);
+    } finally {
+      this.lock = false;
+    }
+  }
+}

package/src/transactions/management/asyncQueue.ts

@@ -0,0 +1,107 @@
+/**
+ * The AsyncQueue class is an async-aware data structure that provides a queue-like
+ * behavior for managing asynchronous tasks or operations.
+ * It allows to enqueue items and dequeue them asynchronously.
+ * This is not thread-safe but it is async concurrency safe and
+ * it does not guarantee ordering for those that call into and await on enqueue.
+ */
+
+interface PendingDequeue<T> {
+  resolve: (value: T) => void;
+  reject: (reason?: AsyncQueueCancelledError) => void;
+}
+
+export class AsyncQueue<T> {
+  readonly queue: T[] = [];
+
+  // The pendingDequeue is used to handle the resolution of promises when items are enqueued and dequeued.
+  private pendingDequeue: PendingDequeue<T>[] = [];
+
+  private cancelled: boolean = false;
+
+  /**
+   * The enqueue method adds an item to the queue. If there are pending dequeued promises,
+   * in the pendingDequeue, it resolves the oldest promise with the enqueued item immediately.
+   * Otherwise, it adds the item to the queue.
+   *
+   * @param item T
+   */
+  enqueue(item: T): void {
+    this.cancelled = false;
+
+    if (this.pendingDequeue.length > 0) {
+      const promise = this.pendingDequeue.shift();
+
+      promise?.resolve(item);
+
+      return;
+    }
+
+    this.queue.push(item);
+  }
+
+  /**
+   * The dequeue method returns a promise that resolves to the next item in the queue.
+   * If the queue is not empty, it resolves the promise immediately with the next item.
+   * Otherwise, it creates a new promise. The promise's resolve function is stored
+   * in the pendingDequeue with a unique counter value as the key.
+   * The newly created promise is then returned, and it will be resolved later when an item is enqueued.
+   *
+   * @returns Promise<T>
+   */
+  async dequeue(): Promise<T> {
+    if (this.queue.length > 0) {
+      return Promise.resolve(this.queue.shift()!);
+    }
+
+    return new Promise<T>((resolve, reject) => {
+      this.pendingDequeue.push({ resolve, reject });
+    });
+  }
+
+  /**
+   * The isEmpty method returns whether the queue is empty or not.
+   *
+   * @returns boolean
+   */
+  isEmpty(): boolean {
+    return this.queue.length === 0;
+  }
+
+  /**
+   * The cancel method cancels all pending promises in the queue.
+   * It rejects the promises with a AsyncQueueCancelledError error,
+   * ensuring that any awaiting code can handle the cancellation appropriately.
+   */
+  cancel(): void {
+    this.cancelled = true;
+
+    this.pendingDequeue.forEach(async ({ reject }) => {
+      reject(new AsyncQueueCancelledError("Task cancelled"));
+    });
+
+    this.pendingDequeue = [];
+
+    this.queue.length = 0;
+  }
+
+  /**
+   * The isCancelled method returns whether the queue is cancelled or not.
+   *
+   * @returns boolean
+   */
+  isCancelled(): boolean {
+    return this.cancelled;
+  }
+
+  /**
+   * The pendingDequeueLength method returns the length of the pendingDequeue.
+   *
+   * @returns number
+   */
+  pendingDequeueLength(): number {
+    return this.pendingDequeue.length;
+  }
+}
+
+export class AsyncQueueCancelledError extends Error {}

package/src/transactions/management/index.ts

@@ -0,0 +1,2 @@
+export * from "./accountSequenceNumber";
+export * from "./transactionWorker";

package/src/transactions/management/transactionWorker.ts

@@ -0,0 +1,275 @@
+/* eslint-disable no-await-in-loop */
+
+/**
+ * TransactionWorker provides a simple framework for receiving payloads to be processed.
+ *
+ * Once one `start()` the process and pushes a new transaction, the worker acquires
+ * the current account's next sequence number (by using the AccountSequenceNumber class),
+ * generates a signed transaction and pushes an async submission process into the `outstandingTransactions` queue.
+ * At the same time, the worker processes transactions by reading the `outstandingTransactions` queue
+ * and submits the next transaction to chain, it
+ * 1) waits for resolution of the submission process or get pre-execution validation error
+ * and 2) waits for the resolution of the execution process or get an execution error.
+ * The worker fires events for any submission and/or execution success and/or failure.
+ */
+
+import { AptosConfig } from "../../api/aptosConfig";
+import { Account } from "../../core";
+import { waitForTransaction } from "../../internal/transaction";
+import { generateTransaction, signAndSubmitTransaction } from "../../internal/transactionSubmission";
+import { PendingTransactionResponse, TransactionResponse } from "../../types";
+import {
+  InputGenerateTransactionOptions,
+  InputGenerateTransactionPayloadData,
+  SingleSignerTransaction,
+} from "../types";
+import { AccountSequenceNumber } from "./accountSequenceNumber";
+import { AsyncQueue, AsyncQueueCancelledError } from "./asyncQueue";
+
+const promiseFulfilledStatus = "fulfilled";
+
+export class TransactionWorker {
+  readonly aptosConfig: AptosConfig;
+
+  readonly account: Account;
+
+  // current account sequence number
+  readonly accountSequnceNumber: AccountSequenceNumber;
+
+  readonly taskQueue: AsyncQueue<() => Promise<void>> = new AsyncQueue<() => Promise<void>>();
+
+  // process has started
+  started: boolean;
+
+  /**
+   * transactions payloads waiting to be generated and signed
+   *
+   * TODO support entry function payload from ABI builder
+   */
+  transactionsQueue = new AsyncQueue<
+    [InputGenerateTransactionPayloadData, InputGenerateTransactionOptions | undefined]
+  >();
+
+  /**
+   * signed transactions waiting to be submitted
+   */
+  outstandingTransactions = new AsyncQueue<[Promise<PendingTransactionResponse>, bigint]>();
+
+  /**
+   * transactions that have been submitted to chain
+   */
+  sentTransactions: Array<[string, bigint, any]> = [];
+
+  /**
+   * transactions that have been committed to chain
+   */
+  executedTransactions: Array<[string, bigint, any]> = [];
+
+  /**
+   * Provides a simple framework for receiving payloads to be processed.
+   *
+   * @param aptosConfig - a config object
+   * @param sender - a sender as Account
+   * @param maxWaitTime - the max wait time to wait before resyncing the sequence number
+   * to the current on-chain state, default to 30
+   * @param maximumInFlight - submit up to `maximumInFlight` transactions per account.
+   * Mempool limits the number of transactions per account to 100, hence why we default to 100.
+   * @param sleepTime - If `maximumInFlight` are in flight, wait `sleepTime` seconds before re-evaluating, default to 10
+   */
+  constructor(
+    aptosConfig: AptosConfig,
+    account: Account,
+    maxWaitTime: number = 30,
+    maximumInFlight: number = 100,
+    sleepTime: number = 10,
+  ) {
+    this.aptosConfig = aptosConfig;
+    this.account = account;
+    this.started = false;
+    this.accountSequnceNumber = new AccountSequenceNumber(
+      aptosConfig,
+      account,
+      maxWaitTime,
+      maximumInFlight,
+      sleepTime,
+    );
+  }
+
+  /**
+   * Gets the current account sequence number,
+   * generates the transaction with the account sequence number,
+   * adds the transaction to the outstanding transaction queue
+   * to be processed later.
+   */
+  async submitNextTransaction() {
+    try {
+      /* eslint-disable no-constant-condition */
+      while (true) {
+        if (this.transactionsQueue.isEmpty()) return;
+        const sequenceNumber = await this.accountSequnceNumber.nextSequenceNumber();
+        if (sequenceNumber === null) return;
+        const transaction = await this.generateNextTransaction(this.account, sequenceNumber);
+        if (!transaction) return;
+        const pendingTransaction = signAndSubmitTransaction({
+          aptosConfig: this.aptosConfig,
+          transaction,
+          signer: this.account,
+        });
+        await this.outstandingTransactions.enqueue([pendingTransaction, sequenceNumber]);
+      }
+    } catch (error: any) {
+      if (error instanceof AsyncQueueCancelledError) {
+        return;
+      }
+      throw new Error(`Submit transaction failed for ${this.account.accountAddress.toString()} with error ${error}`);
+    }
+  }
+
+  /**
+   * Reads the outstanding transaction queue and submits the transaction to chain.
+   *
+   * If the transaction has fulfilled, it pushes the transaction to the processed
+   * transactions queue and fires a transactionsFulfilled event.
+   *
+   * If the transaction has failed, it pushes the transaction to the processed
+   * transactions queue with the failure reason and fires a transactionsFailed event.
+   */
+  async processTransactions() {
+    try {
+      /* eslint-disable no-constant-condition */
+      while (true) {
+        const awaitingTransactions = [];
+        const sequenceNumbers = [];
+        let [pendingTransaction, sequenceNumber] = await this.outstandingTransactions.dequeue();
+
+        awaitingTransactions.push(pendingTransaction);
+        sequenceNumbers.push(sequenceNumber);
+
+        while (!this.outstandingTransactions.isEmpty()) {
+          [pendingTransaction, sequenceNumber] = await this.outstandingTransactions.dequeue();
+
+          awaitingTransactions.push(pendingTransaction);
+          sequenceNumbers.push(sequenceNumber);
+        }
+        // send awaiting transactions to chain
+        const sentTransactions = await Promise.allSettled(awaitingTransactions);
+        for (let i = 0; i < sentTransactions.length && i < sequenceNumbers.length; i += 1) {
+          // check sent transaction status
+          const sentTransaction = sentTransactions[i];
+          sequenceNumber = sequenceNumbers[i];
+          if (sentTransaction.status === promiseFulfilledStatus) {
+            // transaction sent to chain
+            this.sentTransactions.push([sentTransaction.value.hash, sequenceNumber, null]);
+            // check sent transaction execution
+            await this.checkTransaction(sentTransaction, sequenceNumber);
+          } else {
+            // send transaction failed
+            this.sentTransactions.push([sentTransaction.status, sequenceNumber, sentTransaction.reason]);
+          }
+        }
+      }
+    } catch (error: any) {
+      if (error instanceof AsyncQueueCancelledError) {
+        return;
+      }
+      throw new Error(`Process execution failed for ${this.account.accountAddress.toString()} with error ${error}`);
+    }
+  }
+
+  /**
+   * Once transaction has been sent to chain, we check for its execution status.
+   * @param sentTransaction transactions that were sent to chain and are now waiting to be executed
+   * @param sequenceNumber the account's sequence number that was sent with the transaction
+   */
+  async checkTransaction(sentTransaction: PromiseFulfilledResult<PendingTransactionResponse>, sequenceNumber: bigint) {
+    try {
+      const waitFor: Array<Promise<TransactionResponse>> = [];
+      waitFor.push(waitForTransaction({ aptosConfig: this.aptosConfig, transactionHash: sentTransaction.value.hash }));
+      const sentTransactions = await Promise.allSettled(waitFor);
+
+      for (let i = 0; i < sentTransactions.length; i += 1) {
+        const executedTransaction = sentTransactions[i];
+        if (executedTransaction.status === promiseFulfilledStatus) {
+          // transaction executed to chain
+          this.executedTransactions.push([executedTransaction.value.hash, sequenceNumber, null]);
+        } else {
+          // transaction execution failed
+          this.executedTransactions.push([executedTransaction.status, sequenceNumber, executedTransaction.reason]);
+        }
+      }
+    } catch (error: any) {
+      throw new Error(`Check transaction failed for ${this.account.accountAddress.toString()} with error ${error}`);
+    }
+  }
+
+  /**
+   * Push transaction to the transactions queue
+   * @param payload Transaction payload
+   */
+  async push(
+    transactionData: InputGenerateTransactionPayloadData,
+    options?: InputGenerateTransactionOptions,
+  ): Promise<void> {
+    await this.transactionsQueue.enqueue([transactionData, options]);
+  }
+
+  /**
+   * Generates a signed transaction that can be submitted to chain
+   * @param account an Aptos account
+   * @param sequenceNumber a sequence number the transaction will be generated with
+   * @returns
+   */
+  async generateNextTransaction(
+    account: Account,
+    sequenceNumber: bigint,
+  ): Promise<SingleSignerTransaction | undefined> {
+    if (this.transactionsQueue.isEmpty()) return undefined;
+    const [transactionData, options] = await this.transactionsQueue.dequeue();
+    const transaction = await generateTransaction({
+      aptosConfig: this.aptosConfig,
+      sender: account.accountAddress,
+      data: transactionData,
+      options: { ...options, accountSequenceNumber: sequenceNumber },
+    });
+
+    return transaction;
+  }
+
+  /**
+   * Starts transaction submission and transaction processing.
+   */
+  async run() {
+    try {
+      while (!this.taskQueue.isCancelled()) {
+        const task = await this.taskQueue.dequeue();
+        await task();
+      }
+    } catch (error: any) {
+      throw new Error(`Unable to start transaction batching: ${error}`);
+    }
+  }
+
+  /**
+   * Starts the transaction management process.
+   */
+  start() {
+    if (this.started) {
+      throw new Error("worker has already started");
+    }
+    this.started = true;
+    this.taskQueue.enqueue(() => this.submitNextTransaction());
+    this.taskQueue.enqueue(() => this.processTransactions());
+    this.run();
+  }
+
+  /**
+   * Stops the the transaction management process.
+   */
+  stop() {
+    if (this.taskQueue.isCancelled()) {
+      throw new Error("worker has already stopped");
+    }
+    this.started = false;
+    this.taskQueue.cancel();
+  }
+}

package/src/transactions/transactionBuilder/helpers.ts

@@ -8,7 +8,7 @@ import {
   InputScriptData,
   SimpleEntryFunctionArgumentTypes,
 } from "../types";
-import { Bool, FixedBytes, MoveString, U128, U16, U256, U32, U64, U8 } from "../../bcs";
+import { Bool, FixedBytes, MoveOption, MoveString, MoveVector, U128, U16, U256, U32, U64, U8 } from "../../bcs";
 import { AccountAddress } from "../../core";
 import { MoveFunction, MoveFunctionId } from "../../types";
 
@@ -32,17 +32,39 @@ export function isNull(arg: SimpleEntryFunctionArgumentTypes): arg is null | und
   return arg === null || arg === undefined;
 }
 
+export function isEncodedEntryFunctionArgument(
+  arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes,
+): arg is EntryFunctionArgumentTypes {
+  return (
+    isBcsBool(arg) ||
+    isBcsU8(arg) ||
+    isBcsU16(arg) ||
+    isBcsU32(arg) ||
+    isBcsU64(arg) ||
+    isBcsU128(arg) ||
+    isBcsU256(arg) ||
+    isBcsAddress(arg) ||
+    isBcsString(arg) ||
+    isBcsFixedBytes(arg) ||
+    arg instanceof MoveVector ||
+    arg instanceof MoveOption
+  );
+}
+
 export function isBcsBool(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is Bool {
   return arg instanceof Bool;
 }
+
 export function isBcsAddress(
   arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes,
 ): arg is AccountAddress {
   return arg instanceof AccountAddress;
 }
+
 export function isBcsString(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is MoveString {
   return arg instanceof MoveString;
 }
+
 export function isBcsFixedBytes(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is FixedBytes {
   return arg instanceof FixedBytes;
 }
@@ -50,18 +72,23 @@ export function isBcsFixedBytes(arg: EntryFunctionArgumentTypes | SimpleEntryFun
 export function isBcsU8(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U8 {
   return arg instanceof U8;
 }
+
 export function isBcsU16(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U16 {
   return arg instanceof U16;
 }
+
 export function isBcsU32(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U32 {
   return arg instanceof U32;
 }
+
 export function isBcsU64(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U64 {
   return arg instanceof U64;
 }
+
 export function isBcsU128(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U128 {
   return arg instanceof U128;
 }
+
 export function isBcsU256(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U256 {
   return arg instanceof U256;
 }