Skip to content

feat(startup): replace legacy migration with a backup gate, drop hive - #2559

Merged
ethicnology merged 6 commits into
developfrom
remove-hive-legacy-migrations
Aug 6, 2026
Merged

feat(startup): replace legacy migration with a backup gate, drop hive#2559
ethicnology merged 6 commits into
developfrom
remove-hive-legacy-migrations

Conversation

@ethicnology

@ethicnology ethicnology commented Aug 4, 2026

Copy link
Copy Markdown
Member

hive was only kept alive by the legacy storage migrations: the v0.1–v0.4 → v5
chain (004_legacy + 005_hive_to_sqlite) and the legacy_seed_view recovery
feature. Those paths serve BULL builds from 2023–2024 (Android only); the app is
at v6.13.

Simply deleting the migration would strand any user still on those builds: the
app would start empty with no guidance.

What changes

Pre-v5 installs are now gated behind a backup screen instead of being migrated
(commit 1):

  • CheckLegacyInstallUsecase detects the legacy version marker in secure
    storage (Android only — other platforms never shipped a pre-v5 build, and the
    guard avoids the iOS pre-first-unlock keychain error).
  • GetLegacySeedsUsecase enumerates legacy seeds without Hive: the old app
    always stored the seed material itself (keyed by fingerprint) in secure
    storage; Hive only held the wallet index.
  • LegacyBackupScreen blocks startup: it shows each recovery phrase (and any
    non-empty passphrases — omitting them would strand funds), makes the user
    confirm they wrote everything down, then instructs them to delete and
    reinstall the app and recover. If the marker says legacy but no seed is
    readable, it points to support instead of suggesting a delete.
  • The migration code becomes unreachable at this commit and is removed in the
    next two.

Then the legacy path is deleted (commits 2–3): the legacy_seed_view
feature, the 004_legacy + 005_hive_to_sqlite migrations,
RequiresMigrationUsecase, all DI wiring, and the hive dependency itself
(−3 700 lines).

Security notes (key material — please review carefully)

  • The new screen displays recovery phrases. It follows the repo's sealed-UI
    rules: the bloc state carries no seed (legacyBackupRequired is a plain
    marker); the widget reads the seeds internally and never returns them;
    no_screenshot is enabled while shown; the words and passphrases are excluded
    from the semantics/accessibility tree; nothing is logged.
  • Reinstalling wipes app data (including the old Hive files) on Android, which
    is why the flow instructs a reinstall rather than an in-app reset.

What deliberately does NOT change

  • Users already migrated (v5+) are unaffected — the gate only triggers on the
    pre-v5 version marker.
  • hive leaves the lockfile entirely; nothing else depended on it.
  • No change to the current (post-v5) schema migrations (schema_*_to_*.dart).
  • legacy_seed_view was never in the FEATURES.md graph, so no graph update is
    needed.

Commit reading order

  1. feat(startup): gate legacy installs behind a seed-backup screen — the
    behaviour change: detection, seed enumeration, sealed screen, l10n, tests.
  2. refactor(settings): drop the legacy_seed_view feature — feature + settings
    wiring + dead l10n keys.
  3. refactor(storage): drop the legacy v4/v5 hive migration path — migrations,
    DI wiring, hive dependency.

Test plan

Automated (in this PR):

  • make analyze — no issues (matches CI: --fatal-warnings --fatal-infos)
  • make unit-test — all green, including 10 new tests:
    CheckLegacyInstallUsecase (marker prefixes, non-Android guard, current
    version) and GetLegacySeedsUsecase (valid seed parsing, passphrase
    filtering, non-seed entries skipped, empty store)
  • fvm flutter pub get --enforce-lockfile resolves without hive

Manual QA:

  • Fresh install / already-migrated install: startup is unchanged (no gate)
  • Legacy install (version marker 0.1–0.4 in secure storage): the backup
    gate appears, shows the recovery phrase(s) + passphrase(s), screenshots are
    blocked, and the confirm checkbox reveals the reinstall instructions
  • Settings → Bitcoin: the "Legacy seeds" entry is gone

@ethicnology

Copy link
Copy Markdown
Member Author

@claude review this please

@claude

This comment was marked as resolved.

@ethicnology
ethicnology force-pushed the remove-hive-legacy-migrations branch 2 times, most recently from c47d087 to fef0a38 Compare August 4, 2026 18:29
@ethicnology ethicnology self-assigned this Aug 4, 2026
@ethicnology

Copy link
Copy Markdown
Member Author

@wired-pasteque can you try the legacy apk https://github.com/SatoshiPortal/bullbitcoin-mobile/actions/runs/30940542068 migration to the current branch https://github.com/SatoshiPortal/bullbitcoin-mobile/actions/runs/30941630233 ?

@ethicnology
ethicnology force-pushed the remove-hive-legacy-migrations branch from fef0a38 to dc90d5e Compare August 4, 2026 22:08
@wired-pasteque

Copy link
Copy Markdown
Collaborator

@ethicnology, tested on my side - did the full loop, recovery included - everything is working as expected:

Installed the legacy APK, set up my wallet, then installed the new build over the top. The notice screen appeared as expected with the steps on what to do (see the screenshot), legacy seeds line in Settings still showed the seed at that point.

After reinstalling the app and recovering - balance still correct, nothing lost, and the legacy seeds line in Settings is now gone. Fresh and already-migrated installs start normally with no gate. Working as expected on my end.

Screenshot_20260805-002005

@ethicnology

Copy link
Copy Markdown
Member Author

Do you ACK the concept @i5hi @BullishNode @thibistaken ?

Getting rid of the unmaintained dependency hive by dropping the migration from the archaic 0.4.X to >5.X.X (sqlite) by forcing the user to make a backup and re-install the app to recover. This is the same kind of solution we offered for the forced migration to flutter_secure_storage version 10

@i5hi

i5hi commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

conceptACK

@ethicnology
ethicnology force-pushed the remove-hive-legacy-migrations branch from dc90d5e to c8abf87 Compare August 6, 2026 19:20
Conflicts resolved:

- legacy_seed_view_screen.dart: deleted. This branch replaces the feature with app_startup's legacy backup screen, which already blocks capture through the PrivacyScreen mixin and keeps the words out of the semantics tree, so develop's screen-capture fix (1dd4aec) is preserved in the new screen rather than lost with the old one.
- settings_cubit.dart, settings_locator.dart and settings_cubit_test.dart: the union of both sides' removals — no GetOldSeedsUsecase (dropped here along with the hive migration path) and no RevokeArkUsecase (dropped on develop along with the Ark feature). toggleDevMode keeps develop's signature without the WalletBloc parameter, and the cubit keeps develop's payjoin-policy wiring.
- 13 .arb files: resolved as a key-level three-way merge, so both sides' additions are kept and both sides' deletions applied. arkAboutDustValue and arkSendConfirmMessage (removed with Ark on develop) and legacySeedViewNoSeedsMessage and bitcoinSettingsLegacySeedsTitle (removed with the legacy seed view here) are all gone.
updateSenderSessionState came in unformatted with the payjoin package (a568d1a), so `make format-check` — and therefore the CI checks job — fails on every branch that carries develop. Formatting only, no behaviour change; cherry-pick it onto develop if you prefer to fix it at the source.
@ethicnology
ethicnology merged commit d8f0255 into develop Aug 6, 2026
@claude claude Bot mentioned this pull request Aug 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants