bip138: clarify key selection and apply exclusions across expressions #2300

pull Sjors wants to merge 5 commits into bitcoin:master from Sjors:2026/09/bip138-recipients changing 3 files +168 −64
  1. Sjors commented at 2:53 PM on September 23, 2026: member

    This PR clarifies which keys can decrypt a BIP138 backup.

    It expands the existing exclusion rule to consider all descriptors and key expressions in the backup. This makes encryption safer, but does not impact decryption, so it's not a breaking change.

    Four middle commits:

    • generalize key-selection test vectors: rename keys_types.json to recipient_keys.json and support lists of descriptors and expected keys, preserving the nine existing cases.
    • clarify MuSig participant eligibility: add two vectors, clarify that the participant xpubs should be used, not the aggregate key
    • collect and deduplicate recipient keys across the backup: deduplicate across all descriptor / policy sets.
    • exclude roots exposed by another expression: three test vectors: bare/derived reuse, an opposite-parity literal, and a MuSig participant exposed in a script leaf.

    The first commit introduces a changelog. I'm reusing that commit across a few parallel pull requests.

    The last commit updates the changelog; I'll update that depending on merge order.

  2. Sjors commented at 2:53 PM on September 23, 2026: member

    cc @pythcoiner, see also #2298 and #2299

  3. murchandamus commented at 4:19 PM on September 23, 2026: member

    Seems reasonable, waiting for @pythcoiner to chime in.

  4. murchandamus added the label Proposed BIP modification on Sep 23, 2026
  5. murchandamus added the label Pending acceptance on Sep 23, 2026
  6. Sjors referenced this in commit 763e8eb7d0 on Sep 23, 2026
  7. Sjors referenced this in commit f15428abbc on Sep 23, 2026
  8. Sjors referenced this in commit 9ebe96f809 on Sep 23, 2026
  9. Sjors referenced this in commit 7f106d32e6 on Sep 23, 2026
  10. pythcoiner commented at 10:57 AM on September 24, 2026: contributor

    @Sjors, about bip138: exclude roots exposed by another expression I'm wondering if we should not even be more strict: only use keys expressions that have at least a wildcard or a multipath

    let's take the example of wsh(or_i(pk(X/0/*),pk(Y))), here Y has not link to X, but the key will end up on chain, so anyone that get the encrypted payload could easily bruteforce by trying all onchain keys?

  11. Sjors commented at 11:49 AM on September 24, 2026: member

    @pythcoiner can you explain your example a bit more? IIUC Y is already excluded because it's a bare xpub or pubkey.

  12. pythcoiner commented at 12:04 PM on September 24, 2026: contributor

    @Sjors my bad, you are right

  13. pythcoiner commented at 12:05 PM on September 24, 2026: contributor

    ACK bf63b1d9

  14. bip138: generalize key-selection test vectors
    Rename keys_types.json to recipient_keys.json and generalize the format
    to support multiple descriptors and multiple recipient keys:
    
    - "key": a single key-expression string becomes "descriptors": an array
      of complete descriptor strings.
    - "expected": an x-only key string becomes "expected_keys": an array
      containing that key; null remains null.
    
    Convert the nine existing cases by wrapping each key expression in tr(),
    except the uncompressed literal uses pk(), since tr() does not accept it.
    Each case has one descriptor.
    5fc05e2b17
  15. bip138: clarify MuSig participant eligibility
    MuSig aggregation hides participant keys, so account xpubs do not need
    individual trailing derivation.
    
    Specify that encryption uses participant roots rather than the aggregate key.
    
    Add MuSig2 test vectors: one for a bare aggregate and one for aggregate
    derivation.
    11a3be7458
  16. bip138: collect and deduplicate recipient keys across the backup bde776ecb8
  17. bip138: exclude roots exposed by another expression
    A root selected through a derived xpub can also appear bare or as a
    literal key. Once a spend reveals it, anyone could decrypt the backup.
    Exclude such cases.
    299442b7de
  18. bip138: record recipients clarifications in changelog 346008db89
  19. murchandamus removed the label Pending acceptance on Sep 25, 2026
  20. murchandamus force-pushed on Sep 25, 2026
  21. murchandamus commented at 3:18 AM on September 25, 2026: member

    Thanks, @Sjors and @pythcoiner. I rebased the PR to fix the merge conflict on version and Changelog.

  22. murchandamus merged this on Sep 25, 2026
  23. murchandamus closed this on Sep 25, 2026

  24. Sjors deleted the branch on Sep 25, 2026

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bips. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-10-03 04:10 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me