@moveindustries/ts-sdk 5.1.4

package/src/transactions/management/accountSequenceNumber.ts

@@ -0,0 +1,226 @@
+/**
+ * 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.
+ * @group Implementation
+ * @category Transactions
+ */
+
+import { Account } from "../../account";
+import { MovementConfig } from "../../api/movementConfig";
+import { getInfo } from "../../internal/account";
+import { nowInSeconds, sleep } from "../../utils/helpers";
+
+/**
+ * Represents an account's sequence number management for transaction handling on the Movement blockchain.
+ * This class provides methods to retrieve the next available sequence number, synchronize with the on-chain sequence number,
+ * and manage local sequence numbers while ensuring thread safety.
+ *
+ * @param movementConfig - The configuration settings for Movement.
+ * @param account - The account associated with the sequence number.
+ * @param maxWaitTime - The maximum time to wait for a transaction to commit.
+ * @param maximumInFlight - The maximum number of transactions that can be in flight at once.
+ * @param sleepTime - The time to wait before retrying to get the sequence number.
+ * @group Implementation
+ * @category Transactions
+ */
+export class AccountSequenceNumber {
+  readonly movementConfig: MovementConfig;
+
+  readonly account: Account;
+
+  // sequence number on chain
+  // TODO: Change to Uncommitted
+  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 an incremental integer.
+   * When they complete, they increment that number and that entity is able to enter the `lock`.
+   * That would guarantee ordering.
+   * @group Implementation
+   * @category Transactions
+   */
+  lock = false;
+
+  maxWaitTime: number;
+
+  maximumInFlight: number;
+
+  sleepTime: number;
+
+  /**
+   * Creates an instance of the class with the specified configuration and account details.
+   * This constructor initializes the necessary parameters for managing Movement transactions.
+   *
+   * @param movementConfig - The configuration settings for Movement.
+   * @param account - The account associated with the Movement transactions.
+   * @param maxWaitTime - The maximum time to wait for a transaction to be processed, in milliseconds.
+   * @param maximumInFlight - The maximum number of transactions that can be in flight at the same time.
+   * @param sleepTime - The time to sleep between transaction checks, in milliseconds.
+   * @group Implementation
+   * @category Transactions
+   */
+  constructor(
+    movementConfig: MovementConfig,
+    account: Account,
+    maxWaitTime: number,
+    maximumInFlight: number,
+    sleepTime: number,
+  ) {
+    this.movementConfig = movementConfig;
+    this.account = account;
+    this.maxWaitTime = maxWaitTime;
+    this.maximumInFlight = maximumInFlight;
+    this.sleepTime = sleepTime;
+  }
+
+  /**
+   * Returns the next available sequence number for this account.
+   * This function ensures that the sequence number is updated and synchronized, handling potential delays in transaction commits.
+   *
+   * @returns {BigInt} The next available sequence number.
+   * @group Implementation
+   * @category Transactions
+   */
+  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 = nowInSeconds();
+        while (this.currentNumber! - this.lastUncommintedNumber! >= this.maximumInFlight) {
+          await sleep(this.sleepTime);
+          if (nowInSeconds() - startTime > this.maxWaitTime) {
+            /* eslint-disable no-console */
+            console.warn(
+              `Waited over 30 seconds for a transaction to commit, re-syncing ${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.
+   *
+   * @returns {Promise<void>} A promise that resolves when the account has been initialized.
+   *
+   * @throws {Error} Throws an error if the account information cannot be retrieved.
+   * @group Implementation
+   * @category Transactions
+   */
+  async initialize(): Promise<void> {
+    const { sequence_number: sequenceNumber } = await getInfo({
+      movementConfig: this.movementConfig,
+      accountAddress: this.account.accountAddress,
+    });
+    this.currentNumber = BigInt(sequenceNumber);
+    this.lastUncommintedNumber = BigInt(sequenceNumber);
+  }
+
+  /**
+   * Updates this account's sequence number with the one on-chain.
+   *
+   * @returns The on-chain sequence number for this account.
+   * @group Implementation
+   * @category Transactions
+   */
+  async update(): Promise<bigint> {
+    const { sequence_number: sequenceNumber } = await getInfo({
+      movementConfig: this.movementConfig,
+      accountAddress: this.account.accountAddress,
+    });
+    this.lastUncommintedNumber = BigInt(sequenceNumber);
+    return this.lastUncommintedNumber;
+  }
+
+  /**
+   * Synchronizes the local sequence number with the sequence number on-chain for the specified account.
+   * This function polls the network until all submitted transactions have either been committed or until the maximum wait time has elapsed.
+   *
+   * @throws {Error} Throws an error if there is an issue synchronizing the account sequence number with the one on-chain.
+   * @group Implementation
+   * @category Transactions
+   */
+  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 = nowInSeconds();
+      while (this.lastUncommintedNumber !== this.currentNumber) {
+        if (nowInSeconds() - startTime > this.maxWaitTime) {
+          /* eslint-disable no-console */
+          console.warn(
+            `Waited over 30 seconds for a transaction to commit, re-syncing ${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,126 @@
+/**
+ * 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.
+ * @group Implementation
+ * @category Transactions
+ */
+
+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;
+
+  /**
+   * Adds an item to the queue. If there are pending dequeued promises, it resolves the oldest promise with the enqueued item
+   * immediately; otherwise, it adds the item to the queue.
+   *
+   * @param item - The item to be added to the queue.
+   * @group Implementation
+   * @category Transactions
+   */
+  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);
+  }
+
+  /**
+   * Dequeues the next item from the queue and returns a promise that resolves to it.
+   * If the queue is empty, it creates a new promise that will be resolved when an item is enqueued.
+   *
+   * @returns Promise<T>
+   * @group Implementation
+   * @category Transactions
+   */
+  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 });
+    });
+  }
+
+  /**
+   * Determine whether the queue is empty.
+   *
+   * @returns boolean - Returns true if the queue has no elements, otherwise false.
+   * @group Implementation
+   * @category Transactions
+   */
+  isEmpty(): boolean {
+    return this.queue.length === 0;
+  }
+
+  /**
+   * Cancels all pending promises in the queue and rejects them with an AsyncQueueCancelledError.
+   * This ensures that any awaiting code can handle the cancellation appropriately.
+   *
+   * @returns {void}
+   * @group Implementation
+   * @category Transactions
+   */
+  cancel(): void {
+    this.cancelled = true;
+
+    this.pendingDequeue.forEach(async ({ reject }) => {
+      reject(new AsyncQueueCancelledError("Task cancelled"));
+    });
+
+    this.pendingDequeue = [];
+
+    this.queue.length = 0;
+  }
+
+  /**
+   * Determine whether the queue has been cancelled.
+   *
+   * @returns boolean - Returns true if the queue is cancelled, otherwise false.
+   * @group Implementation
+   * @category Transactions
+   */
+  isCancelled(): boolean {
+    return this.cancelled;
+  }
+
+  /**
+   * Retrieve the length of the pending dequeue.
+   *
+   * @returns number - The number of items currently in the pending dequeue.
+   * @group Implementation
+   * @category Transactions
+   */
+  pendingDequeueLength(): number {
+    return this.pendingDequeue.length;
+  }
+}
+
+/**
+ * Represents an error that occurs when an asynchronous queue operation is cancelled.
+ * This error extends the built-in Error class to provide additional context for cancellation events.
+ *
+ * @extends Error
+ * @group Implementation
+ * @category Transactions
+ */
+export class AsyncQueueCancelledError extends Error {}

package/src/transactions/management/index.ts

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