Skip to content

feat: pair trezor passphrase hidden wallets - #1142

Draft
jvsena42 wants to merge 29 commits into
masterfrom
feat/hw-passphrase-wallets
Draft

feat: pair trezor passphrase hidden wallets#1142
jvsena42 wants to merge 29 commits into
masterfrom
feat/hw-passphrase-wallets

Conversation

@jvsena42

@jvsena42 jvsena42 commented Aug 6, 2026

Copy link
Copy Markdown
Member

Closes #1060

This PR:

  1. Adds an optional Passphrase path to the Connect Hardware flow, so the hidden wallets of a paired Trezor can be watched alongside its standard wallet
  2. Tracks each passphrase-derived account set as its own hardware wallet identity, with its own home tile, funds label, activity scope and removal
  3. Asks for the passphrase again before signing a transfer when the Trezor session that held it is gone, and refuses to sign if it opens a different wallet
  4. Lets the connect flow offer an already paired device, so passphrase wallets can be added after the initial pairing
  5. Fixes a Trezor Bridge session bug that blocked every passphrase pairing after the first on the emulator

Description

Trezor keeps no record of its hidden wallets and forgets a passphrase with the session, so Bitkit watches each one by its extended public keys and asks for the passphrase again whenever a session has to be rebuilt. The passphrase is never persisted or logged, and both entry screens block screenshots and screen recording the same way the wallet's own passphrase screens do.

A device previously mapped to a single wallet. It now maps to one identity per passphrase, keyed by the wallet id derived from its accounts rather than by the transport id, which two identities on the same device share. Watchers, balances, activity, labels and removal all follow that identity, and removing one hidden wallet leaves the others paired.

Pairing a hidden wallet adds an entry next to the standard one instead of replacing it. The device is matched by shared key material, so re-reading accounts updates the right entry while a different passphrase creates a new one. Only the identity that currently holds the device session shows as connected, since only that one can sign.

Before signing a transfer, Bitkit reopens the hidden wallet and accepts the session only if its accounts resolve back to the wallet being spent from. A wrong passphrase is not rejected by the device — it silently derives another wallet — so the mismatch is caught, the stray wallet that reading its accounts created is dropped, and the transfer fails instead of signing from the wrong wallet. A session that is still open signs with no prompt.

Discovery skips devices that are already paired, which left the Add Hardware Wallet button searching forever and made the passphrase step unreachable after the first pairing. It now falls back to offering a known reachable device once no new one is found.

Separately, the Bridge transport used for the emulator offered a released session id as the previous one when re-acquiring, and the bridge answered wrong previous session. Since switching to a passphrase wallet closes and reopens the session, this blocked every passphrase pairing after the first. This only affects builds with the Bridge enabled; USB and BLE are unaffected.

Preview

no-wallet-add-with-passphrase.webm
Add.multiple.passphrase.wallets.webm

QA Notes

Needs a Trezor with passphrase protection enabled. On the emulator start it with TREZOR_PASSPHRASE_PROTECTION=true ../bitkit-docker/scripts/trezor-emulator start and confirm on the device for every account a passphrase session reads, otherwise the call blocks until it times out.

Manual Tests

  • 1a. Settings → Hardware Wallets → Add → Found → Connect: Device Connected shows Passphrase and Finish.
    • 1b. Passphrase → enter a passphrase → Continue: Passphrase Funds Found shows the balance and Label Funds prefilled with the device name.
    • 1c. Rename the label → Finish: home shows a second hardware tile under that name.
  • 2. Home: headline total includes both hardware balances, and only the identity holding the device session shows a green connection indicator.
  • 3. Paired or Passphrase Funds Found → Passphrase → re-enter a passphrase already watched: toast reports it is already added, no tile is added.
  • 4a. Settings → Hardware Wallets: one row per identity, each with its own balance.
    • 4b. Rename one row: only that identity is renamed.
    • 4c. Delete the hidden wallet row: the standard wallet keeps working and the device stays paired, no re-pairing needed.
  • 5. Settings → Hardware Wallets → Add on an already paired device: reaches Found and then Device Connected, instead of searching forever.
  • 6a. Hidden wallet tile → Transfer To Spending → Amount → Sign → Open Trezor Connect while its session is still open: signs with no passphrase prompt.
    • 6b. Force-stop and relaunch the app, then repeat: the passphrase sheet opens before signing.
    • 6c. Enter a wrong passphrase: error says it opens a different wallet, nothing is signed or broadcast, and no extra tile appears.
    • 6d. Enter the correct passphrase: signing continues normally.
  • 7. regression: Pair a device without using the Passphrase path: home tile, detail screen, rename, remove and Transfer To Spending behave as before.
  • 8. Both passphrase screens: screenshots and screen recording are blocked, and the passphrase is absent from files/logs/ and files/datastore/ (release build; blocking is disabled in debug).

Automated Checks

  • Unit tests added: cover a passphrase wallet being added next to the standard one, the flag surviving reconnects, and credentials surviving a scoped removal in TrezorRepoTest.kt.
  • Unit tests added: cover two identities on one device, per-identity balances, connected state, funding account, scoped removal, and connectWithPassphrase including the already-watched case in HwWalletRepoTest.kt.
  • Unit tests added: cover the passphrase step effects, the duplicate toast, the label prefill, the paired step following the right identity, and the fallback to an already paired device in HwConnectViewModelTest.kt.
  • Unit tests added: cover signing with a live session, prompting once it is gone, and refusing a passphrase that opens another wallet in TransferViewModelTest.kt.
  • Unit tests added: cover re-acquiring after a release without the stale session in TrezorBridgeTransportTest.kt.
  • Unit tests modified: existing hardware tests moved to wallet-id keying in HwWalletRepoTest.kt, TransferViewModelTest.kt and HwConnectViewModelTest.kt.
  • Journeys added: passphrase-pairing.xml, passphrase-duplicate.xml, passphrase-settings-remove.xml and passphrase-transfer-to-spending.xml, including checks that the passphrase never reaches the logs or datastore.
  • Verified on a Pixel emulator against the Trezor emulator: pairing two hidden wallets alongside the standard one, per-identity labels, three home tiles, the connected indicator, and no passphrase in the logs. The duplicate, settings-remove and transfer journeys were not executed; the transfer one additionally needs regtest funds on a hidden wallet.
  • CI: standard compile, unit test and detekt checks run by the PR bot.

Known gaps

  • A hidden wallet can persist with only part of its accounts when a read fails with a device error that is not classified as transient, and its wallet id would change once the missing accounts are read. This is a pre-existing gap in the partial-save guard that passphrase sessions make easier to hit.
  • Two hidden wallets on the same device default to the same name until renamed, since the default label is the device name.

@jvsena42 jvsena42 self-assigned this Aug 6, 2026
Comment thread app/src/test/java/to/bitkit/repositories/TrezorRepoTest.kt Fixed
…eId in it.deviceIds } and unconditionally writes pairedWalletId = wallet.id, so a wallets emission that does not yet contain the just-added hidden wallet resets the paired identity back to the standard wallet.
…se POST, so a failed release still leaves the stale session id cached.
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.

Hardware wallet: passphrase (hidden) wallet pairing

2 participants