diff --git a/README.mediawiki b/README.mediawiki index f3dbcda1..d3143d3e 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -1050,6 +1050,55 @@ Those proposing changes should consider that ultimately consent may rest with th | Andrew Chow | Standard | Draft +|- +| [[bip-0380.mediawiki|380]] +| Applications +| Output Script Descriptors General Operation +| Pieter Wuille, Andrew Chow +| Informational +| Draft +|- +| [[bip-0381.mediawiki|381]] +| Applications +| Non-Segwit Output Script Descriptors +| Pieter Wuille, Andrew Chow +| Informational +| Draft +|- +| [[bip-0382.mediawiki|382]] +| Applications +| Segwit Output Script Descriptors +| Pieter Wuille, Andrew Chow +| Informational +| Draft +|- +| [[bip-0383.mediawiki|383]] +| Applications +| Multisig Output Script Descriptors +| Pieter Wuille, Andrew Chow +| Informational +| Draft +|- +| [[bip-0384.mediawiki|384]] +| Applications +| combo() Output Script Descriptors +| Pieter Wuille, Andrew Chow +| Informational +| Draft +|- +| [[bip-0385.mediawiki|385]] +| Applications +| raw() and addr() Output Script Descriptors +| Pieter Wuille, Andrew Chow +| Informational +| Draft +|- +| [[bip-0386.mediawiki|386]] +| Applications +| tr() Output Script Descriptors +| Pieter Wuille, Andrew Chow +| Informational +| Draft |} diff --git a/bip-0380.mediawiki b/bip-0380.mediawiki new file mode 100644 index 00000000..d57bbc69 --- /dev/null +++ b/bip-0380.mediawiki @@ -0,0 +1,277 @@ +
+  BIP: 380
+  Layer: Applications
+  Title: Output Script Descriptors General Operation
+  Author: Pieter Wuille 
+          Andrew Chow 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0380
+  Status: Draft
+  Type: Informational
+  Created: 2021-06-27
+  License: BSD-2-Clause
+
+ +==Abstract== + +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. + +==Copyright== + +This BIP is licensed under the BSD 2-clause license. + +==Motivation== + +Bitcoin wallets traditionally have stored a set of keys which are later serialized and mutated to produce the output scripts that the wallet watches and the addresses it provides to users. +Typically backups have consisted of solely the private keys, nowadays primarily in the form of BIP 39 mnemonics. +However this backup solution is insuffient, 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. +This has lead to incompatibilities between wallets when restoring a backup or exporting data for a watch only wallet. + +Further complicating matters are BIP 32 derivation paths. +Although BIPs 44, 49, and 84 have specified standard BIP 32 derivation paths for different output scripts and addresses, not all wallets support them nor use those derivation paths. +The lack of derivation path information in these backups and exports leads to further incompatibilities between wallets. + +Current solutions to these issues have not been generic and can be viewed as being layer violations. +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. + +Output Script Descriptors introduces a generic solution to these issues. +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. +With the general structure specified in this BIP, new Script Expressions can be introduced as new script types are added. +Lastly, 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. + +==Specification== + +Descriptors consist of several types of expressions. +The top level expression is a SCRIPT. +This expression may be followed by #CHECKSUM, where CHECKSUM is an 8 character alphanumeric descriptor checksum. + +===Script Expressions=== + +Script Expressions (denoted SCRIPT) 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. +Expressions are written with a human readable identifier string with the arguments enclosed with parentheses. +The identifier string should be alphanumeric and may include underscores. + +The arguments to a script expression are defined by that expression itself. +They could be a script expression, a key expression, or some other expression entirely. + +===Key Expressions=== + +A common expression used as an argument to script expressions are key expressions (denoted KEY). +These represent a public or private key and, optionally, information about the origin of that key. +Key expressions can only be used as arguments to script expressions. + +Key expressions consist of: +* Optionally, key origin information, consisting of: +** An open bracket [ +** Exactly 8 hex characters for the fingerprint of the key where the derivation starts (see BIP 32 for details) +** Followed by zero or more /NUM or /NUMh path elements to indicate the unhardened or hardened derivation steps between the fingerprint and the key that follows. +** A closing bracket ] +* Followed by the actual key, which is either: +** A hex encoded public key, which depending the script expression, may be either: +*** 66 hex character string beginning with 02 or 03 representing a compressed public key +*** 130 hex character string beginning with 04 representing an uncompressed public key +** A [[https://en.bitcoin.it/wiki/Wallet_import_format|WIF]] encoded private key +** xpub encoded extended public key or xprv encoded extended private key (as defined in BIP 32) +*** Followed by zero or more /NUM or /NUMh path elements indicating BIP 32 derivation steps to be taken after the given extended key. +*** Optionally followed by a single /* or /*h final step to denote all direct unhardened or hardened children. + +If the KEY is a BIP 32 extended key, before output scripts can be created, child keys must be derived using the derivation information that follows the extended key. +When the final step is /* or /*', an output script will be produced for every child key index. +The derived key must be not be serialized as an uncompressed public key. +Script Expressions may have further requirements on how derived public keys are serialized for script creation. + +In the above specification, the hardened indicator h may be replaced with alternative hardened indicators of H or '. + +====Normalization of Key Expressions with Hardened Derivation==== + +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. +If there is no key origin information, then one must be added for the newly derived extended public key. +If the final derivation is hardened, then it is not necessary to do additional derivation. + +===Character Set=== + +The expressions used in descriptors must only contain characters within this character set so that the descriptor checksum will work. + +The allowed characters are: +
+0123456789()[],'/*abcdefgh@:$%{}
+IJKLMNOPQRSTUVWXYZ&+-.;<=>?!^_|~
+ijklmnopqrstuvwxyzABCDEFGH`#"\
+
+Note that on the last line is a space character. + +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). +Case errors cause an offset that is a multiple of 32 while as many alphabetic characters are in the same group while following the previous restrictions. + +===Checksum=== + +Following the top level script expression is a single octothorpe (#) followed by the 8 character checksum. +The checksum is an error correcting checksum similar to bech32. + +The checksum has the following properties: +* Mistakes in a descriptor string are measured in "symbol errors". The higher the number of symbol errors, the harder it is to detect: +** An error substituting a character from 0123456789()[],'/*abcdefgh@:$%{} for another in that set always counts as 1 symbol error. +*** Note that hex encoded keys are covered by these characters. Extended keys (xpub and xprv) use other characters too, but also have their own checksum mechanism. +*** SCRIPT expression function names use other characters, but mistakes in these would generally result in an unparsable descriptor. +** A case error always counts as 1 symbol error. +** Any other 1 character substitution error counts as 1 or 2 symbol errors. +* 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. +* Is optimized to minimize the chance of a 5 symbol error in a descriptor up to 387 characters is undetected +* Random errors have a chance of 1 in 240 of being undetected. + +The checksum itself uses the same character set as bech32: qpzry9x8gf2tvdw0s3jn54khce6mua7l + +Valid descriptor strings with a checksum must pass the criteria for validity specified by the Python3 code snippet below. +The function descsum_check must return true when its argument s is a descriptor consisting in the form SCRIPT#CHECKSUM. + +
+INPUT_CHARSET = "0123456789()[],'/*abcdefgh@:$%{}IJKLMNOPQRSTUVWXYZ&+-.;<=>?!^_|~ijklmnopqrstuvwxyzABCDEFGH`#\"\\ "
+CHECKSUM_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"
+GENERATOR = [0xf5dee51989, 0xa9fdca3312, 0x1bab10e32d, 0x3706b1677a, 0x644d626ffd]
+
+def descsum_polymod(symbols):
+    """Internal function that computes the descriptor checksum."""
+    chk = 1
+    for value in symbols:
+        top = chk >> 35
+        chk = (chk & 0x7ffffffff) << 5 ^ value
+        for i in range(5):
+            chk ^= GENERATOR[i] if ((top >> i) & 1) else 0
+    return chk
+
+def descsum_expand(s):
+    """Internal function that does the character to symbol expansion"""
+    groups = []
+    symbols = []
+    for c in s:
+        if not c in INPUT_CHARSET:
+            return None
+        v = INPUT_CHARSET.find(c)
+        symbols.append(v & 31)
+        groups.append(v >> 5)
+        if len(groups) == 3:
+            symbols.append(groups[0] * 9 + groups[1] * 3 + groups[2])
+            groups = []
+    if len(groups) == 1:
+        symbols.append(groups[0])
+    elif len(groups) == 2:
+        symbols.append(groups[0] * 3 + groups[1])
+    return symbols
+
+def descsum_check(s):
+    """Verify that the checksum is correct in a descriptor"""
+    if s[-9] != '#':
+        return False
+    if not all(x in CHECKSUM_CHARSET for x in s[-8:]):
+        return False
+    symbols = descsum_expand(s[:-9]) + [CHECKSUM_CHARSET.find(x) for x in s[-8:]]
+    return descsum_polymod(symbols) == 1
+
+ +This implements a BCH code that has the properties described above. +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. + +To construct a valid checksum given a script expression, the code below can be used: + +
+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
+    return s + '#' + ''.join(CHECKSUM_CHARSET[(checksum >> (5 * (7 - i))) & 31] for i in range(8))
+
+
+ +==Backwards Compatibility== + +Output script descriptors are an entirely new language which is not compatible with any existing software. +However many components of the expressions reuse encodings and serializations defined by previous BIPs. + +Output script descriptors are designed for future extension with further fragment types and new script expressions. +These will be specified in additional BIPs. + +==Reference Implemntation== + +Descriptors have been implemented in Bitcoin Core since version 0.17. + +==Appendix A: Index of Expressions== + +Future BIPs may specify additional types of expressions. +All available expression types are listed in this table. + +{| +! Name +! Denoted As +! BIP +|- +| Script +| SCRIPT +| 380 +|- +| Key +| KEY +| 380 +|- +| Tree +| TREE +| [[bip-0386.mediawiki|386]] +|} + +==Appendix B: Index of Script Expressions== + +Script expressions will be specified in additional BIPs. +This Table lists all available Script expressions and the BIPs specifying them. + +{| +! Expression +! BIP +|- +| pk(KEY) +| [[bip-0381.mediawiki|381]] +|- +| pkh(KEY) +| [[bip-0381.mediawiki|381]] +|- +| sh(SCRIPT) +| [[bip-0381.mediawiki|381]] +|- +| wpkh(KEY) +| [[bip-0382.mediawiki|382]] +|- +| wsh(SCRIPT) +| [[bip-0382.mediawiki|382]] +|- +| multi(NUM, KEY, ..., KEY) +| [[bip-0383.mediawiki|383]] +|- +| sortedmulti(NUM, KEY, ..., KEY) +| [[bip-0383.mediawiki|383]] +|- +| combo(KEY) +| [[bip-0384.mediawiki|384]] +|- +| raw(HEX) +| [[bip-0385.mediawiki|385]] +|- +| addr(ADDR) +| [[bip-0385.mediawiki|385]] +|- +| tr(KEY), tr(KEY, TREE) +| [[bip-0386.mediawiki|386]] +|} diff --git a/bip-0381.mediawiki b/bip-0381.mediawiki new file mode 100644 index 00000000..8d7e3917 --- /dev/null +++ b/bip-0381.mediawiki @@ -0,0 +1,83 @@ +
+  BIP: 381
+  Layer: Applications
+  Title: Non-Segwit Output Script Descriptors
+  Author: Pieter Wuille 
+          Andrew Chow 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0381
+  Status: Draft
+  Type: Informational
+  Created: 2021-06-27
+  License: BSD-2-Clause
+
+ +==Abstract== + +This document specifies pk(), pkh(), and sh() output script descriptors. +pk() descriptors take a key and produces a P2PK output script. +pkh() descriptors take a key and produces a P2PKH output script. +sh() descriptors take a script and produces a P2SH output script. + +==Copyright== + +This BIP is licensed under the BSD 2-clause license. + +==Motivation== + +Prior to the activation of Segregated Witness, there were 3 main standard output script formats: P2PK, P2PKH, and P2SH. +These expressions allow specifying those formats as a descriptor. + +==Specification== + +Three new script expressions are defined: pk(), pkh(), and sh(). + +===pk()=== + +The pk(KEY) expression can be used in any context or level of a descriptor. +It takes a single key expression as an argument and produces a P2PK output script. +Depending on the higher level descriptors, there may be restrictions on the type of public keys that can be included. +Such restrictions will be specified by those descriptors. + +The output script produced is: +
+ OP_CHECKSIG
+
+ +===pkh()=== + +The pkh(KEY) expression can be used as a top level expression, or inside of either a sh() or wsh() descriptor. +It takes a single key expression as an argument and produces a P2PKH output script. +Depending on the higher level descriptors, there may be restrictions on the type of public keys that can be included. +Such restrictions will be specified by those descriptors. + +The output script produced is: +
+OP_DUP OP_HASH160  OP_EQUALVERIFY OP_CHECKSIG
+
+ +===sh()=== + +The sh(SCRIPT) 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. +sh() expressions also create a redeemScript which is required in order to spend outputs which use its output script. +This redeemScript is the output script produced by the SCRIPT argument to sh(). + +The output script produced is: +
+OP_HASH160  OP_EQUAL
+
+ +==Test Vectors== + +TBD + +==Backwards Compatibility== + +pk(), pkh(), and sh() descriptors use the format and general operation specified in [[bip-0380.mediawiki|380]]. +As these are a wholly new descriptors, they are not compatible with any implementation. +However the scripts produced are standard scripts so existing software are likely to be familiar with them. + +==Reference Implemntation== + +pk(), pkh(), and sh() descriptors have been implemented in Bitcoin Core since version 0.17. diff --git a/bip-0382.mediawiki b/bip-0382.mediawiki new file mode 100644 index 00000000..0508d2b7 --- /dev/null +++ b/bip-0382.mediawiki @@ -0,0 +1,70 @@ +
+  BIP: 382
+  Layer: Applications
+  Title: Segwit Output Script Descriptors
+  Author: Pieter Wuille 
+          Andrew Chow 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0382
+  Status: Draft
+  Type: Informational
+  Created: 2021-06-27
+  License: BSD-2-Clause
+
+ +==Abstract== + +This document specifies wpkh(), and wsh() output script descriptors. +wpkh() descriptors take a key and produces a P2WPKH output script. +wsh() descriptors take a script and produces a P2WSH output script. + +==Copyright== + +This BIP is licensed under the BSD 2-clause license. + +==Motivation== + +Segregated Witness added 2 additional standard output script formats: P2WPKH and P2WSH. +These expressions allow specifying those formats as a descriptor. + +==Specification== + +Two new script expressions are defined: wpkh(), and wsh(). + +===wpkh()=== + +The wpkh(KEY) expression can be used as a top level expression, or inside of a sh() descriptor. +It takes a single key expression as an argument and produces a P2WPKH output script. +Only keys which are/has compressed public keys can be contained in a wpkh() expression. + +The output script produced is: +
+OP_0 
+
+ +===wsh()=== + +The wsh(SCRIPT) expression can be used as a top level expression, or inside of a sh() descriptor. +It takes a single script expression as an argument and produces a P2WSH output script. +wsh() expressions also create a witnessScript which is required in order to spend outputs which use its output script. +This redeemScript is the output script produced by the SCRIPT argument to wsh(). +Any key expression found in any script expression contained by a wsh() expression must only produce compressed public keys. + +The output script produced is: +
+OP_0 
+
+ +==Test Vectors== + +TBD + +==Backwards Compatibility== + +wpkh(), and wsh() descriptors use the format and general operation specified in [[bip-0380.mediawiki|380]]. +As these are a wholly new descriptors, they are not compatible with any implementation. +However the scripts produced are standard scripts so existing software are likely to be familiar with them. + +==Reference Implemntation== + +wpkh(), and wsh() descriptors have been implemented in Bitcoin Core since version 0.17. diff --git a/bip-0383.mediawiki b/bip-0383.mediawiki new file mode 100644 index 00000000..6b749506 --- /dev/null +++ b/bip-0383.mediawiki @@ -0,0 +1,78 @@ +
+  BIP: 383
+  Layer: Applications
+  Title: Multisig Output Script Descriptors
+  Author: Pieter Wuille 
+          Andrew Chow 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0383
+  Status: Draft
+  Type: Informational
+  Created: 2021-06-27
+  License: BSD-2-Clause
+
+ +==Abstract== + +This document specifies multi(), and sortedmulti() output script descriptors. +Both functions take a threshold and one or more public keys and produce a multisig output script. +multi() specifies the public keys in the output script in the order given in the descriptor while sortedmulti() sorts the public keys lexicographically when the output script is produced. + +==Copyright== + +This BIP is licensed under the BSD 2-clause license. + +==Motivation== + +The most common complex script used in Bitcoin is a threshold multisig. +These expressions allow specifying multisig scripts as a descriptor. + +==Specification== + +Two new script expressions are defined: multi(), and sortedmulti(). +Both expressions produce the scripts of the same template and take the same arguments. +They are written as multi(k,KEY_1,KEY_2,...,KEY_n). +k is the threshold - the number of keys that must sign the input for the script to be valid. +KEY_1,KEY_2,...,KEY_n are the key expressions for the multisig. k must be less than or equal to n. + +multi() and sortedmulti() expressions can be used as a top level expression, or inside of either a sh() or wsh() descriptor. +Depending on the higher level descriptors, there may be restrictions on the type of public keys that can be included. + +Depending on the higher level descriptors, there are also restrictions on the number of keys that can be present, i.e. the maximum value of n. +When used at the top level, there can only be at most 3 keys. +When used inside of a sh() expression, there can only be most 15 compressed public keys (this is limited by the P2SH script limit). +Otherwise the maximum number of keys is 20. + +The output script produced also depends on the value of k. If k is less than or equal to 16: +
+OP_k KEY_1 KEY_2 ... KEY_n OP_CHECKMULTISIG
+
+ +if k is greater than 16: +
+k KEY_1 KEY_2 ... KEY_n OP_CHECKMULTISIG
+
+ +===sortedmulti()=== + +The only change for sortedmulti() 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. + +===Multiple Extended Keys=== + +When one or more the key expressions in a multi() or sortedmulti() expression are extended keys, the derived keys use the same child index. +This changes the keys in lockstep and allows for output scripts to be indexed in the same way that the derived keys are indexed. + +==Test Vectors== + +TBD + +==Backwards Compatibility== + +multi(), and sortedmulti() descriptors use the format and general operation specified in [[bip-0380.mediawiki|380]]. +As these are a wholly new descriptors, they are not compatible with any implementation. +However the scripts produced are standard scripts so existing software are likely to be familiar with them. + +==Reference Implemntation== + +multi(), and multi() descriptors have been implemented in Bitcoin Core since version 0.17. diff --git a/bip-0384.mediawiki b/bip-0384.mediawiki new file mode 100644 index 00000000..da7cb236 --- /dev/null +++ b/bip-0384.mediawiki @@ -0,0 +1,48 @@ +
+  BIP: 384
+  Layer: Applications
+  Title: combo() Output Script Descriptors
+  Author: Pieter Wuille 
+          Andrew Chow 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0384
+  Status: Draft
+  Type: Informational
+  Created: 2021-06-27
+  License: BSD-2-Clause
+
+ +==Abstract== + +This document specifies combo() output script descriptors. +These take a key and produce P2PK, P2PKH, P2WPKH, and P2SH-P2WPKH output scripts if applicable to the key. + +==Copyright== + +This BIP is licensed under the BSD 2-clause license. + +==Motivation== + +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. + +==Specification== + +A new top level script expression is defined: combo(KEY). +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 combo() expression always produces a P2PK and P2PKH script, the same as putting the key in both a pk() and a pkh() expression. +If the key is/has a compressed public key, then P2WPKH and P2SH-P2WPKH scripts are also produced, the same as putting the key in both a wpkh() and sh(wpkh()) expression. + +==Test Vectors== + +TBD + +==Backwards Compatibility== + +combo() descriptors use the format and general operation specified in [[bip-0380.mediawiki|380]]. +As this is a wholly new descriptor, it is not compatible with any implementation. +However the scripts produced are standard scripts so existing software are likely to be familiar with them. + +==Reference Implemntation== + +combo descriptors have been implemented in Bitcoin Core since version 0.17. diff --git a/bip-0385.mediawiki b/bip-0385.mediawiki new file mode 100644 index 00000000..2469eb0c --- /dev/null +++ b/bip-0385.mediawiki @@ -0,0 +1,57 @@ +
+  BIP: 385
+  Layer: Applications
+  Title: raw() and addr() Output Script Descriptors
+  Author: Pieter Wuille 
+          Andrew Chow 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0385
+  Status: Draft
+  Type: Informational
+  Created: 2021-06-27
+  License: BSD-2-Clause
+
+ +==Abstract== + +This document specifies raw() and addr() output script descriptors. +raw() encapsulates a raw script as a descriptor. +addr() encapsulates an address as a descriptor. + +==Copyright== + +This BIP is licensed under the BSD 2-clause license. + +==Motivation== + +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. + +==Specification== + +Two new script expressions are defined: raw() and addr(). + +===raw()=== + +The raw(HEX) expression can only be used as a top level descriptor. +As the argument, it takes a hex string representing a Bitcoin script. +The output script produced by this descriptor is the script represented by HEX. + +===addr()=== + +The addr(ADDR) expression can only be used as a top level descriptor. +It takes an address as its single argument. +The output script produced by this descriptor is the output script produced by the address ADDR. + +==Test Vectors== + +TBD + +==Backwards Compatibility== + +raw() and addr() descriptors use the format and general operation specified in [[bip-0380.mediawiki|380]]. +As this is a wholly new descriptor, it is not compatible with any implementation. +The reuse of existing Bitcoin addresses allows for this to be more easily implemented. + +==Reference Implemntation== + +raw() and addr descriptors have been implemented in Bitcoin Core since version 0.17. diff --git a/bip-0386.mediawiki b/bip-0386.mediawiki new file mode 100644 index 00000000..d90e801a --- /dev/null +++ b/bip-0386.mediawiki @@ -0,0 +1,101 @@ +
+  BIP: 386
+  Layer: Applications
+  Title: tr() Output Script Descriptors
+  Author: Pieter Wuille 
+          Andrew Chow 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0386
+  Status: Draft
+  Type: Informational
+  Created: 2021-06-27
+  License: BSD-2-Clause
+
+ +==Abstract== + +This document specifies tr() output script descriptors. +tr() descriptors take a key and optionally a tree of scripts and produces a P2TR output script. + +==Copyright== + +This BIP is licensed under the BSD 2-clause license. + +==Motivation== + +Taproot added one additional standard output script format: P2TR. +These expressions allow specifying those formats as a descriptor. + +==Specification== + +A new script expression is defined: tr(). +A new expression is defined: Tree Expressions + +===Tree Expression=== + +A Tree Expression (denoted TREE) is an expression which represents a tree of scripts. +The way the tree is represented in an output script is dependent on the higher level expressions. + +A Tree Expression is: +* Any Script Expression that is allowed at the level this Tree Expression is in. +* A pair of Tree Expressions consisting of: +** An open brace { +** A Tree Expression +** A comma , +** A Tree Expression +** A closing brace } + +===tr()=== + +The tr(KEY) or tr(KEY, TREE) expression can only be used as a top level expression. +All key expressions under any tr() expression must create x-only public keys. + +tr(KEY) takes a single key expression as an argument and produces a P2TR output script which does not have a script path. +Each key produced by the key expression is used as the internal key of a P2TR output as specified by [[bip-0341.mediawiki#cite_ref-22-0|BIP 341]]. +Specifically, "If the spending conditions do not require a script path, the output key should commit to an unspendable script path instead of having no script path. +This can be achieved by computing the output key point as ''Q = P + int(hashTapTweak(bytes(P)))G''." + +
+internal_key:       lift_x(KEY)
+32_byte_output_key: internal_key + int(HashTapTweak(bytes(internal_key)))G
+scriptPubKey:       OP_1 <32_byte_output_key>
+
+ +tr(KEY, TREE) 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. +The keys produced by the first key expression are used as the internal key as specified by [[bip-0341.mediawiki#Constructing_and_spending_Taproot_outputs|BIP 341]]. +The Tree expression becomes the Taproot script tree as described in BIP 341. +A merkle root is computed from this tree and combined with the internal key to create the Taproot output key. + +
+internal_key:       lift_x(KEY)
+merkle_root:        HashTapBranch(TREE)
+32_byte_output_key: internal_key + int(HashTapTweak(bytes(internal_key) || merkle_root))G
+scriptPubKey:       OP_1 <32_byte_output_key>
+
+ +===Modified Key Expression=== + +Key Expressions within a tr() expression must only create x-only public keys. +Uncompressed public keys are not allowed, but compressed public keys would be implicitly converted to x-only public keys. +The keys derived from extended keys must be serialized as x-only public keys. +An additional key expression is defined only for use within a tr() descriptor: + +* A 64 hex character string representing an x-only public key + +==Test Vectors== + +TBD + +==Backwards Compatibility== + +tr() descriptors use the format and general operation specified in [[bip-0380.mediawiki|380]]. +As these are a set of wholly new descriptors, they are not compatible with any implementation. +However the scripts produced are standard scripts so existing software are likely to be familiar with them. + +Tree Expressions are largely incompatible with existing script expressions due to the restrictions in those expressions. +As of 2021-06-27, the only allowed script expression that can be used in a tree expression is pk(). +However there will be future BIPs that specify script expressions that can be used in tree expressions. + +==Reference Implementation== + +tr() descriptors have been implemented in Bitcoin Core since version 22.0.