@reyaxyz/common 0.365.3 → 0.366.0

package/src/utils/receipt-rpc-error.ts

@@ -0,0 +1,85 @@
+import { errorChain } from './error-chain';
+
+const TRANSIENT_HTTP = new Set([408, 429, 500, 502, 503, 504]);
+const TRANSIENT_CODES = new Set([
+  'TIMEOUT',
+  'ETIMEDOUT',
+  'ECONNABORTED',
+  'ECONNRESET',
+  'EPIPE',
+  'ECONNREFUSED',
+  'EAI_AGAIN',
+  'ENETDOWN',
+  'ENETUNREACH',
+  'EHOSTDOWN',
+  'EHOSTUNREACH',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_BODY_TIMEOUT',
+  'UND_ERR_SOCKET',
+]);
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null
+    ? (value as Record<string, unknown>)
+    : undefined;
+const temporaryRpc = (value: unknown): boolean => {
+  const error = record(value);
+  return (
+    typeof error?.message === 'string' &&
+    (error.code === -32002 ||
+      error.code === -32017 ||
+      (error.code === -32000 &&
+        /no backends available|temporarily unavailable/i.test(error.message)))
+  );
+};
+
+/** Read-only receipt failures. Never use this to decide to resend a transaction. */
+export function isTransientReceiptError(error: unknown): boolean {
+  let transient = false;
+  for (const entry of errorChain(error)) {
+    const failure = record(entry);
+    if (!failure) continue;
+    const response = record(failure.response);
+    const status = response?.statusCode;
+    if (typeof status === 'number' && (status < 200 || status >= 300)) {
+      // Ethers escalates exhausted HTTP throttling to a synthetic 599.
+      // Other 599 errors (post-processing, invalid gateways) remain failures.
+      const exhaustedThrottle =
+        failure.code === 'SERVER_ERROR' &&
+        status === 599 &&
+        failure.shortMessage === 'exceeded maximum retry limit' &&
+        typeof response?.statusMessage === 'string' &&
+        response.statusMessage.startsWith(
+          'CLIENT ESCALATED SERVER ERROR (429 ',
+        );
+      if (!TRANSIENT_HTTP.has(status) && !exhaustedThrottle) return false;
+      transient = true;
+      continue;
+    }
+    if (failure.code === 'NETWORK_ERROR') return false;
+    if (failure.code === 'UNKNOWN_ERROR' && failure.error !== undefined) {
+      if (!temporaryRpc(failure.error)) return false;
+      transient = true;
+    } else if (failure.code === 'BAD_DATA') {
+      // Missing request IDs are only transient when every returned error is
+      // a recognised provider timeout/rate-limit response. BAD_DATA alone isn't.
+      if (
+        failure.shortMessage !== 'missing response for request' ||
+        !Array.isArray(failure.value) ||
+        failure.value.length === 0 ||
+        !failure.value.every((value: unknown) => {
+          const reply = record(value);
+          return reply?.id === null && temporaryRpc(reply.error);
+        })
+      )
+        return false;
+      transient = true;
+    } else if (
+      typeof failure.code === 'string' &&
+      TRANSIENT_CODES.has(failure.code)
+    ) {
+      transient = true;
+    }
+  }
+  return transient;
+}

package/src/utils/transaction-receipt.ts

@@ -1,9 +1,13 @@
-import { Provider } from 'ethers';
+import { makeError, Provider } from 'ethers';
 import { delay } from './delay';
+import { isTransientReceiptError } from './receipt-rpc-error';
 
 type TransactionReceiptMetadata = {
   pollingInterval?: number;
+  /** Maximum read attempts, including the initial read. */
   maxRetries?: number;
+  /** Total observation budget, including RPC latency and provider retries. */
+  timeoutMs?: number;
 };
 
 export const getTransactionReceipt = async (
@@ -11,19 +15,56 @@ export const getTransactionReceipt = async (
   txHash: string,
   metadata: TransactionReceiptMetadata = {},
 ) => {
-  const maxRetries = metadata.maxRetries || 40;
-  const pollingInterval = metadata.pollingInterval || 50;
-
+  const maxRetries = metadata.maxRetries ?? 40;
+  const pollingInterval = metadata.pollingInterval ?? 50;
+  // Preserve the intended 40 x 50ms observation budget, now including RPC time.
+  const timeoutMs = metadata.timeoutMs ?? maxRetries * pollingInterval;
+  for (const [name, value] of Object.entries({
+    maxRetries,
+    pollingInterval,
+    timeoutMs,
+  })) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 2 ** 31 - 1) {
+      throw new Error(
+        `${name} must be a positive integer no greater than ${2 ** 31 - 1}`,
+      );
+    }
+  }
+  const deadline = performance.now() + timeoutMs;
+  let lastError: unknown;
   for (let attempts = 0; attempts < maxRetries; attempts++) {
-    const receipt = await provider.getTransactionReceipt(txHash);
-    if (receipt) {
-      return receipt;
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) break;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let expired = false;
+    try {
+      // Provider has no per-call abort API. Stop waiting at the deadline and
+      // never start another poll alongside an unfinished provider request.
+      const receipt = await Promise.race([
+        provider.getTransactionReceipt(txHash),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => {
+            expired = true;
+            reject(
+              makeError('Receipt observation timed out', 'TIMEOUT', {
+                operation: 'getTransactionReceipt',
+                reason: 'timeout',
+              }),
+            );
+          }, remaining);
+        }),
+      ]);
+      if (receipt) return receipt;
+      lastError = undefined;
+    } catch (error) {
+      if (expired || !isTransientReceiptError(error)) throw error;
+      lastError = error;
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
     }
-
-    // Wait for the specified interval before retrying
-    await delay(pollingInterval);
-    attempts++;
+    const wait = Math.min(pollingInterval, deadline - performance.now());
+    if (attempts + 1 < maxRetries && wait > 0) await delay(wait);
   }
-
+  if (lastError !== undefined) throw lastError;
   return null;
 };