epic: Trezor Hardware Wallet UI

[ovitrif]

Design: Figma — Trezor Screens

Related (iOS): synonymdev/bitkit-ios#589

Context

Bitkit is adding a Hardware Wallet balance type alongside Savings (on-chain) and Spending (Lightning), backed by Trezor. The hardware balance is a watch-only view of funds held on a paired Trezor: Bitkit displays the amount and the device's on-chain activity but never holds the keys. Removing a device just stops Bitkit from displaying its balance.

The home-screen parents already exist (Savings/Spending tiles, suggestion carousel, Settings list), but the hardware/Trezor side of each is missing.

Device naming & connection indicator

• Display name = label ?: model ?: "Trezor" — label is the device name set on the Trezor (editable on-device / in Trezor Suite), model is the hardware model (e.g. "Safe 3" / "Safe 7").
• The Figma "LABEL FUNDS" field is a Bitkit-side display name for the balance, defaulting to the resolved device name; persisted per device so the user can rename within Bitkit without touching the device.
• Connection indicator = connection type (Bluetooth or USB), tinted green while the device is currently connected. Figma examples: bluetooth · usb.

Subtasks

• 1. #1024 Home Screen hardware-wallet updates — (a) full-width device row below the Savings|Spending tiles (<device name> [conn-type indicator, green when connected] ₿ <balance>, blue BTC icon; empty state ₿ 0), hardware funds included in the headline total, device activity merged into the home activity list; (b) new "HARDWARE / Connect device" suggestion card in the carousel → opens the Connect Hardware flow.
• 2. #1025 Hardware Wallet detail screen — Savings/Spending-style overview: top bar = device name + blue BTC icon; balance header; Transfer To Spending button; grouped activity list; Remove <device name> → confirm dialog ("Don't worry, your funds are safe and your coins won't be deleted. Bitkit will simply stop displaying the amounts in the wallet." / Cancel / Remove). Empty state = ₿ 0, Send/Receive only.
• 3. #1026 Hardware Wallet settings — (a) new row in Settings ▸ General ▸ Payments, value = paired-device count → (b) Hardware Wallets Settings Screen: list of paired devices (name + balance + green connection indicator when connected + per-row delete) + Add Hardware Wallet button → Connect flow.
• 4. #1027 Connect Hardware flow (bottom-modal, 4 steps) — Intro (ADD YOUR HARDWARE WALLET) → Searching (SEARCHING FOR DEVICES, USB or Bluetooth) → Found (FOUND TREZOR, pair prompt) → Paired (PAIRED TREZOR, editable LABEL FUNDS field defaulting to the device name, Finish). Entered from the suggestion card or from Hardware Wallets Settings ▸ Add.
• 5. #1028 Transfer to Spending from HW device flow (top-level-screens navigation, 4 steps) — watch-only: channel funding is a send signed on the Trezor device. Amount (numpad; AVAILABLE = savings limit; 25% shortcut; MAX = savings − fees/reserve or the Blocktank limit; over-max resets + error toast) → Review & Sign (SIGN WITH YOUR DEVICE; network/service fees, to-spending, total; Open Trezor Connect; disconnected → "Reconnect Hardware Device" error) → Transaction Signed (checkmark; auto-forwards after a short delay) → Processing Payment (existing frame). Figma frame.
• 6. #1029 Bitkit Core support for hardware wallet activities — integrate Core wallet-scoped activity support after refactor: move walletId to v2 activity models bitkit-core#112 and fix: add wallet-scoped backup migrations bitkit-core#113: persist watcher activities and transaction details with the shared hardware wallet id, load details/tags through Core using the activity wallet id, and keep global list/search scoped so normal Bitkit and hardware-wallet activity only merge where the UI expects it.
• 7. #1046 Hardware Wallet Data Backup & Restore — after fix: add wallet-scoped backup migrations bitkit-core#113 lands, update the app Activity/Metadata VSS restore so Core-owned activity JSON is migrated/imported by Core before typed decode, then rewrite VSS with migrated/current Core entries. The app owns the VSS envelope, not Core model migration.
• 8. #1030 Hardware wallet connection reliability and UX polish — improve reconnection reliability, handle passphrase-enabled wallets explicitly, improve pairing-code/PIN retry states, optimise Bitkit's Trezor ping cadence so the app backs off while the device is waiting for user action, and route Trezor-related logs through the normal app log capture.
• 9. #1038 Hardware wallet emulator E2E coverage — UI test hooks (testTags / accessibility IDs), current journey docs, and a hardware-wallet E2E shard so connect / transfer flows are runnable by AI agents and in CI, driven by a Trezor emulator rather than a physical device.
• 10. #1056 Rename hardware wallet from Settings — follow-up to Hardware Wallet settings #1026 / feat: hardware wallets settings #1032: tap device name on Hardware Wallets settings → rename sheet (NAME + Save; empty disabled); reuse HwWalletRepo.setDeviceLabel and customLabel; parity with iOS feat: hardware wallets settings screen bitkit-ios#612 and Figma Rename Hardware Wallet.
• 11. #1060 Hardware wallet: passphrase (hidden) wallet pairing — optional Passphrase path in Connect flow (Enter Passphrase → Passphrase Paired); separate watch-only identity per passphrase (home tile, label, remove); Add passphrase wallet from HW settings; never persist passphrase. iOS tracker: Hardware wallet: passphrase (hidden) wallet pairing bitkit-ios#615. Figma: Enter Passphrase · Passphrase funds found.
• 12. #1088 Trezor transfer to spending uses low on-chain fee rate — HW funding uses settings medium/mid (and 1 sat/vB fallback), so transfers can linger unconfirmed; use fast + raise fallback floor. iOS tracker: [Bug]: Trezor transfer to spending uses low on-chain fee rate bitkit-ios#633.

