Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
4c8b6c7
coldcard: improve return type annotations
Sjors Aug 6, 2026
416ef03
ledger: decode MuSig2 signing yields
Sjors Aug 24, 2026
95ed48b
ledger: decode compressed MuSig2 aggregate pubkeys
Sjors Aug 24, 2026
6d01fb8
ledger: parse unknown sign_psbt yield tags
Sjors Aug 24, 2026
3cbd7fb
descriptor: tighten key expression parsing
Sjors Aug 24, 2026
d1f6442
descriptor: deduplicate BIP 388 key information
Sjors Aug 24, 2026
925b4ac
descriptor: split BIP 388 placeholder checks from serialization
Sjors Aug 24, 2026
1cfc828
descriptor: parse tr() internal key with _get_expr
Sjors Aug 24, 2026
5c8a38a
descriptor: parse Segwit Miniscript policies
Sjors Aug 24, 2026
6a51e26
test: display Segwit Miniscript addresses
Sjors Aug 24, 2026
6f9d5bc
descriptor: parse tapscript Miniscript policies
Sjors Aug 24, 2026
fa04228
displayaddress: require registration for taproot script trees
Sjors Aug 24, 2026
271ff36
test: display taproot Miniscript addresses
Sjors Aug 24, 2026
ca300b3
descriptor: support musig() aggregate keys
Sjors Aug 24, 2026
3ecbb06
displayaddress: require registration for musig()
Sjors Aug 24, 2026
8ea09f3
test: display MuSig2 addresses
Sjors Aug 24, 2026
e6dc37a
descriptor: allow musig() keys in tapscript Miniscript
Sjors Aug 24, 2026
35588fe
test: display MuSig2 Miniscript addresses
Sjors Aug 24, 2026
58aefcd
Merge bitcoin-core/HWI#851: musig2 device plumbing
Sjors Aug 26, 2026
0d8edca
Merge bitcoin-core/HWI#852: Display musig2 miniscript addresses
Sjors Aug 26, 2026
dfdaed3
coldcard: recognize MuSig2 signing data
Sjors Aug 24, 2026
828469b
ledger: sign MuSig2
Sjors Sep 5, 2025
1b65916
ci: build Bitcoin Core from MuSig2 branch
Sjors Jul 3, 2026
db37784
test: add Ledger MuSig2 device test
Sjors Aug 18, 2026
df1977a
test: exercise MuSig2 device recovery path
Sjors Aug 18, 2026
c23a442
test: add Coldcard Edge MuSig2 coverage
Sjors Aug 18, 2026
5f799a1
test: add MuSig2 device interoperability
Sjors Aug 18, 2026
316ebf0
docs: add MuSig2 walkthrough
Sjors Aug 7, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -232,6 +232,45 @@ jobs:
runs-on: ubuntu-latest
python_versions: '["3.14"]'

test-interoperability:
name: Python 3.14 interoperability cli
runs-on: ubuntu-latest
timeout-minutes: 45
needs: [sim-builder-coldcard-edge, sim-builder-ledger, ledger-app-builder, bitcoind-builder]
container: python:3.14
steps:
- uses: actions/checkout@v7

- run: |
pip install poetry
poetry install

- uses: actions/download-artifact@v8
with:
name: bitcoind

- run: |
tar -xvf bitcoind.tar.gz

- name: Install Coldcard Edge simulator
uses: ./.github/actions/install-sim
with:
device: coldcard-edge

- name: Install Ledger simulator
uses: ./.github/actions/install-sim
with:
device: ledger

- name: Run interoperability test
run: |
cd test
poetry run python test_interoperability.py --interface=cli

