OnboardingController class

Constructors

OnboardingController()

Properties

hashCode → int

The hash code for this object.

no setter, inherited

operationGeneration → int

The current operation generation — what a reveal authorization is bound to beside the wallet session instance (RevealGrant). Any lifecycle mutation's start or end changes it.

no setter

ref → Ref

The Ref associated with this notifier.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

state ↔ OnboardingState

The value currently exposed by this notifier.

getter/setter pair, inherited

stateOrNull → OnboardingState?

The value currently exposed by this Notifier.

no setter, inherited

Methods

beginRestore() → void

Enter the RESTORE flow from OnboardingWelcome — show the words-entry screen (OnboardingRestoreInput). Guarded to Welcome (the only place restore is offered), so — exactly as in startCreate — a wallet is known absent on disk when this runs, which is what makes the gate-close-before-write in startRestore safe.

beginWatchOnly() → void

Enter the WATCH-ONLY import flow from OnboardingWelcome (#397 §3.7 D5) — show the viewing-key input screen (OnboardingWatchOnlyInput). Guarded to Welcome (the only place it's offered), so a wallet is known absent on disk when this runs — the same precondition that makes the gate-close-before-write in startWatchOnly safe.

build() → OnboardingState

Initialize a Notifier.

cancelRestore() → void

Leave the restore screen back to OnboardingWelcome (the Back action). Guarded to the restore-input phase; a stray call from any other state is a no-op (precondition discipline as elsewhere).

cancelWatchOnly() → void

Leave the watch-only import screen back to OnboardingWelcome (the Back action). Guarded to the watch-only-input phase; a stray call is a no-op.

confirmBackup() → Future<void>

Confirm the recovery-phrase backup from OnboardingAwaitingBackup. DURABLY persists the confirmation, THEN opens the gate (OnboardingActive). If the persist fails the gate stays CLOSED (back to awaiting-backup) and the error rethrows so the screen can surface "couldn't save — try again": the wallet must never become deposit-ready on a confirmation that didn't survive.

deleteWallet() → Future<WalletDeletionOutcome>

CRYPTO-SHRED the provisioned wallet (FR-14 — the "delete wallet" / "reset" action). Guarded to a state that HOLDS a wallet (OnboardingActive or OnboardingAwaitingBackup) and single-flighted by the operation generation (operationGeneration) like every other lifecycle mutation. The destruction contract (mirrors rescanActiveWallet's recover-by-reopen):

listenSelf(void listener(OnboardingState? previous, OnboardingState next), {void onError(Object error, StackTrace stackTrace)?}) → RemoveListener

Listens to changes on the value exposed by this provider.

inherited

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

recoverByRestore() → Future<void>

The #251 escape out of a NON-RETRYABLE OnboardingFailed (a needsRecovery wallet whose custody key is gone, so it can't be opened on this device). Force-clears the unreadable on-device remnant and routes to the restore form, where the user re-enters their recovery phrase and recovers their funds — which live ON-CHAIN, not on this device, so clearing the remnant loses no money. This is what guarantees a non-retryable failure is NEVER a dead-end.

rescanActiveWallet(RescanTarget target) → Future<RescanOutcome>

Rescan the ACTIVE wallet from an earlier birthday (ADR-0534 — recover funds an over-high restore birthday skipped). Guarded to OnboardingActive (a rescan is meaningful only on a deposit-ready wallet) and single-flighted by the operation generation. The money-recovery contract:

retry() → Future<void>

Retry after an OnboardingFailed — re-runs the boot probe (e.g. the user unlocked the device, freed disk, or closed the other instance). Guarded to the failed state ONLY: it is the Retry button's action, not a general re-probe. Re-probing from OnboardingActive would needlessly flash Loading and re-open the wallet, so a stray call from any other state is a no-op (matching the precondition discipline of startCreate/ confirmBackup).

runBuild() → WhenComplete?

Executes Notifier.build.

inherited

startCreate() → Future<void>

Start the CREATE flow from OnboardingWelcome. Generates + seals a fresh seed in Rust and moves to OnboardingAwaitingBackup (NOT active — the recovery phrase must be backed up and confirmed first). A failure surfaces as OnboardingFailed (the screen renders it with the right next step); no rethrow, the state IS the surface.

startRestore(List<String> mnemonicWords, {DateTime? approximateCreationTime}) → Future<void>

Restore a wallet from mnemonicWords (the recovery phrase) and — since the user demonstrably HOLDS the backup by typing it — go straight to deposit-ready OnboardingActive, not the forced-backup state a fresh create lands in. approximateCreationTime optionally speeds the scan (the adapter floors the birthday from it; null ⇒ a full, money-safe scan).

startWatchOnly(String ufvk, {required DateTime creationDate}) → Future<void>

Create a WATCH-ONLY wallet from ufvk at creationDate (#397 §3.7 D2) and go straight to deposit-ready-shaped OnboardingActive — a watch-only wallet has NO seed and so NOTHING to back up (there is no OnboardingAwaitingBackup step; it cannot deposit-spend anyway, but the gate discipline is identical: a session reaches the UI iff state is Active). The birthday is REQUIRED here (a watch-only import has no lazy seed-path — the account is imported eagerly), converted from creationDate via the same conservative estimator restore uses.

switchSyncServer(SyncServerChoice choice) → Future<SwitchServerResult>

Switch the ACTIVE wallet onto choice (the picker, P3-13) — the rescanActiveWallet shape: the provisioner swaps the session in place and a FRESH session identity goes into the gate, so the live-sync graph rebuilds and sync restarts on the new server. SAME identityEpoch (the same wallet's life, over the same DB) and kind carried, as for a rescan.

toString() → String

A string representation of this object.

inherited

updateShouldNotify(OnboardingState previous, OnboardingState next) → bool

A method invoked when the state exposed by this Notifier changes. It compares the previous and new value, and return whether listeners should be notified.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Constants

switchServerTimeout → const Duration

How long a server switch may go unanswered before its generation ends. The SDK bounds the switch's own steps — the reachability probe (SYNC_SERVER_PROBE_TIMEOUT_SECS, 15 s) and the quiesce of the sync loop (QUIESCE_MAX, 30 s) — and the session rebuild after them is local I/O (the provisioner's defaultLocalIoBound, 30 s); this sits above their sum with a margin. Past it the switch answers SwitchServerFailedRecovered with the session in the gate unchanged, a delete is accepted again, and the switch's late answer lands nowhere. A Dart timeout cannot cancel the Rust side: a delete accepted here meets the core's own gate on the handle.