Skip to content
BIP ATLAS

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 revision
bitcoin/bips @ 3a10b5b
Source checked
1 October 2026
Review state
Awaiting review
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

Pinned source · Reader view on bips.dev
SHA-256 34e6510bb2eba9445a68eacf3d24d5a4e5f24481477488d5552f674ac81dd5fe
Git blob 88fd273a186a916a04ae3f3f48c2ba05396db494

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

Pinned source · Reader view on bips.dev
SHA-256 f0f6060332f82454f61015815c824eea4b7b6684ce4892ef42d23e4e782fa817
Git blob b3ccf49abf79497eba495f42d73d759db046b139

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

Pinned source · Reader view on bips.dev
SHA-256 6cd2574998ca0d2141d1c487e70da2dfab47abd6a2dfcc3680af2c241f01fe9d
Git blob aaad5426fb11c68df91272f4062183a551ecb52c

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

Pinned source · Reader view on bips.dev
SHA-256 c46f75e5869386c1852dd187725293822b9e3b761342a966fbcf99adaa112aa2
Git blob 04e732756c934f234563127411048d289a5492b9

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

Pinned source · Reader view on bips.dev
SHA-256 9d6b32a619e021f50f4b1a07ed8f9d08cfea599c8f484e6b1360ada9aae8541c
Git blob 8db844d02515aadf6e16db788f105638edc3fd01

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

Pinned source · Reader view on bips.dev
SHA-256 8c4963492f1d5b492808e5ece8be75f7f66def37f35d091074fdbfa98a6ddd08
Git blob e14aa3829796d94f0b439e3202dd7fa23d504900

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

Pinned source · Reader view on bips.dev
SHA-256 770121b4b33a50bfadfebcd94931dd0ad04159b9fbc1d3b3c3ae17fc0cc16de8
Git blob 85a63f0b53fb965641eaa291052b23abdf837506

Fig. A13.1 One key does not identify one script

One key does not identify one scriptOne compressed public key, 02d2b36900396c9282fa14628566582f206a5dd0bcc8d5e892611806cafb0301f0, can be used in different output scripts. BIP 384's published combo() example produces all four: pk(KEY), P2PK: 2102d2b36900396c9282fa14628566582f206a5dd0bcc8d5e892611806cafb0301f0ac; pkh(KEY), P2PKH: 76a91431a507b815593dfc51ffc7245ae7e5aee304246e88ac; wpkh(KEY), P2WPKH: 001431a507b815593dfc51ffc7245ae7e5aee304246e; sh(wpkh(KEY)), P2SH-P2WPKH: a9142aafb926eb247cb18240a7f4c07983ad1f37922687. KEY is a placeholder for that same public key in each expression, not four different keys. A more specific expression selects the script form. These are output scripts, not addresses; their displayed bytes are shortened.THE SAME PUBLIC KEY02d2b36900396c9282fa14…can be used in each of thesepk(KEY)P2PK21 02d2b3690039… acpkh(KEY)P2PKH76 a9 14 31a507b81559… 88 acwpkh(KEY)P2WPKH00 14 31a507b81559…sh(wpkh(KEY))P2SH-P2WPKHa9 14 2aafb926eb24… 87THE EXPRESSION SETTLES THE CHOICE
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
These four output scripts use the same public key. BIP 384’s combo() example produces all of them; a more specific expression, such as wpkh(), chooses a particular form.25678

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

