Skip to content

MuSig2 + BIP138 - #132

Closed
Sjors wants to merge 16 commits into
2025/06/musig2-powerfrom
2026/11/musig2-bip138
Closed

Sjors wants to merge 16 commits into
2025/06/musig2-powerfrom
2026/11/musig2-bip138

Conversation

@Sjors

@Sjors Sjors commented Nov 9, 2026

Copy link
Copy Markdown
Owner

Sjors added 16 commits November 9, 2026 14:16
Add a shared RFC 3629 validator with tests for ASCII, multibyte boundaries, incomplete sequences, overlong encodings, surrogate code points, and values above U+10FFFF.
Preserve raw string bytes and validate them with the shared UTF-8 utility instead of decoding and normalizing malformed input. Keep escaped UTF-16 surrogate handling local, reject interrupted pairs, and correct supplementary-plane decoding.

Add regressions for malformed values and object keys, mixed raw bytes and escapes, and surrogate-pair boundaries.
Introduces WalletDescriptorInfo struct and DescriptorInfoToUniValue() helper
to avoid code duplication when serializing descriptor metadata to UniValue.

Refactors listdescriptors RPC to use the new helper.
Expose descriptor public-key collection that can omit keys observable from spent outputs. This lets encrypted-backup code derive recipient keys from non-observable descriptor xpubs without adding a separate BIP138-specific descriptor API.
Extract and normalize eligible descriptor BIP32 public key expressions for
BIP138 encrypted backups. Extended public keys that are not directly observable
from descriptor spends are converted to x-only keys, while literal pubkeys,
directly observable xpubs, and the BIP341 NUMS point are excluded.

For MuSig2 descriptors, participant xpubs remain eligible because the on-chain
aggregate key does not reveal them. Add a test vector for aggregate derivation
from bare participant xpubs using the BIP138 recipient vectors.
Add functions to compute the decryption secret and individual secrets
as specified in BIP138. The decryption secret is derived from sorted
public keys, and individual secrets allow any keyholder to decrypt.

Functions added:
- ComputeDecryptionSecret(): Hash sorted keys to derive decryption secret
- ComputeIndividualSecret(): Hash a single key to derive its individual secret
- ComputeAllIndividualSecrets(): Compute XOR'd secrets for all keys

Includes test vectors from the BIP specification.
Add functions for encoding and decoding BIP138 derivation paths as
count-prefixed arrays of big-endian child indices.

Encode paths in deterministic lexicographic order. Use the existing
ParseHDKeypath helper for textual path parsing in tests.

Includes test vectors from the BIP specification.
Add functions for encoding/decoding individual secrets as specified in BIP138:
- EncodeIndividualSecrets: encode sorted secrets to binary format
- DecodeIndividualSecrets: decode from binary format

Individual secrets allow any keyholder to derive the decryption secret using:
decryption_secret = ci XOR sha256("BIP_XXXX_INDIVIDUAL_SECRET" || pi)

Includes test vectors from the BIP specification.
Add functions for encoding and decoding BIP138 content type metadata.

Content types define what kind of data is in the encrypted payload:
- TYPE 0x01 encodes a 2-byte big-endian BIP number.
- TYPE 0x02 encodes vendor-specific content with CompactSize length.

Decode unknown TYPE values below 0x80 by skipping their length-prefixed
data. Reject TYPE 0x00 as reserved and TYPE values 0x80 or above as
unsupported upgrade-required content.
Add the BIP138 ChaCha20-Poly1305 algorithm identifier, nonce size, tag
size, and test coverage for the AEAD operation used by encrypted
backups.

The tests exercise a random roundtrip and the BIP test vectors against
the existing AEADChaCha20Poly1305 helper with an empty AAD.
Add binary and base64 encoding, encryption for all descriptor keys, and decryption helpers. Validate payloads and nonces, report excluded key expressions, pad secrets with decoys, and omit common derivation paths.

Include the full-backup vectors and roundtrip, malformed-content, and excluded-key tests.
Export every descriptor set as JSON or compact multipath content and encrypt for all included keys. Support optional derivation-path hints, metadata inspection, and decryption with an explicit xpub or wallet keys.

Keep decrypted content items separate internally so imports can process each document independently.
Import JSON documents and compact descriptors, including multiple content items and empty descriptor sets. Validate document fields and expand multipath descriptors while preserving birth times, ranges, and existing receive/change cursors.
Add encryptbackup, decryptbackup, and inspectbackup with compact output, optional derivation-path hints, explicit-xpub decryption, and import using wallet keys.

Exercise backup creation, recovery with every account xpub, metadata inspection, and JSON and compact imports in tool_wallet.py.
a9dcbfc wallet-tool: add encrypted descriptor backup commands
36a28d9 wallet: import BIP138 descriptor backups
7b90eb4 wallet: create and decrypt BIP138 descriptor backups
4a76ac1 wallet: recombine descriptor pairs as multipath descriptors
a532cc5 wallet: BIP138 full encrypted backup
d546828 wallet: BIP138 ChaCha20-Poly1305 test vectors
7229243 wallet: BIP138 content type encoding
de4c0c2 wallet: BIP138 individual secrets encoding
c028094 wallet: BIP138 derivation path encoding
1aab0b0 wallet: BIP138 secret computation
3f6001d wallet: BIP138 key extraction primitives
edc6b96 script: exclude observable pubkeys from descriptors
4c10318 wallet: add WalletDescriptorInfo helper for descriptor serialization
b6240b6 univalue: use strict UTF-8 validation for JSON strings
662e3fc util: add strict UTF-8 validation

Conflict resolution:

- src/script/descriptor.cpp: GetPubKeys() keeps returning MuSig2
  participant keys, but skips them when only_observable is set, since a
  spend reveals only the aggregate key.
- src/wallet/rpc/backup.cpp: listdescriptors keeps the wallet-provided
  multipath_descriptor field instead of the recombined multipath_desc.
- test/functional/wallet_listdescriptors.py: keep the existing multipath
  assertions and check multipath_descriptor for the recombination test.

Adaptations to the multipath descriptor API on this branch:

- Parse() returns a single descriptor; callers use GetMultipathExpansion()
  where they previously iterated over the parsed vector.
- ParseHDKeypath() returns a KeyPath; ParseDerivationPath() and
  FormatDerivationPath() convert to and from the BIP138 DerivationPath.
- Backup imports pass multipath descriptors to the wallet unexpanded so
  the branches keep their multipath relatives. Re-imports restore each
  branch's address cursor afterwards, since a multipath import request
  carries only one next_index.
@Sjors
Sjors added this pull request to stack #133 November 9, 2026 14:10
@Sjors Sjors closed this Nov 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant