From: Craig Raw <craigraw@gmail.com>
To: Bitcoin Development Mailing List <bitcoindev@googlegroups.com>
Subject: [bitcoindev] [BIP Proposal] Output Script Descriptor Annotations
Date: Wed, 11 Feb 2026 12:38:41 +0200 [thread overview]
Message-ID: <CAPR5oBN8vJs2wNhKWBo6XpkdXdzDK0+nYHSzQqWS26=XNdiejg@mail.gmail.com> (raw)
[-- Attachment #1: Type: text/plain, Size: 2771 bytes --]
Hi all,
During discussion around BIP392 [1] for Silent Payment Output Script
Descriptors, 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 is not unique to silent payments. Any descriptor-based backup can
suffer from the same issue: the descriptor specifies in general what to
derive, but not where to begin or how far to scan. A wallet restored with
only a descriptor must guess at parameters like the gap limit or starting
block height, and may be inefficient or alternatively miss funds if those
guesses are too conservative.
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.
An annotated descriptor has the form:
SCRIPT?key=value&key=value#CHECKSUM
Three key names are defined for starting block height, gap limit (for BIP32
HD wallets) and max label index (for silent payments wallets). Annotation
values are declared lower bounds: they represent the minimum values
required to recover all funds at the time the descriptor was exported. Over
the lifetime of a wallet these values may increase (e.g. the gap limit may
grow as more addresses are used) but should not decrease.
Example: wpkh([deadbeef/84h/0h/0h]xpub.../0/*)?bh=800000&gl=30#v35n46d2
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.
The full text of the BIP can be found at
https://github.com/craigraw/bips/blob/descriptorannotations/bip-descriptorannotations.mediawiki
--Craig
[1]: https://github.com/bitcoin/bips/pull/2047
--
You received this message because you are subscribed to the Google Groups "Bitcoin Development Mailing List" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bitcoindev+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/bitcoindev/CAPR5oBN8vJs2wNhKWBo6XpkdXdzDK0%2BnYHSzQqWS26%3DXNdiejg%40mail.gmail.com.
[-- Attachment #2: Type: text/html, Size: 3491 bytes --]
reply other threads:[~2026-02-11 10:59 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAPR5oBN8vJs2wNhKWBo6XpkdXdzDK0+nYHSzQqWS26=XNdiejg@mail.gmail.com' \
--to=craigraw@gmail.com \
--cc=bitcoindev@googlegroups.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox