[BIP Proposal] Output Script Descriptor Annotations

[Craig Raw]

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