Skip to content

feat(hwi): Add Hardware Wallet Support - #311

Open
tvpeter wants to merge 8 commits into
bitcoindevkit:masterfrom
tvpeter:feat/add-hwi
Open

feat(hwi): Add Hardware Wallet Support#311
tvpeter wants to merge 8 commits into
bitcoindevkit:masterfrom
tvpeter:feat/add-hwi

Conversation

@tvpeter

@tvpeter tvpeter commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

Description

Adds hardware wallet support to the project using async-hwi library. Supported hardware devices include Specter, Jade, Ledger, Coldcard, and BitBox02 together with their simulators.

This supersedes #207, which was approved but went stale after the project restructure. The feature has been reimplemented from scratch on the current modular structure, and the design is reworked around the saved wallet config.

Commands:

The feature introduced two top-level commands (hwi devices and hwi xpub) and wallet subcommands (register, address, and sign).

  • hwi xpub [<path>] [--type <wpkh|tr|sh-wpkh|pkh>]: reads a device extended public key. Outputs a ready-to-use key expression and external/internal descriptors.
  • hwi devices: list every connected device (fingerprint + model).
  • register: Wallet scoped operation (wallet -w <walletname> hwi register). It registers the wallet policy on the device (returns the HMAC where the device supports it). The policy comes from the saved wallet config.
  • address: Also a wallet-scoped operation. It displays the address on-device where supported, and derive it locally.
  • sign <psbt>: sign a PSBT with the device.

fixes #194

Notes to the reviewers

  • xpub and devices are top-level because you need xpub to build a wallet.
  • register, address, sign live under wallet and read descriptors from the saved config.
  • Policy handling. async-hwi expects a single multipath (…/<0;1>/*) public wallet policy. BDK stores the external/internal chains as two single-path descriptors, so the code combines them (from the wallet's public_descriptor, guaranteeing xpub-only) into the multipath form.
  • create_tx defaults --offline_signer to true when built with hwi, so PSBTs carry the xpub data the hardware wallets need.

Known limitations:

  • Only the first connected device is used
  • sign produces partial signatures only; finalize separately with finalize_psbt
  • On-device address display for single-sig is limited to taproot (async-hwi has no simple wpkh display path); other single-sig returns the locally derived address.

HWI subcommand implementation

  • hwi xpub
  • hwi devices
  • wallet … hwi register
  • wallet … hwi address
  • wallet … hwi sign

Devices tested:

  • specter simulator: devices, xpub, register, sign
  • bitbox simulator: devices, xpub, register, sign
  • coldcard device: devices, xpub, address, sign

Changelog notice

  • Added hwi feature with hardware wallet support (Specter, Jade, Ledger, Coldcard, BitBox02) to read device xpubs, list devices, register a wallet policy, display/verify addresses, and sign PSBTs.

Checklists

All Submissions:

  • I've signed all my commits
  • I followed the contribution guidelines
  • I ran cargo fmt and cargo clippy before committing

New Features:

  • I've added tests for the new feature
  • I've added docs for the new feature
  • I've updated CHANGELOG.md

@codecov

codecov Bot commented Aug 6, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 332 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.74%. Comparing base (e7223e5) to head (51da903).
⚠️ Report is 1 commits behind head on master.

Files with missing lines Patch % Lines
src/handlers/hwi.rs 0.00% 204 Missing ⚠️
src/utils/hwi.rs 0.00% 112 Missing ⚠️
src/main.rs 0.00% 13 Missing ⚠️
src/handlers/repl.rs 0.00% 3 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #311      +/-   ##
==========================================
- Coverage   57.45%   52.74%   -4.72%     
==========================================
  Files          22       24       +2     
  Lines        3695     4027     +332     
==========================================
+ Hits         2123     2124       +1     
- Misses       1572     1903     +331     
Flag Coverage Δ
rust 52.74% <0.00%> (-4.72%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

Add back HWI signing support

1 participant