python client: first-class MUSIG2_SESSION_ID field
What changed, and why it matters
This commit adds support in Ledger's Python PSBT library for a new optional metadata field called MUSIG2_SESSION_ID. It is a preparatory client-side change for upcoming MuSig2 multi-signature features. The commit does not change any device firmware, cryptographic operations, or security-critical logic; it only lets the Python client recognize, parse, and serialize this new PSBT field correctly.
No security action required; treat as a normal feature addition. Review the upcoming commits that will consume this field to assess MuSig2 session-management security implications.
Security signals we found
No security-relevant behavior change: purely additive client-side PSBT field support
Duplicate-key check follows existing PSBT parsing pattern
Field is explicitly documented as not part of the transaction and signer-specific
No firmware, signing, or key-handling code is modified
Evidence from the diff
The patch introduces a first-class PSBT.musig2_session_id attribute in ledger_bitcoin/psbt.py, backed by a BIP-174 proprietary global key with identifier ‘MUSIG2_SESSION_ID’, subtype 0, and no keydata. Serialization and deserialization paths are updated to handle the field, with duplicate-key detection. A new test file verifies round-tripping across PSBT v0/v2, fallback parsing from unknown fields, and rejection of duplicate keys. The change is additive and entirely within the Python client code.
Changed components
bitcoin_client/ledger_bitcoin/psbt.pybitcoin_client/tests/test_psbt_musig2_session_id.pyInspect captured patch +98 / −0
### bitcoin_client/ledger_bitcoin/psbt.py
@@ -775,6 +775,9 @@ class PSBT(object):
PSBT_GLOBAL_GENERIC_SIGNED_MESSAGE = 0x09
PSBT_GLOBAL_VERSION = 0xFB
+ # Proprietary key (BIP-174) with identifier "MUSIG2_SESSION_ID", subtype 0 and no keydata
+ PSBT_GLOBAL_MUSIG2_SESSION_ID_KEY = b"\xfc" + ser_compact_size(17) + b"MUSIG2_SESSION_ID" + ser_compact_size(0)
+
def __init__(self, tx: Optional[CTransaction] = None) -> None:
"""
:param tx: A Bitcoin transaction that specifies the inputs and outputs to use
@@ -792,6 +795,11 @@ def __init__(self, tx: Optional[CTransaction] = None) -> None:
self.tx_modifiable: Optional[int] = None
# BIP-322: the message of a generic signed message request (allowed in any PSBT version)
self.generic_signed_message: Optional[bytes] = None
+ # MuSig2: the session id chosen by the software wallet (allowed in any PSBT version).
+ # A signer identifies its pending MuSig2 session by it, so the PSBT given to a signer in
+ # round 2 must have the value used for that signer in round 1. It is not part of the
+ # transaction: each signer can use its own value, in its own copy of the PSBT.
+ self.musig2_session_id: Optional[bytes] = None
# Assume version 0 PSBT
self.version = 0
@@ -907,6 +915,10 @@ def deserialize(self, psbt: str) -> None:
raise PSBTSerializationError("Global PSBT version is not 1 bytes")
self.version = struct.unpack("<I", v)[0]
self.explicit_version = True
+ elif key == PSBT.PSBT_GLOBAL_MUSIG2_SESSION_ID_KEY:
+ if key in key_lookup:
+ raise PSBTSerializationError("Duplicate key, global MuSig2 session id is already provided")
+ self.musig2_session_id = deser_string(f)
else:
if key in self.unknown:
raise PSBTSerializationError("Duplicate key, key for unknown value already provided")
@@ -1035,6 +1047,10 @@ def serialize(self) -> str:
r += ser_string(ser_compact_size(PSBT.PSBT_GLOBAL_VERSION))
r += ser_string(struct.pack("<I", self.version))
+ if self.musig2_session_id is not None:
+ r += ser_string(PSBT.PSBT_GLOBAL_MUSIG2_SESSION_ID_KEY)
+ r += ser_string(self.musig2_session_id)
+
# unknowns
for key, value in sorted(self.unknown.items()):
r += ser_string(key)
### bitcoin_client/tests/test_psbt_musig2_session_id.py
@@ -0,0 +1,82 @@
+import pytest
+
+from bitcoin_client.ledger_bitcoin.errors import PSBTSerializationError
+from bitcoin_client.ledger_bitcoin.psbt import PSBT, PartiallySignedInput, PartiallySignedOutput
+from bitcoin_client.ledger_bitcoin.tx import CTransaction, CTxIn, CTxOut, COutPoint
+
+
+MUSIG2_SESSION_ID_KEY = bytes.fromhex("fc11") + b"MUSIG2_SESSION_ID" + b"\x00"
+
+
+def make_psbt(session_id=None) -> PSBT:
+ """A PSBTv0 with one input and one output."""
+ tx = CTransaction()
+ tx.vin = [CTxIn(COutPoint(1, 0), b"", 0)]
+ tx.vout = [CTxOut(0, b"\x6a")]
+
+ psbt = PSBT(tx)
+ psbt.inputs = [PartiallySignedInput(0)]
+ psbt.outputs = [PartiallySignedOutput(0)]
+ psbt.musig2_session_id = session_id
+ return psbt
+
+
+def roundtrip(psbt: PSBT) -> PSBT:
+ result = PSBT()
+ result.deserialize(psbt.serialize())
+ return result
+
+
+def test_musig2_session_id_key():
+ assert PSBT.PSBT_GLOBAL_MUSIG2_SESSION_ID_KEY == MUSIG2_SESSION_ID_KEY
+ assert len(MUSIG2_SESSION_ID_KEY) == 20
+
+
+@pytest.mark.parametrize("session_id", [bytes(range(32)), b"\x01"])
+def test_musig2_session_id_roundtrip(session_id: bytes):
+ """The MUSIG2_SESSION_ID proprietary field is kept in both PSBT versions."""
+ psbt = make_psbt(session_id)
+
+ psbt_v0 = roundtrip(psbt)
+ assert psbt_v0.version == 0
+ assert psbt_v0.musig2_session_id == session_id
+ assert psbt_v0.unknown == {}
+
+ psbt_v0.convert_to_v2()
+ psbt_v2 = roundtrip(psbt_v0)
+ assert psbt_v2.version == 2
+ assert psbt_v2.musig2_session_id == session_id
+
+ psbt_v2.convert_to_v0()
+ assert roundtrip(psbt_v2).musig2_session_id == session_id
+
+
+def test_musig2_session_id_absent():
+ psbt = roundtrip(make_psbt())
+ assert psbt.musig2_session_id is None
+
+
+def test_musig2_session_id_set_as_unknown():
+ # a field set by a tool that does not know about it is parsed as well
+ psbt = make_psbt()
+ psbt.unknown[MUSIG2_SESSION_ID_KEY] = b"\x42" * 32
+ psbt = roundtrip(psbt)
+ assert psbt.musig2_session_id == b"\x42" * 32
+ assert psbt.unknown == {}
+
+
+def test_musig2_session_id_other_proprietary_keys():
+ # different subtype or keydata: not the MUSIG2_SESSION_ID field
+ psbt = make_psbt()
+ psbt.unknown[MUSIG2_SESSION_ID_KEY[:-1] + b"\x01"] = b"\x42"
+ psbt.unknown[MUSIG2_SESSION_ID_KEY + b"\x00"] = b"\x43"
+ psbt = roundtrip(psbt)
+ assert psbt.musig2_session_id is None
+ assert len(psbt.unknown) == 2
+
+
+def test_musig2_session_id_duplicate_key():
+ psbt = make_psbt(b"\x42" * 32)
+ psbt.unknown[MUSIG2_SESSION_ID_KEY] = b"\x43" * 32
+ with pytest.raises(PSBTSerializationError):
+ roundtrip(psbt)Why this scored 18/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.