feat: throwOnReceiptRevert

Author: jxom

.changeset/eleven-teeth-throw.md

@@ -0,0 +1,5 @@
+---
+"viem": patch
+---
+
+Added `throwOnReceiptRevert` property to `sendTransactionSync`, `writeContractSync`, `sendRawTransactionSync`.

site/pages/docs/actions/wallet/sendRawTransactionSync.md

@@ -63,3 +63,33 @@ const signature = await walletClient.sendRawTransaction({
   serializedTransaction: '0x02f850018203118080825208808080c080a04012522854168b27e5dc3d5839bab5e6b39e1a0ffd343901ce1622e3d64b48f1a04e00902ae0502c4728cbf12156290df99c3ed7de85b1dbfe20b5c36931733a33' // [!code focus]
 })
 ```
+
+### throwOnReceiptRevert (optional)
+
+- **Type:** `boolean`
+
+Whether to throw an error if the transaction was detected as reverted.
+
+```ts twoslash
+// [!include ~/snippets/walletClient.ts]
+// ---cut---
+const receipt = await walletClient.sendRawTransactionSync({
+  serializedTransaction: '0x02f850018203118080825208808080c080a04012522854168b27e5dc3d5839bab5e6b39e1a0ffd343901ce1622e3d64b48f1a04e00902ae0502c4728cbf12156290df99c3ed7de85b1dbfe20b5c36931733a33',
+  throwOnReceiptRevert: true // [!code focus]
+})
+```
+
+### timeout (optional)
+
+- **Type:** `number`
+
+Timeout for the transaction to be included in a block.
+
+```ts twoslash
+// [!include ~/snippets/walletClient.ts]
+// ---cut---
+const receipt = await walletClient.sendRawTransactionSync({
+  serializedTransaction: '0x02f850018203118080825208808080c080a04012522854168b27e5dc3d5839bab5e6b39e1a0ffd343901ce1622e3d64b48f1a04e00902ae0502c4728cbf12156290df99c3ed7de85b1dbfe20b5c36931733a33',
+  timeout: 20_000 // [!code focus]
+})
+```

site/pages/docs/actions/wallet/sendTransactionSync.md

@@ -381,6 +381,24 @@ const receipt = await walletClient.sendTransactionSync({
 })
 ```
 
+### throwOnReceiptRevert (optional)
+
+- **Type:** `boolean`
+
+Whether to throw an error if the transaction was detected as reverted.
+
+```ts twoslash
+// [!include ~/snippets/walletClient.ts]
+// ---cut---
+const receipt = await walletClient.sendTransactionSync({
+  account,
+  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+  value: 1000000000000000000n,
+  nonce: 69,
+  throwOnReceiptRevert: true // [!code focus]
+})
+```
+
 ### timeout (optional)
 
 - **Type:** `number`

site/pages/docs/contract/writeContractSync.md

