fix(backup): align failure handling and localization

Author: FrancisPouliot

FEATURES.md

@@ -60,54 +60,7 @@ graph TB
     BACKUPS --> TOR
     BACKUPS --> WALLETS
     BTC_PRICE --> SETTINGS
-    BTCPAY --> BIP85_REGISTRY
-    BTCPAY --> DETERMINISTIC_WALLETS
-    BTCPAY --> KEYCHAIN_MANIFEST
-    BTCPAY --> GET_PAID_SETTINGS
-    BTCPAY --> WALLETS
-    DETERMINISTIC_WALLETS --> BIP85
-    KEYCHAIN_MANIFEST --> BIP85_REGISTRY
-    KEYCHAIN_MANIFEST --> NOSTR_IDENTITY
-    KEYCHAIN_RECOVERY --> BIP85_REGISTRY
-    KEYCHAIN_RECOVERY --> DETERMINISTIC_WALLETS
-    KEYCHAIN_RECOVERY --> KEYCHAIN_MANIFEST
     ONBOARDING --> BACKUPS
-    NOSTR_IDENTITY --> BIP85_REGISTRY
-    LIGHTNING_ADDRESS --> BIP85_REGISTRY
-    LIGHTNING_ADDRESS --> BULLNYM
-    LIGHTNING_ADDRESS --> DETERMINISTIC_WALLETS
-    LIGHTNING_ADDRESS --> KEYCHAIN_MANIFEST
-    LIGHTNING_ADDRESS --> NOSTR_IDENTITY
-    LIGHTNING_ADDRESS --> GET_PAID_SETTINGS
-    PAYMENT_PAGE --> BULLNYM
-    PAYMENT_PAGE --> LIGHTNING_ADDRESS
-    PAYMENT_PAGE --> DETERMINISTIC_WALLETS
-    PAYMENT_PAGE --> KEYCHAIN_MANIFEST
-    PAYMENT_PAGE --> BIP85_REGISTRY
-    PAYMENT_PAGE --> GET_PAID_SETTINGS
-    PAYMENT_PAGE --> NOSTR_IDENTITY
-    POS --> BULLNYM
-    POS --> LIGHTNING_ADDRESS
-    POS --> DETERMINISTIC_WALLETS
-    POS --> KEYCHAIN_MANIFEST
-    POS --> BIP85_REGISTRY
-    POS --> GET_PAID_SETTINGS
-    POS --> NOSTR_IDENTITY
-    INVOICES --> BULLNYM
-    INVOICES --> NOSTR_IDENTITY
-    INVOICES --> WALLETS
-    INVOICES --> LABELS
-    GET_PAID_SETTINGS --> KEYCHAIN_MANIFEST
-    GET_PAID_SETTINGS --> NOSTR_RELAY_POLICY
-    GET_PAID_SETTINGS --> CORE
-    REMOTE_KEYCHAIN_RECOVERY --> KEYCHAIN_MANIFEST
-    REMOTE_KEYCHAIN_RECOVERY --> KEYCHAIN_RECOVERY
-    REMOTE_KEYCHAIN_RECOVERY --> NOSTR_RELAY_POLICY
-    REMOTE_KEYCHAIN_RECOVERY --> LIGHTNING_ADDRESS
-    REMOTE_KEYCHAIN_RECOVERY --> PAYMENT_PAGE
-    REMOTE_KEYCHAIN_RECOVERY --> POS
-    REMOTE_KEYCHAIN_RECOVERY --> GET_PAID_SETTINGS
-    REMOTE_KEYCHAIN_RECOVERY --> CORE
     BUY --> EXCHANGE
     BUY --> RECEIVE
     COINS --> UTXO_MGMT
@@ -154,8 +107,7 @@ graph TB
     classDef featureStyle fill:#1a202c,stroke:#2d3748,stroke-width:2px,color:#e2e8f0
 
     class CORE coreStyle
