* [bitcoindev] [BIP Proposal] Output Script Descriptor Annotations
@ 2026-02-11 10:38 Craig Raw
0 siblings, 0 replies; only message in thread
From: Craig Raw @ 2026-02-11 10:38 UTC (permalink / raw)
To: Bitcoin Development Mailing List
[-- 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 --]
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2026-02-11 10:59 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2026-02-11 10:38 [bitcoindev] [BIP Proposal] Output Script Descriptor Annotations Craig Raw
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox