Onboarding & KYC bugs from Android test (2026-05-28)

[TaprootFreak]

Context

An Android internal-test session on 2026-05-28 surfaced five distinct bugs in the KYC and account-merge flow. A review on 2026-06-01 confirmed all five and produced a first diagnosis (summarised below).

Bundled in one issue because the bugs interact: the merge flow triggers redundant KYC, which the FoF-on-buy bug then amplifies. Split into separate PRs as appropriate and track sub-status via the checklist.

Bugs

1. FoF questions are asked on buy (should be on first sell only)

• Fix
• Expected: For the RealUnit wallet, the 10 Financial-Data questions fire only on the first sell, not on buy.
• Actual: FINANCIAL_DATA is required for every user, regardless of buy or sell.
• Diagnosis: The agreed differentiation is not implemented in the current state.
• Scope: api (KYC step logic), possibly app surface.

2. Duplicate merge mail

• Fix
• Expected: One merge-request mail per merge event.
• Actual: Two identical mails received. The ident-doc conflict triggered twice — once at the end of identification, once again on tapping "Aktualisieren" in the app.
• Diagnosis: The backend has three independent triggers (mail conflict, IBAN conflict, ident-doc conflict), each sending its own mail. No dedup per merge transaction.
• Scope: api (notification logic on the account-merge path).

3. KYC steps asked again after merge

• Fix
• Expected: Completed KYC steps on the master account survive the merge.
• Actual: After the merge, the 10 FoF questions were asked a second time.
• Diagnosis: The merge attaches the old account's KYC steps to the master account; the app sees them as open and re-prompts. Partially resolved by fixing chore: typo in *_repository.dart #1.
• Scope: api (merge logic must respect completed master-account steps).

4. 21-minute lag until "verification completed" mail

• Fix
• Expected: A few seconds.
• Actual: 21 minutes between merge completion and the "Ihre Verifizierung ist abgeschlossen" mail.
• Diagnosis: Part of the KYC follow-up runs on a 1-hour cron job; worst-case lag matches the observation.
• Goal: Move the path from cron-based to event-driven (target: seconds).
• Scope: api (KYC follow-up dispatch).

5. "Fehler beim Laden" in app after merge

• Fix
• Expected: A clear waiting/status indicator while the backend processes the merge.
• Actual: The app polls status with a 30-second timeout; the backend takes longer, the timeout fires, the user sees an error even though the merge is still progressing.
• Goal: Longer timeout or retry with explicit status messaging — no premature error.
• Scope: realunit-app (post-merge status polling).

[joshuakrueger-dfx]

Re #5 ("Fehler beim Laden" in app after merge) — app-side root cause + a fix plan and a red regression test (from a source-level review of develop).

Root cause: lib/screens/kyc/cubits/kyc/kyc_cubit.dart:45-56 wraps the entire KYC status chain (getKycStatus + getUser + getRegistrationInfo + continueKyc) in a single Future.timeout(30s). After a merge the backend legitimately takes longer than 30s, the timeout fires, and the cubit emits KycFailure('KYC backend did not respond in time') → kyc_page_manager.dart:49 renders KycFailurePage. There is no distinction between "still processing" and "failed", and no retry/waiting UX. (The existing _runGeneration cancellation token is good and the fix builds on it.)

Fix plan:

1. Make the timeout + retry policy injectable on the constructor (defaults preserve prod behavior; tests use ms): checkKycTimeout = const Duration(seconds: 30), maxStatusRetries, retryBackoff.
2. Add a KycProcessing state (waiting indicator + explicit message, e.g. "Zusammenführung wird verarbeitet…") rendered by kyc_page_manager.dart instead of KycFailurePage.
3. On TimeoutException (and transient/in-progress): emit KycProcessing, retry with bounded backoff up to maxStatusRetries; only emit KycFailure after the budget is exhausted. Keep the generation/isClosed guards on every retry continuation.
4. Optional: a longer budget specifically when the prior state was KycAccountMergeRequested.

Red regression test (drops into test/screens/kyc/cubits/kyc/kyc_cubit_test.dart; red against current code — no checkKycTimeout/maxStatusRetries params yet and current code emits KycFailure immediately on timeout):

group('post-merge slow backend (#611-5)', () {
  blocTest<KycCubit, KycState>(
    'shows processing + retries instead of a premature KycFailure when the first status call is slow',
    build: () {
      final kyc = _MockDfxKycService();
      final reg = _MockRealUnitRegistrationService();
      final store = _MockAppStore();
      final wallet = _MockAWallet();
      when(() => store.wallet).thenReturn(wallet);
      when(() => wallet.walletType).thenReturn(WalletType.software);
      when(() => kyc.getUser())
          .thenAnswer((_) async => _user(headerLevel: KycLevel.level20));
      when(() => reg.getRegistrationInfo()).thenAnswer((_) async =>
          RealUnitRegistrationInfoDto(state: RealUnitRegistrationState.alreadyRegistered));
      var call = 0;
      when(() => kyc.getKycStatus()).thenAnswer((_) async {
        if (++call == 1) {
          await Future<void>.delayed(const Duration(milliseconds: 200)); // > timeout: merge still processing
        }
        return _kycStatus(level: KycLevel.level20, processStatus: KycProcessStatus.completed);
      });
      return KycCubit(kyc, reg, store,
        checkKycTimeout: const Duration(milliseconds: 50), // NEW (fix): injectable
        maxStatusRetries: 2, retryBackoff: const Duration(milliseconds: 10),
      )..markLegalDisclaimerAccepted();
    },
    act: (c) => c.checkKyc(),
    wait: const Duration(milliseconds: 500),
    expect: () => [
      const KycLoading(),
      isA<KycProcessing>(),   // NEW state
      const KycLoading(),     // retry
      const KycCompleted(),
    ],
  );

  // companion: 'still fails after the retry budget is exhausted (slow forever)'
  // → [KycLoading, KycProcessing, KycLoading, KycProcessing, isA<KycFailure>()]
});

Binding assertions: no premature KycFailure while retries remain, and a KycProcessing waiting state appears. Exact emitted sequence is finalized with the implementation.

(For visibility: a broader read-only audit filed adjacent app-side findings as #612–#616; this comment stays scoped to #611-5.)

[joshuakrueger-dfx]

Fix PRs from the read-only audit (all open against develop)

PR	Issue/item	Title
#617	#615 M1	fix(sell): zero-pad EIP-7702 authorization r/s to 32 bytes
#618	#613 K1	fix(kyc): render pending page for dfxApproval instead of a blank screen
#619	#612 S1	fix(seed): block screenshots on the verify-seed screen
#620	#613 K2	fix(kyc): keep financial-data answers on submit failure (retryable)
#621	#612 S2	fix(wallet): fully purge seed + key on wallet delete

Each is locally verified against the dfx01 CI sequence (Flutter 3.41.6: generate_localization → generate_release_info → build_runner → analyze → test), with a red→green regression test.

CI status: functional checks pass on all — Analyze & Test ✅, Coverage Floor Gate ✅, BitBox quirks audit ✅ (#621's Coverage Floor was 99.9% and is fixed by an added SecureStorage.deleteMnemonicKey test, re-running). The red ✗ on the PRs is the pre-existing Visual Regression drift on one golden — home_golden_test.dart "HomePage loaded state with price data (macOS)" (101 pass / 1 fail) — which also fails on other develop-based PRs (e.g. #604) and on zero-UI changes, while develop-push is green. It clears via a golden-regenerate.yaml baseline run, separate from these fixes.

[TaprootFreak]

API-side tracking for the 5 items in this issue:

Bug	API issue
1. FoF questions on buy	DFXswiss/api#3798
2. Duplicate merge mail	DFXswiss/api#3799
3. KYC steps re-asked after merge	DFXswiss/api#3800
4. 21-min "verification completed" lag	DFXswiss/api#3801
5. App polling sees no in-progress merge state	DFXswiss/api#3802

Each API issue carries the source-code-level diagnosis (file:line) and suggested fix shape. Items 1 and 5 require companion app PRs (pair-PR convention from CONTRIBUTING.md); items 2, 3, 4 are pure backend.