WalletSyncDrive enum

What the host is doing with the background sync LOOP — distinct from the observed SyncStatus (which reports how that loop is progressing; see syncStatusProvider). This enum is the reference app's SYNC POLICY.

It is INTERNAL POLICY state. WalletSyncDrive.failed renders the retry notice, and WalletSyncDrive.running is read by the sync banner to disambiguate the SDK's Idle: a started-but-not-yet-reporting loop (the silent prep phase — fetching commitment-tree roots + the chain tip) renders "Connecting…" rather than a stale "Not syncing yet". suspended/inactive are still never shown. The honest live progress is always the SyncStatus banner; this state only colours how its Idle arm reads. The optimistic running set before a (near-instant, loop-spawning) startSync settles is safe — at worst it shows "Connecting…" a beat early, never a false sync claim.

FORWARD-OWED (review S99): ideally the SDK emits a real SyncStatus::Connecting during the prep phase so this disambiguation lives Rust-side and driving drops out of _SyncBanner; today the production controller never emits that arm.

WHY this exists (maintainer review, spec §3.3): the SDK's Wallet::open deliberately does NOT auto-sync — the host owns sync policy (battery, network, foreground/background), so the core exposes idempotent startSync/stopSync and leaves the when to the host. Real wallets have no "Start sync" button; sync just runs. So this controller drives the loop:

  • run while a deposit-ready wallet exists AND the app is foreground,
  • stop in the background (battery — the OS would suspend us anyway),
  • resume on return. It replaces the manual Start/Stop buttons an earlier slice surfaced.

Money-safety: stopping loses nothing — durable scan progress is kept (the chain is the source of truth, SDK §6.3), so a background stop + foreground restart resumes exactly where it left off.

Inheritance
Available extensions

Values

inactive → const WalletSyncDrive

No deposit-ready wallet → nothing to drive.

running → const WalletSyncDrive

Wallet present + app foreground → the loop is running (or being started).

suspended → const WalletSyncDrive

App backgrounded → the loop is stopped to save battery; a real resume restarts it. UNREACHABLE on desktop: paused never fires there (the deepest state is hidden), so desktop keeps the loop running while minimized — which is wanted.

failed → const WalletSyncDrive

The START command itself failed (rare — e.g. the handle closed underneath us). Surfaced honestly (no silent failure, invariant 10); a foreground resume (mobile only — paused never fires on desktop) or an explicit WalletSyncController.retry re-attempts. A stop failure does NOT land here — see WalletSyncController._command.

disabledByHost → const WalletSyncDrive

The HOST's sync policy is off (#383 R1 — walletSyncPolicyProvider false): the loop is deliberately not driven. Distinct from inactive (a wallet EXISTS; the host chose not to sync it) so the badge/sheet can render the honest "sync off — turn it on in settings" story instead of a stalled/connecting state that never resolves. Reactive: the controller watches the policy, so a host flip starts/stops the loop on the spot.

Properties

hashCode → int
The hash code for this object.
no setterinherited
index → int
A numeric identifier for the enumerated value.
no setterinherited
name → String

Available on Enum, provided by the EnumName extension

The name of the enum value.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

values → const List<WalletSyncDrive>
A constant List of the values in this enum, in order of their declaration.