waitForTransactionReceipt does not work as expected

[Pasha8914]

Check existing issues

• I checked there isn't already an issue for the bug I encountered.

Viem Version

2.34.0

Current Behavior

The waitForTransactionReceipt function does not handle the scenario where a transaction is no longer found on the network (e.g., because it was replaced by a newer one with the same nonce and a higher gas price, or it was simply dropped from the mempool). Instead of rejecting the promise with a clear error

First Issue: The function cannot find transactions that have been replaced or dropped
Second Issue: Regardless of the configuration (e.g., timeout, retryCount), the function's promise never settles (neither resolves nor rejects) if it cannot locate the transaction hash on the blockchain

Expected Behavior

waitForTransactionReceipt should detect replaced transactions or throw an error

Steps To Reproduce

This app has two buttons:

• Send 1 wei to yourself — submits a self-transfer with intentionally tiny EIP-1559 fees so it stays pending.
• Speed Up — resubmits the same nonce with higher fees, replacing the first transaction.

How to reproduce

1. Click Send 1 wei to yourself.

   • The tx uses maxFeePerGas = 2 and maxPriorityFeePerGas = 1 (wei), so it will not get mined on Sepolia. It remains pending indefinitely.
   • waitForTransactionReceipt for this tx never resolves with a receipt (by design), because the transaction won’t be included in a block.

2. After a short wait, click Speed Up.

   • The app sends a replacement tx with the same nonce and higher fees (roughly 2× the current estimateFeesPerGas values).
   • This replacement supersedes the first tx. You’ll see a receipt in the console only for the second (speed-up) transaction.
   • The original tx will never produce a receipt, because it was replaced before inclusion.

3. If you don’t click Speed Up, nothing will happen: the first tx stays pending forever and no receipt is printed.

Screen.Recording.2025-08-20.at.20.37.57.mp4

Link to Minimal Reproducible Example

https://github.com/Pasha8914/waitForTransactionReceipt-bug

Anything else?

No response

[jxom]

I cannot reproduce this issue. Can you please break this test I made for this issue, or our existing replacement tests?

[Pasha8914]

I cannot reproduce this issue. Can you please break this test I made for this issue, or our existing replacement tests?

please run my test
I've managed to narrow down the problem more precisely

The issue is that during a gas spike, my transaction is rejected from the mempool. Therefore, when I try to speed it up, there is no original transaction to replace, and I do not receive a new transaction hash

[Pasha8914]

@jxom

[jxom]

I will look into it. Please feel free to raise a PR to fix in the meantime.

[sambacha]

just to clarify, there is a difference between replace and repriced

[Pasha8914]

just to clarify, there is a difference between replace and repriced

repriced = a special case of replace, where the data is identical and only the gas/fee is changed
Why highlight repriced separately in this case? What exactly did you mean by your message?

[Pasha8914]

@sambacha