@settlemint/dalp-sdk 3.1.25 → 3.1.26-main.37113215468

package/dist/wait-for-transaction.d.ts

@@ -1,94 +1,52 @@
-/**
- * Bounded wait-until-terminal barrier for queued DALP mutations.
- *
- * A v2 mutation may return a `202`-style async-accepted envelope when its
- * synchronous wait window elapses while the execution workflow is still
- * confirming. `waitForTransaction` turns that into a deterministic outcome:
- * poll the transaction status route at a FIXED interval bounded by a wall-clock
- * deadline, resolve on a terminal success, throw a typed error on a terminal
- * failure, and throw a loud timeout error if the deadline elapses first.
- *
- * This is a determinism barrier, not a masking retry — total wait is bounded by
- * `timeoutMs` (never exponential), and a never-terminating transaction fails
- * loud and bounded instead of hanging.
- *
- * Related: kit/sdk/src/types.ts
- * Related: packages/dalp/api-contract/src/routes/transaction/routes/transaction.status.schema.ts
- *
- * @module
- */
-import type { DalpClient } from "./types.js";
-/** Outcome shape returned by the transaction status route, narrowed to the fields this helper reads. */
-export interface WaitForTransactionResult {
-    readonly tokenAddress?: unknown;
+import type { DalpClient } from "./proxy/client.ts";
+import type { EvmTransactionStatusOutput } from "./generated/api-types.d.ts";
+export interface WaitForTransactionContractError {
+    readonly id: string;
+    readonly args: Readonly<Record<string, string>>;
+    readonly why: string;
+    readonly message: string;
+    readonly fix?: string;
 }
 export interface WaitForTransactionStatus {
-    transactionId: string;
-    status: string;
-    subStatus: string | null;
-    transactionHash: string | null;
-    errorMessage: string | null;
-    result?: WaitForTransactionResult;
+    readonly transactionId: string;
+    readonly status: string;
+    readonly subStatus: string | null;
+    readonly transactionHash: string | null;
+    readonly errorMessage: string | null;
+    readonly contractError?: WaitForTransactionContractError | null;
+    readonly result?: WaitForTransactionResult;
+    readonly activeRequirement?: EvmTransactionStatusOutput["activeRequirement"];
+    readonly activeRequirementUnavailable?: EvmTransactionStatusOutput["activeRequirementUnavailable"];
+    readonly indexerRebuild?: EvmTransactionStatusOutput["indexerRebuild"];
+    readonly indexerRebuildUnavailable?: EvmTransactionStatusOutput["indexerRebuildUnavailable"];
+}
+export type WaitForTransactionResult = NonNullable<EvmTransactionStatusOutput["result"]>;
+export interface WaitForTransactionSuccess extends WaitForTransactionStatus {
+    readonly status: "COMPLETED";
 }
 export interface WaitForTransactionOptions {
-    /** Wall-clock ceiling for the whole wait, in milliseconds. Default 120_000. */
-    timeoutMs?: number;
-    /** Fixed delay between status polls, in milliseconds. Default 2_000. */
-    intervalMs?: number;
-    /**
-     * Resolve (instead of continuing to poll) when the transaction reaches
-     * `PENDING_APPROVAL` — an external approval gate (DFNS / Fireblocks) that is
-     * not a stall and may legitimately outlast the deadline. Default `true`.
-     */
-    resolveOnPendingApproval?: boolean;
-    /**
-     * Cancels the wait when the owning context (React component, request handler,
-     * workflow step) is torn down. An aborted signal stops the loop on the next
-     * iteration, cancels the in-flight status request, and surfaces as a
-     * {@link DalpTransactionWaitError} with `reason: "aborted"`.
-     */
-    signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onStatus?: (status: WaitForTransactionStatus) => void;
+    readonly holdWhilePaused?: boolean;
+    readonly holdWhileRebuilding?: boolean;
+    readonly now?: () => number;
+    readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    readonly readStatus?: (transactionId: string, signal?: AbortSignal) => Promise<WaitForTransactionStatus>;
 }
-/**
- * Thrown when a transaction reaches a terminal failure state
- * (`FAILED` / `DEAD_LETTER` / `CANCELLED`), does not reach any terminal state
- * within the deadline (`reason: "timeout"`), or the caller's `AbortSignal`
- * fires (`reason: "aborted"`).
- */
+export type TransactionWaitFailureReason = "terminal-failure" | "timeout" | "aborted" | "funding-paused" | "indexer-rebuild";
 export declare class DalpTransactionWaitError extends Error {
+    readonly code = "sdk.transaction.WAIT_FAILED";
+    readonly category: "operational";
     readonly transactionId: string;
-    readonly status: string;
-    readonly subStatus: string | null;
-    readonly reason: "terminal-failure" | "timeout" | "aborted";
-    readonly lastStatus: WaitForTransactionStatus | undefined;
-    constructor(options: {
-        message: string;
-        transactionId: string;
-        status: string;
-        subStatus: string | null;
-        reason: "terminal-failure" | "timeout" | "aborted";
-        lastStatus?: WaitForTransactionStatus;
-        cause?: unknown;
-    });
+    readonly reason: TransactionWaitFailureReason;
+    readonly lastStatus?: WaitForTransactionStatus;
+    readonly elapsedMs?: number;
+    constructor(transactionId: string, reason: TransactionWaitFailureReason, lastStatus?: WaitForTransactionStatus, elapsedMs?: number);
+    get status(): string;
+    get subStatus(): string | null;
+    get retryable(): boolean;
 }
-/**
- * Poll the transaction status route until the transaction reaches a terminal
- * state or the deadline elapses.
- *
- * - `COMPLETED` → resolves with the final status (the handler already waited for
- *   the indexer drain, so this is a true read-after-write guarantee).
- * - `FAILED` / `DEAD_LETTER` / `CANCELLED` → throws {@link DalpTransactionWaitError}
- *   (`reason: "terminal-failure"`) carrying `status`, `subStatus`, and
- *   `errorMessage` — fail fast, do not keep polling.
- * - `PENDING_APPROVAL` → resolves as pending (when `resolveOnPendingApproval`,
- *   the default) so an external approval gate is never treated as a stall.
- * - deadline elapsed → throws {@link DalpTransactionWaitError} (`reason: "timeout"`)
- *   carrying the last observed status — a loud, bounded failure, never an
- *   indefinite hang.
- *
- * @param client A DALP API client.
- * @param transactionId The queue transaction identifier (UUIDv7) returned in the
- *   async-accepted envelope.
- */
-export declare function waitForTransaction(client: DalpClient, transactionId: string, options?: WaitForTransactionOptions): Promise<WaitForTransactionStatus>;
-//# sourceMappingURL=wait-for-transaction.d.ts.map
+export declare const isDalpTransactionWaitError: (error: unknown) => error is DalpTransactionWaitError;
+export declare function waitForTransaction(client: DalpClient, transactionId: string, options?: WaitForTransactionOptions): Promise<WaitForTransactionSuccess>;

package/dist/wait-for-transaction.js

@@ -0,0 +1,151 @@
+// 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 defaultSleep = (milliseconds, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted === true) {
+    reject(signal.reason);
+    return;
+  }
+  const onAbort = () => {
+    clearTimeout(timeout);
+    reject(signal?.reason);
+  };
+  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)) {
+      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
+};