test_utils: deduplicate the musig2 key aggregation helpers
What changed, and why it matters
This commit is a code cleanup in the project's test utilities. It removes duplicated helper functions for MuSig2 key aggregation and moves them into a single shared file. There is no change to the actual Ledger Bitcoin app firmware or to how cryptographic operations are performed. It is purely a refactoring of test-only Python code.
No security action required. Treat as routine refactoring of test infrastructure.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The commit deduplicates test utility code across test_utils/musig2.py, test_utils/txmaker.py, and test_utils/wallet_policy.py. Functions such as tapleaf_hash, unsorted_musig, musig, aggregate_musig_pubkey, derive_from_key_info, and derive_plain_descriptor are consolidated into wallet_policy.py, with musig2.py re-exporting them for backward compatibility. The BIP-328 chaincode constant is also shared via wallet_policy.BIP328_CHAINCODE. The behavior of the helpers is preserved, including the sorting of public keys in musig() and the construction of the synthetic BIP-328 xpub. No firmware code, no transaction parsing, and no cryptographic protocol logic in the app itself is modified.
Changed components
test_utils/musig2.pytest_utils/txmaker.pytest_utils/wallet_policy.pyInspect captured patch +57 / −149
### test_utils/musig2.py
@@ -19,12 +19,10 @@
import hashlib
import hmac
from io import BytesIO
-import re
-from re import Match
import secrets
import struct
-from typing import Dict, Iterable, Iterator, List, Optional, Set, Tuple, Union
+from typing import Dict, Iterator, List, Optional, Tuple, Union
from abc import ABC, abstractmethod
import sys
@@ -34,8 +32,6 @@
if _REPO_ROOT not in sys.path:
sys.path.insert(0, _REPO_ROOT)
-import base58
-
from test_utils.taproot_sighash import SIGHASH_DEFAULT, TaprootSignatureHash
from test_utils import bip0327, bip0340, hash160, sha256
from test_utils import taproot
@@ -44,6 +40,13 @@
MuSig2KeyPlaceholder,
KeyPlaceholder,
extract_placeholders,
+ # the musig() helpers below are also re-exported from this module
+ aggregate_musig_pubkey,
+ derive_from_key_info,
+ derive_plain_descriptor,
+ musig,
+ tapleaf_hash,
+ unsorted_musig,
)
from bitcoin_client.ledger_bitcoin._embit.descriptor.miniscript import Miniscript
@@ -55,122 +58,6 @@
HARDENED_INDEX = 0x80000000
-def tapleaf_hash(script: Optional[bytes], leaf_version=b'\xC0') -> Optional[bytes]:
- if script is None:
- return None
- return taproot.tagged_hash(
- "TapLeaf",
- leaf_version + taproot.ser_script(script)
- )
-
-
-
-
-def unsorted_musig(pubkeys: Iterable[bytes], version_bytes: bytes) -> Tuple[str, bip0327.KeyAggContext]:
- """
- Constructs the musig2 aggregated extended public key from an unsorted list of
- compressed public keys, and the version bytes.
- """
-
- assert all(len(pk) == 33 for pk in pubkeys)
- assert len(version_bytes) == 4
-
- depth = b'\x00'
- fingerprint = b'\x00\x00\x00\x00'
- child_number = b'\x00\x00\x00\x00'
-
- key_agg_ctx = bip0327.key_agg(pubkeys)
- Q = key_agg_ctx.Q
- compressed_pubkey = (
- b'\x02' if Q[1] % 2 == 0 else b'\x03') + bip0327.get_xonly_pk(key_agg_ctx)
- chaincode = bytes.fromhex(
- "868087ca02a6f974c4598924c36b57762d32cb45717167e300622c7167e38965")
- ext_pubkey = version_bytes + depth + fingerprint + \
- child_number + chaincode + compressed_pubkey
- return base58.b58encode_check(ext_pubkey).decode(), key_agg_ctx
-
-
-def musig(pubkeys: Iterable[bytes], version_bytes: bytes) -> Tuple[str, bip0327.KeyAggContext]:
- """
- Constructs the musig2 aggregated extended public key from a list of compressed public keys,
- and the version bytes. The keys are sorted, as required by the `the musig()` key expression
- in descriptors.
- """
- return unsorted_musig(sorted(pubkeys), version_bytes)
-
-
-def aggregate_musig_pubkey(keys_info: Iterable[str]) -> Tuple[str, bip0327.KeyAggContext]:
- """
- Constructs the musig2 aggregated extended public key from the list of keys info
- of the participating keys.
- """
-
- pubkeys: list[bytes] = []
- versions: Set[str] = set()
- for ki in keys_info:
- start = ki.find(']')
- xpub = ki[start + 1:]
- xpub_bytes = base58.b58decode_check(xpub)
- versions.add(xpub_bytes[:4])
- pubkeys.append(xpub_bytes[-33:])
-
- if len(versions) > 1:
- raise ValueError(
- "All the extended public keys should be from the same network")
-
- return musig(pubkeys, versions.pop())
-
-
-def derive_from_key_info(key_info: str, steps: List[int]) -> str:
- start = key_info.find(']')
- pk = ExtendedKey.deserialize(key_info[start + 1:])
- return pk.derive_pub_path(steps).to_string()
-
-
-def derive_plain_descriptor(desc_tmpl: str, keys_info: List[str], is_change: bool, address_index: int):
- """
- Given a wallet policy, and the change/address_index combination, computes the corresponding descriptor.
- It replaces /** with /<0;1>/*
- It also replaces each musig() key expression with the corresponding xpub.
- The resulting descriptor can be used with descriptor libraries that do not support musig or wallet policies.
- """
-
- desc_tmpl = desc_tmpl.replace("/**", "/<0;1>/*")
- desc_tmpl = desc_tmpl.replace("*", str(address_index))
-
- # Replace each <M;N> with M if is_change is False, otherwise with N
- def replace_m_n(match: Match[str]):
- m, n = match.groups()
- return m if not is_change else n
-
- desc_tmpl = re.sub(r'<([^;]+);([^>]+)>', replace_m_n, desc_tmpl)
-
- # Replace musig(...) expressions
- def replace_musig(match: Match[str]):
- musig_content = match.group(1)
- steps = [int(x) for x in match.group(2).split("/")]
-
- assert len(steps) == 2
-
- key_indexes = [int(i.strip('@')) for i in musig_content.split(',')]
- key_infos = [keys_info[i] for i in key_indexes]
- agg_xpub = aggregate_musig_pubkey(key_infos)[0]
-
- return derive_from_key_info(agg_xpub, steps)
-
- desc_tmpl = re.sub(r'musig\(([^)]+)\)/(\d+/\d+)', replace_musig, desc_tmpl)
-
- # Replace @i/a/b with the i-th element in keys_info, deriving the key appropriately
- # to get a plain xpub
- def replace_key_index(match):
- index, step1, step2 = [int(x) for x in match.group(1).split('/')]
- return derive_from_key_info(keys_info[index], [step1, step2])
-
- desc_tmpl = re.sub(r'@(\d+/\d+/\d+)', replace_key_index, desc_tmpl)
-
- return desc_tmpl
-
-
class Tree:
"""
Recursive structure that represents a taptree, or one of its subtrees.
### test_utils/txmaker.py
@@ -32,15 +32,7 @@
from bitcoin_client.ledger_bitcoin._embit.descriptor.miniscript import Miniscript
from test_utils import bip0340, sha256, hash160
from test_utils.bip0327 import cbytes, key_agg
-from test_utils.wallet_policy import DescriptorTemplate, KeyPlaceholder, MuSig2KeyPlaceholder, PlainKeyPlaceholder, ShDescriptorTemplate, ShWpkhDescriptorTemplate, ShWshDescriptorTemplate, TrDescriptorTemplate, WshDescriptorTemplate, WpkhDescriptorTemplate, PkhDescriptorTemplate, derive_plain_descriptor, tapleaf_hash
-
-
-# BIP-328 chaincode used by BIP-388 to derive a synthetic xpub from an
-# aggregated musig2 public key. Pinned constant; see the reference
-# implementation in bitcoin_client.ledger_bitcoin.client.aggr_xpub.
-_BIP328_CHAINCODE = bytes.fromhex(
- "868087ca02a6f974c4598924c36b57762d32cb45717167e300622c7167e38965"
-)
+from test_utils.wallet_policy import BIP328_CHAINCODE, DescriptorTemplate, KeyPlaceholder, MuSig2KeyPlaceholder, PlainKeyPlaceholder, ShDescriptorTemplate, ShWpkhDescriptorTemplate, ShWshDescriptorTemplate, TrDescriptorTemplate, WshDescriptorTemplate, WpkhDescriptorTemplate, PkhDescriptorTemplate, derive_plain_descriptor, tapleaf_hash
def _musig_root_aggregate(placeholder: MuSig2KeyPlaceholder, keys_info: List[str]) -> Tuple[bytes, List[bytes]]:
@@ -257,7 +249,7 @@ def get_placeholder_root_key(placeholder: KeyPlaceholder, keys_info: List[str])
0,
b"\x00\x00\x00\x00",
0,
- _BIP328_CHAINCODE,
+ BIP328_CHAINCODE,
None,
aggregated_pubkey,
)
### test_utils/wallet_policy.py
@@ -9,7 +9,7 @@
from dataclasses import dataclass
from io import BytesIO
import re
-from typing import Iterator, List, Optional, Tuple, Type, Union
+from typing import Iterable, Iterator, List, Optional, Set, Tuple, Type, Union
_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
if _REPO_ROOT not in sys.path:
@@ -20,35 +20,64 @@
from bitcoin_client.ledger_bitcoin._embit.descriptor.miniscript import Miniscript
from bitcoin_client.ledger_bitcoin.key import ExtendedKey
from test_utils.taproot import ser_script, tagged_hash
-from test_utils.bip0327 import get_xonly_pk, key_agg
+from test_utils import bip0327
-# BIP-328 chaincode used to derive a synthetic xpub from an aggregated musig2 public key.
-_BIP328_CHAINCODE = bytes.fromhex(
+# BIP-328 chaincode of the synthetic xpub derived from an aggregated musig2 public key.
+BIP328_CHAINCODE = bytes.fromhex(
"868087ca02a6f974c4598924c36b57762d32cb45717167e300622c7167e38965")
-def aggregate_musig_pubkey(keys_info: List[str]) -> str:
- """Returns the BIP-328 synthetic extended public key (as a string) aggregating the
- participant keys of a musig() key expression, sorted as required by descriptors."""
- pubkeys: List[bytes] = []
- versions = set()
+def unsorted_musig(pubkeys: Iterable[bytes], version_bytes: bytes) -> Tuple[str, bip0327.KeyAggContext]:
+ """
+ Constructs the musig2 aggregated extended public key from an unsorted list of
+ compressed public keys, and the version bytes.
+ """
+
+ assert all(len(pk) == 33 for pk in pubkeys)
+ assert len(version_bytes) == 4
+
+ depth = b'\x00'
+ fingerprint = b'\x00\x00\x00\x00'
+ child_number = b'\x00\x00\x00\x00'
+
+ key_agg_ctx = bip0327.key_agg(pubkeys)
+ Q = key_agg_ctx.Q
+ compressed_pubkey = (
+ b'\x02' if Q[1] % 2 == 0 else b'\x03') + bip0327.get_xonly_pk(key_agg_ctx)
+ ext_pubkey = version_bytes + depth + fingerprint + \
+ child_number + BIP328_CHAINCODE + compressed_pubkey
+ return base58.b58encode_check(ext_pubkey).decode(), key_agg_ctx
+
+
+def musig(pubkeys: Iterable[bytes], version_bytes: bytes) -> Tuple[str, bip0327.KeyAggContext]:
+ """
+ Constructs the musig2 aggregated extended public key from a list of compressed public keys,
+ and the version bytes. The keys are sorted, as required by the `musig()` key expression
+ in descriptors.
+ """
+ return unsorted_musig(sorted(pubkeys), version_bytes)
+
+
+def aggregate_musig_pubkey(keys_info: Iterable[str]) -> Tuple[str, bip0327.KeyAggContext]:
+ """
+ Constructs the musig2 aggregated extended public key from the list of keys info
+ of the participating keys.
+ """
+
+ pubkeys: list[bytes] = []
+ versions: Set[bytes] = set()
for ki in keys_info:
- xpub = ki[ki.find(']') + 1:]
+ start = ki.find(']')
+ xpub = ki[start + 1:]
xpub_bytes = base58.b58decode_check(xpub)
versions.add(xpub_bytes[:4])
pubkeys.append(xpub_bytes[-33:])
if len(versions) > 1:
raise ValueError(
"All the extended public keys should be from the same network")
- version_bytes = versions.pop()
- keyagg_ctx = key_agg(sorted(pubkeys))
- Q = keyagg_ctx.Q
- compressed_pubkey = (b'\x02' if Q[1] % 2 == 0 else b'\x03') + get_xonly_pk(keyagg_ctx)
- ext_pubkey = (version_bytes + b'\x00' + b'\x00\x00\x00\x00' + b'\x00\x00\x00\x00' +
- _BIP328_CHAINCODE + compressed_pubkey)
- return base58.b58encode_check(ext_pubkey).decode()
+ return musig(pubkeys, versions.pop())
def tapleaf_hash(script: Optional[bytes], leaf_version=b'\xC0') -> Optional[bytes]:
@@ -143,7 +172,7 @@ def replace_musig(match: re.Match[str]):
key_indexes = [int(i.strip('@')) for i in match.group(1).split(',')]
steps = [int(x) for x in match.group(2).split("/")]
assert len(steps) == 2
- agg_xpub = aggregate_musig_pubkey([keys_info[i] for i in key_indexes])
+ agg_xpub = aggregate_musig_pubkey([keys_info[i] for i in key_indexes])[0]
return derive_from_key_info(agg_xpub, steps)
desc_tmpl = re.sub(r'musig\(([^)]+)\)/(\d+/\d+)', replace_musig, desc_tmpl)Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.