From 62d3ea144be1abe00ef6b009b85561c88a3df641 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 4 Aug 2026 22:35:52 +0200 Subject: [PATCH 01/11] descriptor: add ranged descriptor derivation Add a helper that selects a receive or change branch and address index without mutating the original descriptor. --- hwilib/descriptor.py | 12 ++++++++++++ test/test_descriptor.py | 15 +++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/hwilib/descriptor.py b/hwilib/descriptor.py index 0e8531179..14c8098ad 100644 --- a/hwilib/descriptor.py +++ b/hwilib/descriptor.py @@ -29,6 +29,7 @@ from base64 import b64decode, b64encode from binascii import unhexlify from collections import namedtuple +from copy import deepcopy from enum import Enum from io import BufferedReader, BytesIO from typing import ( @@ -354,6 +355,17 @@ def get_pubkey_providers(self) -> list['PubkeyProvider']: out.extend(s.get_pubkey_providers()) return out + def derive(self, pos: int, multipath_index: int = 0) -> 'Descriptor': + """Select a multipath entry and address index from a ranged descriptor.""" + + descriptor = deepcopy(self) + for pubkey in descriptor.get_pubkey_providers(): + path = pubkey.get_deriv_path(pos, multipath_index) + pubkey.deriv_path = [[step] for step in path] or None + pubkey.ranged = False + pubkey.multipath_len = 1 + return descriptor + class PKDescriptor(Descriptor): """ diff --git a/test/test_descriptor.py b/test/test_descriptor.py index 828e24616..4755b815b 100755 --- a/test/test_descriptor.py +++ b/test/test_descriptor.py @@ -16,6 +16,21 @@ import unittest class TestDescriptor(unittest.TestCase): + def test_derive(self): + xpub = "tpubD6NzVbkrYhZ4WaWSyoBvQwbpLkojyoTZPRsgXELWz3Popb3qkjcJyJUGLnL4qHHoQvao8ESaAstxYSnhyswJ76uZPStJRJCTKvosUCJZL5B" + descriptor_str = "wsh(multi(1,{0}/<0;1;2>/*,{0}/<10;11;12>/*))".format(xpub) + descriptor = parse_descriptor(descriptor_str) + + self.assertEqual( + descriptor.derive(7).to_string_no_checksum(), + "wsh(multi(1,{0}/0/7,{0}/10/7))".format(xpub), + ) + self.assertEqual( + descriptor.derive(7, multipath_index=2).to_string_no_checksum(), + "wsh(multi(1,{0}/2/7,{0}/12/7))".format(xpub), + ) + self.assertEqual(descriptor.to_string_no_checksum(), descriptor_str) + def test_parse_descriptor_with_origin(self): d = "wpkh([00000001/84h/1h/0h]tpubD6NzVbkrYhZ4WaWSyoBvQwbpLkojyoTZPRsgXELWz3Popb3qkjcJyJUGLnL4qHHoQvao8ESaAstxYSnhyswJ76uZPStJRJCTKvosUCJZL5B/0/0)" desc = parse_descriptor(d) From d8b0d995e6ac23d39372b893266f2b59adc7354b Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 4 Aug 2026 21:30:27 +0200 Subject: [PATCH 02/11] displayaddress: add BIP388 policy support Accept a serialized registered descriptor, address index, and change flag, then request that address from the selected device. --- hwilib/_cli.py | 18 ++++++++++++++++-- hwilib/commands.py | 35 +++++++++++++++++++++++++++++++++-- hwilib/hwwclient.py | 12 ++++++++++++ 3 files changed, 61 insertions(+), 4 deletions(-) diff --git a/hwilib/_cli.py b/hwilib/_cli.py index 3d14600d9..4a17a53f8 100644 --- a/hwilib/_cli.py +++ b/hwilib/_cli.py @@ -57,8 +57,16 @@ def backup_device_handler(args: argparse.Namespace, client: HardwareWalletClient) -> Dict[str, bool]: return backup_device(client, label=args.label, backup_passphrase=args.backup_passphrase) -def displayaddress_handler(args: argparse.Namespace, client: HardwareWalletClient) -> Dict[str, str]: - return displayaddress(client, desc=args.desc, path=args.path, addr_type=args.addr_type) +def displayaddress_handler(args: argparse.Namespace, client: HardwareWalletClient) -> Dict[str, Union[int, str]]: + return displayaddress( + client, + desc=args.desc, + path=args.path, + addr_type=args.addr_type, + registration=args.registration, + index=args.index, + multipath_index=args.multipath_index, + ) def enumerate_handler(args: argparse.Namespace) -> List[Dict[str, Any]]: return enumerate(password=args.password, expert=args.expert, chain=args.chain, allow_emulators=args.allow_emulators) @@ -198,7 +206,13 @@ def get_parser() -> HWIArgumentParser: group = displayaddr_parser.add_mutually_exclusive_group(required=True) group.add_argument('--desc', help='Output Descriptor. E.g. wpkh([00000000/84h/0h/0h]xpub.../0/0), where 00000000 must match --fingerprint and xpub can be obtained with getxpub. See doc/descriptors.md in Bitcoin Core') group.add_argument('--path', help='The BIP 32 derivation path of the key embedded in the address, default follows BIP43 convention, e.g. ``m/84h/0h/0h/1/*``') + group.add_argument('--registration', help='Registration returned by the registerdescriptor command') displayaddr_parser.add_argument("--addr-type", help="The address type to display", type=AddressType.argparse, choices=list(AddressType), default=AddressType.WIT) # type: ignore + displayaddr_policy_group = displayaddr_parser.add_argument_group("BIP388 policy") + displayaddr_policy_group.add_argument('--index', help='Address index to display from the policy', type=int) + displayaddr_multipath_group = displayaddr_policy_group.add_mutually_exclusive_group() + displayaddr_multipath_group.add_argument('--multipath-index', help='Multipath index to select from the policy', type=int) + displayaddr_multipath_group.add_argument('--change', help='Select the change branch (equivalent to --multipath-index 1)', action='store_const', const=1, dest='multipath_index') displayaddr_parser.set_defaults(func=displayaddress_handler) setupdev_parser = subparsers.add_parser('setup', help='Setup a device. Passphrase protection uses the password given by -p. Requires interactive mode') diff --git a/hwilib/commands.py b/hwilib/commands.py index 1730f9ffc..eb47465d8 100644 --- a/hwilib/commands.py +++ b/hwilib/commands.py @@ -39,6 +39,7 @@ ) from .descriptor import ( Descriptor, + RegisteredDescriptor, parse_descriptor, MultisigDescriptor, TRDescriptor, @@ -435,8 +436,11 @@ def displayaddress( client: HardwareWalletClient, path: Optional[str] = None, desc: Optional[str] = None, - addr_type: AddressType = AddressType.WIT -) -> Dict[str, str]: + addr_type: AddressType = AddressType.WIT, + registration: Optional[str] = None, + index: Optional[int] = None, + multipath_index: Optional[int] = None, +) -> Dict[str, Union[int, str]]: """ Display an address on the device for client. The address can be specified by the path with additional parameters, or by a descriptor. @@ -445,10 +449,37 @@ def displayaddress( :param path: The path of the address to display. Mutually exclusive with ``desc`` :param desc: The descriptor to display the address for. Mutually exclusive with ``path`` :param addr_type: The address type to return. Only works with ``path`` + :param registration: Serialized registered descriptor for BIP388 policy display + :param index: Address index to display for BIP388 policy mode + :param multipath_index: Multipath index to select for BIP388 policy mode :return: A dictionary containing the address displayed. Returned as ``{"address": }``. :raises: BadArgumentError: if an argument is malformed, missing, or conflicts. """ + policy_mode = index is not None or registration is not None or multipath_index is not None + if policy_mode: + if registration is None: + raise BadArgumentError("Missing --registration") + if index is None: + raise BadArgumentError("Missing --index") + if index < 0: + raise BadArgumentError("Address index must be non-negative") + if multipath_index is None: + multipath_index = 0 + elif multipath_index < 0: + raise BadArgumentError("Multipath index must be non-negative") + + registered_descriptor = RegisteredDescriptor.deserialize(registration) + address = client.display_bip388_policy_address( + registered_descriptor, + index, + multipath_index, + ) + return { + "address": address, + "index": index, + "multipath_index": multipath_index, + } if path is not None: return {"address": client.display_singlesig_address(path, addr_type)} elif desc is not None: diff --git a/hwilib/hwwclient.py b/hwilib/hwwclient.py index 394bd837f..ab08b20c2 100644 --- a/hwilib/hwwclient.py +++ b/hwilib/hwwclient.py @@ -139,6 +139,18 @@ def display_multisig_address( raise NotImplementedError("The HardwareWalletClient base class " "does not implement this method") + def display_bip388_policy_address( + self, + registered_descriptor: RegisteredDescriptor, + index: int, + multipath_index: int = 0, + ) -> str: + """Display and return an address from a BIP388 descriptor policy.""" + + raise NotImplementedError( + "This device does not support BIP388 policy address display or it is not yet implemented" + ) + def wipe_device(self) -> bool: """ Wipe the device. From ac8391fac183eee6dc0e4895404b3be2eab4475a Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 4 Aug 2026 21:31:44 +0200 Subject: [PATCH 03/11] ledger: support BIP388 policy address display Reconstruct the wallet policy from the registered descriptor, then display the selected receive or change address. --- hwilib/devices/ledger.py | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/hwilib/devices/ledger.py b/hwilib/devices/ledger.py index b4df7140b..868c1c9c5 100644 --- a/hwilib/devices/ledger.py +++ b/hwilib/devices/ledger.py @@ -483,6 +483,34 @@ def format_key_info(pubkey: PubkeyProvider) -> str: return self.client.get_wallet_address(multisig_wallet, registered_hmac, change, address_index, True) + @ledger_exception + def display_bip388_policy_address( + self, + registered_descriptor: RegisteredDescriptor, + index: int, + multipath_index: int = 0, + ) -> str: + if isinstance(self.client, LegacyClient): + raise BadArgumentError( + "Displaying a BIP388 policy address is not supported by this version of the Bitcoin App" + ) + + wallet_policy = WalletPolicy( + name=registered_descriptor.name, + descriptor_template=registered_descriptor.descriptor.get_bip388_template(), + keys_info=[ + key.get_bip388_key_info() + for key in registered_descriptor.descriptor.get_pubkey_providers() + ], + ) + return self.client.get_wallet_address( + wallet_policy, + registered_descriptor.registration, + multipath_index, + index, + True, + ) + def setup_device(self, label: str = "", passphrase: str = "") -> bool: """ Ledgers do not support setup via software. From 23fb64e7f28e45aa0abb14cd56ba5f8db4c61881 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 21 Aug 2026 11:58:38 +0200 Subject: [PATCH 04/11] coldcard: enroll Edge policies with Miniscript --- hwilib/devices/coldcard.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/hwilib/devices/coldcard.py b/hwilib/devices/coldcard.py index 8b627e5f6..a865bdbe9 100644 --- a/hwilib/devices/coldcard.py +++ b/hwilib/devices/coldcard.py @@ -471,7 +471,12 @@ def register_descriptor(self, name: str, descriptor: 'Descriptor') -> Registered raise DeviceFailureError(f"Wrong checksum, expected {expect.hex()}, got {result.hex()}") # Register the descriptor - self.device.send_recv(CCProtocolPacker.multisig_enroll(size, expect), timeout=None) + enroll = ( + CCProtocolPacker.miniscript_enroll + if self.is_edge + else CCProtocolPacker.multisig_enroll + ) + self.device.send_recv(enroll(size, expect), timeout=None) if self.device.is_simulator: self.device.send_recv(CCProtocolPacker.sim_keypress(b'y')) return RegisteredDescriptor(name=name, descriptor=descriptor, device_type="coldcard", registration=b"") From 169fdd0004b6090682c7cc7c730259d15e980df2 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 21 Aug 2026 11:58:47 +0200 Subject: [PATCH 05/11] coldcard: support registered policy address display Derive the selected wsh(sortedmulti()) policy address and display it through the existing multisig command. --- hwilib/devices/coldcard.py | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/hwilib/devices/coldcard.py b/hwilib/devices/coldcard.py index a865bdbe9..df8b61b92 100644 --- a/hwilib/devices/coldcard.py +++ b/hwilib/devices/coldcard.py @@ -13,6 +13,7 @@ Descriptor, MultisigDescriptor, RegisteredDescriptor, + WSHDescriptor, ) from ..hwwclient import HardwareWalletClient from ..errors import ( @@ -346,6 +347,40 @@ def display_multisig_address( self.device.send_recv(CCProtocolPacker.sim_keypress(b'y')) return address + def display_bip388_policy_address( + self, + registered_descriptor: RegisteredDescriptor, + index: int, + multipath_index: int = 0, + ) -> str: + if self.is_edge: + if multipath_index not in (0, 1): + raise BadArgumentError("Coldcard Edge only supports receive and change branches") + address = self.device.send_recv( + CCProtocolPacker.miniscript_address( + registered_descriptor.name, + change=bool(multipath_index), + idx=index, + ), + timeout=None, + ) + assert isinstance(address, str) + if self.device.is_simulator: + self.device.send_recv(CCProtocolPacker.sim_keypress(b'y')) + return address + + descriptor = registered_descriptor.descriptor.derive(index, multipath_index) + if ( + not isinstance(descriptor, WSHDescriptor) + or len(descriptor.subdescriptors) != 1 + or not isinstance(descriptor.subdescriptors[0], MultisigDescriptor) + ): + raise BadArgumentError("Coldcard only supports wsh(sortedmulti()) policies") + return self.display_multisig_address( + AddressType.WIT, + descriptor.subdescriptors[0], + ) + def setup_device(self, label: str = "", passphrase: str = "") -> bool: """ The Coldcard does not support setup via software. From 86a86c6f26b1fcb8be44b151cead3e3ba661a40f Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 21 Aug 2026 11:59:06 +0200 Subject: [PATCH 06/11] test: fix Coldcard simulator multisig path iteration --- test/data/coldcard-multisig.patch | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/test/data/coldcard-multisig.patch b/test/data/coldcard-multisig.patch index 05216356f..f47608651 100644 --- a/test/data/coldcard-multisig.patch +++ b/test/data/coldcard-multisig.patch @@ -60,7 +60,7 @@ index 1e692d41..6294e9a3 100644 # return list of lists [xfp, *deriv] - return list(self.xfp_paths.values()) + ret = [] -+ for paths_list in self.xfp_paths: ++ for paths_list in self.xfp_paths.values(): + for xfp_path in paths_list: + ret.append(xfp_path) + return ret @@ -111,4 +111,3 @@ index 1e692d41..6294e9a3 100644 return True -- 2.51.0 - From 26cbbe45913bef8f5e5f64aead693ecab4a213a0 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 4 Aug 2026 21:31:58 +0200 Subject: [PATCH 07/11] jade: support BIP388 policy address display Use the registered descriptor name to request the selected receive or change address. --- hwilib/devices/jade.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/hwilib/devices/jade.py b/hwilib/devices/jade.py index 91848bb36..b1ed9f890 100644 --- a/hwilib/devices/jade.py +++ b/hwilib/devices/jade.py @@ -458,6 +458,21 @@ def display_multisig_address(self, addr_type: AddressType, multisig: MultisigDes return str(address) + @jade_exception + def display_bip388_policy_address( + self, + registered_descriptor: RegisteredDescriptor, + index: int, + multipath_index: int = 0, + ) -> str: + address = self.jade.get_receive_address( + self._network(), + multipath_index, + index, + descriptor_name=registered_descriptor.name, + ) + return str(address) + # Setup a new device def setup_device(self, label: str = "", passphrase: str = "") -> bool: """ From dcb524532dda60b38dc39db7c7a0f7bc2f2fff5e Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 4 Aug 2026 22:28:58 +0200 Subject: [PATCH 08/11] bitbox02: support BIP388 policy address display Translate the registered policy into a BitBox02 script configuration and display the selected receive or change address. --- hwilib/devices/bitbox02.py | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/hwilib/devices/bitbox02.py b/hwilib/devices/bitbox02.py index 67f7209b8..d7902d5f3 100644 --- a/hwilib/devices/bitbox02.py +++ b/hwilib/devices/bitbox02.py @@ -521,6 +521,33 @@ def display_singlesig_address( ) return address + @bitbox02_exception + def display_bip388_policy_address( + self, + registered_descriptor: RegisteredDescriptor, + index: int, + multipath_index: int = 0, + ) -> str: + descriptor = registered_descriptor.descriptor + account_keypath = None + device_fingerprint = self.get_master_fingerprint() + for pubkey in descriptor.get_pubkey_providers(): + if ( + pubkey.origin is not None + and pubkey.origin.fingerprint == device_fingerprint + ): + account_keypath = pubkey.origin.path + break + if account_keypath is None: + raise BadArgumentError("This BitBox02 is not one of the policy keys") + + return self.init().btc_address( + [*account_keypath, multipath_index, index], + coin=self._get_coin(), + script_config=self._bip388_script_config(descriptor), + display=True, + ) + @bitbox02_exception def display_multisig_address( self, From fc113c74d8160c07dc25c4b7f0ac8b3de2f326e4 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 4 Aug 2026 21:31:23 +0200 Subject: [PATCH 09/11] test: display registered descriptor address Extend the generic descriptor registration test to display address index 7 from the registered policy. --- test/test_device.py | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/test/test_device.py b/test/test_device.py index 5a55185a4..421054dbd 100644 --- a/test/test_device.py +++ b/test/test_device.py @@ -14,6 +14,7 @@ from typing import Dict from authproxy import AuthServiceProxy, JSONRPCException +from hwilib import _bech32 as bech32 from hwilib._base58 import xpub_to_pub_hex, to_address, decode from hwilib._cli import process_commands from hwilib.descriptor import AddChecksum, parse_descriptor, PubkeyProvider, RegisteredDescriptor @@ -806,3 +807,24 @@ def test_register_descriptor(self): self.assertGreater(len(reg.registration), 0) else: self.assertEqual(len(reg.registration), 0) + + address_index = 7 + multipath_index = 1 + expected_address = self.rpc.deriveaddresses( + reg.descriptor.to_string(), [address_index, address_index] + )[multipath_index][0] + result = self.do_command(self.dev_args + [ + "displayaddress", + "--index", str(address_index), + "--multipath-index", str(multipath_index), + "--registration", result["registration"], + ]) + self.assertNotIn("error", result) + self.assertNotIn("code", result) + self.assertIn("address", result) + self.assertEqual(result["index"], address_index) + self.assertEqual(result["multipath_index"], multipath_index) + self.assertEqual( + bech32.decode("bcrt", expected_address), + bech32.decode("tb", result["address"]), + ) From 1a6fb497cb29f0c53b1b6176c5fd755a17e7d0e5 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Mon, 17 Aug 2026 14:49:10 +0200 Subject: [PATCH 10/11] test: disambiguate Ledger fee automation The new app renders the "Fees" title at y=3, while the legacy app renders it at y=7. Match both positions explicitly so an address line such as "Fee3bWhy6jMv2rzbRs" does not trigger the fee-screen action. --- test/data/speculos-automation.json | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/test/data/speculos-automation.json b/test/data/speculos-automation.json index 5618fefb7..58c2c72ac 100644 --- a/test/data/speculos-automation.json +++ b/test/data/speculos-automation.json @@ -39,7 +39,23 @@ ] }, { - "regexp": "^(Address|Review|Account name|Amount|External amounts|You spend|You receive|Fee|Confirm|The derivation|Derivation path|Reject if|The change path|Change path|Register wallet|Policy map|Key|Path|Public key|Our key|Their key|Unspendable key|Spend from|Spending policy|Primary spending path|Spending path|Transaction output|From account|Wallet name|Wallet policy|Descriptor template|Verify [Bb]itcoin|Output|Warning).*", + "regexp": "^(Address|Review|Account name|Amount|External amounts|You spend|You receive|Confirm|The derivation|Derivation path|Reject if|The change path|Change path|Register wallet|Policy map|Key|Path|Public key|Our key|Their key|Unspendable key|Spend from|Spending policy|Primary spending path|Spending path|Transaction output|From account|Wallet name|Wallet policy|Descriptor template|Verify [Bb]itcoin|Output|Warning).*", + "actions": [ + [ "button", 2, true ], + [ "button", 2, false ] + ] + }, + { + "regexp": "^Fee.*", + "y": 3, + "actions": [ + [ "button", 2, true ], + [ "button", 2, false ] + ] + }, + { + "regexp": "^Fees$", + "y": 7, "actions": [ [ "button", 2, true ], [ "button", 2, false ] From 458a92009f5f7244863f0e3def070f9212d8b479 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Fri, 21 Aug 2026 11:38:18 +0200 Subject: [PATCH 11/11] test: make Ledger approval automation atomic The automation models a simultaneous left-and-right press as four separate events. If the app redraws between events, Speculos can apply the remaining input on a different screen. In the observed failure this advanced to "Reject transaction" and confirmed it. Use button mask 3 for one combined press and release for all two-button approvals, keeping them atomic across redraws. --- test/data/speculos-automation.json | 30 ++++++++++-------------------- 1 file changed, 10 insertions(+), 20 deletions(-) diff --git a/test/data/speculos-automation.json b/test/data/speculos-automation.json index 58c2c72ac..4ee4cfefb 100644 --- a/test/data/speculos-automation.json +++ b/test/data/speculos-automation.json @@ -13,29 +13,23 @@ "text": "Confirm", "x": 43, "y": 37, "actions": [ - [ "button", 1, true ], - [ "button", 2, true ], - [ "button", 1, false ], - [ "button", 2, false ] + [ "button", 3, true ], + [ "button", 3, false ] ] }, { "text": "Confirm", "x": 41, "y": 34, "actions": [ - [ "button", 1, true ], - [ "button", 2, true ], - [ "button", 1, false ], - [ "button", 2, false ] + [ "button", 3, true ], + [ "button", 3, false ] ] }, { "text": "Confirm account ", "actions": [ - [ "button", 1, true ], - [ "button", 2, true ], - [ "button", 1, false ], - [ "button", 2, false ] + [ "button", 3, true ], + [ "button", 3, false ] ] }, { @@ -79,10 +73,8 @@ { "regexp": "^(Accept|Approve|Continue|Sign message|Sign transaction|Register account).*", "actions": [ - [ "button", 1, true ], - [ "button", 2, true ], - [ "button", 1, false ], - [ "button", 2, false ] + [ "button", 3, true ], + [ "button", 3, false ] ] }, { @@ -118,10 +110,8 @@ [ "seen_msg_hash", true ] ], "actions": [ - [ "button", 1, true ], - [ "button", 2, true ], - [ "button", 1, false ], - [ "button", 2, false ], + [ "button", 3, true ], + [ "button", 3, false ], [ "setbool", "seen_msg_hash", false ] ] }