From 9170a530a3628d8d7e6e14a2cc12df7a58b3ea4a Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Mon, 30 Aug 2021 15:34:41 -0400 Subject: [PATCH] doc: Mention multipath specifier --- doc/descriptors.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/descriptors.md b/doc/descriptors.md index 1baf652f3085ce..39529168662e02 100644 --- a/doc/descriptors.md +++ b/doc/descriptors.md @@ -97,6 +97,7 @@ Descriptors consist of several types of expressions. The top level expression is - [WIF](https://en.bitcoin.it/wiki/Wallet_import_format) encoded private keys may be specified instead of the corresponding public key, with the same meaning. - `xpub` encoded extended public key or `xprv` encoded extended private key (as defined in [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)). - Followed by zero or more `/NUM` unhardened and `/NUM'` hardened BIP32 derivation steps. + - No more than one of these derivation steps may be of the form `` (including hardened indicators with either or both `NUM`). If such specifiers are included, the descriptor will be parsed as multiple descriptors where the first descriptor uses all of the first `NUM` in the pair, and the second descriptor uses the second `NUM` in the pair for all `KEY` expressions, and so on. - Optionally followed by a single `/*` or `/*'` final step to denote all (direct) unhardened or hardened children. - The usage of hardened derivation steps requires providing the private key. @@ -245,6 +246,30 @@ supported, a private key in WIF format or xprv may be provided instead. This is useful when private keys are necessary for hardened derivation steps, or for dumping wallet descriptors including private key material. +### Specifying receiving and change descriptors in one descriptor + +Since receiving and change addresses are frequently derived from the same +extended key(s) but with a single derivation index changed, it is convenient +to be able to specify a descriptor that can derive at the two different +indexes. Thus a single tuple of indexes is allowed in each derivation path +following the extended key. When this descriptor is parsed, multiple descriptors +will be produced, the first one will use the first index in the tuple for all +key expressions, the second will use the second index, the third will use the +third index, and so on.. + +For example, a descriptor of the form: + + multi(2,xpub.../<0;1;2>/0/*,xpub.../<2;3;4>/*) + +will expand to the two descriptors + + multi(2,xpub.../0/0/*,xpub.../2/*) + multi(2,xpub.../1/0/*,xpub.../3/*) + multi(2,xpub.../2/0/*,xpub.../4*) + +When this tuple contains only two elements, wallet implementations can use the +first descriptor for receiving addresses and the second descriptor for change addresses. + ### Compatibility with old wallets In order to easily represent the sets of scripts currently supported by