bug: GatewayClient mislabels receipt-wait failures as "Mint transaction failed" and never checks receipt.status for real reverts

[sharken3948]

Summary

@circle-fin/x402-batching 3.2.0 wraps every waitForTransactionReceipt exception in GatewayClient.withdraw() as Mint transaction failed: <hash>, even when the underlying transaction succeeded onchain. At the same time, it never inspects receipt.status, so a transaction that actually reverted is reported as a successful withdrawal. The false-failure case is intermittent in the wild (it depends on RPC receipt propagation), but I include a deterministic repro below, and the unchecked-revert case is visible by code inspection.

I first hit this in production on Arc Testnet while building an x402 marketplace: the SDK threw Mint transaction failed: 0x4dce8d4f037369aad86f2711023605c15275d0e6a73d460771f9733475b30759, but that tx was confirmed onchain with status Success, no revert, gas 141697/143989 (98.41%).

Onchain evidence: https://testnet.arcscan.app/tx/0x4dce8d4f037369aad86f2711023605c15275d0e6a73d460771f9733475b30759

Affected code

src/client/GatewayClient.ts, inside withdraw() (also reached via the deprecated transfer() alias):

try {
  await destPublicClient.waitForTransactionReceipt({ hash: mintTxHash });
} catch (err) {
  throw new Error(`Mint transaction failed: ${mintTxHash}`, { cause: err });
}

Two problems with this pattern:

1. False failure on transient errors. viem's waitForTransactionReceipt throws on timeouts and RPC errors (for example a transient 5xx or receipt propagation lag exhausting the default retry budget). None of these mean the mint failed. The tx was already broadcast and, in both cases below, already confirmed. Callers who trust this error and trigger refund or retry logic risk double payouts.

2. Real reverts pass silently. viem does not throw when a transaction reverts. It resolves with receipt.status === 'reverted'. Since the code only catches exceptions and never checks the status field, an actually reverted mint returns a successful WithdrawResult with a mintTxHash pointing at a failed tx.

The same catch-without-status-check pattern repeats in deposit(), depositFor(), initiateTrustlessWithdrawal() and completeTrustlessWithdrawal().

Deterministic repro

Observed naturally in production on July 15 (evidence above). To isolate the SDK's error handling, I also built a fault-injection repro: a local JSON-RPC proxy that forwards every request to https://rpc.testnet.arc.network unchanged, except eth_getTransactionReceipt, which gets an injected HTTP 500 — simulating the transient receipt-lookup failures public RPCs produce under load.

Running GatewayClient.transfer('0.0009', 'arcTestnet', <own address>) through that proxy on 3.2.0:

[repro] SDK threw as expected:
Mint transaction failed: 0xab19fc6283d7da40803d3d917fbe6635e90b5ded3215dc15c157a37ddcaafd69
[repro] verifying on-chain via direct RPC (bypassing proxy)
[repro] on-chain receipt: status=success gasUsed=135209
[repro] CONFIRMED: SDK reported failure but tx succeeded on-chain.

Repro tx: https://testnet.arcscan.app/tx/0xab19fc6283d7da40803d3d917fbe6635e90b5ded3215dc15c157a37ddcaafd69

Happy to share the proxy + repro scripts if useful.

Expected behavior

• A receipt-wait exception should surface as an indeterminate/receipt-timeout error (ideally with the tx hash in a structured field), not as a definitive mint failure.
• receipt.status should be checked after a successful wait, and 'reverted' should be the case that produces a failure.

Suggested fix

let receipt;
try {
  receipt = await destPublicClient.waitForTransactionReceipt({ hash: mintTxHash });
} catch (err) {
  throw new Error(
    `Mint receipt not confirmed within timeout (tx may still succeed): ${mintTxHash}`,
    { cause: err },
  );
}
if (receipt.status === 'reverted') {
  throw new Error(`Mint transaction reverted: ${mintTxHash}`);
}

