@settlemint/dalp-sdk 3.1.33 → 3.2.0-rc.1

package/dist/wait-for-transaction.js

@@ -0,0 +1,154 @@
+// src/wait-for-transaction.ts
+var failedStates = new Set(["FAILED", "DEAD_LETTER", "CANCELLED"]);
+var isWaitForTransactionSuccess = (status) => status.status === "COMPLETED";
+
+class DalpTransactionWaitError extends Error {
+  code = "sdk.transaction.WAIT_FAILED";
+  category = "operational";
+  transactionId;
+  reason;
+  lastStatus;
+  elapsedMs;
+  constructor(transactionId, reason, lastStatus, elapsedMs) {
+    let message;
+    if (reason === "terminal-failure") {
+      message = `Transaction ${transactionId} reached terminal state ${lastStatus?.status ?? "UNKNOWN"}`;
+    } else if (reason === "timeout") {
+      message = `Transaction ${transactionId} did not reach a terminal state within ${elapsedMs ?? 0}ms`;
+    } else if (reason === "funding-paused") {
+      message = `Transaction ${transactionId} is paused waiting for a gas funding payment`;
+    } else if (reason === "indexer-rebuild") {
+      const chainId = lastStatus?.indexerRebuild?.chainId;
+      message = `Transaction ${transactionId} is on chain, and the platform is still rebuilding its index of chain ${chainId ?? "unknown"} before the write can be read back`;
+    } else {
+      message = `Transaction status observation was aborted for transaction ${transactionId}`;
+    }
+    super(message);
+    this.name = "DalpTransactionWaitError";
+    this.transactionId = transactionId;
+    this.reason = reason;
+    this.lastStatus = lastStatus;
+    this.elapsedMs = elapsedMs;
+  }
+  get status() {
+    return this.lastStatus?.status ?? "UNKNOWN";
+  }
+  get subStatus() {
+    return this.lastStatus?.subStatus ?? null;
+  }
+  get retryable() {
+    return this.reason === "timeout" || this.reason === "funding-paused" || this.reason === "indexer-rebuild";
+  }
+}
+var isDalpTransactionWaitError = (error) => error instanceof DalpTransactionWaitError;
+var abortReason = (signal) => signal.reason instanceof Error ? signal.reason : new Error("Aborted", { cause: signal.reason });
+var defaultSleep = (milliseconds, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted === true) {
+    reject(abortReason(signal));
+    return;
+  }
+  const onAbort = () => {
+    clearTimeout(timeout);
+    if (signal !== undefined) {
+      reject(abortReason(signal));
+    }
+  };
+  const timeout = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, milliseconds);
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+var routeStatusReader = (client) => async (transactionId, signal) => {
+  const result = await client.execute("transactionsV2.status", { transactionId }, signal === undefined ? undefined : { signal });
+  const body = result !== null && typeof result === "object" ? Reflect.get(result, "data") ?? result : result;
+  return body;
+};
+var MAX_UNREADABLE_HOLDS = 5;
+var noParks = { fundingPaused: false, indexerRebuild: false };
+var PAUSED_POLL_INTERVAL_MAX_MS = 30000;
+function readParks(status, held) {
+  const fundingPaused = status.activeRequirement !== undefined && status.activeRequirement !== null;
+  const indexerRebuild = status.indexerRebuild !== undefined && status.indexerRebuild !== null;
+  return {
+    fundingPaused: fundingPaused || held.fundingPaused && status.activeRequirementUnavailable === true,
+    indexerRebuild: indexerRebuild || held.indexerRebuild && status.indexerRebuildUnavailable === true
+  };
+}
+function namedPark(parks) {
+  if (parks.fundingPaused) {
+    return "funding-paused";
+  }
+  return parks.indexerRebuild ? "indexer-rebuild" : undefined;
+}
+async function waitForTransaction(client, transactionId, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 120000;
+  const pollIntervalMs = options.pollIntervalMs ?? 1000;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? defaultSleep;
+  const readStatus = options.readStatus ?? routeStatusReader(client);
+  const holdWhilePaused = options.holdWhilePaused ?? true;
+  const holdWhileRebuilding = options.holdWhileRebuilding ?? true;
+  const waitStartedAt = now();
+  let budgetStartedAt = waitStartedAt;
+  let pollDelayMs = pollIntervalMs;
+  let lastStatus;
+  let held = noParks;
+  let unreadableHolds = 0;
+  const isAborted = () => options.signal?.aborted === true;
+  while (true) {
+    if (isAborted()) {
+      throw new DalpTransactionWaitError(transactionId, "aborted", lastStatus);
+    }
+    if (now() - budgetStartedAt >= timeoutMs) {
+      const ranOutIn = namedPark(held) ?? "timeout";
+      throw new DalpTransactionWaitError(transactionId, ranOutIn, lastStatus, now() - waitStartedAt);
+    }
+    try {
+      lastStatus = await readStatus(transactionId, options.signal);
+    } catch (error) {
+      if (isAborted()) {
+        throw new DalpTransactionWaitError(transactionId, "aborted", lastStatus);
+      }
+      throw error;
+    }
+    options.onStatus?.(lastStatus);
+    if (failedStates.has(lastStatus.status) && lastStatus.mayStillLand !== true) {
+      throw new DalpTransactionWaitError(transactionId, "terminal-failure", lastStatus);
+    }
+    if (isWaitForTransactionSuccess(lastStatus)) {
+      return lastStatus;
+    }
+    const ownParks = readParks(lastStatus, noParks);
+    held = readParks(lastStatus, held);
+    const parkedBy = namedPark(held);
+    unreadableHolds = parkedBy === undefined || namedPark(ownParks) !== undefined ? 0 : unreadableHolds + 1;
+    let holdsThroughIt = false;
+    if (parkedBy === "funding-paused") {
+      holdsThroughIt = holdWhilePaused;
+    } else if (parkedBy === "indexer-rebuild") {
+      holdsThroughIt = holdWhileRebuilding;
+    }
+    if (parkedBy === undefined) {
+      pollDelayMs = pollIntervalMs;
+    } else {
+      if (!holdsThroughIt) {
+        throw new DalpTransactionWaitError(transactionId, parkedBy, lastStatus, now() - waitStartedAt);
+      }
+      if (unreadableHolds <= MAX_UNREADABLE_HOLDS) {
+        budgetStartedAt = now();
+      }
+      pollDelayMs = Math.min(pollDelayMs * 2, Math.max(pollIntervalMs, PAUSED_POLL_INTERVAL_MAX_MS));
+    }
+    try {
+      await sleep(Math.min(pollDelayMs, Math.max(0, timeoutMs - (now() - budgetStartedAt))), options.signal);
+    } catch {
+      throw new DalpTransactionWaitError(transactionId, "aborted", lastStatus);
+    }
+  }
+}
+export {
+  DalpTransactionWaitError,
+  isDalpTransactionWaitError,
+  waitForTransaction
+};