perf(solana): drop two RPC round-trips from the x402 payment critical path

[VickyXAI]

Every Solana payment made two serial RPC calls before it could sign — measured at ~107ms each against sol.blockrun.ai, ~212ms of the ~286ms median gap between the 402 landing and the paid retry going out. Base's equivalent gap is 2ms.

Found while benchmarking Base vs Solana settle latency: the reproducible Solana penalty was never settlement, it was this client-side gap.

getMint was fetching a constant

SPL Token fixes decimals in InitializeMint and ships no instruction to change it, so a mint's decimals is immutable. This path only ever transfers USDC, and the module already exported SOLANA_USDC_DECIMALS = 6 — while the payment path paid 107ms per call to fetch that same 6 over the network.

The call is gone outright, and getMint is out of the dynamic import, so it no longer reaches the bundle either.

getLatestBlockhash cached for 10s

Valid ~150 slots (~60s). The default RPC already caches this method 30s server-side, so a value can be 30s old on arrival; 10s keeps the worst case ~40s and leaves ~20s of settlement margin.

Cached per RPC URL rather than in a single slot, because endpoints genuinely differ on what "latest" is. One slot would mean a client alternating between a primary and a fallback refetches on every single call. The duplicate guard is deliberately not scoped this way — see below.

The non-obvious part: reusing a blockhash needs a duplicate guard

Two payments sharing a blockhash with identical economics compile to a byte-identical message. ed25519 is deterministic, so both carry the same signature and Solana rejects the second as already-processed. Verified directly before writing the fix:

same amount, price=1 (the existing constant):
  sig A: 3svEyz4eLd9ZQAuEMfA2P7353bK2r4w4C7qTLGbkbCAW
  sig B: 3svEyz4eLd9ZQAuEMfA2P7353bK2r4w4C7qTLGbkbCAW
  IDENTICAL -> true

Two same-priced calls in a row is a completely ordinary agent pattern, so each cached blockhash tracks the transactions already signed against it.

On a collision the fee nonce is tried first, without touching the network: the priority fee is nudged until the message is distinct. One step is +1 microLamport/CU over 8000 CU = 0.008 lamports, and feePayer is the facilitator, so it isn't the user's cost either. The top of the range, 65 microLamports/CU, sits three orders of magnitude under the facilitator's 50,000 ceiling (validateComputeBudgetLimits in @x402/svm), so it cannot trip verification.

Ordering matters here. My first version refreshed the blockhash first, and repeated same-priced calls then refetched every single time and kept the entire RPC cost — which is exactly what a benchmark loop does. The live numbers caught it.

Caught in review, before merge

Three duplicate-transaction paths, each reproduced before it was fixed.

The exhausted-nonce path re-emitted payment #1 (0b7449b)

When all 65 fee-nonce values were spent on one blockhash, the fallback fetched a fresh blockhash and rebuilt at the default price. But a forced refresh legitimately returns the same blockhash — that is what the RPC's 30s server-side cache does — and the cache correctly resolves that to the same entry, duplicate-guard state and all. Rebuilding at the default price there reproduced payment #1 byte for byte and re-emitted it as a silent duplicate, and stayed stuck that way until the blockhash actually rotated.

Reproduced before fixing: 70 same-priced payments produced only 65 distinct transactions, with #66 onward duplicating #1.

The nonce search now re-runs against the refreshed entry instead of restarting at the default price, and a genuinely exhausted range throws a named error rather than handing back a transaction that cannot land.

Concurrent payments collided (1c0b3f1)

The blockhash lookup read the cache into a local before awaiting the RPC and still trusted it afterwards. A burst is all inside getLatestBlockhash at the same moment, so each call missed what its siblings had stored, built its own entry with an empty issued record, and produced the same bytes. Measured with a deterministic mock: 8 concurrent same-priced payments produced 2 to 3 distinct transactions. The lookup now re-reads after the wait.

Two endpoints on one blockhash produced identical bytes (1c0b3f1)