Exposing receipt timeout and confirmation count via GatewayClientConfig would also help consumers on chains with slower or flakier public RPCs.

Workaround I am using

In my payment path I catch the error, extract the hash with /Mint transaction failed: (0x[a-fA-F0-9]{64})/, and poll the receipt myself with a 60s budget. status === 'success' recovers the payment, status === 'reverted' stays a failure. The workaround commit (July 15) documents the error as first encountered: sharken3948/Mahshar@2815dc0

Happy to test a fix.

Environment

• @circle-fin/x402-batching 3.2.0
• viem 2.52.2 (SDK internal), Arc Testnet (eip155:5042002)
• Filing here since the package has no public repository field on npm; precedent for SDK issues in this repo: Bug: Documented exports 'withGateway' and 'CircleGatewayClient' missing in latest '@circle-fin/x402-batching' #101

[osr21]

I can independently confirm both bugs and add some Arc-specific context from building arc-relay-bridge — a CCTP V2 bridge that also makes calls through similar receipt-wait paths on Arc Testnet.

---

Independent tx verification

I polled both transactions directly via arc-testnet.drpc.org (bypassing the primary RPC):

Tx	Block	Gas used	Status
0x4dce8d... (your production case)	51,955,413	141,697	0x1 — success
0xab19fc... (fault-injection repro)	52,256,442	135,209	0x1 — success

Both transactions were confirmed on-chain. The SDK errors were false negatives in both cases, consistent with your report.

---

Why this is especially prevalent on Arc Testnet

Arc's primary RPC https://rpc.testnet.arc.network applies a per-connection rate limit that returns {"code": -32011, "message": "request limit reached"} on eth_getTransactionReceipt calls made at any real throughput. Under a payment flow that chains approve → burn → attest → mint, the cumulative receipt polls easily exhaust the budget — so waitForTransactionReceipt times out or throws an HTTP error on the receipt lookup, not because the tx is absent.

We found that using https://arc-testnet.drpc.org for receipt polling is significantly more reliable on Arc (it has proper rate-limit tiers and no -32011 throttle). Adding it as a fallback RPC for the destPublicClient in GatewayClientConfig would mitigate a large share of the false-negative case without any code change.

---

Pattern we use in arc-relay-bridge

We hit exactly this class of failure on the mint step and ended up with a waitWithRetry helper that separates the two failure modes:

async function waitWithRetry(
  tx: TransactionResponse,
  fallbackRpcUrls: string[],
  retries = 4,
  retryDelayMs = 4000,
): Promise<TransactionReceipt> {
  const isTransient = (err: unknown) => {
    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
    return msg.includes('network') || msg.includes('timeout') ||
           msg.includes('could not detect') || msg.includes('connection');
  };

  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      const receipt = await tx.wait();
      if (receipt) {
        // Bug 2 fix: viem/ethers resolves — not throws — for on-chain reverts.
        // status 0 is a definitive failure; surface it explicitly.
        if (receipt.status !== 1) {
          throw new Error(`Transaction reverted on-chain: ${tx.hash}`);
        }
        return receipt;
      }
    } catch (err) {
      if (!isTransient(err)) throw err;   // definitive errors bubble immediately
      if (attempt === retries) throw err;
    }

    // Transient error: wait, then poll via static fallback RPCs
    // independently of the wallet's connection state.
    await sleep(retryDelayMs);
    for (const url of fallbackRpcUrls) {
      try {
        const receipt = await new StaticProvider(url).getTransactionReceipt(tx.hash);
        if (receipt) {
          if (receipt.status !== 1)
            throw new Error(`Transaction reverted on-chain: ${tx.hash}`);
          return receipt;  // confirmed success via fallback RPC
        }
      } catch (inner) {
        if (String(inner).includes('reverted on-chain')) throw inner; // re-throw definitive
        // otherwise try next fallback
      }
    }
  }

  // Receipt genuinely unresolvable — indeterminate, not a confirmed failure.
  throw new Error(
    `Receipt not confirmed within timeout — tx may still succeed: ${tx.hash}. ` +
    `Check the explorer and retry rather than triggering a refund.`
  );
}

