features/wallet/wallet_rescan_controller
library
Classes
-
WalletCatchUpCue
-
The catch-up presentation truth (#380) — SHOULD the wallet surface explain
an empty/partial balance + history as "still filling in", and with which
copy. The banner, the activity empty-cue, and the swap "Available" line all
derive from this ONE provider.
-
WalletCatchUpNone
-
Nothing to explain — the balance/history render normally.
-
WalletCatchUpRebuilding
-
A rescan rebuild is repopulating. Two arms share this cue:
-
WalletCatchUpSyncing
-
The durable-signal arm: a never-synced wallet below the tip with no
intra-session rescan state (a relaunch mid-catch-up, a dismissed failure
notice over a rebuilt wallet, a restore/create's first sync) — generic
catch-up copy.
-
WalletRescanBlockedBySettlingSend
-
The SDK refused the rescan because a send is still settling on-chain (the
§4.4 witness-inversion fence — rebuilding under it could double-pay). The
wallet is fully usable at its prior state; the cue is HOURS-scale ("keep
the app online" — resolution needs sync passes), distinct from
WalletRescanFailed's "try again in a moment".
-
WalletRescanBlockedBySyncNotRunning
-
The rescan was REFUSED at its commit point because no sync pass will run
(#405): either the host's sync policy is off or the start command failed, so
the rebuild this wipe depends on cannot execute. Nothing destructive ran —
the wallet is untouched at its full prior state, which is why this is a
distinct state from WalletRescanFailed (whose wallet may have been rebuilt
at a lower birthday, #379) and why its copy claims "unchanged" outright.
-
WalletRescanController
-
-
WalletRescanFailed
-
The rescan FAILED but the wallet was recovered — re-opened at its prior
birthday on the common pre-rename faults, or at the REBUILT lower birthday
if the fault hit after the atomic rename (#379; NO funds lost either way —
see RescanOutcome.failedRecovered for the two-arm story). An honest,
dismissable cue; the wallet stays fully usable. (A failure that ALSO
couldn't re-open routes the whole surface to OnboardingFailed, so this
state is never used for that case.)
-
WalletRescanFailedNeedsSpace
-
The rescan failed because the disk is FULL (the SDK's typed
DiskFull —
the rebuild + WAL fold need headroom routine commits don't, so the sync
badge stays HEALTHY while a retry deterministically re-fails; #375). The
wallet is fully usable — at its prior state on the common pre-rename
faults, or at the REBUILT lower-birthday state if the DiskFull hit after
the rebuild's atomic rename (#379: balance/history repopulate via sync,
which is why the cue claims funds-safety, never "unchanged"); the cue is
ACTIONABLE ("free up space"), distinct from WalletRescanFailed's "try
again in a moment".
-
WalletRescanIdle
-
No rescan in progress (the default) — the activity list renders normally.
-
WalletRescanRebuilding
-
The rebuild SUCCEEDED and the wallet is re-scanning from the lower birthday.
The balance + activity are EMPTY/partial until sync reaches the tip; the
surface shows an honest "rebuilding your history" cue — DISTINCT from the
"no activity yet" empty card — so the user knows their funds are safe and the
history is being recovered (review P1 #4: a user must not watch their whole
history vanish unexplained). Cleared on reached-tip.
-
WalletRescanRunning
-
The FFI rebuild is running (stops + joins sync, rebuilds the data DB). Brief +
local; the confirm sheet shows a spinner. The wallet surface still shows the
PRIOR session's data until the swap lands.
-
WalletRescanState
-
The rescan-recovery presentation state (ADR-0534 / FR-1b). Distinct from the
onboarding state machine (which owns the session swap) and the
SyncStatus
(which reports scan progress): this is purely how the wallet surface presents
a user-initiated "scan from earlier / scan all history" recovery.