@@ -457,6 +457,22 @@ await walletClient.writeContractSync({
 })
 ```
 
+### throwOnReceiptRevert (optional)
+
+- **Type:** `boolean`
+
+Whether to throw an error if the transaction was detected as reverted.
+
+```ts
+await walletClient.writeContractSync({
+  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+  abi: wagmiAbi,
+  functionName: 'mint',
+  args: [69420],
+  throwOnReceiptRevert: true // [!code focus]
+})
+```
+
 ### timeout (optional)
 
 - **Type:** `number`

src/actions/wallet/sendRawTransactionSync.test.ts

@@ -1,7 +1,10 @@
 import { expect, test } from 'vitest'
 import { accounts } from '~test/src/constants.js'
+import { ErrorsExample } from '../../../contracts/generated.js'
 import { anvilMainnet } from '../../../test/src/anvil.js'
+import { deployErrorExample } from '../../../test/src/utils.js'
 import { privateKeyToAccount } from '../../accounts/privateKeyToAccount.js'
+import { encodeFunctionData } from '../../utils/index.js'
 import { wait } from '../../utils/wait.js'
 import { mine } from '../index.js'
 import { prepareTransactionRequest } from './prepareTransactionRequest.js'
@@ -28,3 +31,30 @@ test('default', async () => {
   ])
   expect(receipt).toBeDefined()
 })
+
+test('args: throwOnReceiptRevert', async () => {
+  const { contractAddress } = await deployErrorExample()
+
+  const request = await prepareTransactionRequest(client, {
+    account: privateKeyToAccount(accounts[0].privateKey),
+    data: encodeFunctionData({
+      abi: ErrorsExample.abi,
+      functionName: 'revertWrite',
+    }),
+    gas: 100_000n,
+    throwOnReceiptRevert: true,
+    to: contractAddress!,
+  })
+  const serializedTransaction = await signTransaction(client, request)
+  await expect(() =>
+    Promise.all([
+      sendRawTransactionSync(client, {
+        serializedTransaction,
+      }),
+      (async () => {
+        await wait(100)
+        await mine(client, { blocks: 1 })
+      })(),
+    ]),
+  ).rejects.toThrow('The receipt marked the transaction as "reverted"')
+})

src/actions/wallet/sendRawTransactionSync.ts

@@ -1,5 +1,6 @@
 import type { Client } from '../../clients/createClient.js'
 import type { Transport } from '../../clients/transports/createTransport.js'
+import { TransactionReceiptRevertedError } from '../../errors/transaction.js'
 import type { ErrorType } from '../../errors/utils.js'
 import type { Chain } from '../../types/chain.js'
 import type { TransactionSerializedGeneric } from '../../types/transaction.js'
@@ -13,6 +14,8 @@ import {
 export type SendRawTransactionSyncParameters = {
   /** The signed serialized transaction. */
   serializedTransaction: TransactionSerializedGeneric
+  /** Whether to throw an error if the transaction was detected as reverted. @default true */
+  throwOnReceiptRevert?: boolean | undefined
   /** The timeout for the transaction. */
   timeout?: number | undefined
 }
@@ -50,7 +53,11 @@ export type SendRawTransactionSyncErrorType = RequestErrorType | ErrorType
  */
 export async function sendRawTransactionSync<chain extends Chain | undefined>(
   client: Client<Transport, chain>,
-  { serializedTransaction, timeout }: SendRawTransactionSyncParameters,
+  {
+    serializedTransaction,
+    throwOnReceiptRevert,
+    timeout,
+  }: SendRawTransactionSyncParameters,
 ): Promise<SendRawTransactionSyncReturnType<chain>> {
   const receipt = await client.request(
     {
@@ -64,5 +71,9 @@ export async function sendRawTransactionSync<chain extends Chain | undefined>(
   const format =
     client.chain?.formatters?.transactionReceipt?.format ||
     formatTransactionReceipt
-  return format(receipt) as SendRawTransactionSyncReturnType<chain>
+
+  const formatted = format(receipt) as SendRawTransactionSyncReturnType<chain>
+  if (formatted.status === 'reverted' && throwOnReceiptRevert)
+    throw new TransactionReceiptRevertedError({ receipt: formatted })
+  return formatted
 }

src/actions/wallet/sendTransactionSync.test.ts

@@ -2,10 +2,10 @@ import { describe, expect, test, vi } from 'vitest'
 
 import { accounts } from '~test/src/constants.js'
 import { maxUint256 } from '~viem/constants/number.js'
-import { Delegation } from '../../../contracts/generated.js'
+import { Delegation, ErrorsExample } from '../../../contracts/generated.js'
 import { getSmartAccounts_07 } from '../../../test/src/account-abstraction.js'
 import { anvilMainnet } from '../../../test/src/anvil.js'
-import { deploy } from '../../../test/src/utils.js'
+import { deploy, deployErrorExample } from '../../../test/src/utils.js'
 import { generatePrivateKey } from '../../accounts/generatePrivateKey.js'
 import { privateKeyToAccount } from '../../accounts/privateKeyToAccount.js'
 import {
@@ -327,6 +327,24 @@ test('no chain', async () => {
   `)
 })
 
