docs(eth): document privatePending hint, tighten its contract and tests

Review follow-ups for the wallet-declared privatePending hint; no behavior change.

- docs/evm-send.md: add the "Wallet-declared privatePending hint" section the
  ts_doc/generated contract already point to but that was never written, including
  the accepted trust-boundary rationale (the hint is an unauthenticated, per-request
  signal: it routes only the caller's own request to the relay, never touches shared
  state, and does not re-open the #1629 hot-path quota drain).
- server/ws_types.go: reference WsPrivatePending by name in WsEstimateFeeReq.specific
  instead of duplicating the inline {nonces?;txids?} shape (single source of truth);
  document that Nonces entries are literal (0 is meaningful, not a sentinel). Mirror
  both edits into the generated blockbook-api.ts by hand (matching the file's style).
- bchain/coins/eth/ethrpc.go: note the trust boundary at the estimate routing gate.
- tests: add 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).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: pragmaxim

bchain/coins/eth/ethrpc.go

@@ -1991,6 +1991,9 @@ func (b *EthereumRPC) EthereumTypeEstimateGas(params map[string]interface{}) (ui
 	// estimateFee endpoint does not burn the provider's rate-limit quota (#1629); a missing/empty
 	// `from` also takes the primary path. Unlike the nonce hint - which IS the answer and short-
 	// circuits the lookup - a declared estimate only selects the backend; Blockbook still simulates.
+	// The hint is an unauthenticated, per-request client signal: it can route only the caller's own
+	// request to the relay and never touches shared state, so it does not re-open the #1629 hot-path
+	// quota drain (accepted trust boundary, see docs/evm-send.md).
 	declaredPrivatePending := estimatePrivatePendingDeclared(params)
 	if b.alternativeSendTxProvider != nil && msg.From != (ethcommon.Address{}) &&
 		(declaredPrivatePending || b.alternativeSendTxProvider.useForNonces(msg.From)) {

bchain/coins/eth/nonce_hint_test.go

@@ -3,6 +3,7 @@
 package eth
 
 import (
+	"math"
 	"testing"
 	"time"
 
@@ -70,6 +71,54 @@ func TestEthereumTypeGetNonces_PrivatePendingHint_RaisesPrimaryFallback(t *testi
 	}
 }
 
+// TestEthereumTypeGetNonces_PrivatePendingHint_WithConfirmedNonce exercises the exact production
+// combination (api/worker.go passes WithConfirmedNonce together with PrivatePendingNonces...): the
+// declared floor must raise only the PENDING nonce and leave the confirmed (latest) nonce untouched.
+func TestEthereumTypeGetNonces_PrivatePendingHint_WithConfirmedNonce(t *testing.T) {
+	server := newNonceRPCServer(t, map[string]string{"pending": "0x9", "latest": "0x5"}, nil)
+	stub := &nonceBatchStub{results: map[string]string{"pending": "0x4", "latest": "0x2"}}
+	// no recent senders → routed purely by the declared floor
+	b := &EthereumRPC{RPC: stub, Timeout: time.Second, alternativeSendTxProvider: newRecentSenderProvider(server)}
+
+	// declared nonce 42 → pending floor 43, above the provider's pending answer of 9
+	pending, confirmed, confirmedOK, err := b.EthereumTypeGetNonces(nonceTestAddr, true, 42)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pending != 43 {
+		t.Errorf("pending = %d, want 43 (declared floor over the provider answer)", pending)
+	}
+	if confirmed != 5 || !confirmedOK {
+		t.Errorf("confirmed = (%d, ok=%v), want (5, true) — the floor must not touch the confirmed nonce", confirmed, confirmedOK)
+	}
+	if len(stub.queried) != 0 {
+		t.Errorf("primary RPC queried tags %v, want none once routed to the provider", stub.queried)
+	}
+}
+
+// TestEthereumTypeGetNonces_PrivatePendingHint_RoutesOnDeclaredZero confirms a declared nonce of 0
+// (a wallet's very first tx) still trips the routing guard (declaredFloor 1 > 0) and raises the
+// pending nonce to 1 — the boundary the routing tests above (nonce 42) do not exercise.
+func TestEthereumTypeGetNonces_PrivatePendingHint_RoutesOnDeclaredZero(t *testing.T) {
+	server := newNonceRPCServer(t, map[string]string{"pending": "0x0"}, nil)
+	stub := &nonceBatchStub{results: map[string]string{"pending": "0x0"}}
+	b := &EthereumRPC{RPC: stub, Timeout: time.Second, alternativeSendTxProvider: newRecentSenderProvider(server)}
+
+	pending, _, _, err := b.EthereumTypeGetNonces(nonceTestAddr, false, 0)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pending != 1 {
+		t.Errorf("pending = %d, want 1 (declared nonce 0 → floor 1)", pending)
+	}
+	if got := server.callCount("pending"); got != 1 {
+		t.Errorf("alternative provider queried %d times, want 1 (declared 0 must still route)", got)
+	}
+	if len(stub.queried) != 0 {
+		t.Errorf("primary RPC queried tags %v, want none once routed to the provider", stub.queried)
+	}
+}
+
 // TestEthereumTypeGetNonces_PrivatePendingHint_IgnoredWithoutProvider confirms the hint is a
 // relay-deployment feature: with no alternative provider configured it is ignored and the primary
 // answer stands unchanged.
@@ -124,6 +173,11 @@ func TestDeclaredPendingFloor(t *testing.T) {
 		{[]uint64{0}, 1},
 		{[]uint64{5}, 6},
 		{[]uint64{5, 42, 7}, 43},
+		// n+1 wraps to 0 at MaxUint64; the entry is silently ignored (benign: the floor is only
+		// ever a max() operand, so a spurious 0 can never lower the reported nonce).
+		{[]uint64{math.MaxUint64}, 0},
+		// a physically-unreachable max value co-declared with a real nonce must not corrupt it.
+		{[]uint64{math.MaxUint64, 43}, 44},
 	}
 	for _, c := range cases {
 		if got := declaredPendingFloor(c.in); got != c.want {

blockbook-api.ts

@@ -682,7 +682,7 @@ export interface WsRes {
     data: any;
 }
 export interface WsPrivatePending {
-    /** Account nonces of the wallet's in-flight private transactions for this address. */
+    /** Account nonces of the wallet's in-flight private transactions for this address. Each entry is a literal in-flight nonce (0 is a valid value, not a sentinel); do not pad or default the array, as any entry raises the reported pending nonce to at least value+1. */
     nonces?: number[];
     /** Transaction hashes of the in-flight private transactions (reserved for future use). */
     txids?: string[];
@@ -819,7 +819,7 @@ export interface WsEstimateFeeReq {
     /** Block confirmations targets for which fees should be estimated. */
     blocks?: number[];
     /** Additional chain-specific parameters (e.g. for Ethereum). privatePending (Ethereum-like) declares the sender's in-flight private transactions so the gas estimate is routed to the alternative send-tx provider; see WsPrivatePending and docs/evm-send.md. */
-    specific?: {conservative?: boolean; txsize?: number; from?: string; to?: string; data?: string; value?: string; privatePending?: {nonces?: number[]; txids?: string[]};};
+    specific?: {conservative?: boolean; txsize?: number; from?: string; to?: string; data?: string; value?: string; privatePending?: WsPrivatePending;};
 }
 export interface Eip1559Fee {
     maxFeePerGas?: string;

docs/evm-send.md

@@ -82,6 +82,47 @@ Key invariants:
   pending tx is gone on its next account re-fetch (the initiating device also removes it
   optimistically). The cache timeout is the backstop for anything the deterministic evictions miss.
 
+## Wallet-declared `privatePending` hint (nonce + gas routing)
+
+A private relay exposes no mempool, so a transaction pending only there is invisible to the public
+backend RPC. Blockbook otherwise *infers* "this sender has a private tx in flight" from the
+`recentSenders` map (populated by `registerSuccessfulSend`), which is fragile across restarts and
+across load-balanced replicas without request affinity. A wallet already knows this state with
+certainty, so it may **declare** it on its read requests via an optional `privatePending` field.
+Blockbook then routes deterministically from that declaration instead of guessing.
+
+The field appears in two places, matching the two consumers of the routing machinery:
+
+- **`getAccountInfo` → top-level `privatePending: {nonces, txids}`** drives the pending-**nonce**
+  lookup. A declared nonce *is* the answer: Blockbook routes the `eth_getTransactionCount` to the
+  relay and reports at least `max(nonces) + 1`, so the wallet can never reuse the nonce of a private
+  tx it has in flight — even for a tx this instance never cached (accepted by another replica, or
+  lost to a restart). The declared floor only ever *raises* the reported nonce; it never lowers a
+  higher provider/primary answer. The nonce list is capped (see `maxPrivatePendingNonces`) and, past
+  the cap, collapsed to its single highest entry — only the maximum matters for the floor.
+- **`estimateFee` → `specific.privatePending`** is a **routing signal only**. Unlike a nonce, the
+  wallet cannot compute gas itself, so Blockbook still simulates the call — the declaration only says
+  "estimate against the relay's pending-private state" (e.g. a privately-submitted `approve` a
+  following swap's gas depends on). Presence of a non-empty `nonces` array is all that is read; the
+  field is stripped before the `eth_estimateGas` call object is forwarded to the relay.
+
+Only `nonces` drives behavior today; `txids` is accepted for forward compatibility (future
+pending-tx correlation) and is not yet consumed on any path.
+
+The hint is **additive and backward-compatible**: absent the field, behavior is exactly as before
+(the `recentSenders` heuristic remains the fallback, and is still consulted when no hint is
+declared), and an older Blockbook simply ignores the unknown field. With no alternative provider
+configured the hint is a no-op (there is no private mempool to reconcile against).
+
+**Trust boundary (accepted).** `privatePending` is an *unauthenticated client hint* — Blockbook does
+not verify the caller owns the address or that a private tx actually exists. This is safe because the
+declaration is per-request only: it is never written into `recentSenders` or the pending-tx cache, so
+a hostile client can distort only its **own** request's answer and cannot poison another client's
+view or any shared state. Its one outward effect is forcing the read to route to the relay; that is
+bounded by the relay's own rate-limit quota and the per-connection pending-requests limit, and — by
+design — does **not** re-introduce the #1629 hot-path quota drain, because a normal wallet declares
+the field only when it genuinely has a private tx in flight (rare), not on every keystroke.
+
 ## Observability
 
 Prometheus counters for the cache lifecycle:

server/websocket_privatepending_test.go

@@ -95,3 +95,28 @@ func TestPrivatePendingJSONRoundTripsThroughWsReq(t *testing.T) {
 		t.Fatalf("privatePending = %+v, want nonces [5]", r.PrivatePending)
 	}
 }
+
+// TestEstimateFeePrivatePendingDecodesIntoSpecific confirms the estimate-side wire contract: a real
+// estimateFee envelope carrying specific.privatePending decodes so that r.Specific["privatePending"]
+// is the nested object EthereumTypeEstimateGas reads (nonces arriving as JSON float64). Unlike the
+// typed getAccountInfo field, the estimate path is an untyped map, so this is the only place the
+// nesting is pinned end-to-end.
+func TestEstimateFeePrivatePendingDecodesIntoSpecific(t *testing.T) {
+	var req WsReq
+	body := `{"id":"1","method":"estimateFee","params":{"blocks":[1],"specific":{"from":"0xabc","privatePending":{"nonces":[42],"txids":["0xdead"]}}}}`
+	if err := json.Unmarshal([]byte(body), &req); err != nil {
+		t.Fatalf("outer unmarshal error = %v", err)
+	}
+	var r WsEstimateFeeReq
+	if err := json.Unmarshal(req.Params, &r); err != nil {
+		t.Fatalf("params unmarshal error = %v", err)
+	}
+	pp, ok := r.Specific["privatePending"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("specific.privatePending = %#v, want a nested object", r.Specific["privatePending"])
+	}
+	nonces, ok := pp["nonces"].([]interface{})
+	if !ok || len(nonces) != 1 || nonces[0].(float64) != 42 {
+		t.Fatalf("specific.privatePending.nonces = %#v, want [42]", pp["nonces"])
+	}
+}

server/ws_types.go

@@ -51,7 +51,7 @@ type WsAccountInfoReq struct {
 // rather than guessing from which addresses recently sent through this instance. Only Nonces drive
 // behavior today; Txids are accepted for forward compatibility (future pending-tx correlation).
 type WsPrivatePending struct {
-	Nonces []uint64 `json:"nonces,omitempty" ts_doc:"Account nonces of the wallet's in-flight private transactions for this address."`
+	Nonces []uint64 `json:"nonces,omitempty" ts_doc:"Account nonces of the wallet's in-flight private transactions for this address. Each entry is a literal in-flight nonce (0 is a valid value, not a sentinel); do not pad or default the array, as any entry raises the reported pending nonce to at least value+1."`
 	Txids  []string `json:"txids,omitempty" ts_doc:"Transaction hashes of the in-flight private transactions (reserved for future use)."`
 }
 
@@ -151,7 +151,7 @@ type WsTransactionSpecificReq struct {
 // WsEstimateFeeReq requests an estimation of transaction fees for a set of blocks or with specific parameters.
 type WsEstimateFeeReq struct {
 	Blocks   []int                  `json:"blocks,omitempty" ts_doc:"Block confirmations targets for which fees should be estimated."`
-	Specific map[string]interface{} `json:"specific,omitempty" ts_type:"{conservative?: boolean; txsize?: number; from?: string; to?: string; data?: string; value?: string; privatePending?: {nonces?: number[]; txids?: string[]};}" ts_doc:"Additional chain-specific parameters (e.g. for Ethereum). privatePending (Ethereum-like) declares the sender's in-flight private transactions so the gas estimate is routed to the alternative send-tx provider; see WsPrivatePending and docs/evm-send.md."`
+	Specific map[string]interface{} `json:"specific,omitempty" ts_type:"{conservative?: boolean; txsize?: number; from?: string; to?: string; data?: string; value?: string; privatePending?: WsPrivatePending;}" ts_doc:"Additional chain-specific parameters (e.g. for Ethereum). privatePending (Ethereum-like) declares the sender's in-flight private transactions so the gas estimate is routed to the alternative send-tx provider; see WsPrivatePending and docs/evm-send.md."`
 }
 
 // WsEstimateFeeRes is returned in response to a fee estimation request.