BIP393: Output Script Descriptor Annotations #2099

pull craigraw wants to merge 5 commits into bitcoin:master from craigraw:descriptorannotations changing 3 files +141 −0
  1. craigraw commented at 11:15 AM on February 11, 2026: contributor

    This BIP proposal follows from the discussion for BIP392 (#2047) in which it emerged that due to the resource-intensive scanning requirements of the protocol some metadata (for example the birthday block height) may be practically required for efficient recovery of wallet funds. However, this metadata is not technically required to determine the output scripts, and therefore deemed unsuitable for direct inclusion in an output descriptor. This may lead to a situation in future where a wallet backup consisting of a valid output descriptor may not practically be complete enough to recover all the funds in a wallet.

    This BIP proposal provides a solution in the form of annotations - key/value pairs appended to a descriptor expression using URL-like query string delimiters. Annotations provide a compact way to include such metadata directly in a descriptor string, using characters already present in the BIP380 checksum character set.

    Note that annotations are not intended for general wallet backup, which may include other data such as labels. They are strictly scoped to convey operational metadata to aid recovery of funds without altering the scripts produced by the descriptor.

    cc: @achow101 as author of most Descriptor BIPs.

  2. murchandamus renamed this:
    Output Script Descriptor Annotations
    BIP Draft: Output Script Descriptor Annotations
    on Feb 13, 2026
  3. murchandamus added the label New BIP on Feb 13, 2026
  4. murchandamus commented at 7:13 PM on February 13, 2026: member

    Looks great for a first showing. No comments from an editorial perspective. I plan on letting this mature a bit in hope of seeing more discussion on the ML and review on the document.

  5. murchandamus added the label Needs number assignment on Feb 27, 2026
  6. murchandamus commented at 8:26 PM on March 17, 2026: member

    Let’s call this BIP 393. Please update the BIP and Assigned headers in the preamble, add a README table entry, and rename the file.

  7. murchandamus renamed this:
    BIP Draft: Output Script Descriptor Annotations
    BIP393: Output Script Descriptor Annotations
    on Mar 17, 2026
  8. murchandamus removed the label Needs number assignment on Mar 17, 2026
  9. Initial draft of Descriptor Annotations BIP f440874b99
  10. Improve scope definition, tighten specification and clarify semantics 2a3b64b23a
  11. Add link to mailing list discussion 4ca424850a
  12. craigraw force-pushed on Mar 18, 2026
  13. Update with assigned number 393 420248c5a1
  14. craigraw commented at 10:50 AM on March 18, 2026: contributor

    Done.

  15. achow101 commented at 11:28 PM on March 25, 2026: member

    Concept ACK

  16. in bip-0393.mediawiki:111 in 420248c5a1
     106 | +* Taproot descriptor with annotations:
     107 | +: <tt>tr(xpub6BgBgsespWvERF3LHQu6CnqdvfEvtMcQjYrcRzx53QJjSxarj2afYWcLteoGVky7D3UKDP9QyrLprQ3VCECoY49yfdDEHGCtMMj92pReUsQ/0/*)?bh=709632&gl=20#6la5jcn3</tt>
     108 | +
     109 | +The following annotated descriptors are invalid:
     110 | +
     111 | +* Uppercase key: <tt>raw(deadbeef)?Bh=1#...</tt>
    


    murchandamus commented at 9:09 PM on April 6, 2026:

    Nit:

    * Mixed case key: <tt>raw(deadbeef)?Bh=1#...</tt>
    
  17. murchandamus commented at 9:14 PM on April 6, 2026: member

    LGTM

    Any reservations against publishing this soon? Is there still any open planned work?

  18. Fix nit: mixed case key 01d1f916e2
  19. craigraw commented at 5:25 AM on April 7, 2026: contributor

    No reservations - there is no further planned work on this. I think it's ready for publishing.

  20. murchandamus merged this on Apr 7, 2026
  21. murchandamus closed this on Apr 7, 2026

  22. murchandamus commented at 3:39 PM on April 7, 2026: member

    SGTM, published.


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-04-14 15:10 UTC

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