fix: recover stalled wallet syncs via idle watchdog and progress reorder

[reubenyap]

Summary

The base Wallet<T>._refresh() is shared across many wallet types. When any awaited sub-operation hangs indefinitely (unresponsive server, OS-suspended socket, wedged native-lib callback, etc.), refreshMutex is never released — the catch/finally blocks only run when the future completes or throws, and a permanently pending future does neither. Every subsequent periodic sync then bails out at the if (refreshMutex.isLocked) return check, leaving the wallet unable to sync until the app is force-closed.

The most visible manifestation is Firo getting stuck at ~65% (which is what prompted this fix), but the underlying cause is generic and affects all wallets routing through the shared _refresh() path.

Changes

1. Idle watchdog on _refresh() — lib/wallets/wallet/wallet.dart

The refresh body is extracted to a new _doRefreshWork(viewOnly) helper. _refresh() races it against a Timer.periodic watchdog that trips if no refresh activity has been observed for 5 minutes (_refreshIdleThreshold). On trip, the watchdog throws TimeoutException → existing catch → completer.completeError() → finally releases refreshMutex. The next periodic sync (every 150s) gets a fresh attempt.

Activity is fed from two sources:

• _fireRefreshPercentChange ticks — coarse phase checkpoints, plus per-sector progress during Spark anon-set downloads.
• Successful electrum RPCs, via a new onRequestComplete hook on ElectrumXClient (see change Change name in README. #2).

This matters because updateTransactions() on a wallet with large history does hundreds of sequential getTransaction RPCs with no _fireRefreshPercentChange calls between 0.65 and 0.70. Without the electrum hook, a slow server could legitimately trigger a false timeout on an initial restore of a big wallet. With the hook, the watchdog stays fed as long as electrum is answering.

Caveats:

• The watchdog does not cancel in-flight work; it only unblocks the outer future so the mutex can be released. The abandoned _doRefreshWork future keeps running. If it eventually throws, the error is swallowed via a no-op catchError attached in the finally block so it does not surface as an uncaught async error. Per-call hang detection remains the job of the underlying adapters (e.g. electrum's connectionTimeout / aliveTimerDuration at 60s each).

2. onRequestComplete hook on ElectrumXClient — lib/electrumx_rpc/electrumx_client.dart

New nullable void Function()? onRequestComplete field, called after every successful RPC in both request() and batchRequest(). Invocations go through _fireOnRequestComplete(), which wraps the call in try/catch so a faulty hook cannot be misattributed as an RPC failure by the surrounding catch block (which would otherwise increment currentFailoverIndex and trigger a failover retry). _refresh() wires it to reset the watchdog timestamp while a refresh is active, then clears it in finally. Covers every current and future electrum-routed call automatically without instrumenting each wallet's updateTransactions.

3. Fix misleading progress reporting — lib/wallets/wallet/wallet.dart

Before: 0.6 → 0.65 → [await UTXOs] → 0.70 → [await txns]
After: 0.6 → [await UTXOs] → 0.65 → [await txns] → 0.70

Progress now reflects actual completion rather than jumping ahead before the awaited work finishes. Applies to all non-Namecoin wallets (the else branch).

Scope

Affected (wallet types routing through the base _refresh()):
BTC, LTC, BCH, Dash, Doge, Ecash, Ethereum, Firo, Cardano, Solana, Stellar, Tezos, Xelis, Namecoin, Bitcoin Frost, Fact0rn, Particl, Peercoin, Nano, Banano.

Unaffected (override refresh() entirely and bypass _refresh()):

• Monero / Wownero / Salvium (each has its own refresh() override in lib_monero_wallet.dart, lib_wownero_wallet.dart, lib_salvium_wallet.dart)
• MimbleWimbleCoin / Epic Cash
• ETH tokens
• SOL tokens

The same watchdog pattern could be applied to the Monero-family overrides in a follow-up if they exhibit similar mutex-stuck symptoms.

Commits

For easier review each concern is isolated to its own commit:

1. refactor: extract _refresh() body into _doRefreshWork helper — pure mechanical extraction, no behavior change.
2. fix: fire refresh progress updates after awaited work completes — progress reorder.
3. fix: add idle watchdog to _refresh() so hung syncs release the mutex — core watchdog + onRequestComplete hook.
4. fix: isolate onRequestComplete hook from RPC error handling — defensive try/catch around the hook invocation.
5. fix: suppress uncaught errors from detached refresh work after watchdog trip — no-op catchError on the abandoned work future.
6. refactor: promote refresh watchdog intervals to named constants — _refreshIdleThreshold / _refreshWatchdogTick.

Test plan

• Sync a Firo wallet and verify it completes past 65%
• Verify progress bar advances smoothly without premature jumps
• Kill the ElectrumX server mid-sync and verify the wallet recovers on next periodic refresh (mutex released)
• Verify long legitimate initial syncs complete without the watchdog firing prematurely:
  • Firo: full Spark anon-set download on a constrained network (Spark per-sector progress keeps watchdog alive)
  • BTC/LTC/Doge/Dash: restore of a wallet with thousands of historical transactions (electrum onRequestComplete hook keeps watchdog alive)
• Sanity check other coin types (ETH, Solana, Cardano) still sync normally