BIPs 0380–0386
How do you describe the output scripts a wallet should watch?
The keys are only part of a wallet backup. A descriptor records how to turn them into the outputs the wallet should look for.
You restore a wallet from its seed. The keys are there, but which outputs should the wallet search for? The same public key can appear in several kinds of script. The seed also does not record which derivation paths the old wallet used. A backup can preserve the keys and still leave these questions unanswered.12
An output script descriptor supplies those missing instructions. It names the script to build, the keys to put in it, and any steps needed to derive them. Another wallet can read that description and reproduce the same outputs instead of having to guess how the first wallet used its keys.34
Source details
This chapter is an independent explanation, not the proposal itself. Preamble fields are shown as the pinned files record them, without author e-mail addresses. Status is the proposal’s own field. It is not an endorsement or a sign of consensus.
BIP 380: Output Script Descriptors General Operation
- BIP
- 380
- Layer
- Applications
- Title
- Output Script Descriptors General Operation
- Authors
- Pieter Wuille
Ava Chow - Status
- Deployed
- Type
- Specification
- Assigned
- 2021-06-27
- License
- BSD-2-Clause
BIP 381: Non-Segwit Output Script Descriptors
- BIP
- 381
- Layer
- Applications
- Title
- Non-Segwit Output Script Descriptors
- Authors
- Pieter Wuille
Ava Chow - Status
- Deployed
- Type
- Specification
- Assigned
- 2021-06-27
- License
- BSD-2-Clause
- Requires
- 380
BIP 382: Segwit Output Script Descriptors
- BIP
- 382
- Layer
- Applications
- Title
- Segwit Output Script Descriptors
- Authors
- Pieter Wuille
Ava Chow - Status
- Deployed
- Type
- Specification
- Assigned
- 2021-06-27
- License
- BSD-2-Clause
- Requires
- 380
BIP 383: Multisig Output Script Descriptors
- BIP
- 383
- Layer
- Applications
- Title
- Multisig Output Script Descriptors
- Authors
- Pieter Wuille
Ava Chow - Status
- Deployed
- Type
- Specification
- Assigned
- 2021-06-27
- License
- BSD-2-Clause
- Requires
- 380
BIP 384: combo() Output Script Descriptors
- BIP
- 384
- Layer
- Applications
- Title
- combo() Output Script Descriptors
- Authors
- Pieter Wuille
Ava Chow - Status
- Deployed
- Type
- Specification
- Assigned
- 2021-06-27
- License
- BSD-2-Clause
- Requires
- 380
BIP 385: raw() and addr() Output Script Descriptors
- BIP
- 385
- Layer
- Applications
- Title
- raw() and addr() Output Script Descriptors
- Authors
- Pieter Wuille
Ava Chow - Status
- Deployed
- Type
- Specification
- Assigned
- 2021-06-27
- License
- BSD-2-Clause
- Requires
- 380
BIP 386: tr() Output Script Descriptors
- BIP
- 386
- Layer
- Applications
- Title
- tr() Output Script Descriptors
- Authors
- Pieter Wuille
Ava Chow - Status
- Deployed
- Type
- Specification
- Assigned
- 2021-06-27
- License
- BSD-2-Clause
- Requires
- 380
Fig. A13.1 One key does not identify one script
The shared key and all four output scripts
- Published combo() descriptor
combo([01234567]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL)- Public key used in every expression
02d2b36900396c9282fa14628566582f206a5dd0bcc8d5e892611806cafb0301f0- pk(KEY) · BIP 384, line 48
2102d2b36900396c9282fa14628566582f206a5dd0bcc8d5e892611806cafb0301f0ac- pkh(KEY) · BIP 384, line 49
76a91431a507b815593dfc51ffc7245ae7e5aee304246e88ac- wpkh(KEY) · BIP 384, line 50
001431a507b815593dfc51ffc7245ae7e5aee304246e- sh(wpkh(KEY)) · BIP 384, line 51
a9142aafb926eb247cb18240a7f4c07983ad1f37922687
Choose the script, not just the key
Look at pkh(KEY) and wpkh(KEY). Both use the hash of a public key, but they put it into different scripts. The letters before the parentheses settle that choice. The key alone cannot tell a restored wallet which form the original wallet used.12
The expression is a recipe for ordinary Bitcoin script. With pkh(), the key’s 20-byte hash fills a slot between fixed instructions. Change the key and that slot changes. Change the function and the surrounding script changes too. Descriptors describe outputs that Bitcoin already supports; they do not introduce a new spending rule.269
Fig. A13.2 What pkh() adds around the key
Exact values
- Descriptor (BIP 381 line 80)
pkh([deadbeef/1/2'/3/4']03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd)- Key
03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd- HASH160 of the key
9a1c78a507689f6f54b847ad1cef1e614ee23f1e- Script
76a9149a1c78a507689f6f54b847ad1cef1e614ee23f1e88ac
Functions can fit inside one another. In sh(wpkh(KEY)), wpkh() first produces the SegWit script. sh() then makes an output that commits to that script’s hash. The inner script becomes the redeemScript needed when spending. The parentheses preserve this relationship instead of leaving it for the receiving wallet to infer.679
Which functions can go inside which?
BIP 381 covers the three main standard formats from before SegWit: pk(), pkh() and sh(). BIP 382 adds wpkh() and wsh(). sh() is only allowed at the top level; wpkh() and wsh() can appear at the top or inside sh(). Keys in wpkh(), and anywhere under wsh(), must be compressed. BIP 386 adds tr(), whose keys are x-only. A checksum cannot make an invalid nesting valid.671011
Read the key’s past and future
The brackets before a key describe its past. They contain a fingerprint of the key where derivation began, followed by the path from there. This origin information helps a signer holding that root find the right private key. It is information for the wallet; it adds no instructions to the output script.121314
The path after an extended key describes what to do next. In the example below, the wallet starts from the supplied xpub, follows /1/2, and then derives a child at the final /*. Keep those two paths separate when reading: the bracketed path explains how the supplied key was reached; the suffix continues from it.81215
Fig. A13.3 Past steps, supplied key, next steps
The descriptor in full (BIP 382, line 67)
wpkh([ffffffff/13']xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/2/*)A final /* makes this a ranged descriptor. It stands for a sequence of output scripts, one for each child index, so the wallet can keep deriving fresh receiving outputs from the same description. BIP 382 lists its first three. The interactive example reproduces those scripts from the published xpub.815
Choose the BIP 384 example below and compare its output scripts with the starting example. One descriptor can describe several script forms; the key alone does not choose the form.2568
Fig. A13.4 From a description to its output scripts
Static view: wpkh() over a ranged xpub, with its checksum computed (none is written). With JavaScript you can pick any of 8 published descriptors, highlight each key and check each checksum.
wpkh() over a ranged xpub. wpkh(KEY), 1 key, ranged: one script per child index. Checksum: computed #66s997t5, none written, nothing to compare.
Exact values for this descriptor
- Descriptor (BIP 382 line 67)
wpkh([ffffffff/13']xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/2/*)- Checksum computed
#66s997t5- Key 1
[ffffffff/13']xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/2/*- Public key, child 0
021a45661073b3902a29ab5d1bf2545d3bc09420d8ff1f574e5eebd3c4da98c589- Public key, child 1
02c99d4ca62021dadf698e56d7d0542660dfe6f090e466d0232026052b078a9b19- Public key, child 2
02683791601676cdefeabbc87d3740f31050b83419c9cc40d0aaf83c64fd862b81- Script, child 0
0014326b2249e3a25d5dc60935f044ee835d090ba859- Script, child 1
0014af0bd98abc2f2cae66e36896a39ffe2d32984fb7- Script, child 2
00141fa798efd1cbf95cebf912c031b8a4a6e9fb9f27
Published descriptors from BIPs 380–386, parsed and expanded at build time by the tested descriptor model; every script the BIPs list for them matches.
Key encodings and equivalent spellings
A key expression can contain a hex public key, a WIF private key, or an extended key. Hardened steps may be written with h or an apostrophe. BIP 381 publishes pkh() examples using both spellings, and using either a WIF private key or its corresponding public key. All produce the same output script. The origin records how to find a key, rather than changing what that key pays to.121314
Catch a copying mistake
A descriptor can end with # followed by an eight-character checksum. It gives the receiving software a way to notice that the text changed during copying. BIP 380 allows parsing without a checksum, but an application may require one. A # with nothing after it is a different case: the checksum is missing, and the test vector is rejected.162021
In the example, changing deadbeef to deedbeef while keeping the old checksum makes the check fail. But someone who deliberately changes the text can also calculate its new checksum. No secret key is involved. A matching checksum therefore cannot establish who supplied the descriptor or whether you should trust it.1821
Fig. A13.5 A copying error and a deliberate edit
How the checksum works, and what it guarantees
The checksum uses a fixed set of 95, which BIP 380 describes as three groups of 32 (the last group is one short). Each character becomes its position in a group. After every third character, another symbol records the group numbers. This arrangement helps the checksum detect changes to the text.2223
Any single symbol error is always detected; any two or three in a descriptor up to 49,154 characters; any four up to 507; any five up to 77. Random errors go undetected with a chance of 1 in 2^40. The model reproduces BIP 380’s raw(deadbeef)#89f8spxm vector and checks all of its published checksum cases.2124
Those cases include a checksum that is too long or too short, an error in the payload, an error in the checksum, and an unsupported character. Checking the checksum and checking whether the descriptor is a valid expression are separate jobs.1620
More than a single-key wallet
For multisignature outputs, multi() records the threshold and the participating keys. sortedmulti() sorts the derived public keys before building the script. If the keys have ranges, they advance together using the same child index. That keeps the description of the joint output in one expression.25
Other functions cover other needs. combo() expands one key into the older script forms shown at the top of this page. raw() carries an existing script directly, and addr() describes the script for an existing address. tr() describes a Taproot output, optionally including its tree of spending scripts.51126
Fig. A13.6 A reference for placing expressions
What each expression produces
- pk(KEY) · BIP 381
- <KEY> OP_CHECKSIG
- pkh(KEY) · BIP 381
- OP_DUP OP_HASH160 <KEY_hash160> OP_EQUALVERIFY OP_CHECKSIG
- sh(SCRIPT) · BIP 381
- OP_HASH160 <SCRIPT_hash160> OP_EQUAL
- wpkh(KEY) · BIP 382
- OP_0 <KEY_hash160>
- wsh(SCRIPT) · BIP 382
- OP_0 <SCRIPT_sha256>
- multi(NUM, KEY, ..., KEY) · BIP 383
- k KEY_1 … KEY_n n OP_CHECKMULTISIG
- sortedmulti(NUM, KEY, ..., KEY) · BIP 383
- as multi(), keys sorted
- combo(KEY) · BIP 384
- P2PK, P2PKH (+ P2WPKH, P2SH-P2WPKH if compressed)
- raw(HEX) · BIP 385
- the script itself
- addr(ADDR) · BIP 385
- the address's output script
- tr(KEY) · BIP 386
- OP_1 <32_byte_output_key>
- tr(KEY, TREE) · BIP 386
- OP_1 <32_byte_output_key>
- musig(KEY, KEY, ..., KEY) · BIP 390
- outside this chapter’s sources
- sp(KEY) · BIP 392
- outside this chapter’s sources
- sp(KEY, KEY) · BIP 392
- outside this chapter’s sources
Multisig limits and the Taproot model’s scope
For multi(k, KEY_1, …, KEY_n), k must not exceed n. The context limits the key count: 3 at the top level, 15 compressed keys (or 7 uncompressed) directly inside sh() because of the 520-byte push limit, and 20 otherwise. sortedmulti() sorts keys lexicographically after derivation.25
tr(KEY) produces an output with no usable script path; tr(KEY, TREE) adds a tree written with braces. Of the script expressions that existed when BIP 386 was written, only pk() could be a leaf. Miniscript and multi_a() came later. This site’s model supports pk() leaves and rejects the published Miniscript example as outside its scope.81128
Source and design notes
These proposals were assigned in 2021 as BIPs 380 to 386 and are recorded as Deployed in the pinned sources. The BIPs record descriptors in Bitcoin Core since version 0.17, and tr() since 22.0. BIP 380’s index also lists later expressions such as musig() and sp().272930
The authors wanted descriptors to be readable by engineers familiar with Bitcoin’s existing formats. They also argued against encoding script choices in alternative extended-key version bytes: key derivation and script type are separate decisions. Descriptors give each an explicit place in the text.431
A key is one ingredient. A descriptor records how that key and any others fit into an output script. Keeping the description lets another wallet reproduce the same scripts.234
Evidence
Each numbered marker in the text points here, and the ↩ links lead back to the text. Quotes are verbatim
from the BIP files at commit 3a10b5b, wiki markup
included. Links open the exact lines. Labels say what kind of statement each entry is: a rule, the
author’s rationale, history, a test vector, or our own inference.
-
↩ a b Author’s rationale The authors' motivation: backups of private keys alone, now mostly BIP 39 mnemonics, do not tell a restored wallet which output scripts to produce, and missing derivation-path information adds more incompatibilities.
BIP 380 L26–29 BIP 380 L32 BIP 380 L32–33
Quoted source text (3)
Typically backups have consisted of solely the private keys, nowadays primarily in the form of BIP 39 mnemonics. However this backup solution is insufficient, especially since the introduction of Segregated Witness which added new output types. Given just the private keys, it is not possible for restored wallets to know which kinds of output scripts and addresses to produce.
Although BIPs 44, 49, and 84 have specified standard BIP 32 derivation paths for different output scripts and addresses, not all wallets support those derivation paths nor use them.
The lack of derivation path information in these backups and exports leads to further incompatibilities between wallets.
-
↩ a b c d e f g Rule Each script expression fills a fixed template: pk() gives <KEY> OP_CHECKSIG, pkh() gives OP_DUP OP_HASH160 <KEY_hash160> OP_EQUALVERIFY OP_CHECKSIG, and wpkh() gives OP_0 <KEY_hash160>.
BIP 381 L43 BIP 381 L55 BIP 382 L41
Quoted source text (3)
<KEY> OP_CHECKSIG
OP_DUP OP_HASH160 <KEY_hash160> OP_EQUALVERIFY OP_CHECKSIG
OP_0 <KEY_hash160>
-
↩ a b Rule Output script descriptors are a simple language for describing collections of output scripts; BIP 380 gives the general syntax, the checksum and the common expressions.
Quoted source text (1)
Output Script Descriptors are a simple language which can be used to describe collections of output scripts. There can be many different descriptor fragments and functions. This document describes the general syntax for descriptors, descriptor checksums, and common expressions.
-
↩ a b c d e Author’s rationale Descriptors state script types explicitly in script expressions and derivation paths in key expressions, so backups and exports can specify the exact scripts, subscripts and keys, in a form meant to be readable at a glance.
Quoted source text (2)
Script types are specified explicitly through the use of Script Expressions. Key derivation paths are specified explicitly in Key Expressions. These allow for creating wallet backups and exports which specify the exact scripts, subscripts (redeemScript, witnessScript, etc.), and keys to produce.
the use of common terminology and existing standards allow for Output Script Descriptors to be engineer readable so that the results can be understood at a glance.
-
↩ a b c d Rule combo(KEY), top level only, produces P2PK and P2PKH scripts, plus P2WPKH and P2SH-P2WPKH for a compressed key, to ease the move from key-based to descriptor-based wallets.
Quoted source text (2)
In order to make the transition from traditional key based wallets to descriptor based wallets easier, it is useful to be able to take a key and produce the scripts which have traditionally been produced by wallet software.
This expression can only be used as a top level expression. It takes a single key expression as an argument and produces either 2 or 4 output scripts, depending on the key.
-
↩ a b c d e f g Rule BIP 381 defines pk() (P2PK, allowed at any level), pkh() (P2PKH; top level or inside sh() or wsh()) and sh() (P2SH, top level only, whose argument becomes the redeemScript), the three main standard formats before SegWit.
BIP 381 L27–28 BIP 381 L36 BIP 381 L48 BIP 381 L60–63
Quoted source text (4)
Prior to the activation of Segregated Witness, there were 3 main standard output script formats: P2PK, P2PKH, and P2SH.
The <tt>pk(KEY)</tt> expression can be used in any context or level of a descriptor.
The <tt>pkh(KEY)</tt> expression can be used as a top level expression, or inside of either a <tt>sh()</tt> or <tt>wsh()</tt> descriptor.
The <tt>sh(SCRIPT)</tt> expression can only be used as a top level expression. It takes a single script expression as an argument and produces a P2SH output script. <tt>sh()</tt> expressions also create a redeemScript which is required in order to spend outputs which use its output script.
-
↩ a b c d Rule BIP 382 defines wpkh() and wsh() for SegWit's P2WPKH and P2WSH, usable at the top level or inside sh(); only compressed public keys are allowed in wpkh() and anywhere under wsh().
Quoted source text (2)
The <tt>wpkh(KEY)</tt> expression can be used as a top level expression, or inside of a <tt>sh()</tt> descriptor. It takes a single key expression as an argument and produces a P2WPKH output script. Only keys which are/have compressed public keys can be contained in a <tt>wpkh()</tt> expression.
Any key expression found in any script expression contained by a <tt>wsh()</tt> expression must only produce compressed public keys.
-
↩ a b c d e f g Test vector This site's descriptor model expands every valid descriptor listed in BIPs 381 to 386 to exactly the scripts the BIPs list (for ranged ones, the children each BIP lists: 0 to 2, or 0 and 1 for combo()) and rejects every listed invalid descriptor; the one listed valid descriptor with a Miniscript leaf, tr(…, pkh(…)), is outside the model's scope and is refused as such.
Quoted source text (2)
Valid descriptors followed by the scripts they produce. Descriptors involving derived child keys will have the 0th, 1st, and 2nd scripts listed.
* <tt>tr(a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd,pkh(L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1))</tt>
-
↩ a b Rule Script expressions are written as functions whose arguments fill a script template; the arguments may be script expressions, key expressions or something else.
Quoted source text (1)
Script Expressions (denoted <tt>SCRIPT</tt>) are expressions which correspond directly with a Bitcoin script. These expressions are written as functions and take arguments. Such expressions have a script template which is filled with the arguments correspondingly.
-
↩ History BIP 381 counts three main standard output formats before SegWit: P2PK, P2PKH and P2SH.
Quoted source text (1)
Prior to the activation of Segregated Witness, there were 3 main standard output script formats: P2PK, P2PKH, and P2SH.
-
↩ a b c d Rule tr(KEY) produces a P2TR output with no usable script path (the key is tweaked to commit to an unspendable one); tr(KEY, TREE) adds a script tree written with braces; all keys under tr() are x-only, and uncompressed keys are not allowed.
BIP 386 L49–50 BIP 386 L52 BIP 386 L63–66 BIP 386 L78
Quoted source text (4)
The <tt>tr(KEY)</tt> or <tt>tr(KEY, TREE)</tt> expression can only be used as a top level expression. All key expressions under any <tt>tr()</tt> expression must create x-only public keys.
<tt>tr(KEY)</tt> takes a single key expression as an argument and produces a P2TR output script which does not have a script path.
<tt>tr(KEY, TREE)</tt> takes a key expression as the first argument, and a tree expression as the second argument and produces a P2TR output script which has a script path.
Uncompressed public keys are not allowed, but compressed public keys would be implicitly converted to x-only public keys.
-
↩ a b c d e Rule A key expression is optional origin information (an 8-hex-character fingerprint and the derivation steps from it, in brackets), then a hex public key, a WIF private key, or an xpub or xprv followed by derivation steps and optionally /* or /*h; h and ' both mark hardened steps.
BIP 380 L70–74 BIP 380 L75–82 BIP 380 L89
Quoted source text (3)
* Optionally, key origin information, consisting of: ** An open bracket <tt>[</tt> ** Exactly 8 hex characters for the fingerprint of the key where the derivation starts (see BIP 32 for details)
** A [[https://en.bitcoin.it/wiki/Wallet_import_format|WIF]] encoded private key ** <tt>xpub</tt> encoded extended public key or <tt>xprv</tt> encoded extended private key (as defined in BIP 32) *** Followed by zero or more <tt>/NUM</tt> or <tt>/NUMh</tt> path elements indicating BIP 32 derivation steps to be taken after the given extended key. *** Optionally followed by a single <tt>/*</tt> or <tt>/*h</tt> final step to denote all direct unhardened or hardened children.
the hardened indicator <tt>h</tt> may be replaced with alternative hardened indicator of <tt>'</tt>.
-
↩ a b c Editorial inference The origin information exists so that software holding the root key can tell which of its keys a descriptor key is; the script itself does not depend on it.
Quoted source text (1)
** Exactly 8 hex characters for the fingerprint of the key where the derivation starts (see BIP 32 for details) ** Followed by zero or more <tt>/NUM</tt> or <tt>/NUMh</tt> path elements to indicate the unhardened or hardened derivation steps between the fingerprint and the key that follows.
-
↩ a b c Test vector Key origin information describes where a key came from and does not change the script: BIP 381 lists pkh() with an origin, written with ' or with h, and with a WIF key or its public key, all producing the same script.
Quoted source text (2)
These represent a public or private key and, optionally, information about the origin of that key.
* <tt>pkh([deadbeef/1/2'/3/4']L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1)</tt> ** <tt>76a9149a1c78a507689f6f54b847ad1cef1e614ee23f1e88ac</tt> * <tt>pkh([deadbeef/1/2'/3/4']03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd)</tt> ** <tt>76a9149a1c78a507689f6f54b847ad1cef1e614ee23f1e88ac</tt> * <tt>pkh([deadbeef/1/2h/3/4h]03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd)</tt> ** <tt>76a9149a1c78a507689f6f54b847ad1cef1e614ee23f1e88ac</tt>
-
↩ a b c d Rule When the final step is /* or /*', an output script is produced for every child index.
Quoted source text (1)
When the final step is <tt>/*</tt> or <tt>/*'</tt>, an output script will be produced for every child key index.
-
↩ a b c d Rule A descriptor is a top-level script expression, optionally followed by # and an 8-character checksum; the checksum is optional for parsing, but applications may reject descriptors without one.
Quoted source text (1)
The top level expression is a <tt>SCRIPT</tt>. This expression may be followed by <tt>#CHECKSUM</tt>, where <tt>CHECKSUM</tt> is an 8 character alphanumeric descriptor checksum. Although the checksum is optional for parsing, applications may choose to reject descriptors that do not contain a checksum.
-
↩ a b c Editorial inference A descriptor whose keys are all public reveals the scripts it stands for but cannot spend them; one that contains a WIF key or an xprv is as sensitive as those keys.
Quoted source text (1)
** A [[https://en.bitcoin.it/wiki/Wallet_import_format|WIF]] encoded private key ** <tt>xpub</tt> encoded extended public key or <tt>xprv</tt> encoded extended private key (as defined in BIP 32)
-
↩ a b c Editorial inference The checksum is computed from the descriptor text alone, with no key, so anyone can produce a valid checksum for any descriptor: it catches typos, not tampering.
Quoted source text (1)
def descsum_create(s): """Add a checksum to a descriptor without""" symbols = descsum_expand(s) + [0, 0, 0, 0, 0, 0, 0, 0] checksum = descsum_polymod(symbols) ^ 1
-
↩ a b Rule When a descriptor is exported without private keys, BIP 380 says the exporter should derive the extended public key at the last hardened step, and the steps taken to get there must be added to the key origin.
Quoted source text (1)
When a descriptor is exported without private keys, it is necessary to do additional derivation to remove any intermediate hardened derivation steps for the exported descriptor to be useful. The exporter should derive the extended public key at the last hardened derivation step and use that extended public key as the key in the descriptor. The derivation steps that were taken to get to that key must be added to the previous key origin information.
-
↩ a b c Rule BIP 380's checksum vectors cover a valid checksum, a missing one, one character too many or too few, an error in the payload, an error in the checksum, and a character outside the set.
Quoted source text (1)
* Valid checksum: <tt>raw(deadbeef)#89f8spxm</tt> * No checksum: <tt>raw(deadbeef)</tt> * Missing checksum: <tt>raw(deadbeef)#</tt> * Too long checksum (9 chars): <tt>raw(deadbeef)#89f8spxmx</tt> * Too short checksum (7 chars): <tt>raw(deadbeef)#89f8spx</tt> * Error in payload: <tt>raw(deedbeef)#89f8spxm</tt> * Error in checksum: <tt>raw(deedbeef)##9f8spxm</tt> * Invalid characters in payload: <tt>raw(Ü)#00000000</tt>
-
↩ a b c d Test vector This site's checksum code, transcribed from BIP 380's Python, reproduces the published checksum #89f8spxm for raw(deadbeef) and gives the expected verdict for each of BIP 380's checksum vectors; a test confirms every single-character substitution from the first group in that descriptor is detected.
Quoted source text (1)
* Valid checksum: <tt>raw(deadbeef)#89f8spxm</tt>
-
↩ Rule Descriptors may only use a fixed character set, which BIP 380 writes as three groups of 32 (its own code has 95 characters, the last group one short) in an order chosen so the checksum can identify more errors.
Quoted source text (2)
The expressions used in descriptors must only contain characters within this character set so that the descriptor checksum will work.
This character set is written as 3 groups of 32 characters in this specific order so that the checksum below can identify more errors. The first group are the most common "unprotected" characters (i.e. things such as hex and keypaths that do not already have their own checksums).
-
↩ Rule Each character becomes its position within its group, and after every third character a symbol for the three group numbers is inserted, so a change to only the position or only the group affects a single symbol.
Quoted source text (1)
The entire descriptor string is first processed into an array of symbols. The symbol for each character is its position within its group. After every 3rd symbol, a 4th symbol is inserted which represents the group numbers combined together. This means that a change that only affects the position within a group, or only a group number change, will only affect a single symbol.
-
↩ Rule The checksum is an error-correcting code similar to bech32: any 1 symbol error is always detected, any 2 or 3 in descriptors up to 49,154 characters, any 4 up to 507, any 5 up to 77, and random errors go undetected with a chance of 1 in 2^40.
BIP 380 L118 BIP 380 L127–132 BIP 380 L132
Quoted source text (3)
The checksum is an error correcting checksum similar to bech32.
* Any 1 symbol error is always detected. * Any 2 or 3 symbol error in a descriptor of up to 49154 characters is always detected. * Any 4 symbol error in a descriptor of up to 507 characters is always detected. * Any 5 symbol error in a descriptor of up to 77 characters is always detected.
* Random errors have a chance of 1 in 240 of being undetected.
-
↩ a b c Rule multi(k, KEY_1, …, KEY_n) and sortedmulti() produce a k-of-n CHECKMULTISIG script with k ≤ n; sortedmulti() sorts the derived keys, extended keys advance in lockstep, and the number of keys is limited to 3 at the top level, 15 compressed keys in sh() (the 520-byte push limit), and 20 otherwise.
BIP 383 L33–35 BIP 383 L41–47 BIP 383 L60–61 BIP 383 L65–66
Quoted source text (4)
They are written as <tt>multi(k,KEY_1,KEY_2,...,KEY_n)</tt>. <tt>k</tt> is the threshold - the number of keys that must sign the input for the script to be valid. <tt>KEY_1,KEY_2,...,KEY_n</tt> are the key expressions for the multisig. <tt>k</tt> must be less than or equal to <tt>n</tt>.
When used at the top level, there can only be at most 3 keys. When used inside of a <tt>sh()</tt> expression, the output script produced is the redeem script, which is pushed as a single element in the spending scriptSig and must therefore not exceed the 520 byte limit on the size of a script element. This allows at most 15 compressed public keys, or at most 7 uncompressed ones, as an uncompressed key takes 66 bytes of the script rather than 34. Otherwise the maximum number of keys is 20.
The only change for <tt>sortedmulti()</tt> is that the keys are sorted lexicographically prior to the creation of the output script. This sorting is on the keys that are to be put into the output script, i.e. after all extended keys are derived.
When one or more the key expressions in a <tt>multi()</tt> or <tt>sortedmulti()</tt> expression are extended keys, the derived keys use the same child index.
-
↩ a b Rule raw(HEX) and addr(ADDR), top level only, wrap an arbitrary script or an address as a descriptor.
Quoted source text (2)
In order to make descriptors maximally compatible with scripts in use today, it is useful to be able to wrap any arbitrary output script or an address into a descriptor.
The <tt>raw(HEX)</tt> expression can only be used as a top level descriptor. As the argument, it takes a hex string representing a Bitcoin script.
-
↩ a b Rule BIP 380's appendix indexes the script expressions and the BIPs that define them, and leaves room for future ones such as musig() (BIP 390) and sp() (BIP 392).
BIP 380 L299–300 BIP 380 L339–343
Quoted source text (2)
Script expressions will be specified in additional BIPs. This Table lists all available Script expressions and the BIPs specifying them.
| <tt>musig(KEY, KEY, ..., KEY)</tt> | [[bip-0390.mediawiki|390]] |- | <tt>sp(KEY)</tt>, <tt>sp(KEY, KEY)</tt> | [[bip-0392.mediawiki|392]]
-
↩ History Of the script expressions that existed when BIP 386 was written, only pk() can be used in a tree; Miniscript (BIP 379) and BIP 387's multi_a() came later.
Quoted source text (1)
Of the script expressions that existed when this BIP was written, only <tt>pk()</tt> can be used in a tree expression. Script expressions specified since then that can be used in a tree expression are the Miniscript expressions of [[bip-0379.md|379]], which include a <tt>pkh()</tt> fragment, and the <tt>multi_a()</tt> and <tt>sortedmulti_a()</tt> expressions of [[bip-0387.mediawiki|387]].
-
↩ History BIPs 380 to 386 are application-layer specifications by Pieter Wuille and Ava Chow, assigned in 2021 and recorded as Deployed; 381 to 386 each require BIP 380.
Quoted source text (2)
Layer: Applications Title: Output Script Descriptors General Operation Authors: Pieter Wuille <pieter@wuille.net> Ava Chow <me@achow101.com> Status: Deployed Type: Specification Assigned: 2021-06-27
Title: tr() Output Script Descriptors Authors: Pieter Wuille <pieter@wuille.net> Ava Chow <me@achow101.com> Status: Deployed Type: Specification Assigned: 2021-06-27 License: BSD-2-Clause Requires: 380
-
↩ History The BIPs record descriptors as implemented in Bitcoin Core since version 0.17, and tr() since version 22.0.
Quoted source text (2)
Descriptors have been implemented in Bitcoin Core since version 0.17.
<tt>tr()</tt> descriptors have been implemented in Bitcoin Core since version 22.0.
-
↩ Author’s rationale The authors call alternative version bytes for extended keys a layer violation, since key derivation should be separate from script type, and specific to one path and script type.
Quoted source text (1)
Solutions such as introducing different version bytes for extended key serialization both are a layer violation (key derivation should be separate from script type meaning) and specific only to a particular derivation path and script type.