Skip to content

waitForTransactionReceipt

Waits for the Transaction to be included on a Block (one confirmation), and then returns the Transaction Receipt.

The waitForTransactionReceipt action additionally supports Replacement detection (e.g. sped up Transactions).

Usage

example.ts
import { publicClient } from './client'
 
const transaction = await publicClient.waitForTransactionReceipt( 
  { hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d' }
)

{
 
 blockHash: '0xaf1dadb8a98f1282e8f7b42cc3da8847bfa2cf4e227b8220403ae642e1173088',
 
 blockNumber: 15132008n,
 
 from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
 
 ...
 
 status: 'success',
 
}

Returns

TransactionReceipt

The transaction receipt.

Parameters

confirmations (optional)

  • Type: number
  • Default: 1

The number of confirmations (blocks that have passed) to wait before resolving.

const transaction = await publicClient.waitForTransactionReceipt(
  { 
    confirmations: 5, 
    hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d' 
  }
)

onReplaced (optional)

  • Type: ({ reason: 'replaced' | 'repriced' | 'cancelled', replacedTransaction: Transaction, transaction: Transaction, transactionReceipt: TransactionReceipt }) => void

Optional callback to emit if the transaction has been replaced.

const transaction = await publicClient.waitForTransactionReceipt(
  { 
    hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
    onReplaced: replacement => console.log(replacement) 
  }
)

pollingInterval (optional)

  • Type: number

Polling frequency (in ms). Defaults to the Client's pollingInterval config.

const transaction = await publicClient.waitForTransactionReceipt(
  { 
    hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
    pollingInterval: 12_000, 
  }
)

retryCount (optional)

  • Type: number
  • Default: 6

Number of times to retry if the transaction or block is not found.

const transaction = await publicClient.waitForTransactionReceipt(
  { 
    hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
    retryCount: 3, 
  }
)

retryDelay (optional)

  • Type: number | (({ count: number; error: Error }) => number)
  • Default: ({ count }) => ~~(1 << count) * 200 (exponential backoff)

Time to wait (in ms) between retries.

const transaction = await publicClient.waitForTransactionReceipt(
  { 
    hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
    retryDelay: 10_000, 
  }
)

timeout (optional)

  • Type: number

Optional timeout (in milliseconds) to wait before stopping polling.

const transaction = await publicClient.waitForTransactionReceipt(
  { 
    hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
    timeout: 60_000, 
  }
)

Notes

  • Transactions can be replaced when a user modifies their transaction in their wallet (to speed up or cancel). Transactions are replaced when they are sent from the same nonce.
  • There are 3 types of Transaction Replacement reasons:
    • repriced: The gas price has been modified (ie. different maxFeePerGas)
    • cancelled: The Transaction has been cancelled (ie. value === 0n)
    • replaced: The Transaction has been replaced (ie. different value or data)

Live Example

Check out the usage of waitForTransactionReceipt in the live Sending Transactions Example below.

JSON-RPC Methods