features/wallet/shield/shield_state library

Classes

ShieldDone

Terminal result of the shield's send — the reused SendOutcome (the shield IS a send of the retained token, §3.3a Recv-3).

ShieldIdle

Initial / reset — nothing prepared yet.

ShieldNothingToShield

proposeShield returned null — the transparent balance is below the shieldable minimum (the fee would outweigh the benefit). An honest no-op the sheet explains, NEVER an error.

ShieldOutcomeUnknown

The shield's spend STARTED and its answer was lost (R13 §4.3): send threw a kind that can follow persistence (singleStepSendErrorPrecedesPersistence does not accept it), or the host's code threw or declined after the spend ran. The transaction may already be saved, so neither "shielded" nor "couldn't shield" is true — the sheet points at Activity and offers Close only. A Try again here would re-propose over a saved shield. Carries no error: nothing renders a throw's text.

ShieldPreparing

proposeShield in flight — deterministic + local (note-selection/fee), no network. Transient; a spinner.

ShieldReady

The confirm sheet: the EXACT numbers — gross transparent (proposal.totalZat), fee (proposal.feeZat), net that lands shielded (proposal.changeZat) — then ShieldController.confirm signs + broadcasts. Holds the display proposal (its opaque token is consumed by id on confirm).

ShieldState

The shield flow's states (Recv-3), a sealed family the sheet renders with an exhaustive switch. The flow is: open → (proposeShield) → ready | nothing, then ready → (send) → done. Rendering layer ONLY — every transition runs through ShieldController; no money state is stored here (design invariant 1).

ShieldSubmitting

send (sign + broadcast the shield tx) in flight. Transient; a spinner. Holds the proposal so the sheet can keep showing the figures.

ShieldUnavailable

A recoverable prepare/confirm fault that did NOT move money: the wallet isn't synced far enough to anchor the shield (notSyncedYet), is mid-lifecycle (walletBusy), has no live session (walletUnavailable), or the shield could not be prepared/signed for a reason with no finer mapping (couldNotPrepare). The sheet offers "try again" (re-prepare) or honest copy — never a code (§6).

Enums

ShieldFaultReason

The payload-free shield-fault categories (the honest message axis; no codes).

Functions

classifyShieldPrepareFailure(Object error) → ShieldState

Map a proposeShield failure to a ShieldState. Reads the typed WalletApiError.kind ONLY (never a payload — §5.4); a non-FRB error is the generic ShieldFaultReason.couldNotPrepare. Pure + total, unit-tested at its boundary without a device.

classifyShieldSendFailure(Object error) → ShieldState

Map a shield send (sign+broadcast) failure to the next ShieldState. A consumed token is the honest "already submitted" (the notes are never broadcast twice, §6.3); a stale anchor routes to re-prepare; everything else is a no-money-moved sign failure. Reads kind only (§5.4) — mirrors the send flow's classifySendFailure, projected onto the shield states.