The key properties:

• Transient errors (network, timeout, RPC 5xx) → retry via static fallback RPCs that don't share the wallet's connection state
• receipt.status !== 1 → definitive on-chain revert → throw immediately and don't retry
• Exhausted retries without a receipt → indeterminate (not a confirmed failure) — the error message makes that explicit so callers don't trigger refunds/retries that cause double-payouts

---

Confirming the systematic scope

Your observation that deposit(), depositFor(), initiateTrustlessWithdrawal(), and completeTrustlessWithdrawal() share the same pattern is consistent with a code-grep of the affected file. The same two bugs — wrapping all wait exceptions as a definitive failure, and never checking receipt.status — repeat in each. A shared internal waitForReceiptOrThrow(client, hash, config) helper that centralises both checks would fix all call sites in one change.

---

Suggested API surface

For the GatewayClientConfig, two additions would cover the Arc use case cleanly:

interface GatewayClientConfig {
  // existing fields ...

  /** Extra RPC URLs polled for receipts when the primary destPublicClient times out.
   *  Useful on chains where the primary RPC throttles eth_getTransactionReceipt. */
  receiptFallbackRpcUrls?: Record<SupportedChain, string[]>;

  /** How long to wait for a receipt before giving up and throwing an indeterminate error.
   *  Default: 60_000 ms. Increase on chains with slow finality or flaky RPCs. */
  receiptTimeoutMs?: number;
}

Happy to test a fix on Arc Testnet once there's a build available.

[sharken3948]

Thanks for the independent verification, this is really useful.

The -32011 detail explains a lot. I was seeing the failures cluster around the mint step under load, which lines up with the receipt polls exhausting the per-connection budget rather than anything being wrong with the tx itself.

Your waitWithRetry split matches what I ended up doing in Mahshar as a workaround: treat a missing receipt as indeterminate and never as a confirmed failure, since that is exactly the path that triggers a refund on a payment that already settled onchain.

Agreed on the shared helper. A single waitForReceiptOrThrow used by deposit(), depositFor(), initiateTrustlessWithdrawal() and completeTrustlessWithdrawal() would fix all four call sites at once, and the two config fields you sketched cover the Arc case without forcing a hardcoded fallback RPC into the SDK.

Happy to test on Arc Testnet alongside you once there is a build.

[osr21]

The -32011 detail explains a lot. I was seeing the failures cluster around the mint step under load

One more data point worth having in the bug report: -32011 can fire within a single JSON-RPC batch, not just across sequential polls. I just hit this while testing — a 5-request batch to rpc.testnet.arc.network with identical eth_getTransactionReceipt calls returned:

req 1: ok
req 2: ok
req 3: {"code":-32011, "message":"request limit reached"}
req 4: ok
req 5: ok

Request 4 and 5 still succeed after request 3 fails — it's not a circuit breaker that kills the whole batch, just a partial rate-limit that touches one slot. This matters because viem's http() transport batches by default (createPublicClient with no explicit transport config coalesces calls). When waitForTransactionReceipt internally fires eth_getTransactionReceipt + eth_blockNumber in a batch and one slot gets -32011, viem may throw at the batch-response level rather than retrying just the throttled call — which is what produces the intermittent SDK error on a tx that has been confirmed.

arc-testnet.drpc.org returned all four receipt slots cleanly with no -32011, confirming it is safe to use as the fallback transport. One caveat if callers configure it directly: drpc's free tier caps JSON-RPC batches at 3 requests (code 31). For receipt-only polling a batch of 1–3 is fine, but if the transport is also coalescing other calls the batch can exceed that. Safest is to construct the fallback client with http(url, { batch: false }) or http(url, { batch: { batchSize: 1 } }).

