waitForTransactionReceipt foot gun

[dcposch]

Check existing issues

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

Viem Version

2.23.2

Current Behavior

waitForTransactionReceipt sometimes returns a receipt for a completely different transaction.

This is very surprising behavior and cost us a day of debugging:

const hash = await walletClient.writeContract({...})
const receipt = await publicClient.waitForTransactionReceipt({ hash })
// Successful response, receipt for an unrelated transaction with txhash != hash

On digging through the code, it's because it is doing a lot of extra work (including downloading whole blocks and scanning transactions) to find a replacement transaction at the same sender + nonce.

Expected Behavior

The docs make it sound like replacement transactions are an optional feature:

Replacement detection (e.g. sped up transactions) is also supported.
...
onReplaced
Optional callback to emit if the transaction has been replaced.

...so it's unexpected that waitForTransactionReceipt would return a different tx, esp when not passing onReplaced.

Proposed fix

By default waitForTransactionReceipt should throw an error when the tx hash you're looking for didn't make it onchain, not return a different transaction.

Fixing this will also make your RPC usage more efficient. Instead of calling eth_getBlockByNumber, downloading and scanning entire blocks' worth of transactions (which is surprising, unexpected behavior by itself) you can poll the sender EOA's nonce with a lighter eth_getTransactionCount call.

If you see that the transaction count is >= the nonce of the transaction we're looking for, but the one we're looking for is not available, then throw an "transaction replaced" error.

--

Optionally keep the current behavior only if onReplaced is passed. In fact, I would consider replacing onReplaced with eg. a searchForReplacement boolean option, so that callers get a consistent promise-await interface instead of a callback.

Steps To Reproduce

• Use code snippet above.
• Race the writeContract call with another transaction from the same wallet at same nonce
• Then, waitForTransactionReceipt returns this other transaction's receipt, not the one it was called to look for.

Link to Minimal Reproducible Example

No response

Anything else?

No response

[jxom]

This behavior has existed since the inception of Viem, and also exists in Ethers. We can make it disabled by default for Viem v3. For now, you can disable it by passing checkReplacement: false.