eth: wallet-declared privatePending hint for nonce + gas routing (backs design gist)

[pragmaxim]

Draft — proposal, backs the design note: https://gist.github.com/pragmaxim/f71b03a4ed4c0030b6cba7fb0a302e96

Lets a wallet declare its in-flight private (alternative send-tx / relay) transactions on its EVM read requests, so Blockbook routes the nonce lookup and the gas estimate deterministically from authoritative wallet state instead of inferring "did this instance recently accept a send" via the recentSenders heuristic (fragile across restarts and load-balanced replicas).

The field is added in two places — top-level privatePending on getAccountInfo, and inside the existing specific object on estimateFee — because EthereumTypeGetNonces and EthereumTypeEstimateGas are the only two consumers of the recentSenders / useForNonces / nonceURL machinery. Declaring both is the prerequisite for a later change to retire that machinery (not done here; this is additive and keeps the heuristic as the fallback). The contract and its trust boundary are documented in docs/evm-send.md.

Commits

• ws: accept privatePending on getAccountInfo — WsPrivatePending{nonces,txids} + blockbook-api.ts + AddressFilter.PrivatePendingNonces (plumbing, no behavior change).
• eth: short-circuit nonce routing — EthereumTypeGetNonces routes to the relay when declared and raises the pending nonce to max(declared)+1; correct even for a tx this instance never cached.
• ws: preserve the highest nonce when capping — over-cap collapses to the max instead of first-N truncation.
• ws: document privatePending on estimateFee — extend the specific ts_type (contract only).
• eth: short-circuit gas-estimate routing — EthereumTypeEstimateGas routes on the declared hint; strips the bookkeeping from the forwarded eth_estimateGas call.
• docs(eth): document privatePending hint, tighten its contract and tests — review follow-ups (see below).

Notes

• A declared nonce is the answer (short-circuits the lookup); a declared estimate is only a routing signal — Blockbook still simulates, but against the right pending state.
• Additive and backward-compatible: absent the field, behavior is exactly today's (useForNonces fallback); older Blockbook ignores the field (json.Unmarshal).
• Trust boundary (accepted): privatePending is an unauthenticated, per-request client hint. It is never written into recentSenders or the pending-tx cache, so a hostile client can distort only its own request's answer — never shared state — and it does not re-open the eth: every gas estimate is sent to the alternative provider, burning its rate-limit quota #1629 hot-path quota drain, since a normal wallet declares it only when it genuinely has a private tx in flight. Documented in docs/evm-send.md.
• Suite is not yet wired to send the field; the gist lists the Suite-side edits.

Review follow-ups

A broad multi-angle, adversarially-verified review found no blockers. Applied in the last commit (no behavior change):

• docs: wrote the "Wallet-declared privatePending hint" section of docs/evm-send.md that the ts_doc/generated contract already pointed to, including the trust-boundary note above.
• contract: WsEstimateFeeReq.specific now references WsPrivatePending by name instead of duplicating the inline {nonces?; txids?} shape (single source of truth); documented that nonces entries are literal (0 is meaningful, not a sentinel). Both mirrored into the generated blockbook-api.ts and verified to match generator output.
• tests: added the production confirmedNonce=true + declared-floor combination (floor raises only pending, leaves confirmed untouched), a declared-nonce-0 routing case, the MaxUint64 benign-overflow boundary, and an estimate-side wire-decode test (specific.privatePending through a real WsEstimateFeeReq envelope).
• known, out of scope: the committed blockbook-api.ts is globally stale vs the generator (2-space vs 4-space indent + a couple of missing Tron fields) — pre-existing on master/base and passing the type-parity CI gate; these additions match generator output modulo that indent. A full regeneration is a separate cleanup.

🤖 Generated with Claude Code