Filling the templatepkh() fills BIP 381's template OP_DUP OP_HASH160 <KEY_hash160> OP_EQUALVERIFY OP_CHECKSIG. The key 03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd goes through HASH160, giving 9a1c78a507689f6f54b847ad1cef1e614ee23f1e, which fills the one slot after a push of 20 bytes (0x14). The script is 76a9149a1c78a507689f6f54b847ad1cef1e614ee23f1e88ac, as BIP 381 lists it on line 81.KEY · 03a34b99f2…ITS ORIGIN [deadbeef/…] ADDS NO BYTESHASH160→ 20 BYTES INTO THE ONE SLOTTEMPLATE (BIP 381)BYTES · BIP 381 LINE 81OP_DUP76OP_HASH160a9push 20 bytes14<KEY_hash160>9a1c78a507689f…OP_EQUALVERIFY88OP_CHECKSIGac
Exact values
Descriptor (BIP 381 line 80)
pkh([deadbeef/1/2'/3/4']03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd)
Key
03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd
HASH160 of the key
9a1c78a507689f6f54b847ad1cef1e614ee23f1e
Script
76a9149a1c78a507689f6f54b847ad1cef1e614ee23f1e88ac
The highlighted slot holds the key’s hash. The surrounding instructions come from the pkh() template.268

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

