@multiplatform.one/web3 7.23.2 → 7.25.0

package/src/clients/evm.ts

@@ -15,6 +15,7 @@ import {
   type Hex,
   type PublicClient,
   type SendTransactionParameters,
+  type Transaction,
   type TransactionReceipt,
   type Transport,
   type WalletClient,
@@ -39,6 +40,213 @@ export type EvmWriteContractParameters<
 
 export type EvmSendTransactionParameters = SendTransactionParameters<Chain, Account>;
 
+export interface EvmWaitOptions {
+  /**
+   * Milliseconds before giving up with ReceiptPendingError, even with an RPC
+   * call still unanswered. None by default, or when it is not a positive
+   * finite number: the wait lasts until the transaction is mined or its
+   * nonce goes to another transaction, because one still in the mempool can
+   * land any time. RPC errors alone never end a wait without one; it backs
+   * off and retries.
+   */
+  timeout?: number;
+  /**
+   * Stops the wait: it rejects with ReceiptWaitAbortedError, which
+   * classifyTxError calls `aborted`. A wait with no timeout polls until the
+   * transaction settles, forever for one that was dropped, so a component
+   * must abort its wait when it unmounts.
+   */
+  signal?: AbortSignal;
+  /** Blocks on top of the one that mined it, 1 by default. */
+  confirmations?: number;
+  /**
+   * The transaction's nonce, as `onTrack` gave it. A wait resumed after a
+   * reload needs it to see that another transaction took the nonce once the
+   * node has forgotten the original.
+   */
+  nonce?: number;
+  /**
+   * Called with what to persist and resume on: once the nonce is known, and
+   * with the new hash when a speed-up replaces the one being waited on.
+   * Errors it throws are ignored.
+   */
+  onTrack?: (tracked: { hash: Hash; nonce: number }) => void;
+}
+
+/**
+ * The receipt never arrived before the wait's timeout, whether the chain was
+ * slow or the RPC was failing (`cause` holds its last error). The transaction
+ * was sent and may still land, so resending it can pay twice. Show it as
+ * pending (`explorerUrl` when the chain has an explorer) and keep waiting on
+ * `hash` instead of offering a retry.
+ */
+export class ReceiptPendingError extends Error {
+  readonly mayStillLand = true as const;
+  readonly explorerUrl: string | undefined;
+  /** Known once the node has seen the transaction. Keep it with the hash to resume the wait. */
+  readonly nonce: number | undefined;
+  constructor(
+    readonly hash: Hash,
+    readonly chainId: number,
+    options: {
+      detail: string;
+      explorerUrl?: string;
+      nonce?: number;
+      cause?: unknown;
+      label?: string;
+    },
+  ) {
+    super(
+      `${options.label ?? "transaction"} ${hash} on chain ${chainId} ${options.detail}; it may still land, so do not resend it`,
+      { cause: options.cause },
+    );
+    this.name = "ReceiptPendingError";
+    this.explorerUrl = options.explorerUrl;
+    this.nonce = options.nonce;
+  }
+}
+
+/**
+ * The wait's signal aborted. Named AbortError like fetch's. The transaction
+ * is as pending as it was, so keep `hash` and `nonce` to resume the wait.
+ */
+export class ReceiptWaitAbortedError extends Error {
+  readonly mayStillLand = true as const;
+  constructor(
+    readonly hash: Hash,
+    readonly chainId: number,
+    readonly nonce: number | undefined,
+    cause: unknown,
+  ) {
+    super(`stopped waiting for transaction ${hash} on chain ${chainId}`, { cause });
+    this.name = "AbortError";
+  }
+}
+
+/** Mined and reverted: it spent gas and moved nothing. A retry is a new transaction. */
+export class TransactionRevertedError extends Error {
+  readonly mayStillLand = false as const;
+  readonly hash: Hash;
+  constructor(
+    readonly receipt: TransactionReceipt,
+    readonly chainId: number,
+    label = "transaction",
+  ) {
+    super(`${label} ${receipt.transactionHash} reverted in block ${receipt.blockNumber}`);
+    this.name = "TransactionRevertedError";
+    this.hash = receipt.transactionHash;
+  }
+}
+
+/**
+ * Sorted as viem's waitForTransactionReceipt sorts a replacement, except
+ * that a repriced copy (same `to`, `value` and `input`) is a speed-up and
+ * resolves the wait instead:
+ * - `cancelled`: a wallet's cancel, a 0-value send to self. Nothing was paid.
+ * - `replaced`: a different transaction. This one was not paid.
+ * - `unmatched`: the original was never seen, so the transaction that took
+ *   its nonce could not be compared with it. It may be the same payment sped
+ *   up, so this classifies as pending.
+ */
+export type EvmReplacementReason = "cancelled" | "replaced" | "unmatched";
+
+/**
+ * Another transaction took this one's nonce, so this one can never land. A
+ * speed-up is not this: the wait resolves with the faster copy's receipt.
+ */
+export class TransactionReplacedError extends Error {
+  readonly mayStillLand = false as const;
+  constructor(
+    readonly hash: Hash,
+    readonly chainId: number,
+    readonly reason: EvmReplacementReason,
+    /** The transaction that took the nonce, when it was found. */
+    readonly replacement: TransactionReceipt | undefined,
+  ) {
+    super(
+      `transaction ${hash} was ${reason === "unmatched" ? "superseded" : reason}${
+        replacement ? ` by ${replacement.transactionHash}` : ""
+      }: another transaction took its nonce`,
+    );
+    this.name = "TransactionReplacedError";
+  }
+}
+
+/**
+ * What an app shows for a failed send or confirmation:
+ * - `user-rejected`: declined or cancelled in the wallet. Nothing was paid.
+ * - `reverted`: the contract refused it, in simulation (nothing sent) or on
+ *   chain (gas spent). Nothing was bought.
+ * - `pending`: sent, with no receipt yet, or superseded by a transaction
+ *   that may be the same payment sped up. Show it as pending and never
+ *   resend it.
+ * - `aborted`: the app stopped waiting through the wait's `signal`. The
+ *   transaction is as pending as it was; nothing to show on an unmounted
+ *   screen.
+ * - `failed`: anything else. No hash came back and nothing says the wallet
+ *   sent it, or a different transaction took its nonce.
+ */
+export type TxErrorKind = "user-rejected" | "reverted" | "pending" | "aborted" | "failed";
+
+interface ErrorLike {
+  name?: unknown;
+  code?: unknown;
+  cause?: unknown;
+  mayStillLand?: unknown;
+  reason?: unknown;
+  receipt?: { status?: unknown };
+}
+
+/** The error and its `cause` chain. Matches by name, so a second copy of viem still classifies. */
+function causes(error: unknown): ErrorLike[] {
+  const chain: ErrorLike[] = [];
+  for (let e = error; e && typeof e === "object" && chain.length < 16; e = (e as ErrorLike).cause) {
+    if (chain.includes(e as ErrorLike)) break;
+    chain.push(e as ErrorLike);
+  }
+  return chain;
+}
+
+/** Sorts any error from sending or confirming an EVM transaction into a TxErrorKind. */
+export function classifyTxError(error: unknown): TxErrorKind {
+  const chain = causes(error);
+  const pendingAt = chain.findIndex(
+    (e) =>
+      e.mayStillLand === true ||
+      e.name === "WaitForTransactionReceiptTimeoutError" ||
+      (e.name === "TransactionReplacedError" && e.reason === "unmatched"),
+  );
+  // Only this module's aborts, which carry mayStillLand, count. A wallet
+  // SDK's own AbortError is a failed send, and one under a pending error,
+  // such as a fetch timeout in a ReceiptPendingError's cause, is pending.
+  const abortedAt = chain.findIndex(
+    (e) => e.name === "AbortError" && typeof e.mayStillLand === "boolean",
+  );
+  if (abortedAt >= 0 && (pendingAt < 0 || abortedAt <= pendingAt)) return "aborted";
+  if (pendingAt >= 0) return "pending";
+  if (
+    chain.some(
+      (e) =>
+        e.name === "UserRejectedRequestError" ||
+        e.code === 4001 ||
+        (e.name === "TransactionReplacedError" && e.reason === "cancelled"),
+    )
+  ) {
+    return "user-rejected";
+  }
+  if (
+    chain.some(
+      (e) =>
+        e.name === "ContractFunctionRevertedError" ||
+        e.name === "ExecutionRevertedError" ||
+        e.receipt?.status === "reverted",
+    )
+  ) {
+    return "reverted";
+  }
+  return "failed";
+}
+
 export interface Erc20Actions {
   balanceOf(token: Address, owner?: Address): Promise<bigint>;
   allowance(token: Address, spender: Address, owner?: Address): Promise<bigint>;
@@ -52,9 +260,20 @@ export interface Erc20Actions {
    * approval to be mined so a purchase call right after it sees the allowance.
    * A non-zero allowance is reset to 0 first, since USDT refuses to move one
    * non-zero allowance to another. Returns the final approval hash, or null
-   * when the allowance already covered it. Throws if an approval reverts.
+   * when the allowance already covered it. Each approval is confirmed like
+   * confirmTransaction: no timeout unless `timeout` is set, stopped by
+   * `signal`, and a TransactionRevertedError, ReceiptPendingError,
+   * TransactionReplacedError or ReceiptWaitAbortedError when it does not
+   * succeed. A signal aborted before an approval is sent rejects with an
+   * AbortError carrying `mayStillLand: false`, and nothing is sent.
    */
-  ensureAllowance(args: { token: Address; spender: Address; amount: bigint }): Promise<Hash | null>;
+  ensureAllowance(args: {
+    token: Address;
+    spender: Address;
+    amount: bigint;
+    timeout?: number;
+    signal?: AbortSignal;
+  }): Promise<Hash | null>;
 }
 
 export interface EvmClient extends ChainClient<"evm"> {
@@ -75,7 +294,23 @@ export interface EvmClient extends ChainClient<"evm"> {
   >(
     parameters: EvmWriteContractParameters<abi, functionName, args>,
   ): Promise<Hash>;
-  waitForTransactionReceipt(hash: Hash): Promise<TransactionReceipt>;
+  /**
+   * Resolves with the receipt, reverted or not, or a speed-up's receipt.
+   * Waits with no timeout unless `timeout` is set, backing off while the RPC
+   * fails. Rejects with ReceiptPendingError when the timeout runs out, since
+   * the transaction may still land, with TransactionReplacedError when
+   * another transaction took its nonce, and with ReceiptWaitAbortedError when
+   * `signal` aborts.
+   */
+  waitForTransactionReceipt(hash: Hash, options?: EvmWaitOptions): Promise<TransactionReceipt>;
+  /**
+   * waitForTransactionReceipt that also rejects a reverted receipt with
+   * TransactionRevertedError, so one catch and classifyTxError cover every
+   * outcome.
+   */
+  confirmTransaction(hash: Hash, options?: EvmWaitOptions): Promise<TransactionReceipt>;
+  /** The chain explorer's page for `hash`, when the chain names an explorer. */
+  explorerTxUrl(hash: Hash): string | undefined;
   readonly erc20: Erc20Actions;
 }
 
@@ -165,10 +400,261 @@ export function evmClient(config: EvmClientConfig): EvmClient {
     return walletClient.writeContract({ ...request, account, chain } as EvmWriteContractParameters);
   };
 
-  const approveAndWait = async (token: Address, spender: Address, amount: bigint) => {
+  const explorer = chain.blockExplorers?.default.url.replace(/\/+$/, "");
+  const explorerTxUrl = (hash: Hash) => (explorer ? `${explorer}/tx/${hash}` : undefined);
+
+  const missing = (name: string) => (error: unknown) => {
+    if ((error as { name?: string } | undefined)?.name === name) return undefined;
+    throw error;
+  };
+  const getReceipt = (hash: Hash) =>
+    publicClient.getTransactionReceipt({ hash }).catch(missing("TransactionReceiptNotFoundError"));
+  const getTransaction = (hash: Hash) =>
+    publicClient.getTransaction({ hash }).catch(missing("TransactionNotFoundError"));
+  const sameAddress = (a?: string | null, b?: string | null) =>
+    !!a && !!b && a.toLowerCase() === b.toLowerCase();
+
+  /**
+   * The block that mined a nonce: the first whose `count` of sent
+   * transactions is past it. `taken` is a block where the nonce is gone,
+   * `free` one where it was not (none after a reload, so it gallops back from
+   * `taken` to find one). A binary search between them costs a few dozen
+   * calls however far back the nonce went, and needs the RPC to serve state
+   * that old.
+   */
+  const nonceBlock = async (
+    count: (blockNumber: bigint) => Promise<number>,
+    nonce: number,
+    taken: bigint,
+    free?: bigint,
+  ) => {
+    let hi = taken;
+    let lo = -1n;
+    if (free !== undefined && free < hi) lo = free;
+    else {
+      for (let step = 1n; hi - step >= 0n; step *= 2n) {
+        const probe = hi - step;
+        if ((await count(probe)) <= nonce) {
+          lo = probe;
+          break;
+        }
+        hi = probe;
+      }
+    }
+    while (hi - lo > 1n) {
+      const mid = (lo + hi) / 2n;
+      if ((await count(mid)) > nonce) hi = mid;
+      else lo = mid;
+    }
+    return { block: hi, free: lo >= 0n ? lo : undefined };
+  };
+
+  const replacementReason = (taker: Transaction, original?: Transaction) => {
+    if (
+      original &&
+      sameAddress(taker.to, original.to) &&
+      taker.value === original.value &&
+      taker.input === original.input
+    ) {
+      return "repriced" as const;
+    }
+    if (sameAddress(taker.to, taker.from) && taker.value === 0n) return "cancelled" as const;
+    return original ? ("replaced" as const) : ("unmatched" as const);
+  };
+
+  /**
+   * setTimeout for any delay, returning its cancel. Browsers and Node fire a
+   * delay past 2^31 - 1 ms at once, so a long one is re-armed in steps.
+   */
+  const after = (ms: number, fire: () => void) => {
+    const step = 2 ** 31 - 1;
+    let cancel = () => {};
+    const arm = (left: number) => {
+      const id = setTimeout(() => (left > step ? arm(left - step) : fire()), Math.min(left, step));
+      cancel = () => clearTimeout(id);
+    };
+    arm(Math.max(0, ms));
+    return () => cancel();
+  };
+
+  /** Up to 30 s from the polling interval, doubling per failure, jittered down to half. */
+  const backoff = (failures: number) => {
+    const ceiling = Math.min(
+      30_000,
+      Math.max(1, publicClient.pollingInterval) * 2 ** Math.min(failures - 1, 16),
+    );
+    return ceiling / 2 + (Math.random() * ceiling) / 2;
+  };
+
+  // A poll loop of our own rather than viem's waitForTransactionReceipt: viem
+  // shares one poller per client and hash, and a waiter with no timeout can be
+  // left listening to a poller another waiter stopped. It also only notices a
+  // replacement it saw happen, so a wait resumed after a reload never ends.
+  const waitForReceipt = async (hash: Hash, options: EvmWaitOptions = {}, label?: string) => {
+    const { signal } = options;
+    const confirmations = BigInt(Math.max(1, options.confirmations ?? 1));
+    const { timeout } = options;
+    const deadline =
+      timeout !== undefined && Number.isFinite(timeout) && timeout > 0
+        ? Date.now() + timeout
+        : undefined;
+    let target = hash;
+    let original: Transaction | undefined;
+    let nonce = options.nonce;
+    let freeBlock: bigint | undefined;
+    let failures = 0;
+    let lastError: unknown;
+
+    const aborted = () => new ReceiptWaitAbortedError(hash, chain.id, nonce, signal?.reason);
+    const timedOut = () =>
+      new ReceiptPendingError(hash, chain.id, {
+        detail: `has no receipt after ${timeout} ms`,
+        explorerUrl: explorerTxUrl(hash),
+        nonce,
+        cause: lastError,
+        label,
+      });
+    let ended = false;
+    // A poll left running after an abort or the deadline must not hand the
+    // app a hash it has since replaced with a new purchase's.
+    const track = () => {
+      if (ended || signal?.aborted || nonce === undefined) return;
+      try {
+        options.onTrack?.({ hash: target, nonce });
+      } catch {
+        // the app's bookkeeping, not the wait's
+      }
+    };
+    if (signal?.aborted) throw aborted();
+    /**
+     * Settles with `promise`, or rejects at the abort or the deadline without
+     * waiting for it, calling `onStop` then. The listener and the timer go
+     * whichever way it settles, so a wait that polls for days holds nothing
+     * per poll.
+     */
+    const guard = <T>(promise: Promise<T>, onStop = () => {}) =>
+      new Promise<T>((resolve, reject) => {
+        let cancelTimer = () => {};
+        const cleanup = () => {
+          cancelTimer();
+          signal?.removeEventListener("abort", stop);
+        };
+        const give = (error: Error) => {
+          cleanup();
+          onStop();
+          reject(error);
+        };
+        const stop = () => give(aborted());
+        promise.then(resolve, reject).finally(cleanup);
+        if (signal?.aborted) return stop();
+        signal?.addEventListener("abort", stop, { once: true });
+        if (deadline !== undefined)
+          cancelTimer = after(deadline - Date.now(), () => give(timedOut()));
+      });
+    /** Every RPC call goes through here, so a poll left in flight starts no more. */
+    const rpc = <T>(call: () => Promise<T>) => {
+      if (ended || signal?.aborted) throw aborted();
+      return call();
+    };
+    const countAt = (address: Address, blockNumber: bigint) =>
+      rpc(() => publicClient.getTransactionCount({ address, blockNumber }));
+
+    /** One look at the chain: the receipt once it has its confirmations, else undefined. */
+    const poll = async (): Promise<TransactionReceipt | undefined> => {
+      const head = await rpc(() => publicClient.getBlockNumber({ cacheTime: 0 }));
+      const receipt = await rpc(() => getReceipt(target));
+      if (receipt) return head - receipt.blockNumber + 1n >= confirmations ? receipt : undefined;
+      if (!original) {
+        original = await rpc(() => getTransaction(target));
+        if (original && original.nonce !== nonce) {
+          nonce = original.nonce;
+          track();
+        }
+      }
+      if (nonce === undefined) return undefined;
+      const from = original?.from ?? account.address;
+      if ((await countAt(from, head)) <= nonce) {
+        freeBlock = head;
+        return undefined;
+      }
+      const found = await nonceBlock((n) => countAt(from, n), nonce, head, freeBlock);
+      freeBlock = found.free;
+      const block = await rpc(() =>
+        publicClient.getBlock({ blockNumber: found.block, includeTransactions: true }),
+      );
+      const taker = block.transactions.find(
+        (tx) => sameAddress(tx.from, from) && tx.nonce === nonce,
+      );
+      // Not there after a reorg, or it is this transaction, mined since the
+      // receipt lookup: either way the next poll sees the truth.
+      if (!taker || taker.hash === target) {
+        if (!taker) freeBlock = undefined;
+        return undefined;
+      }
+      const reason = replacementReason(taker, original);
+      if (reason === "repriced") {
+        target = taker.hash;
+        original = taker;
+        track();
+        return undefined;
+      }
+      if (head - found.block + 1n < confirmations) return undefined;
+      const replacement = await rpc(() => getReceipt(taker.hash));
+      throw new TransactionReplacedError(hash, chain.id, reason, replacement);
+    };
+
+    try {
+      for (;;) {
+        try {
+          const receipt = await guard(poll());
+          if (receipt) return receipt;
+          failures = 0;
+        } catch (error) {
+          if (
+            error instanceof TransactionReplacedError ||
+            error instanceof ReceiptWaitAbortedError ||
+            error instanceof ReceiptPendingError
+          ) {
+            throw error;
+          }
+          lastError = error;
+          failures++;
+        }
+        if (deadline !== undefined && Date.now() >= deadline) throw timedOut();
+        const pause = failures ? backoff(failures) : publicClient.pollingInterval;
+        let wake = () => {};
+        await guard(
+          new Promise((resolve) => {
+            wake = after(pause, () => resolve(undefined));
+          }),
+          () => wake(),
+        );
+      }
+    } finally {
+      ended = true;
+    }
+  };
+
+  const confirmTransaction = async (hash: Hash, options?: EvmWaitOptions, label?: string) => {
+    const receipt = await waitForReceipt(hash, options, label);
+    if (receipt.status !== "success") throw new TransactionRevertedError(receipt, chain.id, label);
+    return receipt;
+  };
+
+  const approveAndWait = async (
+    token: Address,
+    spender: Address,
+    amount: bigint,
+    options: Pick<EvmWaitOptions, "timeout" | "signal">,
+  ) => {
+    if (options.signal?.aborted) {
+      throw Object.assign(
+        new Error("stopped before sending the approval", { cause: options.signal.reason }),
+        { name: "AbortError", mayStillLand: false },
+      );
+    }
     const hash = await erc20.approve({ token, spender, amount });
-    const receipt = await publicClient.waitForTransactionReceipt({ hash });
-    if (receipt.status !== "success") throw new Error(`approve ${hash} reverted`);
+    await confirmTransaction(hash, options, "approve");
     return hash;
   };
 
@@ -193,11 +679,11 @@ export function evmClient(config: EvmClientConfig): EvmClient {
       simulateAndWrite({ address: token, functionName: "transfer", args: [to, amount] }),
     approve: ({ token, spender, amount }) =>
       simulateAndWrite({ address: token, functionName: "approve", args: [spender, amount] }),
-    async ensureAllowance({ token, spender, amount }) {
+    async ensureAllowance({ token, spender, amount, timeout, signal }) {
       const current = await erc20.allowance(token, spender);
       if (current >= amount) return null;
-      if (current > 0n) await approveAndWait(token, spender, 0n);
-      return approveAndWait(token, spender, amount);
+      if (current > 0n) await approveAndWait(token, spender, 0n, { timeout, signal });
+      return approveAndWait(token, spender, amount, { timeout, signal });
     },
   };
 
@@ -217,7 +703,9 @@ export function evmClient(config: EvmClientConfig): EvmClient {
         ...parameters,
       } as EvmSendTransactionParameters),
     writeContract: writeContract as EvmClient["writeContract"],
-    waitForTransactionReceipt: (hash) => publicClient.waitForTransactionReceipt({ hash }),
+    waitForTransactionReceipt: (hash, options) => waitForReceipt(hash, options),
+    confirmTransaction: (hash, options) => confirmTransaction(hash, options),
+    explorerTxUrl,
     erc20,
   };
 }

package/src/clients/index.ts

@@ -11,13 +11,21 @@ export {
   type ClientFamily,
 } from "./types";
 export {
+  classifyTxError,
   evmClient,
+  ReceiptPendingError,
+  ReceiptWaitAbortedError,
+  TransactionReplacedError,
+  TransactionRevertedError,
   type Erc20Actions,
   type EvmClient,
   type EvmClientConfig,
+  type EvmReplacementReason,
   type EvmSendTransactionParameters,
+  type EvmWaitOptions,
   type EvmWalletClient,
   type EvmWriteContractParameters,
+  type TxErrorKind,
 } from "./evm";
 export { suiClient, type SuiClient } from "./sui";
 export { bitcoinClient, type BitcoinClient } from "./bitcoin";