---

On the error type for indeterminate receipts: the string-extraction workaround you described (regex on Mint transaction failed: (0x...)) only works because the hash is embedded in the message. If the SDK switches to a proper indeterminate error, it is worth giving it a typed structure:

class ReceiptTimeoutError extends Error {
  readonly txHash: `0x${string}`;
  constructor(txHash: `0x${string}`, cause?: unknown) {
    super(`Receipt not confirmed within timeout — tx may still succeed: ${txHash}`);
    this.txHash = txHash;
    this.cause = cause;
  }
}

That way consumers can do if (err instanceof ReceiptTimeoutError) { poll(err.txHash) } without any regex. viem already exports WaitForTransactionReceiptTimeoutError with a .hash field for the same reason — worth following that convention so the error surface is familiar to viem users.

---

On risk ranking across the four call sites: completeTrustlessWithdrawal is the one I would fix first. A false-negative there is the most dangerous: if the receipt wait throws and the caller treats it as a failure, the user may attempt to re-initiate a trustless withdrawal that already completed — depending on the contract's re-entrancy guards that could be a no-op or it could behave unexpectedly. deposit() and depositFor() are also high-risk (double-charge on retry), but the trustless withdrawal path has the smallest user recovery surface.

[sharken3948]

Really appreciate the extra digging here, the partial batch behavior is a useful detail.

I checked the SDK source though, and the batch mechanism does not apply here. GatewayClient builds its transport as http(rpcUrl) with no second argument, and passes only { chain, transport } to createPublicClient. viem's http transport does not batch by default (transport level batching is opt-in via http(url, { batch: true })), and client level batch.multicall also defaults to false and would only coalesce eth_call anyway, not eth_getTransactionReceipt or eth_blockNumber. So on this SDK, waitForTransactionReceipt fires its receipt and blockNumber polls as separate sequential requests, not as one JSON-RPC batch.

That does not weaken your finding, it just relocates it. The -32011 is real, but on the current SDK it hits as isolated sequential failures under load rather than as one throttled slot inside a batch, which matches the pattern I was seeing. Your partial-batch repro would become relevant the moment the SDK opts into batch: true, so it is still worth having on record as a forward-looking risk, just not the mechanism behind today's false negatives.

The drpc caveat is good to have. Constructing the fallback client with http(url, { batch: false }) is the safe default given drpc's 3-request batch cap, agreed.

On the typed error, fully agree. A ReceiptTimeoutError carrying txHash is much cleaner than regex over the message string, and following viem's WaitForTransactionReceiptTimeoutError convention (a typed error with a hash field) keeps the surface familiar to anyone already on viem. The regex was only ever a consumer-side workaround because the current error embeds the hash in the string.

And I agree on prioritizing completeTrustlessWithdrawal. A false-negative there has the smallest recovery surface for the user, so it is the most dangerous of the four. deposit() and depositFor() carry the double-charge risk on retry, but the withdrawal path is the one where a caller acting on a false failure can do the most damage.

[osr21]

You're right on the batch point — I had that wrong. I went back to the viem 2.x source to check.

http(url) with no options does not batch. The transport-level batch flag is opt-in and the SDK doesn't set it, so waitForTransactionReceipt fires eth_getTransactionReceipt as individual sequential requests, not coalesced. My partial-batch repro is a forward-looking data point rather than an explanation of the current failures. Thanks for checking the SDK source.

---

There is one thing in the waitForTransactionReceipt source that's worth adding to the record, since it bears directly on the fix scope.

The poll loop's catch block has this structure (src/actions/public/waitForTransactionReceipt.ts):

} catch (err) {
  if (
    err instanceof TransactionNotFoundError ||
    err instanceof TransactionReceiptNotFoundError
  ) {
    // tx not yet mined / may have been replaced — keep polling
    ...
  } else {
    done(() => emit.reject(err))   // ← everything else: immediate rejection
  }
}