+describe('args: throwOnReceiptRevert', async () => {
+  await setup()
+
+  const { contractAddress } = await deployErrorExample()
+
+  await expect(() =>
+    sendTransactionSync(client, {
+      account: sourceAccount.address,
+      data: encodeFunctionData({
+        abi: ErrorsExample.abi,
+        functionName: 'revertWrite',
+      }),
+      throwOnReceiptRevert: true,
+      to: contractAddress!,
+    }),
+  ).rejects.toThrow('The receipt marked the transaction as "reverted".')
+})
+
 describe('args: gasPrice', () => {
   test('sends transaction', async () => {
     await setup()
@@ -1460,6 +1478,25 @@ describe('local account', () => {
       ).toBe(40)
     })
   })
+
+  test('args: throwOnReceiptRevert', async () => {
+    await setup()
+
+    const { contractAddress } = await deployErrorExample()
+
+    await expect(() =>
+      sendTransactionSync(client, {
+        account: privateKeyToAccount(sourceAccount.privateKey),
+        data: encodeFunctionData({
+          abi: ErrorsExample.abi,
+          functionName: 'revertWrite',
+        }),
+        gas: 100_000n,
+        throwOnReceiptRevert: true,
+        to: contractAddress!,
+      }),
+    ).rejects.toThrow('The receipt marked the transaction as "reverted".')
+  })
 })
 
 describe('smart account', async () => {

src/actions/wallet/sendTransactionSync.ts

@@ -15,6 +15,10 @@ import {
   type AccountTypeNotSupportedErrorType,
 } from '../../errors/account.js'
 import { BaseError } from '../../errors/base.js'
+import {
+  TransactionReceiptRevertedError,
+  type TransactionReceiptRevertedErrorType,
+} from '../../errors/transaction.js'
 import type { ErrorType } from '../../errors/utils.js'
 import type { GetAccountParameter } from '../../types/account.js'
 import type {
@@ -91,6 +95,8 @@ export type SendTransactionSyncParameters<
   GetTransactionRequestKzgParameter<request> & {
     /** Polling interval (ms) to poll for the transaction receipt. @default client.pollingInterval */
     pollingInterval?: number | undefined
+    /** Whether to throw an error if the transaction was detected as reverted. @default true */
+    throwOnReceiptRevert?: boolean | undefined
     /** Timeout (ms) to wait for a response. @default Math.max(chain.blockTime * 3, 5_000) */
     timeout?: number | undefined
   }
@@ -111,6 +117,7 @@ export type SendTransactionSyncErrorType =
       | SendRawTransactionSyncErrorType
       | RecoverAuthorizationAddressErrorType
       | SignTransactionErrorType
+      | TransactionReceiptRevertedErrorType
       | RequestErrorType
     >
   | WaitForTransactionReceiptErrorType
@@ -184,6 +191,7 @@ export async function sendTransactionSync<
     maxPriorityFeePerGas,
     nonce,
     pollingInterval,
+    throwOnReceiptRevert,
     type,
     value,
     ...rest
@@ -314,7 +322,7 @@ export async function sendTransactionSync<
         }
       })()
 
-      return getAction(
+      const receipt = await getAction(
         client,
         waitForTransactionReceipt,
         'waitForTransactionReceipt',
@@ -324,6 +332,9 @@ export async function sendTransactionSync<
         pollingInterval,
         timeout,
       })
+      if (throwOnReceiptRevert && receipt.status === 'reverted')
+        throw new TransactionReceiptRevertedError({ receipt })
+      return receipt
     }
 
     if (account?.type === 'local') {
@@ -363,6 +374,7 @@ export async function sendTransactionSync<
         'sendRawTransactionSync',
       )({
         serializedTransaction,
+        throwOnReceiptRevert,
       })) as never
     }
 

src/actions/wallet/writeContractSync.test.ts

@@ -149,6 +149,35 @@ test('no chain', async () => {
   `)
 })
 
+describe('behavior: throw when receipt is reverted', () => {
+  test('default', async () => {
+    const { contractAddress } = await deployErrorExample()
+
+    await expect(() =>
+      writeContractSync(client, {
+        abi: ErrorsExample.abi,
+        address: contractAddress!,
+        functionName: 'revertWrite',
+        account: accounts[0].address,
+      }),
+    ).rejects.toThrow('The receipt marked the transaction as "reverted"')
+  })
+
+  test('args: throwOnReceiptRevert: false', async () => {
+    const { contractAddress } = await deployErrorExample()
+
+    await expect(
+      writeContractSync(client, {
+        abi: ErrorsExample.abi,
+        address: contractAddress!,
+        functionName: 'revertWrite',
+        account: accounts[0].address,
+        throwOnReceiptRevert: false,
+      }),
+    ).resolves.toBeDefined()
+  })
+})
+
 describe('args: chain', () => {
   test('default', async () => {
     const client = createWalletClient({

src/actions/wallet/writeContractSync.ts

@@ -39,7 +39,10 @@ export type WriteContractSyncParameters<
   account,
   chainOverride
 > &
-  Pick<SendTransactionSyncParameters<chain>, 'pollingInterval' | 'timeout'>
+  Pick<
+    SendTransactionSyncParameters<chain>,
+    'pollingInterval' | 'throwOnReceiptRevert' | 'timeout'
+  >
 
 export type WriteContractSyncReturnType<
   chain extends Chain | undefined = Chain | undefined,