The record of what had already been signed was filed per RPC URL. Solana never sees which URL served a blockhash — a transaction's identity is its blockhash plus its economics — so a client with a fallback RPC could send a payment through the primary and the byte-identical payment through the fallback, and the second is rejected as already-processed.

This one predates the caching change: the original single-slot code also created an empty record on a URL mismatch. The per-URL test missed it by discarding the fallback transaction instead of asserting on it.

The record is now keyed by blockhash and shared across endpoints, while endpoints keep their own blockhash and TTL, which they do genuinely need. It is bounded to 8 recent blockhashes — one expires in ~60s, so an older entry cannot describe a transaction that could still land, and a long-running process no longer accumulates every blockhash and transaction it ever signed.

The tests could reach the live gateway

vi.doMock + vi.resetModules() per test rebuilds the module registry while createSolanaPaymentPayload's dynamic import is already in flight. Under Promise.all some imports resolved to the real @solana/web3.js and called the live gateway — visible as blockhashes the stub never returned, and about 30% flakiness. Both Solana test files now use a hoisted vi.mock, so they cannot reach the network.

Measured, live gateway, 24 real payments per run

Alternating chains, two models, before vs after:

	before	after
solana sign gap (median)	286ms	7ms
solana total, openai/chat-latest	1686ms	1412ms
solana total, anthropic/claude-haiku-4.5	1532ms	1143ms

Remaining outliers in the sign gap (~130ms, 2 of 12) are the 10s TTL expiring and refetching — as designed. 24/24 payments settled clean, no errors.

Verification

228 unit tests pass across 5 consecutive full-suite runs, no flakes; typecheck, lint and build clean. Ten tests cover the caching and the hazards, and each behaviour is mutation-checked — reverting it fails exactly its own test:

revert this	and this test fails
the re-read after the RPC wait	keeps eight concurrent same-priced payments distinct
blockhash keying of the issued record	does not repeat bytes across two endpoints
the nonce re-search after refresh	fails loudly once the fee-nonce range is spent
the TTL check	refetches once the blockhash TTL expires
per-URL blockhash entries	keeps a separate blockhash entry per RPC URL

Ships as 3.8.4 (VERSION, package.json, src/version.ts, CHANGELOG).

Follow-ups, deliberately not in this PR

The nonce search is O(n) per payment. The Nth same-priced payment on one blockhash re-signs from the default price upward, so the 65th does 64 wasted signs before falling back. Correct, but it is linear work on exactly the burst pattern this PR optimizes for. A per-entry nonce cursor would make it O(1), at the cost of giving up the "first payment on a blockhash always uses the default price" property.

Two separate processes on the same wallet can still collide. Same-amount payments from different processes can receive the same server-cached blockhash. The record is process-local, so that case is unchanged — neither worse nor better. Worth addressing if concurrent same-wallet workers are a real deployment shape.

No in-flight coalescing at the TTL boundary. N concurrent payments crossing the boundary each issue their own getLatestBlockhash. Still strictly better than before, where every payment fetched unconditionally.

[VickyXAI]

Pushed 0b7449b — review fixes on top of the caching change.

Correctness bug in the exhausted-nonce path. When all 64 fee-nonce steps collided, the code forced a blockhash refresh and reset the price to the default. But a forced refresh legitimately returns the same hash (30s server-side cache), which resolves to the same entry and issued set — so rebuilding at the default price reproduced payment #1 byte for byte. Exactly the duplicate Solana rejects. That case now throws rather than emitting a transaction that cannot land.

Cache keyed per RPC URL. Held in a single slot, a client alternating between a primary and a fallback endpoint would evict the entry every call and discard issued with it — silently disabling the duplicate guard precisely when two endpoints fronting one cluster can return the same blockhash.

getMint dropped outright rather than cached: this path only ever transfers USDC, whose decimals the module already exports.

Three new tests: exhausted range, TTL expiry under fake timers, per-RPC-URL isolation.

Re-verified end to end — 215 unit tests, typecheck, lint, build clean, and re-measured live against the built SDK: 24/24 payments settled, solana sign gap still 7ms median.