[peachbits]

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

none

Description

Asana task

Asana: https://app.asana.com/1/9976422036640/project/1213843652804305/task/1218875483565488

Last weekend the LTC Edge Blockbook fell behind its backend. It kept answering pings, so it kept its top score, and wallets stayed pinned to it: a completed resync showed a short balance that corrected itself an hour later. The engine scored servers on round-trip time only and never read Blockbook's inSync.

The Trezor 403s in the same ticket are not a production problem. Cloudflare rejects tool user agents (curl, okhttp, CFNetwork); the plugin's WebView user agent passes. Verified in the simulator against the plugin's own logs.

inSync is only on Blockbook's REST GET /api/, not on the WebSocket getInfo, and Trezor's REST is closed to everyone, so only Edge's own servers can be probed. Each commit stands alone:

1. Probe. A socket URI finds its HTTPS twin in the blockbook entries of engineInfo.serverConfigs and probes it after connect and on every keepalive (de-duplicated within 10 s). inSync: false disconnects the server through the normal close path and schedules a refill. No twin means never probed; a failed, timed-out, or unparseable probe is unknown, never unhealthy.
2. Quarantine. Five minutes in memory on PluginState, shared by every wallet of the currency, withheld from getLocalServers, skipped by refill, and listed in dumpData. Refill keeps retrying while a quarantine is in force so the server returns when it expires.
3. Re-query on drop. A SERVER_DROPPED engine event. The processor clears the processing flag on every subscribed address and queues a UTXO refresh, so the surviving connection fetches the range the stale server missed, starting from each address's stored lastQueriedBlockHeight. Progress is now per-address completion flags rather than a counter, so re-queued work cannot push the ratio past 1 or report 100% early.
4. Last leg. A stale server is only dropped while another connection is open and not known unhealthy. Re-evaluated on every probe result and once each new connection finishes connecting.
5. Block height guard. Null check in the BLOCK_HEIGHT_CHANGED handler, matching its sibling.
6. Tests. Keepalive, wake-up, and probe de-dupe intervals are injectable (production defaults unchanged). Over-time tests cover re-probing, dropping a server that falls out of sync, keeping the last leg, the de-dupe window, and taking a recovered server back.
7. Shared probe. The de-dupe lives on PluginState, keyed by server URI, so every wallet of a currency shares one probe per server per 10 s instead of each sending its own GET /api/ on its own keepalive. Each wallet still applies the answer to its own connection.

Also fixed on the way: reconnect() overwrote its pending timer instead of clearing it, so a timer could outlive stop() and switch a stopped engine back on.

Design calls: no hysteresis beyond Blockbook's own 5 s grace, and no block-height comparison between servers (reorgs).

Testing. Unit: 1340 passing, suite exits on its own. Integration, in the iOS simulator with a local proxy in front of ltc-wusa1 whose /api/ reports a flippable inSync, with two LTC wallets and ltc1.trezor.io as the peer:

Time	Observed
18:03:27	Both wallets connect; proxy probed healthy
18:03:45	Flag flipped to false
18:04:22	Next keepalive: health: healthy -> unhealthy, dropped, quarantined 300000ms, 171 and 122 addresses re-queued, reconnect scheduled
18:09:26	Quarantine expired, proxy reconnected and probed healthy

Follow-up, not in this PR: after a drop the re-query fires ~460 requests in one second at the surviving Trezor socket, which closes it; it converges after a few reconnects. Per-server request pacing (the socket's 50 in-flight cap is global) would fix that and the same burst on a fresh wallet whose first pick is a third-party server.

---

Note

Medium Risk
Changes core multi-server sync, connection selection, and balance correctness paths; behavior is heavily unit-tested but affects all UTXO Blockbook wallets when servers fall behind.

Overview
UTXO wallets now detect lagging Edge Blockbook indexers and fail over instead of staying on a fast but stale connection.

On connect and each socket keepalive, probeable servers get a shared REST GET /api/ check for inSync (Edge hosts only; failed probes count as unknown, not unhealthy). Servers reporting behind are quarantined for five minutes (currency-wide), disconnected when another healthy or unknown peer exists, and only the last stale connection is kept if nothing else is usable. Dropping a server emits SERVER_DROPPED, which re-queues address tx/UTXO sync from stored lastQueriedBlockHeight, caps that cursor to the answering server’s height, and tracks sync progress with per-address flags so re-queries cannot report 100% early. Probe deduplication across wallets limits one REST call per server per ~10s. reconnect() now clears its pending timer so stop() cannot resurrect the engine.

^{Reviewed by Cursor Bugbot for commit 725d488. Bugbot is set up for automated code reviews on this repo. Configure here.}

[j0ntz]

Commit subjects: 6 of 7 exceed the 50-character limit (commit-subject-50). Suggested replacements:

Commit	Len	Suggestion
1623f37	59	Drop Blockbook servers that report inSync false
cea9e9e	63	Quarantine dropped servers from the refill
27fe15a	64	Re-query addresses after a stale server drop
23da251	66	Keep an out-of-sync server if it is the last
c2eb9a6	58	Guard block height handler on closed sockets
613cb32	51	Test keepalive re-probe, de-dupe, and recovery

On the Trezor 403s: in the app, Socket.ts connects through setupBrowser, which sends the WebView's own user agent. Only the Node fallback (nodejsWS.ts) sends NodeJS-WS-agent, so the code supports the PR's read that the 403s come from the Node/CLI path rather than production.

[j0ntz]

Correction to the Trezor note in my review: a live handshake against wss://ltc1 through wss://ltc5.trezor.io/websocket returns 101 for both a WebView user agent and NodeJS-WS-agent, so neither app path triggers the 403. All five return 403 only when the User-Agent header is missing or is curl's default, and GET https://ltc1.trezor.io/api/ with curl's user agent also returns 403. The reported 403s fit a probe tool that sends no browser-like user agent, which still supports the PR's read that production is unaffected.

[peachbits]

Rechecked the handshake against wss://ltc1.trezor.io/websocket: okhttp/4.12.0, a CFNetwork user agent, and curl's default get 403, while NodeJS-WS-agent and an iOS WebView user agent get 101. That matches the PR description's list (curl, okhttp, CFNetwork), so it stays as written.

[cursor]

Stale Bugbot comment from a previous run.

[j0ntz]

Approved after bugbot

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5608508. Configure here.}