-    class SETTINGS,TOR,PIN_CODE,LABELS,SECRETS,HW_WALLETS,BTC_PRICE,NETWORK,BIP85,FEES,WALLETS,EXCHANGE,APP_STARTUP,UTXO_MGMT,ADDRESS_MGMT,RECIPIENTS,FUNDING,BACKUPS,SWAPS,PAYJOIN,WITHDRAWAL,STATUS,SEND,RECEIVE,TRANSFER,TX_HISTORY,BG_TASKS,AUTOSWAPS,DCA,SELL,PAY,BUY,COINS featureStyle
-    class SETTINGS,TOR,PIN_CODE,LABELS,SECRETS,HW_WALLETS,BTC_PRICE,BTCPAY,BIP85_REGISTRY,DETERMINISTIC_WALLETS,KEYCHAIN_MANIFEST,KEYCHAIN_RECOVERY,NOSTR_IDENTITY,NOSTR_RELAY_POLICY,BULLNYM,LIGHTNING_ADDRESS,PAYMENT_PAGE,POS,INVOICES,GET_PAID_SETTINGS,REMOTE_KEYCHAIN_RECOVERY,NETWORK,BIP85,FEES,WALLETS,EXCHANGE,APP_STARTUP,ONBOARDING,UTXO_MGMT,ADDRESS_MGMT,RECIPIENTS,FUNDING,BACKUPS,SWAPS,PAYJOIN,WITHDRAWAL,STATUS,SEND,RECEIVE,TRANSFER,TX_HISTORY,BG_TASKS,AUTOSWAPS,AUTOSWEEP,DCA,SELL,PAY,BUY,COINS featureStyle
+    class SETTINGS,TOR,PIN_CODE,LABELS,SECRETS,HW_WALLETS,BTC_PRICE,NETWORK,BIP85,FEES,WALLETS,EXCHANGE,APP_STARTUP,ONBOARDING,UTXO_MGMT,ADDRESS_MGMT,RECIPIENTS,FUNDING,BACKUPS,SWAPS,PAYJOIN,WITHDRAWAL,STATUS,SEND,RECEIVE,TRANSFER,TX_HISTORY,BG_TASKS,AUTOSWAPS,DCA,SELL,PAY,BUY,COINS featureStyle
 ```
 
 ## About Package Dependency Diagrams

docs/backup-health-reminders.md

@@ -70,7 +70,9 @@ Reminder state is stored locally in a versioned SharedPreferences record keyed b
 - a pending action start time; and
 - the pending action balance tier.
 
-No mnemonic, seed, private key, vault key, or other secret is stored or logged by the reminder. Malformed or unsupported reminder records are ignored and replaced with an empty in-memory record, which favors showing another reminder over suppressing one indefinitely.
+No mnemonic, seed, private key, vault key, or other secret is stored or logged by the reminder. Malformed, unsupported, or unreadable reminder records are replaced with an empty in-memory record, which favors showing another reminder over suppressing one indefinitely. The underlying read failure is logged without exposing it to the user.
+
+If a reminder action cannot be persisted, the overlay stays visible so the user can retry. A localized "close for now" action is then available as a session-only escape; it does not acknowledge the reminder, so the app evaluates it again on the next launch.
 
 ## Architecture
 

lib/features/backup_settings/data/shared_preferences_backup_health_reminder_repository.dart

@@ -55,7 +55,9 @@ class SharedPreferencesBackupHealthReminderRepository
         error: e,
         trace: st,
       );
-      return Err(BackupSettingsPersistenceFailure(e.toString()));
+      return Ok(
+        BackupHealthReminderRecord(masterFingerprint: masterFingerprint),
+      );
     }
   }
 

lib/features/backup_settings/presentation/cubit/backup_health_reminder_cubit.dart

@@ -105,4 +105,16 @@ class BackupHealthReminderCubit extends Cubit<BackupHealthReminderState> {
         return false;
     }
   }
+
+  void dismissFailureForSession() {
+    final current = state;
+    if (current is! BackupHealthReminderVisible ||
+        current.failure == null ||
+        current.isSaving) {
+      return;
+    }
+
+    _sessionSuppressed = true;
+    emit(const BackupHealthReminderHidden());
+  }
 }

lib/features/backup_settings/ui/widgets/backup_health_reminder_overlay.dart

@@ -214,6 +214,17 @@ class _BackupHealthReminderBlocker extends StatelessWidget {
                           ),
                         ),
                       ],
+                      if (state.failure != null) ...[
+                        const Gap(8),
+                        TextButton(
+                          onPressed: state.isSaving
+                              ? null
+                              : () => context
+                                    .read<BackupHealthReminderCubit>()
+                                    .dismissFailureForSession(),
+                          child: Text(context.loc.backupHealthCloseForNow),
+                        ),
+                      ],
                     ],
                   ),
                 ),

lib/features/onboarding/domain/onboarding_failure.dart

@@ -7,3 +7,8 @@ sealed class OnboardingFailure extends Failure {
 final class OnboardingUnexpectedFailure extends OnboardingFailure {
   const OnboardingUnexpectedFailure([super.logMessage]);
 }
+
+final class OnboardingBackupVerificationPersistenceFailure
+    extends OnboardingFailure {
+  const OnboardingBackupVerificationPersistenceFailure([super.logMessage]);
+}

…hysical_backup_verification_usecase.dart …hysical_backup_verification_usecase.dartlib/features/onboarding/domain/complete_physical_backup_verification_usecase.dart renamed to lib/features/onboarding/domain/usecases/complete_physical_backup_verification_usecase.dart lib/features/onboarding/domain/complete_physical_backup_verification_usecase.dart renamed to lib/features/onboarding/domain/usecases/complete_physical_backup_verification_usecase.dart

@@ -18,7 +18,9 @@ class CompletePhysicalBackupVerificationUsecase {
       case Ok():
         return const Ok(null);
       case Err(:final failure):
-        return Err(OnboardingUnexpectedFailure(failure.logMessage));
+        return Err(
+          OnboardingBackupVerificationPersistenceFailure(failure.logMessage),
+        );
     }
   }
 }

lib/features/onboarding/domain/usecases/create_onboarding_wallets_usecase.dart

@@ -0,0 +1,44 @@
+import 'package:bb_mobile/core/utils/logger.dart';
+import 'package:bb_mobile/core/utils/result.dart';
+import 'package:bb_mobile/core/wallet/domain/entities/wallet.dart';
+import 'package:bb_mobile/core/wallet/domain/usecases/create_default_wallets_usecase.dart';
+import 'package:bb_mobile/features/onboarding/domain/onboarding_failure.dart';
+import 'package:meta/meta.dart';
+
+class CreateOnboardingWalletsUsecase {
+  final CreateDefaultWalletsUsecase _createDefaultWalletsUsecase;
+
+  CreateOnboardingWalletsUsecase(this._createDefaultWalletsUsecase);
+
+  @useResult
+  Future<Result<List<Wallet>, OnboardingFailure>> execute({
+    List<String>? mnemonicWords,
+  }) async {
+    try {
+      final wallets = mnemonicWords == null
+          ? await _createDefaultWalletsUsecase.execute()
+          : await _createDefaultWalletsUsecase.execute(
+              mnemonicWords: mnemonicWords,
+            );
+      if (wallets.isEmpty) {
+        const failure = OnboardingUnexpectedFailure(
+          'No wallets were created or restored',
+        );
+        log.severe(
+          message: failure.logMessage,
+          error: failure,
+          trace: StackTrace.current,
+        );
+        return const Err(failure);
+      }
+      return Ok(wallets);
+    } on CreateDefaultWalletsException catch (error, trace) {
+      log.severe(
+        message: 'createOnboardingWallets failed',
+        error: error,
+        trace: trace,
+      );
+      return Err(OnboardingUnexpectedFailure(error.toString()));
+    }
+  }
+}

lib/features/onboarding/onboarding_locator.dart

@@ -1,5 +1,6 @@
 import 'package:bb_mobile/core/wallet/domain/usecases/create_default_wallets_usecase.dart';
-import 'package:bb_mobile/features/onboarding/domain/complete_physical_backup_verification_usecase.dart';
+import 'package:bb_mobile/features/onboarding/domain/usecases/complete_physical_backup_verification_usecase.dart';
+import 'package:bb_mobile/features/onboarding/domain/usecases/create_onboarding_wallets_usecase.dart';
 import 'package:bb_mobile/features/onboarding/presentation/bloc/onboarding_bloc.dart';
 import 'package:bb_mobile/features/test_wallet_backup/public/test_wallet_backup_facade.dart';
 import 'package:get_it/get_it.dart';
@@ -9,7 +10,8 @@ class OnboardingLocator {
     // Blocs
     locator.registerFactory<OnboardingBloc>(
       () => OnboardingBloc(
-        createDefaultWalletsUsecase: locator<CreateDefaultWalletsUsecase>(),
+        createOnboardingWalletsUsecase:
+            locator<CreateOnboardingWalletsUsecase>(),
         completePhysicalBackupVerificationUsecase:
             locator<CompletePhysicalBackupVerificationUsecase>(),
       ),
@@ -21,5 +23,10 @@ class OnboardingLocator {
         locator<TestWalletBackupFacade>(),
       ),
     );
+    locator.registerFactory<CreateOnboardingWalletsUsecase>(
+      () => CreateOnboardingWalletsUsecase(
+        locator<CreateDefaultWalletsUsecase>(),
+      ),
+    );
   }
 }

lib/features/onboarding/presentation/bloc/onboarding_bloc.dart

@@ -1,10 +1,9 @@
 import 'dart:async';
 
-import 'package:bb_mobile/core/utils/logger.dart';
 import 'package:bb_mobile/core/utils/result.dart';
-import 'package:bb_mobile/core/wallet/domain/usecases/create_default_wallets_usecase.dart';
-import 'package:bb_mobile/features/onboarding/domain/complete_physical_backup_verification_usecase.dart';
 import 'package:bb_mobile/features/onboarding/domain/onboarding_failure.dart';
+import 'package:bb_mobile/features/onboarding/domain/usecases/complete_physical_backup_verification_usecase.dart';
+import 'package:bb_mobile/features/onboarding/domain/usecases/create_onboarding_wallets_usecase.dart';
 import 'package:bip39_mnemonic/bip39_mnemonic.dart' as bip39;
 import 'package:flutter_bloc/flutter_bloc.dart';
 import 'package:freezed_annotation/freezed_annotation.dart';
@@ -15,7 +14,7 @@ part 'onboarding_state.dart';
 
 class OnboardingBloc extends Bloc<OnboardingEvent, OnboardingState> {
   OnboardingBloc({
-    required this._createDefaultWalletsUsecase,
+    required this._createOnboardingWalletsUsecase,
     required this._completePhysicalBackupVerificationUsecase,
   }) : super(const OnboardingState()) {
     on<OnboardingCreateNewWallet>(_onCreateNewWallet);
@@ -26,18 +25,17 @@ class OnboardingBloc extends Bloc<OnboardingEvent, OnboardingState> {
     });
   }
 
-  final CreateDefaultWalletsUsecase _createDefaultWalletsUsecase;
+  final CreateOnboardingWalletsUsecase _createOnboardingWalletsUsecase;
 
   final CompletePhysicalBackupVerificationUsecase
   _completePhysicalBackupVerificationUsecase;
 
-  void _handleError(Exception error, Emitter<OnboardingState> emit) {
-    log.severe(error: error, trace: StackTrace.current);
+  void _emitFailure(OnboardingFailure failure, Emitter<OnboardingState> emit) {
     emit(
       state.copyWith(
         onboardingStepStatus: OnboardingStepStatus.none,
         step: OnboardingStep.splash,
-        failure: OnboardingUnexpectedFailure(error.toString()),
+        failure: failure,
       ),
     );
   }
@@ -50,18 +48,20 @@ class OnboardingBloc extends Bloc<OnboardingEvent, OnboardingState> {
     // dequeues, the 1st emit has already flipped the status to loading,
     // so this guard drops the duplicate (#2015).
     if (state.onboardingStepStatus == OnboardingStepStatus.loading) return;
-    try {
-      emit(
-        state.copyWith(
-          onboardingStepStatus: OnboardingStepStatus.loading,
-          step: OnboardingStep.create,
-          failure: null,
-        ),
-      );
-      await _createDefaultWalletsUsecase.execute();
-      emit(state.copyWith(onboardingStepStatus: OnboardingStepStatus.success));
-    } on Exception catch (e) {
-      _handleError(e, emit);
+    emit(
+      state.copyWith(
+        onboardingStepStatus: OnboardingStepStatus.loading,
+        step: OnboardingStep.create,
+        failure: null,
+      ),
+    );
+    switch (await _createOnboardingWalletsUsecase.execute()) {
+      case Ok():
+        emit(
+          state.copyWith(onboardingStepStatus: OnboardingStepStatus.success),
+        );
+      case Err(:final failure):
+        _emitFailure(failure, emit);
     }
   }
 
@@ -71,41 +71,36 @@ class OnboardingBloc extends Bloc<OnboardingEvent, OnboardingState> {
   ) async {
     // Same serialized-event guard as `_onCreateNewWallet` (#2015).
     if (state.onboardingStepStatus == OnboardingStepStatus.loading) return;
-    try {
-      emit(
-        state.copyWith(
-          onboardingStepStatus: OnboardingStepStatus.loading,
-          step: OnboardingStep.recover,
-          failure: null,
-        ),
-      );
-      final restoredWallets = await _createDefaultWalletsUsecase.execute(
-        mnemonicWords: event.mnemonic.words,
-      );
-      if (restoredWallets.isEmpty) {
-        _handleError(Exception('No wallets were restored'), emit);
-        return;
-      }
-      final completed = await _completePhysicalBackupVerificationUsecase
-          .execute(masterFingerprint: restoredWallets.first.masterFingerprint);
-      if (completed case Err(:final failure)) {
-        log.severe(
-          message: failure.logMessage,
-          error: failure,
-          trace: StackTrace.current,
-        );
-        emit(
-          state.copyWith(
-            onboardingStepStatus: OnboardingStepStatus.none,
-            step: OnboardingStep.splash,
-            failure: failure,
-          ),
-        );
-        return;
-      }
-      emit(state.copyWith(onboardingStepStatus: OnboardingStepStatus.success));
-    } on Exception catch (e) {
-      _handleError(e, emit);
+    emit(
+      state.copyWith(
+        onboardingStepStatus: OnboardingStepStatus.loading,
+        step: OnboardingStep.recover,
+        failure: null,
+      ),
+    );
+    switch (await _createOnboardingWalletsUsecase.execute(
+      mnemonicWords: event.mnemonic.words,
+    )) {
+      case Err(:final failure):
+        _emitFailure(failure, emit);
+      case Ok(:final value):
+        final completed = await _completePhysicalBackupVerificationUsecase
+            .execute(masterFingerprint: value.first.masterFingerprint);
+        switch (completed) {
+          case Ok():
+            emit(
+              state.copyWith(
+                onboardingStepStatus: OnboardingStepStatus.success,
+              ),
+            );
+          case Err(:final failure):
+            emit(
+              state.copyWith(
+                onboardingStepStatus: OnboardingStepStatus.success,
+                failure: failure,
+              ),
+            );
+        }
     }
   }
 }