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: "0x..." }
);

{
 
 type: 'legacy',
 
 transactionHash: '0x...',
 
 from: 'cfx:...',
 
 ...
 
 outcomeStatus: 'success',
 
}

Returns

TransactionReceipt

The transaction receipt.

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: 1, 
  hash: "0x...",
});

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: "0x...",
  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: "0x..",
  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: "0x...",
  retryCount: 10, 
});

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: "0x...",
  retryDelay: 10_000, 
});

timeout (optional)

  • Type: number

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

const transaction = await publicClient.waitForTransactionReceipt({
  hash: "0x...",
  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)

JSON-RPC Methods