Hardware wallet: passphrase (hidden) wallet pairing

[piotr-iohk]

Part of #998.

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

Related: #1030 — reconnect/signing safety for passphrase identities (runtime). This issue owns the pairing UX and watch-only identity model.

Design

Screen	Figma
Enter Passphrase	46312-107873
Passphrase funds found	46312-107925

Extends the existing Connect Hardware Paired step (standard wallet): secondary Passphrase action → enter passphrase → confirm label/balance → Passphrase again or Finish.

Goal

Pair and watch multiple Trezor wallet identities from one physical device:

• Standard wallet (empty passphrase) — already shipped.
• Hidden wallet(s) — user enters a passphrase; Bitkit persists xpubs and shows a separate hardware balance tile.

Trezor does not store passphrases or list hidden wallets. Bitkit must never persist raw passphrases — watch-only via xpubs; re-enter passphrase when signing.

Scope

• Connect flow: Passphrase button on Paired → Enter Passphrase → Passphrase Paired (label + balance) → loop or Finish.
• Passphrase entry: host (phone) and/or on-device on capable models (Safe 5/7), same as dev Trezor screen.
• Identity model: each passphrase-derived xpub set = separate walletKey / home tile / settings row / remove action.
• Settings follow-up: Add passphrase wallet on an already-paired device (not only during initial connect loop).
• Zero balance: allow add; non-blocking warning if balance is 0 ("No balance found — double-check passphrase if you expected funds").
• Duplicate: same xpub already watched → "already added", no duplicate tile.
• Signing: Transfer to Spending from a hidden wallet reconnects/signs with that identity (coordinate with Hardware wallet connection reliability and UX polish #1030).

Out of scope

• Enabling Trezor "passphrase protection" device setting (Trezor Suite).
• Discovering unknown passphrases / storing passphrase for convenience.
• E2E emulator coverage (can land in Hardware wallet emulator E2E coverage #1038).

Acceptance criteria

• Standard wallet pairs unchanged; Passphrase path adds a separate watched identity.
• Separate home tile + HW settings row per identity; remove is per-identity.
• Zero-balance hidden wallet can be added (warning, not block).
• Duplicate passphrase rejected.
• Add passphrase wallet from settings after pairing.
• Passphrase not persisted; signing uses correct identity.
• Android + iOS parity.

Unknowns (need product / eng decision)

1. Home UI grouping — separate tiles per identity (Figma) vs one device row with sub-accounts?
2. Default label — Figma uses "Trezor Safe 3B" suffix; pattern for auto-naming vs user-only?
3. Zero-balance UX — warn-only (proposed) vs hard gate ("no balance → check passphrase" error)?
4. Typo handling — wrong passphrase = valid empty wallet; no reliable detection. Is warn-on-zero enough, or extra confirmation copy?
5. Pairing loop limits — unlimited Passphrase taps during connect, or cap and defer rest to settings?
6. Standard wallet with 0 balance — same warn/copy as passphrase, or different treatment on first Paired screen?
7. Signing UX — always re-prompt passphrase on Transfer to Spending, or session-cache for active connect only?
8. MVP timing — 2.4.0 with Figma, or follow-up after core connect/transfer ships?

Cross-platform spec — comment here for decisions that affect both platforms.