A -32011 response is wrapped by viem as an RpcRequestError, not a TransactionNotFoundError. It hits the else branch — emit.reject — and waitForTransactionReceipt rejects immediately on the first throttled poll. There is no tolerance: one -32011 on one sequential receipt lookup ends the wait.

The retryCount: 6 default that's visible in the function signature applies only to the withRetry blocks used inside the replacement-transaction detection path, not to the main receipt fetch. It doesn't provide any protection here.

This confirms the fix has to be at the SDK level — catching the rejection and retrying via a fallback client — rather than just swapping the RPC provider on the existing destPublicClient. viem will still reject immediately on any RPC error regardless of which provider is behind the transport; the SDK is the layer that needs to retry.

[sharken3948]

This is a great find, and it sharpens the fix scope in exactly the right way.

The catch structure you pulled matches the behavior I've been seeing: a -32011 comes back as an RpcRequestError, which isn't a not-found error, so it takes the else branch and rejects on the first throttled poll. No tolerance, one throttle ends the wait. That lines up with the intermittent rejections on already-confirmed txs, since a single receipt lookup hitting the rate limit is enough.

And the retryCount point is the key one. If that default only guards the replacement-detection path and not the main receipt fetch, then there's genuinely no retry protection on the fetch that matters here. Swapping in a more reliable RPC lowers how often -32011 fires, but it doesn't change the fact that any single RPC error still rejects immediately, so on a busy enough flow it will still surface.

So I agree the fix has to live in the SDK, not in the transport. The SDK is the only layer that can catch the rejection, distinguish a transient RPC error from a definitive on-chain result, and retry the receipt lookup (ideally against a fallback client) before deciding anything. A better RPC is a mitigation, not the fix. That's also why the two original bugs matter together: even with retries in place, the SDK still has to check receipt.status to tell a real revert from a success, and still has to treat an exhausted retry as indeterminate rather than a confirmed failure.

Between a fallback RPC and SDK-level retry, the retry is the load-bearing part. The fallback just improves the odds on each attempt.

[osr21]

Connecting this to a broader pattern that's worth naming explicitly: -32011 is the root cause of both bugs in this report, and it surfaces in a third way that the discussion hasn't touched yet — the frontend approve path.

---

The three surfaces

1. waitForTransactionReceipt — already covered in this thread

The catch structure osr21 pulled from viem makes this definitive: -32011 → RpcRequestError → else branch → immediate reject. No retry, no tolerance, even if the tx is already confirmed. The retryCount: 6 default is irrelevant here.

2. eth_sendRawTransaction — the frontend path

When MetaMask submits a transaction and the RPC is rate-limiting, the error bubbles back not as a network error but as a contract revert with reason "Request is being rate limited." The ContractFunctionRevertedError.shortMessage reads:

The contract function 'approve' reverted with the following reason: Request is being rate limited.

This is the same -32011 error code, but viem's RPC error decoding wraps it in a revert shape because it appears in the response where a revert reason would be. Builders see it as a false contract failure on their approve step and have no indication it's a transient RPC error.

3. Server-side viem clients — keeper / relay paths

Any server-side readContract or writeContract that hits -32011 fails immediately. A keeper job that batch-settles 25 nanopay sessions gets one throttled poll → the whole tick fails, no sessions settle.

---

Working mitigations (tested against Arc Testnet, Chain ID 5042002)

Transport-level: viem fallback() across multiple providers

import { fallback, http } from "viem";

const ARC_RPCS = [
  "https://rpc.testnet.arc.network",
  "https://rpc.drpc.testnet.arc.network",
  "https://rpc.quicknode.testnet.arc.network",
  "https://rpc.blockdaemon.testnet.arc.network",
];

export const publicClient = createPublicClient({
  chain: arcTestnet,
  transport: fallback(ARC_RPCS.map(url => http(url))),
});

