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. 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. 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. 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. 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. 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. Bitkit Core support for hardware wallet activities — add Bitkit Core support for hardware-wallet watcher activity so hardware transactions can reuse normal activity capabilities where appropriate: stable detail loading, inputs/outputs via Core transaction details fetched from the configured Electrum/electrs backend, and tag add/remove support. After the Bitkit Core support lands, update Bitkit Android's hardware-wallet activity path to use those Core activity/details/tag records so Activity Detail shows tags and inputs/outputs instead of the current watch-only fallback. Hardware activity visibility must stay scoped to paired hardware-wallet identities: removing a device deletes that wallet's hardware activity/details/tag metadata from Bitkit Core so the activity DB does not grow for unpaired devices; re-adding the same wallet should rebuild visible history from the watcher and fetch details again as needed.
• 7. Automated testing & polishing — UI test hooks (testTags / accessibility ids) on the new hardware screens + a hardware-wallet e2e shard so the connect / transfer flows are runnable by AI agents and in CI, driven by a Trezor emulator (no physical device). Polishing: improve reliability of reconnection, handle passphrase-enabled wallets explicitly, and optimise Bitkit pinging the Trezor device, currently results in user unable to unlock device due to repeated pings.

Android implementation notes are in the comment below.

[ovitrif]

Android implementation notes

(stale, not updating since scoping is captured for evaluation of how far off initial specs by AI were vs. where we got with new work discovered during implememntation)

Order mirrors the 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).