Initial specs are in the comment below.

[ovitrif]

Android implementation notes

Current follow-up split:

• Hardware wallet connection reliability and UX polish #1030 tracks runtime connection reliability and UX polish.
• Hardware wallet emulator E2E coverage #1038 tracks emulator/E2E coverage and automation.

The notes below are intentionally stale and kept as historical implementation guidance for comparing the original AI-generated spec against the later discovered work.

Order mirrors the original subtasks. All patterns confirmed in the codebase — reuse, don't reinvent.

1. Home Screen updates — extend BalancesSection() in ui/screens/wallets/HomeScreen.kt with the full-width hardware row; include hardware sats in the total; merge device activity into the home activity list. Suggestion card: add HARDWARE to models/Suggestion.kt (title/description/color/icon), add the drawable + cards__hardware__* strings, wire it into a suggestion-list builder and the onClickSuggestion when to open the Connect flow; dismissal is automatic.

2. Hardware Wallet detail screen — model on ui/screens/wallets/SavingsWalletScreen.kt / SpendingWalletScreen.kt: parent composable + inner Content(). New HardwareWalletScreen.kt in ui/screens/wallets/. Reuse BalanceHeaderView, activityListGroupedItems(), AppTopBar, SecondaryButton, EmptyStateView, and the existing confirm-dialog pattern for Remove. Ensure the bottom Send / Scan / Receive button bar (the overlay shown on Savings/Spending detail screens) also renders on this route.

3. Hardware Wallet settings — in ui/settings/SettingsScreen.kt add a SettingsButtonRow under Payments with SettingsButtonValue.StringValue(deviceCount), a HardwareWalletsClick : SettingsEvent, and a handler navigating to the new HardwareWalletsScreen.kt (list + Add), reusing the settings row components. Add settings__hardware_wallets_* strings.

4. Connect Hardware flow — the 4 steps are bottom sheets via the existing Sheet/showSheet mechanism, backed by HwWalletViewModel / HwWalletRepo (see Cross-cutting).

5. Transfer to Spending from HW device flow — also bottom sheets; mirror the existing Spending transfer flow, swapping local signing for on-device signing (Open Trezor Connect).

6. Automated testing — the repo already ships a TrezorBridgeTransport (services/TrezorBridgeTransport.kt, HTTP, default http://10.0.2.2:21325) gated by BuildConfig.TREZOR_BRIDGE / TREZOR_BRIDGE_URL, with a unit test that mocks an emulator:21324 device — i.e. the path for testing without physical hardware already exists. Plan: (a) add testTags on the new composables; (b) build the E2E APK with E2E=true TREZOR_BRIDGE=true pointed at a trezor-user-env emulator (ghcr.io/trezor/trezor-user-env, ports 21324/21325); (c) add a @hardware shard of flows to the external synonymdev/bitkit-e2e-tests repo covering connect + transfer-to-spending; (d) add adb/deep-link android-cli journeys so an agent can drive the same paths locally. Extend the existing TrezorRepoTest / TrezorViewModelTest / TrezorBridgeTransportTest unit coverage for the new VM/repo.

Cross-cutting

Navigation & routes — in ui/ContentView.kt: add the new @Serializable routes and register with composableWithDefaultTransitions. Use direct route navigation at the call site — do not add navigateToHardwareWallet()-style helpers (current preference).

ViewModels / Repo — keep the existing dev-settings integration but rename it for clarity: TrezorViewModel → TrezorDevSettingsViewModel and TrezorScreen → TrezorDevSettingsScreen (stays the dev-settings entry). Add a new, lighter HwWalletViewModel (named generically so it can back future vendors) for the production connect / balance / transfer flows. Introduce HwWalletRepo as the production hardware-wallet business layer (evolve/rename the existing repositories/TrezorRepo.kt — it already holds the device list, connect orchestration, and KnownDevice persistence via TrezorStore); keep the Trezor-specific TrezorTransport / TrezorBridgeTransport classes as-is underneath. Both TrezorDevSettingsViewModel and HwWalletViewModel consume HwWalletRepo. Repo methods return Result<T>; UiState is @Immutable/@Stable with ImmutableList fields and _uiState.update {}.

Changelog — one user-facing feat: fragment in changelog.d/next/ (<pr>.added.md).