From: merge-script <withtvpeter@gmail.com>
Date: Wed, 21 Oct 2026 22:51:58 +0000 (+0100)
Subject: Merge bitcoindevkit/bdk-cli#311: feat(hwi): Add Hardware Wallet Support
X-Git-Url: http://internal-gitweb-vhost/-client-interface/%22https:/src/struct.RpcConfig.html?a=commitdiff_plain;h=HEAD;p=bdk-cli

Merge bitcoindevkit/bdk-cli#311: feat(hwi): Add Hardware Wallet Support

d34e6bf020a9af14edc44af746f4895c9afb01c6 test(hwi): add more tests to helper fns (Vihiga Tyonum)
c2466e91eb7605a71b68c334224a303deb3e9a2f ref(hwi): move descriptor utils into descriptor utils (Vihiga Tyonum)
4131510db77240500d1df55be06b3da86bc11b52 feat(hwi): Add fingerprint to "hwi xpub" (Vihiga Tyonum)
3e3c0be3b1c8ca63beb831f087b9c5c263c80987 feat(hwi): Add merging ext and int desc into policy (Vihiga Tyonum)
e59a64d9036b5f77e98f2d0dd8b4a96b2421856d feat(hwi): Move register, address & sign to wallet (Vihiga Tyonum)
a12186601c5fdfc13887d9bf6df096284757602c feat(hwi): Reuse saved wallet config for hwi (Vihiga Tyonum)
abea78941ee2c9867448627d1db7ef62c7647601 feat(hwi): Add hwi documentation (Vihiga Tyonum)
25b60b6293180b2bff59340dbabce44597d23d18 feat(hwi): Add hidapi to workflows (Vihiga Tyonum)
ea7043eade4d11e7855c69f6620e3db8f3d8311e feat(hwi): Add hwi feature to dispatch and routing (Vihiga Tyonum)
7eab2467994ae5167f2fa19b42baa715b0be1bdc feat(hwi): Add hwi subcommand handler (Vihiga Tyonum)
0c9e1c386d6c63c7b10be93cf4430b74dd56b8be feat(hwi): Add utility fns to detect & list device (Vihiga Tyonum)

Pull request description:

  <!-- You can erase any parts of this template not applicable to your Pull Request. -->

  ### 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

  <!-- Describe the purpose of this PR, what's being adding and/or fixed -->

  ### 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`

  <!-- In this section you can include notes directed to the reviewers, like explaining why some parts
  of the PR were done in a specific way -->

  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.

  <!-- Notice the release manager should include in the release tag message changelog -->
  <!-- See https://keepachangelog.com/en/1.0.0/ for examples -->

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk-cli/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

  #### New Features:

  * [ ] I've added tests for the new feature
  * [x] I've added docs for the new feature
  * [x] I've updated `CHANGELOG.md`

ACKs for top commit:
  Musab1258:
    tACK d34e6bf020a9af14edc44af746f4895c9afb01c6

Tree-SHA512: 4756dc1ecbb541f478f183ac8d625fe5ed1978a201cfe869b71eaa40532400b840dcc0fd91545e94ba0eff9e90190c8440ae47f7ebb44914a0de67dec92ac474
---

525250e58ce9b788e47f5d5306b7239814d6c2ea