feat: add throwOnFailure to waitForCallsStatus

Author: jxom

.changeset/itchy-terms-joke.md

@@ -0,0 +1,5 @@
+---
+"viem": patch
+---
+
+Added \`throwOnFailure\` to \`waitForCallsStatus\`.

site/pages/docs/actions/wallet/waitForCallsStatus.mdx

@@ -85,6 +85,34 @@ const result = await walletClient.waitForCallsStatus({
 })
 ```
 
+### retryCount
+
+- **Type:** `number`
+- **Default:** `4`
+
+Number of times to retry if the call bundle fails.
+
+```ts
+const result = await walletClient.waitForCallsStatus({
+  id: '0xdeadbeef',
+  retryCount: 10, // [!code focus]
+})
+```
+
+### retryDelay
+
+- **Type:** `number`
+- **Default:** `({ count }) => ~~(1 << count) * 200`
+
+Time to wait (in ms) between retries.
+
+```ts
+const result = await walletClient.waitForCallsStatus({
+  id: '0xdeadbeef',
+  retryDelay: 1_000, // [!code focus]
+})
+```
+
 ### status
 
 - **Type:** `(parameters: { statusCode: number, status: string | undefined }) => boolean`
@@ -99,6 +127,20 @@ const result = await walletClient.waitForCallsStatus({
 })
 ```
 
+### throwOnFailure
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to throw an error if the call bundle fails.
+
+```ts
+const result = await walletClient.waitForCallsStatus({
+  id: '0xdeadbeef',
+  throwOnFailure: true, // [!code focus]
+})
+```
+
 ### timeout
 
 - **Type:** `number`

src/actions/wallet/waitForCallsStatus.test.ts

@@ -4,6 +4,7 @@ import { accounts } from '../../../test/src/constants.js'
 import { mainnet } from '../../chains/index.js'
 import { createClient } from '../../clients/createClient.js'
 import { custom } from '../../clients/transports/custom.js'
+import { BundleFailedError } from '../../errors/calls.js'
 import { RpcRequestError } from '../../errors/request.js'
 import type {
   WalletCallReceipt,
@@ -238,3 +239,119 @@ test('behavior: `wallet_getCallsStatus` failure', async () => {
     }),
   ).rejects.toThrowError('RPC Request failed.')
 })
+
+test('behavior: throwOnFailure = true with failed bundle', async () => {
+  const client = createClient({
+    pollingInterval: 100,
+    transport: custom({
+      async request({ params }) {
+        return {
+          atomic: false,
+          chainId: '0x1',
+          id: params[0],
+          receipts: [],
+          status: 400,
+          version: '2.0.0',
+        } satisfies WalletGetCallsStatusReturnType
+      },
+    }),
+  })
+
+  try {
+    await waitForCallsStatus(client, {
+      id: 'test-bundle-id',
+      throwOnFailure: true,
+    })
+  } catch (e) {
+    const error = e as BundleFailedError
+    expect(error).toBeInstanceOf(BundleFailedError)
+    expect((error as BundleFailedError).name).toBe('BundleFailedError')
+    expect((error as BundleFailedError).result.status).toBe('failure')
+    expect((error as BundleFailedError).result.statusCode).toBe(400)
+  }
+})
+
+test('behavior: throwOnFailure = false with failed bundle (default)', async () => {
+  const client = createClient({
+    pollingInterval: 100,
+    transport: custom({
+      async request({ params }) {
+        return {
+          atomic: false,
+          chainId: '0x1',
+          id: params[0],
+          receipts: [],
+          status: 400,
+          version: '2.0.0',
+        } satisfies WalletGetCallsStatusReturnType
+      },
+    }),
+  })
+
+  const id = 'test-bundle-id'
+
+  // Should not throw by default (throwOnFailure = false)
+  const result = await waitForCallsStatus(client, {
+    id,
+  })
+
+  expect(result.status).toBe('failure')
+  expect(result.statusCode).toBe(400)
+  expect(result.id).toBe(id)
+})
+
+test('behavior: throwOnFailure = false explicitly with failed bundle', async () => {
+  const client = createClient({
+    pollingInterval: 100,
+    transport: custom({
+      async request({ params }) {
+        return {
+          atomic: false,
+          chainId: '0x1',
+          id: params[0],
+          receipts: [],
+          status: 500,
+          version: '2.0.0',
+        } satisfies WalletGetCallsStatusReturnType
+      },
+    }),
+  })
+
+  const id = 'test-bundle-id'
+
+  const result = await waitForCallsStatus(client, {
+    id,
+    throwOnFailure: false,
+  })
+
+  expect(result.status).toBe('failure')
+  expect(result.statusCode).toBe(500)
+  expect(result.id).toBe(id)
+})
+
+test('behavior: throwOnFailure = true with successful bundle', async () => {
+  const client = getClient()
+
+  const { id } = await sendCalls(client, {
+    account: accounts[0].address,
+    calls: [
+      {
+        to: accounts[1].address,
+        value: parseEther('1'),
+      },
+    ],
+    chain: mainnet,
+  })
+
+  expect(id).toBeDefined()
+
+  await mine(testClient, { blocks: 1 })
+
+  const result = await waitForCallsStatus(client, {
+    id,
+    throwOnFailure: true,
+  })
+
+  expect(result.status).toBe('success')
+  expect(result.statusCode).toBe(200)
+})

src/actions/wallet/waitForCallsStatus.ts

@@ -1,11 +1,16 @@
 import type { Client } from '../../clients/createClient.js'
 import type { Transport } from '../../clients/transports/createTransport.js'
 import { BaseError } from '../../errors/base.js'
+import { BundleFailedError } from '../../errors/calls.js'
 import type { ErrorType } from '../../errors/utils.js'
 import type { Chain } from '../../types/chain.js'
 import { type ObserveErrorType, observe } from '../../utils/observe.js'
 import { type PollErrorType, poll } from '../../utils/poll.js'
 import { withResolvers } from '../../utils/promise/withResolvers.js'
+import {
+  type WithRetryParameters,
+  withRetry,
+} from '../../utils/promise/withRetry.js'
 import { stringify } from '../../utils/stringify.js'
 import {
   type GetCallsStatusErrorType,
@@ -24,12 +29,28 @@ export type WaitForCallsStatusParameters = {
    * @default client.pollingInterval
    */
   pollingInterval?: number | undefined
+  /**
+   * Number of times to retry if the call bundle failed.
+   * @default 4 (exponential backoff)
+   */
+  retryCount?: WithRetryParameters['retryCount'] | undefined
+  /**
+   * Time to wait (in ms) between retries.
+   * @default `({ count }) => ~~(1 << count) * 200` (exponential backoff)
+   */
+  retryDelay?: WithRetryParameters['delay'] | undefined
   /**
    * The status range to wait for.
    *
    * @default (status) => status >= 200
    */
   status?: ((parameters: GetCallsStatusReturnType) => boolean) | undefined
+  /**
+   * Whether to throw an error if the call bundle fails.
+   *
+   * @default false
+   */
+  throwOnFailure?: boolean | undefined
   /**
    * Optional timeout (in milliseconds) to wait before stopping polling.
    *
@@ -76,8 +97,11 @@ export async function waitForCallsStatus<chain extends Chain | undefined>(
   const {
     id,
     pollingInterval = client.pollingInterval,
-    status = ({ statusCode }) => statusCode >= 200,
+    status = ({ statusCode }) => statusCode === 200 || statusCode >= 300,
+    retryCount = 4,
+    retryDelay = ({ count }) => ~~(1 << count) * 200, // exponential backoff
     timeout = 60_000,
+    throwOnFailure = false,
   } = parameters
   const observerId = stringify(['waitForCallsStatus', client.uid, id])
 
@@ -97,7 +121,18 @@ export async function waitForCallsStatus<chain extends Chain | undefined>(
         }
 
         try {
-          const result = await getCallsStatus(client, { id })
+          const result = await withRetry(
+            async () => {
+              const result = await getCallsStatus(client, { id })
+              if (throwOnFailure && result.status === 'failure')
+                throw new BundleFailedError(result)
+              return result
+            },
+            {
+              retryCount,
+              delay: retryDelay,
+            },
+          )
           if (!status(result)) return
           done(() => emit.resolve(result))
         } catch (error) {

src/errors/calls.ts

@@ -0,0 +1,17 @@
+import type { GetCallsStatusReturnType } from '../actions/wallet/getCallsStatus.js'
+import { BaseError } from './base.js'
+
+export type BundleFailedErrorType = BundleFailedError & {
+  name: 'BundleFailedError'
+}
+export class BundleFailedError extends BaseError {
+  result: GetCallsStatusReturnType
+
+  constructor(result: GetCallsStatusReturnType) {
+    super(`Call bundle failed with status: ${result.statusCode}`, {
+      name: 'BundleFailedError',
+    })
+
+    this.result = result
+  }
+}