waitForTransactionReceipt() leaks polling handles after timeout when receipt is not found

[songge-cb]

Check existing issues

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

Viem Version

2.24.1

Current Behavior

When calling waitForTransactionReceipt() with an invalid or never-mined transaction hash, and the timeout is reached before a receipt is found:

• The returned promise is correctly rejected with a WaitForTransactionReceiptTimeoutError
• ❌ However, the internal polling loop started by watchBlockNumber() is not stopped
• This leaves active timers or handles in the background, which:
  • Causes test runners (e.g., Jest) to hang after tests finish
  • Risks long-term memory or resource exhaustion in production environments, especially when used inside retryable workflows or repeated polling scenarios

Expected Behavior

When timeout is reached and the promise is rejected:

• The internal polling loop should be stopped by calling _unwatch() (and optionally _unobserve())
• This ensures no lingering event loop handles or timers after the promise is settled
• Resource usage remains bounded and safe, even if the function is retried repeatedly with invalid transaction hashes

Steps To Reproduce

1. Call waitForTransactionReceipt() with a valid client and an invalid or never-mined txnHash
2. Set timeout to a low value (e.g., 1000ms)
3. Observe that the promise is rejected as expected after timeout
4. But the process (e.g., test runner) does not exit cleanly

Example

await client.waitForTransactionReceipt({
  hash: '0xdeadbeef...', // invalid or unmined tx
  timeout: 1000,
  pollingInterval: 100,
});

Link to Minimal Reproducible Example

No response

Anything else?

We're using Viem inside long-running Temporal workflows. A retryable activity using waitForTransactionReceipt() can leave behind a polling process if the tx hash is invalid. This accumulates over time, potentially exhausting resources.

To avoid this, we replaced Viem’s function with our own polling logic using getTransactionReceipt() — but we’d love to use the official method safely if this issue is addressed.

[github-actions]

Hello @songge-cb.

Please provide a minimal reproduction using StackBlitz, TypeScript Playground (for type issues), or a separate minimal GitHub repository.

Minimal reproductions are required as they save us a lot of time reproducing your config/environment and issue, and allow us to help you faster.

Once a minimal reproduction is added, a team member will confirm it works, then re-open the issue.

[songge-cb]

Hi team,

I’ve created a minimal reproduction of the issue using StackBlitz as requested. Here are the details:

Minimal Reproduction on StackBlitz

• Project: link
• Steps to Reproduce:
  1. Open the terminal in StackBlitz (bottom panel).
  2. Run npm test.
  3. Observe the output: the test passes (timeout returns null), but the terminal hangs (no prompt returns).
• Expected Behavior: Jest exits cleanly after the test completes.
• Actual Behavior: Jest hangs, indicating an unresolved async process from waitForTransactionReceipt. See the screenshot below, where I had to use ctrl + C to stop it.
• Note: I tried npm run test:debug (with --detectOpenHandles), but StackBlitz’s Node.js environment throws Cannot find global.gc function due to missing --expose-gc. The hang is still observable with npm test.

This reproduces the issue I described: waitForTransactionReceipt leaves an async process running after a timeout, which could accumulate in a retry workflow and exhaust resources. Please let me know if you need any adjustments to the repro!

Thanks,
Song

[rouzwelt]

oh man, I've been experiencing leaks for some time now, and I was just getting frustrated not being able to find where it is coming from, its is big project, and the experienced leak is very minimal, this looks like it might be it tbh. looking forward to this.
@songge-cb would you mind sharing your poling solution? Im interested to check it out and see if it solves my leak or not.

[songge-cb]

oh man, I've been experiencing leaks for some time now, and I was just getting frustrated not being able to find where it is coming from, its is big project, and the experienced leak is very minimal, this looks like it might be it tbh. looking forward to this. @songge-cb would you mind sharing your poling solution? Im interested to check it out and see if it solves my leak or not.

@rouzwelt I called getTransactionReceipt() with customized timeout check. FYI, see below.

async function pollForTransactionReceiptWithTimeout(
  client: ExtendedL1Client | ExtendedL2Client,
  txnHash: `0x${string}`,
  timeoutMs: number,
  pollingIntervalMs: number,
  confirmations: number = 1
): Promise<TransactionReceipt | null> {
  const start = Date.now();

  while (Date.now() - start < timeoutMs) {
    try {
      const receipt = await client.getTransactionReceipt({ hash: txnHash });
      if (receipt?.blockNumber != null) {
        if (confirmations <= 1) {
          return receipt;
        }

        const latestBlock = await client.getBlockNumber();
        const confirmationsMet =
          latestBlock - receipt.blockNumber + 1n >= BigInt(confirmations);
        if (confirmationsMet) {
          return receipt;
        }

        // Otherwise, continue polling for more confirmations
      }
    } catch (error: any) {
      if (!(error instanceof TransactionReceiptNotFoundError)) {
        throw error;
      }
    }

    await new Promise((resolve) => setTimeout(resolve, pollingIntervalMs));
  }

  return null; // timeout reached
}