This distributes load and reduces how often any single poll hits -32011. As the thread has already established: mitigation, not fix — a single -32011 on a sequential receipt poll still terminates waitForTransactionReceipt because the rejection happens above the transport layer.

SDK-level: catch and retry waitForTransactionReceipt on -32011

The load-bearing fix. The SDK must distinguish a transient RPC error from a definitive on-chain result:

import { RpcRequestError } from "viem";

async function waitForReceiptWithRetry(
  client: PublicClient,
  hash: `0x${string}`,
  maxAttempts = 5,
): Promise<TransactionReceipt> {
  for (let i = 0; i < maxAttempts; i++) {
    try {
      return await client.waitForTransactionReceipt({ hash, pollingInterval: 2_000 });
    } catch (err) {
      const isRateLimit =
        err instanceof RpcRequestError && (err as any).code === -32011;
      if (isRateLimit && i < maxAttempts - 1) {
        await new Promise(r => setTimeout(r, 1_000 * (i + 1))); // linear back-off
        continue;
      }
      throw err;
    }
  }
  throw new Error("receipt wait: exhausted retries");
}

The GatewayClient fix in this issue should also adopt this pattern — the receipt catch block needs to inspect cause.code before deciding whether to rethrow as Mint transaction failed.

User-facing: normalize -32011 at the error display layer

function formatTxError(err: unknown): string {
  const raw = (err as any)?.shortMessage ?? (err as any)?.message ?? String(err);
  if (/rate.?limit|request limit reached/i.test(raw) || raw.includes("0x4cef52")) {
    return "Arc Testnet RPC is rate-limiting — please wait a few seconds and try again.";
  }
  return raw;
}

Without this, builders (and their users) see "The contract function 'approve' reverted..." and assume a contract bug.

---

One ask for Circle: officially document the alternative RPC endpoints (drpc, quicknode, blockdaemon) in this repo's testnet reference table. Currently they're undocumented — I only found them through community channels and have been using them as fallbacks in the Arc Stablecoin DApp. If they have the same rate limit, builders have no good option short of running their own node.

I've filed a dedicated tracking issue for the broader rate-limit problem at #207.

[sharken3948]

yeah you're right on the framing, -32011 showing up on all three surfaces is the real picture. the receipt wait and keeper paths line up with what i hit, and the approve one is the worst because it just looks like a contract bug if you dont know -32011 is behind it.

couple things though.

The retry helper checks err instanceof rpcrequesterror && err.code == -32011. but like you said yourself, on the approve path -32011 doesnt come as an rpcrequesterror, it comes wrapped as a revert (contractfunctionrevertederror). so that guard would miss the exact case you're describing. since the whole point is -32011 shows up in different wrappers depending on the rpc method, better to walk the cause chain for the code (or just match the message) instead of checking instanceof on one class.

On the 0x4cef52 in formatTxError, i cant tie that to the rate limit error at all. its not derivable from the message (keccak of "request is being rate limited" is 0x46c99825 and a string revert uses the standard error(string) selector 0x08c379a0 with the text in the payload). and formatTxError matches on the decoded message string anyway, so a raw selector wouldnt even show up there. if you pulled it from an actual payload lmk where, otherwise that branch never fires and the regex is doing all the work.

Also the ask to circle, those endpoints are already documented. the connect page has all four (primary blockdaemon dprc quicknode) at docs.arc.io/arc/references/connect-to-arc and they're in this repo's running-an-arc-node.md too. so the real question isnt docs, its whether they all share the same rate limit budget. if drpc/quicknode/blockdaemon have separate tiers then fallback actually spreads load if they re all behind the same throttle it doesnt do much thats the thing worth asking them.

anyway none of this changes the main point and i think we agree the sdk level retry is the actual fix fallback and error formatting are just mitigations on top and the two original bugs (checking receipt status and treating an exhausted wait as indeterminate not a failure) still need fixing either way.