feat(hwi): Add hwi documentation

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 916b581a7d4b5f18b24463330c59abe089cf10ac..baa324a205fdf993d8fa24eb2a02fab4c4b2d653 100644 (file)
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ page. See [DEVELOPMENT_CYCLE.md](DEVELOPMENT_CYCLE.md) for more details.
 - Rejected `--proxy` on the `rpc` backend, and unsupported proxy options (`--proxy_auth`, `--timeout`) on the `rpc` and `cbf` backends, instead of silently ignoring them
 - Fixed `compile` rejecting policies that are valid for the requested script type
 - Fixed `warn!` messages, including the mainnet notice, being hidden unless `RUST_LOG` was set; warnings are now shown by default
+- Added `hwi` feature with a hardware wallet `hwi` command to list connected devices, register a wallet policy, display a receive address, and sign PSBTs. Supports Ledger, Coldcard, BitBox02, Jade and Specter.
 
 ## [4.0.0]
 

diff --git a/README.md b/README.md
index 94278f3cb6354b9f9c465f5ef51bca0fe0adf6da..98c21ff5836f712b209200d7abcb2b475a5254a8 100644 (file)
--- a/README.md
+++ b/README.md
@@ -56,6 +56,7 @@ bdk-cli can be compiled with different features to suit your experimental needs.
      - `message_signer`: BIP322 message signing/verification.
      - `silent-payments`: Experimental BIP-352 silent payment sending
      - `dns_payment`: BIP-353 DNS payment instructions
+     - `hwi`: Hardware wallet support (Ledger, Coldcard, BitBox02, Jade, Specter) to list devices, register a wallet policy, display a receive address, and sign PSBTs.
     
 The `default` feature set is `repl` and `sqlite`. With the `default` features, `bdk-cli` can be used as an **air-gapped** wallet, and can do everything that doesn't require a network connection.
 
@@ -206,6 +207,38 @@ View all payjoin sessions (active and completed) and also see their status:
 cargo run -- wallet --wallet <wallet_name> payjoin_history
 ```
 
+## Hardware wallet (HWI)
+
+Compile with the `hwi` feature to interact with a connected hardware wallet
+(Ledger, Coldcard, BitBox02, Jade or Specter). On Linux you need the USB/HID
+system libraries first:
+
+```shell
+sudo apt-get install -y libudev-dev libusb-1.0-0-dev pkg-config
+```
+List every connected device (fingerprint and model):
+
+```shell
+cargo run --features hwi -- hwi devices
+```
+Register a wallet policy on the device. This returns an HMAC that some devices (e.g. Ledger) require to reuse the policy on later calls:
+
+```shell
+cargo run --features hwi -- hwi --wallet my_wallet --ext-descriptor <policy> register
+```
+
+Display a receive address on the device for verification (defaults to external keychain, index 0):
+
+```shell
+cargo run --features hwi -- hwi --ext-descriptor <policy> address 
+```
+
+Sign a PSBT with the device:
+
+```shell
+cargo run --features hwi -- hwi --wallet my_wallet --ext-descriptor <policy> --hmac <hmac> sign <base64-psbt>
+```
+
 ## Justfile
 
 We have added the `just` command runner to help you with common commands (during development) and running regtest `bitcoind` if you are using the `rpc` feature.