diff options
46 files changed, 2734 insertions, 554 deletions
diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..732da86 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.mediawiki linguist-detectable diff --git a/README.mediawiki b/README.mediawiki index b3c2f97..f558246 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -258,6 +258,13 @@ Those proposing changes should consider that ultimately consent may rest with th | Justus Ranvier | Informational | Draft +|- style="background-color: #ffffcf" +| [[bip-0048.mediawiki|48]] +| Applications +| Multi-Script Hierarchy for Multi-Sig Wallets +| Fontaine +| Standard +| Proposed |- style="background-color: #cfffcf" | [[bip-0049.mediawiki|49]] | Applications @@ -441,6 +448,13 @@ Those proposing changes should consider that ultimately consent may rest with th | Ethan Kosakovsky | Informational | Draft +|- +| [[bip-0086.mediawiki|86]] +| Applications +| Key Derivation for Single Key P2TR Outputs +| Andrew Chow +| Standard +| Draft |- style="background-color: #ffffcf" | [[bip-0087.mediawiki|87]] | Applications @@ -598,8 +612,8 @@ Those proposing changes should consider that ultimately consent may rest with th |- | [[bip-0118.mediawiki|118]] | Consensus (soft fork) -| SIGHASH_NOINPUT -| Christian Decker +| SIGHASH_ANYPREVOUT for Taproot Scripts +| Christian Decker, Anthony Towns | Standard | Draft |- @@ -1036,6 +1050,62 @@ Those proposing changes should consider that ultimately consent may rest with th | Andrew Chow | Standard | Draft +|- +| [[bip-0371.mediawiki|371]] +| Applications +| Taproot Fields for PSBT +| 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 |} <!-- IMPORTANT! See the instructions at the top of this page, do NOT JUST add BIPs here! --> diff --git a/bip-0002.mediawiki b/bip-0002.mediawiki index 35d38c2..c6eb950 100644 --- a/bip-0002.mediawiki +++ b/bip-0002.mediawiki @@ -41,14 +41,14 @@ It also helps to make sure the idea is applicable to the entire community and no Once the champion has asked the Bitcoin community as to whether an idea has any chance of acceptance, a draft BIP should be presented to the [https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev Bitcoin development mailing list]. This gives the author a chance to flesh out the draft BIP to make it properly formatted, of high quality, and to address additional concerns about the proposal. Following a discussion, the proposal should be submitted to the [https://github.com/bitcoin/bips BIPs git repository] as a pull request. -This draft must be written in BIP style as described below, and named with an alias such as "bip-johndoe-infinitebitcoins" until the editor has assigned it a BIP number (authors MUST NOT self-assign BIP numbers). +This draft must be written in BIP style as described below, and named with an alias such as "bip-johndoe-infinitebitcoins" until an editor has assigned it a BIP number (authors MUST NOT self-assign BIP numbers). BIP authors are responsible for collecting community feedback on both the initial idea and the BIP before submitting it for review. However, wherever possible, long open-ended discussions on public mailing lists should be avoided. Strategies to keep the discussions efficient include: setting up a separate SIG mailing list for the topic, having the BIP author accept private comments in the early design phases, setting up a wiki page or git repository, etc. BIP authors should use their discretion here. It is highly recommended that a single BIP contain a single key proposal or new idea. The more focused the BIP, the more successful it tends to be. If in doubt, split your BIP into several well-focused ones. -When the BIP draft is complete, the BIP editor will assign the BIP a number, label it as Standards Track, Informational, or Process, and merge the pull request to the BIPs git repository. -The BIP editor will not unreasonably reject a BIP. +When the BIP draft is complete, a BIP editor will assign the BIP a number, label it as Standards Track, Informational, or Process, and merge the pull request to the BIPs git repository. +The BIP editors will not unreasonably reject a BIP. Reasons for rejecting BIPs include duplication of effort, disregard for formatting rules, being too unfocused or too broad, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the Bitcoin philosophy. For a BIP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. @@ -61,16 +61,19 @@ The BIP author may update the draft as necessary in the git repository. Updates It occasionally becomes necessary to transfer ownership of BIPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred BIP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the BIP process, or has fallen off the face of the 'net (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the BIP. We try to build consensus around a BIP, but if that's not possible, you can always submit a competing BIP. -If you are interested in assuming ownership of a BIP, send a message asking to take over, addressed to both the original author and the BIP editor. If the original author doesn't respond to email in a timely manner, the BIP editor will make a unilateral decision (it's not like such decisions can't be reversed :). +If you are interested in assuming ownership of a BIP, send a message asking to take over, addressed to both the original author and the BIP editors. If the original author doesn't respond to email in a timely manner, the BIP editors will make a unilateral decision (it's not like such decisions can't be reversed :). ===BIP Editors=== -The current BIP editor is Luke Dashjr who can be contacted at [[mailto:luke_bipeditor@dashjr.org|luke_bipeditor@dashjr.org]]. +The current BIP editors are: + +* Luke Dashjr ([[mailto:luke_bipeditor@dashjr.org|luke_bipeditor@dashjr.org]]) +* Kalle Alm ([[mailto:karljohan-alm@garage.co.jp|karljohan-alm@garage.co.jp]]) ===BIP Editor Responsibilities & Workflow=== -The BIP editor subscribes to the Bitcoin development mailing list. -Off-list BIP-related correspondence should be sent (or CC'd) to luke_bipeditor@dashjr.org. +The BIP editors subscribe to the Bitcoin development mailing list. +Off-list BIP-related correspondence should be sent (or CC'd) to the BIP editors. For each new BIP that comes in an editor does the following: @@ -186,7 +189,7 @@ The typical paths of the status of BIPs are as follows: <img src="bip-0002/process.png"></img> Champions of a BIP may decide on their own to change the status between Draft, Deferred, or Withdrawn. -The BIP editor may also change the status to Deferred when no progress is being made on the BIP. +A BIP editor may also change the status to Deferred when no progress is being made on the BIP. A BIP may only change status from Draft (or Rejected) to Proposed, when the author deems it is complete, has a working implementation (where applicable), and has community plans to progress it to the Final status. diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index c9fcd6f..f7fbad1 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -197,7 +197,7 @@ Miners MAY clear or set bits in the block version WITHOUT any special "mutable" Softfork deployment names listed in "rules" or as keys in "vbavailable" may be prefixed by a '!' character. Without this prefix, GBT clients may assume the rule will not impact usage of the template as-is; typical examples of this would be when previously valid transactions cease to be valid, such as BIPs [[bip-0016.mediawiki|16]], [[bip-0065.mediawiki|65]], [[bip-0066.mediawiki|66]], [[bip-0068.mediawiki|68]], [[bip-0112.mediawiki|112]], and [[bip-0113.mediawiki|113]]. If a client does not understand a rule without the prefix, it may use it unmodified for mining. -On the other hand, when this prefix is used, it indicates a more subtle change to the block structure or generation transaction; examples of this would be BIP 34 (because it modifies coinbase construction) and 141 (since it modifies the txid hashing and adds a commitment to the generation transaction). +On the other hand, when this prefix is used, it indicates a more subtle change to the block structure or generation transaction; examples of this would be [[bip-0034.mediawiki|BIP 34]] (because it modifies coinbase construction) and [[bip-0141.mediawiki|141]] (since it modifies the txid hashing and adds a commitment to the generation transaction). A client that does not understand a rule prefixed by '!' must not attempt to process the template, and must not attempt to use it for mining even unmodified. ==Support for future changes== @@ -205,7 +205,7 @@ A client that does not understand a rule prefixed by '!' must not attempt to pro The mechanism described above is very generic, and variations are possible for future soft forks. Here are some ideas that can be taken into account. '''Modified thresholds''' -The 1916 threshold (based on in BIP 34's 95%) does not have to be maintained for eternity, but changes should take the effect on the warning system into account. In particular, having a lock-in threshold that is incompatible with the one used for the warning system may have long-term effects, as the warning system cannot rely on a permanently detectable condition anymore. +The 1916 threshold (based on BIP 34's 95%) does not have to be maintained for eternity, but changes should take the effect on the warning system into account. In particular, having a lock-in threshold that is incompatible with the one used for the warning system may have long-term effects, as the warning system cannot rely on a permanently detectable condition anymore. '''Conflicting soft forks''' At some point, two mutually exclusive soft forks may be proposed. The naive way to deal with this is to never create software that implements both, but that is making a bet that at least one side is guaranteed to lose. Better would be to encode "soft fork X cannot be locked-in" as consensus rule for the conflicting soft fork - allowing software that supports both, but can never trigger conflicting changes. diff --git a/bip-0016.mediawiki b/bip-0016.mediawiki index 0f4fb81..abc27d6 100644 --- a/bip-0016.mediawiki +++ b/bip-0016.mediawiki @@ -40,7 +40,7 @@ The rules for validating these outpoints when relaying transactions or consideri # Normal validation is done: an initial stack is created from the signatures and {serialized script}, and the hash of the script is computed and validation fails immediately if it does not match the hash in the outpoint. # {serialized script} is popped off the initial stack, and the transaction is validated again using the popped stack and the deserialized script as the scriptPubKey. -These new rules should only be applied when validating transactions in blocks with timestamps >= 1333238400 (Apr 1 2012) <ref>[https://github.com/bitcoin/bitcoin/commit/8f188ece3c82c4cf5d52a3363e7643c23169c0ff Remove -bip16 and -paytoscripthashtime command-line arguments]</ref>. There are transactions earlier than 1333238400 in the block chain that fail these new validation rules. <ref>[http://blockexplorer.com/tx/6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192 Transaction 6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192]</ref>. Older transactions must be validated under the old rules. (see the Backwards Compatibility section for details). +These new rules should only be applied when validating transactions in blocks with timestamps >= 1333238400 (Apr 1 2012) <ref>[https://github.com/bitcoin/bitcoin/commit/8f188ece3c82c4cf5d52a3363e7643c23169c0ff Remove -bip16 and -paytoscripthashtime command-line arguments]</ref>. There are transactions earlier than 1333238400 in the block chain that fail these new validation rules. <ref>[https://web.archive.org/web/20141122040355/http://blockexplorer.com/tx/6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192 Transaction 6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192]</ref>. Older transactions must be validated under the old rules. (see the Backwards Compatibility section for details). For example, the scriptPubKey and corresponding scriptSig for a one-signature-required transaction is: diff --git a/bip-0021.mediawiki b/bip-0021.mediawiki index cfab856..0fba9bc 100644 --- a/bip-0021.mediawiki +++ b/bip-0021.mediawiki @@ -58,10 +58,9 @@ The scheme component ("bitcoin:") is case-insensitive, and implementations must *label: Label for that address (e.g. name of receiver) *address: bitcoin address *message: message that describes the transaction to the user ([[#Examples|see examples below]]) -*size: amount of base bitcoin units ([[#Transfer amount/size|see below]]) *(others): optional, for future extensions -==== Transfer amount/size ==== +==== Transfer amount ==== If an amount is provided, it MUST be specified in decimal BTC. All amounts MUST contain no commas and use a period (.) as the separating character to separate whole numbers and decimal fractions. diff --git a/bip-0032.mediawiki b/bip-0032.mediawiki index f2f1e48..ee09b68 100644 --- a/bip-0032.mediawiki +++ b/bip-0032.mediawiki @@ -4,6 +4,7 @@ RECENT CHANGES: * (25 May 2013) Added test vectors * (15 Jan 2014) Rename keys with index ≥ 0x80000000 to hardened keys, and add explicit conversion functions. * (24 Feb 2017) Added test vectors for hardened derivation with leading zeros +* (4 Nov 2020) Added new test vectors for hardened derivation with leading zeros <pre> BIP: 32 @@ -118,7 +119,7 @@ To shorten notation, we will write CKDpriv(CKDpriv(CKDpriv(m,3<sub>H</sub>),2),5 * N(m/a<sub>H</sub>/b/c) = N(m/a<sub>H</sub>/b)/c = N(m/a<sub>H</sub>)/b/c. However, N(m/a<sub>H</sub>) cannot be rewritten as N(m)/a<sub>H</sub>, as the latter is not possible. -Each leaf node in the tree corresponds to an actual key, while the internal nodes correspond to the collections of keys that descend from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is relevant. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant non-hardened public keys. +Each leaf node in the tree corresponds to an actual key, while the internal nodes correspond to the collections of keys that descend from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is relevant. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public key allows reconstruction of all descendant non-hardened public keys. ===Key identifiers=== @@ -150,7 +151,7 @@ The total number of possible extended keypairs is almost 2<sup>512</sup>, but th * Calculate I = HMAC-SHA512(Key = "Bitcoin seed", Data = S) * Split I into two 32-byte sequences, I<sub>L</sub> and I<sub>R</sub>. * Use parse<sub>256</sub>(I<sub>L</sub>) as master secret key, and I<sub>R</sub> as master chain code. -In case I<sub>L</sub> is 0 or ≥n, the master key is invalid. +In case parse<sub>256</sub>(I<sub>L</sub>) is 0 or parse<sub>256</sub>(I<sub>L</sub>) ≥ n, the master key is invalid. <img src=bip-0032/derivation.png></img> @@ -272,6 +273,41 @@ Seed (hex): 4b381541583be4423346c643850da4b320e46a87ae3d2a4e6da11eba819cd4acba45 ** ext pub: xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y ** ext prv: xprv9uPDJpEQgRQfDcW7BkF7eTya6RPxXeJCqCJGHuCJ4GiRVLzkTXBAJMu2qaMWPrS7AANYqdq6vcBcBUdJCVVFceUvJFjaPdGZ2y9WACViL4L +===Test vector 4=== + +These vectors test for the retention of leading zeros. See [https://github.com/btcsuite/btcutil/issues/172 btcsuite/btcutil#172] for more information. + +Seed (hex): 3ddd5602285899a946114506157c7997e5444528f3003f6134712147db19b678 +* Chain m +** ext pub: xpub661MyMwAqRbcGczjuMoRm6dXaLDEhW1u34gKenbeYqAix21mdUKJyuyu5F1rzYGVxyL6tmgBUAEPrEz92mBXjByMRiJdba9wpnN37RLLAXa +** ext prv: xprv9s21ZrQH143K48vGoLGRPxgo2JNkJ3J3fqkirQC2zVdk5Dgd5w14S7fRDyHH4dWNHUgkvsvNDCkvAwcSHNAQwhwgNMgZhLtQC63zxwhQmRv +* Chain m/0<sub>H</sub> +** ext pub: xpub69AUMk3qDBi3uW1sXgjCmVjJ2G6WQoYSnNHyzkmdCHEhSZ4tBok37xfFEqHd2AddP56Tqp4o56AePAgCjYdvpW2PU2jbUPFKsav5ut6Ch1m +** ext prv: xprv9vB7xEWwNp9kh1wQRfCCQMnZUEG21LpbR9NPCNN1dwhiZkjjeGRnaALmPXCX7SgjFTiCTT6bXes17boXtjq3xLpcDjzEuGLQBM5ohqkao9G +* Chain m/0<sub>H</sub>/1<sub>H</sub> +** ext pub: xpub6BJA1jSqiukeaesWfxe6sNK9CCGaujFFSJLomWHprUL9DePQ4JDkM5d88n49sMGJxrhpjazuXYWdMf17C9T5XnxkopaeS7jGk1GyyVziaMt +** ext prv: xprv9xJocDuwtYCMNAo3Zw76WENQeAS6WGXQ55RCy7tDJ8oALr4FWkuVoHJeHVAcAqiZLE7Je3vZJHxspZdFHfnBEjHqU5hG1Jaj32dVoS6XLT1 + +===Test vector 5=== + +These vectors test that invalid extended keys are recognized as invalid. + +* xpub661MyMwAqRbcEYS8w7XLSVeEsBXy79zSzH1J8vCdxAZningWLdN3zgtU6LBpB85b3D2yc8sfvZU521AAwdZafEz7mnzBBsz4wKY5fTtTQBm (pubkey version / prvkey mismatch) +* xprv9s21ZrQH143K24Mfq5zL5MhWK9hUhhGbd45hLXo2Pq2oqzMMo63oStZzFGTQQD3dC4H2D5GBj7vWvSQaaBv5cxi9gafk7NF3pnBju6dwKvH (prvkey version / pubkey mismatch) +* xpub661MyMwAqRbcEYS8w7XLSVeEsBXy79zSzH1J8vCdxAZningWLdN3zgtU6Txnt3siSujt9RCVYsx4qHZGc62TG4McvMGcAUjeuwZdduYEvFn (invalid pubkey prefix 04) +* xprv9s21ZrQH143K24Mfq5zL5MhWK9hUhhGbd45hLXo2Pq2oqzMMo63oStZzFGpWnsj83BHtEy5Zt8CcDr1UiRXuWCmTQLxEK9vbz5gPstX92JQ (invalid prvkey prefix 04) +* xpub661MyMwAqRbcEYS8w7XLSVeEsBXy79zSzH1J8vCdxAZningWLdN3zgtU6N8ZMMXctdiCjxTNq964yKkwrkBJJwpzZS4HS2fxvyYUA4q2Xe4 (invalid pubkey prefix 01) +* xprv9s21ZrQH143K24Mfq5zL5MhWK9hUhhGbd45hLXo2Pq2oqzMMo63oStZzFAzHGBP2UuGCqWLTAPLcMtD9y5gkZ6Eq3Rjuahrv17fEQ3Qen6J (invalid prvkey prefix 01) +* xprv9s2SPatNQ9Vc6GTbVMFPFo7jsaZySyzk7L8n2uqKXJen3KUmvQNTuLh3fhZMBoG3G4ZW1N2kZuHEPY53qmbZzCHshoQnNf4GvELZfqTUrcv (zero depth with non-zero parent fingerprint) +* xpub661no6RGEX3uJkY4bNnPcw4URcQTrSibUZ4NqJEw5eBkv7ovTwgiT91XX27VbEXGENhYRCf7hyEbWrR3FewATdCEebj6znwMfQkhRYHRLpJ (zero depth with non-zero parent fingerprint) +* xprv9s21ZrQH4r4TsiLvyLXqM9P7k1K3EYhA1kkD6xuquB5i39AU8KF42acDyL3qsDbU9NmZn6MsGSUYZEsuoePmjzsB3eFKSUEh3Gu1N3cqVUN (zero depth with non-zero index) +* xpub661MyMwAuDcm6CRQ5N4qiHKrJ39Xe1R1NyfouMKTTWcguwVcfrZJaNvhpebzGerh7gucBvzEQWRugZDuDXjNDRmXzSZe4c7mnTK97pTvGS8 (zero depth with non-zero index) +* DMwo58pR1QLEFihHiXPVykYB6fJmsTeHvyTp7hRThAtCX8CvYzgPcn8XnmdfHGMQzT7ayAmfo4z3gY5KfbrZWZ6St24UVf2Qgo6oujFktLHdHY4 (unknown extended key version) +* DMwo58pR1QLEFihHiXPVykYB6fJmsTeHvyTp7hRThAtCX8CvYzgPcn8XnmdfHPmHJiEDXkTiJTVV9rHEBUem2mwVbbNfvT2MTcAqj3nesx8uBf9 (unknown extended key version) +* xprv9s21ZrQH143K24Mfq5zL5MhWK9hUhhGbd45hLXo2Pq2oqzMMo63oStZzF93Y5wvzdUayhgkkFoicQZcP3y52uPPxFnfoLZB21Teqt1VvEHx (private key 0 not in 1..n-1) +* xprv9s21ZrQH143K24Mfq5zL5MhWK9hUhhGbd45hLXo2Pq2oqzMMo63oStZzFAzHGBP2UuGCqWLTAPLcMtD5SDKr24z3aiUvKr9bJpdrcLg1y3G (private key n not in 1..n-1) +* xpub661MyMwAqRbcEYS8w7XLSVeEsBXy79zSzH1J8vCdxAZningWLdN3zgtU6Q5JXayek4PRsn35jii4veMimro1xefsM58PgBMrvdYre8QyULY (invalid pubkey 020000000000000000000000000000000000000000000000000000000000000007) +* xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHL (invalid checksum) ==Acknowledgements== diff --git a/bip-0038.mediawiki b/bip-0038.mediawiki index bfe1f4a..511b55a 100644 --- a/bip-0038.mediawiki +++ b/bip-0038.mediawiki @@ -66,7 +66,7 @@ To keep the size of the encrypted key down, no initialization vectors (IVs) are * Count of payload bytes (beyond prefix): 37 ** 1 byte (''flagbyte''): *** the most significant two bits are set as follows to preserve the visibility of the compression flag in the prefix, as well as to keep the payload within the range of allowable values that keep the "6P" prefix intact. For non-EC-multiplied keys, the bits are 11. For EC-multiplied keys, the bits are 00. -*** the bit with value 0x20 when set indicates the key should be converted to a bitcoin address using the compressed public key format. +*** the bit with value 0x20 when set indicates the key should be converted to a base58check encoded P2PKH bitcoin address using the DER compressed public key format. When not set, it should be a base58check encoded P2PKH bitcoin address using the DER uncompressed public key format. *** the bits with values 0x10 and 0x08 are reserved for a future specification that contemplates using multisig as a way to combine the factors such that parties in possession of the separate factors can independently sign a proposed transaction without requiring that any party possess both factors. These bits must be 0 to comply with this version of the specification. *** the bit with value 0x04 indicates whether a lot and sequence number are encoded into the first factor, and activates special behavior for including them in the decryption process. This applies to EC-multiplied keys only. Must be 0 for non-EC-multiplied keys. *** remaining bits are reserved for future use and must all be 0 to comply with this version of the specification. diff --git a/bip-0039.mediawiki b/bip-0039.mediawiki index 9d38248..4ac3c55 100644 --- a/bip-0039.mediawiki +++ b/bip-0039.mediawiki @@ -163,7 +163,7 @@ Haskell: * https://github.com/NicolasDorier/NBitcoin JavaScript: -* https://github.com/bitpay/bitcore-mnemonic +* https://github.com/bitpay/bitcore/tree/master/packages/bitcore-mnemonic * https://github.com/bitcoinjs/bip39 (used by [[https://github.com/blockchain/My-Wallet-V3/blob/v3.8.0/src/hd-wallet.js#L121-L146|blockchain.info]]) Java: @@ -176,6 +176,9 @@ Rust: * https://github.com/maciejhirsz/tiny-bip39/ * https://github.com/koushiro/bip0039-rs +Smalltalk: +* https://github.com/eMaringolo/pharo-bip39mnemonic + Swift: * https://github.com/CikeQiu/CKMnemonic * https://github.com/yuzushioh/WalletKit diff --git a/bip-0043.mediawiki b/bip-0043.mediawiki index 67b799d..32e02b1 100644 --- a/bip-0043.mediawiki +++ b/bip-0043.mediawiki @@ -42,6 +42,8 @@ We encourage different schemes to apply for assigning a separate BIP number and use the same number for purpose field, so addresses won't be generated from overlapping BIP32 spaces. +Purpose codes from 10001 to 19999 are reserved for [[https://github.com/satoshilabs/slips|SLIPs]]. + Example: Scheme described in BIP44 should use 44' (or 0x8000002C) as purpose. Note that m / 0' / * is already taken by BIP32 (default account), which diff --git a/bip-0048.mediawiki b/bip-0048.mediawiki new file mode 100644 index 0000000..dbfac3f --- /dev/null +++ b/bip-0048.mediawiki @@ -0,0 +1,251 @@ +<pre> + BIP: 48 + Layer: Applications + Title: Multi-Script Hierarchy for Multi-Sig Wallets + Author: Fontaine <dentondevelopment@protonmail.com> + Comments-Summary: No comments + Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0048 + Status: Proposed + Type: Standards Track + Created: 2020-12-16 + License: MIT +</pre> + +==Abstract== + +This BIP defines a logical hierarchy for deterministic multi-sig wallets based on an algorithm +described in BIP-0067 (BIP67 from now on), BIP-0032 (BIP32 from now on), purpose scheme described in +BIP-0043 (BIP43 from now on), and multi-account hierarchy described in +BIP-0044 (BIP44 from now on). + +This BIP is a particular application of BIP43. + +==Copyright== + +This BIP falls under the MIT License. + +==Motivation== + +The motivation of this BIP is to define the existing industry wide practice of utilizing m/48' +derivation paths in hierarchical deterministic multi-sig wallets so that other developers may +benefit from a standard. This BIP allows for future script types to easily be appended to the +specification so that a new BIP is not required for every future script type. + +The hierarchy proposed in this paper is quite comprehensive. It allows the handling of +multiple accounts, external and internal chains per account, multiple script types and +millions of addresses per chain. + +This paper was inspired from BIP44. + +==Backwards compatibility== + +Currently a number of wallets utilize the <code>m/48'</code> derivation scheme for HD multi-sig accounts. +This BIP is intended to maintain the *existing* real world use of the <code>m/48'</code> derivation. +No breaking changes are made so as to avoid "loss of funds" to existing users. +Wallets which currently support the <code>m/48'</code> derivation will not need to make any changes +to comply with this BIP. + +==Specification== + +===Key sorting=== + +Any wallet that supports BIP48 inherently supports deterministic key sorting as per BIP67 so that all possible +multi-signature addresses/scripts are derived from deterministically sorted public keys. + +===Path levels=== + +We define the following 6 levels in BIP32 path: + +<pre> +m / purpose' / coin_type' / account' / script_type' / change / address_index +</pre> + +<code>h</code> or <code>'</code> in the path indicates that BIP32 hardened derivation is used. + +Each level has a special meaning, described in the chapters below. + +===Purpose=== + +Purpose is a constant set to 48' following the BIP43 recommendation. +It indicates that the subtree of this node is used according to this specification. + +Hardened derivation is used at this level. + +===Coin type=== + +One master node (seed) can be used for multiple Bitcoin networks. +Sharing the same space for various networks has some disadvantages. + +Avoiding reusing addresses across networks and improving privacy issues. + +Coin type <code>0</code> for mainnet and <code>1</code> for testnet. + +Hardened derivation is used at this level. + +===Account=== + +This level splits the key space into independent user identities, following the BIP44 pattern, +so the wallet never mixes the coins across different accounts. + +Users can use these accounts to organize the funds in the same +fashion as bank accounts; for donation purposes (where all +addresses are considered public), for saving purposes, +for common expenses etc. + +Accounts are numbered from index 0 in sequentially increasing manner. +This number is used as child index in BIP32 derivation. + +Hardened derivation is used at this level. + +===Script=== + +This level splits the key space into two separate <code>script_type</code>(s). To provide +forward compatibility for future script types this specification can be easily extended. + +Currently the only script types covered by this BIP are Native Segwit (p2wsh) and +Nested Segwit (p2sh-p2wsh). + +The following path represents Nested Segwit (p2sh-p2wsh) mainnet, account 0: +<code>1'</code>: Nested Segwit (p2sh-p2wsh) <code>m/48'/0'/0'/1'</code></br> + +The following path represents Native Segwit (p2wsh) mainnet, account 0: +<code>2'</code>: Native Segwit (p2wsh) <code>m/48'/0'/0'/2'</code></br> + +The recommended default for wallets is pay to witness script hash <code>m/48'/0'/0'/2'</code>. + +To add new script types submit a PR to this specification and include it in the list above: +<code>X'</code>: Future script type <code>m/48'/0'/0'/X'</code></br> + +===Change=== + +Constant 0 is used for external chain and constant 1 for internal chain (also +known as change addresses). External chain is used for addresses that are meant +to be visible outside of the wallet (e.g. for receiving payments). Internal +chain is used for addresses which are not meant to be visible outside of the +wallet and is used for return transaction change. + +Public derivation is used at this level. + +===Index=== + +Addresses are numbered from index 0 in sequentially increasing manner. +This number is used as child index in BIP32 derivation. + +Public derivation is used at this level. + +==Examples== + +{| +|network +|account +|script +|chain +|address +|path +|- +|mainnet +|first +|p2wsh +|external +|first +|m / 48' / 0' / 0' / 2' / 0 / 0 +|- +|mainnet +|first +|p2wsh +|external +|second +|m / 48' / 0' / 0' / 2' / 0 / 1 +|- +|mainnet +|first +|p2wsh +|change +|first +|m / 48' / 0' / 0' / 2' / 1 / 0 +|- +|mainnet +|first +|p2wsh +|change +|second +|m / 48' / 0' / 0' / 2' / 1 / 1 +|- +|mainnet +|second +|p2wsh +|external +|first +|m / 48' / 0' / 1' / 2' / 0 / 0 +|- +|mainnet +|second +|p2wsh +|external +|second +|m / 48' / 0' / 1' / 2' / 0 / 1 +|- +|testnet +|first +|p2sh-p2wsh +|external +|first +|m / 48' / 1' / 0' / 1' / 0 / 0 +|- +|testnet +|first +|p2wsh +|external +|second +|m / 48' / 1' / 0' / 2' / 0 / 1 +|- +|testnet +|first +|p2wsh +|change +|first +|m / 48' / 1' / 0' / 2' / 1 / 0 +|- +|testnet +|first +|p2wsh +|change +|second +|m / 48' / 1' / 0' / 2' / 1 / 1 +|- +|testnet +|second +|p2wsh +|external +|first +|m / 48' / 1' / 1' / 2' / 0 / 0 +|- +|testnet +|second +|p2wsh +|external +|second +|m / 48' / 1' / 1' / 2' / 0 / 1 +|- +|testnet +|second +|p2wsh +|change +|first +|m / 48' / 1' / 1' / 2' / 1 / 0 +|- +|testnet +|second +|p2wsh +|change +|second +|m / 48' / 1' / 1' / 2' / 1 / 1 +|} + + +==Reference== + +* [[bip-0067.mediawiki|BIP67 - Deterministic Pay-to-script-hash multi-signature addresses through public key sorting]] +* [[bip-0032.mediawiki|BIP32 - Hierarchical Deterministic Wallets]] +* [[bip-0043.mediawiki|BIP43 - Purpose Field for Deterministic Wallets]] +* [[bip-0044.mediawiki|BIP44 - Multi-Account Hierarchy for Deterministic Wallets]] diff --git a/bip-0067.mediawiki b/bip-0067.mediawiki index b164289..793039d 100644 --- a/bip-0067.mediawiki +++ b/bip-0067.mediawiki @@ -124,7 +124,7 @@ The authors wish to thank BtcDrak and Luke-Jr for their involvement & contributi ==Usage & Implementations== * [[https://github.com/bitcoin/bips/blob/master/bip-0045.mediawiki#address-generation-procedure|BIP-0045]] - Structure for Deterministic P2SH Multisignature Wallets * [[https://github.com/bitpay/bitcore/blob/50a868cb8cdf2be04bb1c5bf4bcc064cc06f5888/lib/script/script.js#L541|Bitcore]] -* [[https://github.com/haskoin/haskoin/blob/master/Network/Haskoin/Script/Parser.hs#L112-122|Haskoin]] Bitcoin implementation in haskell +* [[https://github.com/haskoin/haskoin-core/blob/b41b1deb0989334a7ead6fc993fb8b02f0c00810/haskoin-core/Network/Haskoin/Script/Parser.hs#L112-L122|Haskoin]] - Bitcoin implementation in Haskell * [[https://github.com/etotheipi/BitcoinArmory/blob/268db0f3fa20c989057bd43343a43b2edbe89aeb/armoryengine/ArmoryUtils.py#L1441|Armory]] * [[https://github.com/bitcoinj/bitcoinj/blob/master/core/src/main/java/org/bitcoinj/script/ScriptBuilder.java#L331|BitcoinJ]] diff --git a/bip-0069.mediawiki b/bip-0069.mediawiki index 3aa9463..7b5034e 100644 --- a/bip-0069.mediawiki +++ b/bip-0069.mediawiki @@ -147,7 +147,7 @@ Outputs: ==References== * [[https://bitcoinmagazine.com/20273/bitstamp-exchange-activity-trackable-due-multisig-wallet-implementation/|1: Bitstamp Info Leak]] -* [[https://github.com/OpenBitcoinPrivacyProject/wallet-ratings/blob/master/2015-1/criteria.md|2: OBPP Random Indexing as Countermeasure]] +* [[https://github.com/OpenBitcoinPrivacyProject/wallet-ratings/blob/5a7e2e1555e91bb48edeca3aa710272777d98c2a/2015-1/criteria.md|2: OBPP Random Indexing as Countermeasure]] * [[https://github.com/aantonop/bitcoinbook/blob/develop/ch05.asciidoc|3: Mastering Bitcoin]] * [[https://en.bitcoin.it/wiki/Script|4: Bitcoin Wiki on Script]] * [[http://www.cplusplus.com/reference/algorithm/lexicographical_compare|5: std::lexicographical_compare]] diff --git a/bip-0078.mediawiki b/bip-0078.mediawiki index c795343..1893f0e 100644 --- a/bip-0078.mediawiki +++ b/bip-0078.mediawiki @@ -209,7 +209,7 @@ In such case, the receiver will need to increase the fee of the transaction afte * The sender's wallet software is using round fee rate. If the sender's fee rate is always round, then a blockchain analyst can easily spot the transactions of the sender involving payjoin by checking if, when removing a single input to the suspected payjoin transaction, the resulting fee rate is round. -To prevent this, the sender can agree to pay more more fee so the receiver make sure that the payjoin transaction fee is also round. +To prevent this, the sender can agree to pay more fee so the receiver make sure that the payjoin transaction fee is also round. * The sender's transaction is time sensitive. @@ -229,6 +229,9 @@ Our recommendation for <code>maxadditionalfeecontribution=</code> is <code>origi |- |P2SH-P2WPKH |91 +|- +|P2TR +|58 |} @@ -249,7 +252,7 @@ The receiver needs to do some check on the original PSBT before proceeding: ===Sender's payjoin proposal checklist=== The sender should check the payjoin proposal before signing it to prevent a malicious receiver from stealing money. - + * Verify that the absolute fee of the payjoin proposal is equals or higher than the original PSBT. * If the receiver's BIP21 signalled <code>pjos=0</code>, disable payment output substitution. * Verify that the transaction version, and the nLockTime are unchanged. @@ -272,7 +275,7 @@ The sender should check the payjoin proposal before signing it to prevent a mali ** If the output is the [[#fee-output|fee output]]: *** The amount that was substracted from the output's value is less than or equal to <code>maxadditionalfeecontribution</code>. Let's call this amount <code>actual contribution</code>. *** Make sure the actual contribution is only paying fee: The <code>actual contribution</code> is less than or equals to the difference of absolute fee between the payjoin proposal and the original PSBT. -*** Make sure the actual contribution is only paying for fee incurred by additional inputs: <code>actual contribution</code> is less than or equals to <code>originalPSBTFeeRate * vsize(sender_input_type) * (count(original_psbt_inputs) - count(payjoin_proposal_inputs))</code>. (see [[#fee-output|Fee output]] section) +*** Make sure the actual contribution is only paying for fee incurred by additional inputs: <code>actual contribution</code> is less than or equals to <code>originalPSBTFeeRate * vsize(sender_input_type) * (count(payjoin_proposal_inputs) - count(original_psbt_inputs))</code>. (see [[#fee-output|Fee output]] section) ** If the output is the payment output and payment output substitution is allowed. *** Do not make any check ** Else @@ -325,7 +328,7 @@ Because the receiver needs to bump the fee to keep the same fee rate as the orig The validation (policy and consensus) of the original transaction is optional: a receiver without a full node can decide to create the payjoin transaction and automatically broadcast the original transaction after a timeout of 1 minute, and only verify that it has been propagated in the network. -However, non-interactive receivers (like a payment processor) need to verify the transaction to prevent UTXO probing attacks. +However, non-interactive receivers (like a payment processor) need to verify the transaction to prevent UTXO probing attacks. This is not a concern for interactive receivers like Wasabi Wallet, because those receivers can just limit the number of original PSBT proposals of a specific address to one. With such wallets, the attacker has no way to generate new deposit addresses to probe the UTXOs. @@ -498,7 +501,7 @@ public async Task<PSBT> RequestPayjoin( if (proposedPSBTInput.NonWitnessUtxo != null || proposedPSBTInput.WitnessUtxo != null) throw new PayjoinSenderException("The receiver added non_witness_utxo or witness_utxo to one of our inputs"); sequences.Add(proposedTxIn.Sequence); - + // Fill up the info from the original PSBT input so we can sign and get fees. proposedPSBTInput.NonWitnessUtxo = input.SignedPSBTInput.NonWitnessUtxo; proposedPSBTInput.WitnessUtxo = input.SignedPSBTInput.WitnessUtxo; @@ -541,10 +544,16 @@ public async Task<PSBT> RequestPayjoin( // Verify that no keypaths is in the PSBT output if (proposedPSBTOutput.HDKeyPaths.Count != 0) throw new PayjoinSenderException("The receiver added keypaths to an output"); - bool isOriginalOutput = originalOutputs.Count > 0 && originalOutputs.Peek().OriginalTxOut.ScriptPubKey == proposedPSBTOutput.ScriptPubKey; - if (isOriginalOutput) + if (originalOutputs.Count == 0) + continue; + var originalOutput = originalOutputs.Peek(); + bool isOriginalOutput = originalOutput.OriginalTxOut.ScriptPubKey == proposedPSBTOutput.ScriptPubKey; + bool substitutedOutput = !isOriginalOutput && + allowOutputSubstitution && + originalOutput.OriginalTxOut.ScriptPubKey == paymentScriptPubKey; + if (isOriginalOutput || substitutedOutput) { - var originalOutput = originalOutputs.Dequeue(); + originalOutputs.Dequeue(); if (output.OriginalTxOut == feeOutput) { var actualContribution = feeOutput.Value - proposedPSBTOutput.Value; @@ -637,7 +646,7 @@ A successful exchange with: !maxadditionalfeecontribution !additionalfeeoutputindex |- -|P2SH-P2WSH +|P2SH-P2WPKH |2 sat/vbyte |0.00000182 |0 @@ -660,7 +669,7 @@ A successful exchange with: * [[https://github.com/BlueWallet/BlueWallet|BlueWallet]] is in the process of implementing the protocol. * [[https://github.com/btcpayserver/btcpayserver|BTCPay Server]] has implemented sender and receiver side of this protocol. * [[https://github.com/zkSNACKs/WalletWasabi/|Wasabi Wallet]] has merged sender's support. -* [[https://github.com/JoinMarket-Org/joinmarket-clientserver|Join Market]] is in the process of implementing the protocol. +* [[https://github.com/JoinMarket-Org/joinmarket-clientserver|Join Market]] has implemented sender and receiver side of this protocol. * [[https://github.com/bitcoinjs/payjoin-client|JavaScript sender implementation]]. ==Backward compatibility== diff --git a/bip-0085.mediawiki b/bip-0085.mediawiki index b0131c3..6e7dd0e 100644 --- a/bip-0085.mediawiki +++ b/bip-0085.mediawiki @@ -104,6 +104,8 @@ OUTPUT * Ian Coleman's Mnemonic Code Converter: [https://github.com/iancoleman/bip39] and [https://iancoleman.io/bip39/] +* AirGap Vault: [https://github.com/airgap-it/airgap-vault/commit/d64332fc2f332be622a1229acb27f621e23774d6] + btc_hd_wallet: [https://github.com/scgbckbone/btc-hd-wallet] ==Applications== diff --git a/bip-0086.mediawiki b/bip-0086.mediawiki new file mode 100644 index 0000000..f724884 --- /dev/null +++ b/bip-0086.mediawiki @@ -0,0 +1,128 @@ +<pre> + BIP: 86 + Layer: Applications + Title: Key Derivation for Single Key P2TR Outputs + Author: Andrew Chow <andrew@achow101.com> + Comments-Summary: No comments yet. + Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0086 + Status: Draft + Type: Standards Track + Created: 2021-06-22 + License: BSD-2-Clause +</pre> + +==Abstract== + +This document suggests a derivation scheme for HD wallets whose keys are involved in single key +P2TR ([[bip-0341.mediawiki|BIP 341]]) outputs as the Taproot internal key. + +===Copyright=== + +This BIP is licensed under the 2-clause BSD license. + +==Motivation== + +With the usage of single key P2TR transactions, it is useful to have a common derivation scheme so +that HD wallets that only have a backup of the HD seed can be likely to recover single key Taproot +outputs. Although there are now solutions which obviate the need for fixed derivation paths for +specific script types, many software wallets and hardware signers still use seed backups which +lack derivation path and script information. Thus we largely use the same approach used in BIPs +[[bip-0049.mediawiki|49]] and [[bip-0084.mediawiki|84]] for ease of implementation. + +==Specifications== + +This BIP defines the two needed steps to derive multiple deterministic addresses based on a +[[bip-0032.mediawiki|BIP 32]] master private key. + +===Public key derivation=== + +To derive a public key from the root account, this BIP uses the same account-structure as +defined in BIPs [[bip-0044.mediawiki|44]], [[bip-0049.mediawiki|49]], and [[bip-0084.mediawiki|84]], +but with a different purpose value for the script type. + +<pre> +m / purpose' / coin_type' / account' / change / address_index +</pre> + +For the <tt>purpose</tt>-path level it uses <tt>86'</tt>. +The rest of the levels are used as defined in BIPs 44, 49, and 84. + +A key derived with this derivation path pattern will be referred to as <tt>derived_key</tt> further +in this document. + +===Address derivation=== + + +[[bip-0341.mediawiki#cite_ref-22-0|BIP 341]] states: "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(hash<sub>TapTweak</sub>(bytes(P)))G''." Thus: + +<pre> +internal_key: lift_x(derived_key) +32_byte_output_key: internal_key + int(HashTapTweak(bytes(internal_key)))G +</pre> + +In a transaction, the scripts and witnesses are as defined in +[[bip-0341.mediawiki#specification|BIP 341]]: + +<pre> +witness: <signature> +scriptSig: (empty) +scriptPubKey: 1 <32_byte_output_key> + (0x5120{32_byte_output_key}) +</pre> + +==Backwards Compatibility== + +This BIP is not backwards compatible by design. +An incompatible wallet will not discover these accounts at all and the user will notice that +something is wrong. + +However this BIP uses the same method used in BIPs 44, 49, and 84, so it should not be difficult +to implement. + +==Test vectors== + +<pre> +mnemonic = abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about +rootpriv = xprv9s21ZrQH143K3GJpoapnV8SFfukcVBSfeCficPSGfubmSFDxo1kuHnLisriDvSnRRuL2Qrg5ggqHKNVpxR86QEC8w35uxmGoggxtQTPvfUu +rootpub = xpub661MyMwAqRbcFkPHucMnrGNzDwb6teAX1RbKQmqtEF8kK3Z7LZ59qafCjB9eCRLiTVG3uxBxgKvRgbubRhqSKXnGGb1aoaqLrpMBDrVxga8 + +// Account 0, root = m/86'/0'/0' +xprv = xprv9xgqHN7yz9MwCkxsBPN5qetuNdQSUttZNKw1dcYTV4mkaAFiBVGQziHs3NRSWMkCzvgjEe3n9xV8oYywvM8at9yRqyaZVz6TYYhX98VjsUk +xpub = xpub6BgBgsespWvERF3LHQu6CnqdvfEvtMcQjYrcRzx53QJjSxarj2afYWcLteoGVky7D3UKDP9QyrLprQ3VCECoY49yfdDEHGCtMMj92pReUsQ + +// Account 0, first receiving address = m/86'/0'/0'/0/0 +xprv = xprvA449goEeU9okwCzzZaxiy475EQGQzBkc65su82nXEvcwzfSskb2hAt2WymrjyRL6kpbVTGL3cKtp9herYXSjjQ1j4stsXXiRF7kXkCacK3T +xpub = xpub6H3W6JmYJXN49h5TfcVjLC3onS6uPeUTTJoVvRC8oG9vsTn2J8LwigLzq5tHbrwAzH9DGo6ThGUdWsqce8dGfwHVBxSbixjDADGGdzF7t2B +internal_key = cc8a4bc64d897bddc5fbc2f670f7a8ba0b386779106cf1223c6fc5d7cd6fc115 +output_key = a60869f0dbcf1dc659c9cecbaf8050135ea9e8cdc487053f1dc6880949dc684c +scriptPubKey = 5120a60869f0dbcf1dc659c9cecbaf8050135ea9e8cdc487053f1dc6880949dc684c +address = bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr + +// Account 0, second receiving address = m/86'/0'/0'/0/1 +xprv = xprvA449goEeU9okyiF1LmKiDaTgeXvmh87DVyRd35VPbsSop8n8uALpbtrUhUXByPFKK7C2yuqrB1FrhiDkEMC4RGmA5KTwsE1aB5jRu9zHsuQ +xpub = xpub6H3W6JmYJXN4CCKUSnriaiQRCZmG6aq4sCMDqTu1ACyngw7HShf59hAxYjXgKDuuHThVEUzdHrc3aXCr9kfvQvZPit5dnD3K9xVRBzjK3rX +internal_key = 83dfe85a3151d2517290da461fe2815591ef69f2b18a2ce63f01697a8b313145 +output_key = a82f29944d65b86ae6b5e5cc75e294ead6c59391a1edc5e016e3498c67fc7bbb +scriptPubKey = 5120a82f29944d65b86ae6b5e5cc75e294ead6c59391a1edc5e016e3498c67fc7bbb +address = bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh + +// Account 0, first change address = m/86'/0'/0'/1/0 +xprv = xprvA3Ln3Gt3aphvUgzgEDT8vE2cYqb4PjFfpmbiFKphxLg1FjXQpkAk5M1ZKDY15bmCAHA35jTiawbFuwGtbDZogKF1WfjwxML4gK7WfYW5JRP +xpub = xpub6GL8SnQwRCGDhB59LEz9HMyM6sRYoByXBzXK3iEKWgCz8XrZNHUzd9L3AUBELW5NzA7dEFvMas1F84TuPH3xqdUA5tumaGWFgihJzWytXe3 +internal_key = 399f1b2f4393f29a18c937859c5dd8a77350103157eb880f02e8c08214277cef +output_key = 882d74e5d0572d5a816cef0041a96b6c1de832f6f9676d9605c44d5e9a97d3dc +scriptPubKey = 5120882d74e5d0572d5a816cef0041a96b6c1de832f6f9676d9605c44d5e9a97d3dc +address = bc1p3qkhfews2uk44qtvauqyr2ttdsw7svhkl9nkm9s9c3x4ax5h60wqwruhk7 +</pre> + +==Reference== + +* [[bip-0032.mediawiki|BIP32 - Hierarchical Deterministic Wallets]] +* [[bip-0043.mediawiki|BIP43 - Purpose Field for Deterministic Wallets]] +* [[bip-0044.mediawiki|BIP44 - Multi-Account Hierarchy for Deterministic Wallets]] +* [[bip-0049.mediawiki|BIP49 - Derivation scheme for P2WPKH-nested-in-P2SH based accounts]] +* [[bip-0084.mediawiki|BIP84 - Derivation scheme for P2WPKH based accounts]] +* [[bip-0341.mediawiki|BIP341 - Taproot: SegWit version 1 spending rules]] diff --git a/bip-0088.mediawiki b/bip-0088.mediawiki index 1f77c8e..936f2ca 100644 --- a/bip-0088.mediawiki +++ b/bip-0088.mediawiki @@ -223,7 +223,11 @@ Its representation after parsing can be (using Python syntax, ignoring full/part Its representation after parsing can be: [[(0, 2), (33, 33), (123, 123)], [(0, 2147483647)]] -<code>*h/0</code> specifies a partial template that matches any hardened index followed by any non-hardened index +<code>*h/0</code> specifies a partial template that matches any hardened index followed by non-hardened index 0 Its representation after parsing can be: [[(2147483648, 4294967295)], [(0, 0)]] + +==Acknowledgements== + +Special thanks to Peter D. Gray, Dr. Maxim Orlovsky, Robert Spigler and others for their feedback on the specification, and to Janine (github:@Enegnei) for the help in preparing the draft. diff --git a/bip-0118.mediawiki b/bip-0118.mediawiki index afbfde6..a3a690b 100644 --- a/bip-0118.mediawiki +++ b/bip-0118.mediawiki @@ -1,144 +1,213 @@ <pre> BIP: 118 Layer: Consensus (soft fork) - Title: SIGHASH_NOINPUT + Title: SIGHASH_ANYPREVOUT for Taproot Scripts Author: Christian Decker <decker.christian@gmail.com> + Anthony Towns <aj@erisian.com.au> Comments-Summary: No comments yet. Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0118 Status: Draft Type: Standards Track Created: 2017-02-28 License: BSD-3-Clause + Requires: 340, 341, 342 </pre> -== Abstract == -This BIP describes a new signature hash flag (<tt>sighash</tt>-flag) for -segwit transactions. It removes any commitment to the output being -spent from the signature verification mechanism. This enables dynamic -binding of transactions to outputs, predicated solely on the -compatibility of output scripts to input scripts. - -== Motivation == -Off-chain protocols make use of transactions that are not yet -broadcast to the Bitcoin network in order to renegotiate the final -state that should be settled on-chain. -In a number of cases it is desirable to react to a given transaction -being seen on-chain with a predetermined reaction in the form of -another transaction. -Often the reaction is identical, no matter which transaction is seen -on-chain, but the application still needs to create many identical -transactions. -This is because signatures in the input of a transaction uniquely -commit to the hash of the transaction that created the output being -spent. - -This proposal introduces a new sighash flag that modifies the behavior -of the transaction digest algorithm used in the signature creation and -verification, to exclude the previous output commitment. -By removing the commitment we enable dynamic rebinding of a signed -transaction to outputs whose <tt>witnessProgram</tt> and value match the ones -in the <tt>witness</tt> of the spending transaction. - -The dynamic binding is opt-in and can further be restricted by using -unique <tt>witnessProgram</tt> scripts that are specific to the application -instance, e.g., using public keys that are specific to the off-chain -protocol instance. +== Introduction == + +=== Abstract === + +This BIP describes a new type of public key for tapscript ([[bip-0342.mediawiki|BIP 342]]) transactions. +It allows signatures for these public keys to not commit to the exact UTXO being spent. +This enables dynamic binding of transactions to different UTXOs, provided they have compatible scripts. + +=== Copyright === + +This document is licensed under the 3-clause BSD license. + +=== Motivation === + +Off-chain protocols make use of transactions that are not yet broadcast to the Bitcoin network in order to renegotiate the final state that should be settled on-chain. +In a number of cases it is desirable to respond to a given transaction being seen on-chain with a predetermined reaction in the form of another transaction. +Often the same reaction is desired for a variety of different transactions that may be seen on-chain, but because the input signatures in the response transaction commit to the exact transaction that is being reacted to, this means a new signature must be created for every possible transaction one wishes to be able to react to. + +This proposal introduces a new public key type<ref>'''Why a new public key type?''' +New public key types for tapscript can be introduced in a soft fork by specifying new rules for ''unknown public key types'' as specified in [[bip-0342.mediawiki|BIP 342]], as this only requires adding restrictions to the pre-existing signature opcodes. +Possible alternative approaches would be to define new script opcodes, to use a different taproot leaf version, or to use a different set of SegWit outputs than those specified by [[bip-0341.mediawiki|BIP 341]]; however all of these approaches are more complicated, and are better reserved for other upgrades where the additional flexibility is actually needed. +In this case, we specify a new transaction digest, but retain the same elliptic curve and signature algorithm (ie, secp256k1 and [[bip-0340.mediawiki|BIP 340]]).</ref> +that modifies the behavior of the transaction digest algorithm used in the signature creation and verification, by excluding the commitment to the previous output (and, optionally, the witness script<ref>'''Why (and why not) commit to the witness script?''' +The [https://blockstream.com/eltoo.pdf eltoo] paper provides an example of why committing to the witness script is not always appropriate. +It uses script and the transaction <code>nLockTime</code> to make signatures asymmetric, so that a transaction with an earlier signature can be spent by a transaction with a later signature, but a transaction with a later signature cannot be spent by a transaction with an earlier signature. +As a result, a single signature for a third, even later transaction must be able to spend both the prior transactions, even though they have a different tapscript. +On the other hand, these cases also provide a good reason to have the option to commit to the script: because each transaction has a new script, committing to the script allows you to produce a signature that applies to precisely one of these transactions. +In the eltoo case, this allows you to have a signature for an update transaction that can be applied to any prior update, and a signature for a settlement transaction that applies only to the corresponding update transaction, while using the same key for both, which in turn allows for a more compact script. +</ref> and value <ref>'''Why (and why not) commit to the input value?''' +Committing to the input value may provide additional safety that a signature can't be maliciously reused to claim funds that the signer does not intend to spend, so by default it seems sensible to commit to it. However, doing so prevents being able to use a single signature to consolidate a group of UTXOs with the same spending condition into a single UTXO which may be useful for some protocols, such as the proposal for [https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-January/002448.html layered commitments with eltoo].</ref>). +Removing this commitment allows dynamic rebinding of a signed transaction to another previous output that requires authorisation by the same key. + +The dynamic rebinding is opt-in due to using a separate public key type, and the breadth of transactions the signature can be rebound to can be further restricted by using different keys, committing to the script being spent in the signature, using different amounts between UTXOs, using different nSequence values in the spending transaction, or using the codeseparator opcode to commit to the position in the script. == Specification == -<tt>SIGHASH_NOINPUT</tt> is a flag with value <tt>0x40</tt> appended to a signature -so that the signature does not commit to any of the inputs, and -therefore to the outputs being spent. The flag applies solely to the -verification of that single signature. - -The <tt>SIGHASH_NOINPUT</tt> flag is only active for segwit scripts with -version 1 or higher. Should the flag be used in a non-segwit script or -a segwit script of version 0, the current behavior is maintained and -the script execution MUST abort with a failure. - -The transaction digest algorithm from BIP 143 is used when verifying a -<tt>SIGHASH_NOINPUT</tt> signature, with the following modifications: - - 2. hashPrevouts (32-byte hash) is 32 0x00 bytes - 3. hashSequence (32-byte hash) is 32 0x00 bytes - 4. outpoint (32-byte hash + 4-byte little endian) is - set to 36 0x00 bytes - 5. scriptCode of the input is set to an empty script - 0x00 - -The <tt>value</tt> of the previous output remains part of the transaction -digest and is therefore also committed to in the signature. - -The <tt>NOINPUT</tt> flag MAY be combined with the <tt>SINGLE</tt> flag in which -case the <tt>hashOutputs</tt> is modified as per BIP -143<ref>https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki</ref>: it -only commits to the output with the matching index, if such output exists, and -is a <tt>uint256</tt> <tt>0x0000......0000</tt> otherwise. - -Being a change in the digest algorithm, the <tt>NOINPUT</tt> flag applies to -all segwit signature verification opcodes, specifically it applies to: - -* <tt>OP_CHECKSIG</tt> - -* <tt>OP_CHECKSIGVERIFY</tt> - -* <tt>OP_CHECKMULTISIG</tt> - -* <tt>OP_CHECKMULTISIGVERIFY</tt> - -== Binding through scripts == -Using <tt>NOINPUT</tt> the input containing the signature no longer -references a specific output. -Any participant can take a transaction and rewrite it by changing the -hash reference to the previous output, without invalidating the -signatures. -This allows transactions to be bound to any output that matches the -value committed to in the signature and whose <tt>witnessProgram</tt>, -combined with the spending transaction's <tt>witness</tt> returns <tt>true</tt>. - -Previously, all information in the transaction was committed in the -signature itself, while now the relationship between the spending -transaction and the output being spent is solely based on the -compatibility of the <tt>witnessProgram</tt> and the <tt>witness</tt>. - -This also means that particular care has to be taken in order to avoid -unintentionally enabling this rebinding mechanism. <tt>NOINPUT</tt> MUST NOT -be used, unless it is explicitly needed for the application, e.g., it -MUST NOT be a default signing flag in a wallet -implementation. Rebinding is only possible when the outputs the -transaction may bind to all use the same public keys. Any public key -that is used in a <tt>NOINPUT</tt> signature MUST only be used for outputs -that the input may bind to, and they MUST NOT be used for transactions -that the input may not bind to. For example an application SHOULD -generate a new key-pair for the application instance using <tt>NOINPUT</tt> -signatures and MUST NOT reuse them afterwards. + +This BIP modifies the behaviour of the [[bip-0342.mediawiki|BIP 342]] signature opcodes<ref>'''What about key path spends?''' +This proposal only supports ANYPREVOUT signatures via script path spends, and does not support ANYPREVOUT signatures for key path spends. +This is for two reasons: first, not supporting key path spends allows this proposal to be independent of the core changes included in [[bip-0341.mediawiki|BIP 341]] and [[bip-0342.mediawiki|BIP 342]]; second, it allows addresses to opt-in or opt-out of ANYPREVOUT support while remaining indistinguishable prior to being spent. +</ref> (<code>CHECKSIG</code>, <code>CHECKSIGVERIFY</code>, and <code>CHECKSIGADD</code>) for public keys that have a length of 33 bytes and a first byte of <code>0x01</code> or the public key which is precisely the single byte vector <code>0x01</code><ref>'''Use of 0x01 public key type''' +Because <code>OP_0</code> leaves an empty vector on the stack it would not satisfy [[bip-0342.mediawiki|BIP 342]]'s rules for unknown public key types. As such, it is convenient to use one of <code>OP_1..OP_16</code> or <code>OP_1NEGATE</code> as a way to reference the taproot internal key. +To keep things as simple as possible, we use the first of these, and add the same byte as a prefix to allow ANYPREVOUT signatures for explicitly specified keys. +</ref>. +These keys are termed '''BIP 118 public keys'''. + +==== Rules for signature opcodes ==== + +The [[bip-0342.mediawiki|BIP 342]] rules for signature opcodes are modified by removing keys with the first byte <code>0x01</code> and length of either 1-byte or 33-bytes from the list of unknown public key types, and adding the following rule prior to the handling of unknown public key types: + +* If the public key is the single byte <code>0x01</code>, or if the public key is 33 bytes and the first byte of the public key is <code>0x01</code>, it is considered to be a BIP 118 public key: +** If the signature is not the empty vector, the signature is validated according to the [[bip-0341.mediawiki|BIP 341]] signing validation rules with the public key, allowable <code>hash_type</code> values, and transaction digest modified as defined below. + +==== Public key ==== + +To convert the 1-byte BIP 118 public key for use with [[bip-0340.mediawiki|BIP 340]], use the 32-byte taproot internal key, <code>p</code>, as defined in [[bip-0341.mediawiki|BIP 341]]. + +To convert a 33-byte BIP 118 public key for use with [[bip-0340.mediawiki|BIP 340]], remove the <code>0x01</code> prefix and use the remaining 32 bytes. + +==== Signature message ==== + +The function ''SigMsg118(hash_type, ext_flag)'' computes the message being signed as a byte array, analogously to ''SigMsg(hash_type, ext_flag)'' defined in [[bip-0341.mediawiki|BIP 341]], ''SigExt118(hash_type,key_version)'' computes the extension, similarly to [[bip-0342.mediawiki|BIP 342]]. + +The parameter ''hash_type'' is an 8-bit unsigned value, reusing values defined in [[bip-0341.mediawiki|BIP 341]], with the addition that the values <code>0x41</code>, <code>0x42</code>, <code>0x43</code>, <code>0xc1</code>, <code>0xc2</code>, and <code>0xc3</code> are also valid for BIP 118 public keys. + +We define the following constants using bits 6 and 7 of <code>hash_type</code>: + +* <code>SIGHASH_ANYPREVOUT = 0x40</code> +* <code>SIGHASH_ANYPREVOUTANYSCRIPT = 0xc0</code> + +As per [[bip-0341.mediawiki|BIP 341]], the parameter ''ext_flag'' is an integer in the range 0-127, used for indicating that extensions are added at the end of the message. The parameter ''key_version'' is an 8-bit unsigned value (an integer in the range 0-255) used for committing to the public key version. + +The following restrictions apply and cause validation failure if violated: +* Using any undefined ''hash_type'' (not ''0x00'', ''0x01'', ''0x02'', ''0x03'', ''0x41'', ''0x42'', ''0x43'', ''0x81'', ''0x82'', ''0x83'', ''0xc1'', ''0xc2'', or ''0xc3''). +* Using <code>SIGHASH_SINGLE</code> without a "corresponding output" (an output with the same index as the input being verified). + +If these restrictions aren't violated, ''SigMsg118(hash_type,ext_flag)'' evaluates to the concatenation of the following data, in order (with byte size of each item listed in parentheses). Numerical values in 2, 4, or 8-byte items are encoded in little-endian. + +* Control: +** ''hash_type'' (1). +* Transaction data: +** ''nVersion'' (4): the ''nVersion'' of the transaction. +** ''nLockTime'' (4): the ''nLockTime'' of the transaction. +** If ''hash_type & 0xc0'' is zero: +*** ''sha_prevouts'' (32): the SHA256 of the serialization of all input outpoints. +*** ''sha_amounts'' (32): the SHA256 of the serialization of all spent output amounts. +*** ''sha_scriptpubkeys'' (32): the SHA256 of the serialization of all spent output ''scriptPubKey''s. +*** ''sha_sequences'' (32): the SHA256 of the serialization of all input ''nSequence''. +** If ''hash_type & 3'' does not equal <code>SIGHASH_NONE</code> or <code>SIGHASH_SINGLE</code>: +*** ''sha_outputs'' (32): the SHA256 of the serialization of all outputs in <code>CTxOut</code> format. +* Data about this input: +** ''spend_type'' (1): equal to ''(ext_flag * 2) + annex_present'', where ''annex_present'' is 0 if no annex is present, or 1 otherwise (the original witness stack has two or more witness elements, and the first byte of the last element is ''0x50'') +** If ''hash_type & 0xc0'' is non-zero: +*** If ''hash_type & 0xc0'' is <code>SIGHASH_ANYONECANPAY</code>: +**** ''outpoint'' (36): the <code>COutPoint</code> of this input (32-byte hash + 4-byte little-endian). +*** If ''hash_type & 0xc0'' is <code>SIGHASH_ANYONECANPAY</code> or <code>SIGHASH_ANYPREVOUT</code>: +**** ''amount'' (8): value of the previous output spent by this input. +**** ''scriptPubKey'' (35): ''scriptPubKey'' of the previous output spent by this input, serialized as script inside <code>CTxOut</code>. Its size is always 35 bytes. +*** ''nSequence'' (4): ''nSequence'' of this input. +** If ''hash_type & 0xc0'' is zero: +*** ''input_index'' (4): index of this input in the transaction input vector. Index of the first input is 0. +** If an annex is present (the lowest bit of ''spend_type'' is set): +*** ''sha_annex'' (32): the SHA256 of ''(compact_size(size of annex) || annex)'', where ''annex'' includes the mandatory ''0x50'' prefix. +* Data about this output: +** If ''hash_type & 3'' equals <code>SIGHASH_SINGLE</code>: +*** ''sha_single_output'' (32): the SHA256 of the corresponding output in <code>CTxOut</code> format. + +Similarly, ''SigExt118(hash_type,key_version)'' evaluates to the concatenation of: + +* Extension: +** If ''hash_type & 0xc0'' is not <code>SIGHASH_ANYPREVOUTANYSCRIPT</codE>: +*** ''tapleaf_hash'' (32): the tapleaf hash as defined in [[bip-0341.mediawiki|BIP 341]] +** ''key_version'' (1). +** ''codesep_pos'' (4): the opcode position of the last executed <code>OP_CODESEPARATOR</code> before the currently executed signature opcode, with the value in little endian (or ''0xffffffff'' if none executed). The first opcode in a script has a position of 0. A multi-byte push opcode is counted as one opcode, regardless of the size of data being pushed. + +Note that if ''hash_type & 0x40'' is zero, ''SigMsg118(hash_type,ext_flag) == SigMsg(hash_type,ext_flag)'', and ''SigExt118(hash_type,0x00) == ext'' (where ''ext'' is the message extension as defined in [[bip-0342.mediawiki|BIP 342]]). + +To verify a signature ''sig'' for a BIP 118 public key ''p'': + +* If the ''sig'' is 64 bytes long, return ''Verify(p, hash<sub>TapSigHash</sub>(0x00 || SigMsg118(0x00, 1) || SigExt118(0x00, 0x01), sig)'', where ''Verify'' is defined in [[bip-0340.mediawiki|BIP 340]]. +* If the ''sig'' is 65 bytes long, return ''sig[64] ≠ 0x00 and Verify(p, hash<sub>TapSighash</sub>(0x00 || SigMsg118(sig[64], 1) || SigExt118(sig[64], 0x01), sig[0:64])''. +* Otherwise, fail. + +The key differences from [[bip-0342.mediawiki|BIP 342]] signature verification are: + +* In all cases, <code>key_version</code> is set to the constant value <code>0x01</code> instead of <code>0x00</code>.<ref>'''Why change key_version?''' Changing <code>key_version</code> ensures that if the same private key is used to generate both a [[bip-0342.mediawiki|BIP 342]] key and a BIP 118 public key, that a signature for the [[bip-0342.mediawiki|BIP 342]] key is not also valid for the BIP 118 public key (and vice-versa).</ref> +* If <code>SIGHASH_ANYPREVOUT</code> is set, the digest is calculated as if <code>SIGHASH_ANYONECANPAY</code> was set, except <code>outpoint</code> is not included in the digest. +* If <code>SIGHASH_ANYPREVOUTANYSCRIPT</code> is set, the digest is calculated as if <code>SIGHASH_ANYONECANPAY</code> was set, except <code>outpoint</code>, <code>scriptPubKey</code> and <code>tapleaf_hash</code> are not included in the digest. + +== Security == + +==== Signature replay ==== + +By design, <code>SIGHASH_ANYPREVOUT</code> and <code>SIGHASH_ANYPREVOUTANYSCRIPT</code> introduce additional potential for signature replay (that is they allow the same signature to be reused on a different transaction) when compared to <code>SIGHASH_ALL</code> and <code>SIGHASH_ANYONECANPAY</code> signatures. + +Both <code>SIGHASH_ALL</code> and <code>SIGHASH_ANYONECANPAY</code> signatures prevent signature replay by committing to one or more inputs, so replay of the signature is only possible if the same input can be spent multiple times, which is not possible on the Bitcoin blockchain (due to enforcement of [[bip-0030.mediawiki|BIP 30]]). +With <code>SIGHASH_ANYPREVOUT</code> signature replay is possible for different UTXOs with the same <code>scriptPubKey</code> and the same value, while with <code>SIGHASH_ANYPREVOUTANYSCRIPT</code> signature replay is possible for any UTXOs that reuse the same BIP 118 public key in one of their potential scripts. + +As a consequence, implementors MUST ensure that BIP 118 public keys are only reused when signature replay cannot cause loss of funds (eg due to other features of the protocol or other constraints on the transaction), or when such a loss of funds is acceptable. + +==== Malleability ==== + +Use of <code>SIGHASH_ANYPREVOUT</code> or <code>SIGHASH_ANYPREVOUTANYSCRIPT</code> may introduce additional malleability vectors. + +In particular, a transaction authenticated using only ANYPREVOUT signatures is malleable to anyone able to provide an alternate input satisfied by the signature -- an input changed in this way would produce a new, valid transaction paying the same recipient, but with a different txid. +Depending on the changes to the inputs, this might conflict with the original transaction (if some inputs remain shared) or might result in a double-payment to the recipient (if they do not). + +Further, for a chain of transactions using the same <code>scriptPubKey</code> and value, and only authenticated via ANYPREVOUT signatures (as envisioned in eltoo for failure cases), it may be possible for any third party to malleate the transactions (and their txids) without having access to any of the private keys, particularly by omitting intermediate transactions. + +This form of malleation can be dealt with by the child transactions also using ANYPREVOUT signatures -- when a parent transaction is malleated, its children can be adjusted to reference the new txid as the input and the ANYPREVOUT signatures remain valid. + +However child transactions that are authorised by a <code>SIGHASH_ALL</code> or <code>SIGHASH_ANYONECANPAY</code> signature will need new signatures if their inputs are malleated in this way. +This risk may be mitigated somewhat by using [[bip-0068.mediawiki|BIP 68]]/[[bip-0112.mediawiki|BIP 112]] relative time locks before spending a UTXO that had been authorised via an ANYPREVOUT signature with <code>SIGHASH_ALL</code> or <code>SIGHASH_ANYONECANPAY</code>: a relative timelock can ensure that the inputs have enough confirmations that they can only be replaced in the event of a large block reorg. +Note that this approach has drawbacks: relative timelocks prevent fee-bumping via child-pays-for-parent, and have the obvious drawback of making the funds temporarily unusable until the timelock expires. + +==== Privacy considerations ==== + +It is expected that ANYPREVOUT signatures will only be rarely used in practice. +Protocol and wallet designers should aim to have their transactions use Taproot key path spends whenever possible, both for efficiency reasons due to the lower transaction weight, but also for privacy reasons to avoid third parties being able to distinguish their transactions from those of other protocols. + +Transactions that do use ANYPREVOUT signatures will therefore reveal information about the transaction, potentially including that cooperation was impossible, or what protocol or software was used (due to the details of the script). + +In order to maximise privacy, it is therefore recommended that protocol designers only use BIP 118 public keys in scripts that will be spent using at least one ANYPREVOUT signature, and either use key path spends or alternate scripts in the taproot merkle tree for any spends that can be authorised without ANYPREVOUT signatures. +Following this recommendation may require additional script branches, which may mean disregarding this recommendation may result in a better tradeoff between cost and privacy in some circumstances. + +== Rationale == + +<references /> == Deployment == -The <tt>NOINPUT</tt> sighash flag is to be deployed during a regular segwit -script update. -== Backward compatibility == -As a soft fork, older software will continue to operate without -modification. Non-upgraded nodes, however, will not verify the -validity of the new sighash flag and will consider the transaction -valid by default. Being only applicable to segwit transactions, -non-segwit nodes will see an anyone-can-spend script and will consider -it valid. +TODO + +This may be deployed as a soft-fork either concurrent with, or subsequent to the deployment of [[bip-0340.mediawiki|BIP 340]], [[bip-0341.mediawiki|BIP 341]] and [[bip-0342.mediawiki|BIP 342]]. + +== Backwards compatibility == + +As a soft fork, older software will continue to operate without modification. +Nodes that have not upgraded to support [[bip-0341.mediawiki|BIP 341]] will see all taproot witness programs as anyone-can-spend scripts, and nodes that have upgraded to support [[bip-0341.mediawiki|BIP 341]] and [[bip-0342.mediawiki|BIP 342]] but not BIP 118 will simply treat any non-empty signature against a BIP 118 public key as valid. +As such, nodes are strongly encourage to upgrade in order to fully validate signatures for the new public key type. + +Non-upgraded wallets can receive and send bitcoin from non-upgraded and upgraded wallets using SegWit version 0 programs, traditional pay-to-pubkey-hash, etc. +Depending on the implementation, non-upgraded wallets may be able to send to SegWit version 1 programs if they support sending to [[bip-0350.mediawiki|BIP350]] Bech32m addresses and do not prevent the transaction from being broadcast due to considering the outputs non-standard. -== Acknowledgments == +== Revisions == -The <tt>NOINPUT</tt> sighash flag was first proposed by Joseph Poon in -February 2016<ref>https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2016-February/012460.html</ref>, after being mentioned in the original -Lightning paper<ref>http://lightning.network/lightning-network.pdf</ref>. A formal proposal was however -deferred until after the activation of segwit. This proposal is a -continuation of this discussion and attempts to formalize it in such a -way that it can be included in the Bitcoin protocol. As such we'd like -acknowledge Joseph Poon and Thaddeus Dryja as the original inventors -of the <tt>NOINPUT</tt> sighash flag, and its uses in off-chain protocols. +Apart from being based on Taproot rather than SegWit v0, the main differences to prior revisions of this BIP are: -== References == +* The sighash flag has been renamed from "NOINPUT" to "ANYPREVOUT" to reflect that while any prevout may potentially be used with the signature, some aspects of the input are still committed to, namely the input nSequence value, and (optionally) the spending conditions and amount. +* Previously NOINPUT would have worked for direct public key spends (assuming deployment was fleshed out in a way similar to BIP 141 P2WPKH and P2WSH), however this proposal only applies to signatures via tapscript, and not direct key path spends. This means that addresses must opt-in to the ability to be spent by a <code>SIGHASH_ANYPREVOUT</code> or <code>SIGHASH_ANYPREVOUTANYSCRIPT</code> signature by including an appropriate tapscript path when the address is created. +* NOINPUT signatures do not commit to the output's spending conditions either via <code>scriptPubKey</code> or the redeem/witness script. This behaviour is preserved when <code>SIGHASH_ANYPREVOUTANYSCRIPT</code> is used, but when <code>SIGHASH_ANYPREVOUT</code> is used, the signature now commits to <code>scriptPubKey</code> and the tapscript. +* NOINPUT signatures did commit to the input's amount. This behaviour is preserved when <code>SIGHASH_ANYPREVOUT</code> is used, but not when <code>SIGHASH_ANYPREVOUTANYSCRIPT</code> is used. +* <code>OP_CODESEPARATOR</code> in script will affect both <code>SIGHASH_ANYPREVOUT</code> and <code>SIGHASH_ANYPREVOUTANYSCRIPT</code> signatures, whereas it would not have in the previous draft. -<references/> +== Acknowledgements == -== Copyright == +The <code>SIGHASH_NOINPUT</code> flag was first proposed by Joseph Poon in [https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2016-February/012460.html February 2016], after being mentioned in the original [http://lightning.network/lightning-network-paper.pdf Lightning paper] by Joseph Poon and Thaddeus Dryja. +This document is the result of discussions with many people and had direct input from Greg Maxwell, Jonas Nick, Pieter Wuille and others. -This document is licensed under the BSD 3 Clause license. diff --git a/bip-0119.mediawiki b/bip-0119.mediawiki index 730ffb9..e887caf 100644 --- a/bip-0119.mediawiki +++ b/bip-0119.mediawiki @@ -27,9 +27,9 @@ OP_CHECKTEMPLATEVERIFY does the following: * There is at least one element on the stack, fail otherwise * The element on the stack is 32 bytes long, NOP otherwise -* The StandardTemplateHash of the transaction at the current input index is equal to the element on the stack, fail otherwise +* The DefaultCheckTemplateVerifyHash of the transaction at the current input index is equal to the element on the stack, fail otherwise -The StandardTemplateHash commits to the serialized version, locktime, scriptSigs hash (if any +The DefaultCheckTemplateVerifyHash commits to the serialized version, locktime, scriptSigs hash (if any non-null scriptSigs), number of inputs, sequences hash, number of outputs, outputs hash, and currently executing input index. @@ -57,7 +57,6 @@ for purposes of confirmation using CHECKTEMPLATEVERIFY. Then, some time later, t be expanded out of that UTXO when the demand for blockspace is decreased. These payments can be structured in a tree-like fashion to reduce individual costs of redemption. - The below chart showcases the structure of these transactions in comparison to normal transactions and batched transactions. @@ -71,6 +70,7 @@ is provided in this BIP's subdirectory. <img src="bip-0119/fifty.png" align="middle"></img> ===Payment Channels=== + There are numerous payment channel related uses. ====Channel Factories==== @@ -84,6 +84,7 @@ penultimate transaction node. Thus, coins sent using a congestion controlled transaction can still enjoy instant liquidity. ====Non-Interactive Channels==== + When opening a traditional payment channel, both parties to the channel must participate. This is because the channel uses pre-signed multi-sig transactions to ensure that a channel can always be exited by either party, before entering. @@ -94,6 +95,7 @@ for their private key to be online. <img src="bip-0119/nic.svg" align="middle"></img> ====Increased Channel Routes==== + In the Lightning Network protocol, Hashed Time Locked Contracts (HTLCS) are used in the construction of channels. A new HTLC is required per route that the channel is serving in. In BOLT #2, this maximum number of HTLCs in a channel is hard limited to 483 as the maximum safe @@ -107,7 +109,6 @@ HTLCS. Because each HTLC can have its own relative time lock in the tree, this also improves the latency sensitivity of the lightning protocol on contested channel close. - ===Wallet Vaults=== When greater security is required for cold storage solutions, there can be @@ -133,19 +134,26 @@ before. Further Each participant doesn't need to know the totality of the outpu that output, they only have to verify their own sub-tree will pay them. ==Detailed Specification== + The below code is the main logic for verifying CHECKTEMPLATEVERIFY, and is the canonical specification for the semantics of OP_CHECKTEMPLATEVERIFY. case OP_CHECKTEMPLATEVERIFY: { // if flags not enabled; treat as a NOP4 - if (!(flags & SCRIPT_VERIFY_STANDARD_TEMPLATE)) break; + if (!(flags & SCRIPT_VERIFY_DEFAULT_CHECK_TEMPLATE_VERIFY_HASH)) { + if (flags & SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_NOPS) + return set_error(serror, SCRIPT_ERR_DISCOURAGE_UPGRADABLE_NOPS); + break; + } + if (stack.size() < 1) return set_error(serror, SCRIPT_ERR_INVALID_STACK_OPERATION); + // If the argument was not 32 bytes, treat as OP_NOP4: switch (stack.back().size()) { case 32: - if (!checker.CheckStandardTemplateHash(stack.back())) { + if (!checker.CheckDefaultCheckTemplateVerifyHash(stack.back())) { return set_error(serror, SCRIPT_ERR_TEMPLATE_MISMATCH); } break; @@ -159,19 +167,25 @@ specification for the semantics of OP_CHECKTEMPLATEVERIFY. } break; +Where + + bool CheckDefaultCheckTemplateVerifyHash(const std::vector<unsigned char>& hash) { + return GetDefaultCheckTemplateVerifyHash(current_tx, current_input_index) == uint256(hash); + } + The hash is computed as follows: - uint256 GetStandardTemplateHash(const CTransaction& tx, uint32_t input_index) { - return GetStandardTemplateHash(tx, GetOutputsSHA256(tx), GetSequenceSHA256(tx), input_index); + uint256 GetDefaultCheckTemplateVerifyHash(const CTransaction& tx, uint32_t input_index) { + return GetDefaultCheckTemplateVerifyHash(tx, GetOutputsSHA256(tx), GetSequenceSHA256(tx), input_index); } - uint256 GetStandardTemplateHash(const CTransaction& tx, const uint256& outputs_hash, const uint256& sequences_hash, + uint256 GetDefaultCheckTemplateVerifyHash(const CTransaction& tx, const uint256& outputs_hash, const uint256& sequences_hash, const uint32_t input_index) { bool skip_scriptSigs = std::find_if(tx.vin.begin(), tx.vin.end(), [](const CTxIn& c) { return c.scriptSig != CScript(); }) == tx.vin.end(); - return skip_scriptSigs ? GetStandardTemplateHashEmptyScript(tx, outputs_hash, sequences_hash, input_index) : - GetStandardTemplateHashWithScript(tx, outputs_hash, sequences_hash, GetScriptSigsSHA256(tx), input_index); + return skip_scriptSigs ? GetDefaultCheckTemplateVerifyHashEmptyScript(tx, outputs_hash, sequences_hash, input_index) : + GetDefaultCheckTemplateVerifyHashWithScript(tx, outputs_hash, sequences_hash, GetScriptSigsSHA256(tx), input_index); } - uint256 GetStandardTemplateHashWithScript(const CTransaction& tx, const uint256& outputs_hash, const uint256& sequences_hash, + uint256 GetDefaultCheckTemplateVerifyHashWithScript(const CTransaction& tx, const uint256& outputs_hash, const uint256& sequences_hash, const uint256& scriptSig_hash, const uint32_t input_index) { auto h = CHashWriter(SER_GETHASH, 0) << tx.nVersion @@ -184,7 +198,7 @@ The hash is computed as follows: << input_index; return h.GetSHA256(); } - uint256 GetStandardTemplateHashEmptyScript(const CTransaction& tx, const uint256& outputs_hash, const uint256& sequences_hash, + uint256 GetDefaultCheckTemplateVerifyHashEmptyScript(const CTransaction& tx, const uint256& outputs_hash, const uint256& sequences_hash, const uint32_t input_index) { auto h = CHashWriter(SER_GETHASH, 0) << tx.nVersion @@ -197,10 +211,9 @@ The hash is computed as follows: return h.GetSHA256(); } +A PayToBareDefaultCheckTemplateVerifyHash output matches the following template: -A PayToBasicStandardTemplate output matches the following template: - - bool CScript::IsPayToBasicStandardTemplate() const + bool CScript::IsPayToBareDefaultCheckTemplateVerifyHash() const { // Extra-fast test for pay-to-basic-standard-template CScripts: return (this->size() == 34 && @@ -210,18 +223,26 @@ A PayToBasicStandardTemplate output matches the following template: ==Deployment== -Deployment should be done via BIP 9 VersionBits. +Deployment should be done via BIP 9 VersionBits deployed through Speedy Trial. The start time and bit in the implementation are currently set to bit 5 and -March 1st, 2020, but this is subject to change while the BIP is a draft. +NEVER_ACTIVE/NO_TIMEOUT, but this is subject to change while the BIP is a draft. -For the avoidance of unclarity, the parameters are: +For the avoidance of unclarity, the parameters to be determined are: + // Deployment of CTV (BIP 119) consensus.vDeployments[Consensus::DEPLOYMENT_CHECKTEMPLATEVERIFY].bit = 5; - consensus.vDeployments[Consensus::DEPLOYMENT_CHECKTEMPLATEVERIFY].nStartTime = 1583020800; // March 1, 2020 - consensus.vDeployments[Consensus::DEPLOYMENT_CHECKTEMPLATEVERIFY].nTimeout = 1614556800; // March 1, 2021 + consensus.vDeployments[Consensus::DEPLOYMENT_CHECKTEMPLATEVERIFY].nStartTime = Consensus::BIP9Deployment::NEVER_ACTIVE; + consensus.vDeployments[Consensus::DEPLOYMENT_CHECKTEMPLATEVERIFY].nTimeout = Consensus::BIP9Deployment::NO_TIMEOUT; + consensus.vDeployments[Consensus::DEPLOYMENT_CHECKTEMPLATEVERIFY].min_activation_height = 0; + +Until BIP-119 reaches ACTIVE state and the +SCRIPT_VERIFY_DEFAULT_CHECK_TEMPLATE_VERIFY_HASH flag is set, the network should +execute a NOP4 as SCRIPT_ERR_DISCOURAGE_UPGRADABLE_NOPS for policy and a NOP for +consensus. -In order to facilitate using CHECKTEMPLATEVERIFY, the common case of a PayToBasicStandardTemplate +In order to facilitate using CHECKTEMPLATEVERIFY, the common case of a +PayToBareDefaultCheckTemplateVerifyHash with no scriptSig data shall be made standard to permit relaying. Future template types may be standardized later as policy changes. @@ -230,26 +251,20 @@ standardized later as policy changes. A reference implementation and tests are available here: https://github.com/JeremyRubin/bitcoin/tree/checktemplateverify. - ==Rationale== The goal of CHECKTEMPLATEVERIFY is to be minimal impact on the existing codebase -- in the future, as we become aware of more complex but shown to be safe use cases new template types can be added. - Below we'll discuss the rules one-by-one: - - -====The StandardTemplateHash of the transaction at the current input index matches the top of the stack==== +====The DefaultCheckTemplateVerifyHash of the transaction at the current input index matches the top of the stack==== The set of data committed to is a superset of data which can impact the TXID of the transaction, other than the inputs. This ensures that for a given known input, the TXIDs can also be known ahead of time. Otherwise, CHECKTEMPLATEVERIFY would not be usable for Channel Factory type constructions as the redemption TXID could be malleated and pre-signed transactions invalidated. - - =====Committing to the version and locktime===== Were these values not committed, it would be possible to delay the spending of @@ -272,16 +287,15 @@ spend, as long as the exact scriptsig for the legacy output is committed. This i simply disallowing any scriptSig to be set with CHECKTEMPLATEVERIFY. If no scriptSigs are set in the transaction, there is no purpose in hashing the data or including it -in the StandardTemplateHash, so we elide it. It is expected to be common that no scriptSigs will be +in the DefaultCheckTemplateVerifyHash, so we elide it. It is expected to be common that no scriptSigs will be set as segwit mandates that the scriptSig must be empty (to avoid malleability). We commit to the hash rather than the values themselves as this is already precomputed for each transaction to optimize SIGHASH_ALL signatures. -Committing to the hash additionally makes it simpler to construct StandardTemplateHashes safely and unambiguously from +Committing to the hash additionally makes it simpler to construct DefaultCheckTemplateVerifyHash safely and unambiguously from script. - =====Committing to the number of inputs===== If we allow more than one input to be spent in the transaction then it would be @@ -314,7 +328,7 @@ specific applications. In principal, committing to the Sequences Hash (below) implicitly commits to the number of inputs, making this field strictly redundant. However, separately committing to this number makes it easier -to construct StandardTemplateHashes from script. +to construct DefaultCheckTemplateVerifyHash from script. We treat the number of inputs as a `uint32_t` because signature checking code expects nIn to be an `unsigned int`, even though in principal a transaction can encode more than a `uint32_t`'s worth of @@ -329,14 +343,14 @@ with OP_CSV because OP_CSV enforces a minimum nSequence value, not a literal val We commit to the hash rather than the values themselves as this is already precomputed for each transaction to optimize SIGHASH_ALL signatures. -Committing to the hash additionally makes it simpler to construct StandardTemplateHashes safely and unambiguously from +Committing to the hash additionally makes it simpler to construct DefaultCheckTemplateVerifyHash safely and unambiguously from script. =====Committing to the Number of Outputs===== In principal, committing to the Outputs Hash (below) implicitly commits to the number of outputs, making this field strictly redundant. However, separately committing to this number makes it easier -to construct StandardTemplateHashes from script. +to construct DefaultCheckTemplateVerifyHash from script. We treat the number of outputs as a `uint32_t` because a `COutpoint` index is a `uint32_t`, even though in principal a transaction could encode more outputs. @@ -349,7 +363,7 @@ requested. We commit to the hash rather than the values themselves as this is already precomputed for each transaction to optimize SIGHASH_ALL signatures. -Committing to the hash additionally makes it simpler to construct StandardTemplateHashes safely and unambiguously from +Committing to the hash additionally makes it simpler to construct DefaultCheckTemplateVerifyHash safely and unambiguously from script. =====Committing to the current input's index===== @@ -370,7 +384,8 @@ added to Bitcoin, the index may simply be passed in by the witness before hashin =====Committing to Values by Hash===== -Committing to values by hash makes it easier and more efficient to construct a StandardTemplateHash +Committing to values by hash makes it easier and more efficient to construct a +DefaultCheckTemplateVerifyHash from script. Fields which are not intended to be set may be committed to by hash without incurring O(n) overhead to re-hash. @@ -378,12 +393,41 @@ Furthermore, if OP_SHA256STREAM is added in the future, it may be possible to wr allows adding a single output to a list of outputs without incurring O(n) overhead by committing to a hash midstate in the script. +=====Using SHA256===== + +SHA256 is a 32 byte hash which meets Bitcoin's security standards and is +available already inside of Bitcoin Script for programmatic creation of template +programs. + +RIPEMD160, a 20 byte hash, might also be a viable hash in some contexts and has some benefits. For fee efficiency, +RIPEMD160 saves 12 bytes. However, RIPEMD160 was not chosen for BIP-119 because it introduces +risks around the verification of programs created by third parties to be subject to a +[birthday-attack https://bitcoin.stackexchange.com/questions/54841/birthday-attack-on-p2sh] on +transaction preimages. + +=====Using Non-Tagged Hashes===== + +The Taproot/Schnorr BIPs use Tagged Hashes +(`SHA256(SHA256(tag)||SHA256(tag)||msg)`) to prevent taproot leafs, branches, +tweaks, and signatures from overlapping in a way that might introduce a security +[vulnerability https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-June/016091.html]. + +OP_CHECKTEMPLATEVERIFY is not subject to this sort of vulnerability as the +hashes are effectively tagged externally, that is, by OP_CHECKTEMPLATEVERIFY +itself and therefore cannot be confused for another hash. + +It would be a conservative design decisison to make it a tagged hash even if +there was no obvious benefit and no cost. However, in the future, if OP_CAT were +to be introduced to Bitcoin, it would make programs which dynamically build +OP_CHECKTEMPLATEVERIFY hashes less space-efficient. Therefore, bare untagged hashes +are used in BIP-119. =====The Ordering of Fields===== -Strictly speaking, the ordering of fields is insignificant. However, with a carefully selected -order, the efficiency of future scripts (e.g., those using a OP_CAT or OP_SHA256STREAM) may be -improved. +Strictly speaking, the ordering of fields is insignificant. However, with a +carefully selected order, the efficiency of future scripts (e.g., those using a +OP_CAT or OP_SHA256STREAM) may be improved (as described in the Future Upgrades +section). In particular, the order is selected in order of least likely to change to most. @@ -414,13 +458,6 @@ does not make sense for input index to be the last field. However, given the des able to express a "don't care" index easily (e.g., for decentralized kickstarter-type transactions), this value is placed last. -As an example, the following code checks an input index argument and concatenates it to the template and -checks the template matches the transaction. - - OP_SIZE 4 OP_EQUALVERIF - <nVersion || nLockTime || input count || sequences hash || output count || outputs hash> - OP_SWAP OP_CAT OP_SHA256 OP_CHECKTEMPLATEVERIFY - ===Design Tradeoffs and Risks=== Covenants have historically been controversial given their potential for fungibility risks -- coins could be minted which have a permanent restriction on how they may or may not be spent or required @@ -435,10 +472,10 @@ transactions which create all the inputs directly in this regard. Furthermore, templates are restricted to be spendable as a known number of inputs only, preventing unintentional introduction of the 'half spend' problem. - Templates, as restricted as they are, bear some risks. ====Permanently Unspendable Outputs==== + The preimage argument passed to CHECKTEMPLATEVERIFY may be unknown or otherwise unsatisfiable. However, requiring knowledge that an address is spendable from is incompatible with sender's ability to spend to any address (especially, OP_RETURN). If a sender needs to know the template can be spent @@ -446,6 +483,7 @@ from before sending, they may request a signature of an provably non-transaction from the leafs of the CHECKTEMPLATEVERIFY tree. ====Forwarding Addresses==== + Key-reuse with CHECKTEMPLATEVERIFY may be used as a form of "forwarding address contract". A forwarding address is an address which can automatically execute in a predefined way. For example, a exchange's hot wallet might use an address which can automatically be moved to a cold @@ -471,7 +509,6 @@ reuse-unsafe. Because CHECKTEMPLATEVERIFY commits to the input index currently being spent, reused-keys are guaranteed to execute in separate transactions which reduces the risk of "half-spend" type issues. - ====NOP-Default and Standardness Rules==== If the argument length is not exactly 32, CHECKTEMPLATEVERIFY treats it as a NOP. @@ -484,8 +521,8 @@ stricter standardness rules to be enforced during consensus. Should that develop transaction directly to the network relying on standardness rejection, an standardness-invalid but consensus-valid transaction may be caused, leading to a potential loss of funds. - ====Feature Redundancy==== + CHECKTEMPLATEVERIFY templates are substantially less risky than other covenant systems. If implemented, other covenant systems could make the CHECKTEMPLATEVERIFY's functionality redundant. However, given CHECKTEMPLATEVERIFY's simple semantics and low on chain cost it's likely that it @@ -499,26 +536,91 @@ unintended behavior. Alternatively, SIGHASH_ANYPREVOUTANYSCRIPT based covenant designs can implement something similar to templates, via a scriptPubKey like: - <sig of desired TX with PK and fixed nonce R || SIGHASH_ANYPREVOUTANYSCRIPT <PK with public SK> OP_CHECKSIG -SIGHASH_ANYPREVOUTANYSCRIPT bears additional technical and implementation risks that may preclude -its viability for inclusion in Bitcoin, but the capabilities above are similar to what -CHECKTEMPLATEVERIFY offers. However, CHECKTEMPLATEVERIFY has benefits in terms of verification -speed, as it requires only hash computation rather than signature operations. This can be -significant when constructing large payment trees or programmatic compilations. CHECKTEMPLATEVERIFY -also has a feature-wise benefit in that it provides a robust pathway for future template upgrades. - -CHECKSIGFROMSTACK along with OP_CAT may also be used to emulate CHECKTEMPLATEVERIFY. However such -constructions are more complicated to use than CHECKTEMPLATEVERIFY, and encumbers additional -verification overhead absent from CHECKTEMPLATEVERIFY. These types of covenants also bear similar -potential recursion issues to OP_COV which make it unlikely for inclusion in Bitcoin. - +SIGHASH_ANYPREVOUTANYSCRIPT bears additional technical and implementation risks +that may preclude its viability for inclusion in Bitcoin, but the capabilities +above are similar to what CHECKTEMPLATEVERIFY offers. The key functional +difference between SIGHASH_ANYPREVOUTANYSCRIPT and OP_CHECKTEMPLATEVERIFY is +that OP_CHECKTEMPLATEVERIFY restricts the number of additional inputs and +precludes dynamically determined change outputs while +SIGHASH_ANYPREVOUTANYSCRIPT can be combined with SIGHASH_SINGLE or +SIGHASH_ANYONECANPAY. For the additional inputs, OP_CHECKTEMPLATEVERIFY also +commits to the scriptsig and sequence, which allows for specifying specific P2SH +scripts (or segwit v0 P2SH) which have some use cases. Furthermore, +CHECKTEMPLATEVERIFY has benefits in terms of script size (depending on choice of +PK, SIGHASH_ANYPREVOUTANYSCRIPT may use about 2x-3x the bytes) and verification +speed, as OP_CHECKTEMPLATEVERIFY requires only hash computation rather than +signature operations. This can be significant when constructing large payment +trees or programmatic compilations. CHECKTEMPLATEVERIFY also has a feature-wise +benefit in that it provides a robust pathway for future template upgrades. + +OP_CHECKSIGFROMSTACKVERIFY along with OP_CAT may also be used to emulate +CHECKTEMPLATEVERIFY. However such constructions are more complicated to use +than CHECKTEMPLATEVERIFY, and encumbers additional verification overhead absent +from CHECKTEMPLATEVERIFY. These types of covenants also bear similar potential +recursion issues to OP_COV which make it unlikely for inclusion in Bitcoin. Given the simplicity of this approach to implement and analyze, and the benefits realizable by user applications, CHECKTEMPLATEVERIFY's template based approach is proposed in lieu of more complete covenants system. +====Future Upgrades==== + +This section describes updates to OP_CHECKTEMPLATEVERIFY that are possible in +the future as well as synergies with other possible upgrades. + +=====CHECKTEMPLATEVERIFY Versions===== + +OP_CHECKTEMPLATEVERIFY currently only verifies properties of 32 byte arguments. +In the future, meaning could be ascribed to other length arguments. For +example, a 33-byte argument could just the last byte as a control program. In +that case, DefaultCheckTemplateVerifyHash could be computed when the flag byte +is set to CTVHASH_ALL. Other programs could be added similar to SIGHASH_TYPEs. +For example, CTVHASH_GROUP could read data from the Taproot Annex for +compatibility with SIGHASH_GROUP type proposals and allow dynamic malleability +of which indexes get hashed for bundling. + +=====Eltoo with OP_CHECKSIGFROMSTACKVERIFY===== + +Were both OP_CHECKTEMPLATEVERIFY and OP_CHECKSIGFROMSTACKVERIFY to be added to +Bitcoin, it would be possible to implement a variant of Eltoo's floating +transactions using the following script: + + witness(S+n): <sig> <H(tx with nLockTime S+n paying to program(S+n))> + program(S): OP_CHECKTEMPLATEVERIFY <musig_key(pk_update_a, pk_update_b)> OP_CHECKSIGFROMSTACKVERIFY <S+1> OP_CHECKLOCKTIMEVERIFY + +Compared to SIGHASH_ANYPREVOUTANYSCRIPT, because OP_CHECKTEMPLATEVERIFY does not +allow something similar to SIGHASH_ANYONECANPAY or SIGHASH_SINGLE, protocol +implementers might elect to sign multiple versions of transactions with CPFP +Anchor Outputs or Inputs for paying fees or an alternative such as transaction +sponsors might be considered. + +=====OP_AMOUNTVERIFY===== + +An opcode which verifies the exact amount that is being spent in the +transaction, the amount paid as fees, or made available in a given output could +be used to make safer OP_CHECKTEMPLATEVERIFY addressses. For instance, if the +OP_CHECKTEMPLATEVERIFY program P expects exactly S satoshis, sending S-1 +satoshis would result in a frozen UTXO and sending S+n satoshis would result in +n satoshis being paid to fee. A range check could restrict the program to only +apply for expected values and default to a keypath otherwise, e.g.: + + IF OP_AMOUNTVERIFY <N> OP_GREATER <PK> CHECKSIG ELSE <H> OP_CHECKTEMPLATEVERIFY + +=====OP_CAT/OP_SHA256STREAM===== + +OP_CHECKTEMPLATEVERIFY is (as described in the Ordering of Fields section) +efficient for building covenants dynamically should Bitcoin get enhanced string +manipulation opcodes. + +As an example, the following code checks an input index argument and +concatenates it to the template and checks the template matches the transaction. + + OP_SIZE 4 OP_EQUALVERIF + <nVersion || nLockTime || input count || sequences hash || output count || outputs hash> + OP_SWAP OP_CAT OP_SHA256 OP_CHECKTEMPLATEVERIFY + == Backwards Compatibility == OP_CHECKTEMPLATEVERIFY replaces a OP_NOP4 with stricter verification semantics. Therefore, scripts @@ -527,15 +629,18 @@ for an OP_NOP are a soft fork, so existing software will be fully functional wit for mining and block validation. Similar soft forks for OP_CHECKSEQUENCEVERIFY and OP_CHECKLOCKTIMEVERIFY (see BIP-0065 and BIP-0112) have similarly changed OP_NOP semantics without introducing compatibility issues. +In contrast to previous forks, OP_CHECKTEMPLATEVERIFY will not make scripts +valid for policy until the new rule is active. + Older wallet software will be able to accept spends from OP_CHECKTEMPLATEVERIFY outputs, but will -require an upgrade in order to treat PayToBasicStandardTemplate chains with a confirmed ancestor as +require an upgrade in order to treat PayToBareDefaultCheckTemplateVerifyHash chains with a confirmed ancestor as being "trusted" (i.e., eligible for spending before the transaction is confirmed). Backports of OP_CHECKTEMPLATEVERIFY can be trivially prepared (see the reference implementation) for older node versions that can be patched but not upgraded to a newer major release. - == References == + *[https://utxos.org utxos.org informational site] *[https://www.youtube.com/watch?v=YxsjdIl0034&t=2451 Scaling Bitcoin Presentation] *[https://bitcoinops.org/en/newsletters/2019/05/29/ Optech Newsletter Covering OP_CHECKOUTPUTSHASHVERIFY] @@ -547,6 +652,7 @@ for older node versions that can be patched but not upgraded to a newer major re ===Note on Similar Alternatives=== + An earlier version of CHECKTEMPLATEVERIFY, CHECKOUTPUTSHASHVERIFY, is withdrawn in favor of CHECKTEMPLATEVERIFY. CHECKOUTPUTSHASHVERIFY did not commit to the version or lock time and was thus insecure. @@ -559,4 +665,5 @@ CHECKTEMPLATEVERIFY has also been previously referred to as OP_SECURETHEBAG, whi to aid in searching and referencing discussion on this BIP. ==Copyright== + This document is licensed under the 3-clause BSD license. diff --git a/bip-0155.mediawiki b/bip-0155.mediawiki index 19f92f2..3e7b0d8 100644 --- a/bip-0155.mediawiki +++ b/bip-0155.mediawiki @@ -131,7 +131,7 @@ See the appendices for the address encodings to be used for the various networks ==Signaling support and compatibility== -Introduce a new message type <code>sendaddrv2</code>. Sending such a message indicates that a node can understand and prefers to receive <code>addrv2</code> messages instead of <code>addr</code> messages. I.e. "Send me addrv2". +Introduce a new message type <code>sendaddrv2</code>. Sending such a message indicates that a node can understand and prefers to receive <code>addrv2</code> messages instead of <code>addr</code> messages. I.e. "Send me addrv2". Sending or not sending this message does not imply any preference with respect to receiving unrequested address messages. The <code>sendaddrv2</code> message MUST only be sent in response to the <code>version</code> message from a peer and prior to sending the <code>verack</code> message. diff --git a/bip-0157.mediawiki b/bip-0157.mediawiki index bb864aa..d641a8e 100644 --- a/bip-0157.mediawiki +++ b/bip-0157.mediawiki @@ -431,9 +431,9 @@ document proposes a solution purely at the P2P layer. The constant interval of 1,000 blocks between checkpoints was chosen so that, given the current chain height and rate of growth, the size of a -<code>cfcheckpt</code> message is not drastically from a -<code>cfheaders</code> between two checkpoints. Also, 1,000 is a nice round -number, at least to those of us who think in decimal. +<code>cfcheckpt</code> message is not drastically different from a +<code>cfheaders</code> message between two checkpoints. Also, 1,000 is a nice +round number, at least to those of us who think in decimal. == Compatibility == diff --git a/bip-0158.mediawiki b/bip-0158.mediawiki index ce4a4af..484e674 100644 --- a/bip-0158.mediawiki +++ b/bip-0158.mediawiki @@ -299,9 +299,9 @@ one is able to select <code>P</code> and <code>M</code> independently, then setting <code>M=1.497137 * 2^P</code> is close to optimal <ref>https://gist.github.com/sipa/576d5f09c3b86c3b1b75598d799fc845</ref>. -Empirical analysis also shows that was chosen as these parameters minimize the -bandwidth utilized, considering both the expected number of blocks downloaded -due to false positives and the size of the filters themselves. +Empirical analysis also shows that these parameters minimize the bandwidth +utilized, considering both the expected number of blocks downloaded due to false +positives and the size of the filters themselves. The parameter <code>k</code> MUST be set to the first 16 bytes of the hash (in standard little-endian representation) of the block for which the filter is diff --git a/bip-0173.mediawiki b/bip-0173.mediawiki index c3ee060..1fdd8be 100644 --- a/bip-0173.mediawiki +++ b/bip-0173.mediawiki @@ -208,7 +208,7 @@ be of the same length as the mainnet counterpart (to simplify implementations' assumptions about lengths), but still be visually distinct.</ref> for testnet. * The data-part values: -** 1 byte: the witness version +** 1 character (representing 5 bits of data): the witness version ** A conversion of the 2-to-40-byte witness program (as defined by [https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki BIP141]) to base32: *** Start with the bits of the witness program, most significant bit per byte first. *** Re-arrange those bits into groups of 5, and pad with zeroes at the end if needed. diff --git a/bip-0174.mediawiki b/bip-0174.mediawiki index 9434ce6..27e475f 100644 --- a/bip-0174.mediawiki +++ b/bip-0174.mediawiki @@ -65,7 +65,7 @@ be used as a separator and allow for easier unserializer implementation.</ref>. Where: ;<tt><keytype></tt> -: A compact size unsigned integer representing the type. This compact size unsigned integer must be minimally encoded, i.e. if the value can be represented using one byte, it must be represented as one byte. This must be unique within a specific <tt><map></tt>. +: A compact size unsigned integer representing the type. This compact size unsigned integer must be minimally encoded, i.e. if the value can be represented using one byte, it must be represented as one byte. There can be multiple entries with the same <tt><keytype></tt> within a specific <tt><map></tt>, but the <tt><key></tt> must be unique. ;<tt><keylen></tt> : The compact size unsigned integer containing the combined length of <tt><keytype></tt> and <tt><keydata></tt> ;<tt><valuelen></tt> @@ -125,7 +125,7 @@ The currently defined global types are as follows: | 2 | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | Fallback Locktime | <tt>PSBT_GLOBAL_FALLBACK_LOCKTIME = 0x03</tt> @@ -136,7 +136,7 @@ The currently defined global types are as follows: | | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | Input Count | <tt>PSBT_GLOBAL_INPUT_COUNT = 0x04</tt> @@ -147,7 +147,7 @@ The currently defined global types are as follows: | 2 | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | Output Count | <tt>PSBT_GLOBAL_OUTPUT_COUNT = 0x05</tt> @@ -158,18 +158,18 @@ The currently defined global types are as follows: | 2 | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | Transaction Modifiable Flags | <tt>PSBT_GLOBAL_TX_MODIFIABLE = 0x06</tt> | None | No key data -| <tt><single byte boolean> <single byte boolean> <bitvector></tt> -| A single byte boolean (0 for False, 1 for True) representing whether inputs can be modified, followed by a single byte boolean representing whether outputs can be modified. +| <tt><8-bit uint></tt> +| An 8 bit little endian unsigned integer as a bitfield for various transaction modification flags. Bit 0 is the Inputs Modifiable Flag and indicates whether inputs can be modified. Bit 1 is the Outputs Modifiable Flag and indicates whether outputs can be modified. Bit 2 is the Has SIGHASH_SINGLE flag and indicates whether the transaction has a SIGHASH_SINGLE signature who's input and output pairing must be preserved. Bit 2 essentially indicates that the Constructor must iterate the inputs to determine whether and how to add an input. | | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | SIGHASH_SINGLE Inputs | <tt>PSBT_GLOBAL_SIGHASH_SINGLE_INPUTS = 0x07</tt> @@ -180,7 +180,7 @@ The currently defined global types are as follows: | | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | PSBT Version Number | <tt>PSBT_GLOBAL_VERSION = 0xFB</tt> @@ -382,7 +382,7 @@ The currently defined per-input types are defined as follows: | 2 | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | Spent Output Index | <tt>PSBT_IN_OUTPUT_INDEX = 0x0f</tt> @@ -393,7 +393,7 @@ The currently defined per-input types are defined as follows: | 2 | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | Sequence Number | <tt>PSBT_IN_SEQUENCE = 0x10</tt> @@ -404,7 +404,7 @@ The currently defined per-input types are defined as follows: | | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | Required Time-based Locktime | <tt>PSBT_IN_REQUIRED_TIME_LOCKTIME = 0x11</tt> @@ -415,7 +415,7 @@ The currently defined per-input types are defined as follows: | | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | Required Height-based Locktime | <tt>PSBT_IN_REQUIRED_HEIGHT_LOCKTIME = 0x12</tt> @@ -426,7 +426,73 @@ The currently defined per-input types are defined as follows: | | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] +|- +| Taproot Key Spend Signature +| <tt>PSBT_IN_TAP_KEY_SIG = 0x13</tt> +| None +| No key data +| <tt><signature></tt> +| The 64 or 65 byte Schnorr signature for key path spending a Taproot output. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] +|- +| Taproot Script Spend Signature +| <tt>PSBT_IN_TAP_SCRIPT_SIG = 0x14</tt> +| <tt><xonlypubkey> <leafhash></tt> +| A 32 byte X-only public key involved in a leaf script concatenated with the 32 byte hash of the leaf it is part of. +| <tt><signature></tt> +| The 64 or 65 byte Schnorr signature for this pubkey and leaf combination. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] +|- +| Taproot Leaf Script +| <tt>PSBT_IN_TAP_LEAF_SCRIPT = 0x15</tt> +| <tt><control block></tt> +| The control block for this leaf as specified in BIP 341. The control block contains the merkle tree path to this leaf. +| <tt><script> <8-bit uint></tt> +| The script for this leaf as would be provided in the witness stack followed by the single byte leaf version. Note that the leaves included in this field should be those that the signers of this input are expected to be able to sign for. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] +|- +| Taproot Key BIP 32 Derivation Path +| <tt>PSBT_IN_TAP_BIP32_DERIVATION = 0x16</tt> +| <tt><xonlypubkey></tt> +| A 32 byte X-only public key involved in this input. It may be the internal key, or a key present in a leaf script. +| <tt><hashes len> <leaf hash>* <4 byte fingerprint> <32-bit uint>*</tt> +| A compact size unsigned integer representing the number of leaf hashes, followed by a list of leaf hashes, followed by the 4 byte master key fingerprint concatenated with the derivation path of the public key. The derivation path is represented as 32-bit little endian unsigned integer indexes concatenated with each other. Public keys are those needed to spend this output. The leaf hashes are of the leaves which involve this public key. The internal key does not have leaf hashes, so can be indicated with a <tt>hashes len</tt> of 0. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] +|- +| Taproot Internal Key +| <tt>PSBT_IN_TAP_INTERNAL_KEY = 0x17</tt> +| None +| No key data +| <tt><pubkey></tt> +| The X-only pubkey used as the internal key in this output. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] +|- +| Taproot Merkle Root +| <tt>PSBT_IN_TAP_MERKLE_ROOT = 0x18</tt> +| None +| No key data +| <tt><pubkey></tt> +| The 32 byte Merkle root hash. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] |- | Proprietary Use Type | <tt>PSBT_IN_PROPRIETARY = 0xFC</tt> @@ -482,7 +548,7 @@ determine which outputs are change outputs and verify that the change is returni | <tt>PSBT_OUT_BIP32_DERIVATION = 0x02</tt> | <tt><public key></tt> | The public key -| <tt><{32-bit uint> <32-bit uint>*</tt> +| <tt><32-bit uint> <32-bit uint>*</tt> | The master key fingerprint concatenated with the derivation path of the public key. The derivation path is represented as 32-bit little endian unsigned integer indexes concatenated with each other. Public keys are those needed to spend this output. | | @@ -498,10 +564,10 @@ determine which outputs are change outputs and verify that the change is returni | 2 | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] |- | Output Script -| <tt>PSBT_OUT_SCRIPT = 0x03</tt> +| <tt>PSBT_OUT_SCRIPT = 0x04</tt> | None | No key data | <tt><script></tt> @@ -509,7 +575,51 @@ determine which outputs are change outputs and verify that the change is returni | 2 | 0 | 2 -| [[bip-psb2.mediawiki|psbt2]] +| [[bip-0370.mediawiki|370]] +|- +| Taproot Internal Key +| <tt>PSBT_OUT_TAP_INTERNAL_KEY = 0x05</tt> +| None +| No key data +| <tt><pubkey></tt> +| The X-only pubkey used as the internal key in this output. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] +|- +| Taproot Tree +| <tt>PSBT_OUT_TAP_TREE = 0x06</tt> +| None +| No key data +| <tt>{<8-bit uint depth> <8-bit uint leaf version> <scriptlen> <script>}*</tt> +| One or more tuples representing the depth, leaf version, and script for a leaf in the Taproot tree, allowing the entire tree to be reconstructed. The tuples must be in depth first search order so that the tree is correctly reconstructed. Each tuple is an 8-bit unsigned integer representing the depth in the Taproot tree for this script, an 8-bit unsigned integer representing the leaf version, the length of the script as a compact size unsigned integer, and the script itself. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] +|- +| Taproot Leaf Script +| <tt>PSBT_OUT_TAP_LEAF_SCRIPT = 0x06</tt> +| <tt><control block></tt> +| The control block for this leaf as specified in BIP 341. The control block contains the merkle tree path to this leaf. +| <tt><script></tt> +| The script for this leaf as would be provided in the witness stack. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] +|- +| Taproot Key BIP 32 Derivation Path +| <tt>PSBT_OUT_TAP_BIP32_DERIVATION = 0x07</tt> +| <tt><xonlypubkey></tt> +| A 32 byte X-only public key involved in this output. It may be the internal key, or a key present in a leaf script. +| <tt><hashes len> <leaf hash>* <4 byte fingerprint> <32-bit uint>*</tt> +| A compact size unsigned integer representing the number of leaf hashes, followed by a list of leaf hashes, followed by the 4 byte master key fingerprint concatenated with the derivation path of the public key. The derivation path is represented as 32-bit little endian unsigned integer indexes concatenated with each other. Public keys are those needed to spend this output. The leaf hashes are of the leaves which involve this public key. The internal key does not have leaf hashes, so can be indicated with a <tt>hashes len</tt> of 0. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +| [[bip-0371.mediawiki|371]] |- | Proprietary Use Type | <tt>PSBT_OUT_PROPRIETARY = 0xFC</tt> @@ -544,7 +654,7 @@ values are valid, then it does not matter which is chosen as either way the tran ===Proprietary Use Type=== -For all global, per-input, and per-output maps, the types <tt>0xFC</tt> is reserved for proprietary use. +For all global, per-input, and per-output maps, the type <tt>0xFC</tt> is reserved for proprietary use. The proprietary use type requires keys that follow the type with a compact size unsigned integer representing the length of the string identifer, followed by the string identifier, then a subtype, and finally any key data. The identifier can be any variable length string that software can use to identify whether the particular data in the proprietary type can be used by it. @@ -554,7 +664,7 @@ The subtype is defined by the proprietary type user and can mean whatever they w The subtype must also be a compact size unsigned integer in the same form as the normal types. The key data and value data are defined by the proprietary type user. -The proprietary use types is for private use by individuals and organizations who wish to use PSBT in their processes. +The proprietary use type is for private use by individuals and organizations who wish to use PSBT in their processes. It is useful when there are additional data that they need attached to a PSBT but such data are not useful or available for the general public. The proprietary use type is not to be used by any public specification and there is no expectation that any publicly available software be able to understand any specific meanings of it and the subtypes. This type must be used for internal processes only. @@ -688,6 +798,8 @@ Or, for participants performing fA(psbt) and fB(psbt): Combine(fA(psbt), fB(psbt The Input Finalizer must only accept a PSBT. For each input, the Input Finalizer determines if the input has enough data to pass validation. If it does, it must construct the <tt>0x07</tt> Finalized scriptSig and <tt>0x08</tt> Finalized scriptWitness and place them into the input key-value map. +If scriptSig is empty for an input, <tt>0x07</tt> should remain unset rather than assigned an empty array. +Likewise, if no scriptWitness exists for an input, <tt>0x08</tt> should remain unset rather than assigned an empty array. All other data except the UTXO and unknown fields in the input key-value map should be cleared from the PSBT. The UTXO should be kept to allow Transaction Extractors to verify the final network serialized transaction. ===Transaction Extractor=== @@ -727,7 +839,7 @@ If an updater is updating a PSBT and needs to add a field that is only available ===Procedure For New Fields=== New fields should first be proposed on the bitcoin-dev mailing list. -If a field requires significatn description as to its usage, it should be accompanied by a separate BIP. +If a field requires significant description as to its usage, it should be accompanied by a separate BIP. The field must be added to the field listing tables in the Specification section. ===Procedure For New Versions=== diff --git a/bip-0300.mediawiki b/bip-0300.mediawiki index 08f8994..f8c9b4d 100644 --- a/bip-0300.mediawiki +++ b/bip-0300.mediawiki @@ -15,143 +15,181 @@ ==Abstract== -A "Hashrate Escrow" is a clearer term for the concept of "locked to an SPV Proof", which is itself a restatement of the phrase "within a sidechain" as described in [https://blockstream.com/sidechains.pdf the 2014 Blockstream whitepaper]. +In Bip300, txns are not signed via cryptographic key. Instead, they are "signed" by the accumulation of hashpower over time. -A Hashrate Escrow resembles a 2-of-3 multisig escrow, where the 3rd party (who will arbitrate any disputes) is a decentralized group of people: the dynamic-membership set of Bitcoin Miners. However, the 3rd party does not sign escrow-withdrawal transactions with a private key. Instead, these are "signed" by the accumulation of hashpower over time. +Bip300 emphasizes slow, transparent, auditable transactions which are easy for honest users to get right and very hard for dishonest users to abuse. The chief design goal for Bip300 is ''partitioning'' -- users may safely ignore Bip300 txns if they want to (or Bip300 entirely). -This project has [http://www.drivechain.info/ a website] which includes [http://www.drivechain.info/faq/index.html an FAQ]. +See [http://www.drivechain.info/ this site] for more information. ==Motivation== -In practice these escrows are likely to be "asymmetric sidechains" of Bitcoin (such as [http://www.rsk.co/ Rootstock]) or "virtual chains" within Bitcoin (such as [https://github.com/blockstack/virtualchain proposed by Blockstack] in mid-2016). -Sidechains have many potential benefits, including: +As Reid Hoffman [https://blockstream.com/2015/01/13/en-reid-hoffman-on-the-future-of-the-bitcoin-ecosystem/ wrote in 2014]: "Sidechains allow developers to add features and functionality to the Bitcoin universe without actually modifying the Bitcoin Core code...Consequently, innovation can occur faster, in more flexible and distributed ways, without losing the synergies of a common platform with a single currency." -# Protect Bitcoin from competition from altcoins and spinoffs. -# Protect Bitcoin from hard fork campaigns. (Such campaigns represent an existential threat to Bitcoin, as well as an avenue for developer corruption.) -# Help with review, by making it much easier for reviewers to ignore bad ideas. -# Provide an avenue for good-but-confusing ideas to prove their value safely. +Coins such as Namecoin, Monero, ZCash, and Sia, offer features that Bitcoiners cannot access -- not without selling their BTC to invest in a rival monetary unit. According to [https://coinmarketcap.com/charts/#dominance-percentage coinmarketcap.com], there is now more value *outside* the BTC protocol than within it. According to [https://cryptofees.info/ cryptofees.info], 10x more txn fees are paid outside the BTC protocol, than within it. +Software improvements to Bitcoin rely on developer consensus -- BTC will pass on a good idea if it is even slightly controversial. Development is slow: we are now averaging one major feature every 5 years. +Sidechains allow for competitive "benevolent dictators" to create a new sidechain at any time. These dictators are accountable only to their users, and (crucially) they are protected from rival dictators. Users can move their BTC among these different pieces of software, as *they* see fit. -==Specification== - -==== Components ==== - -Hashrate Escrows are built of two types of component: [1] new databases, and [2] new message-interpretations. - -===== 1. New Databases ===== +BTC can copy every useful technology, as soon as it is invented; scamcoins lose their justification and become obsolete; and the community can be pro-creativity, knowing that Layer1 is protected from harmful changes. -* D1. "Escrow_DB" -- a database of "accounts" and their attributes. -* D2. "Withdrawal_DB" -- a database of pending withdrawals from these accounts, and their statuses. +==Specification== -Please note that these structures (D1 and D2) will not literally exist anywhere in the blockchain. Instead they are constructed from messages...these messages, in contrast, *will* exist in the blockchain (with the exception of M4). +Bip300 allows for six new blockchain messages: -===== 2. New Messages ===== +* M1. "Propose New Sidechain" +* M2. "ACK Proposal" +* M3. "Propose Bundle" +* M4. "ACK Bundle" +* M5. Deposit -- a transfer of BTC from-main-to-side +* M6. Withdrawal -- a transfer of BTC from-side-to-main -* M1. "Propose New Escrow" -* M2. "ACK Escrow Proposal" -* M3. "Propose Withdrawal" -* M4. (implied) "ACK Withdrawal" -* M5. "Execute Deposit" -- a transfer of BTC from-main-to-side -* M6. "Execute Withdrawal" -- a transfer of BTC from-side-to-main +Nodes organize those messages into two caches: +* D1. "Escrow_DB" -- tracks the 256 Hashrate Escrows (Escrows slots that a sidechain can live in). +* D2. "Withdrawal_DB" -- tracks the withdrawal-Bundles (coins leaving a Sidechain). +We will cover: +# Adding Sidechains (D1, M1, M2) +# Approving Withdrawals (D2, M3, M4) +# Depositing and Withdrawing (M5, M6) === Adding Sidechains (D1, M1, M2) === -==== D1 -- "Escrow_DB" ==== -The table below enumerates the new database fields, their size in bytes, and their purpose. In general, an escrow designer (for example, a sidechain-designer), is free to choose any value for these. +==== D1 -- "Escrow_DB" ==== +The table below enumerates the new database fields, their size in bytes, and their purpose. A sidechain designer is free to choose any value for these. {| class="wikitable" +|- style="font-weight:bold; text-align:center; vertical-align:middle;" ! Field No. ! Label ! Type ! Description / Purpose -|- +|- style="vertical-align:middle;" | 1 | Escrow Number | uint8_t -| A number assigned to the entire escrow. Used to make it easy to refer to each escrow. +| The escrow's ID number. Used to uniquely refer to each sidechain. |- | 2 -| Sidechain Deposit Script Hex -| string -| The script that will be deposited to, and update the CTIP of the sidechain. +| Version +| int32_t +| Version number. |- | 3 +| String KeyID +| string +| Used to derive all sidechain deposit addresses. +|- +| 4<br /> | Sidechain Private Key | string | The private key of the sidechain deposit script. -|- -| 4 -| Escrow Name +|- style="vertical-align:middle;" +| 5<br /> +| ScriptPubKey +| CScript +| Where the sidechain coins go. This always stays the same, even though the CTIP (UTXO) containing the coins is always changing. +|- style="vertical-align:middle;" +| 6 +| Sidechain Name | string | A human-readable name of the sidechain. -|- -| 5 -| Escrow Description -| string -| A human-readable name description of the sidechain. More than enough space to hold a 32 byte hash. -|- -| 6 -| Hash ID 1 -| uint256 -| A field of 32 bytes, which could be any bytes such as a sha256 hash. -|- +|- style="vertical-align:middle;" | 7 -| Hash ID 2 +| Sidechain Description +| string +| A human-readable name description of the sidechain. +|- style="vertical-align:middle;" +| 8 +| Hash1 - tarball hash | uint256 -| A field of 32 bytes, which could be any bytes such as a sha256 hash. +| Intended as the sha256 hash of the tar.gz of the canonical sidechain software. (This is not enforced anywhere by Bip300, and is for human purposes only.) +|- style="vertical-align:middle;" +| 9 +| Hash2 - git commit hash +| uint160 +| Intended as the git commit hash of the canonical sidechain node software. (This is not enforced anywhere by Bip300, and is for human purposes only.) |- -| 8 +| 10 +| Active +| bool +| Does this sidechain slot contain an active sidechain?<br /> +|- style="vertical-align:middle;" +| 11 | "CTIP" -- Part 1 "TxID" | uint256 -| The CTIP, or "Critical (TxID, Index) Pair" is a variable for keeping track of where the escrow's money is (ie, which member of the UTXO set). -|- -| 9 +| The CTIP, or "Critical (TxID, Index) Pair" is a variable for keeping track of where the sidechain's money is (ie, which member of the UTXO set). +|- style="vertical-align:middle;" +| 12 | "CTIP" -- Part 2 "Index" | int32_t -| Of the CTIP, this is second element of the pair: the Index. See #9 above. -|- +| Of the CTIP, the second element of the pair: the Index. See #11 above. |} D1 is updated via M1 and M2. -( The following messages were modeled on SegWit -- see [https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#commitment-structure here] and [https://github.com/DriveNetTESTDRIVE/DriveNet/blob/564516653c1d876429382971a011f5f6119f7eb4/src/validation.cpp#L3348-L3375 here]. ) - ==== M1 -- "Propose New Sidechain" ==== +Examples: + +<img src="bip-0300/m1-gui.jpg?raw=true" align="middle"></img> + +<img src="bip-0300/m1-cli.png?raw=true" align="middle"></img> + +M1 is a coinbase OP Return output containing the following: + 1-byte - OP_RETURN (0x6a) - 4-byte - Commitment header (0xD5E0C4AF) + 4-byte - Message header (0xD5E0C4AF) N-byte - The serialization of the sidechain. - + 1-byte nSidechain + 4-byte nVersion + x-byte strKeyID + x-byte strPrivKey + x-byte scriptPubKey + x-byte title + x-byte description + 32-byte hashID1 + 20-byte hashID2 + +M1 is used in conjunction with M2. ==== M2 -- "ACK Sidechain Proposal" ==== 1-byte - OP_RETURN (0x6a) - 4-byte - Commitment header (0xD6E1C5BF) - 32-byte - Commitment hash: sha256D hash of sidechain's serialization + 4-byte - Message header (0xD6E1C5BF) + 32-byte - sha256D hash of sidechain's serialization -==== New Block Validation Rules ==== +==== M1/M2 Validation Rules ==== +# Any miner can propose a new sidechain at any time. This procedure resembles BIP 9 soft fork activation: the network must see a properly-formatted M1, followed by "acknowledgment" of the sidechain in 90% of the following 2016 blocks. +# It is possible to "overwrite" a sidechain. This requires more ACKs -- 50% of the following 26300 blocks must contain an M2. The possibility of overwrite, does not change the security assumptions (because we already assume that users perform extra-protocolic validation at a rate of 1 bit per 26300 blocks). -# Escrows are added in a procedure that resembles BIP 9 soft fork activation: the network must see a properly-formatted M1, followed by "acknowledgment" of the sidechain in 95% of the following 2016 blocks. -# It is possible to "overwrite" an escrow. This requires 6 months (26298 blocks) of M2s, instead of 2 weeks (XXXX). This possibility does not change the security assumptions (because we already assume that users perform extra-protocolic validation at a rate of 1 bit per 26298 blocks). +=== Approving Withdrawals (D2, M3, M4) === +Withdrawals in Bip300 (ie, "M6"), are very significant. So, we will first discuss how these are approved/rejected -- a process involving M3, M4, and D2. + +==== What are Bundles? ==== + +All Bip300 withdrawals take the form of “Bundles” (formerly known as “WT^s”) -- named because they "bundle up" many individual withdrawal-requests into one single rare layer1 transaction. + +This bundle either pays all of the withdrawals out, or else it fails (and pays nothing out). Bip300 / layer 1 does not assemble Bundles (the sidechain developer does this in a manner of their choosing). + +Bundles are identified by a 32-byte hash, which aspires to be the TxID of M6. Unfortunately, the Bundle-hash and M6-TxID cannot match exactly, since the first input to M6 is a CTIP which is constantly changing. So, we must accomplish a task, which is conceptually similar to AnyPrevOut (BIP 118). We define a "blinded TxID" as a way of hashing a txn, in which some bytes are first overwritten with zeros. In our case, these bytes are the first input and the first output. + +D2 controls Bundles, and is driven by M3, M4, M5, and M6. -=== Withdrawing from Escrows (D2, M3, M4) === ==== D2 -- "Withdrawal_DB" ==== -D2 changes deterministically with respect to M3, M4, M5, and M6. {| class="wikitable" ! Field No. @@ -160,117 +198,108 @@ D2 changes deterministically with respect to M3, M4, M5, and M6. ! Description / Purpose |- | 1 -| Escrow Number +| Sidechain Number | uint8_t -| Links the withdrawal-request to a specific escrow. +| Links the withdrawal-request to a specific hashrate escrow. |- | 2 -| WT^ Hash +| Bundle Hash | uint256 -| This is a "blinded transaction id" (ie, the double-Sha256 of a txn that has had two fields zeroed out, see M6) of a withdrawal-attempt. +| A withdrawal attempt. Specifically, it is a "blinded transaction id" (ie, the double-Sha256 of a txn that has had two fields zeroed out, see M6) of a txn which could withdraw funds from a sidechain. |- | 3 | ACKs (Work Score) | uint16_t -| The current total number of ACKs (PoW) +| The current total number of ACKs (the PoW that has been used to validate the Bundle). |- | 4 | Blocks Remaining (Age) | uint16_t -| The number of blocks which this WT^ has remaining to accumulate ACKs +| The number of blocks which this Bundle has remaining to accumulate ACKs |} +A hash of D2 exists in each coinbase txn, and has consensus-significance. -==== New Block Validation Rules for D2 ==== +==== D2 Validation Rules ==== -# A hash commitment to D2 exists in each block (even if D2 is blank). -# Withdrawals in D2 are sorted first by field #1 (Escrow Number) and second by field #4 (Age). This imposes a unique sort. -# From one block to the next, "Age" fields must increase by exactly 1. -# Withdrawals are stored in D2 until they fail ("Age" = "MaxAge"), or they succeed (the blockchain contains a txn whose blinded txID matches "WT^"). +# The D2 hash commitment must be in each block (unless D2 is blank). +# The Bundles must be listed in a canonical order (so that the hashes match). +# From one block to the next, "Age" fields must increase by exactly 1 (ie, Blocks Remaining decreases by 1). +# Bundles are stored in D2 until they fail (which occurs at "Age" = "MaxAge"), or they succeed (Bundle is paid out). +# From one block to the next, the value in the ACKs field can increase or decrease by a maximum of 1 (see below). -In addition, there are special rules for the "ACKs" field (see M4 below). +If a Bundle succeeds (in D2), it "becomes" an M6 message and is included in a block. -==== M3 -- "Propose Withdrawal" ==== +So, first: how do we add a Bundle to D2? + +==== M3 -- "Propose Bundle" ==== + + +Nodes will add an entry to D2 if there is a coinbase output with the following: 1-byte - OP_RETURN (0x6a) - 1-byte - Push the following 36 bytes (0x24) 4-byte - Commitment header (0xD45AA943) - 32-byte - The WT^ hash to populate a new D2 entry + 32-byte - The Bundle hash, to populate a new D2 entry -==== New Block Validation Rules for M3 ==== +==== M3 Validation Rules ==== -# If the network detects a properly-formatted M3, it must add an entry to D2 in the very next block. The starting values of fields #3 and #4 are zero, and #5 is pulled over by extracting the relevant value from D1. +# If the network detects a properly-formatted M3, it must add an entry to D2 in the very next block. The starting Blocks Remaining value is 26,299. The starting ACKs count is 1. # Each block can only contain one M3 per sidechain. +Once a Bundle is in D2, how can we give it enough ACKs to make it valid? ==== M4 -- "ACK Withdrawal" ==== -M4 is a way of describing changes to the "ACKs" column of D2. - From one block to the next, "ACKs" can only change as follows: -* The ACK-counter of any withdrawal can only change by (-1,0,+1). -* Within a sidechain-group, upvoting one withdrawal ("+1") requires you to downvote all other withdrawals in that group. However, the minimum ACK-value is zero (and, therefore, downvotes cannot reduce it below zero). -* While only one withdrawal can be upvoted at once, they can all be unchanged at once ("abstain") and they can all be downvoted at once ("alarm"). +* The ACK-counter of any Bundle can only change by (-1,0,+1). +* Within a sidechain-group, upvoting one Bundle ("+1") requires you to downvote all other Bundles in that group. However, the minimum ACK-value is zero. +* While only one Bundle can be upvoted at once; the whole group can all be unchanged at once ("abstain"), and they can all be downvoted at once ("alarm"). -One option for explicit transmission of M4 is: +M4 does not need to be explicitly transmitted. It can simply be inferred from the new state of D2. M4 can therefore be improved over time, without affecting consensus. - 4-byte - Message identifier (0x????????) - 1-byte - Version of this message - 1-byte - Length (in bytes) of this message; total number of withdrawal attempts; y = ceiling( sum_i(m_i +2)/8 ). Nodes should already know what length to expect, because they know the sequence of M3s and therefore the vector of WT^s. - N-byte - stream of bits (not bytes), with a 1 indicating the position of the chosen action [downvote all, abstain, upvote1, upvote2, ...] +Nonetheless, one option for explicit transmission of M4 is [https://github.com/drivechain-project/mainchain/blob/8901d469975752d799b6a7a61d4e00a9a124028f/src/validation.cpp#L3735-L3790 in our code]. -But sometimes M4 does not need to be transmitted at all! If there are n Escrows and m Withdrawals-per-escrow, then there are (m+2)^n total candidates for the next D2. So, when m and n are low, all of the possible D2s can be trivially computed in advance. +Often, M4 does not need to be transmitted at all. If there are n Sidechains and m Withdrawals-per-sidechain, then there are (m+2)^n total candidates for the next D2. So, when m and n are low, all of the possible D2s can be trivially computed in advance. -Miners can impose a "soft limit" on m, blocking new withdrawal-attempts until previous ones expire. For a worst-case scenario of n=200 and m=1,000, honest nodes can communicate M4 with ~25 KB per block [4+1+1+(200\*(1000+1+1)/8)]. +Miners can impose a "soft limit" on m, blocking new withdrawal-attempts until previous ones expire. Even if they fail to do this, a a worst-case scenario of n=200 and m=1,000, honest nodes can communicate the M4 with ~25 KB per block [4+1+1+(200\*(1000+1+1)/8)]. +Finally, we give Deposits and Withdrawals. -=== Depositing and Withdrawing (M5, M6) === +=== Deposits and Withdrawals (M5, M6) === -Both M5 and M6 are regular Bitcoin txns. They are identified by meeting an important criteria: they select a one of the Critical TxID-index Pairs (a "CTIP") as one of their inputs. +Both M5 and M6 are regular Bitcoin txns. They are identified, as Deposits/Withdrawals, when they select one of the special CTIP UTXOs as one of their inputs (see D1). -Just as these txns must select a CTIP input, they must create a new CTIP output. D1 is then updated to match only the latest CTIP output. The purpose of this is to have all of the escrow's money (ie all of the sidechain's money) in one TxID, so that depositors immediately undo any UTXO bloat they may cause. -Deposits ("M5") are distinguished from withdrawals ("M6") by simply checking to see if money is "going in", or "out". +All of a sidechain’s coins, are stored in one UTXO. (Deposits/Withdrawals never cause UTXO bloat.) So, each Deposit/Withdrawal must select a CTIP, and generate a new CTIP (this is tracked in D1, above). -https://github.com/DriveNetTESTDRIVE/DriveNet/blob/564516653c1d876429382971a011f5f6119f7eb4/src/validation.cpp#L647-L742 +If the from-CTIP-to-CTIP quantity of coins goes '''up''', (ie, if the user is adding coins), then the txn is treated as a Deposit (M5). Else it is treated as a Withdrawal (M6). See [https://github.com/drivechain-project/mainchain/blob/8901d469975752d799b6a7a61d4e00a9a124028f/src/validation.cpp#L668-L781 here]. ==== M5. "Make a Deposit" -- a transfer of BTC from-main-to-side ==== -As far as mainchain consensus is concerned, deposits to the escrow are always valid. - -However, in practice there will be additional requirements. The escrow account (ie the "sidechain") needs to know how to credit depositors. One well-known method, is for mainchain depositors to append a zero-value OP Return to a Deposit txn, so that the sidechain knows how to credit funds. Mainchain users must upgrade their wallet software, of course, (on an individual basis) in order to become aware of and take advantage of new deposit-methods. - - +As far as mainchain consensus is concerned, all deposits to a sidechain are always valid. ==== M6. "Execute Withdrawal" -- a transfer of BTC from-side-to-main ==== -We come, finally, to the critical matter: where users can take their money *out* of the escrow account, and return it to the "regular" UTXO set. As previously mentioned, this txn is one which (a) spends from a CTIP and (b) reduces the quantity of BTC in an account's CTIP. Most of the work has already been done by D1, M3, M4, and D2. Furthermore, existing Bitcoin tx-rules prevent the sidechain from ever withdrawing more money than has been placed into it. +We come, finally, to the critical matter: where users can take their money *out* of the sidechain. -In each block, a withdrawal in D2 is considered "approved" if its "ACKs" value meets the threshold (13,150). +In each block, a Bundle in D2 is considered "approved" if its "ACKs" value meets the threshold (13,150). -Approved withdrawals give the green light to their respective "WT^". A "WT^" is 32-bytes which aspire to represent the withdrawing transaction (the txn that actually withdraws funds from the escrow). The two cannot match exactly, because "WT^" is defined at onset, and the withdrawing TxID depends on the its CTIP input (which is constantly changing). -To solve this, we define a "blinded TxID" as a way of hashing a txn, in which some bytes are first overwritten with zeros. Specifically, these bytes are the first input and the first output. +The Bundle must meet all these criteria: -So, withdrawals must meet the following three criteria: - -# "Be ACKed" -- The "blinded TxID" of this txn must be member of the "approved candidate" set in the D2 of this block. -# "Return Change to Account" -- TxOut0 must pay to the "critical account" (see D1) that corresponds to the CTIP that was selected as a TxIn. +# "Be ACKed" -- The "blinded TxID" of this txn must be a member of the "approved candidate" set in the D2 of this block. +# "Return Change to Account" -- TxOut0 must pay coins back to the sidechain's CTIP. # "Return *all* Change to Account" -- Sum of inputs must equal the sum of outputs. No traditional tx fee is possible. - - - ==Backward compatibility== - As a soft fork, older software will continue to operate without modification. Non-upgraded nodes will see a number of phenomena that they don't understand -- coinbase txns with non-txn data, value accumulating in anyone-can-spend UTXOs for months at a time, and then random amounts leaving the UTXO in single, infrequent bursts. However, these phenomena don't affect them, or the validity of the money that they receive. -( As a nice bonus, note that the sidechains themselves inherit a resistance to hard forks. The only way to guarantee that the WT^s reported by different clients will continue to match identically, is to upgrade sidechains via soft forks of themselves. ) +( As a nice bonus, note that the sidechains themselves inherit a resistance to hard forks. The only way to guarantee that a sidechain's Bundles will continue to match identically, is to upgrade sidechains via soft forks of themselves. ) ==Deployment== @@ -281,10 +310,9 @@ This BIP will be deployed by "version bits" BIP9 with the name "hrescrow" and us <pre> // Deployment of Drivechains (BIPX, BIPY) consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].bit = 4; -consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nStartTime = 1579072881; // January 15th, 2020. -consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nTimeout = 1610695281; // January 15th, 2021. +consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nStartTime = 1642276800; // January 15th, 2022. +consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nTimeout = 1673812800; // January 15th, 2023. </pre> - ==Reference Implementation== diff --git a/bip-0300/appendix-1.txt b/bip-0300/appendix-1.txt deleted file mode 100644 index 736a6c4..0000000 --- a/bip-0300/appendix-1.txt +++ /dev/null @@ -1,45 +0,0 @@ - -==== Two Withdrawals at Once ==== - -Currently, the documentation and code describe a situation where only one withdrawal can proceed at a time. As a result, one "train" (carrying everyone's withdrawals) leaves the station every 3 months, and takes 3-6 months to reach its destination. - -Thus, if a withdrawing-user is very unlucky, and "just misses" the train, this user must wait double-long. First, (s)he must wait for the missed-train to reach its destination. Second, (s)he must board the new train, and wait for *it* to reach its destination. Each of these steps takes 3-6 months. - -So, even when withdrawals always go as quickly as possible (3 months each), the total time varies, from 3 months (0 months waiting + 3 months travel) to 6 months (3 months waiting + 3 months travel). The average is 4.5 months. - -To improve this, we allow for slightly different behavior if the highest-ACK-withdrawal [1st] has an ACK score >= 6575; and [2nd] is not tied with any other withdrawal. - -Basically: a second train can leave, if the furthest train is 50+% of the way to its destination. - -So, previously, for m trains, M4 could be any of the following: - - abstain - alarm (move all trains backwards) - move train #1 forward (and others backwards) - move train #2 forward (and others backwards) - ... - move train #3 forward (and others backwards) - -If our new special conditions apply, we now double the (m-1) elements, to accommodate a second train: - - |abstain - |alarm (move all trains backwards) - - |advance furthest train + advance train #1 (regress all others) - |advance furthest train + advance train #2 (regress all others) - |... - |advance furthest train + advance train #(m-1) (regress all others) - - |regress furthest train + advance train #1 (regress all others) - |regress furthest train + advance train #2 (regress all others) - |... - |regress furthest train + advance train #(m-1) (regress all others) - - -It is theoretically possible (but in practice probably impossible) to troll this rule, by getting two (or even three) withdrawals to have >6575 ACK scores, and then getting these to *tie* for first place. Then they'd both be furthest. Hence the second condition prohibiting this new behavior, if the furthest trains have any ACK-score ties. - -This simple change, which has almost zero impact on the security assumptions, improves the monthly total wait times drastically: - - Worst-case: 6 --> 4.5 - Average: 4.5 --> 3.75 - Std Dev: ~.91 --> ~.45 diff --git a/bip-0300/m1-cli.png b/bip-0300/m1-cli.png Binary files differnew file mode 100644 index 0000000..2454848 --- /dev/null +++ b/bip-0300/m1-cli.png diff --git a/bip-0300/m1-gui.jpg b/bip-0300/m1-gui.jpg Binary files differnew file mode 100644 index 0000000..edae79c --- /dev/null +++ b/bip-0300/m1-gui.jpg diff --git a/bip-0300/two-groups.png b/bip-0300/two-groups.png Binary files differdeleted file mode 100644 index c8a3ffa..0000000 --- a/bip-0300/two-groups.png +++ /dev/null diff --git a/bip-0301.mediawiki b/bip-0301.mediawiki index d6056f2..2f6b79e 100644 --- a/bip-0301.mediawiki +++ b/bip-0301.mediawiki @@ -12,181 +12,151 @@ License: BSD-2-Clause </pre> -==Abstract== - -Blind Merged Mining (BMM) is a way of mining optional extension blocks (ie, "asymmetric sidechains"). BMM produces weak guarantees that the block is valid, for *any* arbitrary set of rules; and yet it does so without requiring miners to actually do any validation on the block whatsoever. +==Abstract== -BMM actually is a process that spans two or more chains. Here we focus on the modifications to mainchain Bitcoin. For an explanation of the "whole picture", please see [http://www.truthcoin.info/blog/blind-merged-mining/ this post]. +Blind Merged Mining (BMM) allows miners to mine a Sidechain/Altcoin, without running its node software (ie, without "looking" at it, hence "blind"). -Our goal here, is to allow mainchain miners to trustlessly "sell" the act of finding a sidechain block. +Instead, a separate sidechain user runs their node and constructs the block, paying himself the transaction fees. He then uses an equivalent amount of money to "buy" the right to find this block, from the conventional layer1 Sha256d miners. ==Motivation== -Regular "Merged-Mining" (MM) allows miners to reuse their hashing work to secure other chains (for example, as in Namecoin). However, traditional MM has two drawbacks: - -# Miners must run a full node of the other chain. (This is because [while miners can effortlessly create the block] miners will not create a valid payment to themselves, unless the block that they MM is a valid one. Therefore, miners must assemble a *valid* block first, then MM it.) -# Miners are paid on the other chain, not on the regular BTC mainchain. For example, miners who MM Namecoin will earn NMC (and they will need to sell the NMC for BTC, before selling the BTC in order to pay for electricity). - -BMM addresses both shortcomings. - - -==Specification== - -Note: This document uses the notation side:\* and main:\* in front of otherwise-ambiguous words (such as "block", "node", or "chain"), to distinguish the mainchain version from its sidechain counterpart. We also use "Simon" to refer to a Sidechain Full Node, and "Mary" to refer to a mainchain miner. - - -=== BMM Request === - -To buy the right to find a sidechain block, users broadcast BMM Requests. - -Here, these can take two forms. The first does not require the Lightning Network, but it does have new requirements for Immediate Expiration (see below). The second inherits Immediate Expiration from the Lightning Network itself, but requires extra preparation and a different/larger message. +"Merged-Mining" (MM) allows miners to reuse their hashing work to secure other chains (for example, as in Namecoin). -Both forms require that certain Critical Data will be committed to within the coinbase of the block that the transaction is included in (see BMM Accept). For the OnChain (non-Lightning) version, we have created a new extended serialization transaction type (very similar to how SegWit handles witness data (the witness stack)). +However, traditional MM has two drawbacks: -==== Immediate Expiration ("Fill-or-Kill") ==== +# Miners must run a full node of the other chain(s). (Thus, they must run "non-Bitcoin" software which may be buggy.) +# Miners are paid on the other chain, in Alt-currency. (Miners who MM Namecoin, will earn NMC.) -We would like to make special guarantees to the counterparties of this transaction. Specifically, instead of Simon making a "payment" to Mary, we prefer that Simon give Mary an "offer" (which she can either accept or decline). -Crucially, we want Simon to safely make many offers to several different Mary's, in realtime (ie, quickly and off-chain). However, we ultimately want only one offer to be accepted, at most. In other words, we want Simon's offers to *immediately expire*. If only one offer can become a bona fide transaction, then Simon will feel comfortable making multiple offers all day long. Because all of the Simons are making many offers, the Marys collectively gain access to a large set of offers to choose from. +==Notation and Example== -==== OnChain BMM Request ==== +Note: We use notation side:\* and main:\* in front of otherwise-ambiguous words (such as "block", "node", or "chain"), to sort the mainchain version from its sidechain counterpart. We name all sidechain users "Simon", and name all mainchain miners "Mary". -OnChain BMMRs do not require the Lightning network, but they do have new requirements for validation. +Example: imagine that a sidechain block contains 20,000 txns, each paying a $0.10 fee; therefore, the block is worth $2000 of fee-revenue. As usual: the sidechain's coinbase txn will pay this $2000 to someone (in this case, "Simon"). Under Bip301, Simon does no hashing, but instead makes one layer1 txn paying $1999 to the layer1 miners ("Mary"). -===== Structure ===== -The following data is required: +{| class="wikitable" +|- +! colspan="3" | Upon finding a sidechain block worth $2000... +|- style="font-weight:bold; text-decoration:underline;" +| Item +| Layer1 Miner ("Mary") +| Sidechain User ("Simon") +|- +| Runs a sidechain node? +| No +| Yes +|- +| How much hashing? +| 100% +| 0% +|- +| Coins collected, on Layer2 +| $0 +| $2000 +|- +| Coins paid out, on Layer1 +| $0 +| $1999 +|- +| Coins rec'd, on Layer1 +| $1999 +| $0 +|- +| d(Net Worth) +| +$1999 +| +$1 +|} -<pre> - 32-bytes - h* sideHeaderHash - ?~?-bytes - critical data extended serialization - 3-bytes - 0x00bf00 identifying bytes - 1-byte - nSidechain - 2-bytes - prevSideBlockRef - 4-bytes - prevMainHeaderBytes -</pre> -sideHeaderHash comes from side:chain (side:nodes build side:blocks/headers). The identifying bytes are given here. nSidechain identifies which sidechain we are BMMing. By the time Blind Merged Mining can take place, it is known globally. +Bip301 makes this specialization-of-labor trustless on layer1. If Mary takes Simon's money, then she must let Simon control the side:block. -prevBlockRef, is a little more complicated (next section). -To qualify for inclusion in a block, BMM requests are subject to the following requirements: -# Requests must match a corresponding "BMM Accept" (see last section of BIP). -# At most, only one Request is allowed in a main:block, per sidechain. In other words, if 700 users broadcast BMM Requests for sidechain #4, then the main:miner must choose one single Request to include. -# The 4-bytes of prevMainHeaderBytes must match the last four bytes of the previous main:blockheader. Thus, Simon's txns are only be valid for the current block, in the block history that he knows about (and therefore, the current sidechain history that he knows about). - -===== prevBlockRef ===== - -prevBlockRef is an integer that counts the number of "skips" one must take in the side:chain in order to find the current side:block's parent block. This value is zero unless the sidechain is reorganizing (or skipping over invalid sidechain blocks). If a side:node wants to orphan the most-recent N blocks, the value of the current block will be equal to N; in the block after that it will be back to zero. - -<img src="bip-0301/bmm-dots-examples.png?raw=true" align="middle"></img> +==Specification== -Above: Three blockchains, with different max length (small number), reorganization histories, and prevBlockRef numbers (larger numbers beneath blocks). The ordering given via each side:block's "prevSideBlockRef" will be isomorphic to an ordering given by each side:block's "prevSideHeaderHash" ("prevSideHeaderHash is the sidechain's equivalent of the mainchain's "prevBlockHash"). One can freely convert from one to the other. -===== Extended Serialization ===== +Bip300 consists of two messages: "BMM Accept" and "BMM Request". These govern something called "h*". -To impose new requirements at the transaction level, we borrow the dummy vin & "flag" trick from SegWit style transactions. Unless all of the requirements for sidechain critical data transactions are met by the block it is included in, the transaction is invalid. With SegWit, this extra data is the SegWit signature stack, and the extra requirements are the signatures' locations and validity. In the sidechain BMM critical data transactions, the extra data is the (nSidechain, h\*) pair, which must meet the first two requirements (above) as well as the main:blocknumber, which must meet the third requirement (above). +So we will discuss: -<img src="bip-0301/witness-vs-critical.png?raw=true" align="middle"></img> +# h* -- The sidechain's hashMerkleRoot, and why it matters. +# "BMM Accept" -- How h* enters a main:coinbase. When Mary "accepts" a BMM Request, Mary is ''endorsing a side:block''. +# "BMM Request" -- Simon offering money to Mary, if (and only if) she will Endorse a specific h*. When Simon broadcasts a BMM Request, Simon is ''attempting a side:block''. -Above: A chart showing normal txns, SegWit txns, and CriticalData txns. The specific SegWit txn can be seen [http://srv1.yogh.io/#tx:id:D4A99AE93DF6EE3D4E42CE69338DFC1D06CCD9B198666E98FF0588057378D3D9 here]. -These types of transactions have slightly different mempool behavior, and should probably be kept in a second mempool. These txns are received, checked immediately, and if valid they are evaluated for inclusion in a block. If they are not able to be included in the specific requested block (if the block height requested has been surpassed by the chain tip), they are discarded. In fact, after any main:block is found, everything in this "second mempool" can be discarded as new payments will be created immediately for the next block height. (This includes cases where the blockchain reorganizes.) There is no re-evaluation of the txns in this mempool ever -- they are evaluated once and then either included or discarded. They never need to be rescanned. +=== h* === -Interestingly, these payments will *always* be directed to main:miners from non-main:miners. Therefore, non-mining full nodes do not need to keep them in any mempool at all. Non-miner nodes can just wait for a block to be found, and check the txn then. These transactions more resemble a stock market's pit trade-offers (in contrast, regular Bitcoin txns are more like paper checks). +h* ("h star") is the sidechain's Merkle Root hash. -==== Lightning BMM Request ==== +In Bip301, a sidechain's coinbase txn acts as a header (it contains the hash of the previous side:block, and previous main:block). Thus, the MerkleRoot contains everything important. -Lightning BMMRs require Simons to have a LN-channel pathways open with Marys. This may not always be practical (or even possible), especially today. +Note: in Bip301 sidechains, "headers" and "block hashes" do not have significant consensus meaning and are in the design mainly to help with IBD. (In the mainchain, in contrast, headers and block hashes determine the difficulty adjustments and cumulative PoW.) -LN txns cannot make use of prevSideBlockRef, as no one knows for sure when (or if) they will be broadcast on-chain. Instead, they must use prevSideBlockHash. But they otherwise require the same data: +<img src="bip-0301/sidechain-headers.png?raw=true" align="middle"></img> -<pre> - 4-bytes - Message header (0xD0520C6E) - 1-byte - sidechain number - 32-bytes - h* side:block hash - 32-bytes - prevSideBlockHash -</pre> -Notice that, in OnChain BMMRs, Simon could reuse the same h\* all he wanted, because only one OnChain BMMR could be included per main:block per sidechain. However, on the LN no such rule can be enforced, as the goal is to push everything off-chain and include *zero* txns. So, we will never know what the Requests were, or how many had an effect on anything. +Above: h* is located in the main:coinbase. h* contains all side:txns, including the side:coinbase. The side:coinbase contains many "header-like" fields, such as the hash of the previous side:block. -Therefore, Simon will need to ensure that he '''gives each Mary a different h\*'''. Simon can easily do this, as he controls the side:block's contents and can simply increment a side:nonce -- this changes the side:block, and changes its hash (ie, changes h\*). +Mary controls the main:coinbase, so she may select any h*. Her selection will determine which side:block is "found". -With a unique h\* per Mary (or, more precisely, per channel), and at most 1 h\* making it into a block (per sidechain), Simon can ensure that he is charged, at most, one time. -That's probably confusing, so here is an example, in which: Simon starts with 13 BTC, Mary starts with 40 BTC, the side:block's tx-fees currently total 7.1 BTC, and Simon is keeping 0.1 BTC for himself and paying 7 BTC to Mary. +=== BMM Accept === -We start with (I): +To "Accept" the BMM proposal (and to accept Simon's money), Mary must endorse Simon's block. <pre> - Simon 13 in, Mary 40 in ; 53 in total - Simon's version [signed by Mary] - 13 ; to Simon if TimeLock=over; OR to Mary if SimonSig - 40 ; to Mary - Mary's version [signed by Simon] - 40 ; to me if TimeLock=over; OR to Simon if MarySig - 13 ; to Simon +For each side:block Mary wishes to endorse, Mary places the following into a main:coinbase OP_RETURN: + 1-byte - OP_RETURN (0x6a) + 4-bytes - Message header (0xD1617368) + 32-bytes - h* (obtained from Simon) </pre> +[https://github.com/drivechain-project/mainchain/blob/8901d469975752d799b6a7a61d4e00a9a124028f/src/validation.cpp#L3530-L3572 Code details here]. -And both parties move, from there to (II): +If these OP_RETURN outputs are not present, then no Requests were accepted. (And, Mary would get no money from Requests.) -<pre> - Simon 13 in, Mary 40 in ; 53 in total - Simon's version [signed by Mary] - 6 ; to Simon if TimeLock=over; OR to Mary if SimonSig - 40 ; to Mary - 7 ; to Mary if critical data requirements met; OR to Simon if LongTimeLock=over - Mary's version [signed by Simon] - 40 ; to Mary if TimeLock=over; OR to Simon if MarySig - 6 ; to Simon - 7 ; to Mary if critical data requirements met; OR to Simon if LongTimeLock=over -</pre> +It is possible for Mary and Simon to be the same person.They would trust each other completely, so the BMM process would stop here. There would only be Accepts; Requests would be unnecessary. +When Simon and Mary are different people, Simon will need to use BMM Requests. -From here, if the h\* side:block in question is BMMed, they can proceed to (III): +=== BMM Request === + +Simon will use BMM Requests to buy the right to find a sidechain block, from Mary. <pre> - Simon 13 in, Mary 40 in ; 53 in total - Simon's version [signed by Mary] - 6 ; to Simon if TimeLock=over; OR to Mary if SimonSig - 47 ; to Mary - Mary's version [signed by Simon] - 47 ; to me if TimeLock=over; OR to Simon if MarySig - 6 ; to Simon +For each side:block that Simon wants to attempt, he broadcasts a txn containing the following: + 3-bytes - Message header (0x00bf00) + 32-bytes - h* (side:MerkleRoot) + 1-byte - nSidechain (sidechain ID number) + 4-bytes - prevMainHeaderBytes (the last four bytes of the previous main:block) </pre> -If Simon proceeds immediately, he removes Mary's incentive to care about blocks being built on this side:block. If Simon's side:block is orphaned, he loses his 7 BTC. Simon can either play it safe, and wait for (for example) 100 side:blocks before moving on (ie, before moving on to the third LN txn, above); or else Simon can take the risk if he feels comfortable with it. +We make use of the [https://github.com/drivechain-project/mainchain/blob/8901d469975752d799b6a7a61d4e00a9a124028f/src/primitives/transaction.h#L224-L331 extended serialization format]. (SegWit used ESF to position scriptWitness data within txns; we use it here to position the five fields above.) -If the h\* side:block is not found, then (II) and (III) are basically equivalent to each other. Simon and Mary could jointly reconstruct (I) and go back there, or they could proceed to a new version of II (with a different h\*, trying again with new side:block in the next main:block). -Now that we have described Requests, we can describe how they are accepted. +The Message header identifies this txn as a BMM transaction. h* is chosen by Simon to correspond to his side:block. nSidechain is the number assigned to the sidechain when it was created. preSideBlockRef allows Simon to build on any preexisting side:block (allowing him to bypass one or more invalid blocks, details below). prevMainHeaderBytes are the last four bytes of the previous main:block (details below). -=== BMM Accept === +This txn is invalid if it fails any of the following checks: -For each BMM Request that a main:miner "accepts", main:miners must place an OP Return output into their main:coinbase txn. (We've changed the tx-standardness policy to allow multiple OP_RETURNs.) - -The following data is required in the "accept" OP_RETURN output: - 1-byte - OP_RETURN (0x6a) - 1-byte - Push the following 36 bytes (0x24) - 4-bytes - Message header (0xD3407053) - 32-bytes - h* - ~5-bytes - BMM identifier bytes +# Each "BMM Request", must match one corresponding "BMM Accept" (previous section). +# Only one BMM Request is allowed in each main:block, per sidechain. In other words, if 700 users broadcast BMM Requests for sidechain #4, then the main:miner singles out one BMM Request to include. +# The 4-bytes of prevMainHeaderBytes must match the last four bytes of the previous main:blockheader. Thus, Simon's txns are only valid for the current block, in the block history that he knows about (and therefore, the current sidechain history that he knows about). -[https://github.com/DriveNetTESTDRIVE/DriveNet/blob/564516653c1d876429382971a011f5f6119f7eb4/src/validation.cpp#L3377-L3470 Link to code]. - -If these OP_RETURN outputs are not present, then no BMM Requests have been accepted. (And, if they are not accepted, then they cannot be included in a main:block.) +Most BMM Request txns will never make it into a block. Simon will make many BMM Requests, but only one will be accepted. Since only one BMM Request can become a bona fide transaction, Simon may feel comfortable making multiple offers all day long. This means Mary has many offers to choose from, and can choose the one which pays her the most. +This BIP allows BMM Requests to take place over Lightning. One method is [https://www.drivechain.info/media/bmm-note/bmm-lightning/ here]. (BMM Accepts cannot be over LN, since they reside in main:coinbase txns.) ==Backward compatibility== -As a soft fork, older software will continue to operate without modification. As stated above, BMM asks nodes to track a set of ordered hashes, and to allow miners to "sell" the act of finding a sidechain block. Non-upgraded nodes will notice that this activity (specifically: data in coinbases, and new txns that have OP Returns and interesting message headers) is now taking place, but they will not understand any of it. Much like P2SH or a new OP Code, these old users will not be directly affected by the fork, as they will have no expectations of receiving payments of this kind. +As a soft fork, older software will continue to operate without modification. To enforce BMM trustlessly, nodes must watch "pairs" of transactions, and subject them to extra rules. Non-upgraded nodes will notice that this activity is present in the blockchain, but they will not understand any of it. + +Much like P2SH or a new OP Code, these old users can never be directly affected by the fork, as they will have no expectations of receiving payments of this kind. (As a matter of fact, the only people receiving BTC here, all happen to be miners. So there is less reason than ever to expect compatibility problems.) -(As a matter of fact, the only people receiving money here all happen to be miners. So there is less reason than ever to expect compatibility problems.) +As with all previous soft forks, non-upgraded users are indirectly affected, in that they are no longer performing full validation. ==Deployment== @@ -196,8 +166,8 @@ This BIP will be deployed by "version bits" BIP9 with the name "blindmm" and usi <pre> // Deployment of Drivechains (BIPX, BIPY) consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].bit = 4; -consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nStartTime = 1579072881; // January 15th, 2020. -consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nTimeout = 1610695281; // January 15th, 2021. +consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nStartTime = 1642276800; // January 15th, 2022. +consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nTimeout = 1673812800; // January 15th, 2023. </pre> @@ -224,3 +194,4 @@ Thanks to everyone who contributed to the discussion, especially: ZmnSCPxj, Adam ==Copyright== This BIP is licensed under the BSD 2-clause license. + diff --git a/bip-0301/bmm-dots-examples.png b/bip-0301/bmm-dots-examples.png Binary files differdeleted file mode 100644 index 70f11f6..0000000 --- a/bip-0301/bmm-dots-examples.png +++ /dev/null diff --git a/bip-0301/m1-gui.jpg b/bip-0301/m1-gui.jpg Binary files differnew file mode 100644 index 0000000..8f3aab1 --- /dev/null +++ b/bip-0301/m1-gui.jpg diff --git a/bip-0301/sidechain-headers.png b/bip-0301/sidechain-headers.png Binary files differnew file mode 100644 index 0000000..de9697c --- /dev/null +++ b/bip-0301/sidechain-headers.png diff --git a/bip-0322.mediawiki b/bip-0322.mediawiki index 5f4704d..9b5afed 100644 --- a/bip-0322.mediawiki +++ b/bip-0322.mediawiki @@ -74,7 +74,7 @@ The <code>to_sign</code> transaction is: vout[0].nValue = 0 vout[0].scriptPubKey = OP_RETURN -A full signature consists of the base64-encoding of the <code>to_sign</code> transaction in standard network serialisation. +A full signature consists of the base64-encoding of the <code>to_sign</code> transaction in standard network serialisation once it has been signed. === Full (Proof of Funds) === @@ -120,7 +120,7 @@ Validation consists of the following steps: # Check the **upgradeable rules** ## The version of <code>to_sign</code> must be 0 or 2. ## The use of NOPs reserved for upgrades is forbidden. -## The use of segwit versions greater than 0 are forbidden. +## The use of segwit versions greater than 1 are forbidden. ## If any of the above steps failed, the validator should stop and output the ''inconclusive'' state. # Let ''T'' by the nLockTime of <code>to_sign</code> and ''S'' be the nSequence of the first input of <code>to_sign</code>. Output the state ''valid at time T and age S''. diff --git a/bip-0341.mediawiki b/bip-0341.mediawiki index 586bb39..693233a 100644 --- a/bip-0341.mediawiki +++ b/bip-0341.mediawiki @@ -88,13 +88,13 @@ We first define a reusable common signature message calculation function, follow ==== Common signature message ==== -The function ''SigMsg(hash_type, ext_flag)'' computes the message being signed as a byte array. It is implicitly also a function of the spending transaction and the outputs it spends, but these are not listed to keep notation simple. +The function ''SigMsg(hash_type, ext_flag)'' computes the common portion of the message being signed as a byte array. It is implicitly also a function of the spending transaction and the outputs it spends, but these are not listed to keep notation simple. -The parameter ''hash_type'' is an 8-bit unsigned value. The <code>SIGHASH</code> encodings from the legacy script system are reused, including <code>SIGHASH_ALL</code>, <code>SIGHASH_NONE</code>, <code>SIGHASH_SINGLE</code>, and <code>SIGHASH_ANYONECANPAY</code>, plus the default ''hash_type'' value ''0x00'' which results in signing over the whole transaction just as for <code>SIGHASH_ALL</code>. The following restrictions apply, which cause validation failure if violated: +The parameter ''hash_type'' is an 8-bit unsigned value. The <code>SIGHASH</code> encodings from the legacy script system are reused, including <code>SIGHASH_ALL</code>, <code>SIGHASH_NONE</code>, <code>SIGHASH_SINGLE</code>, and <code>SIGHASH_ANYONECANPAY</code>. We define a new ''hashtype'' <code>SIGHASH_DEFAULT</code> (value ''0x00'') which results in signing over the whole transaction just as for <code>SIGHASH_ALL</code>. The following restrictions apply, which cause validation failure if violated: * Using any undefined ''hash_type'' (not ''0x00'', ''0x01'', ''0x02'', ''0x03'', ''0x81'', ''0x82'', or ''0x83''<ref>'''Why reject unknown ''hash_type'' values?''' By doing so, it is easier to reason about the worst case amount of signature hashing an implementation with adequate caching must perform.</ref>). * Using <code>SIGHASH_SINGLE</code> without a "corresponding output" (an output with the same index as the input being verified). -The parameter ''ext_flag'' is an integer in range 0-127, and is used for indicating (in the message) that extensions are added at the end of the message<ref>'''What extensions use the ''ext_flag'' mechanism?''' [[bip-0342.mediawiki|BIP342]] reuses the same common signature message algorithm, but adds BIP342-specific data at the end, which is indicated using ''ext_flag = 1''.</ref>. +The parameter ''ext_flag'' is an integer in range 0-127, and is used for indicating (in the message) that extensions are appended to the output of ''SigMsg()''<ref>'''What extensions use the ''ext_flag'' mechanism?''' [[bip-0342.mediawiki#common-signature-message-extension|BIP342]] reuses the same common signature message algorithm, but adds BIP342-specific data at the end, which is indicated using ''ext_flag = 1''.</ref>. If the parameters take acceptable values, the message is the concatenation of the following data, in order (with byte size of each item listed in parentheses). Numerical values in 2, 4, or 8-byte are encoded in little-endian. @@ -106,7 +106,7 @@ If the parameters take acceptable values, the message is the concatenation of th ** If the ''hash_type & 0x80'' does not equal <code>SIGHASH_ANYONECANPAY</code>: *** ''sha_prevouts'' (32): the SHA256 of the serialization of all input outpoints. *** ''sha_amounts'' (32): the SHA256 of the serialization of all spent output amounts. -*** ''sha_scriptpubkeys'' (32): the SHA256 of the serialization of all spent output ''scriptPubKey''s. +*** ''sha_scriptpubkeys'' (32): the SHA256 of all spent outputs' ''scriptPubKeys'', serialized as script inside <code>CTxOut</code>. *** ''sha_sequences'' (32): the SHA256 of the serialization of all input ''nSequence''. ** If ''hash_type & 3'' does not equal <code>SIGHASH_NONE</code> or <code>SIGHASH_SINGLE</code>: *** ''sha_outputs'' (32): the SHA256 of the serialization of all outputs in <code>CTxOut</code> format. @@ -167,20 +167,22 @@ Alice will not be able to notice the script path, but Mallory can unilaterally s </ref> * The remaining scripts should be organized into the leaves of a binary tree. This can be a balanced tree if each of the conditions these scripts correspond to are equally likely. If probabilities for each condition are known, consider constructing the tree as a Huffman tree. -'''Computing the output script''' Once the spending conditions are split into an internal key <code>internal_pubkey</code> and a binary tree whose leaves are (leaf_version, script) tuples, the output script can be computed using the Python3 algorithms below. These algorithms take advantage of helper functions from the [bip-0340/referency.py BIP340 reference code] for integer conversion, point multiplication, and tagged hashes. +'''Computing the output script''' Once the spending conditions are split into an internal key <code>internal_pubkey</code> and a binary tree whose leaves are (leaf_version, script) tuples, the output script can be computed using the Python3 algorithms below. These algorithms take advantage of helper functions from the [[bip-0340/reference.py|BIP340 reference code]] for integer conversion, point multiplication, and tagged hashes. First, we define <code>taproot_tweak_pubkey</code> for 32-byte [[bip-0340.mediawiki|BIP340]] public key arrays. The function returns a bit indicating the tweaked public key's Y coordinate as well as the public key byte array. The parity bit will be required for spending the output with a script path. In order to allow spending with the key path, we define <code>taproot_tweak_seckey</code> to compute the secret key for a tweaked public key. -For any byte string <code>h</code> it holds that <code>taproot_tweak_pubkey(pubkey_gen(seckey), h)[0] == pubkey_gen(taproot_tweak_seckey(seckey, h))</code>. +For any byte string <code>h</code> it holds that <code>taproot_tweak_pubkey(pubkey_gen(seckey), h)[1] == pubkey_gen(taproot_tweak_seckey(seckey, h))</code>. + +Note that because tweaks are applied to 32-byte public keys, `taproot_tweak_seckey` may need to negate the secret key before applying the tweak. <source lang="python"> def taproot_tweak_pubkey(pubkey, h): t = int_from_bytes(tagged_hash("TapTweak", pubkey + h)) if t >= SECP256K1_ORDER: raise ValueError - Q = point_add(lift_x(int_from_bytes(pubkey)), point_mul(G, t)) + Q = point_add(lift_x(pubkey), point_mul(G, t)) return 0 if has_even_y(Q) else 1, bytes_from_int(x(Q)) def taproot_tweak_seckey(seckey0, h): @@ -219,7 +221,7 @@ def taproot_output_script(internal_pubkey, script_tree): h = bytes() else: _, h = taproot_tree_helper(script_tree) - output_pubkey, _ = taproot_tweak_pubkey(internal_pubkey, h) + _, output_pubkey = taproot_tweak_pubkey(internal_pubkey, h) return bytes([0x51, 0x20]) + output_pubkey </source> @@ -284,7 +286,13 @@ The reason for this is to increase leaf entropy and prevent an observer from lea == Test vectors == -The test vectors used in the [https://github.com/bitcoin/bitcoin/blob/3820090bd619ac85ab35eff376c03136fe4a9f04/src/test/script_tests.cpp#L1718 Bitcoin Core unit test framework] can be found [https://github.com/bitcoin-core/qa-assets/blob/main/unit_test_data/script_assets_test.json?raw=true here]. +Test vectors for wallet operation (scriptPubKey computation, key path spending, control block construction) can be found [[bip-0341/wallet-test-vectors.json|here]]. +It consists of two sets of vectors. +* The first "scriptPubKey" tests concern computing the scriptPubKey and (mainnet) BIP350 address given an internal public key, and a script tree. The script tree is encoded as <code>null</code> to represent no scripts, a JSON object to represent a leaf node, or a 2-element array to represent an inner node. The control blocks needed for script path spending are also provided for each of the script leaves. +* The second "keyPathSpending" tests consists of a list of test cases, each of which provides an unsigned transaction and the UTXOs it spends. For each of its BIP341 inputs, the internal private key and the Merkle root it was derived from is given, as well as the expected witness to spend it. All signatures are created with an all-zero (0x0000...0000) BIP340 auxiliary randomness array. +* In all cases, hexadecimal values represent byte arrays, not numbers. In particular, that means that provided hash values have the hex digits corresponding to the first bytes first. This differs from the convention used for txids and block hashes, where the hex strings represent numbers, resulting in a reversed order. + +Validation test vectors used in the [https://github.com/bitcoin/bitcoin/blob/3820090bd619ac85ab35eff376c03136fe4a9f04/src/test/script_tests.cpp#L1718 Bitcoin Core unit test framework] can be found [https://github.com/bitcoin-core/qa-assets/blob/main/unit_test_data/script_assets_test.json?raw=true here]. == Rationale == @@ -296,7 +304,7 @@ This BIP is deployed concurrently with [[bip-0342.mediawiki|BIP342]]. For Bitcoin signet, these BIPs are always active. -For Bitcoin mainnet and testnet3, these BIPs will be deployed by "version bits" with the name "taproot" and bit 2, using [[bip-0009.mediawiki|BIP9]] modified to use a lower threshold, with an additional ''min_activation_height'' parameter and replacing the state transition logic for the DEFINED, STARTED and LOCKED_IN states as follows: +For Bitcoin mainnet and testnet3, these BIPs are deployed by "version bits" with the name "taproot" and bit 2, using [[bip-0009.mediawiki|BIP9]] modified to use a lower threshold, with an additional ''min_activation_height'' parameter and replacing the state transition logic for the DEFINED, STARTED and LOCKED_IN states as follows: case DEFINED: if (GetMedianTimePast(block.parent) >= starttime) { @@ -326,9 +334,11 @@ For Bitcoin mainnet and testnet3, these BIPs will be deployed by "version bits" } return ACTIVE; -For Bitcoin mainnet, the starttime is epoch timestamp 1619222400 (midnight 24 April 2021 UTC), timeout is epoch timestamp 1628640000 (midnight 11 August 2021 UTC), the threshold is 1815 blocks (90%) instead of 1916 blocks (95%), and the min_activation_height is block 709632 (expected approximately 12 November 2021). +For Bitcoin mainnet, the starttime is epoch timestamp 1619222400 (midnight 24 April 2021 UTC), timeout is epoch timestamp 1628640000 (midnight 11 August 2021 UTC), the threshold is 1815 blocks (90%) instead of 1916 blocks (95%), and the min_activation_height is block 709632. +The deployment did activate at height 709632 on Bitcoin mainnet. For Bitcoin testnet3, the starttime is epoch timestamp 1619222400 (midnight 24 April 2021 UTC), timeout is epoch timestamp 1628640000 (midnight 11 August 2021 UTC), the threshold is 1512 blocks (75%), and the min_activation_height is block 0. +The deployment did activate at height 2011968 on Bitcoin testnet3. == Backwards compatibility == As a soft fork, older software will continue to operate without modification. @@ -336,7 +346,7 @@ Non-upgraded nodes, however, will consider all SegWit version 1 witness programs They are strongly encouraged to upgrade in order to fully validate the new programs. Non-upgraded wallets can receive and send bitcoin from non-upgraded and upgraded wallets using SegWit version 0 programs, traditional pay-to-pubkey-hash, etc. -Depending on the implementation non-upgraded wallets may be able to send to Segwit version 1 programs if they support sending to [[bip-0173.mediawiki|BIP173]] Bech32 addresses. +Depending on the implementation non-upgraded wallets may be able to send to Segwit version 1 programs if they support sending to [[bip-0350.mediawiki|BIP350]] Bech32m addresses. == Acknowledgements == diff --git a/bip-0341/wallet-test-vectors.json b/bip-0341/wallet-test-vectors.json new file mode 100644 index 0000000..11261b0 --- /dev/null +++ b/bip-0341/wallet-test-vectors.json @@ -0,0 +1,452 @@ +{ + "version": 1, + "scriptPubKey": [ + { + "given": { + "internalPubkey": "d6889cb081036e0faefa3a35157ad71086b123b2b144b649798b494c300a961d", + "scriptTree": null + }, + "intermediary": { + "merkleRoot": null, + "tweak": "b86e7be8f39bab32a6f2c0443abbc210f0edac0e2c53d501b36b64437d9c6c70", + "tweakedPubkey": "53a1f6e454df1aa2776a2814a721372d6258050de330b3c6d10ee8f4e0dda343" + }, + "expected": { + "scriptPubKey": "512053a1f6e454df1aa2776a2814a721372d6258050de330b3c6d10ee8f4e0dda343", + "bip350Address": "bc1p2wsldez5mud2yam29q22wgfh9439spgduvct83k3pm50fcxa5dps59h4z5" + } + }, + { + "given": { + "internalPubkey": "187791b6f712a8ea41c8ecdd0ee77fab3e85263b37e1ec18a3651926b3a6cf27", + "scriptTree": { + "id": 0, + "script": "20d85a959b0290bf19bb89ed43c916be835475d013da4b362117393e25a48229b8ac", + "leafVersion": 192 + } + }, + "intermediary": { + "leafHashes": [ + "5b75adecf53548f3ec6ad7d78383bf84cc57b55a3127c72b9a2481752dd88b21" + ], + "merkleRoot": "5b75adecf53548f3ec6ad7d78383bf84cc57b55a3127c72b9a2481752dd88b21", + "tweak": "cbd8679ba636c1110ea247542cfbd964131a6be84f873f7f3b62a777528ed001", + "tweakedPubkey": "147c9c57132f6e7ecddba9800bb0c4449251c92a1e60371ee77557b6620f3ea3" + }, + "expected": { + "scriptPubKey": "5120147c9c57132f6e7ecddba9800bb0c4449251c92a1e60371ee77557b6620f3ea3", + "bip350Address": "bc1pz37fc4cn9ah8anwm4xqqhvxygjf9rjf2resrw8h8w4tmvcs0863sa2e586", + "scriptPathControlBlocks": [ + "c1187791b6f712a8ea41c8ecdd0ee77fab3e85263b37e1ec18a3651926b3a6cf27" + ] + } + }, + { + "given": { + "internalPubkey": "93478e9488f956df2396be2ce6c5cced75f900dfa18e7dabd2428aae78451820", + "scriptTree": { + "id": 0, + "script": "20b617298552a72ade070667e86ca63b8f5789a9fe8731ef91202a91c9f3459007ac", + "leafVersion": 192 + } + }, + "intermediary": { + "leafHashes": [ + "c525714a7f49c28aedbbba78c005931a81c234b2f6c99a73e4d06082adc8bf2b" + ], + "merkleRoot": "c525714a7f49c28aedbbba78c005931a81c234b2f6c99a73e4d06082adc8bf2b", + "tweak": "6af9e28dbf9d6aaf027696e2598a5b3d056f5fd2355a7fd5a37a0e5008132d30", + "tweakedPubkey": "e4d810fd50586274face62b8a807eb9719cef49c04177cc6b76a9a4251d5450e" + }, + "expected": { + "scriptPubKey": "5120e4d810fd50586274face62b8a807eb9719cef49c04177cc6b76a9a4251d5450e", + "bip350Address": "bc1punvppl2stp38f7kwv2u2spltjuvuaayuqsthe34hd2dyy5w4g58qqfuag5", + "scriptPathControlBlocks": [ + "c093478e9488f956df2396be2ce6c5cced75f900dfa18e7dabd2428aae78451820" + ] + } + }, + { + "given": { + "internalPubkey": "ee4fe085983462a184015d1f782d6a5f8b9c2b60130aff050ce221ecf3786592", + "scriptTree": [ + { + "id": 0, + "script": "20387671353e273264c495656e27e39ba899ea8fee3bb69fb2a680e22093447d48ac", + "leafVersion": 192 + }, + { + "id": 1, + "script": "06424950333431", + "leafVersion": 250 + } + ] + }, + "intermediary": { + "leafHashes": [ + "8ad69ec7cf41c2a4001fd1f738bf1e505ce2277acdcaa63fe4765192497f47a7", + "f224a923cd0021ab202ab139cc56802ddb92dcfc172b9212261a539df79a112a" + ], + "merkleRoot": "6c2dc106ab816b73f9d07e3cd1ef2c8c1256f519748e0813e4edd2405d277bef", + "tweak": "9e0517edc8259bb3359255400b23ca9507f2a91cd1e4250ba068b4eafceba4a9", + "tweakedPubkey": "712447206d7a5238acc7ff53fbe94a3b64539ad291c7cdbc490b7577e4b17df5" + }, + "expected": { + "scriptPubKey": "5120712447206d7a5238acc7ff53fbe94a3b64539ad291c7cdbc490b7577e4b17df5", + "bip350Address": "bc1pwyjywgrd0ffr3tx8laflh6228dj98xkjj8rum0zfpd6h0e930h6saqxrrm", + "scriptPathControlBlocks": [ + "c0ee4fe085983462a184015d1f782d6a5f8b9c2b60130aff050ce221ecf3786592f224a923cd0021ab202ab139cc56802ddb92dcfc172b9212261a539df79a112a", + "faee4fe085983462a184015d1f782d6a5f8b9c2b60130aff050ce221ecf37865928ad69ec7cf41c2a4001fd1f738bf1e505ce2277acdcaa63fe4765192497f47a7" + ] + } + }, + { + "given": { + "internalPubkey": "f9f400803e683727b14f463836e1e78e1c64417638aa066919291a225f0e8dd8", + "scriptTree": [ + { + "id": 0, + "script": "2044b178d64c32c4a05cc4f4d1407268f764c940d20ce97abfd44db5c3592b72fdac", + "leafVersion": 192 + }, + { + "id": 1, + "script": "07546170726f6f74", + "leafVersion": 192 + } + ] + }, + "intermediary": { + "leafHashes": [ + "64512fecdb5afa04f98839b50e6f0cb7b1e539bf6f205f67934083cdcc3c8d89", + "2cb2b90daa543b544161530c925f285b06196940d6085ca9474d41dc3822c5cb" + ], + "merkleRoot": "ab179431c28d3b68fb798957faf5497d69c883c6fb1e1cd9f81483d87bac90cc", + "tweak": "639f0281b7ac49e742cd25b7f188657626da1ad169209078e2761cefd91fd65e", + "tweakedPubkey": "77e30a5522dd9f894c3f8b8bd4c4b2cf82ca7da8a3ea6a239655c39c050ab220" + }, + "expected": { + "scriptPubKey": "512077e30a5522dd9f894c3f8b8bd4c4b2cf82ca7da8a3ea6a239655c39c050ab220", + "bip350Address": "bc1pwl3s54fzmk0cjnpl3w9af39je7pv5ldg504x5guk2hpecpg2kgsqaqstjq", + "scriptPathControlBlocks": [ + "c1f9f400803e683727b14f463836e1e78e1c64417638aa066919291a225f0e8dd82cb2b90daa543b544161530c925f285b06196940d6085ca9474d41dc3822c5cb", + "c1f9f400803e683727b14f463836e1e78e1c64417638aa066919291a225f0e8dd864512fecdb5afa04f98839b50e6f0cb7b1e539bf6f205f67934083cdcc3c8d89" + ] + } + }, + { + "given": { + "internalPubkey": "e0dfe2300b0dd746a3f8674dfd4525623639042569d829c7f0eed9602d263e6f", + "scriptTree": [ + { + "id": 0, + "script": "2072ea6adcf1d371dea8fba1035a09f3d24ed5a059799bae114084130ee5898e69ac", + "leafVersion": 192 + }, + [ + { + "id": 1, + "script": "202352d137f2f3ab38d1eaa976758873377fa5ebb817372c71e2c542313d4abda8ac", + "leafVersion": 192 + }, + { + "id": 2, + "script": "207337c0dd4253cb86f2c43a2351aadd82cccb12a172cd120452b9bb8324f2186aac", + "leafVersion": 192 + } + ] + ] + }, + "intermediary": { + "leafHashes": [ + "2645a02e0aac1fe69d69755733a9b7621b694bb5b5cde2bbfc94066ed62b9817", + "ba982a91d4fc552163cb1c0da03676102d5b7a014304c01f0c77b2b8e888de1c", + "9e31407bffa15fefbf5090b149d53959ecdf3f62b1246780238c24501d5ceaf6" + ], + "merkleRoot": "ccbd66c6f7e8fdab47b3a486f59d28262be857f30d4773f2d5ea47f7761ce0e2", + "tweak": "b57bfa183d28eeb6ad688ddaabb265b4a41fbf68e5fed2c72c74de70d5a786f4", + "tweakedPubkey": "91b64d5324723a985170e4dc5a0f84c041804f2cd12660fa5dec09fc21783605" + }, + "expected": { + "scriptPubKey": "512091b64d5324723a985170e4dc5a0f84c041804f2cd12660fa5dec09fc21783605", + "bip350Address": "bc1pjxmy65eywgafs5tsunw95ruycpqcqnev6ynxp7jaasylcgtcxczs6n332e", + "scriptPathControlBlocks": [ + "c0e0dfe2300b0dd746a3f8674dfd4525623639042569d829c7f0eed9602d263e6fffe578e9ea769027e4f5a3de40732f75a88a6353a09d767ddeb66accef85e553", + "c0e0dfe2300b0dd746a3f8674dfd4525623639042569d829c7f0eed9602d263e6f9e31407bffa15fefbf5090b149d53959ecdf3f62b1246780238c24501d5ceaf62645a02e0aac1fe69d69755733a9b7621b694bb5b5cde2bbfc94066ed62b9817", + "c0e0dfe2300b0dd746a3f8674dfd4525623639042569d829c7f0eed9602d263e6fba982a91d4fc552163cb1c0da03676102d5b7a014304c01f0c77b2b8e888de1c2645a02e0aac1fe69d69755733a9b7621b694bb5b5cde2bbfc94066ed62b9817" + ] + } + }, + { + "given": { + "internalPubkey": "55adf4e8967fbd2e29f20ac896e60c3b0f1d5b0efa9d34941b5958c7b0a0312d", + "scriptTree": [ + { + "id": 0, + "script": "2071981521ad9fc9036687364118fb6ccd2035b96a423c59c5430e98310a11abe2ac", + "leafVersion": 192 + }, + [ + { + "id": 1, + "script": "20d5094d2dbe9b76e2c245a2b89b6006888952e2faa6a149ae318d69e520617748ac", + "leafVersion": 192 + }, + { + "id": 2, + "script": "20c440b462ad48c7a77f94cd4532d8f2119dcebbd7c9764557e62726419b08ad4cac", + "leafVersion": 192 + } + ] + ] + }, + "intermediary": { + "leafHashes": [ + "f154e8e8e17c31d3462d7132589ed29353c6fafdb884c5a6e04ea938834f0d9d", + "737ed1fe30bc42b8022d717b44f0d93516617af64a64753b7a06bf16b26cd711", + "d7485025fceb78b9ed667db36ed8b8dc7b1f0b307ac167fa516fe4352b9f4ef7" + ], + "merkleRoot": "2f6b2c5397b6d68ca18e09a3f05161668ffe93a988582d55c6f07bd5b3329def", + "tweak": "6579138e7976dc13b6a92f7bfd5a2fc7684f5ea42419d43368301470f3b74ed9", + "tweakedPubkey": "75169f4001aa68f15bbed28b218df1d0a62cbbcf1188c6665110c293c907b831" + }, + "expected": { + "scriptPubKey": "512075169f4001aa68f15bbed28b218df1d0a62cbbcf1188c6665110c293c907b831", + "bip350Address": "bc1pw5tf7sqp4f50zka7629jrr036znzew70zxyvvej3zrpf8jg8hqcssyuewe", + "scriptPathControlBlocks": [ + "c155adf4e8967fbd2e29f20ac896e60c3b0f1d5b0efa9d34941b5958c7b0a0312d3cd369a528b326bc9d2133cbd2ac21451acb31681a410434672c8e34fe757e91", + "c155adf4e8967fbd2e29f20ac896e60c3b0f1d5b0efa9d34941b5958c7b0a0312dd7485025fceb78b9ed667db36ed8b8dc7b1f0b307ac167fa516fe4352b9f4ef7f154e8e8e17c31d3462d7132589ed29353c6fafdb884c5a6e04ea938834f0d9d", + "c155adf4e8967fbd2e29f20ac896e60c3b0f1d5b0efa9d34941b5958c7b0a0312d737ed1fe30bc42b8022d717b44f0d93516617af64a64753b7a06bf16b26cd711f154e8e8e17c31d3462d7132589ed29353c6fafdb884c5a6e04ea938834f0d9d" + ] + } + } + ], + "keyPathSpending": [ + { + "given": { + "rawUnsignedTx": "02000000097de20cbff686da83a54981d2b9bab3586f4ca7e48f57f5b55963115f3b334e9c010000000000000000d7b7cab57b1393ace2d064f4d4a2cb8af6def61273e127517d44759b6dafdd990000000000fffffffff8e1f583384333689228c5d28eac13366be082dc57441760d957275419a418420000000000fffffffff0689180aa63b30cb162a73c6d2a38b7eeda2a83ece74310fda0843ad604853b0100000000feffffffaa5202bdf6d8ccd2ee0f0202afbbb7461d9264a25e5bfd3c5a52ee1239e0ba6c0000000000feffffff956149bdc66faa968eb2be2d2faa29718acbfe3941215893a2a3446d32acd050000000000000000000e664b9773b88c09c32cb70a2a3e4da0ced63b7ba3b22f848531bbb1d5d5f4c94010000000000000000e9aa6b8e6c9de67619e6a3924ae25696bb7b694bb677a632a74ef7eadfd4eabf0000000000ffffffffa778eb6a263dc090464cd125c466b5a99667720b1c110468831d058aa1b82af10100000000ffffffff0200ca9a3b000000001976a91406afd46bcdfd22ef94ac122aa11f241244a37ecc88ac807840cb0000000020ac9a87f5594be208f8532db38cff670c450ed2fea8fcdefcc9a663f78bab962b0065cd1d", + "utxosSpent": [ + { + "scriptPubKey": "512053a1f6e454df1aa2776a2814a721372d6258050de330b3c6d10ee8f4e0dda343", + "amountSats": 420000000 + }, + { + "scriptPubKey": "5120147c9c57132f6e7ecddba9800bb0c4449251c92a1e60371ee77557b6620f3ea3", + "amountSats": 462000000 + }, + { + "scriptPubKey": "76a914751e76e8199196d454941c45d1b3a323f1433bd688ac", + "amountSats": 294000000 + }, + { + "scriptPubKey": "5120e4d810fd50586274face62b8a807eb9719cef49c04177cc6b76a9a4251d5450e", + "amountSats": 504000000 + }, + { + "scriptPubKey": "512091b64d5324723a985170e4dc5a0f84c041804f2cd12660fa5dec09fc21783605", + "amountSats": 630000000 + }, + { + "scriptPubKey": "00147dd65592d0ab2fe0d0257d571abf032cd9db93dc", + "amountSats": 378000000 + }, + { + "scriptPubKey": "512075169f4001aa68f15bbed28b218df1d0a62cbbcf1188c6665110c293c907b831", + "amountSats": 672000000 + }, + { + "scriptPubKey": "5120712447206d7a5238acc7ff53fbe94a3b64539ad291c7cdbc490b7577e4b17df5", + "amountSats": 546000000 + }, + { + "scriptPubKey": "512077e30a5522dd9f894c3f8b8bd4c4b2cf82ca7da8a3ea6a239655c39c050ab220", + "amountSats": 588000000 + } + ] + }, + "intermediary": { + "hashAmounts": "58a6964a4f5f8f0b642ded0a8a553be7622a719da71d1f5befcefcdee8e0fde6", + "hashOutputs": "a2e6dab7c1f0dcd297c8d61647fd17d821541ea69c3cc37dcbad7f90d4eb4bc5", + "hashPrevouts": "e3b33bb4ef3a52ad1fffb555c0d82828eb22737036eaeb02a235d82b909c4c3f", + "hashScriptPubkeys": "23ad0f61ad2bca5ba6a7693f50fce988e17c3780bf2b1e720cfbb38fbdd52e21", + "hashSequences": "18959c7221ab5ce9e26c3cd67b22c24f8baa54bac281d8e6b05e400e6c3a957e" + }, + "inputSpending": [ + { + "given": { + "txinIndex": 0, + "internalPrivkey": "6b973d88838f27366ed61c9ad6367663045cb456e28335c109e30717ae0c6baa", + "merkleRoot": null, + "hashType": 3 + }, + "intermediary": { + "internalPubkey": "d6889cb081036e0faefa3a35157ad71086b123b2b144b649798b494c300a961d", + "tweak": "b86e7be8f39bab32a6f2c0443abbc210f0edac0e2c53d501b36b64437d9c6c70", + "tweakedPrivkey": "2405b971772ad26915c8dcdf10f238753a9b837e5f8e6a86fd7c0cce5b7296d9", + "sigMsg": "0003020000000065cd1de3b33bb4ef3a52ad1fffb555c0d82828eb22737036eaeb02a235d82b909c4c3f58a6964a4f5f8f0b642ded0a8a553be7622a719da71d1f5befcefcdee8e0fde623ad0f61ad2bca5ba6a7693f50fce988e17c3780bf2b1e720cfbb38fbdd52e2118959c7221ab5ce9e26c3cd67b22c24f8baa54bac281d8e6b05e400e6c3a957e0000000000d0418f0e9a36245b9a50ec87f8bf5be5bcae434337b87139c3a5b1f56e33cba0", + "precomputedUsed": [ + "hashAmounts", + "hashPrevouts", + "hashScriptPubkeys", + "hashSequences" + ], + "sigHash": "2514a6272f85cfa0f45eb907fcb0d121b808ed37c6ea160a5a9046ed5526d555" + }, + "expected": { + "witness": [ + "ed7c1647cb97379e76892be0cacff57ec4a7102aa24296ca39af7541246d8ff14d38958d4cc1e2e478e4d4a764bbfd835b16d4e314b72937b29833060b87276c03" + ] + } + }, + { + "given": { + "txinIndex": 1, + "internalPrivkey": "1e4da49f6aaf4e5cd175fe08a32bb5cb4863d963921255f33d3bc31e1343907f", + "merkleRoot": "5b75adecf53548f3ec6ad7d78383bf84cc57b55a3127c72b9a2481752dd88b21", + "hashType": 131 + }, + "intermediary": { + "internalPubkey": "187791b6f712a8ea41c8ecdd0ee77fab3e85263b37e1ec18a3651926b3a6cf27", + "tweak": "cbd8679ba636c1110ea247542cfbd964131a6be84f873f7f3b62a777528ed001", + "tweakedPrivkey": "ea260c3b10e60f6de018455cd0278f2f5b7e454be1999572789e6a9565d26080", + "sigMsg": "0083020000000065cd1d00d7b7cab57b1393ace2d064f4d4a2cb8af6def61273e127517d44759b6dafdd9900000000808f891b00000000225120147c9c57132f6e7ecddba9800bb0c4449251c92a1e60371ee77557b6620f3ea3ffffffffffcef8fb4ca7efc5433f591ecfc57391811ce1e186a3793024def5c884cba51d", + "precomputedUsed": [], + "sigHash": "325a644af47e8a5a2591cda0ab0723978537318f10e6a63d4eed783b96a71a4d" + }, + "expected": { + "witness": [ + "052aedffc554b41f52b521071793a6b88d6dbca9dba94cf34c83696de0c1ec35ca9c5ed4ab28059bd606a4f3a657eec0bb96661d42921b5f50a95ad33675b54f83" + ] + } + }, + { + "given": { + "txinIndex": 3, + "internalPrivkey": "d3c7af07da2d54f7a7735d3d0fc4f0a73164db638b2f2f7c43f711f6d4aa7e64", + "merkleRoot": "c525714a7f49c28aedbbba78c005931a81c234b2f6c99a73e4d06082adc8bf2b", + "hashType": 1 + }, + "intermediary": { + "internalPubkey": "93478e9488f956df2396be2ce6c5cced75f900dfa18e7dabd2428aae78451820", + "tweak": "6af9e28dbf9d6aaf027696e2598a5b3d056f5fd2355a7fd5a37a0e5008132d30", + "tweakedPrivkey": "97323385e57015b75b0339a549c56a948eb961555973f0951f555ae6039ef00d", + "sigMsg": "0001020000000065cd1de3b33bb4ef3a52ad1fffb555c0d82828eb22737036eaeb02a235d82b909c4c3f58a6964a4f5f8f0b642ded0a8a553be7622a719da71d1f5befcefcdee8e0fde623ad0f61ad2bca5ba6a7693f50fce988e17c3780bf2b1e720cfbb38fbdd52e2118959c7221ab5ce9e26c3cd67b22c24f8baa54bac281d8e6b05e400e6c3a957ea2e6dab7c1f0dcd297c8d61647fd17d821541ea69c3cc37dcbad7f90d4eb4bc50003000000", + "precomputedUsed": [ + "hashAmounts", + "hashOutputs", + "hashPrevouts", + "hashScriptPubkeys", + "hashSequences" + ], + "sigHash": "bf013ea93474aa67815b1b6cc441d23b64fa310911d991e713cd34c7f5d46669" + }, + "expected": { + "witness": [ + "ff45f742a876139946a149ab4d9185574b98dc919d2eb6754f8abaa59d18b025637a3aa043b91817739554f4ed2026cf8022dbd83e351ce1fabc272841d2510a01" + ] + } + }, + { + "given": { + "txinIndex": 4, + "internalPrivkey": "f36bb07a11e469ce941d16b63b11b9b9120a84d9d87cff2c84a8d4affb438f4e", + "merkleRoot": "ccbd66c6f7e8fdab47b3a486f59d28262be857f30d4773f2d5ea47f7761ce0e2", + "hashType": 0 + }, + "intermediary": { + "internalPubkey": "e0dfe2300b0dd746a3f8674dfd4525623639042569d829c7f0eed9602d263e6f", + "tweak": "b57bfa183d28eeb6ad688ddaabb265b4a41fbf68e5fed2c72c74de70d5a786f4", + "tweakedPrivkey": "a8e7aa924f0d58854185a490e6c41f6efb7b675c0f3331b7f14b549400b4d501", + "sigMsg": "0000020000000065cd1de3b33bb4ef3a52ad1fffb555c0d82828eb22737036eaeb02a235d82b909c4c3f58a6964a4f5f8f0b642ded0a8a553be7622a719da71d1f5befcefcdee8e0fde623ad0f61ad2bca5ba6a7693f50fce988e17c3780bf2b1e720cfbb38fbdd52e2118959c7221ab5ce9e26c3cd67b22c24f8baa54bac281d8e6b05e400e6c3a957ea2e6dab7c1f0dcd297c8d61647fd17d821541ea69c3cc37dcbad7f90d4eb4bc50004000000", + "precomputedUsed": [ + "hashAmounts", + "hashOutputs", + "hashPrevouts", + "hashScriptPubkeys", + "hashSequences" + ], + "sigHash": "4f900a0bae3f1446fd48490c2958b5a023228f01661cda3496a11da502a7f7ef" + }, + "expected": { + "witness": [ + "b4010dd48a617db09926f729e79c33ae0b4e94b79f04a1ae93ede6315eb3669de185a17d2b0ac9ee09fd4c64b678a0b61a0a86fa888a273c8511be83bfd6810f" + ] + } + }, + { + "given": { + "txinIndex": 6, + "internalPrivkey": "415cfe9c15d9cea27d8104d5517c06e9de48e2f986b695e4f5ffebf230e725d8", + "merkleRoot": "2f6b2c5397b6d68ca18e09a3f05161668ffe93a988582d55c6f07bd5b3329def", + "hashType": 2 + }, + "intermediary": { + "internalPubkey": "55adf4e8967fbd2e29f20ac896e60c3b0f1d5b0efa9d34941b5958c7b0a0312d", + "tweak": "6579138e7976dc13b6a92f7bfd5a2fc7684f5ea42419d43368301470f3b74ed9", + "tweakedPrivkey": "241c14f2639d0d7139282aa6abde28dd8a067baa9d633e4e7230287ec2d02901", + "sigMsg": "0002020000000065cd1de3b33bb4ef3a52ad1fffb555c0d82828eb22737036eaeb02a235d82b909c4c3f58a6964a4f5f8f0b642ded0a8a553be7622a719da71d1f5befcefcdee8e0fde623ad0f61ad2bca5ba6a7693f50fce988e17c3780bf2b1e720cfbb38fbdd52e2118959c7221ab5ce9e26c3cd67b22c24f8baa54bac281d8e6b05e400e6c3a957e0006000000", + "precomputedUsed": [ + "hashAmounts", + "hashPrevouts", + "hashScriptPubkeys", + "hashSequences" + ], + "sigHash": "15f25c298eb5cdc7eb1d638dd2d45c97c4c59dcaec6679cfc16ad84f30876b85" + }, + "expected": { + "witness": [ + "a3785919a2ce3c4ce26f298c3d51619bc474ae24014bcdd31328cd8cfbab2eff3395fa0a16fe5f486d12f22a9cedded5ae74feb4bbe5351346508c5405bcfee002" + ] + } + }, + { + "given": { + "txinIndex": 7, + "internalPrivkey": "c7b0e81f0a9a0b0499e112279d718cca98e79a12e2f137c72ae5b213aad0d103", + "merkleRoot": "6c2dc106ab816b73f9d07e3cd1ef2c8c1256f519748e0813e4edd2405d277bef", + "hashType": 130 + }, + "intermediary": { + "internalPubkey": "ee4fe085983462a184015d1f782d6a5f8b9c2b60130aff050ce221ecf3786592", + "tweak": "9e0517edc8259bb3359255400b23ca9507f2a91cd1e4250ba068b4eafceba4a9", + "tweakedPrivkey": "65b6000cd2bfa6b7cf736767a8955760e62b6649058cbc970b7c0871d786346b", + "sigMsg": "0082020000000065cd1d00e9aa6b8e6c9de67619e6a3924ae25696bb7b694bb677a632a74ef7eadfd4eabf00000000804c8b2000000000225120712447206d7a5238acc7ff53fbe94a3b64539ad291c7cdbc490b7577e4b17df5ffffffff", + "precomputedUsed": [], + "sigHash": "cd292de50313804dabe4685e83f923d2969577191a3e1d2882220dca88cbeb10" + }, + "expected": { + "witness": [ + "ea0c6ba90763c2d3a296ad82ba45881abb4f426b3f87af162dd24d5109edc1cdd11915095ba47c3a9963dc1e6c432939872bc49212fe34c632cd3ab9fed429c482" + ] + } + }, + { + "given": { + "txinIndex": 8, + "internalPrivkey": "77863416be0d0665e517e1c375fd6f75839544eca553675ef7fdf4949518ebaa", + "merkleRoot": "ab179431c28d3b68fb798957faf5497d69c883c6fb1e1cd9f81483d87bac90cc", + "hashType": 129 + }, + "intermediary": { + "internalPubkey": "f9f400803e683727b14f463836e1e78e1c64417638aa066919291a225f0e8dd8", + "tweak": "639f0281b7ac49e742cd25b7f188657626da1ad169209078e2761cefd91fd65e", + "tweakedPrivkey": "ec18ce6af99f43815db543f47b8af5ff5df3b2cb7315c955aa4a86e8143d2bf5", + "sigMsg": "0081020000000065cd1da2e6dab7c1f0dcd297c8d61647fd17d821541ea69c3cc37dcbad7f90d4eb4bc500a778eb6a263dc090464cd125c466b5a99667720b1c110468831d058aa1b82af101000000002b0c230000000022512077e30a5522dd9f894c3f8b8bd4c4b2cf82ca7da8a3ea6a239655c39c050ab220ffffffff", + "precomputedUsed": [ + "hashOutputs" + ], + "sigHash": "cccb739eca6c13a8a89e6e5cd317ffe55669bbda23f2fd37b0f18755e008edd2" + }, + "expected": { + "witness": [ + "bbc9584a11074e83bc8c6759ec55401f0ae7b03ef290c3139814f545b58a9f8127258000874f44bc46db7646322107d4d86aec8e73b8719a61fff761d75b5dd981" + ] + } + } + ], + "auxiliary": { + "fullySignedTx": "020000000001097de20cbff686da83a54981d2b9bab3586f4ca7e48f57f5b55963115f3b334e9c010000000000000000d7b7cab57b1393ace2d064f4d4a2cb8af6def61273e127517d44759b6dafdd990000000000fffffffff8e1f583384333689228c5d28eac13366be082dc57441760d957275419a41842000000006b4830450221008f3b8f8f0537c420654d2283673a761b7ee2ea3c130753103e08ce79201cf32a022079e7ab904a1980ef1c5890b648c8783f4d10103dd62f740d13daa79e298d50c201210279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798fffffffff0689180aa63b30cb162a73c6d2a38b7eeda2a83ece74310fda0843ad604853b0100000000feffffffaa5202bdf6d8ccd2ee0f0202afbbb7461d9264a25e5bfd3c5a52ee1239e0ba6c0000000000feffffff956149bdc66faa968eb2be2d2faa29718acbfe3941215893a2a3446d32acd050000000000000000000e664b9773b88c09c32cb70a2a3e4da0ced63b7ba3b22f848531bbb1d5d5f4c94010000000000000000e9aa6b8e6c9de67619e6a3924ae25696bb7b694bb677a632a74ef7eadfd4eabf0000000000ffffffffa778eb6a263dc090464cd125c466b5a99667720b1c110468831d058aa1b82af10100000000ffffffff0200ca9a3b000000001976a91406afd46bcdfd22ef94ac122aa11f241244a37ecc88ac807840cb0000000020ac9a87f5594be208f8532db38cff670c450ed2fea8fcdefcc9a663f78bab962b0141ed7c1647cb97379e76892be0cacff57ec4a7102aa24296ca39af7541246d8ff14d38958d4cc1e2e478e4d4a764bbfd835b16d4e314b72937b29833060b87276c030141052aedffc554b41f52b521071793a6b88d6dbca9dba94cf34c83696de0c1ec35ca9c5ed4ab28059bd606a4f3a657eec0bb96661d42921b5f50a95ad33675b54f83000141ff45f742a876139946a149ab4d9185574b98dc919d2eb6754f8abaa59d18b025637a3aa043b91817739554f4ed2026cf8022dbd83e351ce1fabc272841d2510a010140b4010dd48a617db09926f729e79c33ae0b4e94b79f04a1ae93ede6315eb3669de185a17d2b0ac9ee09fd4c64b678a0b61a0a86fa888a273c8511be83bfd6810f0247304402202b795e4de72646d76eab3f0ab27dfa30b810e856ff3a46c9a702df53bb0d8cc302203ccc4d822edab5f35caddb10af1be93583526ccfbade4b4ead350781e2f8adcd012102f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f90141a3785919a2ce3c4ce26f298c3d51619bc474ae24014bcdd31328cd8cfbab2eff3395fa0a16fe5f486d12f22a9cedded5ae74feb4bbe5351346508c5405bcfee0020141ea0c6ba90763c2d3a296ad82ba45881abb4f426b3f87af162dd24d5109edc1cdd11915095ba47c3a9963dc1e6c432939872bc49212fe34c632cd3ab9fed429c4820141bbc9584a11074e83bc8c6759ec55401f0ae7b03ef290c3139814f545b58a9f8127258000874f44bc46db7646322107d4d86aec8e73b8719a61fff761d75b5dd9810065cd1d" + } + } + ] +} diff --git a/bip-0342.mediawiki b/bip-0342.mediawiki index 87e07ae..bbefcaa 100644 --- a/bip-0342.mediawiki +++ b/bip-0342.mediawiki @@ -104,13 +104,17 @@ The following rules apply to <code>OP_CHECKSIG</code>, <code>OP_CHECKSIGVERIFY</ *** For <code>OP_CHECKSIG</code>, a 1-byte value <code>0x01</code> is pushed onto the stack. *** For <code>OP_CHECKSIGADD</code>, a <code>CScriptNum</code> with value of <code>n + 1</code> is pushed onto the stack. +===Common Signature Message Extension=== + +We define the tapscript message extension ''ext'' to [[bip-0341.mediawiki#common-signature-message|BIP341 Common Signature Message]], indicated by ''ext_flag = 1'': +* ''tapleaf_hash'' (32): the tapleaf hash as defined in [[bip-0341.mediawiki#design|BIP341]] +* ''key_version'' (1): a constant value ''0x00'' representing the current version of public keys in the tapscript signature opcode execution. +* ''codesep_pos'' (4): the opcode position of the last executed <code>OP_CODESEPARATOR</code> before the currently executed signature opcode, with the value in little endian (or ''0xffffffff'' if none executed). The first opcode in a script has a position of 0. A multi-byte push opcode is counted as one opcode, regardless of the size of data being pushed. Opcodes in parsed but unexecuted branches count towards this value as well. + ===Signature validation=== To validate a signature ''sig'' with public key ''p'': -* Compute the tapscript message extension ''ext'', consisting of the concatenation of: -** ''tapleaf_hash'' (32): the tapleaf hash as defined in [[bip-0341.mediawiki#design|BIP341]] -** ''key_version'' (1): a constant value ''0x00'' representing the current version of public keys in the tapscript signature opcode execution. -** ''codesep_pos'' (4): the opcode position of the last executed <code>OP_CODESEPARATOR</code> before the currently executed signature opcode, with the value in little endian (or ''0xffffffff'' if none executed). The first opcode in a script has a position of 0. A multi-byte push opcode is counted as one opcode, regardless of the size of data being pushed. Opcodes in parsed but unexecuted branches count towards this value as well. +* Compute the tapscript message extension ''ext'' described above. * If the ''sig'' is 64 bytes long, return ''Verify(p, hash<sub>TapSighash</sub>(0x00 || SigMsg(0x00, 1) || ext), sig)'', where ''Verify'' is defined in [[bip-0340.mediawiki#design|BIP340]]. * If the ''sig'' is 65 bytes long, return ''sig[64] ≠ 0x00 and Verify(p, hash<sub>TapSighash</sub>(0x00 || SigMsg(sig[64], 1) || ext), sig[0:64])''. * Otherwise, fail. diff --git a/bip-0370.mediawiki b/bip-0370.mediawiki index 8dd557a..263fd13 100644 --- a/bip-0370.mediawiki +++ b/bip-0370.mediawiki @@ -197,7 +197,7 @@ The new per-output types for PSBT Version 2 are defined as follows: | 2 |- | Output Script -| <tt>PSBT_OUT_SCRIPT = 0x03</tt> +| <tt>PSBT_OUT_SCRIPT = 0x04</tt> | None | No key data | <tt><script></tt> @@ -209,9 +209,9 @@ The new per-output types for PSBT Version 2 are defined as follows: ===Determining Lock Time=== -The nLockTime field of a transaction is determined by inspecting the PSBT_GLOBAL_PREFERRED_LOCKTIME and each input's PSBT_IN_REQUIRED_TIME_LOCKTIME and PSBT_IN_REQUIRED_HEIGHT_LOCKTIME fields. -If none of the inputs have a PSBT_IN_REQUIRED_TIME_LOCKTIME and PSBT_IN_REQUIRED_HEIGHT_LOCKTIME, then PSBT_GLOBAL_PREFERRED_LOCKTIME must be used. -If PSBT_GLOBAL_PREFERRED_LOCKTIME is not provided, then it is assumed to be 0. +The nLockTime field of a transaction is determined by inspecting the PSBT_GLOBAL_FALLBACK_LOCKTIME and each input's PSBT_IN_REQUIRED_TIME_LOCKTIME and PSBT_IN_REQUIRED_HEIGHT_LOCKTIME fields. +If none of the inputs have a PSBT_IN_REQUIRED_TIME_LOCKTIME and PSBT_IN_REQUIRED_HEIGHT_LOCKTIME, then PSBT_GLOBAL_FALLBACK_LOCKTIME must be used. +If PSBT_GLOBAL_FALLBACK_LOCKTIME is not provided, then it is assumed to be 0. If one or more inuts have a PSBT_IN_REQUIRED_TIME_LOCKTIME or PSBT_IN_REQUIRED_HEIGHT_LOCKTIME, then the field chosen is the one which is supported by all of the inputs. This can be determined by looking at all of the inputs which specify a locktime in either of those fields, and choosing the field which is present in all of those inputs. @@ -232,7 +232,7 @@ PSBTv2 introduces new roles and modifies some existing roles. In PSBTv2, the Creator initializes the PSBT with 0 inputs and 0 outputs. The PSBT version number is set to 2. The transaction version number must be set to at least 2. <ref>'''Why does the transaction version number need to be at least 2?''' The transaction version number is part of the validation rules for some features such as OP_CHECKSEQUENCEVERIFY. Since it is backwards compatible, and there are other ways to disable those features (e.g. through sequence numbers), it is easier to require transactions be able to support these features than to try to negotiate the transaction version number.</ref> -The Creator should also set PSBT_GLOBAL_PREFERRED_LOCKTIME. +The Creator should also set PSBT_GLOBAL_FALLBACK_LOCKTIME. If the Creator is not also a Constructor and will be giving the PSBT to others to add inputs and outputs, the PSBT_GLOBAL_TX_MODIFIABLE field must be present and and the Inputs Modifiable and Outputs Modifiable flags set appropriately. If the Creator is a Constructor and no inputs and outputs will be added by other entities, PSBT_GLOBAL_TX_MODIFIABLE may be omitted. diff --git a/bip-0371.mediawiki b/bip-0371.mediawiki new file mode 100644 index 0000000..189c36f --- /dev/null +++ b/bip-0371.mediawiki @@ -0,0 +1,250 @@ +<pre> + BIP: 371 + Layer: Applications + Title: Taproot Fields for PSBT + Author: Andrew Chow <andrew@achow101.com> + Comments-Summary: No comments yet. + Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0371 + Status: Draft + Type: Standards Track + Created: 2021-06-21 + License: BSD-2-Clause +</pre> + +==Introduction== + +===Abstract=== + +This document proposes additional fields for BIP 174 PSBTv0 and BIP 370 PSBTv2 that allow for +BIP 340/341/342 Taproot data to be included in a PSBT of any version. These will be fields for +signatures and scripts that are relevant to the creation of Taproot inputs. + +===Copyright=== + +This BIP is licensed under the 2-clause BSD license. + +===Motivation=== + +BIPs 340, 341, and 342 specify Taproot which provides a wholly new way to create and spend Bitcoin outputs. +The existing PSBT fields are unable to support Taproot due to the new signature algorithm and the method +by which scripts are embedded inside of a Taproot output. Therefore new fields must be defined to allow +PSBTs to carry the information necessary for signing Taproot inputs. + +==Specification== + +The new per-input types are defined as follows: + +{| +! Name +! <tt><keytype></tt> +! <tt><keydata></tt> +! <tt><keydata></tt> Description +! <tt><valuedata></tt> +! <tt><valuedata></tt> Description +! Versions Requiring Inclusion +! Versions Requiring Exclusion +! Versions Allowing Inclusion +|- +| Taproot Key Spend Signature +| <tt>PSBT_IN_TAP_KEY_SIG = 0x13</tt> +| None +| No key data <ref>'''Why is there no key data for <tt>PSBT_IN_TAP_KEY_SIG</tt>'''The signature in a key path spend corresponds directly with the pubkey provided in the output script. Thus it is not necessary to provide any metadata that attaches the key path spend signature to a particular pubkey.</ref> +| <tt><signature></tt> +| The 64 or 65 byte Schnorr signature for key path spending a Taproot output. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +|- +| Taproot Script Spend Signature +| <tt>PSBT_IN_TAP_SCRIPT_SIG = 0x14</tt> +| <tt><xonlypubkey> <leafhash></tt> +| A 32 byte X-only public key involved in a leaf script concatenated with the 32 byte hash of the leaf it is part of. +| <tt><signature></tt> +| The 64 or 65 byte Schnorr signature for this pubkey and leaf combination. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +|- +| Taproot Leaf Script +| <tt>PSBT_IN_TAP_LEAF_SCRIPT = 0x15</tt> +| <tt><control block></tt> +| The control block for this leaf as specified in BIP 341. The control block contains the merkle tree path to this leaf. +| <tt><script> <8-bit uint></tt> +| The script for this leaf as would be provided in the witness stack followed by the single byte leaf version. Note that the leaves included in this field should be those that the signers of this input are expected to be able to sign for. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +|- +| Taproot Key BIP 32 Derivation Path +| <tt>PSBT_IN_TAP_BIP32_DERIVATION = 0x16</tt> +| <tt><xonlypubkey></tt> +| A 32 byte X-only public key involved in this input. It may be the internal key, or a key present in a leaf script. +| <tt><hashes len> <leaf hash>* <4 byte fingerprint> <32-bit uint>*</tt> +| A compact size unsigned integer representing the number of leaf hashes, followed by a list of leaf hashes, followed by the 4 byte master key fingerprint concatenated with the derivation path of the public key. The derivation path is represented as 32-bit little endian unsigned integer indexes concatenated with each other. Public keys are those needed to spend this output. The leaf hashes are of the leaves which involve this public key. The internal key does not have leaf hashes, so can be indicated with a <tt>hashes len</tt> of 0. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +|- +| Taproot Internal Key +| <tt>PSBT_IN_TAP_INTERNAL_KEY = 0x17</tt> +| None +| No key data +| <tt><pubkey></tt> +| The X-only pubkey used as the internal key in this output.<ref>'''Why is the internal key provided?'''The internal key is not necessarily the same key as in the Taproot output script. BIP 341 recommends tweaking the key with the hash of itself. It may be necessary for signers to know what the internal key actually is so that they are able to determine whether an input can be signed by it.</ref> Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +|- +| Taproot Merkle Root +| <tt>PSBT_IN_TAP_MERKLE_ROOT = 0x18</tt> +| None +| No key data +| <tt><pubkey></tt> +| The 32 byte Merkle root hash. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +|} + +The new per-output types are defined as follows: + +{| +! Name +! <tt><keytype></tt> +! <tt><keydata></tt> +! <tt><keydata></tt> Description +! <tt><valuedata></tt> +! <tt><valuedata></tt> Description +! Versions Requiring Inclusion +! Versions Requiring Exclusion +! Versions Allowing Inclusion +|- +| Taproot Internal Key +| <tt>PSBT_OUT_TAP_INTERNAL_KEY = 0x05</tt> +| None +| No key data +| <tt><pubkey></tt> +| The X-only pubkey used as the internal key in this output. +| +| +| 0, 2 +|- +| Taproot Tree +| <tt>PSBT_OUT_TAP_TREE = 0x06</tt> +| None +| No key data +| <tt>{<8-bit uint depth> <8-bit uint leaf version> <scriptlen> <script>}*</tt> +| One or more tuples representing the depth, leaf version, and script for a leaf in the Taproot tree, allowing the entire tree to be reconstructed. The tuples must be in depth first search order so that the tree is correctly reconstructed. Each tuple is an 8-bit unsigned integer representing the depth in the Taproot tree for this script, an 8-bit unsigned integer representing the leaf version, the length of the script as a compact size unsigned integer, and the script itself. +| +| +| 0, 2 +|- +| Taproot Key BIP 32 Derivation Path +| <tt>PSBT_OUT_TAP_BIP32_DERIVATION = 0x07</tt> +| <tt><xonlypubkey></tt> +| A 32 byte X-only public key involved in this output. It may be the internal key, or a key present in a leaf script. +| <tt><hashes len> <leaf hash>* <4 byte fingerprint> <32-bit uint>*</tt> +| A compact size unsigned integer representing the number of leaf hashes, followed by a list of leaf hashes, followed by the 4 byte master key fingerprint concatenated with the derivation path of the public key. The derivation path is represented as 32-bit little endian unsigned integer indexes concatenated with each other. Public keys are those needed to spend this output. The leaf hashes are of the leaves which involve this public key. The internal key does not have leaf hashes, so can be indicated with a <tt>hashes len</tt> of 0. Finalizers should remove this field after <tt>PSBT_IN_FINAL_SCRIPTWITNESS</tt> is constructed. +| +| +| 0, 2 +|} + +===UTXO Types=== + +BIP 174 recommends using <tt>PSBT_IN_NON_WITNESS_UTXO</tt> for all inputs because of potential attacks involving +an updater lying about the amounts in an output. Because a Taproot signature will commit to all of the amounts +and output scripts spent by the inputs of the transaction, such attacks are prevented as any such lying would +result in an invalid signature. Thus Taproot inputs can use just <tt>PSBT_IN_WITNESS_UTXO</tt>. + +==Compatibility== + +These are simply new fields added to the existing PSBT format. Because PSBT is designed to be extensible, old +software will ignore the new fields. + +==Test Vectors== + +The following are invalid PSBTs: + +* Case: PSBT With <tt>PSBT_IN_TAP_INTERNAL_KEY</tt> key that is too long (incorrectly serialized as compressed DER) +** Bytes in Hex: <pre>70736274ff010071020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff02787c01000000000016001483a7e34bd99ff03a4962ef8a1a101bb295461ece606b042a010000001600147ac369df1b20e033d6116623957b0ac49f3c52e8000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a075701172102fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa232000000 +</pre> +** Base64 String: <pre>cHNidP8BAHECAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////Anh8AQAAAAAAFgAUg6fjS9mf8DpJYu+KGhAbspVGHs5gawQqAQAAABYAFHrDad8bIOAz1hFmI5V7CsSfPFLoAAAAAAABASsA8gUqAQAAACJRIFosLPW1LPMfg60ujaY/8DGD7Nj2CcdRCuikjgORCgdXARchAv40kGTJjW4qhT+jybEr2LMEoZwZXGDvp+4jkwRtP6IyAAAA</pre> + +* Case: PSBT With <tt>PSBT_KEY_PATH_SIG</tt> signature that is too short +** Bytes in Hex: <pre><70736274ff010071020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff02787c01000000000016001483a7e34bd99ff03a4962ef8a1a101bb295461ece606b042a010000001600147ac369df1b20e033d6116623957b0ac49f3c52e8000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a075701133f173bb3d36c074afb716fec6307a069a2e450b995f3c82785945ab8df0e24260dcd703b0cbf34de399184a9481ac2b3586db6601f026a77f7e4938481bc3475000000</pre> +** Base64 String: <pre>cHNidP8BAHECAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////Anh8AQAAAAAAFgAUg6fjS9mf8DpJYu+KGhAbspVGHs5gawQqAQAAABYAFHrDad8bIOAz1hFmI5V7CsSfPFLoAAAAAAABASsA8gUqAQAAACJRIFosLPW1LPMfg60ujaY/8DGD7Nj2CcdRCuikjgORCgdXARM/Fzuz02wHSvtxb+xjB6BpouRQuZXzyCeFlFq43w4kJg3NcDsMvzTeOZGEqUgawrNYbbZgHwJqd/fkk4SBvDR1AAAA</pre> + +* Case: PSBT With <tt>PSBT_KEY_PATH_SIG</tt> signature that is too long +** Bytes in Hex: <pre><70736274ff010071020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff02787c01000000000016001483a7e34bd99ff03a4962ef8a1a101bb295461ece606b042a010000001600147ac369df1b20e033d6116623957b0ac49f3c52e8000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a0757011342173bb3d36c074afb716fec6307a069a2e450b995f3c82785945ab8df0e24260dcd703b0cbf34de399184a9481ac2b3586db6601f026a77f7e4938481bc34751701aa000000</pre> +** Base64 String: <pre>cHNidP8BAHECAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////Anh8AQAAAAAAFgAUg6fjS9mf8DpJYu+KGhAbspVGHs5gawQqAQAAABYAFHrDad8bIOAz1hFmI5V7CsSfPFLoAAAAAAABASsA8gUqAQAAACJRIFosLPW1LPMfg60ujaY/8DGD7Nj2CcdRCuikjgORCgdXARNCFzuz02wHSvtxb+xjB6BpouRQuZXzyCeFlFq43w4kJg3NcDsMvzTeOZGEqUgawrNYbbZgHwJqd/fkk4SBvDR1FwGqAAAA</pre> + +* Case: PSBT With <tt>PSBT_IN_TAP_BIP32_DERIVATION</tt> key that is too long (incorrectly serialized as compressed DER) +** Bytes in Hex: <pre><70736274ff010071020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff02787c01000000000016001483a7e34bd99ff03a4962ef8a1a101bb295461ece606b042a010000001600147ac369df1b20e033d6116623957b0ac49f3c52e8000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a0757221602fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa2321900772b2da75600008001000080000000800100000000000000000000</pre> +** Base64 String: <pre>cHNidP8BAHECAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////Anh8AQAAAAAAFgAUg6fjS9mf8DpJYu+KGhAbspVGHs5gawQqAQAAABYAFHrDad8bIOAz1hFmI5V7CsSfPFLoAAAAAAABASsA8gUqAQAAACJRIFosLPW1LPMfg60ujaY/8DGD7Nj2CcdRCuikjgORCgdXIhYC/jSQZMmNbiqFP6PJsSvYswShnBlcYO+n7iOTBG0/ojIZAHcrLadWAACAAQAAgAAAAIABAAAAAAAAAAAAAA==</pre> + +* Case: PSBT With <tt>PSBT_OUT_TAP_INTERNAL_KEY</tt> key that is too long (incorrectly serialized as compressed DER) +** Bytes in Hex: <pre>70736274ff01007d020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff02887b0100000000001600142382871c7e8421a00093f754d91281e675874b9f606b042a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a0757000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a0757000001052102fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa23200</pre> +** Base64 String: <pre>cHNidP8BAH0CAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////Aoh7AQAAAAAAFgAUI4KHHH6EIaAAk/dU2RKB5nWHS59gawQqAQAAACJRIFosLPW1LPMfg60ujaY/8DGD7Nj2CcdRCuikjgORCgdXAAAAAAABASsA8gUqAQAAACJRIFosLPW1LPMfg60ujaY/8DGD7Nj2CcdRCuikjgORCgdXAAABBSEC/jSQZMmNbiqFP6PJsSvYswShnBlcYO+n7iOTBG0/ojIA</pre> + +* Case: PSBT With <tt>PSBT_OUT_TAP_BIP32_DERIVATION</tt> key that is too long (incorrectly serialized as compressed DER) +** Bytes in Hex: <pre>70736274ff01007d020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff02887b0100000000001600142382871c7e8421a00093f754d91281e675874b9f606b042a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a0757000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a07570000220702fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa2321900772b2da7560000800100008000000080010000000000000000</pre> +** Base64 String: <pre>cHNidP8BAH0CAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////Aoh7AQAAAAAAFgAUI4KHHH6EIaAAk/dU2RKB5nWHS59gawQqAQAAACJRIFosLPW1LPMfg60ujaY/8DGD7Nj2CcdRCuikjgORCgdXAAAAAAABASsA8gUqAQAAACJRIFosLPW1LPMfg60ujaY/8DGD7Nj2CcdRCuikjgORCgdXAAAiBwL+NJBkyY1uKoU/o8mxK9izBKGcGVxg76fuI5MEbT+iMhkAdystp1YAAIABAACAAAAAgAEAAAAAAAAAAA==</pre> + +* Case: PSBT With <tt>PSBT_IN_TAP_SCRIPT_SIG</tt> key that is too long (incorrectly serialized as compressed DER) +** Bytes in Hex: <pre>70736274ff01005e02000000019bd48765230bf9a72e662001f972556e54f0c6f97feb56bcb5600d817f6995260100000000ffffffff0148e6052a01000000225120030da4fce4f7db28c2cb2951631e003713856597fe963882cb500e68112cca63000000000001012b00f2052a01000000225120c2247efbfd92ac47f6f40b8d42d169175a19fa9fa10e4a25d7f35eb4dd85b6924214022cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d2cd970e15f53fc0c82f950fd560ffa919b76172be017368a89913af074f400b094089756aa3739ccc689ec0fcf3a360be32cc0b59b16e93a1e8bb4605726b2ca7a3ff706c4176649632b2cc68e1f912b8a578e3719ce7710885c7a966f49bcd43cb0000</pre> +** Base64 String: <pre>cHNidP8BAF4CAAAAAZvUh2UjC/mnLmYgAflyVW5U8Mb5f+tWvLVgDYF/aZUmAQAAAAD/////AUjmBSoBAAAAIlEgAw2k/OT32yjCyylRYx4ANxOFZZf+ljiCy1AOaBEsymMAAAAAAAEBKwDyBSoBAAAAIlEgwiR++/2SrEf29AuNQtFpF1oZ+p+hDkol1/NetN2FtpJCFAIssTrGgkjegGqmo2Wc88A+toIdCcgRSk6Gj+vehlu20s2XDhX1P8DIL5UP1WD/qRm3YXK+AXNoqJkTrwdPQAsJQIl1aqNznMxonsD886NgvjLMC1mxbpOh6LtGBXJrLKej/3BsQXZkljKyzGjh+RK4pXjjcZzncQiFx6lm9JvNQ8sAAA==</pre> + +* Case: PSBT With <tt>PSBT_IN_TAP_SCRIPT_SIG</tt> signature that is too long +** Bytes in Hex: <pre><0736274ff01005e02000000019bd48765230bf9a72e662001f972556e54f0c6f97feb56bcb5600d817f6995260100000000ffffffff0148e6052a01000000225120030da4fce4f7db28c2cb2951631e003713856597fe963882cb500e68112cca63000000000001012b00f2052a01000000225120c2247efbfd92ac47f6f40b8d42d169175a19fa9fa10e4a25d7f35eb4dd85b69241142cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d2cd970e15f53fc0c82f950fd560ffa919b76172be017368a89913af074f400b094289756aa3739ccc689ec0fcf3a360be32cc0b59b16e93a1e8bb4605726b2ca7a3ff706c4176649632b2cc68e1f912b8a578e3719ce7710885c7a966f49bcd43cb01010000</pre> +** Base64 String: <pre>cHNidP8BAF4CAAAAAZvUh2UjC/mnLmYgAflyVW5U8Mb5f+tWvLVgDYF/aZUmAQAAAAD/////AUjmBSoBAAAAIlEgAw2k/OT32yjCyylRYx4ANxOFZZf+ljiCy1AOaBEsymMAAAAAAAEBKwDyBSoBAAAAIlEgwiR++/2SrEf29AuNQtFpF1oZ+p+hDkol1/NetN2FtpJBFCyxOsaCSN6AaqajZZzzwD62gh0JyBFKToaP696GW7bSzZcOFfU/wMgvlQ/VYP+pGbdhcr4Bc2iomROvB09ACwlCiXVqo3OczGiewPzzo2C+MswLWbFuk6Hou0YFcmssp6P/cGxBdmSWMrLMaOH5ErileONxnOdxCIXHqWb0m81DywEBAAA=</pre> + +* Case: PSBT With <tt>PSBT_IN_TAP_SCRIPT_SIG</tt> signature that is too short +** Bytes in Hex: <pre><70736274ff01005e02000000019bd48765230bf9a72e662001f972556e54f0c6f97feb56bcb5600d817f6995260100000000ffffffff0148e6052a01000000225120030da4fce4f7db28c2cb2951631e003713856597fe963882cb500e68112cca63000000000001012b00f2052a01000000225120c2247efbfd92ac47f6f40b8d42d169175a19fa9fa10e4a25d7f35eb4dd85b69241142cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d2cd970e15f53fc0c82f950fd560ffa919b76172be017368a89913af074f400b093989756aa3739ccc689ec0fcf3a360be32cc0b59b16e93a1e8bb4605726b2ca7a3ff706c4176649632b2cc68e1f912b8a578e3719ce7710885c7a966f49bcd43cb0000</pre> +** Base64 String: <pre>cHNidP8BAF4CAAAAAZvUh2UjC/mnLmYgAflyVW5U8Mb5f+tWvLVgDYF/aZUmAQAAAAD/////AUjmBSoBAAAAIlEgAw2k/OT32yjCyylRYx4ANxOFZZf+ljiCy1AOaBEsymMAAAAAAAEBKwDyBSoBAAAAIlEgwiR++/2SrEf29AuNQtFpF1oZ+p+hDkol1/NetN2FtpJBFCyxOsaCSN6AaqajZZzzwD62gh0JyBFKToaP696GW7bSzZcOFfU/wMgvlQ/VYP+pGbdhcr4Bc2iomROvB09ACwk5iXVqo3OczGiewPzzo2C+MswLWbFuk6Hou0YFcmssp6P/cGxBdmSWMrLMaOH5ErileONxnOdxCIXHqWb0m81DywAA</pre> + +* Case: PSBT With <tt>PSBT_IN_TAP_LEAF_SCRIPT</tt> Control block that is too long +** Bytes in Hex: <pre>70736274ff01005e02000000019bd48765230bf9a72e662001f972556e54f0c6f97feb56bcb5600d817f6995260100000000ffffffff0148e6052a01000000225120030da4fce4f7db28c2cb2951631e003713856597fe963882cb500e68112cca63000000000001012b00f2052a01000000225120c2247efbfd92ac47f6f40b8d42d169175a19fa9fa10e4a25d7f35eb4dd85b6926315c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac06f7d62059e9497a1a4a267569d9876da60101aff38e3529b9b939ce7f91ae970115f2e490af7cc45c4f78511f36057ce5c5a5c56325a29fb44dfc203f356e1f80023202cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d2acc00000</pre> +** Base64 String: <pre>cHNidP8BAF4CAAAAAZvUh2UjC/mnLmYgAflyVW5U8Mb5f+tWvLVgDYF/aZUmAQAAAAD/////AUjmBSoBAAAAIlEgAw2k/OT32yjCyylRYx4ANxOFZZf+ljiCy1AOaBEsymMAAAAAAAEBKwDyBSoBAAAAIlEgwiR++/2SrEf29AuNQtFpF1oZ+p+hDkol1/NetN2FtpJjFcFQkpt0waBJVLeLS2A16XpeB4paDyjsltVHv+6azoA6wG99YgWelJehpKJnVp2YdtpgEBr/OONSm5uTnOf5GulwEV8uSQr3zEXE94UR82BXzlxaXFYyWin7RN/CA/NW4fgAIyAssTrGgkjegGqmo2Wc88A+toIdCcgRSk6Gj+vehlu20qzAAAA=</pre> + +* Case: PSBT With <tt>PSBT_IN_TAP_LEAF_SCRIPT</tt> Control block that is too short +** Bytes in Hex: <pre>70736274ff01005e02000000019bd48765230bf9a72e662001f972556e54f0c6f97feb56bcb5600d817f6995260100000000ffffffff0148e6052a01000000225120030da4fce4f7db28c2cb2951631e003713856597fe963882cb500e68112cca63000000000001012b00f2052a01000000225120c2247efbfd92ac47f6f40b8d42d169175a19fa9fa10e4a25d7f35eb4dd85b6926115c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac06f7d62059e9497a1a4a267569d9876da60101aff38e3529b9b939ce7f91ae970115f2e490af7cc45c4f78511f36057ce5c5a5c56325a29fb44dfc203f356e123202cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d2acc00000</pre> +** Base64 String: <pre>cHNidP8BAF4CAAAAAZvUh2UjC/mnLmYgAflyVW5U8Mb5f+tWvLVgDYF/aZUmAQAAAAD/////AUjmBSoBAAAAIlEgAw2k/OT32yjCyylRYx4ANxOFZZf+ljiCy1AOaBEsymMAAAAAAAEBKwDyBSoBAAAAIlEgwiR++/2SrEf29AuNQtFpF1oZ+p+hDkol1/NetN2FtpJhFcFQkpt0waBJVLeLS2A16XpeB4paDyjsltVHv+6azoA6wG99YgWelJehpKJnVp2YdtpgEBr/OONSm5uTnOf5GulwEV8uSQr3zEXE94UR82BXzlxaXFYyWin7RN/CA/NW4SMgLLE6xoJI3oBqpqNlnPPAPraCHQnIEUpOho/r3oZbttKswAAA</pre> + +The following are valid PSBTs: + +* Case: PSBT with one P2TR key only input with internal key and its derivation path +** Bytes in Hex: <pre>70736274ff010052020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff0148e6052a01000000160014768e1eeb4cf420866033f80aceff0f9720744969000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a07572116fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa2321900772b2da75600008001000080000000800100000000000000011720fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa232002202036b772a6db74d8753c98a827958de6c78ab3312109f37d3e0304484242ece73d818772b2da7540000800100008000000080000000000000000000</pre> +** Base64 String: <pre>cHNidP8BAFICAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////AUjmBSoBAAAAFgAUdo4e60z0IIZgM/gKzv8PlyB0SWkAAAAAAAEBKwDyBSoBAAAAIlEgWiws9bUs8x+DrS6Npj/wMYPs2PYJx1EK6KSOA5EKB1chFv40kGTJjW4qhT+jybEr2LMEoZwZXGDvp+4jkwRtP6IyGQB3Ky2nVgAAgAEAAIAAAACAAQAAAAAAAAABFyD+NJBkyY1uKoU/o8mxK9izBKGcGVxg76fuI5MEbT+iMgAiAgNrdyptt02HU8mKgnlY3mx4qzMSEJ830+AwRIQkLs5z2Bh3Ky2nVAAAgAEAAIAAAACAAAAAAAAAAAAA</pre> + +* Case: PSBT with one P2TR key only input with internal key, its derivation path, and signature +** Bytes in Hex: <pre>70736274ff010052020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff0148e6052a01000000160014768e1eeb4cf420866033f80aceff0f9720744969000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a0757011340bb53ec917bad9d906af1ba87181c48b86ace5aae2b53605a725ca74625631476fc6f5baedaf4f2ee0f477f36f58f3970d5b8273b7e497b97af2e3f125c97af342116fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa2321900772b2da75600008001000080000000800100000000000000011720fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa232002202036b772a6db74d8753c98a827958de6c78ab3312109f37d3e0304484242ece73d818772b2da7540000800100008000000080000000000000000000</pre> +** Base64 String: <pre>cHNidP8BAFICAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////AUjmBSoBAAAAFgAUdo4e60z0IIZgM/gKzv8PlyB0SWkAAAAAAAEBKwDyBSoBAAAAIlEgWiws9bUs8x+DrS6Npj/wMYPs2PYJx1EK6KSOA5EKB1cBE0C7U+yRe62dkGrxuocYHEi4as5aritTYFpyXKdGJWMUdvxvW67a9PLuD0d/NvWPOXDVuCc7fkl7l68uPxJcl680IRb+NJBkyY1uKoU/o8mxK9izBKGcGVxg76fuI5MEbT+iMhkAdystp1YAAIABAACAAAAAgAEAAAAAAAAAARcg/jSQZMmNbiqFP6PJsSvYswShnBlcYO+n7iOTBG0/ojIAIgIDa3cqbbdNh1PJioJ5WN5seKszEhCfN9PgMESEJC7Oc9gYdystp1QAAIABAACAAAAAgAAAAAAAAAAAAA==</pre> + +* Case: PSBT with one P2TR key only output with internal key and its derivation path +** Bytes in Hex: <pre>70736274ff01005e020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff0148e6052a0100000022512083698e458c6664e1595d75da2597de1e22ee97d798e706c4c0a4b5a9823cd743000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a07572116fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa2321900772b2da75600008001000080000000800100000000000000011720fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa232000105201124da7aec92ccd06c954562647f437b138b95721a84be2bf2276bbddab3e67121071124da7aec92ccd06c954562647f437b138b95721a84be2bf2276bbddab3e6711900772b2da7560000800100008000000080000000000500000000</pre> +** Base64 String: <pre>cHNidP8BAF4CAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////AUjmBSoBAAAAIlEgg2mORYxmZOFZXXXaJZfeHiLul9eY5wbEwKS1qYI810MAAAAAAAEBKwDyBSoBAAAAIlEgWiws9bUs8x+DrS6Npj/wMYPs2PYJx1EK6KSOA5EKB1chFv40kGTJjW4qhT+jybEr2LMEoZwZXGDvp+4jkwRtP6IyGQB3Ky2nVgAAgAEAAIAAAACAAQAAAAAAAAABFyD+NJBkyY1uKoU/o8mxK9izBKGcGVxg76fuI5MEbT+iMgABBSARJNp67JLM0GyVRWJkf0N7E4uVchqEvivyJ2u92rPmcSEHESTaeuySzNBslUViZH9DexOLlXIahL4r8idrvdqz5nEZAHcrLadWAACAAQAAgAAAAIAAAAAABQAAAAA=</pre> + +* Case: PSBT with one P2TR script path only input with dummy internal key, scripts, derivation paths for keys in the scripts, and merkle root +** Bytes in Hex: <pre>70736274ff01005e02000000019bd48765230bf9a72e662001f972556e54f0c6f97feb56bcb5600d817f6995260100000000ffffffff0148e6052a0100000022512083698e458c6664e1595d75da2597de1e22ee97d798e706c4c0a4b5a9823cd743000000000001012b00f2052a01000000225120c2247efbfd92ac47f6f40b8d42d169175a19fa9fa10e4a25d7f35eb4dd85b6926215c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac06f7d62059e9497a1a4a267569d9876da60101aff38e3529b9b939ce7f91ae970115f2e490af7cc45c4f78511f36057ce5c5a5c56325a29fb44dfc203f356e1f823202cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d2acc04215c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac097c6e6fea5ff714ff5724499990810e406e98aa10f5bf7e5f6784bc1d0a9a6ce23204320b0bf16f011b53ea7be615924aa7f27e5d29ad20ea1155d848676c3bad1b2acc06215c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0cd970e15f53fc0c82f950fd560ffa919b76172be017368a89913af074f400b09115f2e490af7cc45c4f78511f36057ce5c5a5c56325a29fb44dfc203f356e1f82320fa0f7a3cef3b1d0c0a6ce7d26e17ada0b2e5c92d19efad48b41859cb8a451ca9acc021162cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d23901cd970e15f53fc0c82f950fd560ffa919b76172be017368a89913af074f400b09772b2da7560000800100008002000080000000000000000021164320b0bf16f011b53ea7be615924aa7f27e5d29ad20ea1155d848676c3bad1b23901115f2e490af7cc45c4f78511f36057ce5c5a5c56325a29fb44dfc203f356e1f8772b2da75600008001000080010000800000000000000000211650929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac005007c461e5d2116fa0f7a3cef3b1d0c0a6ce7d26e17ada0b2e5c92d19efad48b41859cb8a451ca939016f7d62059e9497a1a4a267569d9876da60101aff38e3529b9b939ce7f91ae970772b2da7560000800100008003000080000000000000000001172050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0011820f0362e2f75a6f420a5bde3eb221d96ae6720cf25f81890c95b1d775acb515e65000105201124da7aec92ccd06c954562647f437b138b95721a84be2bf2276bbddab3e67121071124da7aec92ccd06c954562647f437b138b95721a84be2bf2276bbddab3e6711900772b2da7560000800100008000000080000000000500000000</pre> +** Base64 String: <pre>cHNidP8BAF4CAAAAAZvUh2UjC/mnLmYgAflyVW5U8Mb5f+tWvLVgDYF/aZUmAQAAAAD/////AUjmBSoBAAAAIlEgg2mORYxmZOFZXXXaJZfeHiLul9eY5wbEwKS1qYI810MAAAAAAAEBKwDyBSoBAAAAIlEgwiR++/2SrEf29AuNQtFpF1oZ+p+hDkol1/NetN2FtpJiFcFQkpt0waBJVLeLS2A16XpeB4paDyjsltVHv+6azoA6wG99YgWelJehpKJnVp2YdtpgEBr/OONSm5uTnOf5GulwEV8uSQr3zEXE94UR82BXzlxaXFYyWin7RN/CA/NW4fgjICyxOsaCSN6AaqajZZzzwD62gh0JyBFKToaP696GW7bSrMBCFcFQkpt0waBJVLeLS2A16XpeB4paDyjsltVHv+6azoA6wJfG5v6l/3FP9XJEmZkIEOQG6YqhD1v35fZ4S8HQqabOIyBDILC/FvARtT6nvmFZJKp/J+XSmtIOoRVdhIZ2w7rRsqzAYhXBUJKbdMGgSVS3i0tgNel6XgeKWg8o7JbVR7/ums6AOsDNlw4V9T/AyC+VD9Vg/6kZt2FyvgFzaKiZE68HT0ALCRFfLkkK98xFxPeFEfNgV85cWlxWMlop+0TfwgPzVuH4IyD6D3o87zsdDAps59JuF62gsuXJLRnvrUi0GFnLikUcqazAIRYssTrGgkjegGqmo2Wc88A+toIdCcgRSk6Gj+vehlu20jkBzZcOFfU/wMgvlQ/VYP+pGbdhcr4Bc2iomROvB09ACwl3Ky2nVgAAgAEAAIACAACAAAAAAAAAAAAhFkMgsL8W8BG1Pqe+YVkkqn8n5dKa0g6hFV2EhnbDutGyOQERXy5JCvfMRcT3hRHzYFfOXFpcVjJaKftE38ID81bh+HcrLadWAACAAQAAgAEAAIAAAAAAAAAAACEWUJKbdMGgSVS3i0tgNel6XgeKWg8o7JbVR7/ums6AOsAFAHxGHl0hFvoPejzvOx0MCmzn0m4XraCy5cktGe+tSLQYWcuKRRypOQFvfWIFnpSXoaSiZ1admHbaYBAa/zjjUpubk5zn+RrpcHcrLadWAACAAQAAgAMAAIAAAAAAAAAAAAEXIFCSm3TBoElUt4tLYDXpel4HiloPKOyW1Ue/7prOgDrAARgg8DYuL3Wm9CClvePrIh2WrmcgzyX4GJDJWx13WstRXmUAAQUgESTaeuySzNBslUViZH9DexOLlXIahL4r8idrvdqz5nEhBxEk2nrskszQbJVFYmR/Q3sTi5VyGoS+K/Ina73as+ZxGQB3Ky2nVgAAgAEAAIAAAACAAAAAAAUAAAAA</pre> + +* Case: PSBT with one P2TR script path only output with dummy internal key, taproot tree, and script key derivation paths +** Bytes in Hex: <pre>70736274ff01005e020000000127744ababf3027fe0d6cf23a96eee2efb188ef52301954585883e69b6624b2420000000000ffffffff0148e6052a010000002251200a8cbdc86de1ce1c0f9caeb22d6df7ced3683fe423e05d1e402a879341d6f6f5000000000001012b00f2052a010000002251205a2c2cf5b52cf31f83ad2e8da63ff03183ecd8f609c7510ae8a48e03910a07572116fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa2321900772b2da75600008001000080000000800100000000000000011720fe349064c98d6e2a853fa3c9b12bd8b304a19c195c60efa7ee2393046d3fa2320001052050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac001066f02c02220736e572900fe1252589a2143c8f3c79f71a0412d2353af755e9701c782694a02ac02c02220631c5f3b5832b8fbdebfb19704ceeb323c21f40f7a24f43d68ef0cc26b125969ac01c0222044faa49a0338de488c8dfffecdfb6f329f380bd566ef20c8df6d813eab1c4273ac210744faa49a0338de488c8dfffecdfb6f329f380bd566ef20c8df6d813eab1c42733901f06b798b92a10ed9a9d0bbfd3af173a53b1617da3a4159ca008216cd856b2e0e772b2da75600008001000080010000800000000003000000210750929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac005007c461e5d2107631c5f3b5832b8fbdebfb19704ceeb323c21f40f7a24f43d68ef0cc26b125969390118ace409889785e0ea70ceebb8e1ca892a7a78eaede0f2e296cf435961a8f4ca772b2da756000080010000800200008000000000030000002107736e572900fe1252589a2143c8f3c79f71a0412d2353af755e9701c782694a02390129a5b4915090162d759afd3fe0f93fa3326056d0b4088cb933cae7826cb8d82c772b2da7560000800100008003000080000000000300000000</pre> +** Base64 String: <pre>cHNidP8BAF4CAAAAASd0Srq/MCf+DWzyOpbu4u+xiO9SMBlUWFiD5ptmJLJCAAAAAAD/////AUjmBSoBAAAAIlEgCoy9yG3hzhwPnK6yLW33ztNoP+Qj4F0eQCqHk0HW9vUAAAAAAAEBKwDyBSoBAAAAIlEgWiws9bUs8x+DrS6Npj/wMYPs2PYJx1EK6KSOA5EKB1chFv40kGTJjW4qhT+jybEr2LMEoZwZXGDvp+4jkwRtP6IyGQB3Ky2nVgAAgAEAAIAAAACAAQAAAAAAAAABFyD+NJBkyY1uKoU/o8mxK9izBKGcGVxg76fuI5MEbT+iMgABBSBQkpt0waBJVLeLS2A16XpeB4paDyjsltVHv+6azoA6wAEGbwLAIiBzblcpAP4SUliaIUPI88efcaBBLSNTr3VelwHHgmlKAqwCwCIgYxxfO1gyuPvev7GXBM7rMjwh9A96JPQ9aO8MwmsSWWmsAcAiIET6pJoDON5IjI3//s37bzKfOAvVZu8gyN9tgT6rHEJzrCEHRPqkmgM43kiMjf/+zftvMp84C9Vm7yDI322BPqscQnM5AfBreYuSoQ7ZqdC7/Trxc6U7FhfaOkFZygCCFs2Fay4Odystp1YAAIABAACAAQAAgAAAAAADAAAAIQdQkpt0waBJVLeLS2A16XpeB4paDyjsltVHv+6azoA6wAUAfEYeXSEHYxxfO1gyuPvev7GXBM7rMjwh9A96JPQ9aO8MwmsSWWk5ARis5AmIl4Xg6nDO67jhyokqenjq7eDy4pbPQ1lhqPTKdystp1YAAIABAACAAgAAgAAAAAADAAAAIQdzblcpAP4SUliaIUPI88efcaBBLSNTr3VelwHHgmlKAjkBKaW0kVCQFi11mv0/4Pk/ozJgVtC0CIy5M8rngmy42Cx3Ky2nVgAAgAEAAIADAACAAAAAAAMAAAAA</pre> + +* Case: PSBT with one P2TR script path only input with dummy internal key, scripts, script key derivation paths, merkle root, and script path signatures +** Bytes in Hex: <pre>70736274ff01005e02000000019bd48765230bf9a72e662001f972556e54f0c6f97feb56bcb5600d817f6995260100000000ffffffff0148e6052a0100000022512083698e458c6664e1595d75da2597de1e22ee97d798e706c4c0a4b5a9823cd743000000000001012b00f2052a01000000225120c2247efbfd92ac47f6f40b8d42d169175a19fa9fa10e4a25d7f35eb4dd85b69241142cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d2cd970e15f53fc0c82f950fd560ffa919b76172be017368a89913af074f400b0940bf818d9757d6ffeb538ba057fb4c1fc4e0f5ef186e765beb564791e02af5fd3d5e2551d4e34e33d86f276b82c99c79aed3f0395a081efcd2cc2c65dd7e693d7941144320b0bf16f011b53ea7be615924aa7f27e5d29ad20ea1155d848676c3bad1b2115f2e490af7cc45c4f78511f36057ce5c5a5c56325a29fb44dfc203f356e1f840e1f1ab6fabfa26b236f21833719dc1d428ab768d80f91f9988d8abef47bfb863bb1f2a529f768c15f00ce34ec283cdc07e88f8428be28f6ef64043c32911811a4114fa0f7a3cef3b1d0c0a6ce7d26e17ada0b2e5c92d19efad48b41859cb8a451ca96f7d62059e9497a1a4a267569d9876da60101aff38e3529b9b939ce7f91ae97040ec1f0379206461c83342285423326708ab031f0da4a253ee45aafa5b8c92034d8b605490f8cd13e00f989989b97e215faa36f12dee3693d2daccf3781c1757f66215c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac06f7d62059e9497a1a4a267569d9876da60101aff38e3529b9b939ce7f91ae970115f2e490af7cc45c4f78511f36057ce5c5a5c56325a29fb44dfc203f356e1f823202cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d2acc04215c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac097c6e6fea5ff714ff5724499990810e406e98aa10f5bf7e5f6784bc1d0a9a6ce23204320b0bf16f011b53ea7be615924aa7f27e5d29ad20ea1155d848676c3bad1b2acc06215c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0cd970e15f53fc0c82f950fd560ffa919b76172be017368a89913af074f400b09115f2e490af7cc45c4f78511f36057ce5c5a5c56325a29fb44dfc203f356e1f82320fa0f7a3cef3b1d0c0a6ce7d26e17ada0b2e5c92d19efad48b41859cb8a451ca9acc021162cb13ac68248de806aa6a3659cf3c03eb6821d09c8114a4e868febde865bb6d23901cd970e15f53fc0c82f950fd560ffa919b76172be017368a89913af074f400b09772b2da7560000800100008002000080000000000000000021164320b0bf16f011b53ea7be615924aa7f27e5d29ad20ea1155d848676c3bad1b23901115f2e490af7cc45c4f78511f36057ce5c5a5c56325a29fb44dfc203f356e1f8772b2da75600008001000080010000800000000000000000211650929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac005007c461e5d2116fa0f7a3cef3b1d0c0a6ce7d26e17ada0b2e5c92d19efad48b41859cb8a451ca939016f7d62059e9497a1a4a267569d9876da60101aff38e3529b9b939ce7f91ae970772b2da7560000800100008003000080000000000000000001172050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0011820f0362e2f75a6f420a5bde3eb221d96ae6720cf25f81890c95b1d775acb515e65000105201124da7aec92ccd06c954562647f437b138b95721a84be2bf2276bbddab3e67121071124da7aec92ccd06c954562647f437b138b95721a84be2bf2276bbddab3e6711900772b2da7560000800100008000000080000000000500000000</pre> +** Base64 String: <pre>cHNidP8BAF4CAAAAAZvUh2UjC/mnLmYgAflyVW5U8Mb5f+tWvLVgDYF/aZUmAQAAAAD/////AUjmBSoBAAAAIlEgg2mORYxmZOFZXXXaJZfeHiLul9eY5wbEwKS1qYI810MAAAAAAAEBKwDyBSoBAAAAIlEgwiR++/2SrEf29AuNQtFpF1oZ+p+hDkol1/NetN2FtpJBFCyxOsaCSN6AaqajZZzzwD62gh0JyBFKToaP696GW7bSzZcOFfU/wMgvlQ/VYP+pGbdhcr4Bc2iomROvB09ACwlAv4GNl1fW/+tTi6BX+0wfxOD17xhudlvrVkeR4Cr1/T1eJVHU404z2G8na4LJnHmu0/A5Wgge/NLMLGXdfmk9eUEUQyCwvxbwEbU+p75hWSSqfyfl0prSDqEVXYSGdsO60bIRXy5JCvfMRcT3hRHzYFfOXFpcVjJaKftE38ID81bh+EDh8atvq/omsjbyGDNxncHUKKt2jYD5H5mI2KvvR7+4Y7sfKlKfdowV8AzjTsKDzcB+iPhCi+KPbvZAQ8MpEYEaQRT6D3o87zsdDAps59JuF62gsuXJLRnvrUi0GFnLikUcqW99YgWelJehpKJnVp2YdtpgEBr/OONSm5uTnOf5GulwQOwfA3kgZGHIM0IoVCMyZwirAx8NpKJT7kWq+luMkgNNi2BUkPjNE+APmJmJuX4hX6o28S3uNpPS2szzeBwXV/ZiFcFQkpt0waBJVLeLS2A16XpeB4paDyjsltVHv+6azoA6wG99YgWelJehpKJnVp2YdtpgEBr/OONSm5uTnOf5GulwEV8uSQr3zEXE94UR82BXzlxaXFYyWin7RN/CA/NW4fgjICyxOsaCSN6AaqajZZzzwD62gh0JyBFKToaP696GW7bSrMBCFcFQkpt0waBJVLeLS2A16XpeB4paDyjsltVHv+6azoA6wJfG5v6l/3FP9XJEmZkIEOQG6YqhD1v35fZ4S8HQqabOIyBDILC/FvARtT6nvmFZJKp/J+XSmtIOoRVdhIZ2w7rRsqzAYhXBUJKbdMGgSVS3i0tgNel6XgeKWg8o7JbVR7/ums6AOsDNlw4V9T/AyC+VD9Vg/6kZt2FyvgFzaKiZE68HT0ALCRFfLkkK98xFxPeFEfNgV85cWlxWMlop+0TfwgPzVuH4IyD6D3o87zsdDAps59JuF62gsuXJLRnvrUi0GFnLikUcqazAIRYssTrGgkjegGqmo2Wc88A+toIdCcgRSk6Gj+vehlu20jkBzZcOFfU/wMgvlQ/VYP+pGbdhcr4Bc2iomROvB09ACwl3Ky2nVgAAgAEAAIACAACAAAAAAAAAAAAhFkMgsL8W8BG1Pqe+YVkkqn8n5dKa0g6hFV2EhnbDutGyOQERXy5JCvfMRcT3hRHzYFfOXFpcVjJaKftE38ID81bh+HcrLadWAACAAQAAgAEAAIAAAAAAAAAAACEWUJKbdMGgSVS3i0tgNel6XgeKWg8o7JbVR7/ums6AOsAFAHxGHl0hFvoPejzvOx0MCmzn0m4XraCy5cktGe+tSLQYWcuKRRypOQFvfWIFnpSXoaSiZ1admHbaYBAa/zjjUpubk5zn+RrpcHcrLadWAACAAQAAgAMAAIAAAAAAAAAAAAEXIFCSm3TBoElUt4tLYDXpel4HiloPKOyW1Ue/7prOgDrAARgg8DYuL3Wm9CClvePrIh2WrmcgzyX4GJDJWx13WstRXmUAAQUgESTaeuySzNBslUViZH9DexOLlXIahL4r8idrvdqz5nEhBxEk2nrskszQbJVFYmR/Q3sTi5VyGoS+K/Ina73as+ZxGQB3Ky2nVgAAgAEAAIAAAACAAAAAAAUAAAAA</pre> + +==Rationale== + +<references/> + +==Reference implementation== + +The reference implementation of the PSBT format is available at https://github.com/achow101/bitcoin/tree/taproot-psbt. + +==Acknowledgements== + +TBD diff --git a/bip-0380.mediawiki b/bip-0380.mediawiki new file mode 100644 index 0000000..f870734 --- /dev/null +++ b/bip-0380.mediawiki @@ -0,0 +1,277 @@ +<pre> + BIP: 380 + Layer: Applications + Title: Output Script Descriptors General Operation + Author: Pieter Wuille <pieter@wuille.net> + Andrew Chow <andrew@achow101.com> + 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 +</pre> + +==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 <tt>SCRIPT</tt>. +This expression may be followed by <tt>#CHECKSUM</tt>, where <tt>CHECKSUM</tt> is an 8 character alphanumeric descriptor checksum. + +===Script Expressions=== + +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. +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 <tt>KEY</tt>). +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 <tt>[</tt> +** 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 closing bracket <tt>]</tt> +* 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 <tt>02</tt> or <tt>03</tt> representing a compressed public key +*** 130 hex character string beginning with <tt>04</tt> representing an uncompressed public key +** 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. + +If the <tt>KEY</tt> 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 <tt>/*</tt> or <tt>/*'</tt>, 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 <tt>h</tt> may be replaced with alternative hardened indicators of <tt>H</tt> or <tt>'</tt>. + +====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: +<pre> +0123456789()[],'/*abcdefgh@:$%{} +IJKLMNOPQRSTUVWXYZ&+-.;<=>?!^_|~ +ijklmnopqrstuvwxyzABCDEFGH`#"\<space> +</pre> +Note that <tt><space></tt> 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 (<tt>#</tt>) 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 <tt>0123456789()[],'/*abcdefgh@:$%{}</tt> for another in that set always counts as 1 symbol error. +*** Note that hex encoded keys are covered by these characters. Extended keys (<tt>xpub</tt> and <tt>xprv</tt>) use other characters too, but also have their own checksum mechanism. +*** <tt>SCRIPT</tt> 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 2<super>40</super> of being undetected. + +The checksum itself uses the same character set as bech32: <tt>qpzry9x8gf2tvdw0s3jn54khce6mua7l</tt> + +Valid descriptor strings with a checksum must pass the criteria for validity specified by the Python3 code snippet below. +The function <tt>descsum_check</tt> must return true when its argument <tt>s</tt> is a descriptor consisting in the form <tt>SCRIPT#CHECKSUM</tt>. + +<pre> +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 +</pre> + +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: + +<pre> +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)) + +</pre> + +==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 Implementation== + +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 +| <tt>SCRIPT</tt> +| 380 +|- +| Key +| <tt>KEY</tt> +| 380 +|- +| Tree +| <tt>TREE</tt> +| [[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 +|- +| <tt>pk(KEY)</tt> +| [[bip-0381.mediawiki|381]] +|- +| <tt>pkh(KEY)</tt> +| [[bip-0381.mediawiki|381]] +|- +| <tt>sh(SCRIPT)</tt> +| [[bip-0381.mediawiki|381]] +|- +| <tt>wpkh(KEY)</tt> +| [[bip-0382.mediawiki|382]] +|- +| <tt>wsh(SCRIPT)</tt> +| [[bip-0382.mediawiki|382]] +|- +| <tt>multi(NUM, KEY, ..., KEY)</tt> +| [[bip-0383.mediawiki|383]] +|- +| <tt>sortedmulti(NUM, KEY, ..., KEY)</tt> +| [[bip-0383.mediawiki|383]] +|- +| <tt>combo(KEY)</tt> +| [[bip-0384.mediawiki|384]] +|- +| <tt>raw(HEX)</tt> +| [[bip-0385.mediawiki|385]] +|- +| <tt>addr(ADDR)</tt> +| [[bip-0385.mediawiki|385]] +|- +| <tt>tr(KEY)</tt>, <tt>tr(KEY, TREE)</tt> +| [[bip-0386.mediawiki|386]] +|} diff --git a/bip-0381.mediawiki b/bip-0381.mediawiki new file mode 100644 index 0000000..f439597 --- /dev/null +++ b/bip-0381.mediawiki @@ -0,0 +1,83 @@ +<pre> + BIP: 381 + Layer: Applications + Title: Non-Segwit Output Script Descriptors + Author: Pieter Wuille <pieter@wuille.net> + Andrew Chow <andrew@achow101.com> + 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 +</pre> + +==Abstract== + +This document specifies <tt>pk()</tt>, <tt>pkh()</tt>, and <tt>sh()</tt> output script descriptors. +<tt>pk()</tt> descriptors take a key and produces a P2PK output script. +<tt>pkh()</tt> descriptors take a key and produces a P2PKH output script. +<tt>sh()</tt> 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: <tt>pk()</tt>, <tt>pkh()</tt>, and <tt>sh()</tt>. + +===<tt>pk()</tt>=== + +The <tt>pk(KEY)</tt> 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: +<pre> +<KEY> OP_CHECKSIG +</pre> + +===<tt>pkh()</tt>=== + +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. +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: +<pre> +OP_DUP OP_HASH160 <KEY_hash160> OP_EQUALVERIFY OP_CHECKSIG +</pre> + +===<tt>sh()</tt>=== + +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. +This redeemScript is the output script produced by the <tt>SCRIPT</tt> argument to <tt>sh()</tt>. + +The output script produced is: +<pre> +OP_HASH160 <SCRIPT_hash160> OP_EQUAL +</pre> + +==Test Vectors== + +TBD + +==Backwards Compatibility== + +<tt>pk()</tt>, <tt>pkh()</tt>, and <tt>sh()</tt> 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 Implementation== + +<tt>pk()</tt>, <tt>pkh()</tt>, and <tt>sh()</tt> 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 0000000..768079e --- /dev/null +++ b/bip-0382.mediawiki @@ -0,0 +1,70 @@ +<pre> + BIP: 382 + Layer: Applications + Title: Segwit Output Script Descriptors + Author: Pieter Wuille <pieter@wuille.net> + Andrew Chow <andrew@achow101.com> + 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 +</pre> + +==Abstract== + +This document specifies <tt>wpkh()</tt>, and <tt>wsh()</tt> output script descriptors. +<tt>wpkh()</tt> descriptors take a key and produces a P2WPKH output script. +<tt>wsh()</tt> 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: <tt>wpkh()</tt>, and <tt>wsh()</tt>. + +===<tt>wpkh()</tt>=== + +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/has compressed public keys can be contained in a <tt>wpkh()</tt> expression. + +The output script produced is: +<pre> +OP_0 <KEY_hash160> +</pre> + +===<tt>wsh()</tt>=== + +The <tt>wsh(SCRIPT)</tt> expression can be used as a top level expression, or inside of a <tt>sh()</tt> descriptor. +It takes a single script expression as an argument and produces a P2WSH output script. +<tt>wsh()</tt> 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 <tt>SCRIPT</tt> argument to <tt>wsh()</tt>. +Any key expression found in any script expression contained by a <tt>wsh()</tt> expression must only produce compressed public keys. + +The output script produced is: +<pre> +OP_0 <SCRIPT_sha256> +</pre> + +==Test Vectors== + +TBD + +==Backwards Compatibility== + +<tt>wpkh()</tt>, and <tt>wsh()</tt> 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 Implementation== + +<tt>wpkh()</tt>, and <tt>wsh()</tt> 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 0000000..92e86e3 --- /dev/null +++ b/bip-0383.mediawiki @@ -0,0 +1,78 @@ +<pre> + BIP: 383 + Layer: Applications + Title: Multisig Output Script Descriptors + Author: Pieter Wuille <pieter@wuille.net> + Andrew Chow <andrew@achow101.com> + 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 +</pre> + +==Abstract== + +This document specifies <tt>multi()</tt>, and <tt>sortedmulti()</tt> output script descriptors. +Both functions take a threshold and one or more public keys and produce a multisig output script. +<tt>multi()</tt> specifies the public keys in the output script in the order given in the descriptor while <tt>sortedmulti()</tt> 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: <tt>multi()</tt>, and <tt>sortedmulti()</tt>. +Both expressions produce the scripts of the same template and take the same arguments. +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>. + +<tt>multi()</tt> and <tt>sortedmulti()</tt> expressions can be used as a top level expression, or inside of either a <tt>sh()</tt> or <tt>wsh()</tt> 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 <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, 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 <tt>k</tt>. If <tt>k</tt> is less than or equal to 16: +<pre> +OP_k KEY_1 KEY_2 ... KEY_n OP_CHECKMULTISIG +</pre> + +if <tt>k</tt> is greater than 16: +<pre> +k KEY_1 KEY_2 ... KEY_n OP_CHECKMULTISIG +</pre> + +===<tt>sortedmulti()</tt>=== + +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. + +===Multiple Extended Keys</tt>=== + +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. +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== + +<tt>multi()</tt>, and <tt>sortedmulti()</tt> 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 Implementation== + +<tt>multi()</tt>, and <tt>sortedmulti()</tt> 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 0000000..e735d74 --- /dev/null +++ b/bip-0384.mediawiki @@ -0,0 +1,48 @@ +<pre> + BIP: 384 + Layer: Applications + Title: combo() Output Script Descriptors + Author: Pieter Wuille <pieter@wuille.net> + Andrew Chow <andrew@achow101.com> + 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 +</pre> + +==Abstract== + +This document specifies <tt>combo()</tt> 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: <tt>combo(KEY)</tt>. +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 <tt>combo()</tt> expression always produces a P2PK and P2PKH script, the same as putting the key in both a <tt>pk()</tt> and a <tt>pkh()</tt> 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 <tt>wpkh()</tt> and <tt>sh(wpkh())</tt> expression. + +==Test Vectors== + +TBD + +==Backwards Compatibility== + +<tt>combo()</tt> 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 Implementation== + +<tt>combo()</tt> 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 0000000..5c46d75 --- /dev/null +++ b/bip-0385.mediawiki @@ -0,0 +1,57 @@ +<pre> + BIP: 385 + Layer: Applications + Title: raw() and addr() Output Script Descriptors + Author: Pieter Wuille <pieter@wuille.net> + Andrew Chow <andrew@achow101.com> + 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 +</pre> + +==Abstract== + +This document specifies <tt>raw()</tt> and <tt>addr()</tt> output script descriptors. +<tt>raw()</tt> encapsulates a raw script as a descriptor. +<tt>addr()</tt> 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: <tt>raw()</tt> and <tt>addr()</tt>. + +===<tt>raw()</tt>=== + +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. +The output script produced by this descriptor is the script represented by <tt>HEX</tt>. + +===<tt>addr()</tt>=== + +The <tt>addr(ADDR)</tt> 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 <tt>ADDR</tt>. + +==Test Vectors== + +TBD + +==Backwards Compatibility== + +<tt>raw()</tt> and <tt>addr()</tt> 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 Implementation== + +<tt>raw()</tt> and <tt>addr()</tt> 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 0000000..d90e801 --- /dev/null +++ b/bip-0386.mediawiki @@ -0,0 +1,101 @@ +<pre> + BIP: 386 + Layer: Applications + Title: tr() Output Script Descriptors + Author: Pieter Wuille <pieter@wuille.net> + Andrew Chow <andrew@achow101.com> + 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 +</pre> + +==Abstract== + +This document specifies <tt>tr()</tt> output script descriptors. +<tt>tr()</tt> 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: <tt>tr()</tt>. +A new expression is defined: Tree Expressions + +===Tree Expression=== + +A Tree Expression (denoted <tt>TREE</tt>) 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 <tt>{</tt> +** A Tree Expression +** A comma <tt>,</tt> +** A Tree Expression +** A closing brace <tt>}</tt> + +===<tt>tr()</tt>=== + +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. +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(hash<sub>TapTweak</sub>(bytes(P)))G''." + +<pre> +internal_key: lift_x(KEY) +32_byte_output_key: internal_key + int(HashTapTweak(bytes(internal_key)))G +scriptPubKey: OP_1 <32_byte_output_key> +</pre> + +<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. +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. + +<pre> +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> +</pre> + +===Modified Key Expression=== + +Key Expressions within a <tt>tr()</tt> 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 <tt>tr()</tt> descriptor: + +* A 64 hex character string representing an x-only public key + +==Test Vectors== + +TBD + +==Backwards Compatibility== + +<tt>tr()</tt> 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 <tt>pk()</tt>. +However there will be future BIPs that specify script expressions that can be used in tree expressions. + +==Reference Implementation== + +<tt>tr()</tt> descriptors have been implemented in Bitcoin Core since version 22.0. |
