From 06cb627da6ffa30620709f4b68f95f1a7f56bbe7 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Sat, 1 Aug 2026 21:22:41 +0200 Subject: [PATCH 1/4] Add BIP388 descriptor-to-policy conversion Convert combined multipath output descriptors into BIP388 descriptor templates and key vectors, and validate that the result follows BIP388. Cover all canonical valid and invalid BIP388 policy vectors. Co-authored-by: Codex (GPT-5.6 Sol) --- .github/workflows/type-check.yml | 1 + hwilib/common.py | 2 - hwilib/policy.py | 201 +++++++++++++++++++++++++++++++ test/run_tests.py | 2 + test/test_policy.py | 190 +++++++++++++++++++++++++++++ 5 files changed, 394 insertions(+), 2 deletions(-) create mode 100644 hwilib/policy.py create mode 100644 test/test_policy.py diff --git a/.github/workflows/type-check.yml b/.github/workflows/type-check.yml index 09a04c08c..0eb6cd4fb 100644 --- a/.github/workflows/type-check.yml +++ b/.github/workflows/type-check.yml @@ -40,4 +40,5 @@ jobs: hwilib/hwwclient.py hwilib/__init__.py hwilib/key.py + hwilib/policy.py hwilib/udevinstaller.py diff --git a/hwilib/common.py b/hwilib/common.py index 0c5c00606..5dcc533e9 100644 --- a/hwilib/common.py +++ b/hwilib/common.py @@ -9,7 +9,6 @@ from typing import Union - class Chain(Enum): """ The blockchain network to use @@ -56,7 +55,6 @@ def argparse(s: str) -> Union['AddressType', str]: except KeyError: return s - def sha256(s: bytes) -> bytes: """ Perform a single SHA256 hash. diff --git a/hwilib/policy.py b/hwilib/policy.py new file mode 100644 index 000000000..04c325554 --- /dev/null +++ b/hwilib/policy.py @@ -0,0 +1,201 @@ +"""BIP388 wallet policy helpers.""" + +from dataclasses import dataclass +import re +from typing import Dict, List, Optional, Set, Tuple + +from .descriptor import DescriptorChecksum +from .errors import BadArgumentError +from .key import ExtendedKey, KeyOriginInfo + + +_EXTENDED_KEY_RE = re.compile( + r"(?P\[[^\]]+\])?(?P[1-9A-HJ-NP-Za-km-z]{100,120})" +) +_PLACEHOLDER_RE = re.compile(r"@(0|[1-9][0-9]*)") +_MUSIG_RE = re.compile(r"(? "BIP388Policy": + """Convert a combined multipath output descriptor into a BIP388 policy.""" + + descriptor = _strip_and_check_checksum(descriptor) + if any(char.isspace() for char in descriptor): + raise BadArgumentError("Whitespace is not allowed in a BIP388 descriptor") + _check_balanced(descriptor) + + keys_info: List[str] = [] + key_indexes: Dict[str, int] = {} + xpub_origins: Dict[str, str] = {} + template_parts: List[str] = [] + last_end = 0 + + for match in _EXTENDED_KEY_RE.finditer(descriptor): + key_str = match.group("key") + try: + extkey = ExtendedKey.deserialize(key_str) + except Exception as exc: + raise BadArgumentError(f"Invalid extended key in descriptor: {key_str}") from exc + if extkey.is_private: + raise BadArgumentError("BIP388 key information must use extended public keys") + + origin_str = "" + raw_origin = match.group("origin") + if raw_origin is not None: + try: + origin = KeyOriginInfo.from_string(raw_origin[1:-1]) + except Exception as exc: + raise BadArgumentError(f"Invalid key origin: {raw_origin}") from exc + normalized_origin = origin.to_string(hardened_char="'") + origin_str = f"[{normalized_origin}]" + elif match.start("key") > 0 and descriptor[match.start("key") - 1] == "]": + raise BadArgumentError("Invalid key origin in descriptor") + + canonical_xpub = extkey.to_string() + key_info = origin_str + canonical_xpub + previous_key_info = xpub_origins.setdefault(canonical_xpub, key_info) + if previous_key_info != key_info: + raise BadArgumentError("The same extended public key has conflicting origins") + + if key_info not in key_indexes: + key_indexes[key_info] = len(keys_info) + keys_info.append(key_info) + + template_parts.append(descriptor[last_end:match.start()]) + template_parts.append(f"@{key_indexes[key_info]}") + last_end = match.end() + + if not keys_info: + raise BadArgumentError("Descriptor does not contain any extended public keys") + + template_parts.append(descriptor[last_end:]) + descriptor_template = "".join(template_parts).replace("/<0;1>/*", "/**") + _validate_template(descriptor_template, len(keys_info)) + + return cls( + name=name, + descriptor_template=descriptor_template, + keys_info=keys_info, + registration=registration, + ) + + +def _strip_and_check_checksum(descriptor: str) -> str: + if descriptor.count("#") > 1: + raise BadArgumentError("Descriptor has more than one checksum separator") + if "#" not in descriptor: + return descriptor + + descriptor, checksum = descriptor.split("#", 1) + expected = DescriptorChecksum(descriptor) + if checksum != expected: + raise BadArgumentError( + f"The descriptor checksum does not match: got {checksum}, expected {expected}" + ) + return descriptor + + +def _check_balanced(descriptor: str) -> None: + pairs = {")": "(", "}": "{"} + stack: List[str] = [] + for char in descriptor: + if char in "({": + stack.append(char) + elif char in pairs: + if not stack or stack.pop() != pairs[char]: + raise BadArgumentError("Descriptor has unbalanced delimiters") + if stack: + raise BadArgumentError("Descriptor has unbalanced delimiters") + + +def _find_closing_parenthesis(template: str, open_pos: int) -> int: + depth = 1 + for pos in range(open_pos + 1, len(template)): + if template[pos] == "(": + depth += 1 + elif template[pos] == ")": + depth -= 1 + if depth == 0: + return pos + raise BadArgumentError("Descriptor has an unterminated musig expression") + + +def _parse_derivation(template: str, pos: int) -> Tuple[int, Set[int]]: + if template.startswith("/**", pos): + return pos + 3, {0, 1} + + match = re.match(r"/<(0|[1-9][0-9]*);(0|[1-9][0-9]*)>/\*", template[pos:]) + if match is None: + raise BadArgumentError( + "Every BIP388 key placeholder must use /** or //*" + ) + first = int(match.group(1)) + second = int(match.group(2)) + if first == second or first >= (1 << 31) or second >= (1 << 31): + raise BadArgumentError("Invalid BIP388 receive/change derivation") + return pos + match.end(), {first, second} + + +def _validate_template(template: str, key_count: int) -> None: + if "[" in template or "]" in template: + raise BadArgumentError("Descriptor contains key origin data without an extended key") + if _EXTENDED_KEY_RE.search(template) is not None: + raise BadArgumentError("A BIP388 descriptor template may only contain key placeholders") + + musig_placeholder_spans: List[Tuple[int, int]] = [] + usages: Dict[Tuple[str, Tuple[int, ...]], List[Set[int]]] = {} + for match in _MUSIG_RE.finditer(template): + close_pos = _find_closing_parenthesis(template, match.end() - 1) + args = template[match.end():close_pos] + if re.fullmatch(r"@[0-9]+(?:,@[0-9]+)+", args) is None: + raise BadArgumentError("A BIP388 musig expression must contain only key placeholders") + indexes = tuple(int(value) for value in re.findall(r"@([0-9]+)", args)) + if len(set(indexes)) != len(indexes): + raise BadArgumentError("A BIP388 musig expression cannot repeat a key") + _, branches = _parse_derivation(template, close_pos + 1) + identity = ("musig", tuple(sorted(indexes))) + usages.setdefault(identity, []).append(branches) + musig_placeholder_spans.append((match.end(), close_pos)) + + def in_musig(pos: int) -> bool: + return any(start <= pos < end for start, end in musig_placeholder_spans) + + seen: Set[int] = set() + next_index = 0 + for match in _PLACEHOLDER_RE.finditer(template): + index = int(match.group(1)) + if index >= key_count: + raise BadArgumentError(f"BIP388 placeholder @{index} has no corresponding key") + if index not in seen: + if index != next_index: + raise BadArgumentError("BIP388 keys are not ordered by first placeholder use") + seen.add(index) + next_index += 1 + if not in_musig(match.start()): + _, branches = _parse_derivation(template, match.end()) + usages.setdefault(("key", (index,)), []).append(branches) + + if seen != set(range(key_count)): + raise BadArgumentError("Not every BIP388 key is used by the descriptor template") + + for branch_sets in usages.values(): + used: Set[int] = set() + for branches in branch_sets: + if used.intersection(branches): + raise BadArgumentError("A BIP388 key is reused in overlapping derivation branches") + used.update(branches) diff --git a/test/run_tests.py b/test/run_tests.py index 80300db1f..49d81f35b 100755 --- a/test/run_tests.py +++ b/test/run_tests.py @@ -13,6 +13,7 @@ from test_psbt import TestPSBT from test_trezor import trezor_test_suite from test_ledger import ledger_test_suite +from test_policy import TestBIP388Policy from test_digitalbitbox import digitalbitbox_test_suite from test_keepkey import keepkey_test_suite from test_jade import jade_test_suite @@ -84,6 +85,7 @@ suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestPSBT)) suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBase58)) suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBIP32)) + suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBIP388Policy)) if sys.platform.startswith("linux"): suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestUdevRulesInstaller)) success = unittest.TextTestRunner(stream=sys.stdout, verbosity=2).run(suite).wasSuccessful() diff --git a/test/test_policy.py b/test/test_policy.py new file mode 100644 index 000000000..63b750c0d --- /dev/null +++ b/test/test_policy.py @@ -0,0 +1,190 @@ +#!/usr/bin/env python3 + +import unittest + +from hwilib.descriptor import AddChecksum +from hwilib.errors import BadArgumentError +from hwilib.policy import BIP388Policy, _validate_template + + +XPUB_A = "tpubDCwYjpDhUdPGP5rS3wgNg13mTrrjBuG8V9VpWbyptX6TRPbNoZVXsoVUSkCjmQ8jJycjuDKBb9eataSymXakTTaGifxR6kmVsfFehH1ZgJT" +XPUB_B = "tpubDDoFYQF4zAhrW8LRtCxePR8bJsAh5SXU6PwPNi2oRfeh67qhmxZawJ4m3V76P8AYSEueKmwvNyiSPAGYtynGfzJNvTHyzj2FJTbp729jmYM" + +# Canonical test vectors from BIP388 version 1.1.0: +# https://github.com/bitcoin/bips/blob/master/bip-0388.mediawiki#test-vectors +BIP44_KEY = "[6738736c/44'/0'/0']xpub6Br37sWxruYfT8ASpCjVHKGwgdnYFEn98DwiN76i2oyY6fgH1LAPmmDcF46xjxJr22gw4jmVjTE2E3URMnRPEPYyo1zoPSUba563ESMXCeb" +BIP49_KEY = "[6738736c/49'/0'/1']xpub6Bex1CHWGXNNwGVKHLqNC7kcV348FxkCxpZXyCWp1k27kin8sRPayjZUKDjyQeZzGUdyeAj2emoW5zStFFUAHRgd5w8iVVbLgZ7PmjAKAm9" +BIP84_KEY = "[6738736c/84'/0'/2']xpub6CRQzb8u9dmMcq5XAwwRn9gcoYCjndJkhKgD11WKzbVGd932UmrExWFxCAvRnDN3ez6ZujLmMvmLBaSWdfWVn75L83Qxu1qSX4fJNrJg2Gt" +BIP86_KEY = "[6738736c/86'/0'/0']xpub6CryUDWPS28eR2cDyojB8G354izmx294BdjeSvH469Ty3o2E6Tq5VjBJCn8rWBgesvTJnyXNAJ3QpLFGuNwqFXNt3gn612raffLWfdHNkYL" +BIP48_KEY_0 = "[6738736c/48'/0'/0'/2']xpub6FC1fXFP1GXLX5TKtcjHGT4q89SDRehkQLtbKJ2PzWcvbBHtyDsJPLtpLtkGqYNYZdVVAjRQ5kug9CsapegmmeRutpP7PW4u4wVF9JfkDhw" +BIP48_KEY_1 = "[b2b1f0cf/48'/0'/0'/2']xpub6EWhjpPa6FqrcaPBuGBZRJVjzGJ1ZsMygRF26RwN932Vfkn1gyCiTbECVitBjRCkexEvetLdiqzTcYimmzYxyR1BZ79KNevgt61PDcukmC7" +POLICY_KEY_0 = "[6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa" +POLICY_KEY_1 = "[b2b1f0cf/44'/0'/0'/100']xpub6EYajCJHe2CK53RLVXrN14uWoEttZgrRSaRztujsXg7yRhGtHmLBt9ot9Pd5ugfwWEu6eWyJYKSshyvZFKDXiNbBcoK42KRZbxwjRQpm5Js" +POLICY_KEY_2 = "[a666a867/44'/0'/0'/100']xpub6Dgsze3ujLi1EiHoCtHFMS9VLS1UheVqxrHGfP7sBJ2DBfChEUHV4MDwmxAXR2ayeytpwm3zJEU3H3pjCR6q6U5sP2p2qzAD71x9z5QShK2" +POLICY_KEY_3 = "[bb641298/44'/0'/0'/100']xpub6Dz8PHFmXkYkykQ83ySkruky567XtJb9N69uXScJZqweYiQn6FyieajdiyjCvWzRZ2GoLHMRE1cwDfuJZ6461YvNRGVBJNnLA35cZrQKSRJ" +TAPROOT_KEY_1 = "xpub6Fc2TRaCWNgfT49nRGG2G78d1dPnjhW66gEXi7oYZML7qEFN8e21b2DLDipTZZnfV6V7ivrMkvh4VbnHY2ChHTS9qM3XVLJiAgcfagYQk6K" +TAPROOT_KEY_2 = "xpub6GxHB9kRdFfTqYka8tgtX9Gh3Td3A9XS8uakUGVcJ9NGZ1uLrGZrRVr67DjpMNCHprZmVmceFTY4X4wWfksy8nVwPiNvzJ5pjLxzPtpnfEM" +TAPROOT_KEY_3 = "xpub6GjFUVVYewLj5no5uoNKCWuyWhQ1rKGvV8DgXBG9Uc6DvAKxt2dhrj1EZFrTNB5qxAoBkVW3wF8uCS3q1ri9fueAa6y7heFTcf27Q4gyeh6" +NON_PLACEHOLDER_XPUB = "xpub6AHA9hZDN11k2ijHMeS5QqHx2KP9aMBRhTDqANMnwVtdyw2TDYRmF8PjpvwUFcL1Et8Hj59S3gTSMcUQ5gAqTz3Wd8EsMTmF3DChhqPQBnU" +RECEIVE_CHANGE_DERIVATION = "/<0;1>/*" +ALTERNATE_DERIVATION = "/<2;3>/*" +OVERLAPPING_DERIVATION = "/<1;2>/*" + + +class TestBIP388Policy(unittest.TestCase): + def test_bip388_valid_policy_vectors(self) -> None: + musig_3_of_3 = f"musig({POLICY_KEY_0},{POLICY_KEY_1},{POLICY_KEY_2})" + musig_0_1 = f"musig({POLICY_KEY_0},{POLICY_KEY_1})" + musig_0_2 = f"musig({POLICY_KEY_0},{POLICY_KEY_2})" + musig_1_2 = f"musig({POLICY_KEY_1},{POLICY_KEY_2})" + + valid_policies = [ + ( + "BIP-44, first account", + "pkh(@0/**)", + [BIP44_KEY], + f"pkh({BIP44_KEY}{RECEIVE_CHANGE_DERIVATION})", + ), + ( + "BIP-49, second account", + "sh(wpkh(@0/**))", + [BIP49_KEY], + f"sh(wpkh({BIP49_KEY}{RECEIVE_CHANGE_DERIVATION}))", + ), + ( + "BIP-84, third account", + "wpkh(@0/**)", + [BIP84_KEY], + f"wpkh({BIP84_KEY}{RECEIVE_CHANGE_DERIVATION})", + ), + ( + "BIP-86, first account", + "tr(@0/**)", + [BIP86_KEY], + f"tr({BIP86_KEY}{RECEIVE_CHANGE_DERIVATION})", + ), + ( + "BIP-48 P2WSH multisig", + "wsh(sortedmulti(2,@0/**,@1/**))", + [BIP48_KEY_0, BIP48_KEY_1], + f"wsh(sortedmulti(2,{BIP48_KEY_0}{RECEIVE_CHANGE_DERIVATION},{BIP48_KEY_1}{RECEIVE_CHANGE_DERIVATION}))", + ), + ( + "Miniscript 3-of-3 degrading to 2-of-3", + "wsh(thresh(3,pk(@0/**),s:pk(@1/**),s:pk(@2/**),sln:older(12960)))", + [POLICY_KEY_0, POLICY_KEY_1, POLICY_KEY_2], + f"wsh(thresh(3,pk({POLICY_KEY_0}{RECEIVE_CHANGE_DERIVATION}),s:pk({POLICY_KEY_1}{RECEIVE_CHANGE_DERIVATION}),s:pk({POLICY_KEY_2}{RECEIVE_CHANGE_DERIVATION}),sln:older(12960)))", + ), + ( + "Miniscript automatic inheritance", + "wsh(or_d(pk(@0/**),and_v(v:multi(2,@1/**,@2/**,@3/**),older(65535))))", + [POLICY_KEY_0, POLICY_KEY_1, POLICY_KEY_2, POLICY_KEY_3], + f"wsh(or_d(pk({POLICY_KEY_0}{RECEIVE_CHANGE_DERIVATION}),and_v(v:multi(2,{POLICY_KEY_1}{RECEIVE_CHANGE_DERIVATION},{POLICY_KEY_2}{RECEIVE_CHANGE_DERIVATION},{POLICY_KEY_3}{RECEIVE_CHANGE_DERIVATION}),older(65535))))", + ), + ( + "Taproot sortedmulti_a and miniscript leaves", + "tr(@0/**,{sortedmulti_a(1,@0/<2;3>/*,@1/**),or_b(pk(@2/**),s:pk(@3/**))})", + [POLICY_KEY_0, TAPROOT_KEY_1, TAPROOT_KEY_2, TAPROOT_KEY_3], + f"tr({POLICY_KEY_0}{RECEIVE_CHANGE_DERIVATION},{{sortedmulti_a(1,{POLICY_KEY_0}{ALTERNATE_DERIVATION},{TAPROOT_KEY_1}{RECEIVE_CHANGE_DERIVATION}),or_b(pk({TAPROOT_KEY_2}{RECEIVE_CHANGE_DERIVATION}),s:pk({TAPROOT_KEY_3}{RECEIVE_CHANGE_DERIVATION}))}})", + ), + ( + "Taproot MuSig2 with recovery paths", + "tr(musig(@0,@1,@2)/**,{and_v(v:pk(musig(@0,@1)/**),older(12960)),{and_v(v:pk(musig(@0,@2)/**),older(12960)),and_v(v:pk(musig(@1,@2)/**),older(12960))}})", + [POLICY_KEY_0, POLICY_KEY_1, POLICY_KEY_2], + f"tr({musig_3_of_3}{RECEIVE_CHANGE_DERIVATION},{{and_v(v:pk({musig_0_1}{RECEIVE_CHANGE_DERIVATION}),older(12960)),{{and_v(v:pk({musig_0_2}{RECEIVE_CHANGE_DERIVATION}),older(12960)),and_v(v:pk({musig_1_2}{RECEIVE_CHANGE_DERIVATION}),older(12960))}}}})", + ), + ] + + for name, descriptor_template, keys_info, descriptor in valid_policies: + with self.subTest(name=name): + policy = BIP388Policy.from_descriptor(name, descriptor) + self.assertEqual(policy.descriptor_template, descriptor_template) + self.assertEqual(policy.keys_info, keys_info) + + def test_bip388_invalid_policy_vectors(self) -> None: + invalid_templates = [ + ("Key placeholder with no path", "pkh(@0)", 1), + ("Key placeholder with an explicit path", "pkh(@0/0/**)", 1), + ("Key placeholders out of order", "sh(multi(1,@1/**,@0/**))", 2), + ("Skipped key placeholder", "sh(multi(1,@0/**,@2/**))", 3), + ("Repeated key path", "sh(multi(1,@0/**,@0/**))", 1), + ( + "Non-disjoint multipath expressions", + "sh(multi(1,@0/<0;1>/*,@0/<1;2>/*))", + 1, + ), + ( + "Non-placeholder key", + f"sh(multi(1,@0/**,{NON_PLACEHOLDER_XPUB}{RECEIVE_CHANGE_DERIVATION}))", + 1, + ), + ("Multipath cardinality greater than two", "pkh(@0/<0;1;2>/*)", 1), + ("Derivation before MuSig2 aggregation", "tr(musig(@0/**,@1/**))", 2), + ] + + for name, descriptor_template, key_count in invalid_templates: + with self.subTest(name=name): + with self.assertRaises(BadArgumentError): + _validate_template(descriptor_template, key_count) + + def test_single_key_descriptor(self) -> None: + descriptor = f"wpkh([f5acc2fd/84h/1h/0h]{XPUB_A}{RECEIVE_CHANGE_DERIVATION})" + policy = BIP388Policy.from_descriptor("single", AddChecksum(descriptor)) + + self.assertEqual(policy.name, "single") + self.assertEqual(policy.descriptor_template, "wpkh(@0/**)") + self.assertEqual( + policy.keys_info, + [f"[f5acc2fd/84'/1'/0']{XPUB_A}"], + ) + self.assertIsNone(policy.registration) + + def test_musig_descriptor(self) -> None: + descriptor = ( + f"tr(musig([f5acc2fd/87h/1h/0h]{XPUB_A}," + f"[4c00739d/87h/1h/0h]{XPUB_B}){RECEIVE_CHANGE_DERIVATION})" + ) + policy = BIP388Policy.from_descriptor("musig", descriptor, "00" * 32) + + self.assertEqual(policy.descriptor_template, "tr(musig(@0,@1)/**)") + self.assertEqual(len(policy.keys_info), 2) + self.assertEqual(policy.registration, "00" * 32) + + def test_reused_key_with_disjoint_branches(self) -> None: + descriptor = ( + f"wsh(or_b(pk([f5acc2fd/84h/1h/0h]{XPUB_A}{RECEIVE_CHANGE_DERIVATION})," + f"s:pk([f5acc2fd/84h/1h/0h]{XPUB_A}{ALTERNATE_DERIVATION})))" + ) + policy = BIP388Policy.from_descriptor("branches", descriptor) + + self.assertEqual(len(policy.keys_info), 1) + self.assertEqual( + policy.descriptor_template, + "wsh(or_b(pk(@0/**),s:pk(@0/<2;3>/*)))", + ) + + def test_rejects_non_combined_descriptor(self) -> None: + with self.assertRaisesRegex(BadArgumentError, "Every BIP388 key placeholder"): + BIP388Policy.from_descriptor( + "receive only", + f"wpkh([f5acc2fd/84h/1h/0h]{XPUB_A}/0/*)", + ) + + def test_rejects_bad_checksum(self) -> None: + with self.assertRaisesRegex(BadArgumentError, "checksum does not match"): + BIP388Policy.from_descriptor( + "bad checksum", + f"wpkh([f5acc2fd/84h/1h/0h]{XPUB_A}{RECEIVE_CHANGE_DERIVATION})#aaaaaaaa", + ) + + def test_rejects_overlapping_key_reuse(self) -> None: + descriptor = ( + f"wsh(or_b(pk([f5acc2fd/84h/1h/0h]{XPUB_A}{RECEIVE_CHANGE_DERIVATION})," + f"s:pk([f5acc2fd/84h/1h/0h]{XPUB_A}{OVERLAPPING_DERIVATION})))" + ) + with self.assertRaisesRegex(BadArgumentError, "overlapping derivation"): + BIP388Policy.from_descriptor("overlap", descriptor) + + +if __name__ == "__main__": + unittest.main() From 74002813aea05a240fcb4691ea428bc3eb0a96a7 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Sun, 2 Aug 2026 12:01:39 +0200 Subject: [PATCH 2/4] ledger: add policy registration encoding Frame the device registration and policy name as separately length-prefixed fields before hex encoding the opaque value. Decode and validate all fields while allowing later fields to be appended. Co-authored-by: Codex (GPT-5.6 Sol) --- .github/workflows/type-check.yml | 1 + hwilib/devices/ledger_registration.py | 51 +++++++++++++++++++++++++++ test/run_tests.py | 2 ++ test/test_ledger_registration.py | 41 +++++++++++++++++++++ 4 files changed, 95 insertions(+) create mode 100644 hwilib/devices/ledger_registration.py create mode 100644 test/test_ledger_registration.py diff --git a/.github/workflows/type-check.yml b/.github/workflows/type-check.yml index 0eb6cd4fb..401ab8e27 100644 --- a/.github/workflows/type-check.yml +++ b/.github/workflows/type-check.yml @@ -32,6 +32,7 @@ jobs: hwilib/devices/__init__.py hwilib/devices/keepkey.py hwilib/devices/ledger.py + hwilib/devices/ledger_registration.py hwilib/devices/trezor.py hwilib/errors.py hwilib/_script.py diff --git a/hwilib/devices/ledger_registration.py b/hwilib/devices/ledger_registration.py new file mode 100644 index 000000000..f1ce14053 --- /dev/null +++ b/hwilib/devices/ledger_registration.py @@ -0,0 +1,51 @@ +"""Encoding helpers for opaque Ledger policy registrations.""" + +from typing import List, Sequence, Tuple + +from ..errors import BadArgumentError + + +def _encode_fields(fields: Sequence[bytes]) -> bytes: + encoded = bytearray() + for field in fields: + if len(field) > 255: + raise BadArgumentError("Ledger policy registration fields cannot exceed 255 bytes") + encoded.append(len(field)) + encoded.extend(field) + return bytes(encoded) + + +def _decode_fields(encoded: bytes) -> List[bytes]: + fields: List[bytes] = [] + offset = 0 + while offset < len(encoded): + field_length = encoded[offset] + offset += 1 + field_end = offset + field_length + if field_end > len(encoded): + raise BadArgumentError("Invalid Ledger policy registration") + fields.append(encoded[offset:field_end]) + offset = field_end + return fields + + +def encode_policy_registration(device_registration: bytes, policy_name: str) -> str: + """Encode the device registration and policy name as an opaque hex string.""" + + try: + name = policy_name.encode("latin-1") + except UnicodeEncodeError as exc: + raise BadArgumentError("Ledger policy names must use Latin-1 characters") from exc + return _encode_fields([device_registration, name]).hex() + + +def decode_policy_registration(registration: str) -> Tuple[bytes, str]: + """Decode the device registration and policy name from an opaque hex string.""" + + try: + fields = _decode_fields(bytes.fromhex(registration)) + except ValueError as exc: + raise BadArgumentError("Invalid Ledger policy registration") from exc + if len(fields) < 2: + raise BadArgumentError("Invalid Ledger policy registration") + return fields[0], fields[1].decode("latin-1") diff --git a/test/run_tests.py b/test/run_tests.py index 49d81f35b..4d190c321 100755 --- a/test/run_tests.py +++ b/test/run_tests.py @@ -14,6 +14,7 @@ from test_trezor import trezor_test_suite from test_ledger import ledger_test_suite from test_policy import TestBIP388Policy +from test_ledger_registration import TestLedgerRegistration from test_digitalbitbox import digitalbitbox_test_suite from test_keepkey import keepkey_test_suite from test_jade import jade_test_suite @@ -86,6 +87,7 @@ suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBase58)) suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBIP32)) suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBIP388Policy)) + suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestLedgerRegistration)) if sys.platform.startswith("linux"): suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestUdevRulesInstaller)) success = unittest.TextTestRunner(stream=sys.stdout, verbosity=2).run(suite).wasSuccessful() diff --git a/test/test_ledger_registration.py b/test/test_ledger_registration.py new file mode 100644 index 000000000..e9912c407 --- /dev/null +++ b/test/test_ledger_registration.py @@ -0,0 +1,41 @@ +#!/usr/bin/env python3 + +import unittest + +from hwilib.devices.ledger_registration import ( + decode_policy_registration, + encode_policy_registration, +) +from hwilib.errors import BadArgumentError + + +class TestLedgerRegistration(unittest.TestCase): + def test_round_trip(self) -> None: + registration = encode_policy_registration(b"\xaa\xbb\xcc", "Møøse") + + self.assertEqual(registration, "03aabbcc054df8f87365") + self.assertEqual( + decode_policy_registration(registration), + (b"\xaa\xbb\xcc", "Møøse"), + ) + + def test_ignores_additional_fields(self) -> None: + registration = encode_policy_registration(b"\xaa", "name") + "01ff" + + self.assertEqual(decode_policy_registration(registration), (b"\xaa", "name")) + + def test_rejects_invalid_encoding(self) -> None: + for registration in ["", "zz", "01", "02aa", "01aa"]: + with self.subTest(registration=registration): + with self.assertRaises(BadArgumentError): + decode_policy_registration(registration) + + def test_rejects_long_fields(self) -> None: + with self.assertRaises(BadArgumentError): + encode_policy_registration(b"\x00" * 256, "name") + with self.assertRaises(BadArgumentError): + encode_policy_registration(b"\x00", "a" * 256) + + +if __name__ == "__main__": + unittest.main() From e37539c3218121f4184171cf2df3bac6637f98eb Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Sat, 1 Aug 2026 21:22:46 +0200 Subject: [PATCH 3/4] Add register command for BIP388 policies Accept a policy name and combined multipath output descriptor, convert it to the BIP388 template and key vector, and register it with the device. Ledger already supports BIP388 wallet policy registration internally. Expose that existing support through the generic command and return its registration value as opaque data. Co-authored-by: Codex (GPT-5.6 Sol) --- hwilib/_cli.py | 11 +++++++++++ hwilib/commands.py | 11 +++++++++++ hwilib/devices/ledger.py | 20 ++++++++++++++++++++ hwilib/hwwclient.py | 16 +++++++++++++++- test/data/speculos-automation.json | 2 +- test/test_device.py | 27 +++++++++++++++++++++++++++ test/test_ledger.py | 11 +++++++++++ 7 files changed, 96 insertions(+), 2 deletions(-) diff --git a/hwilib/_cli.py b/hwilib/_cli.py index e0afa7dd2..040de08cc 100644 --- a/hwilib/_cli.py +++ b/hwilib/_cli.py @@ -12,6 +12,7 @@ getdescriptors, prompt_pin, toggle_passphrase, + register, restore_device, send_pin, setup_device, @@ -24,6 +25,7 @@ AddressType, Chain, ) +from .policy import BIP388Policy from .errors import ( handle_errors, DEVICE_CONN_ERROR, @@ -59,6 +61,10 @@ def backup_device_handler(args: argparse.Namespace, client: HardwareWalletClient 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 register_handler(args: argparse.Namespace, client: HardwareWalletClient) -> Dict[str, Optional[str]]: + policy = BIP388Policy.from_descriptor(name=args.name, descriptor=args.desc) + return register(client, bip388_policy=policy) + 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) @@ -197,6 +203,11 @@ def get_parser() -> HWIArgumentParser: displayaddr_parser.add_argument("--addr-type", help="The address type to display", type=AddressType.argparse, choices=list(AddressType), default=AddressType.WIT) # type: ignore displayaddr_parser.set_defaults(func=displayaddress_handler) + register_parser = subparsers.add_parser('register', help='Register a BIP388 wallet policy') + register_parser.add_argument('--name', help='Name for the policy', required=True) + register_parser.add_argument('--desc', help='Combined multipath output descriptor', required=True) + register_parser.set_defaults(func=register_handler) + setupdev_parser = subparsers.add_parser('setup', help='Setup a device. Passphrase protection uses the password given by -p. Requires interactive mode') setupdev_parser.add_argument('--label', '-l', help='The name to give to the device', default='') setupdev_parser.add_argument('--backup_passphrase', '-b', help='The passphrase to use for the backup, if applicable', default='') diff --git a/hwilib/commands.py b/hwilib/commands.py index 6d192aa5f..7f88065e2 100644 --- a/hwilib/commands.py +++ b/hwilib/commands.py @@ -55,6 +55,7 @@ Chain, ) from .hwwclient import HardwareWalletClient +from .policy import BIP388Policy from .psbt import PSBT from itertools import count @@ -494,6 +495,16 @@ def displayaddress( return {"address": client.display_singlesig_address(pubkey.get_full_derivation_path(0), addr_type)} raise BadArgumentError("Missing both path and descriptor") +def register( + client: HardwareWalletClient, + bip388_policy: BIP388Policy, +) -> Dict[str, Optional[str]]: + """Register a BIP388 policy on the device.""" + + if bip388_policy.registration is not None: + raise BadArgumentError("A policy being registered cannot already have a registration") + return {"registration": client.register_bip388_policy(bip388_policy)} + def setup_device(client: HardwareWalletClient, label: str = "", backup_passphrase: str = "") -> Dict[str, bool]: """ Setup a device that has not yet been initialized. diff --git a/hwilib/devices/ledger.py b/hwilib/devices/ledger.py index fdb6b6d82..6239a4e36 100644 --- a/hwilib/devices/ledger.py +++ b/hwilib/devices/ledger.py @@ -33,6 +33,8 @@ AddressType, Chain, ) +from ..policy import BIP388Policy +from .ledger_registration import encode_policy_registration from .ledger_bitcoin.client import ( createClient, NewClient, @@ -482,6 +484,24 @@ def format_key_info(pubkey: PubkeyProvider) -> str: return self.client.get_wallet_address(multisig_wallet, registered_hmac, change, address_index, True) + @ledger_exception + def register_bip388_policy( + self, + bip388_policy: BIP388Policy, + ) -> Optional[str]: + if isinstance(self.client, LegacyClient): + raise BadArgumentError( + "Registering a BIP388 policy is not supported by this version of the Bitcoin App" + ) + + wallet_policy = WalletPolicy( + name=bip388_policy.name, + descriptor_template=bip388_policy.descriptor_template, + keys_info=bip388_policy.keys_info, + ) + _, registration = self.client.register_wallet(wallet_policy) + return encode_policy_registration(registration, bip388_policy.name) + def setup_device(self, label: str = "", passphrase: str = "") -> bool: """ Ledgers do not support setup via software. diff --git a/hwilib/hwwclient.py b/hwilib/hwwclient.py index 565afcf44..ae9104dbd 100644 --- a/hwilib/hwwclient.py +++ b/hwilib/hwwclient.py @@ -17,7 +17,11 @@ get_bip44_chain, ) from .psbt import PSBT -from .common import AddressType, Chain +from .common import ( + AddressType, + Chain, +) +from .policy import BIP388Policy class HardwareWalletClient(object): @@ -135,6 +139,16 @@ def display_multisig_address( raise NotImplementedError("The HardwareWalletClient base class " "does not implement this method") + def register_bip388_policy( + self, + bip388_policy: BIP388Policy, + ) -> Optional[str]: + """Register a BIP388 policy and return an opaque registration, if any.""" + + raise NotImplementedError( + "This device does not support BIP388 policy registration or it is not yet implemented" + ) + def wipe_device(self) -> bool: """ Wipe the device. diff --git a/test/data/speculos-automation.json b/test/data/speculos-automation.json index 31f69f72a..80af21109 100644 --- a/test/data/speculos-automation.json +++ b/test/data/speculos-automation.json @@ -28,7 +28,7 @@ ] }, { - "regexp": "^(Address|Review|Amount|Fee|Confirm|The derivation|Derivation path|Reject if|The change path|Change path|Register wallet|Policy map|Key|Path|Public key|Spend from|Wallet name|Wallet policy|Descriptor template|Verify Bitcoin|Output|Warning).*", + "regexp": "^(Address|Review|Account name|Amount|Fee|Confirm|The derivation|Derivation path|Reject if|The change path|Change path|Register wallet|Policy map|Key|Our key|Path|Public key|Spend from|Wallet name|Wallet policy|Descriptor template|Verify Bitcoin|Output|Warning).*", "actions": [ [ "button", 2, true ], [ "button", 2, false ] diff --git a/test/test_device.py b/test/test_device.py index abc6ef1ae..62d07ff17 100644 --- a/test/test_device.py +++ b/test/test_device.py @@ -261,6 +261,33 @@ def test_type_only_autodetect(self): self.assertEqual(gmxp_res['error'], 'Unknown device type specified') self.assertEqual(gmxp_res['code'], -4) +class TestPolicyRegistration(DeviceTestCase): + def __init__(self, *args, returns_registration, **kwargs): + super().__init__(*args, **kwargs) + self.returns_registration = returns_registration + + def assert_registration(self, registration): + self.assertRegex(registration, r"^(?:[0-9a-f]{2})+$") + + def test_register_policy(self): + account_path = "m/48h/1h/0h/2h" + account_xpub = self.do_command(self.dev_args + ["getxpub", account_path])["xpub"] + descriptor = ( + f"wsh(pk([{self.emulator.fingerprint}/48h/1h/0h/2h]" + f"{account_xpub}" + "/<0;1>/*))" + ) + result = self.do_command( + self.dev_args + ["register", "--name", "HWI policy", "--desc", descriptor] + ) + + self.assertNotIn("error", result) + self.assertIn("registration", result) + if self.returns_registration: + self.assert_registration(result["registration"]) + else: + self.assertIsNone(result["registration"]) + class TestGetKeypool(DeviceTestCase): def setUp(self): super().setUp() diff --git a/test/test_ledger.py b/test/test_ledger.py index 6ab162e74..e48028897 100755 --- a/test/test_ledger.py +++ b/test/test_ledger.py @@ -17,11 +17,13 @@ TestDisplayAddress, TestGetKeypool, TestGetDescriptors, + TestPolicyRegistration, TestSignMessage, TestSignTx, ) from hwilib._cli import process_commands +from hwilib.devices.ledger_registration import decode_policy_registration class LedgerEmulator(DeviceEmulator): def __init__(self, path, legacy=False): @@ -164,6 +166,13 @@ def test_getxpub(self): self.assertEqual(result['chaincode'], "1067f2a53975faf7ac265be505c1c50ef80a0dcbe1f53f50497c5618e8888dbd") self.assertEqual(result['pubkey'], "035879ca173a9c1b3f300ec587fb4cc6d54d618e30584e425c1b53b98828708f1d") +class TestLedgerPolicyRegistration(TestPolicyRegistration): + def assert_registration(self, registration): + super().assert_registration(registration) + device_registration, policy_name = decode_policy_registration(registration) + self.assertNotEqual(device_registration, b"") + self.assertEqual(policy_name, "HWI policy") + def ledger_test_suite(emulator, bitcoind, interface, legacy=False): dev_emulator = LedgerEmulator(emulator, legacy) @@ -186,6 +195,8 @@ def ledger_test_suite(emulator, bitcoind, interface, legacy=False): suite.addTest(DeviceTestCase.parameterize(TestGetDescriptors, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestGetKeypool, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestDisplayAddress, bitcoind, emulator=dev_emulator, interface=interface)) + if not legacy: + suite.addTest(DeviceTestCase.parameterize(TestLedgerPolicyRegistration, bitcoind, emulator=dev_emulator, interface=interface, returns_registration=True)) suite.addTest(DeviceTestCase.parameterize(TestSignMessage, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestSignTx, bitcoind, emulator=dev_emulator, interface=interface, signtx_cases=signtx_cases)) From 49b009dfdde499d8dc83578a0708beddceb7f87f Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Sat, 1 Aug 2026 21:22:50 +0200 Subject: [PATCH 4/4] bitbox02: support BIP388 policy registration Co-authored-by: Codex (GPT-5.6 Sol) --- hwilib/devices/bitbox02.py | 60 +++++++++++++++++++++++++++++++++++++- test/test_bitbox02.py | 2 ++ 2 files changed, 61 insertions(+), 1 deletion(-) diff --git a/hwilib/devices/bitbox02.py b/hwilib/devices/bitbox02.py index cc6b783b3..288f83d44 100644 --- a/hwilib/devices/bitbox02.py +++ b/hwilib/devices/bitbox02.py @@ -23,7 +23,7 @@ from functools import wraps from .._base58 import decode_check, encode_check -from ..descriptor import MultisigDescriptor +from ..descriptor import MultisigDescriptor, PubkeyProvider from ..hwwclient import HardwareWalletClient from ..key import ExtendedKey from .._script import ( @@ -59,6 +59,7 @@ AddressType, Chain, ) +from ..policy import BIP388Policy import hid @@ -438,6 +439,63 @@ def _maybe_register_script_config( xpub_type=bitbox02.btc.BTCRegisterScriptConfigRequest.AUTO_XPUB_TPUB, ) + def _bip388_script_config( + self, + bip388_policy: BIP388Policy, + ) -> Tuple[bitbox02.btc.BTCScriptConfig, Sequence[int]]: + device_fingerprint = self.get_master_fingerprint() + our_keypath: Optional[Sequence[int]] = None + keys = [] + + for key_info in bip388_policy.keys_info: + pubkey = PubkeyProvider.parse(key_info) + if pubkey.extkey is None or pubkey.extkey.is_private or pubkey.deriv_path is not None: + raise BadArgumentError("Invalid BIP388 key information") + + origin = pubkey.origin + keys.append( + bitbox02.common.KeyOriginInfo( + root_fingerprint=b"" if origin is None else origin.fingerprint, + keypath=[] if origin is None else origin.path, + xpub=util.parse_xpub(pubkey.extkey.to_string()), + ) + ) + + if origin is not None and origin.fingerprint == device_fingerprint: + device_xpub = decode_check(self._get_xpub(origin.path)) + if _xpubs_equal_ignoring_version(device_xpub, pubkey.extkey.serialize()): + if our_keypath is not None: + raise BadArgumentError("This BitBox02 occurs more than once in the policy") + our_keypath = origin.path + + if our_keypath is None: + raise BadArgumentError("This BitBox02 is not one of the policy keys") + + return ( + bitbox02.btc.BTCScriptConfig( + policy=bitbox02.btc.BTCScriptConfig.Policy( + policy=bip388_policy.descriptor_template, + keys=keys, + ) + ), + our_keypath, + ) + + @bitbox02_exception + def register_bip388_policy( + self, + bip388_policy: BIP388Policy, + ) -> Optional[str]: + script_config, keypath = self._bip388_script_config(bip388_policy) + self.init().btc_register_script_config( + coin=self._get_coin(), + script_config=script_config, + keypath=keypath, + name=bip388_policy.name, + xpub_type=bitbox02.btc.BTCRegisterScriptConfigRequest.AUTO_XPUB_TPUB, + ) + return None + def _multisig_scriptconfig( self, threshold: int, diff --git a/test/test_bitbox02.py b/test/test_bitbox02.py index a9d64b999..ef62fa377 100644 --- a/test/test_bitbox02.py +++ b/test/test_bitbox02.py @@ -18,6 +18,7 @@ TestDisplayAddress, TestGetKeypool, TestGetDescriptors, + TestPolicyRegistration, TestSignTx, ) @@ -124,6 +125,7 @@ def bitbox02_test_suite(simulator, bitcoind, interface): suite.addTest(DeviceTestCase.parameterize(TestGetDescriptors, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestSignTx, bitcoind, emulator=dev_emulator, interface=interface, signtx_cases=signtx_cases)) suite.addTest(DeviceTestCase.parameterize(TestDisplayAddress, bitcoind, emulator=dev_emulator, interface=interface)) + suite.addTest(DeviceTestCase.parameterize(TestPolicyRegistration, bitcoind, emulator=dev_emulator, interface=interface, returns_registration=False)) # TestSignMessage is removed, since its only testcase is for legacy p2pkh, which is not supported by BitBox02 # suite.addTest(DeviceTestCase.parameterize(TestSignMessage, bitcoind, emulator=dev_emulator, interface=interface)) suite.addTest(DeviceTestCase.parameterize(TestBitbox02GetXpub, bitcoind, emulator=dev_emulator, interface=interface))