doc: improvements to doc/descriptors.md #33986

1. 
   sipa commented at 4:25 pm on December 1, 2025: member

   This brings doc/descriptors.md up to date:

   • Stop trying to exhaustively list all RPCs that involve descriptors. They’re used everywhere.
   • Stop trying to give the history of descriptor support, we have release notes for that.
   • Mention that wallets are now built around descriptors (especially with legacy wallets gone).
   • Mention musig() KEY expressions in the specification part.
   • Reference the relevant output descriptor BIPs in the text.
2. doc: mention musig() in descriptors.md ee686aca0b
3. doc: do not list descriptor RPCs or history 1e954051ad
4. DrahtBot added the label Docs on Dec 1, 2025
5. 
   DrahtBot commented at 4:25 pm on December 1, 2025: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33986.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   Concept ACK	Sjors
   Stale ACK	rkrux, w0xlt, glozow

   If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.

   LLM Linter (✨ experimental)

   Possible typos and grammar issues:

   • P2SH embed the argument -> P2SH embeds the argument [subject-verb agreement; “P2SH” requires singular verb “embeds”]
   • P2WSH embed the argument -> P2WSH embeds the argument [subject-verb agreement; “P2WSH” requires singular verb “embeds”]
   • first 32 bit -> first 32 bits [plural needed for “bit(s)”]

   2025-12-11

6. 
   fanquake commented at 10:26 am on December 2, 2025: member

   cc @Sjors
7. rkrux approved
8. 
   rkrux commented at 9:23 am on December 3, 2025: contributor

   lgtm ACK fc33626f66e7f93f39989fbbabfbf00222762071
9. 
   w0xlt commented at 6:04 pm on December 3, 2025: contributor

   ACK https://github.com/bitcoin/bitcoin/pull/33986/commits/fc33626f66e7f93f39989fbbabfbf00222762071
10. in doc/descriptors.md:82 in fc33626f66

    78@@ -79,18 +79,18 @@ Descriptors consist of several types of expressions. The top level expression is
    79 - Followed by the actual key, which is either:
    80   - Hex encoded public keys (either 66 characters starting with `02` or `03` for a compressed pubkey, or 130 characters starting with `04` for an uncompressed pubkey).
    81     - Inside `wpkh` and `wsh`, only compressed public keys are permitted.
    82-    - Inside `tr` and `rawtr`, x-only pubkeys are also permitted (64 hex characters).
    83+    - Inside [`tr`](https://github.com/bitcoin/bips/blob/master/bip-0387.mediawiki) and `rawtr`, x-only pubkeys are also permitted (64 hex characters).
    

    ---

    ---

    

    glozow commented at 4:44 pm on December 9, 2025:

    Should this be referencing 386? https://github.com/bitcoin/bips/blob/master/bip-0386.mediawiki

    ---

    

    sipa commented at 1:52 pm on December 11, 2025:

    Fixed.
11. 
    glozow commented at 4:44 pm on December 9, 2025: member

    concept ACK fc33626f66e7f93f39989fbbabfbf00222762071
12. 
    Sjors commented at 4:53 pm on December 9, 2025: member

    Concept ACK

    I prefer to display the BIP numbers rather than “hide” them behind links.

    e.g.

    0Pay-to-witness-pubkey-hash scripts (P2WPKH, [BIP-141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki))
    

13. sipa force-pushed on Dec 10, 2025
14. sipa force-pushed on Dec 10, 2025
15. DrahtBot added the label CI failed on Dec 10, 2025
16. in doc/descriptors.md:63 in f0bae46213

    72+- `sh(SCRIPT)` (top level only): P2SH embed the argument, defined in [BIP 381](https://github.com/bitcoin/bips/blob/master/bip-0381.mediawiki).
    73+- `wsh(SCRIPT)` (top level or inside `sh` only): P2WSH embed the argument, defined in [BIP 382](https://github.com/bitcoin/bips/blob/master/bip-0382.mediawiki).
    74+- `pk(KEY)` (anywhere): P2PK output for the given public key, defined in [BIP 381](https://github.com/bitcoin/bips/blob/master/bip-0381.mediawiki).
    75+- `pkh(KEY)` (not inside `tr`): P2PKH output for the given public key (use `addr` if you only know the pubkey hash), defined in [BIP 381](https://github.com/bitcoin/bips/blob/master/bip-0381.mediawiki).
    76+- `wpkh(KEY)` (top level or inside `sh` only): P2WPKH output for the given compressed pubkey, defined in [BIP 382](https://github.com/bitcoin/bips/blob/master/bip-0382.mediawiki).
    77+- `combo(KEY)`  (top level only): an alias for the collection of `pk(KEY)` and `pkh(KEY)`, defined in [BIP 384][https://github.com/bitcoin/bips/blob/master/bip-0384.mediawiki). If the key is compressed, it also includes `wpkh(KEY)` and `sh(wpkh(KEY))`.
    

    ---

    ---

    

    ajtowns commented at 10:57 pm on December 10, 2025:

    Wrong bracket for bip 384

    ---

    

    sipa commented at 1:50 pm on December 11, 2025:

    Fixed.
17. DrahtBot removed the label CI failed on Dec 11, 2025
18. sipa force-pushed on Dec 11, 2025
19. sipa force-pushed on Dec 11, 2025
20. 
    sipa commented at 1:52 pm on December 11, 2025: member

    @Sjors Done.
21. DrahtBot added the label CI failed on Dec 11, 2025
22. doc: reference descriptor BIPs in descriptors.md b3aff41391
23. sipa force-pushed on Dec 11, 2025
24. DrahtBot removed the label CI failed on Dec 11, 2025

Contributors
sipa DrahtBot fanquake rkrux w0xlt glozow Sjors ajtowns

Labels
Docs