- if: failure()
run: |
tail -v -n +1 test/*-emulator.std* || true

test-bitbox01:
uses: ./.github/workflows/device-test.yml
needs: [sim-builder-bitbox, bitcoind-builder, dist-builder]
Expand Down
1 change: 1 addition & 0 deletions docs/examples/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@ Example Usage

bitcoin-core-usage
examples
musig2
walkthrough/walkthrough
109 changes: 109 additions & 0 deletions docs/examples/musig2.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
MuSig2 With Bitcoin Core And HWI
================================

This walkthrough describes the HWI side of a 2-of-2 MuSig2 wallet where
cosigner A is a hardware wallet and cosigner B is a hot key in the same
Bitcoin Core wallet. It assumes a Bitcoin Core build with ``tr(musig(...))``
descriptors and external-signer descriptor registration support.

The hardware wallet can be a Ledger or a Coldcard Edge. MuSig2 uses Taproot,
which is supported by the Edge firmware but not by the standard Coldcard
firmware.

Get The Hardware Wallet Key
---------------------------

Use BIP87 account keys for MuSig2. For test networks the account path is
``m/87h/1h/0h``:

.. code-block:: bash

./hwi.py --chain test --fingerprint "$FP_A" getxpub "m/87h/1h/0h"

Build the key expression with origin information:

.. code-block:: bash

COSIGNER_A_KEY="[${FP_A}/87h/1h/0h]tpub..."

Create the Core wallet with ``external_signer=true``,
``disable_private_keys=false``, and ``blank=true``. Add cosigner B's hot HD key
to that wallet, derive its BIP87 account xpub, and build a descriptor like:

.. code-block:: bash

DESC_NO_CKSUM="tr(musig(${COSIGNER_A_KEY},${COSIGNER_B_KEY})/<0;1>/*)"

Register The Descriptor
-----------------------

Bitcoin Core's ``registerdescriptor`` RPC derives the ordinary multipath
descriptor from the wallet's active receive and change descriptors and passes
it to HWI. The equivalent direct HWI command is:

.. code-block:: bash

./hwi.py --chain test --fingerprint "$FP_A" registerdescriptor \
MuSigTest "$DESC_NO_CKSUM"

The result contains an opaque serialized registration. Bitcoin Core stores it
unchanged and supplies it to HWI when displaying addresses or signing:

.. code-block:: json

{"registration":"..."}

On Ledger, this registration includes data that authenticates the policy to
the device. Coldcard Edge instead stores the named policy on the device during
registration. In either case, applications should treat the serialized value
as opaque and reuse it unchanged. Confirm the policy on the hardware wallet
before accepting the registration.

Display A Registered Address
----------------------------

For registered descriptors, Bitcoin Core's ``walletdisplayaddress`` invokes
HWI with the stored registration instead of passing a single-address
descriptor:

.. code-block:: bash

./hwi.py --chain test --fingerprint "$FP_A" displayaddress \
--registration "$REGISTRATION" \
--index 0

Use ``--change`` to display the change branch for the same index. HWI returns
the address reported by the device:

.. code-block:: json

{
"address": "tb1p...",
"index": 0,
"change": false
}

Coldcard Edge looks up the policy stored under its registration name, then
derives the requested branch and index. Ledger reconstructs the registered
policy from the serialized registration. Both devices display the resulting
address for confirmation.

Sign
----

Core invokes HWI's ``signtx`` with the same opaque registration:

.. code-block:: bash

./hwi.py --chain test --fingerprint "$FP_A" signtx "$PSBT" \
--registration "$REGISTRATION"

MuSig2 signing has two rounds. When the coordinating wallet has another
cosigner locally, Bitcoin Core can run both rounds inside one ``send`` call:
first HWI yields the hardware wallet's public nonce, then Core adds the hot
cosigner's nonce and partial signature, and finally HWI yields the hardware
wallet's partial signature. The returned PSBT is then ready for finalization
by Core.

Coldcard Edge and Ledger both accept PSBT version 2, so HWI can combine their
independent updates without first converting the PSBT.
5 changes: 5 additions & 0 deletions hwilib/commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
RegisteredDescriptor,
parse_descriptor,
MultisigDescriptor,
MusigPubkeyProvider,
TRDescriptor,
PKHDescriptor,
PubkeyProvider,
Expand Down Expand Up @@ -511,7 +512,11 @@ def displayaddress(
return {"address": client.display_multisig_address(addr_type, descriptor)}
is_wpkh = isinstance(descriptor, WPKHDescriptor)
if isinstance(descriptor, PKHDescriptor) or is_wpkh or isinstance(descriptor, TRDescriptor):
if descriptor.subdescriptors:
raise BadArgumentError("tr() descriptors with a script tree require a registered BIP 388 policy; use --registration")
pubkey = descriptor.pubkeys[0]
if isinstance(pubkey, MusigPubkeyProvider):
raise BadArgumentError("musig() addresses require a registered BIP 388 policy; use --registration")
if pubkey.origin is None:
raise BadArgumentError(f"Descriptor missing origin info: {desc}")
if pubkey.origin.fingerprint != client.get_master_fingerprint():
Expand Down
Loading
Loading