A descriptor, part by partThe descriptor wpkh([ffffffff/13']xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/2/*) from BIP 382, read as parts: wpkh(, the script expression; [ffffffff/13′], the key origin; xpub69H7F5d8…, the public key; /1/2, the derivation; /*, the range. No checksum is written after #; it is optional. It stands for one output script per child index; BIP 382 lists the first 3.wpkh([ffffffff/13′]xpub69H7F5d8…/1/2/*)SCRIPT EXPRESSIONWHAT KIND OF OUTPUTKEY ORIGINFINGERPRINT + STEPSPUBLIC KEYAN XPUBDERIVATIONSTEPS AFTER THE KEYRANGEEVERY CHILD INDEX#CHECKSUMOPTIONALONE OUTPUT SCRIPT PER CHILD INDEX
The descriptor in full (BIP 382, line 67)wpkh([ffffffff/13']xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/2/*)
The origin records earlier derivation. The path and wildcard after the xpub tell the wallet which keys to derive next.4121516

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.

Reading a descriptorwpkh([ffffffff/13']xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/2/*), from BIP 382 line 67. It reads wpkh(KEY): key 1 is a extended public key with origin [ffffffff/13h], then /1/2/*. It stands for 3 output scripts (the first children; the range continues). The checksum computed from the text is #66s997t5: computed here · none written, which is allowed.PUBLIC KEYS ONLY: REVEALS SCRIPTS, CANNOT SPENDRANGED: ONE SCRIPT PER CHILDwpkh( )[ffffffff/13′]xpub69H7F5d8…/1/2/*#NO CHECKSUM WRITTEN183 SYMBOLS → POLYMOD → #66s997t5COMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS/00014326b2249e3a25d5d…/10014af0bd98abc2f2cae…/200141fa798efd1cbf95c…… AND EVERY LATER CHILDKEY 1 OF 1 · EXTENDED PUBLIC KEYorigin [ffffffff/13′]after the key /1/2/*child 0 public key 021a456610…child 1 public key 02c99d4ca6…child 2 public key 0268379160…
Reading a descriptorwpkh([ffffffff/13']xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/2/*), from BIP 382 line 67. It reads wpkh(KEY): key 1 is a extended public key with origin [ffffffff/13h], then /1/2/*. It stands for 3 output scripts (the first children; the range continues). The checksum computed from the text is #66s997t5: computed here · none written, which is allowed.PUBLIC KEYS ONLY: REVEALS SCRIPTS, CANNOT SPENDwpkh( )[ffffffff/13′]xpub69H7F5d8…/1/2/*#NO CHECKSUM WRITTEN183 SYMBOLS → POLYMOD → #66s997t5COMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS/00014326b2249e3a25d5d…/10014af0bd98abc2f2cae…/200141fa798efd1cbf95c…… AND EVERY LATER CHILDKEY 1 OF 1 · EXTENDED PUBLIC KEYorigin [ffffffff/13′]after the key /1/2/*child 0 public key 021a456610…child 1 public key 02c99d4ca6…child 2 public key 0268379160…
Reading a descriptorraw(deadbeef)#89f8spxm, from BIP 380 line 204. It reads raw(…): . It stands for 1 output script. The checksum computed from the text is #89f8spxm: matches the written checksum.NO KEYS IN THIS DESCRIPTORraw( )deadbeef#89f8spxmWRITTEN CHECKSUM18 SYMBOLS → POLYMOD → #89f8spxmMATCHES THE WRITTEN CHECKSUMOUTPUT SCRIPTSdeadbeef
Reading a descriptorraw(deadbeef)#89f8spxm, from BIP 380 line 204. It reads raw(…): . It stands for 1 output script. The checksum computed from the text is #89f8spxm: matches the written checksum.NO KEYS IN THIS DESCRIPTORraw( )deadbeef#89f8spxmWRITTEN CHECKSUM18 SYMBOLS → POLYMOD → #89f8spxmMATCHES THE WRITTEN CHECKSUMOUTPUT SCRIPTSdeadbeef
Reading a descriptorraw(deedbeef)#89f8spxm, from BIP 380 line 209. It does not parse: checksum mismatch. The checksum computed from the text is #xj8ljs75: does not match: rejected.NO KEYS IN THIS DESCRIPTORraw(deedbeef)✕ REJECTED: DOES NOT PARSE#89f8spxmWRITTEN CHECKSUM18 SYMBOLS → POLYMOD → #xj8ljs75DOES NOT MATCH: REJECTEDOUTPUT SCRIPTSNONE: THE DESCRIPTOR IS REJECTED
Reading a descriptorraw(deedbeef)#89f8spxm, from BIP 380 line 209. It does not parse: checksum mismatch. The checksum computed from the text is #xj8ljs75: does not match: rejected.NO KEYS IN THIS DESCRIPTORraw(deedbeef)✕ REJECTED: DOES NOT PARSE#89f8spxmWRITTEN CHECKSUM18 SYMBOLS → POLYMOD → #xj8ljs75DOES NOT MATCH: REJECTEDOUTPUT SCRIPTSNONE: THE DESCRIPTOR IS REJECTED
Reading a descriptorpkh([deadbeef/1/2'/3/4']03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd), from BIP 381 line 80. It reads pkh(KEY): key 1 is a hex public key with origin [deadbeef/1/2h/3/4h]. It stands for 1 output script. The checksum computed from the text is #v0p5w8jl: computed here · none written, which is allowed.PUBLIC KEYS ONLY: REVEALS SCRIPTS, CANNOT SPENDpkh( )[deadbeef/1/2′/3/4′]03a34b99…#NO CHECKSUM WRITTEN122 SYMBOLS → POLYMOD → #v0p5w8jlCOMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS76a9149a1c78a507689f…KEY 1 OF 1 · HEX PUBLIC KEYorigin [deadbeef/1/2′/3/4′]after the key nonepublic key 03a34b99f2…
Reading a descriptorpkh([deadbeef/1/2'/3/4']03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd), from BIP 381 line 80. It reads pkh(KEY): key 1 is a hex public key with origin [deadbeef/1/2h/3/4h]. It stands for 1 output script. The checksum computed from the text is #v0p5w8jl: computed here · none written, which is allowed.PUBLIC KEYS ONLY: REVEALS SCRIPTS, CANNOT SPENDpkh( )[deadbeef/1/2′/3/4′]03a34b99…#NO CHECKSUM WRITTEN122 SYMBOLS → POLYMOD → #v0p5w8jlCOMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS76a9149a1c78a507689f…KEY 1 OF 1 · HEX PUBLIC KEYorigin [deadbeef/1/2′/3/4′]after the key nonepublic key 03a34b99f2…
Reading a descriptorsh(wpkh(xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi/10/20/30/40/*')), from BIP 382 line 71. It reads sh(wpkh(KEY)): key 1 is a extended private key, then /10/20/30/40/*h. It stands for 3 output scripts (the first children; the range continues). The checksum computed from the text is #qxqt7ymh: computed here · none written, which is allowed.HOLDS A PRIVATE KEY: A SPENDING SECRETRANGED: ONE SCRIPT PER CHILDsh( )wpkh( )xprv9s21ZrQH…/10/20/30/40/*′#NO CHECKSUM WRITTEN182 SYMBOLS → POLYMOD → #qxqt7ymhCOMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS/0′a9149a4d9901d6af519b…/1′a914bed59fc0024fae94…/2′a9148483aa1116eb9c05…… AND EVERY LATER CHILDKEY 1 OF 1 · EXTENDED PRIVATE KEYorigin noneafter the key /10/20/30/40/*′child 0′ public key 030a222cbb…child 1′ public key 028c22dde9…child 2′ public key 03823c2dee…PRIVATE: WHOEVER HAS THIS CAN SPEND
Reading a descriptorsh(wpkh(xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi/10/20/30/40/*')), from BIP 382 line 71. It reads sh(wpkh(KEY)): key 1 is a extended private key, then /10/20/30/40/*h. It stands for 3 output scripts (the first children; the range continues). The checksum computed from the text is #qxqt7ymh: computed here · none written, which is allowed.HOLDS A PRIVATE KEY: A SPENDING SECRETsh( )wpkh( )xprv9s21ZrQH…/10/20/30/40/*′#NO CHECKSUM WRITTEN182 SYMBOLS → POLYMOD → #qxqt7ymhCOMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS/0′a9149a4d9901d6af519b…/1′a914bed59fc0024fae94…/2′a9148483aa1116eb9c05…… AND EVERY LATER CHILDKEY 1 OF 1 · EXTENDED PRIVATE KEYorigin noneafter the key /10/20/30/40/*′child 0′ public key 030a222cbb…child 1′ public key 028c22dde9…child 2′ public key 03823c2dee…PRIVATE: WHOEVER HAS THIS CAN SPEND
Reading a descriptorsortedmulti(2,xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/*,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0/0/*), from BIP 383 line 80. It reads sortedmulti(2, KEY, KEY): key 1 is a extended public key, then /*; key 2 is a extended public key, then /0/0/*. It stands for 3 output scripts (the first children; the range continues). The checksum computed from the text is #lyw3zgk5: computed here · none written, which is allowed.PUBLIC KEYS ONLY: REVEALS SCRIPTS, CANNOT SPENDRANGED: ONE SCRIPT PER CHILDsortedmulti( )2xpub6ERApfZw…/*xpub68NZiKmJ…/0/0/*#NO CHECKSUM WRITTEN328 SYMBOLS → POLYMOD → #lyw3zgk5COMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS/05221025d5fc65ebb8d44…/152210264fd4d1f5dea8d…/25221022ccabda84c30ba…… AND EVERY LATER CHILDKEY 1 OF 2 · EXTENDED PUBLIC KEYorigin noneafter the key /*child 0 public key 025d5fc65e…child 1 public key 0264fd4d1f…child 2 public key 024d902e1a…
Reading a descriptorsortedmulti(2,xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/*,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0/0/*), from BIP 383 line 80. It reads sortedmulti(2, KEY, KEY): key 1 is a extended public key, then /*; key 2 is a extended public key, then /0/0/*. It stands for 3 output scripts (the first children; the range continues). The checksum computed from the text is #lyw3zgk5: computed here · none written, which is allowed.PUBLIC KEYS ONLY: REVEALS SCRIPTS, CANNOT SPENDsortedmulti( )2xpub6ERApfZw…/*xpub68NZiKmJ…/0/0/*#NO CHECKSUM WRITTEN328 SYMBOLS → POLYMOD → #lyw3zgk5COMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS/05221025d5fc65ebb8d44…/152210264fd4d1f5dea8d…/25221022ccabda84c30ba…… AND EVERY LATER CHILDKEY 1 OF 2 · EXTENDED PUBLIC KEYorigin noneafter the key /*child 0 public key 025d5fc65e…child 1 public key 0264fd4d1f…child 2 public key 024d902e1a…
Reading a descriptorcombo([01234567]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL), from BIP 384 line 47. It reads combo(KEY): key 1 is a extended public key with origin [01234567]. It stands for 4 output scripts. The checksum computed from the text is #7a7j2khf: computed here · none written, which is allowed.PUBLIC KEYS ONLY: REVEALS SCRIPTS, CANNOT SPENDcombo( )[01234567]xpub6ERApfZw…#NO CHECKSUM WRITTEN171 SYMBOLS → POLYMOD → #7a7j2khfCOMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTSP2PK2102d2b36900396c…P2PKH76a91431a507b815…P2WPKH001431a507b81559…P2SH-P2WPKHa9142aafb926eb24…KEY 1 OF 1 · EXTENDED PUBLIC KEYorigin [01234567]after the key nonepublic key 02d2b36900…
Reading a descriptorcombo([01234567]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL), from BIP 384 line 47. It reads combo(KEY): key 1 is a extended public key with origin [01234567]. It stands for 4 output scripts. The checksum computed from the text is #7a7j2khf: computed here · none written, which is allowed.PUBLIC KEYS ONLY: REVEALS SCRIPTS, CANNOT SPENDcombo( )[01234567]xpub6ERApfZw…#NO CHECKSUM WRITTEN171 SYMBOLS → POLYMOD → #7a7j2khfCOMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTSP2PK2102d2b36900396c…P2PKH76a91431a507b815…P2WPKH001431a507b81559…P2SH-P2WPKHa9142aafb926eb24…KEY 1 OF 1 · EXTENDED PUBLIC KEYorigin [01234567]after the key nonepublic key 02d2b36900…
Reading a descriptortr(a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd,{pk(xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334/0),{{pk(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL),pk(02df12b7035bdac8e3bab862a3a83d06ea6b17b6753d52edecba9be46f5d09e076)},pk(L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1)}}), from BIP 386 line 98. It reads tr(KEY, {pk(KEY), {{pk(KEY), pk(KEY)}, pk(KEY)}}): key 1 is used x-only, a x-only public key; key 2 is used x-only, a extended private key, then /0; key 3 is used x-only, a extended public key; key 4 is used x-only, a hex public key; key 5 is used x-only, a WIF private key. It stands for 1 output script. The checksum computed from the text is #9xus44vp: computed here · none written, which is allowed.HOLDS A PRIVATE KEY: A SPENDING SECRETtr( )a34b99f2…{ } SCRIPT TREEpk( )xprvA2JDeKCS…/0{ } BRANCH{ } BRANCHpk( )xpub6ERApfZw…pk( )02df12b7…pk( )L4rK1yDt…#NO CHECKSUM WRITTEN582 SYMBOLS → POLYMOD → #9xus44vpCOMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS512071fff39599a7b78b…KEY 1 OF 5 · X-ONLY PUBLIC KEY · INTERNAL KEYorigin noneafter the key nonex-only a34b99f22c…
Reading a descriptortr(a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd,{pk(xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334/0),{{pk(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL),pk(02df12b7035bdac8e3bab862a3a83d06ea6b17b6753d52edecba9be46f5d09e076)},pk(L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1)}}), from BIP 386 line 98. It reads tr(KEY, {pk(KEY), {{pk(KEY), pk(KEY)}, pk(KEY)}}): key 1 is used x-only, a x-only public key; key 2 is used x-only, a extended private key, then /0; key 3 is used x-only, a extended public key; key 4 is used x-only, a hex public key; key 5 is used x-only, a WIF private key. It stands for 1 output script. The checksum computed from the text is #9xus44vp: computed here · none written, which is allowed.HOLDS A PRIVATE KEY: A SPENDING SECRETtr( )a34b99f2…{ } SCRIPT TREEpk( )xprvA2JDeKCS…/0{ } BRANCH{ } BRANCHpk( )xpub6ERApfZw…pk( )02df12b7…pk( )L4rK1yDt…#NO CHECKSUM WRITTEN582 SYMBOLS → POLYMOD → #9xus44vpCOMPUTED HERE · NONE WRITTEN, WHICH IS ALLOWEDOUTPUT SCRIPTS512071fff39599a7b78b…KEY 1 OF 5 · X-ONLY PUBLIC KEY · INTERNAL KEYorigin noneafter the key nonex-only a34b99f22c…

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.

Choose a published example. Inspect its keys, resulting scripts and checksum; each expansion is checked against the scripts listed in the BIPs.81215161718
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

What does sharing the line reveal?

A descriptor containing only public keys lets another wallet derive the scripts to watch without handing it the private keys needed to sign. That is useful for a watch-only export. It also reveals which outputs belong together. Public-key material can still carry information you would not want to publish.417

A descriptor can also contain an xprv or a WIF private key. Those keys remain spending secrets when wrapped in a descriptor. Two lines that produce the same script may therefore have very different consequences if shared. One may expose a public key, while the other exposes its private counterpart.1417

Exporting a public descriptor sometimes requires more than replacing xprv with xpub. A public extended key cannot perform the intervening hardened derivations. The exporter has to move past those steps first, then record how it got there so a signer can still identify the key.1319

The rule for removing private keys from an export

BIP 380 says the exporter should derive the extended public key at the last hardened derivation step and use that key in the descriptor. The steps taken to reach it must be added to the previous origin information. The remaining derivation then starts from the exported key.19

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

A typo caught, a change notraw(deadbeef)#89f8spxm is BIP 380's valid vector: the checksum matches. raw(deedbeef)#89f8spxm changes character 7 and keeps the checksum: the computed checksum is #xj8ljs75, so it is rejected. But anyone can compute #xj8ljs75 for the altered text and write raw(deedbeef)#xj8ljs75, which passes: the checksum catches typos, not tampering.raw(deadbeef)#89f8spxm✓ MATCHES · BIP 380 LINE 204raw(deedbeef)#89f8spxm✕ TYPO CAUGHT · BIP 380 LINE 209 · COMPUTED #xj8ljs75raw(deedbeef)#xj8ljs75✓ MATCHES · COMPUTED HERE, NOT IN BIP 380 · NO KEY NEEDED
The middle line keeps the old checksum and fails. The bottom line has a newly calculated checksum and passes, even though its payload is still changed.182021
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

Where each expression may goBIP 380's index of script expressions (lines 302–344): pk(KEY), BIP 381: allowed at the top level, inside sh(), inside wsh(), inside tr(); pkh(KEY), BIP 381: allowed at the top level, inside sh(), inside wsh(); sh(SCRIPT), BIP 381: allowed at the top level; wpkh(KEY), BIP 382: allowed at the top level, inside sh(); wsh(SCRIPT), BIP 382: allowed at the top level, inside sh(); multi(NUM, KEY, ..., KEY), BIP 383: allowed at the top level, inside sh(), inside wsh(); sortedmulti(NUM, KEY, ..., KEY), BIP 383: allowed at the top level, inside sh(), inside wsh(); combo(KEY), BIP 384: allowed at the top level; raw(HEX), BIP 385: allowed at the top level; addr(ADDR), BIP 385: allowed at the top level; tr(KEY), BIP 386: allowed at the top level; tr(KEY, TREE), BIP 386: allowed at the top level; 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.TOPIN sh()IN wsh()IN tr()pk(KEY)381pkh(KEY)381sh(SCRIPT)381wpkh(KEY)382wsh(SCRIPT)382multi(NUM, KEY…383sortedmulti(NU…383combo(KEY)384raw(HEX)385addr(ADDR)385tr(KEY)386tr(KEY, TREE)386musig(KEY, KEY…390sp(KEY)392sp(KEY, KEY)392ALLOWED · HATCHED: NOT COVERED HERE
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
A dot marks an allowed context. Hatched rows belong to proposals outside this chapter’s source set.56711252627
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.

  1. ↩ 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.

    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.

    BIP 380, lines 26–29

    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.

    BIP 380, line 32

    The lack of derivation path information in these backups and exports leads to further incompatibilities between wallets.

    BIP 380, lines 32–33
  2. ↩ 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>.

    Quoted source text (3)

    <KEY> OP_CHECKSIG

    BIP 381, line 43

    OP_DUP OP_HASH160 <KEY_hash160> OP_EQUALVERIFY OP_CHECKSIG

    BIP 381, line 55

    OP_0 <KEY_hash160>

    BIP 382, line 41
  3. ↩ 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.

    BIP 380, lines 15–17
  4. ↩ 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.

    BIP 380, lines 39–43

    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.

    BIP 380, line 43
  5. ↩ 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.

    BIP 384, line 25

    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.

    BIP 384, lines 30–33
  6. ↩ 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.

    Quoted source text (4)

    Prior to the activation of Segregated Witness, there were 3 main standard output script formats: P2PK, P2PKH, and P2SH.

    BIP 381, lines 27–28

    The <tt>pk(KEY)</tt> expression can be used in any context or level of a descriptor.

    BIP 381, line 36

    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.

    BIP 381, line 48

    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.

    BIP 381, lines 60–63
  7. ↩ 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.

    BIP 382, lines 35–37

    Any key expression found in any script expression contained by a <tt>wsh()</tt> expression must only produce compressed public keys.

    BIP 382, line 50
  8. ↩ 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.

    BIP 381, line 72

    * <tt>tr(a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd,pkh(L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1))</tt>

    BIP 386, line 100
  9. ↩ 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.

    BIP 380, lines 54–61
  10. ↩ 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.

    BIP 381, line 27
  11. ↩ 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.

    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.

    BIP 386, lines 49–50

    <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.

    BIP 386, line 52

    <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.

    BIP 386, lines 63–66

    Uncompressed public keys are not allowed, but compressed public keys would be implicitly converted to x-only public keys.

    BIP 386, line 78
  12. ↩ 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.

    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)

    BIP 380, lines 70–74

    ** 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.

    BIP 380, lines 75–82

    the hardened indicator <tt>h</tt> may be replaced with alternative hardened indicator of <tt>'</tt>.

    BIP 380, line 89
  13. ↩ 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.

    BIP 380, lines 72–73
  14. ↩ 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.

    BIP 380, line 66

    * <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>

    BIP 381, lines 78–83
  15. ↩ 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.

    BIP 380, line 85
  16. ↩ 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.

    BIP 380, lines 48–50
  17. ↩ 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)

    BIP 380, lines 79–80
  18. ↩ 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

    BIP 380, lines 192–196
  19. ↩ 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.

    BIP 380, lines 93–95
  20. ↩ 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>

    BIP 380, lines 204–211
  21. ↩ 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>

    BIP 380, lines 204–209
  22. ↩ 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.

    BIP 380, line 101

    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).

    BIP 380, lines 111–112
  23. ↩ 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.

    BIP 380, lines 184–187
  24. ↩ 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.

    Quoted source text (3)

    The checksum is an error correcting checksum similar to bech32.

    BIP 380, line 118

    * 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.

    BIP 380, lines 127–132

    * Random errors have a chance of 1 in 240 of being undetected.

    BIP 380, line 132
  25. ↩ 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.

    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>.

    BIP 383, lines 33–35

    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.

    BIP 383, lines 41–47

    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.

    BIP 383, lines 60–61

    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.

    BIP 383, lines 65–66
  26. ↩ 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.

    BIP 385, line 26

    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.

    BIP 385, lines 34–36
  27. ↩ 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).

    Quoted source text (2)

    Script expressions will be specified in additional BIPs. This Table lists all available Script expressions and the BIPs specifying them.

    BIP 380, lines 299–300

    | <tt>musig(KEY, KEY, ..., KEY)</tt> | [[bip-0390.mediawiki|390]] |- | <tt>sp(KEY)</tt>, <tt>sp(KEY, KEY)</tt> | [[bip-0392.mediawiki|392]]

    BIP 380, lines 339–343
  28. ↩ 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]].

    BIP 386, lines 116–118
  29. ↩ 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

    BIP 380, lines 3–9

    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

    BIP 386, lines 4–11
  30. ↩ 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.

    BIP 380, line 268

    <tt>tr()</tt> descriptors have been implemented in Bitcoin Core since version 22.0.

    BIP 386, line 122
  31. ↩ 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.

    BIP 380, line 36