diff --git a/.typos.toml b/.typos.toml index 38ee447461..e30e9e6bd4 100644 --- a/.typos.toml +++ b/.typos.toml @@ -15,6 +15,8 @@ extend-ignore-re = [ "ser.*", "prefix.*", "value: .*", + "pqNTRUsign", + "Strnad", ] [default.extend-words] diff --git a/README.mediawiki b/README.mediawiki index f8ce4228fe..3bef72ca10 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -1240,6 +1240,13 @@ users (see also: [https://en.bitcoin.it/wiki/Economic_majority economic majority | Matt Corallo, Bastien Teinturier | Specification | Complete +|- +| [[bip-0360.mediawiki|360]] +| Consensus (soft fork) +| Pay-to-Merkle-Root (P2MR) +| Hunter Beast, Ethan Heilman, Isabel Foxen Duke +| Specification +| Draft |- style="background-color: #cfffcf" | [[bip-0370.mediawiki|370]] | Applications diff --git a/bip-0360.mediawiki b/bip-0360.mediawiki new file mode 100644 index 0000000000..7a3f00447d --- /dev/null +++ b/bip-0360.mediawiki @@ -0,0 +1,430 @@ +
+  BIP: 360
+  Layer: Consensus (soft fork)
+  Title: Pay-to-Merkle-Root (P2MR)
+  Authors: Hunter Beast 
+           Ethan Heilman 
+           Isabel Foxen Duke 
+  Status: Draft
+  Type: Specification
+  Assigned: 2024-12-18
+  License: BSD-3-Clause
+  Version: 0.11.0
+  Requires: 340, 341, 342
+
+ +==Introduction== + +===Abstract=== + +This document proposes a new output type: Pay-to-Merkle-Root (P2MR), via a soft fork. P2MR outputs operate with nearly the same functionality as P2TR (Pay-to-Taproot) outputs, but with the key path spend removed. + +Through this modification, P2MR outputs allow developers to use script trees and tapscript in a manner that is: + +# resistant to long exposure attacks by Cryptographically Relevant Quantum Computers (CRQCs), and +# resistant to future cryptanalytic approaches that may compromise the elliptic curve cryptography (ECC) used by Bitcoin. + +It is worth noting that proposed P2MR outputs are only resistant to "long exposure attacks" on elliptic curve cryptography; that is, attacks on keys exposed for time periods longer than needed to confirm a spending transaction. + +Protection against more sophisticated quantum attacks, including protection against private key recovery from public keys exposed in the mempool while a transaction is waiting to be confirmed (a.k.a. "short exposure attacks"), may require the introduction of post-quantum signatures in Bitcoin. We believe it's worth considering this path in the future and intend to offer a separate proposal for this purpose upon further research. + +This document additionally defines "long exposure" and "short exposure" attacks, and other new terminology in the Glossary. + +===Copyright=== + +This document is licensed under the 3-clause BSD license. + +===Motivation=== + +The primary threat to Bitcoin from Cryptographically Relevant Quantum Computers (CRQCs) is their potential to break the key cryptographic assumption which secures the digital signatures used in Bitcoin.A Cryptographically Relevant Quantum Computer is an ''object'' which is only loosely defined by ''characteristics'' in quantum physics as of today. It could be understood in the context of this BIP and in Bitcoin that it's a ''hardware-agnostic'' computer supposed to have the architecture to keep ''coherent'' a sufficient number of logical qubits to be able to run Shor's algorithm in an efficient fashion. More specifically, [https://arxiv.org/pdf/quant-ph/0301141 Shor's algorithm] enables a CRQC to solve the Discrete Logarithm Problem (DLP) exponentially faster than classical methods.Shor's algorithm is believed to need 10^8 operations to break a 256-bit elliptic curve public key. This allows the derivation of private keys from public keys — a process referred to here as quantum key recovery.Meaning, deriving private keys from public keys via Shor's algorithm While it is unclear when or if CRQCs will become viable in the future, we propose the addition of a quantum-resistant, [[#script-tree-output-type|script tree output type]] for those interested in this level of protection. + +While some may balk at the potential threat of quantum computers to Bitcoin given their limited functionality to date, some others — including governments, corporations and some existing and potential Bitcoin users — are concerned about their potential for advancement. The Commercial National Security Algorithm Suite (CNSA) 2.0, for instance, has mandated software and networking equipment to be upgraded to post-quantum schemes by 2030, with browsers and operating systems fully upgraded by 2033. Additionally, according to NIST IR 8547, Elliptic Curve Cryptography (ECC) is planned to be disallowed within the US federal government after 2035 (with an exception made for hybrid cryptography, or the use of ECC and post-quantum algorithms together). These kinds of mandates have triggered concern by some ECC users, including some Bitcoin users who prefer to be prepared out of an abundance of caution. + +In the most optimistic case, wherein quantum computers never pose a significant risk to ECC, we understand that the possibility of quantum advancement alone may be influencing adoption and broad confidence in the Bitcoin network. In other words, we believe users' fear of quantum computers may be worth addressing regardless of CRQC viability. Given these concerns, we think it's worth considering simple low risk changes that create options for using Bitcoin in a quantum-resistant way. + +As a conservative first step in this effort, we propose Pay-to-Merkle-Root (P2MR), a script tree output that can be used in a quantum resistant manner. + +===Long Exposure vs Short Exposure Attacks=== + +For clarity, this proposal specifically mitigates the risk of long exposure attacks on outputs that support tapscript and script trees. While some other Bitcoin output types, such as P2SH, are safe against long exposure attacks, taproot is not and taproot is the only currently activated output type that supports tapscript and script trees. + +A long exposure attack is an attack performed on exposed blockchain data, such as exposed public keys, or the scripts of spent outputs. These are likely to be the earliest quantum attacks made possible on Bitcoin, because attackers will have ample time — as much time as vulnerable keys are exposed — to carry out quantum key recovery. + +Short exposure attacks, however, require faster quantum computers, because they must occur within the relatively short time that a transaction is unconfirmed in the mempool. + +Bitcoin outputs are generally vulnerable to short exposure attacks, as most Bitcoin transactions require revealing the associated public key when spending. Full protection of outputs from short exposure attacks may require the use of post-quantum signature schemes. + +Since long exposure attacks on public keys are likely to be the first quantum-enabled threat to Bitcoin, we propose a script tree output that is resistant to long exposure attacks as a first step in hardening Bitcoin against the potential threat of quantum computers. + +The following list of output types describes their long exposure attack vulnerability: + +{| class="wikitable" +|- +! Type +! Vulnerable +! Prefix +! Example +|- +| P2PK +| Yes +| Varies +| 02103203b768951584fe9af6d9d9e6ff26a5f76e453212f19ba163774182ab8057f3eac +|- +| P2PKH +| No* +| 1 +| 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa +|- +| P2MS +| Yes +| Varies +| 52410496ec45f878b62c46c4be8e336dff7cc58df9b502178cc240e... +|- +| P2SH +| No* +| 3 +| 3FkhZo7sGNue153xhgqPBcUaBsYvJW6tTx +|- +| P2WPKH +| No* +| bc1q +| bc1qsnh5ktku9ztqeqfr89yrqjd05eh58nah884mku +|- +| P2WSH +| No* +| bc1q +| bc1qvhu3557twysq2ldn6dut6rmaj3qk04p60h9l79wk4lzgy0ca8mfsnffz65 +|- +| P2TR +| Yes +| bc1p +| bc1p92aslsnseq786wxfk3ekra90ds9ku47qttupfjsqmmj4z82xdq4q3rr58u +|- +| P2MR +| No* +| bc1z +| bc1zzmv50jjgxxhww6ve4g5zpewrkjqhr06fyujpm20tuezdlxmfphcqfc80ve +|} + +The following output types are fundamentally vulnerable to long exposure attacks: + +* P2PK outputs (e.g. Satoshi's coins, CPU miners) +* Reused outputs* +* Taproot outputs (starts with bc1p) + +* Funds in P2PKH, P2SH, P2WPKH, P2WSH, and P2MR outputs can become vulnerable to long exposure quantum attacks anytime their script reveals a public key. + +Note: Extended public keys, commonly known as "xpubs," and wallet descriptors also reveal quantum vulnerable public key information. For further clarification on quantum attack vectors, please refer to the [[#Glossary|Glossary of Terms]]. + +==Design== + +Pay-to-Merkle-Root (P2MR) is a proposed new output type that commits to the root of a script tree. It operates with nearly the same functionality as P2TR (Pay-to-Taproot) outputs, but with the quantum vulnerable key path spend removed. + +In other words, P2MR outputs commit to the Merkle root of a script tree without committing to an internal key. The script(s) being committed to, however, may contain a key or key-hash. + +This output type is designed to offer users protection against long exposure quantum attacks as well as a practical output type with which post-quantum signatures may be used if such signatures are adopted in the future. + +Since P2MR outputs have no key path spend, they omit the Taproot internal key. Instead, a P2MR output includes the 32-byte root of the script tree as defined in [[bip-0341.mediawiki|BIP 341]] hashed with the tag "TapBranch" as shown below. + +[[File:bip-0360/media/merkletree.png|thumb|Construction of P2MR script tree root, scriptPubkey, and Witness]] + +To construct a P2MR output, we follow the process outlined in [[bip-0341.mediawiki|BIP 341]] to compute the final tapbranch hash, which is the merkle root of the script leaves; however, instead of tweaking the internal key with the root of the Merkle tree (as is the case with P2TR outputs), P2MR outputs commit only to final tapbranch hash, which is tagged, "TapBranch". + + +D = tagged_hash("TapLeaf", bytes([leaf_version]) + ser_script(script)) +CD = tagged_hash("TapBranch", C + D) +CDE = tagged_hash("TapBranch", CD + E) +ABCDE = tagged_hash("TapBranch", AB + CDE) + + +A P2MR input witness provides the following: + + +initial stack element 0, +..., +initial stack element N, +leaf script, +control block = [control byte, 32*m byte Merkle path] # m is the depth of the script in the Merkle tree + + +The initial stack elements of P2MR follow the same rules as P2TR script path spends. +That is, they place elements on the stack to be evaluated by the leaf script. + +The control block is a ''1 + 32 * m'' byte array, where the first byte is the control byte and the next ''32 * m'' bytes are the Merkle path to the leaf script. The control byte is the same as the control byte in a P2TR control block, including the 7 bits which are used to specify the leaf version. The parity bit of the control byte is always 1, since P2MR does not have a key path spend. Unlike P2TR, we omit the public key from the control block as it is not needed in P2MR. We maintain support for the optional annex in the witness (see Specification section below for more details). + +==Rationale== + +Design of the P2MR output type is guided by the following intentions: + +1. Minimize changes to the network. We should reuse existing Bitcoin code and preserve existing software behavior, workflows, user expectations and compatibility whenever possible. + +P2MR leverages the battle tested P2TR, tapleaf and tapscript code already in Bitcoin, reducing the implementation burden on wallets, exchanges, and libraries that can reuse code they already have. This approach reduces complexity and minimizes implementation risks. + +2. Create the safest possible path for the addition of post-quantum signature integrations, in the event that they are used in the future. + +Importantly, we are proposing a script tree output, i.e. an output type that supports tapscript, that is resistant to long exposure attacks. While some existing output types are already resistant to long exposure attacks (e.g. P2WSH), no such output type supports tapscript — a feature that may be required for practical implementation of post-quantum signature opcodes. + +P2WSH, for instance, does not support tapscript and as such does not support the OP_SUCCESSx opcode update path that will be critical for the integration of post-quantum OP_CHECKSIG opcodes into Bitcoin.OP_SUCCESSx is a mechanism to upgrade tapscript + +3. Facilitate gradual integration of quantum resistant features that can be carried out iteratively as quantum computers evolve. This approach encourages responsiveness to the current threat-level, while avoiding heavy-handedness in our reactions to a potential threat. + +We designed P2MR with an eye towards integrating post-quantum signatures in the future, without proposing more complex changes while CRQCs are still in their infancy. + +===P2MR Trade-Offs=== + +While P2TR outputs (and the use of key path spend) will remain an option for folks wishing to use them, we aim to be clear about the tradeoffs of using P2MR outputs, which disable the key path spend for the benefit of quantum resistance. + +The witness to a P2MR spend is always larger than the witness to a P2TR key path spend. This is because a P2TR key path spend requires only a Schnorr signature in the witness. For P2MR, the witness must include the chosen leaf script, the initial stack, and a control block consisting of the control byte and Merkle path (if any). + +That said, the witness to a P2MR spend will always be smaller than the witness to an equivalent P2TR script path spend, because there is no longer any internal key in P2MR that must be revealed in the control block. For a more complete comparison of output type transaction sizes, the "Transaction Size and Fees" section may be reviewed later in this proposal. + +Additionally, there is a privacy tradeoff when comparing P2MR and P2TR, which is that users reveal they are spending to a script tree whenever they are using P2MR outputs, since P2MR outputs can only be spent via script path spend. In P2TR when you spend an output as a key path spend, you don't reveal if you have any script path spends. This trade-off only exists when comparing P2TR key path spends to P2MR script path spends; P2TR and P2MR provide the same level of privacy when both are script path spends. + +'''Note:''' P2MR and P2TR both provide greater script privacy than P2SH [[bip-0016.mediawiki|BIP 16]] because unused script paths are not revealed. + +==Specification== + +We define the Pay-to-Merkle-Root (P2MR) output structure as follows: + +A P2MR output is similar to a P2TR output (as defined in [[bip-0341.mediawiki|BIP 341]]); however, unlike P2TR outputs, we disable the key path spend for the benefit of quantum resistance by omitting the internal key and the tap tweak step. +A P2MR output is then a SegWit version 2 byte followed by the Merkle root of the script tree as the witness program. + + +===Address Format=== + +P2MR outputs use SegWit version 2, resulting in mainnet addresses that start with bc1z, following [[bip-0173.mediawiki|BIP 173]]. Bech32m encoding maps version 2 to the prefix z. + +Example P2MR address: + + +bc1zzmv50jjgxxhww6ve4g5zpewrkjqhr06fyujpm20tuezdlxmfphcqfc80ve + + +This commits to a 32-byte script tree Merkle root. + +===ScriptPubKey=== + +The scriptPubKey for a P2MR output is: + + +OP_2 OP_PUSHBYTES_32 + + +Where: +* OP_2 indicates SegWit version 2. +* is the 32-byte Merkle root of the script tree. + +===Script Validation=== + +A P2MR output is a native SegWit output (see [[bip-0141.mediawiki|BIP 141]]) with version 2 and a 32-byte witness program. For the sake of comparison, we have — as much as possible — copied the language verbatim from the script validation section of [[bip-0341.mediawiki|BIP 341]]. + +* Let ''q'' be the 32-byte array containing the witness program (the second push in the scriptPubKey) which represents the Merkle root of the script tree. +* Fail if the witness stack does not have two or more elements. +* Fail if the witness stack has exactly two elements and the first byte of the last element is 0x50. +* If there are at least three witness elements, and the first byte of the last element is 0x50, this last element is called ''annex a'' and is removed from the witness stack. The annex (or the lack thereof) is always covered by the signature and contributes to transaction weight, but is otherwise ignored during P2MR validation. +* There must be at least two witness elements left. +** Call the second-to-last stack element ''s'', the script (as defined in [[bip-0341.mediawiki|BIP 341]]). +** The last stack element is called the control block ''c'', and must have length ''1 + 32 * m'', for a value of ''m'' that is an integer between 0 and 128, inclusive. Fail if it does not have such a length. +** Let ''v = c[0] & 0xfe'' be the ''leaf version'' (as defined in [[bip-0341.mediawiki|BIP 341]]). To maintain ''leaf version'' encoding compatibility the last bit of c[0] is unused and must be 1.Why set the last bit of c[0] to one? Consider a faulty implementation that deserializes the ''leaf version'' as c[0] rather than c[0] & 0xfe for both P2TR and P2MR. If they test against P2MR outputs and require that last bit is 1, this deserialization bug will cause an immediate error. +** Let ''k0 = hashTapLeaf(v || compact_size(size of s) || s)''; also call it the ''tapleaf hash''. +** For ''j'' in ''[0,1,...,m-1]'': +*** Let ''ej = c[1+32j:33+32j]''. +*** Let ''kj+1'' depend on whether ''kj < ej'' (lexicographically): +**** If ''kj < ej'': ''kj+1 = hashTapBranch(kj || ej)''. +**** If ''kj ≥ ej'': ''kj+1 = hashTapBranch(ej || kj)''. +** Let ''r = km''. +** If ''q ≠ r'', fail. +** Execute the script, according to the script rules specified in BIP 342, using the witness stack elements excluding the script ''s'', the control block ''c'', and the annex ''a'' if present, as initial stack. This implies that for the future leaf versions (non-''0xC0'') the execution must succeed. + +The steps above follow the script path spend logic from [[bip-0341.mediawiki|BIP 341]] with the following changes: + +* The witness program is the the Merkle root of the script tree and not a tweaked public key. This means that we skip directly to the BIP 341 script path validation. +* We compute the script tree Merkle root ''r'' and compare it directly to the witness program ''q''. +* The control block is ''1 + 32*m'' bytes, instead of ''33 + 32*m'' bytes. + +===Common Signature Message Construction=== + +The [https://learnmeabitcoin.com/technical/upgrades/taproot/#common-signature-message common signature message] construction for P2MR outputs is exactly the same procedure as defined in [[bip-0342.mediawiki#user-content-Common_Signature_Message_Extension|BIP342 Common Signature Message]]. + +=== Compatibility with BIP 141 === + +By adhering to the SegWit transaction structure and versioning, P2MR outputs are compatible with existing transaction processing rules. Nodes that do not recognize SegWit version 2 will treat these outputs as anyone-can-spend but generally will not relay or mine such transactions. + +===Transaction Size and Fees=== + +All P2MR and P2TR outputs are always the same size. P2MR inputs can be slightly larger or smaller than their equivalent P2TR inputs, depending on the use of key path vs script path spend in the case of P2TR. Let's consider the cases. + +====Comparison with P2TR key path spend==== + +A P2MR witness will be larger than a P2TR witness when the P2TR output is spent via the key path spend. A witness to a P2TR key path spend is simply a signature. P2MR quantum resistance comes from removing the P2TR key path spend. Every P2MR spend is a P2TR script path spend and so requires a script, its input stack and a control block. Consequently, P2MR loses this size advantage of P2TR key path spends in order to gain quantum resistance. If the script tree only has a single leaf script, no Merkle path is needed in the control block, giving us a minimal size control block of 1 byte. + +P2MR witness for depth-0 tree (103 bytes): + + +[count] (1 byte), # Number of elements in the witness +[size] signature (1 + 64 bytes = 65 bytes), +leaf script = [size] [OP_PUSHBYTES_32, 32-byte public key, OP_CHECKSIG] (1 + 1 + 32 + 1 bytes = 35 bytes), +control block = [size] [control byte] [merkle path (empty)] (1 + 1 + 0 bytes = 2 bytes) + + +P2TR key path spend witness (66 bytes): + + +[count] (1 byte), # Number of elements in the witness +[size] signature (1 + 64 bytes = 65 bytes) + + +Thus, the P2MR witness would be 103 - 66 = 37 bytes larger than a P2TR key path spend witness. + +If the Merkle tree has more than a single leaf, then the Merkle path must be included in the control block, increasing the size by ''32 * m'' bytes, where m is the depth of the Merkle tree. +While script trees do support leaf scripts of different depths, here we assume the Merkle tree has been constructed such that each leaf is at the same depth. +This would make such witness 37 + 32 * m bytes larger than a P2TR key path spend witness.If ''m >= 8'', then the compact size will use 3 bytes rather than 1 byte + +P2MR witness ''(103 + 32*m bytes)'': + + +[count] (1 byte), # Number of elements in the witness +[size] signature (64 + 1 bytes = 65 bytes), +leaf script = [size] [OP_PUSHBYTES_32, 32-byte public key, OP_CHECKSIG] (34 + 1 bytes = 35 bytes), +control block = [size] [control byte] [Merkle path] (1 + 1 + 32*m = 2 + 32*m bytes) + + +====Comparison with P2TR script path spend==== + +A P2MR witness will be smaller than the witness to an equivalent P2TR script path spend. This is because P2MR does not require inclusion of an internal public key in the control block to unlock and spend an output. For this reason, a P2MR witness will always be 32 bytes smaller than an equivalent P2TR script path spend witness. + +==Performance Impact== + +P2MR is slightly more computationally performant than P2TR script path spends, as the operations to spend a P2MR output is a strict subset of the operations needed to perform a script path spend on a P2TR output. + +==Backward Compatibility== + +Older wallets and nodes that have not been made compatible with SegWit version 2 and P2MR will not understand these outputs. Per [[bip-0350.mediawiki|BIP 350]] older wallets should be able to spend funds to SegWit version 2 outputs. Users should ensure they are using updated wallets and nodes to receive P2MR outputs and validate transactions using P2MR outputs. P2MR is fully compatible with tapscript and existing tapscript programs can be used in P2MR outputs without modification. P2MR can also support future scripts with new leaf versions. + +==Security== + +P2MR outputs provide the same tapscript functionality as P2TR outputs, but with the quantum-vulnerable key path spend removed. The similarity between these output types enables users to easily migrate script trees from P2TR outputs to P2MR outputs for protection against long exposure quantum attacks. Wallets supporting only P2TR key path spends would need to migrate to using script trees. This is a straightforward migration as it only requires moving to a simple OP_CHECKSIG leaf script. + +Protection from long exposure quantum attacks does not depend on the activation of post-quantum signatures in Bitcoin, but requires that users do not expose their public keys to attackers via public key reuse or other unsafe practices. + +P2MR uses a 256-bit hash output, providing 128 bits of collision resistance and 256 bits of preimage resistance. This is the same level of security as P2WSH specified in [[bip-0141.mediawiki|BIP 141]], which also uses a 256-bit hash output. + +P2MR does not, by itself, protect against short exposure quantum attacks, but these attacks can be mitigated by future activation of post-quantum signatures. + +Combined with P2MR, post-quantum signature schemes can provide comprehensive quantum resistance to P2MR outputs, including protection from short exposure attacks. + +That said, protection against long exposure quantum attacks alone should not be underestimated. It's unlikely that early CRQCs will be fast enough to perform short exposure attacks, making preparedness against long exposure attacks more time-critical. + +==Security Considerations for Post-Quantum Signature Schemes== + +While this proposal does not include the introduction of post-quantum signature schemes, we think it's worth commenting on security considerations related to this possibility. + +Quantum-resistant signature algorithms (e.g. ML-DSA or SLH-DSA) offer different levels of protection and should be scrutinized before use. We are currently researching options for the potential proposal of post-quantum signatures into Bitcoin and encourage others to engage in this research as well. + +We also imagine the possibility of introducing multiple post-quantum signatures for redundancy. Balancing the risks of additional complexity with the benefits of signature-type redundancy will be the challenge here. + +==Test Vectors and Reference Code== + +Test vector data for creation of P2MR UTXOs can be found [https://github.com/bitcoin/bips/blob/master/bip-0360/ref-impl/common/tests/data/P2MR_construction.json here]. + +These test vectors build off of the test vectors for [[bip-0341.mediawiki|BIP 341]] (Taproot). One important distinction is that the P2MR test vectors do not include keypath spend scenarios. + +Also included are test vectors in [https://github.com/bitcoin/bips/tree/master/bip-0360/ref-impl/rust rust implementation] and [https://github.com/bitcoin/bips/tree/master/bip-0360/ref-impl/python python implementation]. One of these tests demonstrates a tapscript that requires a secp256k1 signature to spend the P2MR UTXO (modeled after one of the extremely valuable examples provided by [https://learnmeabitcoin.com/technical/upgrades/taproot/#example-3-script-path-spend-signature this Taproot script path spend example]. Similar to BIP 341 test vectors, all signatures are created with an all-zero (0x0000...0000) [[bip-0340.mediawiki|BIP 340]] auxiliary randomness array. + +==Related Work== + +Below we attempt to summarize some of the ideas discussed on the Bitcoin Development Mailing List that relate to P2MR. + +The idea of Taproot with key path spend removed has been discussed a number of times in the Bitcoin community. + +For instance, [https://gnusha.org/pi/bitcoindev/CAD5xwhgzR8e5r1e4H-5EH2mSsE1V39dd06+TgYniFnXFSBqLxw@mail.gmail.com/ OP_CAT Makes Bitcoin Quantum Secure] notes that if we disable the key path spend in Taproot and activate OP_CAT [[bip-0347.mediawiki|BIP 347]], we could achieve quantum resistance by using Lamport signatures with OP_CAT. + +Lamport and WOTS (Winternitz One-Time Signatures) built from CAT are quantum resistant, but are one-time signatures — meaning, if you sign twice for the same public key, you risk leaking your private key, which is a significant security concern for everyday users. + +This would require major changes to wallet behavior and would represent a significant security downgrade. Common practices, such as RBF and CPFP, could risk revealing private keys if no stateless signature scheme is used. + +[https://groups.google.com/g/bitcoindev/c/8O857bRSVV8/m/rTrpeFjWDAAJ Trivial QC signatures with clean upgrade path] and [https://groups.google.com/g/bitcoindev/c/oQKezDOc4us/m/T1vSMkZNAAAJ Re: P2QRH / BIP 360 Update] also discuss the possibility of Taproot with key path spend removed. The design of P2MR was partly inspired by these discussions. + +Commit-reveal schemes such as [https://gnusha.org/pi/bitcoindev/1518710367.3550.111.camel@mmci.uni-saarland.de/ Re: Transition to post-quantum (2018)] and [https://groups.google.com/g/bitcoindev/c/LpWOcXMcvk8/m/YEiH-kTHAwAJ Post-Quantum commit / reveal Fawkescoin variant as a soft fork (2025)] have been proposed as a way to create cryptocurrencies without public key cryptography. The ideas in this paper were more recently expanded upon by Tadge Dryja in his "[https://www.youtube.com/watch?v=4bzOwYPf1yo Lifeboat]" proposal, which effectively quantum-proofs Bitcoin transactions through a similar pre-commitment scheme designed for Bitcoin. + +==Other Methods of Addressing Quantum Vulnerabilities for Cryptocurrencies== + +It is worth noting, by way of comparison, that [https://ethresear.ch/t/how-to-hard-fork-to-save-most-users-funds-in-a-quantum-emergency/18901 Vitalik Buterin's proposed solution] to Ethereum's quantum vulnerability is quite different from the approach in this BIP. + +His plan involves a hard fork of the chain, reverting all blocks after some sufficient amount of theft, and using STARKs based on BIP 32 seeds to act as the authoritative secret when signing. We believe rollbacks of any kind are an untenable approach for Bitcoin and would likely be impractical to implement. + +That said, we believe the use of STARKs (which are quantum-resistant) may prove useful as a method of proving access to external private keys, in the event that the community chooses to burn vulnerable coins as proposed by Jameson Lopp and others in [https://qbip.org/ QBIP]. + +Discussions related to the burning of coins, and other attempts to slow a potential supply shock caused by quantum-retrieval of vulnerable coins, are out of scope for this proposal. That said, members of our team have separately proposed [https://github.com/cryptoquick/bips/blob/hourglass/bip-hourglass.mediawiki Hourglass] to address this concern and are continuing research on this subject. + +==Conclusion== + +In this proposal, we adopt a "prepared not scared" approach to the possible advancement of quantum computing and offer Bitcoin users an option for increased protection if they so choose. This BIP does not take a position on any specific quantum computing timeline, but rather proposes a flexible and unobtrusive option for users that wish to mitigate this risk according to their own estimate of the timeline. + +This is an issue that has been discussed with some regularity in [https://bitcointalk.org/index.php?topic=133425.0 Bitcoin forums] since at least 2012, and there is clearly user demand for increased quantum protection. + +==Glossary== + +'''Quantum Key Recovery''' + +The derivation of private keys from public keys in elliptic curve cryptography (ECC), made possible by solving the discrete logarithm problem (DLP). + +Shor's algorithm, developed by Peter Shor in 1994, is a quantum algorithm that efficiently solves the discrete logarithm problem — potentially made possible by the future viability of cryptographically relevant quantum computers (CRQCs). + +'''Long Exposure Attacks''' + +Attempts to derive private keys from public keys that are exposed for an extended period of time; that is, longer than the window of time that a public key is generally exposed in the mempool while waiting to be confirmed. + +Long exposure attacks give attackers an unlimited amount of time to perform quantum key recovery, as long as funds remain in the output. Poor wallet hygiene (e.g. from address reuse) or use of outputs with exposed public keys (e.g. P2TR outputs) increases vulnerability to long exposure attacks. + +'''Short Exposure Attacks''' + +Attempts to derive private keys from public keys during the brief period when funds are unconfirmed in the mempool. These attacks cannot be prevented through wallet hygiene, as revealing a public key is necessary for spending. + +Protection against short exposure attacks may require post-quantum signature schemes; that said, executing these attacks requires faster CRQCs than those capable of executing long exposure attacks and are therefore viewed as lower-risk than long exposure attacks in the nearer term. + + +'''Script Tree Output Type''' + +Script tree output types are a category of output type that support a script tree consisting of leaf scripts. Script tree output types support tapscript and would support any new script language added to bitcoin which is able to be used as a leaf script in a script trees. If Pay-to-Merkle-Root (P2MR) is activated, P2MR would be the second script tree output type in Bitcoin, the other being Pay-to-Taproot (P2TR). + +'''Pay-to-Merkle-Root (P2MR)''' + +A script tree output type, similar to to Pay-to-Taproot (P2TR), but with the quantum-vulnerable key path spend removed. +==Footnotes== + + + +==Changelog== + +To help implementers understand updates to this BIP, we keep a list of substantial changes. + +* __0.11.0__ (2026-02-10) - Rename BIP from Pay-to-Tapscript-Hash (P2TSH) to Pay-to-Merkle-Root (P2MR) +* __0.10.3__ (2026-02-06) - Rename tapscript-native output type to script tree output type. +* __0.10.2__ (2026-01-23) - Fix bug in verification, minor review comments and adopt [[bip-0003.mediawiki|BIP 003]] conventions. +* __0.10.1__ (2026-01-21) - Terminology and clarity improvements, addressed feedback from reviews. +* __0.10.0__ (2025-09-17) - Rewrote BIP for clarity and renamed from P2QRH to P2TSH +* __0.9.0__ (2025-07-20) - Changed the Witness Version from 3 to 2. +* __0.8.0__ (2025-07-07) - P2QRH is now a P2TR with the vulnerable key path spend removed. Number of PQ signature algorithms supported reduced from three to two. PQ signature algorithm support is now added via opcodes or leaf version. +* __0.7.0__ (2025-03-18) - Correct inconsistencies in commitment and attestation structure. Switch from Merkle tree commitment to sorted vector hash commitment. Update descriptor format. +* __0.6.2__ (2025-03-12) - Add verification times for each algorithm. 256 to 128 (NIST V to NIST I). Add key type bitmask. Clarify multisig semantics. +* __0.6.1__ (2025-02-23) - More points of clarification from review. Update dead link. +* __0.6.0__ (2025-01-20) - Remove SQIsign from consideration due to significant performance concerns. Refactor language from long range attack to long exposure so as to not be confused with the language around block re-org attacks. +* __0.5.1__ (2024-12-18) - Assigned BIP number. +* __0.5.0__ (2024-12-13) - Update to use Merkle tree for attestation commitment. Update LR & SR quantum attack scenarios. +* __0.4.0__ (2024-12-01) - Add details on attestation structure and parsing. +* __0.3.0__ (2024-10-21) - Replace XMSS with CRYSTALS-Dilithium due to NIST approval and size constraints. +* __0.2.2__ (2024-09-30) - Refactor the ECC vs PoW section. Swap quitness for attestation. +* __0.2.1__ (2024-09-29) - Update section on PoW to include partial-preimage. +* __0.2.0__ (2024-09-28) - Add Winternitz, XMSS signatures, and security assumption types to PQC table. Omit NIST Level I table. Add spend script specification. Add revealed public key scenario table. +* __0.1.0__ (2024-09-27) - Initial draft proposal + +==Acknowledgements== + +This document is inspired by [[bip-0341.mediawiki|BIP 341]], which introduced the design of the P2TR (Taproot) output type using Schnorr signatures. + +I'm incredibly grateful to Ethan Heilman for joining as co-author and transforming this BIP into something far more congruent with existing Bitcoin design. Additionally, much gratitude to our most recent co-author, Isabel Foxen Duke, for her thoughtful editing and crafting much of the language in this proposal. I am likewise indebted to those on the Anduro Quantum Working Group who took the time to contribute including Jeff Bride, Michael Casey, and notmike. + +Thank you as well to those who took the time to review and contribute, including Jon Atack, Adam Borcany, Ava Chow, Kyle Crews, Pierre-Luc Dallaire-Demers, D++, Mark Erhardt, Jameson Lopp, Antoine Riard, Armin Sabouri, Vojtěch Strnad, Guy Swann, and Joey Yandle. + +Whatever inaccuracies may remain are attributable solely to the authors. diff --git a/bip-0360/media/merkletree.png b/bip-0360/media/merkletree.png new file mode 100644 index 0000000000..0a702a2d9e Binary files /dev/null and b/bip-0360/media/merkletree.png differ diff --git a/bip-0360/media/merkletree.svg b/bip-0360/media/merkletree.svg new file mode 100644 index 0000000000..cb280dc09d --- /dev/null +++ b/bip-0360/media/merkletree.svg @@ -0,0 +1,1902 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + P2MR Witness (input) + + + + + + + + + + + + annex + 50 + + + + Control byte + leaf script + leafscript B + Initial stack + + + + + Merkle path (32*m bytes) + Control block + Witness Program + SegWit version 2 + leaf version + + leaf version + 1 + { + { + P2MR scriptPubKey (output) + How the script tree Merkle root is computed: + + + OP_PUSHNUM2 + script tree Merkle root + + script tree Merkle root + + tagged_hash TapLeaf + + tagged_hash TapBranch + + tagged_hash TapBranch + + tagged_hash TapBranch + + tagged_hash TapBranch + + + + + + + leaf version + + + + + leaf +script B + leaf +script A + + leaf version + + + + + + leaf version + + + + + + leaf version + + + + + + + + + + + + + + + + + tagged_hash TapLeaf + + + tagged_hash TapLeaf + + + tagged_hash TapLeaf + + + + tagged_hash TapLeaf + + + + + + leaf +script D + leaf +script E + leaf +script C + + diff --git a/bip-0360/ref-impl/.gitignore b/bip-0360/ref-impl/.gitignore new file mode 100644 index 0000000000..db5bd6b642 --- /dev/null +++ b/bip-0360/ref-impl/.gitignore @@ -0,0 +1,6 @@ +rust-bitcoin +rust-miniscript +libbitcoinpqc +target +.btcdeb_history +*.swp diff --git a/bip-0360/ref-impl/common/tests/data/p2mr_construction.json b/bip-0360/ref-impl/common/tests/data/p2mr_construction.json new file mode 100644 index 0000000000..f6d76d07ca --- /dev/null +++ b/bip-0360/ref-impl/common/tests/data/p2mr_construction.json @@ -0,0 +1,260 @@ +{ + "version": 1, + "test_vectors": [ + { + "id": "p2tr_using_v2_witness_version_error", + "objective": "Tests that a P2TR v2 scriptPubKey fails with use of witness version 2", + "given": { + "internalPubkey": "d6889cb081036e0faefa3a35157ad71086b123b2b144b649798b494c300a961d", + "scriptTree": null + }, + "intermediary": { + "merkleRoot": null, + "tweak": "b86e7be8f39bab32a6f2c0443abbc210f0edac0e2c53d501b36b64437d9c6c70", + "tweakedPubkey": "53a1f6e454df1aa2776a2814a721372d6258050de330b3c6d10ee8f4e0dda343" + }, + "expected": { + "scriptPubKey": "522053a1f6e454df1aa2776a2814a721372d6258050de330b3c6d10ee8f4e0dda343", + "error": "P2TR requires witness version of 1" + } + }, + { + "id": "p2mr_missing_leaf_script_tree_error", + "objective": "Tests P2MR with missing leaf script tree", + "given": { + "script_tree": "" + }, + "intermediary": { + }, + "expected": { + "error": "P2MR requires a script tree with at least one leaf" + } + }, + { + "id": "p2mr_single_leaf_script_tree", + "objective": "Tests P2MR with single leaf script tree", + "given": { + "scriptTree": { + "id": 0, + "script": "20b617298552a72ade070667e86ca63b8f5789a9fe8731ef91202a91c9f3459007ac", + "asm": "b617298552a72ade070667e86ca63b8f5789a9fe8731ef91202a91c9f3459007 OP_CHECKSIG", + "leafVersion": 192 + } + }, + "intermediary": { + "leafHashes": [ + "c525714a7f49c28aedbbba78c005931a81c234b2f6c99a73e4d06082adc8bf2b" + ], + "merkleRoot": "c525714a7f49c28aedbbba78c005931a81c234b2f6c99a73e4d06082adc8bf2b" + }, + "expected": { + "scriptPubKey": "5220c525714a7f49c28aedbbba78c005931a81c234b2f6c99a73e4d06082adc8bf2b", + "bip350Address": "bc1zc5jhzjnlf8pg4mdmhfuvqpvnr2quyd9j7mye5uly6psg9twghu4ssr0v9k", + "scriptPathControlBlocks": [ + "c1" + ] + } + }, + { + "id": "p2mr_different_version_leaves", + "objective": "Tests P2MR with two script leaves of different versions. TO-DO: currently ignores given leaf version and over-rides. Probably better to throw error", + "given": { + "scriptTree": [ + { + "id": 0, + "script": "20387671353e273264c495656e27e39ba899ea8fee3bb69fb2a680e22093447d48ac", + "asm": "387671353e273264c495656e27e39ba899ea8fee3bb69fb2a680e22093447d48 OP_CHECKSIG", + "leafVersion": 192 + }, + { + "id": 1, + "script": "06424950333431", + "asm": "424950333431", + "description": "just pushes the string 'BIP341' onto the stack", + "leafVersion": 250 + } + ] + }, + "intermediary": { + "leafHashes": [ + "8ad69ec7cf41c2a4001fd1f738bf1e505ce2277acdcaa63fe4765192497f47a7", + "f224a923cd0021ab202ab139cc56802ddb92dcfc172b9212261a539df79a112a" + ], + "merkleRoot": "6c2dc106ab816b73f9d07e3cd1ef2c8c1256f519748e0813e4edd2405d277bef" + }, + "expected": { + "scriptPubKey": "52206c2dc106ab816b73f9d07e3cd1ef2c8c1256f519748e0813e4edd2405d277bef", + "bip350Address": "bc1zdskuzp4ts94h87ws0c7drmev3sf9dagewj8qsylyahfyqhf800hsam4d6e", + "scriptPathControlBlocks": [ + "c1f224a923cd0021ab202ab139cc56802ddb92dcfc172b9212261a539df79a112a", + "c18ad69ec7cf41c2a4001fd1f738bf1e505ce2277acdcaa63fe4765192497f47a7" + ] + } + }, + { + "id": "p2mr_simple_lightning_contract", + "objective": "Tests P2MR with two script leaves that simulate a simple lightning network contract. Reference: https://github.com/bitcoin-core/btcdeb/blob/master/doc/tapscript-example-with-tap.md", + "given": { + "scriptTree": [ + { + "id": 0, + "script": "029000b275209997a497d964fc1a62885b05a51166a65a90df00492c8d7cf61d6accf54803beac", + "asm": "144 OP_CHECKSEQUENCEVERIFY OP_DROP 9997a497d964fc1a62885b05a51166a65a90df00492c8d7cf61d6accf54803be OP_CHECKSIG", + "description": "Alice takes the money after waiting 1 day", + "leafVersion": 192 + }, + { + "id": 1, + "script": "a8206c60f404f8167a38fc70eaf8aa17ac351023bef86bcb9d1086a19afe95bd533388204edfcf9dfe6c0b5c83d1ab3f78d1b39a46ebac6798e08e19761f5ed89ec83c10ac", + "asm": "OP_SHA256 6c60f404f8167a38fc70eaf8aa17ac351023bef86bcb9d1086a19afe95bd5333 OP_EQUALVERIFY 4edfcf9dfe6c0b5c83d1ab3f78d1b39a46ebac6798e08e19761f5ed89ec83c10 OP_CHECKSIG", + "description": "Bob takes the money whenever he wishes to by revealing the preimage_hash", + "leafVersion": 192 + } + ] + }, + "intermediary": { + "leafHashes": [ + "c81451874bd9ebd4b6fd4bba1f84cdfb533c532365d22a0a702205ff658b17c9", + "632c8632b4f29c6291416e23135cf78ecb82e525788ea5ed6483e3c6ce943b42" + ], + "merkleRoot": "41646f8c1fe2a96ddad7f5471bc4fee7da98794ef8c45a4f4fc6a559d60c9f6b" + }, + "expected": { + "scriptPubKey": "522041646f8c1fe2a96ddad7f5471bc4fee7da98794ef8c45a4f4fc6a559d60c9f6b", + "bip350Address": "bc1zg9jxlrqlu25kmkkh74r3h387uldfs72wlrz95n60c6j4n4svna4s4lhfhe", + "scriptPathControlBlocks": [ + "c1c81451874bd9ebd4b6fd4bba1f84cdfb533c532365d22a0a702205ff658b17c9", + "c1632c8632b4f29c6291416e23135cf78ecb82e525788ea5ed6483e3c6ce943b42" + ] + } + }, + { + "id": "p2mr_two_leaf_same_version", + "objective": "Tests P2MR with two script leaves of same version", + "given": { + "scriptTree": [ + { + "id": 0, + "script": "2044b178d64c32c4a05cc4f4d1407268f764c940d20ce97abfd44db5c3592b72fdac", + "asm": "44b178d64c32c4a05cc4f4d1407268f764c940d20ce97abfd44db5c3592b72fd OP_CHECKSIG", + "leafVersion": 192 + }, + { + "id": 1, + "script": "07546170726f6f74", + "asm": "546170726f6f74", + "description": "pushes the string 'Taproot' onto the stack", + "leafVersion": 192 + } + ] + }, + "intermediary": { + "leafHashes": [ + "64512fecdb5afa04f98839b50e6f0cb7b1e539bf6f205f67934083cdcc3c8d89", + "2cb2b90daa543b544161530c925f285b06196940d6085ca9474d41dc3822c5cb" + ], + "merkleRoot": "ab179431c28d3b68fb798957faf5497d69c883c6fb1e1cd9f81483d87bac90cc" + }, + "expected": { + "scriptPubKey": "5220ab179431c28d3b68fb798957faf5497d69c883c6fb1e1cd9f81483d87bac90cc", + "bip350Address": "bc1z4vtegvwz35ak37me39tl4a2f045u3q7xlv0pek0czjpas7avjrxqz20g2y", + "scriptPathControlBlocks": [ + "c12cb2b90daa543b544161530c925f285b06196940d6085ca9474d41dc3822c5cb", + "c164512fecdb5afa04f98839b50e6f0cb7b1e539bf6f205f67934083cdcc3c8d89" + ] + } + }, + { + "id": "p2mr_three_leaf_complex", + "objective": "Tests P2MR with a complex three-leaf script tree structure, demonstrating nested script paths and multiple verification options", + "given": { + "internalPubkey": "e0dfe2300b0dd746a3f8674dfd4525623639042569d829c7f0eed9602d263e6f", + "scriptTree": [ + { + "id": 0, + "script": "2072ea6adcf1d371dea8fba1035a09f3d24ed5a059799bae114084130ee5898e69ac", + "asm": "72ea6adcf1d371dea8fba1035a09f3d24ed5a059799bae114084130ee5898e69 OP_CHECKSIG", + "leafVersion": 192 + }, + [ + { + "id": 1, + "script": "202352d137f2f3ab38d1eaa976758873377fa5ebb817372c71e2c542313d4abda8ac", + "asm": "2352d137f2f3ab38d1eaa976758873377fa5ebb817372c71e2c542313d4abda8 OP_CHECKSIG", + "leafVersion": 192 + }, + { + "id": 2, + "script": "207337c0dd4253cb86f2c43a2351aadd82cccb12a172cd120452b9bb8324f2186aac", + "asm": "7337c0dd4253cb86f2c43a2351aadd82cccb12a172cd120452b9bb8324f2186a OP_CHECKSIG", + "leafVersion": 192 + } + ] + ] + }, + "intermediary": { + "leafHashes": [ + "2645a02e0aac1fe69d69755733a9b7621b694bb5b5cde2bbfc94066ed62b9817", + "ba982a91d4fc552163cb1c0da03676102d5b7a014304c01f0c77b2b8e888de1c", + "9e31407bffa15fefbf5090b149d53959ecdf3f62b1246780238c24501d5ceaf6" + ], + "merkleRoot": "ccbd66c6f7e8fdab47b3a486f59d28262be857f30d4773f2d5ea47f7761ce0e2" + }, + "expected": { + "scriptPubKey": "5220ccbd66c6f7e8fdab47b3a486f59d28262be857f30d4773f2d5ea47f7761ce0e2", + "bip350Address": "bc1zej7kd3hhar76k3an5jr0t8fgyc47s4lnp4rh8uk4afrlwasuur3qzgewqq", + "scriptPathControlBlocks": [ + "c1ffe578e9ea769027e4f5a3de40732f75a88a6353a09d767ddeb66accef85e553", + "c1ba982a91d4fc552163cb1c0da03676102d5b7a014304c01f0c77b2b8e888de1c2645a02e0aac1fe69d69755733a9b7621b694bb5b5cde2bbfc94066ed62b9817", + "c19e31407bffa15fefbf5090b149d53959ecdf3f62b1246780238c24501d5ceaf62645a02e0aac1fe69d69755733a9b7621b694bb5b5cde2bbfc94066ed62b9817" + ] + } + }, + { + "id": "p2mr_three_leaf_alternative", + "objective": "Tests another variant of P2MR with three leaves arranged in a different tree structure, showing alternative script path spending options", + "given": { + "internalPubkey": "55adf4e8967fbd2e29f20ac896e60c3b0f1d5b0efa9d34941b5958c7b0a0312d", + "scriptTree": [ + { + "id": 0, + "script": "2071981521ad9fc9036687364118fb6ccd2035b96a423c59c5430e98310a11abe2ac", + "asm": "71981521ad9fc9036687364118fb6ccd2035b96a423c59c5430e98310a11abe2 OP_CHECKSIG", + "leafVersion": 192 + }, + [ + { + "id": 1, + "script": "20d5094d2dbe9b76e2c245a2b89b6006888952e2faa6a149ae318d69e520617748ac", + "asm": "d5094d2dbe9b76e2c245a2b89b6006888952e2faa6a149ae318d69e520617748 OP_CHECKSIG", + "leafVersion": 192 + }, + { + "id": 2, + "script": "20c440b462ad48c7a77f94cd4532d8f2119dcebbd7c9764557e62726419b08ad4cac", + "asm": "c440b462ad48c7a77f94cd4532d8f2119dcebbd7c9764557e62726419b08ad4c OP_CHECKSIG", + "leafVersion": 192 + } + ] + ] + }, + "intermediary": { + "leafHashes": [ + "f154e8e8e17c31d3462d7132589ed29353c6fafdb884c5a6e04ea938834f0d9d", + "737ed1fe30bc42b8022d717b44f0d93516617af64a64753b7a06bf16b26cd711", + "d7485025fceb78b9ed667db36ed8b8dc7b1f0b307ac167fa516fe4352b9f4ef7" + ], + "merkleRoot": "2f6b2c5397b6d68ca18e09a3f05161668ffe93a988582d55c6f07bd5b3329def" + }, + "expected": { + "scriptPubKey": "52202f6b2c5397b6d68ca18e09a3f05161668ffe93a988582d55c6f07bd5b3329def", + "bip350Address": "bc1z9a4jc5uhkmtgegvwpx3lq5tpv68layaf3pvz64wx7paatvejnhhsv52lcv", + "scriptPathControlBlocks": [ + "c13cd369a528b326bc9d2133cbd2ac21451acb31681a410434672c8e34fe757e91", + "c1737ed1fe30bc42b8022d717b44f0d93516617af64a64753b7a06bf16b26cd711f154e8e8e17c31d3462d7132589ed29353c6fafdb884c5a6e04ea938834f0d9d", + "c1d7485025fceb78b9ed667db36ed8b8dc7b1f0b307ac167fa516fe4352b9f4ef7f154e8e8e17c31d3462d7132589ed29353c6fafdb884c5a6e04ea938834f0d9d" + ] + } + } + ] +} diff --git a/bip-0360/ref-impl/common/tests/data/p2mr_pqc_construction.json b/bip-0360/ref-impl/common/tests/data/p2mr_pqc_construction.json new file mode 100644 index 0000000000..86a7f2fca7 --- /dev/null +++ b/bip-0360/ref-impl/common/tests/data/p2mr_pqc_construction.json @@ -0,0 +1,252 @@ +{ + "version": 1, + "test_vectors": [ + { + "id": "p2mr_missing_leaf_script_tree_error", + "objective": "Tests P2MR with missing leaf script tree", + "given": { + "script_tree": "" + }, + "intermediary": { + }, + "expected": { + "error": "P2MR requires a script tree with at least one leaf" + } + }, + { + "id": "p2mr_single_leaf_script_tree", + "objective": "Tests P2MR with single leaf script tree", + "given": { + "scriptTree": { + "id": 0, + "script": "201f4b1febdc7dfa77c1efacc875b43317b46155e5a564decf475fc369124c5f247f", + "asm": "1f4b1febdc7dfa77c1efacc875b43317b46155e5a564decf475fc369124c5f24 OP_SUBSTR", + "priv_key": "3f0213a51771f25c906cd82c656175e4b2a10e85958039d6e358352a2eb62b791f4b1febdc7dfa77c1efacc875b43317b46155e5a564decf475fc369124c5f24", + "leafVersion": 192 + } + }, + "intermediary": { + "leafHashes": [ + "3bb0db8c6adcd87330a4a8c91be0fe1b23da3c151b6f2fb4f269429c43b8d8bc" + ], + "merkleRoot": "3bb0db8c6adcd87330a4a8c91be0fe1b23da3c151b6f2fb4f269429c43b8d8bc" + }, + "expected": { + "scriptPubKey": "52203bb0db8c6adcd87330a4a8c91be0fe1b23da3c151b6f2fb4f269429c43b8d8bc", + "bip350Address": "bc1z8wcdhrr2mnv8xv9y4ry3hc87rv3a50q4rdhjld8jd9pfcsacmz7qg5szm8", + "scriptPathControlBlocks": [ + "c1" + ] + } + }, + { + "id": "p2mr_different_version_leaves", + "objective": "Tests P2MR with two script leaves of different versions. TO-DO: currently ignores given leaf version and over-rides. Probably better to throw error", + "given": { + "scriptTree": [ + { + "id": 0, + "script": "201f4b1febdc7dfa77c1efacc875b43317b46155e5a564decf475fc369124c5f247f", + "asm": "1f4b1febdc7dfa77c1efacc875b43317b46155e5a564decf475fc369124c5f24 OP_SUBSTR", + "priv_key": "3f0213a51771f25c906cd82c656175e4b2a10e85958039d6e358352a2eb62b791f4b1febdc7dfa77c1efacc875b43317b46155e5a564decf475fc369124c5f24", + "leafVersion": 192 + }, + { + "id": 1, + "script": "06424950333431", + "asm": "424950333431", + "description": "just pushes the string 'BIP341' onto the stack", + "leafVersion": 250 + } + ] + }, + "intermediary": { + "leafHashes": [ + "3bb0db8c6adcd87330a4a8c91be0fe1b23da3c151b6f2fb4f269429c43b8d8bc", + "f224a923cd0021ab202ab139cc56802ddb92dcfc172b9212261a539df79a112a" + ], + "merkleRoot": "1619ce6d22a46dea045c4adf7f5f33d6810d00d0e9c8a4c7ba35db37b915c604" + }, + "expected": { + "scriptPubKey": "52201619ce6d22a46dea045c4adf7f5f33d6810d00d0e9c8a4c7ba35db37b915c604", + "bip350Address": "bc1zzcvuumfz53k75pzuft0h7hen66qs6qxsa8y2f3a6xhdn0wg4cczq0h84sj", + "scriptPathControlBlocks": [ + "c13bb0db8c6adcd87330a4a8c91be0fe1b23da3c151b6f2fb4f269429c43b8d8bc", + "c1f224a923cd0021ab202ab139cc56802ddb92dcfc172b9212261a539df79a112a" + ] + } + }, + { + "id": "p2mr_simple_lightning_contract", + "objective": "Tests P2MR with two script leaves that simulate a simple lightning network contract. Reference: https://github.com/bitcoin-core/btcdeb/blob/master/doc/tapscript-example-with-tap.md", + "given": { + "scriptTree": [ + { + "id": 0, + "script": "029000b275201f4b1febdc7dfa77c1efacc875b43317b46155e5a564decf475fc369124c5f247f", + "asm": "144 OP_CHECKSEQUENCEVERIFY OP_DROP 1f4b1febdc7dfa77c1efacc875b43317b46155e5a564decf475fc369124c5f24 OP_SUBSTR", + "priv_key": "3f0213a51771f25c906cd82c656175e4b2a10e85958039d6e358352a2eb62b791f4b1febdc7dfa77c1efacc875b43317b46155e5a564decf475fc369124c5f24", + "description": "Alice takes the money after waiting 1 day", + "leafVersion": 192 + }, + { + "id": 1, + "script": "a8206c60f404f8167a38fc70eaf8aa17ac351023bef86bcb9d1086a19afe95bd533388204c7f98ab73cc36abeb76d6eace6a9d8b0ff69dfe0f4a17e4f94f0898ec52fadd", + "asm": "OP_SHA256 6c60f404f8167a38fc70eaf8aa17ac351023bef86bcb9d1086a19afe95bd5333 OP_EQUALVERIFY 4c7f98ab73cc36abeb76d6eace6a9d8b0ff69dfe0f4a17e4f94f0898ec52fadd OP_SUBSTR", + "priv_key": "49a4214f386240d97ea68efb4268043fd5a55208dcdac18ce5bd3332b8e488944c7f98ab73cc36abeb76d6eace6a9d8b0ff69dfe0f4a17e4f94f0898ec52fadd", + "description": "Bob takes the money whenever he wishes to by revealing the preimage_hash", + "leafVersion": 192 + } + ] + }, + "intermediary": { + "leafHashes": [ + "cfd5fc07ac39947cba799e14f933f20e7c233dea72dc2792f5547c58cdce743e", + "a9745ac96d4f3702b78751f1e08f3040fbe6347e7b4f520d22d3f907730cbb7e" + ], + "merkleRoot": "2794771cd51f215ba3a19fbcdf08c771edb7de782a0c34457e0e9be5d0e4008f" + }, + "expected": { + "scriptPubKey": "52202794771cd51f215ba3a19fbcdf08c771edb7de782a0c34457e0e9be5d0e4008f", + "bip350Address": "bc1zy728w8x4rus4hgapn77d7zx8w8km0hnc9gxrg3t7p6d7t58yqz8sg0nccq", + "scriptPathControlBlocks": [ + "c1cfd5fc07ac39947cba799e14f933f20e7c233dea72dc2792f5547c58cdce743e", + "c1a9745ac96d4f3702b78751f1e08f3040fbe6347e7b4f520d22d3f907730cbb7e" + ] + } + }, + { + "id": "p2mr_two_leaf_same_version", + "objective": "Tests P2MR with two script leaves of same version", + "given": { + "scriptTree": [ + { + "id": 0, + "script": "20e6b3dad32fc04095a021f5356163cfc14e15f703831e332c56f6b499801f53447f", + "asm": "e6b3dad32fc04095a021f5356163cfc14e15f703831e332c56f6b499801f5344 OP_SUBSTR", + "priv_key": "a695d8a1351774d59ed1b980462c2ab8d58b3b7a48f55b114c6a39980dc1c13ee6b3dad32fc04095a021f5356163cfc14e15f703831e332c56f6b499801f5344", + "leafVersion": 192 + }, + { + "id": 1, + "script": "07546170726f6f74", + "asm": "546170726f6f74", + "description": "pushes the string 'Taproot' onto the stack", + "leafVersion": 192 + } + ] + }, + "intermediary": { + "leafHashes": [ + "9de7eeded7832c28c6f80de76904dd79f98fd302747823b5bc5be440186b0c6d", + "2cb2b90daa543b544161530c925f285b06196940d6085ca9474d41dc3822c5cb" + ], + "merkleRoot": "5112b3edfd2c0b717491e9d4888ed2d5dfeaa25115143540e0a08516b68c008c" + }, + "expected": { + "scriptPubKey": "52205112b3edfd2c0b717491e9d4888ed2d5dfeaa25115143540e0a08516b68c008c", + "bip350Address": "bc1z2yft8m0a9s9hzay3a82g3rkj6h074gj3z52r2s8q5zz3dd5vqzxqngpk2w", + "scriptPathControlBlocks": [ + "c19de7eeded7832c28c6f80de76904dd79f98fd302747823b5bc5be440186b0c6d", + "c12cb2b90daa543b544161530c925f285b06196940d6085ca9474d41dc3822c5cb" + ] + } + }, + { + "id": "p2mr_three_leaf_complex", + "objective": "Tests P2MR with a complex three-leaf script tree structure, demonstrating nested script paths and multiple verification options", + "given": { + "scriptTree": [ + { + "id": 0, + "script": "201d58016252d5a941f84574c4821b5f87e56778b2bbc3b610dfd801fc0250f6cc7f", + "asm": "1d58016252d5a941f84574c4821b5f87e56778b2bbc3b610dfd801fc0250f6cc OP_SUBSTR", + "priv_key": "2b339b5055fad695f0595d5581fa087455854f64c5443c03d5b4ca53549f12a41d58016252d5a941f84574c4821b5f87e56778b2bbc3b610dfd801fc0250f6cc", + "leafVersion": 192 + }, + [ + { + "id": 1, + "script": "20a3b0dcac08f86306ba04f5fe2a3243ef3a0347c0e2a4529720a18d3cfdce90ad7f", + "asm": "a3b0dcac08f86306ba04f5fe2a3243ef3a0347c0e2a4529720a18d3cfdce90ad OP_SUBSTR", + "priv_key": "ec29d60c1be9263602906499b5e3c1de9e36cc88cec31154210191a578b92e9da3b0dcac08f86306ba04f5fe2a3243ef3a0347c0e2a4529720a18d3cfdce90ad", + "leafVersion": 192 + }, + { + "id": 2, + "script": "20e6ccf03593dbd07eba10403e33586c130889de6e8219da0a9ccbdd46a56a5f367f", + "asm": "e6ccf03593dbd07eba10403e33586c130889de6e8219da0a9ccbdd46a56a5f36 OP_SUBSTR", + "priv_key": "da04d13f706a6e0d22ac0db7c361f1aaa706a27043efca4edfecfed3125238e1e6ccf03593dbd07eba10403e33586c130889de6e8219da0a9ccbdd46a56a5f36", + "leafVersion": 192 + } + ] + ] + }, + "intermediary": { + "leafHashes": [ + "0840c39e59eda6c9deee687a480cb169130c2f053ed2eb3134511ec1cfd8a2c7", + "837ef6677aeb0df2b0de47f45024684cc6ca03bda10fa30bb5bc05a94beb8dd1", + "b2a5304f678cc5a2ed51feb377dd0a609bd22ec979cc608bfcf884d0f8e6f93a" + ], + "merkleRoot": "eaf8f557fdb9673de7bb9bad7e7452da9f44a3e65133fdadf2849c55cfb3cf5b" + }, + "expected": { + "scriptPubKey": "5220eaf8f557fdb9673de7bb9bad7e7452da9f44a3e65133fdadf2849c55cfb3cf5b", + "bip350Address": "bc1zatu024lah9nnmeamnwkhuazjm205fglx2yelmt0jsjw9tnaneadszq7wg7", + "scriptPathControlBlocks": [ + "c1837ef6677aeb0df2b0de47f45024684cc6ca03bda10fa30bb5bc05a94beb8dd1b2a5304f678cc5a2ed51feb377dd0a609bd22ec979cc608bfcf884d0f8e6f93a", + "c10840c39e59eda6c9deee687a480cb169130c2f053ed2eb3134511ec1cfd8a2c7b2a5304f678cc5a2ed51feb377dd0a609bd22ec979cc608bfcf884d0f8e6f93a", + "c118781f42f664d67acaf0ce7c6826437e5440eb1789f232af05e9a09fdf547903" + ] + } + }, + { + "id": "p2mr_three_leaf_alternative", + "objective": "Tests another variant of P2MR with three leaves arranged in a different tree structure, showing alternative script path spending options", + "given": { + "scriptTree": [ + { + "id": 0, + "script": "20409f78ce0978519ff5d960c4ab595174c7efca11b1f89410a4e98b70cd423e1c7f", + "asm": "409f78ce0978519ff5d960c4ab595174c7efca11b1f89410a4e98b70cd423e1c OP_SUBSTR", + "priv_key": "c6ec3801b04afa40be6f77f3f7a7b3b7cb8cfe233b0263fb70e2f087b21397c1409f78ce0978519ff5d960c4ab595174c7efca11b1f89410a4e98b70cd423e1c", + "leafVersion": 192 + }, + [ + { + "id": 1, + "script": "209f0955dc884a5c88d1732e017d30e27e8a445889bce5aa42611b7635c5c1073a7f", + "asm": "9f0955dc884a5c88d1732e017d30e27e8a445889bce5aa42611b7635c5c1073a OP_SUBSTR", + "priv_key": "7524bca170d54231f1246f30fb00f9da2208b1363ba5a7bbaf11fc3b0309e9519f0955dc884a5c88d1732e017d30e27e8a445889bce5aa42611b7635c5c1073a", + "leafVersion": 192 + }, + { + "id": 2, + "script": "20c60b10d57c0cdf27e5c751e131ea4301b37abe7384948059256c7f5f1f285a7f7f", + "asm": "c60b10d57c0cdf27e5c751e131ea4301b37abe7384948059256c7f5f1f285a7f OP_SUBSTR", + "priv_key": "d9d0f17d630b6a538e6a8a036373e7b9e5023a4c08f72dd8c3ef59288b98c079c60b10d57c0cdf27e5c751e131ea4301b37abe7384948059256c7f5f1f285a7f", + "leafVersion": 192 + } + ] + ] + }, + "intermediary": { + "leafHashes": [ + "52e9326c2bf04d926b7e9f6c7645dd853f3f007b870201de9b814952750c9310", + "dcef3ce86cc8cea78c9e00f3d9ef58360cb6ed3cb90ec62efe00b9703854ba5c", + "ddb521a44e33ff4974e618d8b8b7794275b7dc754d847c537404f84330454361" + ], + "merkleRoot": "51e3c1151ba73d9efce801837773331bf9030977242f62dfeb6756795f482409" + }, + "expected": { + "scriptPubKey": "522051e3c1151ba73d9efce801837773331bf9030977242f62dfeb6756795f482409", + "bip350Address": "bc1z283uz9gm5u7eal8gqxphwuenr0usxzthyshk9hltvat8jh6gysys28twnc", + "scriptPathControlBlocks": [ + "c1dcef3ce86cc8cea78c9e00f3d9ef58360cb6ed3cb90ec62efe00b9703854ba5cddb521a44e33ff4974e618d8b8b7794275b7dc754d847c537404f84330454361", + "c152e9326c2bf04d926b7e9f6c7645dd853f3f007b870201de9b814952750c9310ddb521a44e33ff4974e618d8b8b7794275b7dc754d847c537404f84330454361", + "c1b45680a7821e4b9450096ab38adbc3c99225af8f6c7ec121a0a5f1ae02893ba3" + ] + } + } + ] +} diff --git a/bip-0360/ref-impl/common/utils/signet_miner_loop.sh b/bip-0360/ref-impl/common/utils/signet_miner_loop.sh new file mode 100755 index 0000000000..6ec65c4a40 --- /dev/null +++ b/bip-0360/ref-impl/common/utils/signet_miner_loop.sh @@ -0,0 +1,40 @@ +#!/bin/bash + +# Invokes mining simulator a configurable number of times + +if [ -z "${P2MR_ADDR}" ]; then + echo "Error: Environment variable P2MR_ADDR needs to be set" + exit 1 +fi + + +BITCOIN_SOURCE_DIR=${BITCOIN_SOURCE_DIR:-$HOME/bitcoin} + +# path to bitcoin.conf for signet +BITCOIN_CONF_FILE_PATH=${BITCOIN_CONF_FILE_PATH:-$HOME/anduro-360/configs/bitcoin.conf.signet} + +# Set default LOOP_COUNT to 110 if not set +LOOP_COUNT=${LOOP_COUNT:-110} + +# Validate LOOP_COUNT is a positive integer +if ! [[ "$LOOP_COUNT" =~ ^[0-9]+$ ]] || [ "$LOOP_COUNT" -le 0 ]; then + echo "Error: LOOP_COUNT must be a positive integer" + exit 1 +fi + +# Determine name of pool by querying mempool.space backend +# curl -X GET "http://localhost:8999/api/v1/mining/pool/marapool" | jq -r .pool.regexes +export POOL_ID=${POOL_ID:-"MARA Pool"} + +echo -en "\nLoop_COUNT = $LOOP_COUNT\nBITCOIN_CONF_FILE_PATH=$BITCOIN_CONF_FILE_PATH\nBITCOIN_SOURCE_DIR=$BITCOIN_SOURCE_DIR\nPOOL_ID=$POOL_ID\n\n"; + + +for ((i=1; i<=LOOP_COUNT; i++)) +do + echo "Iteration $i of $LOOP_COUNT" + $BITCOIN_SOURCE_DIR/contrib/signet/miner --cli "bitcoin-cli -conf=$BITCOIN_CONF_FILE_PATH" generate \ + --address $P2MR_ADDR \ + --grind-cmd "$BITCOIN_SOURCE_DIR/build/bin/bitcoin-util grind" \ + --poolid "$POOL_ID" \ + --min-nbits --set-block-time $(date +%s) +done diff --git a/bip-0360/ref-impl/common/utils/workshop/Dockerfile.bcli b/bip-0360/ref-impl/common/utils/workshop/Dockerfile.bcli new file mode 100644 index 0000000000..2060accaa5 --- /dev/null +++ b/bip-0360/ref-impl/common/utils/workshop/Dockerfile.bcli @@ -0,0 +1,88 @@ +# podman build -f Dockerfile.bcli -t quay.io/jbride2000/p2mr_bcli:0.1 . +# podman run -it --entrypoint /bin/bash quay.io/jbride200/p2mr_bcli:0.1 + +FROM rust:1-slim-bookworm AS builder + +# Install build dependencies +RUN apt-get update && apt-get install -y \ + build-essential \ + cmake \ + git \ + autoconf \ + automake \ + libtool \ + pkg-config \ + zlib1g-dev \ + libevent-dev \ + libboost-dev \ + libzmq3-dev \ + bash \ + python3 \ + python3-pip \ + libclang-dev \ + clang \ + && rm -rf /var/lib/apt/lists/* + +# Set working directory +WORKDIR /bitcoin + +# Copy Bitcoin Core source (or clone) +# COPY . /bitcoin +RUN git clone --branch p2mr-pqc --single-branch https://github.com/jbride/bitcoin.git + +# Environment variables for musl +ENV CC=gcc +ENV CXX=g++ + +# Build Bitcoin Core +WORKDIR bitcoin + +RUN apt-get update && apt-get install -y libsqlite3-dev && rm -rf /var/lib/apt/lists/* + +RUN mkdir build && cd build && \ + cmake .. \ + -DWITH_ZMQ=ON \ + -DBUILD_BENCH=ON \ + -DBUILD_DAEMON=ON && \ + make -j$(nproc) bitcoin-cli + +# Runtime stage with Debian Slim +FROM debian:bookworm-slim + +# Install minimal runtime dependencies +RUN apt-get update && apt-get install -y --no-install-recommends \ + bash \ + ca-certificates \ + libevent-core-2.1-7 \ + libevent-pthreads-2.1-7 \ + libevent-extra-2.1-7 \ + libboost-filesystem1.74.0 \ + libboost-thread1.74.0 \ + libzmq5 \ + libsqlite3-0 \ + telnet \ + && rm -rf /var/lib/apt/lists/* + +# Copy bitcoin-cli from builder +COPY --from=builder /bitcoin/bitcoin/build/bin/bitcoin-cli /usr/local/bin/bitcoin-cli + +# Create non-root user and set permissions +RUN groupadd --system bip360 && \ + useradd --system --gid bip360 --shell /bin/bash --create-home bip360 && \ + chmod +x /usr/local/bin/bitcoin-cli && \ + ln -s /usr/local/bin/bitcoin-cli /usr/local/bin/b-cli && \ + echo 'b-cli() { /usr/local/bin/bitcoin-cli -rpcconnect=${RPC_CONNECT:-192.168.122.1} -rpcport=${RPC_PORT:-18443} -rpcuser=${RPC_USER:-signet} -rpcpassword=${RPC_PASSWORD:-signet} "$@"; }' >> /home/bip360/.bashrc + +# Set default environment variables (can be overridden at runtime) +ENV RPC_CONNECT=192.168.122.1 \ + RPC_PORT=38332 \ + RPC_USER=signet \ + RPC_PASSWORD=signet + +# Switch to non-root user +USER bip360 + +WORKDIR /home/bip360 + +ENTRYPOINT ["/usr/local/bin/bitcoin-cli"] + diff --git a/bip-0360/ref-impl/common/utils/workshop/Dockerfile.full b/bip-0360/ref-impl/common/utils/workshop/Dockerfile.full new file mode 100644 index 0000000000..8ee222e714 --- /dev/null +++ b/bip-0360/ref-impl/common/utils/workshop/Dockerfile.full @@ -0,0 +1,115 @@ +# podman build -f Dockerfile.full -t quay.io/jbride2000/p2mr_demo:0.1 . +# podman run -it --entrypoint /bin/bash quay.io/jbride2000/p2mr_demo:0.1 + +FROM rust:1-slim-bookworm AS builder + +# Install build dependencies +RUN apt-get update && apt-get install -y \ + build-essential \ + cmake \ + git \ + autoconf \ + automake \ + libtool \ + pkg-config \ + zlib1g-dev \ + libevent-dev \ + libboost-dev \ + libzmq3-dev \ + bash \ + python3 \ + python3-pip \ + libclang-dev \ + clang \ + && rm -rf /var/lib/apt/lists/* + +# Set working directory +WORKDIR /bitcoin + +# Copy Bitcoin Core source (or clone) +# COPY . /bitcoin +RUN git clone --branch p2mr-pqc --single-branch https://github.com/jbride/bitcoin.git + +# Environment variables for musl +ENV CC=gcc +ENV CXX=g++ + +# Build Bitcoin Core +WORKDIR bitcoin + +RUN apt-get update && apt-get install -y libsqlite3-dev && rm -rf /var/lib/apt/lists/* + +RUN mkdir build && cd build && \ + cmake .. \ + -DWITH_ZMQ=ON \ + -DBUILD_BENCH=ON \ + -DBUILD_DAEMON=ON && \ + make -j$(nproc) bitcoin-cli + +# Runtime stage with Debian Slim +FROM rust:1-slim-bookworm + +# Install minimal runtime dependencies +RUN apt-get update && apt-get install -y --no-install-recommends \ + bash \ + ca-certificates \ + libevent-core-2.1-7 \ + libevent-pthreads-2.1-7 \ + libevent-extra-2.1-7 \ + libboost-filesystem1.74.0 \ + libboost-thread1.74.0 \ + libzmq5 \ + libsqlite3-0 \ + && rm -rf /var/lib/apt/lists/* + +# Copy bitcoin-cli from builder +COPY --from=builder /bitcoin/bitcoin/build/bin/bitcoin-cli /usr/local/bin/bitcoin-cli + +# Create non-root user and set permissions +RUN groupadd --system bip360 && \ + useradd --system --gid bip360 --shell /bin/bash --create-home bip360 && \ + chmod +x /usr/local/bin/bitcoin-cli && \ + ln -s /usr/local/bin/bitcoin-cli /usr/local/bin/b-cli && \ + echo 'b-cli() { /usr/local/bin/bitcoin-cli -rpcconnect=${RPC_CONNECT:-192.168.122.1} -rpcport=${RPC_PORT:-18443} -rpcuser=${RPC_USER:-signet} -rpcpassword=${RPC_PASSWORD:-signet} "$@"; }' >> /home/bip360/.bashrc + +# Install additional tools needed for building Rust code (before switching to non-root user) +RUN apt-get update && apt-get install -y --no-install-recommends \ + libclang-dev \ + clang \ + git \ + curl \ + cmake \ + build-essential \ + jq \ + gawk \ + telnet \ + && rm -rf /var/lib/apt/lists/* + +# Set default environment variables (can be overridden at runtime) +ENV RPC_CONNECT=192.168.122.1 \ + RPC_PORT=38332 \ + RPC_USER=signet \ + RPC_PASSWORD=signet + +# Switch to non-root user +USER bip360 + +WORKDIR /home/bip360 + +RUN git clone --no-checkout --depth 1 --branch p2mr-pqc \ + --single-branch https://github.com/jbride/bips.git bips && \ + cd bips && \ + git sparse-checkout init --cone && \ + git sparse-checkout set bip-0360 && \ + git checkout && \ + cd bip-0360/ref-impl/rust && \ + cargo build && \ + rm -rf target + +WORKDIR /home/bip360/bips/bip-0360/ref-impl/rust + +ENV BITCOIN_NETWORK=signet \ + USE_PQC=true + +ENTRYPOINT ["/usr/local/bin/bitcoin-cli"] + diff --git a/bip-0360/ref-impl/common/utils/workshop/bip360-workshop.drawio b/bip-0360/ref-impl/common/utils/workshop/bip360-workshop.drawio new file mode 100644 index 0000000000..4f587663c1 --- /dev/null +++ b/bip-0360/ref-impl/common/utils/workshop/bip360-workshop.drawio @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/bip-0360/ref-impl/common/utils/workshop/signet_360.drawio.png b/bip-0360/ref-impl/common/utils/workshop/signet_360.drawio.png new file mode 100644 index 0000000000..4c80145f8d Binary files /dev/null and b/bip-0360/ref-impl/common/utils/workshop/signet_360.drawio.png differ diff --git a/bip-0360/ref-impl/js/.gitignore b/bip-0360/ref-impl/js/.gitignore new file mode 100644 index 0000000000..1d1baf2e55 --- /dev/null +++ b/bip-0360/ref-impl/js/.gitignore @@ -0,0 +1,76 @@ +# Dependencies +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +lerna-debug.log* + +# Build outputs +dist/ +build/ +*.tsbuildinfo + +# TypeScript +*.js.map +*.d.ts.map + +# Environment variables +.env +.env.local +.env.*.local + +# IDE / Editor files +.vscode/ +.idea/ +*.swp +*.swo +*~ +.DS_Store + +# OS files +Thumbs.db +desktop.ini + +# Testing +coverage/ +.nyc_output/ +*.lcov + +# Logs +logs/ +*.log + +# Temporary files +*.tmp +*.temp +.cache/ + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# parcel-bundler cache +.parcel-cache + +# Next.js (if ever used) +.next +out + +# Vercel (if ever used) +.vercel + +# Turbo (if ever used) +.turbo + diff --git a/bip-0360/ref-impl/js/README.adoc b/bip-0360/ref-impl/js/README.adoc new file mode 100644 index 0000000000..797ba5436b --- /dev/null +++ b/bip-0360/ref-impl/js/README.adoc @@ -0,0 +1,18 @@ + += BIP 360 Javascript Reference Implementation + +:numbered: + +== procedure + +----- +$ npm install + +# compile Typecript +$ npx tsc + + +# run tests +$ node src/p2mr-example.ts +$ node src/test-npm-pqc-package.js +----- diff --git a/bip-0360/ref-impl/js/package-lock.json b/bip-0360/ref-impl/js/package-lock.json new file mode 100644 index 0000000000..453951f285 --- /dev/null +++ b/bip-0360/ref-impl/js/package-lock.json @@ -0,0 +1,245 @@ +{ + "name": "js", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "js", + "version": "1.0.0", + "license": "ISC", + "dependencies": { + "@jbride/bitcoinjs-lib": "^7.0.0-rc.0-p2mr-0.0", + "@jbride/bitcoinpqc-wasm": "^0.1.1", + "ecpair": "^3.0.0", + "tiny-secp256k1": "^2.2.4" + }, + "devDependencies": { + "@types/node": "^24.10.0", + "typescript": "^5.9.3" + } + }, + "node_modules/@jbride/bitcoinjs-lib": { + "version": "7.0.0-rc.0-p2mr-0.0", + "resolved": "https://registry.npmjs.org/@jbride/bitcoinjs-lib/-/bitcoinjs-lib-7.0.0-rc.0-p2mr-0.0.tgz", + "integrity": "sha512-JRL0LTBVFBhfHhEciJi8I7C5jGoL24b07rwQthe+3UAGbv2LLOqKRYAD3dc5XD4Maanh1awV+MUELgc7OFgjYw==", + "license": "MIT", + "dependencies": { + "@noble/hashes": "^1.2.0", + "bech32": "^2.0.0", + "bip174": "^3.0.0-rc.0", + "bs58check": "^4.0.0", + "uint8array-tools": "^0.0.9", + "valibot": "^0.38.0", + "varuint-bitcoin": "^2.0.0" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@jbride/bitcoinpqc-wasm": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@jbride/bitcoinpqc-wasm/-/bitcoinpqc-wasm-0.1.1.tgz", + "integrity": "sha512-aftRuCBYXPEYzvWBVG84Vgum/ba4zkpUQrNA3jsWK2ir/DzxY7WmReskFEuPprc8X/LQ0/2lxJZyzqGRxDuO8w==", + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@noble/hashes": { + "version": "1.8.0", + "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz", + "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==", + "license": "MIT", + "engines": { + "node": "^14.21.3 || >=16" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/@types/node": { + "version": "24.10.0", + "resolved": "https://registry.npmjs.org/@types/node/-/node-24.10.0.tgz", + "integrity": "sha512-qzQZRBqkFsYyaSWXuEHc2WR9c0a0CXwiE5FWUvn7ZM+vdy1uZLfCunD38UzhuB7YN/J11ndbDBcTmOdxJo9Q7A==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~7.16.0" + } + }, + "node_modules/base-x": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/base-x/-/base-x-5.0.1.tgz", + "integrity": "sha512-M7uio8Zt++eg3jPj+rHMfCC+IuygQHHCOU+IYsVtik6FWjuYpVt/+MRKcgsAMHh8mMFAwnB+Bs+mTrFiXjMzKg==", + "license": "MIT" + }, + "node_modules/bech32": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/bech32/-/bech32-2.0.0.tgz", + "integrity": "sha512-LcknSilhIGatDAsY1ak2I8VtGaHNhgMSYVxFrGLXv+xLHytaKZKcaUJJUE7qmBr7h33o5YQwP55pMI0xmkpJwg==", + "license": "MIT" + }, + "node_modules/bip174": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/bip174/-/bip174-3.0.0.tgz", + "integrity": "sha512-N3vz3rqikLEu0d6yQL8GTrSkpYb35NQKWMR7Hlza0lOj6ZOlvQ3Xr7N9Y+JPebaCVoEUHdBeBSuLxcHr71r+Lw==", + "license": "MIT", + "dependencies": { + "uint8array-tools": "^0.0.9", + "varuint-bitcoin": "^2.0.0" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/bs58": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/bs58/-/bs58-6.0.0.tgz", + "integrity": "sha512-PD0wEnEYg6ijszw/u8s+iI3H17cTymlrwkKhDhPZq+Sokl3AU4htyBFTjAeNAlCCmg0f53g6ih3jATyCKftTfw==", + "license": "MIT", + "dependencies": { + "base-x": "^5.0.0" + } + }, + "node_modules/bs58check": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/bs58check/-/bs58check-4.0.0.tgz", + "integrity": "sha512-FsGDOnFg9aVI9erdriULkd/JjEWONV/lQE5aYziB5PoBsXRind56lh8doIZIc9X4HoxT5x4bLjMWN1/NB8Zp5g==", + "license": "MIT", + "dependencies": { + "@noble/hashes": "^1.2.0", + "bs58": "^6.0.0" + } + }, + "node_modules/ecpair": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/ecpair/-/ecpair-3.0.0.tgz", + "integrity": "sha512-kf4JxjsRQoD4EBzpYjGAcR0t9i/4oAeRPtyCpKvSwyotgkc6oA4E4M0/e+kep7cXe+mgxAvoeh/jdgH9h5+Wxw==", + "license": "MIT", + "dependencies": { + "uint8array-tools": "^0.0.8", + "valibot": "^0.37.0", + "wif": "^5.0.0" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/ecpair/node_modules/uint8array-tools": { + "version": "0.0.8", + "resolved": "https://registry.npmjs.org/uint8array-tools/-/uint8array-tools-0.0.8.tgz", + "integrity": "sha512-xS6+s8e0Xbx++5/0L+yyexukU7pz//Yg6IHg3BKhXotg1JcYtgxVcUctQ0HxLByiJzpAkNFawz1Nz5Xadzo82g==", + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/ecpair/node_modules/valibot": { + "version": "0.37.0", + "resolved": "https://registry.npmjs.org/valibot/-/valibot-0.37.0.tgz", + "integrity": "sha512-FQz52I8RXgFgOHym3XHYSREbNtkgSjF9prvMFH1nBsRyfL6SfCzoT1GuSDTlbsuPubM7/6Kbw0ZMQb8A+V+VsQ==", + "license": "MIT", + "peerDependencies": { + "typescript": ">=5" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/tiny-secp256k1": { + "version": "2.2.4", + "resolved": "https://registry.npmjs.org/tiny-secp256k1/-/tiny-secp256k1-2.2.4.tgz", + "integrity": "sha512-FoDTcToPqZE454Q04hH9o2EhxWsm7pOSpicyHkgTwKhdKWdsTUuqfP5MLq3g+VjAtl2vSx6JpXGdwA2qpYkI0Q==", + "license": "MIT", + "dependencies": { + "uint8array-tools": "0.0.7" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/tiny-secp256k1/node_modules/uint8array-tools": { + "version": "0.0.7", + "resolved": "https://registry.npmjs.org/uint8array-tools/-/uint8array-tools-0.0.7.tgz", + "integrity": "sha512-vrrNZJiusLWoFWBqz5Y5KMCgP9W9hnjZHzZiZRT8oNAkq3d5Z5Oe76jAvVVSRh4U8GGR90N2X1dWtrhvx6L8UQ==", + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "devOptional": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/uint8array-tools": { + "version": "0.0.9", + "resolved": "https://registry.npmjs.org/uint8array-tools/-/uint8array-tools-0.0.9.tgz", + "integrity": "sha512-9vqDWmoSXOoi+K14zNaf6LBV51Q8MayF0/IiQs3GlygIKUYtog603e6virExkjjFosfJUBI4LhbQK1iq8IG11A==", + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/undici-types": { + "version": "7.16.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz", + "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==", + "dev": true, + "license": "MIT" + }, + "node_modules/valibot": { + "version": "0.38.0", + "resolved": "https://registry.npmjs.org/valibot/-/valibot-0.38.0.tgz", + "integrity": "sha512-RCJa0fetnzp+h+KN9BdgYOgtsMAG9bfoJ9JSjIhFHobKWVWyzM3jjaeNTdpFK9tQtf3q1sguXeERJ/LcmdFE7w==", + "license": "MIT", + "peerDependencies": { + "typescript": ">=5" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/varuint-bitcoin": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/varuint-bitcoin/-/varuint-bitcoin-2.0.0.tgz", + "integrity": "sha512-6QZbU/rHO2ZQYpWFDALCDSRsXbAs1VOEmXAxtbtjLtKuMJ/FQ8YbhfxlaiKv5nklci0M6lZtlZyxo9Q+qNnyog==", + "license": "MIT", + "dependencies": { + "uint8array-tools": "^0.0.8" + } + }, + "node_modules/varuint-bitcoin/node_modules/uint8array-tools": { + "version": "0.0.8", + "resolved": "https://registry.npmjs.org/uint8array-tools/-/uint8array-tools-0.0.8.tgz", + "integrity": "sha512-xS6+s8e0Xbx++5/0L+yyexukU7pz//Yg6IHg3BKhXotg1JcYtgxVcUctQ0HxLByiJzpAkNFawz1Nz5Xadzo82g==", + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/wif": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/wif/-/wif-5.0.0.tgz", + "integrity": "sha512-iFzrC/9ne740qFbNjTZ2FciSRJlHIXoxqk/Y5EnE08QOXu1WjJyCCswwDTYbohAOEnlCtLaAAQBhyaLRFh2hMA==", + "license": "MIT", + "dependencies": { + "bs58check": "^4.0.0" + } + } + } +} diff --git a/bip-0360/ref-impl/js/package.json b/bip-0360/ref-impl/js/package.json new file mode 100644 index 0000000000..4ec7be0f5b --- /dev/null +++ b/bip-0360/ref-impl/js/package.json @@ -0,0 +1,23 @@ +{ + "name": "js", + "version": "1.0.0", + "type": "module", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "keywords": [], + "author": "", + "license": "ISC", + "devDependencies": { + "@types/node": "^24.10.0", + "typescript": "^5.9.3" + }, + "dependencies": { + "@jbride/bitcoinjs-lib": "^7.0.0-rc.0-p2mr-0.0", + "@jbride/bitcoinpqc-wasm": "^0.1.1", + "ecpair": "^3.0.0", + "tiny-secp256k1": "^2.2.4" + } +} diff --git a/bip-0360/ref-impl/js/src/p2mr-example.ts b/bip-0360/ref-impl/js/src/p2mr-example.ts new file mode 100644 index 0000000000..6eb20fb406 --- /dev/null +++ b/bip-0360/ref-impl/js/src/p2mr-example.ts @@ -0,0 +1,200 @@ +// src/p2mr-example.ts +// Example demonstrating P2MR (Pay-to-Taproot-Script-Hash) address construction + +import { payments } from '@jbride/bitcoinjs-lib'; +import * as bitcoinCrypto from '@jbride/bitcoinjs-lib/src/crypto'; +import * as bscript from '@jbride/bitcoinjs-lib/src/script'; +import type { Taptree } from '@jbride/bitcoinjs-lib/src/types'; +import ECPairFactory, { type ECPairInterface } from 'ecpair'; +import * as ecc from 'tiny-secp256k1'; +import { randomBytes } from 'crypto'; + +const { p2mr } = payments; + +// Initialize ECPair with the ECC library +const ECPair = ECPairFactory(ecc); + +// Create a secure RNG function +const rng = (size: number) => randomBytes(size); + +function signAndVerify( + keyPair: ECPairInterface, + xOnlyPubkey: Uint8Array, + message: Buffer, +) { + const hash = Buffer.from(bitcoinCrypto.hash256(message)); + const schnorrSignature = Buffer.from(keyPair.signSchnorr(hash)); + const signatureWithSighashDefault = Buffer.concat([schnorrSignature, Buffer.from([0x00])]); + const verified = keyPair.verifySchnorr(hash, schnorrSignature); + + return { + message, + hash, + signature: schnorrSignature, + signatureWithSighashDefault, + verified, + }; +} + +/** + * Example 1: Construct a P2MR address from a script tree with a single leaf + * This is the simplest case - a script tree containing one script. + */ +function example1_simpleScriptTree() { + console.log('=== Example 1: P2MR from simple script tree ==='); + + // Generate a key pair + const keyPair = ECPair.makeRandom({ rng }); + const pubkey = keyPair.publicKey; + const xOnlyPubkey = ecc.xOnlyPointFromPoint(pubkey); + + // Compile the script: x-only pubkey OP_CHECKSIG (BIP342 Schnorr signature) + const script = bscript.compile([Buffer.from(xOnlyPubkey), bscript.OPS.OP_CHECKSIG]); + + // Create a script tree with one leaf + const scriptTree = { + output: script, + }; + + // Construct the P2MR payment + const payment = p2mr({ + scriptTree: scriptTree, + }); + + console.log('Generated compressed pubkey:', pubkey.toString('hex')); + console.log('X-only pubkey:', Buffer.from(xOnlyPubkey).toString('hex')); + console.log('Script tree:', { output: bscript.toASM(script) }); + console.log('P2MR Address:', payment.address); + console.log('Output script:', bscript.toASM(payment.output!)); + console.log('Merkle root hash:', payment.hash ? Buffer.from(payment.hash).toString('hex') : undefined); + const message = Buffer.from('P2MR demo - example 1', 'utf8'); + const result = signAndVerify(keyPair, xOnlyPubkey, message); + + console.log('Message:', result.message.toString('utf8')); + console.log('Hash256(message):', result.hash.toString('hex')); + console.log('Schnorr signature (64-byte):', result.signature.toString('hex')); + console.log('Signature + default sighash (65-byte witness element):', result.signatureWithSighashDefault.toString('hex')); + console.log('Signature valid:', result.verified); + console.log('Witness stack for spend:', [result.signatureWithSighashDefault.toString('hex'), bscript.toASM(script)]); + console.log(); +} + +/** + * Example 2: Construct a P2MR address from a script tree with multiple leaves + * This demonstrates a more complex script tree structure. + */ +function example2_multiLeafScriptTree() { + console.log('=== Example 2: P2MR from multi-leaf script tree ==='); + + // Generate two different key pairs for the leaves + const keyPair1 = ECPair.makeRandom({ rng }); + const keyPair2 = ECPair.makeRandom({ rng }); + const pubkey1 = keyPair1.publicKey; + const pubkey2 = keyPair2.publicKey; + const xOnlyPubkey1 = ecc.xOnlyPointFromPoint(pubkey1); + const xOnlyPubkey2 = ecc.xOnlyPointFromPoint(pubkey2); + + const script1 = bscript.compile([Buffer.from(xOnlyPubkey1), bscript.OPS.OP_CHECKSIG]); + const script2 = bscript.compile([Buffer.from(xOnlyPubkey2), bscript.OPS.OP_CHECKSIG]); + + // Create a script tree with two leaves (array of two leaf objects) + const scriptTree: Taptree = [ + { output: script1 }, + { output: script2 }, + ]; + + // Construct the P2MR payment + const payment = p2mr({ + scriptTree: scriptTree, + }); + + console.log('Generated compressed public keys:'); + console.log(' Pubkey 1:', pubkey1.toString('hex')); + console.log(' Pubkey 2:', pubkey2.toString('hex')); + console.log('X-only pubkeys:'); + console.log(' X-only 1:', Buffer.from(xOnlyPubkey1).toString('hex')); + console.log(' X-only 2:', Buffer.from(xOnlyPubkey2).toString('hex')); + console.log('Script tree leaves:'); + console.log(' Leaf 1:', bscript.toASM(script1)); + console.log(' Leaf 2:', bscript.toASM(script2)); + console.log('P2MR Address:', payment.address); + console.log('Output script:', bscript.toASM(payment.output!)); + console.log('Merkle root hash:', payment.hash ? Buffer.from(payment.hash).toString('hex') : undefined); + const message1 = Buffer.from('P2MR demo - example 2 leaf 1', 'utf8'); + const message2 = Buffer.from('P2MR demo - example 2 leaf 2', 'utf8'); + const result1 = signAndVerify(keyPair1, xOnlyPubkey1, message1); + const result2 = signAndVerify(keyPair2, xOnlyPubkey2, message2); + + console.log('Leaf 1 signature info:'); + console.log(' Message:', result1.message.toString('utf8')); + console.log(' Hash256(message):', result1.hash.toString('hex')); + console.log(' Schnorr signature (64-byte):', result1.signature.toString('hex')); + console.log(' Signature + default sighash (65-byte):', result1.signatureWithSighashDefault.toString('hex')); + console.log(' Signature valid:', result1.verified); + console.log(' Witness stack:', [result1.signatureWithSighashDefault.toString('hex'), bscript.toASM(script1)]); + + console.log('Leaf 2 signature info:'); + console.log(' Message:', result2.message.toString('utf8')); + console.log(' Hash256(message):', result2.hash.toString('hex')); + console.log(' Schnorr signature (64-byte):', result2.signature.toString('hex')); + console.log(' Signature + default sighash (65-byte):', result2.signatureWithSighashDefault.toString('hex')); + console.log(' Signature valid:', result2.verified); + console.log(' Witness stack:', [result2.signatureWithSighashDefault.toString('hex'), bscript.toASM(script2)]); + console.log(); +} + +/** + * Example 4: Construct a P2MR address from a hash and redeem script + * This demonstrates creating a P2MR when you have the hash directly. + */ +function example3_fromHashAndRedeem() { + console.log('=== Example 3: P2MR from hash and redeem script ==='); + + // Generate a key pair + const keyPair = ECPair.makeRandom({ rng }); + const pubkey = keyPair.publicKey; + const xOnlyPubkey = ecc.xOnlyPointFromPoint(pubkey); + const redeemScript = bscript.compile([Buffer.from(xOnlyPubkey), bscript.OPS.OP_CHECKSIG]); + + // Use a known hash (from test fixtures) + const hash = Buffer.from( + 'b424dea09f840b932a00373cdcdbd25650b8c3acfe54a9f4a641a286721b8d26', + 'hex', + ); + + // Construct the P2MR payment + const payment = p2mr({ + hash: hash, + redeem: { + output: redeemScript, + }, + }); + + console.log('Generated compressed pubkey:', pubkey.toString('hex')); + console.log('X-only pubkey:', Buffer.from(xOnlyPubkey).toString('hex')); + console.log('Redeem script:', bscript.toASM(redeemScript)); + console.log('Hash:', hash.toString('hex')); + console.log('P2MR Address:', payment.address); + console.log('Output script:', bscript.toASM(payment.output!)); + const message = Buffer.from('P2MR demo - example 3', 'utf8'); + const result = signAndVerify(keyPair, xOnlyPubkey, message); + + console.log('Message:', result.message.toString('utf8')); + console.log('Hash256(message):', result.hash.toString('hex')); + console.log('Schnorr signature (64-byte):', result.signature.toString('hex')); + console.log('Signature + default sighash (65-byte):', result.signatureWithSighashDefault.toString('hex')); + console.log('Signature valid:', result.verified); + console.log('Witness stack:', [result.signatureWithSighashDefault.toString('hex'), bscript.toASM(redeemScript)]); + console.log(); +} + +// Run all examples +console.log('P2MR Address Construction Examples\n'); +console.log('=====================================\n'); + +example1_simpleScriptTree(); +example2_multiLeafScriptTree(); +example3_fromHashAndRedeem(); + +console.log('====================================='); +console.log('All examples completed!'); diff --git a/bip-0360/ref-impl/js/src/test-npm-pqc-package.js b/bip-0360/ref-impl/js/src/test-npm-pqc-package.js new file mode 100644 index 0000000000..a16e50dff3 --- /dev/null +++ b/bip-0360/ref-impl/js/src/test-npm-pqc-package.js @@ -0,0 +1,197 @@ +#!/usr/bin/env node + +/** + * Node.js test script for Bitcoin PQC WASM module (High-Level API) + * + * Usage: node test-npm-package.js + * + * This script tests the high-level TypeScript wrapper API (index.js) from the + * command line, which provides a cleaner interface than the low-level API. + */ + +import { randomBytes } from 'node:crypto'; + +// Load the high-level WASM module +let bitcoinpqc; +let Algorithm; + +try { + const module = await import('@jbride/bitcoinpqc-wasm'); + bitcoinpqc = module.bitcoinpqc || module.default; + Algorithm = module.Algorithm; + + if (!bitcoinpqc || !Algorithm) { + throw new Error('Failed to import bitcoinpqc or Algorithm from @jbride/bitcoinpqc-wasm'); + } +} catch (error) { + console.error('Failed to load WASM module:', error); + console.error('Make sure you have installed the @jbride/bitcoinpqc-wasm package before running this test.'); + process.exit(1); +} + +// Helper function to generate random bytes +function generateRandomBytes(length) { + const array = new Uint8Array(length); + const bytes = randomBytes(length); + array.set(bytes); + return array; +} + +// Test function +async function testAlgorithm(algorithm, name) { + console.log(`\nTesting ${name} algorithm:`); + console.log('------------------------'); + + try { + // Get key and signature sizes + const pkSize = bitcoinpqc.publicKeySize(algorithm); + const skSize = bitcoinpqc.secretKeySize(algorithm); + const sigSize = bitcoinpqc.signatureSize(algorithm); + + console.log(`Public key size: ${pkSize} bytes`); + console.log(`Secret key size: ${skSize} bytes`); + console.log(`Signature size: ${sigSize} bytes`); + + // Generate random data for key generation + const randomData = generateRandomBytes(128); + + // Generate a key pair + const keygenStart = Date.now(); + const keypair = bitcoinpqc.generateKeypair(algorithm, randomData); + const keygenDuration = Date.now() - keygenStart; + console.log(`Key generation time: ${keygenDuration} ms`); + + // Create a message to sign + const messageText = 'This is a test message for PQC signature verification'; + const message = Buffer.from(messageText, 'utf8'); + const messageUint8 = new Uint8Array(message); + console.log(`Message to sign: "${messageText}"`); + console.log(`Message length: ${message.length} bytes`); + + // Sign the message + const signStart = Date.now(); + let signature; + try { + signature = bitcoinpqc.sign(keypair.secretKey, messageUint8, algorithm); + const signDuration = Date.now() - signStart; + console.log(`Signing time: ${signDuration} ms`); + console.log(`Actual signature size: ${signature.size} bytes`); + } catch (error) { + const signDuration = Date.now() - signStart; + console.log(`Signing failed after ${signDuration} ms`); + console.log(`Error: ${error.message}`); + if (algorithm === Algorithm.SLH_DSA_SHAKE_128S) { + console.log(''); + console.log('⚠️ NOTE: SLH-DSA-SHAKE-128s signing is currently experiencing'); + console.log(' issues when compiled to WebAssembly. This appears to be a'); + console.log(' bug in the SPHINCS+ reference implementation when compiled'); + console.log(' to WASM. ML-DSA-44 (Dilithium) works correctly.'); + console.log(''); + console.log(' Key generation succeeded, but signing failed.'); + console.log(' This is a known limitation of the browser/WASM build.'); + } + throw error; + } + + // Verify the signature + const verifyStart = Date.now(); + const verifyResult = bitcoinpqc.verify( + keypair.publicKey, + messageUint8, + signature, + algorithm + ); + const verifyDuration = Date.now() - verifyStart; + + if (verifyResult) { + console.log('Signature verified successfully!'); + } else { + console.log('ERROR: Signature verification failed!'); + } + console.log(`Verification time: ${verifyDuration} ms`); + + // Try to verify with a modified message + const modifiedMessageText = 'This is a MODIFIED message for PQC signature verification'; + const modifiedMessage = Buffer.from(modifiedMessageText, 'utf8'); + const modifiedMessageUint8 = new Uint8Array(modifiedMessage); + console.log(`Modified message: "${modifiedMessageText}"`); + const modifiedVerifyResult = bitcoinpqc.verify( + keypair.publicKey, + modifiedMessageUint8, + signature, + algorithm + ); + + if (modifiedVerifyResult) { + console.log('ERROR: Signature verified for modified message!'); + } else { + console.log('Correctly rejected signature for modified message'); + } + + console.log('✓ Test passed!\n'); + return true; + } catch (error) { + console.error(`❌ Error: ${error.message}`); + if (error.stack) { + console.error(error.stack); + } + return false; + } +} + +async function runTests() { + console.log('Bitcoin PQC Library Example (Node.js - High-Level API)'); + console.log('======================================================\n'); + console.log('This example tests the post-quantum signature algorithms designed for BIP-360 and the Bitcoin QuBit soft fork.'); + console.log('Using the high-level TypeScript wrapper API (index.js).\n'); + + // Initialize the module + try { + console.log('Initializing WASM module...'); + await bitcoinpqc.init({ + onRuntimeInitialized: () => { + console.log('✓ WASM module initialized successfully!\n'); + }, + print: (text) => { + // Enable WASM print output for debugging + console.log('WASM:', text); + }, + printErr: (text) => { + console.error('WASM Error:', text); + }, + // Node.js-specific: provide crypto.getRandomValues + getRandomValues: (arr) => { + const bytes = randomBytes(arr.length); + arr.set(bytes); + return arr; + } + }); + } catch (error) { + console.error('Failed to initialize module:', error); + if (error.stack) { + console.error(error.stack); + } + process.exit(1); + } + + const results = []; + + // Test ML-DSA-44 + results.push(await testAlgorithm(Algorithm.ML_DSA_44, 'ML-DSA-44')); + + // Test SLH-DSA-Shake-128s + results.push(await testAlgorithm(Algorithm.SLH_DSA_SHAKE_128S, 'SLH-DSA-Shake-128s')); + + // Summary + console.log('\n======================================================'); + console.log('Test Summary:'); + console.log(` ML-DSA-44: ${results[0] ? '✓ PASSED' : '✗ FAILED'}`); + console.log(` SLH-DSA-Shake-128s: ${results[1] ? '✓ PASSED' : '✗ FAILED'}`); + console.log('======================================================\n'); + + const exitCode = results.every(r => r) ? 0 : 1; + process.exit(exitCode); +} + +// Start +runTests(); diff --git a/bip-0360/ref-impl/js/tsconfig.json b/bip-0360/ref-impl/js/tsconfig.json new file mode 100644 index 0000000000..b181afe130 --- /dev/null +++ b/bip-0360/ref-impl/js/tsconfig.json @@ -0,0 +1,45 @@ +{ + // Visit https://aka.ms/tsconfig to read more about this file + "include": [ + "src/**/*" + ], + "compilerOptions": { + // File Layout + "rootDir": "./src", + "outDir": "./dist", + + // Environment Settings + // See also https://aka.ms/tsconfig/module + "module": "nodenext", + "target": "esnext", + "types": ["node"], + // For nodejs: + // "lib": ["esnext"], + + // Other Outputs + "sourceMap": true, + "declaration": true, + "declarationMap": true, + + // Stricter Typechecking Options + "noUncheckedIndexedAccess": true, + "exactOptionalPropertyTypes": true, + + // Style Options + // "noImplicitReturns": true, + // "noImplicitOverride": true, + // "noUnusedLocals": true, + // "noUnusedParameters": true, + // "noFallthroughCasesInSwitch": true, + // "noPropertyAccessFromIndexSignature": true, + + // Recommended Options + "strict": true, + "jsx": "react-jsx", + "verbatimModuleSyntax": true, + "isolatedModules": true, + "noUncheckedSideEffectImports": true, + "moduleDetection": "force", + "skipLibCheck": true, + } +} diff --git a/bip-0360/ref-impl/python/.gitignore b/bip-0360/ref-impl/python/.gitignore new file mode 100644 index 0000000000..b6e47617de --- /dev/null +++ b/bip-0360/ref-impl/python/.gitignore @@ -0,0 +1,129 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +.python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ diff --git a/bip-0360/ref-impl/rust/.cargo/config.toml b/bip-0360/ref-impl/rust/.cargo/config.toml new file mode 100644 index 0000000000..04bd2901e0 --- /dev/null +++ b/bip-0360/ref-impl/rust/.cargo/config.toml @@ -0,0 +1,2 @@ +[registries.kellnr-denver-space] +index = "sparse+https://crates.denver.space/api/v1/crates/" diff --git a/bip-0360/ref-impl/rust/Cargo.lock b/bip-0360/ref-impl/rust/Cargo.lock new file mode 100644 index 0000000000..e635f4bd5a --- /dev/null +++ b/bip-0360/ref-impl/rust/Cargo.lock @@ -0,0 +1,905 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "aho-corasick" +version = "1.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e60d3430d3a69478ad0993f19238d2df97c507009a52b3c10addcd7f6bcb916" +dependencies = [ + "memchr", +] + +[[package]] +name = "anstream" +version = "0.6.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43d5b281e737544384e969a5ccad3f1cdd24b48086a0fc1b2a5262a26b8f4f4a" +dependencies = [ + "anstyle", + "anstyle-parse", + "anstyle-query", + "anstyle-wincon", + "colorchoice", + "is_terminal_polyfill", + "utf8parse", +] + +[[package]] +name = "anstyle" +version = "1.0.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5192cca8006f1fd4f7237516f40fa183bb07f8fbdfedaa0036de5ea9b0b45e78" + +[[package]] +name = "anstyle-parse" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7644824f0aa2c7b9384579234ef10eb7efb6a0deb83f9630a49594dd9c15c2" +dependencies = [ + "utf8parse", +] + +[[package]] +name = "anstyle-query" +version = "1.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e231f6134f61b71076a3eab506c379d4f36122f2af15a9ff04415ea4c3339e2" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "anstyle-wincon" +version = "3.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3e0633414522a32ffaac8ac6cc8f748e090c5717661fddeea04219e2344f5f2a" +dependencies = [ + "anstyle", + "once_cell_polyfill", + "windows-sys", +] + +[[package]] +name = "anyhow" +version = "1.0.100" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61" + +[[package]] +name = "arrayvec" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50" + +[[package]] +name = "base58ck" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c8d66485a3a2ea485c1913c4572ce0256067a5377ac8c75c4960e1cda98605f" +dependencies = [ + "bitcoin-internals", + "bitcoin_hashes", +] + +[[package]] +name = "base64" +version = "0.21.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9d297deb1925b89f2ccc13d7635fa0714f12c87adce1c75356b39ca9b7178567" + +[[package]] +name = "bech32" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d965446196e3b7decd44aa7ee49e31d630118f90ef12f97900f262eb915c951d" + +[[package]] +name = "bindgen" +version = "0.71.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5f58bf3d7db68cfbac37cfc485a8d711e87e064c3d0fe0435b92f7a407f9d6b3" +dependencies = [ + "bitflags", + "cexpr", + "clang-sys", + "itertools", + "log", + "prettyplease", + "proc-macro2", + "quote", + "regex", + "rustc-hash", + "shlex", + "syn", +] + +[[package]] +name = "bitcoin-internals" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "30bdbe14aa07b06e6cfeffc529a1f099e5fbe249524f8125358604df99a4bed2" +dependencies = [ + "serde", +] + +[[package]] +name = "bitcoin-io" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b47c4ab7a93edb0c7198c5535ed9b52b63095f4e9b45279c6736cec4b856baf" + +[[package]] +name = "bitcoin-p2mr-pqc" +version = "0.32.6-p2mr-pqc.1" +source = "sparse+https://crates.denver.space/api/v1/crates/" +checksum = "ce8a80e619111bf8d228f3f1b169a2487e6e28974f39c8935657640e0214f9ed" +dependencies = [ + "base58ck", + "base64", + "bech32", + "bitcoin-internals", + "bitcoin-io", + "bitcoin-units", + "bitcoin_hashes", + "hex-conservative", + "hex_lit", + "secp256k1 0.29.1", + "serde", +] + +[[package]] +name = "bitcoin-units" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5285c8bcaa25876d07f37e3d30c303f2609179716e11d688f51e8f1fe70063e2" +dependencies = [ + "bitcoin-internals", + "serde", +] + +[[package]] +name = "bitcoin_hashes" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb18c03d0db0247e147a21a6faafd5a7eb851c743db062de72018b6b7e8e4d16" +dependencies = [ + "bitcoin-io", + "hex-conservative", + "serde", +] + +[[package]] +name = "bitcoinpqc" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf74aafaea8106c29daed19657c3952a4f297d44fbd437d5dd697772bb463fc2" +dependencies = [ + "bindgen", + "bitmask-enum", + "cmake", + "hex", + "libc", + "secp256k1 0.31.1", + "serde", +] + +[[package]] +name = "bitcoinpqc" +version = "0.3.0" +source = "sparse+https://crates.denver.space/api/v1/crates/" +checksum = "5fbdb2a3ebd6701c141909f4b7f16165b848481c5c3f37a8bd7b273304ead5a6" +dependencies = [ + "bindgen", + "bitmask-enum", + "cmake", + "hex", + "libc", + "secp256k1 0.31.1", + "serde", +] + +[[package]] +name = "bitflags" +version = "2.9.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2261d10cca569e4643e526d8dc2e62e433cc8aba21ab764233731f8d369bf394" + +[[package]] +name = "bitmask-enum" +version = "2.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6cbbb8f56245b5a479b30a62cdc86d26e2f35c2b9f594bc4671654b03851380" +dependencies = [ + "quote", + "syn", +] + +[[package]] +name = "cc" +version = "1.2.41" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac9fe6cdbb24b6ade63616c0a0688e45bb56732262c158df3c0c4bea4ca47cb7" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cexpr" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766" +dependencies = [ + "nom", +] + +[[package]] +name = "cfg-if" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2fd1289c04a9ea8cb22300a459a72a385d7c73d3259e2ed7dcb2af674838cfa9" + +[[package]] +name = "clang-sys" +version = "1.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b023947811758c97c59bf9d1c188fd619ad4718dcaa767947df1cadb14f39f4" +dependencies = [ + "glob", + "libc", + "libloading", +] + +[[package]] +name = "cmake" +version = "0.1.54" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7caa3f9de89ddbe2c607f4101924c5abec803763ae9534e4f4d7d8f84aa81f0" +dependencies = [ + "cc", +] + +[[package]] +name = "colorchoice" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b05b61dc5112cbb17e4b6cd61790d9845d13888356391624cbe7e41efeac1e75" + +[[package]] +name = "either" +version = "1.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719" + +[[package]] +name = "env_filter" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "186e05a59d4c50738528153b83b0b0194d3a29507dfec16eccd4b342903397d0" +dependencies = [ + "log", + "regex", +] + +[[package]] +name = "env_logger" +version = "0.11.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13c863f0904021b108aa8b2f55046443e6b1ebde8fd4a15c399893aae4fa069f" +dependencies = [ + "anstream", + "anstyle", + "env_filter", + "jiff", + "log", +] + +[[package]] +name = "find-msvc-tools" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "52051878f80a721bb68ebfbc930e07b65ba72f2da88968ea5c06fd6ca3d3a127" + +[[package]] +name = "getrandom" +version = "0.2.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "335ff9f135e4384c8150d6f27c6daed433577f86b4750418338c01a1a2528592" +dependencies = [ + "cfg-if", + "libc", + "wasi 0.11.1+wasi-snapshot-preview1", +] + +[[package]] +name = "getrandom" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "26145e563e54f2cadc477553f1ec5ee650b00862f0a58bcd12cbdc5f0ea2d2f4" +dependencies = [ + "cfg-if", + "libc", + "r-efi", + "wasi 0.14.7+wasi-0.2.4", +] + +[[package]] +name = "glob" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280" + +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + +[[package]] +name = "hex-conservative" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5313b072ce3c597065a808dbf612c4c8e8590bdbf8b579508bf7a762c5eae6cd" +dependencies = [ + "arrayvec", +] + +[[package]] +name = "hex_lit" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3011d1213f159867b13cfd6ac92d2cd5f1345762c63be3554e84092d85a50bbd" + +[[package]] +name = "is_terminal_polyfill" +version = "1.70.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7943c866cc5cd64cbc25b2e01621d07fa8eb2a1a23160ee81ce38704e97b8ecf" + +[[package]] +name = "itertools" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186" +dependencies = [ + "either", +] + +[[package]] +name = "itoa" +version = "1.0.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a5f13b858c8d314ee3e8f639011f7ccefe71f97f96e50151fb991f267928e2c" + +[[package]] +name = "jiff" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "be1f93b8b1eb69c77f24bbb0afdf66f54b632ee39af40ca21c4365a1d7347e49" +dependencies = [ + "jiff-static", + "log", + "portable-atomic", + "portable-atomic-util", + "serde", +] + +[[package]] +name = "jiff-static" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03343451ff899767262ec32146f6d559dd759fdadf42ff0e227c7c48f72594b4" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "libc" +version = "0.2.177" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2874a2af47a2325c2001a6e6fad9b16a53b802102b528163885171cf92b15976" + +[[package]] +name = "libloading" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55" +dependencies = [ + "cfg-if", + "windows-link", +] + +[[package]] +name = "log" +version = "0.4.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "34080505efa8e45a4b816c349525ebe327ceaa8559756f0356cba97ef3bf7432" + +[[package]] +name = "memchr" +version = "2.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f52b00d39961fc5b2736ea853c9cc86238e165017a493d1d5c8eac6bdc4cc273" + +[[package]] +name = "minimal-lexical" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a" + +[[package]] +name = "miniscript" +version = "13.0.0-p2mr-pqc-1.0" +source = "sparse+https://crates.denver.space/api/v1/crates/" +checksum = "aae6f58a3f729d916bf610da66391345706d36115a346efd0041be21c4fa058f" +dependencies = [ + "bech32", + "bitcoin-p2mr-pqc", + "bitcoinpqc 0.2.0", +] + +[[package]] +name = "nom" +version = "7.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a" +dependencies = [ + "memchr", + "minimal-lexical", +] + +[[package]] +name = "once_cell" +version = "1.21.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d" + +[[package]] +name = "once_cell_polyfill" +version = "1.70.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a4895175b425cb1f87721b59f0f286c2092bd4af812243672510e1ac53e2e0ad" + +[[package]] +name = "p2mr-ref" +version = "0.1.0" +dependencies = [ + "anyhow", + "bitcoin-p2mr-pqc", + "bitcoinpqc 0.3.0", + "env_logger", + "hex", + "log", + "miniscript", + "once_cell", + "rand 0.9.2", + "serde", + "serde_json", + "thiserror", +] + +[[package]] +name = "portable-atomic" +version = "1.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f84267b20a16ea918e43c6a88433c2d54fa145c92a811b5b047ccbe153674483" + +[[package]] +name = "portable-atomic-util" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d8a2f0d8d040d7848a709caf78912debcc3f33ee4b3cac47d73d1e1069e83507" +dependencies = [ + "portable-atomic", +] + +[[package]] +name = "ppv-lite86" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9" +dependencies = [ + "zerocopy", +] + +[[package]] +name = "prettyplease" +version = "0.2.37" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b" +dependencies = [ + "proc-macro2", + "syn", +] + +[[package]] +name = "proc-macro2" +version = "1.0.101" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "89ae43fd86e4158d6db51ad8e2b80f313af9cc74f5c0e03ccb87de09998732de" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.41" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce25767e7b499d1b604768e7cde645d14cc8584231ea6b295e9c9eb22c02e1d1" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + +[[package]] +name = "rand" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" +dependencies = [ + "libc", + "rand_chacha 0.3.1", + "rand_core 0.6.4", +] + +[[package]] +name = "rand" +version = "0.9.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1" +dependencies = [ + "rand_chacha 0.9.0", + "rand_core 0.9.3", +] + +[[package]] +name = "rand_chacha" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88" +dependencies = [ + "ppv-lite86", + "rand_core 0.6.4", +] + +[[package]] +name = "rand_chacha" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb" +dependencies = [ + "ppv-lite86", + "rand_core 0.9.3", +] + +[[package]] +name = "rand_core" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" +dependencies = [ + "getrandom 0.2.16", +] + +[[package]] +name = "rand_core" +version = "0.9.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "99d9a13982dcf210057a8a78572b2217b667c3beacbf3a0d8b454f6f82837d38" +dependencies = [ + "getrandom 0.3.3", +] + +[[package]] +name = "regex" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a52d8d02cacdb176ef4678de6c052efb4b3da14b78e4db683a4252762be5433" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "regex-automata" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "722166aa0d7438abbaa4d5cc2c649dac844e8c56d82fb3d33e9c34b5cd268fc6" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3160422bbd54dd5ecfdca71e5fd59b7b8fe2b1697ab2baf64f6d05dcc66d298" + +[[package]] +name = "rustc-hash" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d" + +[[package]] +name = "ryu" +version = "1.0.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "28d3b2b1366ec20994f1fd18c3c594f05c5dd4bc44d8bb0c1c632c8d6829481f" + +[[package]] +name = "secp256k1" +version = "0.29.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9465315bc9d4566e1724f0fffcbcc446268cb522e60f9a27bcded6b19c108113" +dependencies = [ + "bitcoin_hashes", + "rand 0.8.5", + "secp256k1-sys 0.10.1", + "serde", +] + +[[package]] +name = "secp256k1" +version = "0.31.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c3c81b43dc2d8877c216a3fccf76677ee1ebccd429566d3e67447290d0c42b2" +dependencies = [ + "bitcoin_hashes", + "rand 0.9.2", + "secp256k1-sys 0.11.0", + "serde", +] + +[[package]] +name = "secp256k1-sys" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d4387882333d3aa8cb20530a17c69a3752e97837832f34f6dccc760e715001d9" +dependencies = [ + "cc", +] + +[[package]] +name = "secp256k1-sys" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dcb913707158fadaf0d8702c2db0e857de66eb003ccfdda5924b5f5ac98efb38" +dependencies = [ + "cc", +] + +[[package]] +name = "serde" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.145" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "402a6f66d8c709116cf22f558eab210f5a50187f702eb4d7e5ef38d9a7f1c79c" +dependencies = [ + "itoa", + "memchr", + "ryu", + "serde", + "serde_core", +] + +[[package]] +name = "shlex" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" + +[[package]] +name = "syn" +version = "2.0.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ede7c438028d4436d71104916910f5bb611972c5cfd7f89b8300a8186e6fada6" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "thiserror" +version = "2.0.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f63587ca0f12b72a0600bcba1d40081f830876000bb46dd2337a3051618f4fc8" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ff15c8ecd7de3849db632e14d18d2571fa09dfc5ed93479bc4485c7a517c913" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "unicode-ident" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f63a545481291138910575129486daeaf8ac54aee4387fe7906919f7830c7d9d" + +[[package]] +name = "utf8parse" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "wasi" +version = "0.14.7+wasi-0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "883478de20367e224c0090af9cf5f9fa85bed63a95c1abf3afc5c083ebc06e8c" +dependencies = [ + "wasip2", +] + +[[package]] +name = "wasip2" +version = "1.0.1+wasi-0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0562428422c63773dad2c345a1882263bbf4d65cf3f42e90921f787ef5ad58e7" +dependencies = [ + "wit-bindgen", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-targets" +version = "0.53.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3" +dependencies = [ + "windows-link", + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006" + +[[package]] +name = "windows_i686_gnu" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c" + +[[package]] +name = "windows_i686_msvc" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650" + +[[package]] +name = "wit-bindgen" +version = "0.46.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f17a85883d4e6d00e8a97c586de764dabcc06133f7f1d55dce5cdc070ad7fe59" + +[[package]] +name = "zerocopy" +version = "0.8.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0894878a5fa3edfd6da3f88c4805f4c8558e2b996227a3d864f47fe11e38282c" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "88d2b8d9c68ad2b9e4340d7832716a4d21a22a1154777ad56ea55c51a9cf3831" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] diff --git a/bip-0360/ref-impl/rust/Cargo.toml b/bip-0360/ref-impl/rust/Cargo.toml new file mode 100644 index 0000000000..1c94d5f46b --- /dev/null +++ b/bip-0360/ref-impl/rust/Cargo.toml @@ -0,0 +1,40 @@ +[package] +name = "p2mr-ref" +version = "0.1.0" +edition = "2024" + +[dependencies] + +# Dev version of miniscript crate re-exports bitcoin 0.32.6 +# view configuration for "kellnr-denver-space": +# cat .cargo/config.toml +miniscript = { version="=13.0.0-p2mr-pqc-1.0", registry="kellnr-denver-space" } +bitcoin = { package = "bitcoin-p2mr-pqc", version="0.32.6-p2mr-pqc.1", features = ["rand-std", "serde", "base64"], registry = "kellnr-denver-space" } +bitcoinpqc = { version="0.3.0", features = ["serde"], registry="kellnr-denver-space" } + +# BDK Wallet with P2MR support +#bdk_wallet = { version = "=3.0.0-alpha.0-pqc-0.1", registry = "kellnr-denver-space" } + +env_logger = "0.11.5" +log = "0.4.22" +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" +once_cell = "1.19" +hex = "0.4.3" +anyhow = "1.0.98" +thiserror = "2.0.12" +rand = "0.9" + +[patch.crates-io] + +#bitcoin = { git = "https://github.com/jbride/rust-bitcoin.git", branch = "p2mr" } + +# Verify: +# cargo update +# cargo tree -p bitcoin | more +# bitcoin = { path = "./rust-bitcoin/bitcoin" } + +# cargo tree -p miniscript | more +#miniscript = { path = "./rust-miniscript" } + +# bitcoinpqc = { path = "./libbitcoinpqc" } diff --git a/bip-0360/ref-impl/rust/README.md b/bip-0360/ref-impl/rust/README.md new file mode 100644 index 0000000000..52bc7327ad --- /dev/null +++ b/bip-0360/ref-impl/rust/README.md @@ -0,0 +1,45 @@ + +# p2mr test vectors + +This rust project contains the test vectors for BIP-360 + + +## Run Test Vectors + +These test vectors are being developed in conjunction with forks of [rust-bitcoin](https://github.com/jbride/rust-bitcoin/tree/p2mr) and [rust-miniscript](https://github.com/jbride/rust-miniscript/tree/p2mr-pqc) customized with p2mr functionality. + + +1. environment variables + ``` + // Specify Bitcoin network used when generating bip350 (bech32m) address + // Options: regtest, testnet, signet + // Default: mainnet + $ export BITCOIN_NETWORK= + ``` + +1. run a specific test: + ``` + $ cargo test test_p2mr_single_leaf_script_tree -- --nocapture + ``` + +## Local Development + + +All P2MR/PQC enabled bitcoin crates are temporarily available in a custom crate registry at: `https://crates.denver.space`. +These crates will be made available in `crates.io` in the near future. + +Subsequently, you will need to execute the following at the root of your rust workspace: + +```bash +mkdir .cargo \ + && echo '[registries.kellnr-denver-space] +index = "sparse+https://crates.denver.space/api/v1/crates/"' > .cargo/config +``` + +Afterwards, for all P2MR/PQC enabled dependencies used in your project, include a "registry" similar to the following: + +```bash +bitcoin = { version="0.32.6", registry = "kellnr-denver-space" } +``` + + diff --git a/bip-0360/ref-impl/rust/docs/development_notes.adoc b/bip-0360/ref-impl/rust/docs/development_notes.adoc new file mode 100644 index 0000000000..270b05ac63 --- /dev/null +++ b/bip-0360/ref-impl/rust/docs/development_notes.adoc @@ -0,0 +1,174 @@ + +== bitcoin core + +=== Two Different Size Limits: + +* *MAX_SCRIPT_ELEMENT_SIZE* (in interpreter.cpp line 1882) - This is a consensus rule that limits individual stack elements to 520 bytes. This is what's currently blocking your SLH-DSA signature. +* *MAX_STANDARD_P2MR_STACK_ITEM_SIZE* (in policy.h) - This is a policy rule that limits P2MR stack items to 80 bytes (or 8000 bytes with your change) for standardness. + +== P2MR changes to rust-bitcoin + +# 1. p2mr module + +The p2mr branch of rust-bitcoin includes a new module: `p2mr`. + +Source code for this new module can be found [here](https://github.com/jbride/rust-bitcoin/blob/p2mr/bitcoin/src/p2mr/mod.rs). + +Highlights of this _p2mr_ module as follows: + +## 1.1. p2mrBuilder + +This is struct inherits from the rust-bitcoin _TaprootBuilder_. +It has an important modification in that it disables keypath spend. + +Similar to its Taproot parent, p2mrBuilder provides functionality to add leaves to a TapTree. +One its TapTree has been fully populated with all leaves, an instance of _p2mrSpendInfo_ can be retrieved from p2mrBuilder. + + +``` +pub struct p2mrBuilder { + inner: TaprootBuilder +} + +impl p2mrBuilder { + + /// Creates a new p2mr builder. + pub fn new() -> Self { + Self { + inner: TaprootBuilder::new() + } + } + + /// Adds a leaf to the p2mr builder. + pub fn add_leaf_with_ver( + self, + depth: u8, + script: ScriptBuf, + leaf_version: LeafVersion, + ) -> Result { + match self.inner.add_leaf_with_ver(depth, script, leaf_version) { + Ok(builder) => Ok(Self { inner: builder }), + Err(_) => Err(p2mrError::LeafAdditionError) + } + } + + /// Finalizes the p2mr builder. + pub fn finalize(self) -> Result { + let node_info: NodeInfo = self.inner.try_into_node_info().unwrap(); + Ok(p2mrSpendInfo { + merkle_root: Some(node_info.node_hash()), + //script_map: self.inner.script_map().clone(), + }) + } + + /// Converts the p2mr builder into a Taproot builder. + pub fn into_inner(self) -> TaprootBuilder { + self.inner + } +} +``` + +## 1.2. p2mrSpendInfo + +Provides merkle_root of a completed p2mr TapTree + +``` +/// A struct for p2mr spend information. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct p2mrSpendInfo { + + /// The merkle root of the script path. + pub merkle_root: Option + +} +``` + +## 1.3. p2mrScriptBuf + +Allows for creation of a p2mr scriptPubKey UTXO using only the merkle root of a script tree only. + +``` +/// A wrapper around ScriptBuf for p2mr (Pay to Quantum Resistant Hash) scripts. +pub struct p2mrScriptBuf { + inner: ScriptBuf +} + +impl p2mrScriptBuf { + /// Creates a new p2mr script from a ScriptBuf. + pub fn new(inner: ScriptBuf) -> Self { + Self { inner } + } + + /// Generates p2mr scriptPubKey output + /// Only accepts the merkle_root (of type TapNodeHash) + /// since keypath spend is disabled in p2mr + pub fn new_p2mr(merkle_root: TapNodeHash) -> Self { + // https://github.com/cryptoquick/bips/blob/p2mr/bip-0360.mediawiki#scriptpubkey + let merkle_root_hash_bytes: [u8; 32] = merkle_root.to_byte_array(); + let script = Builder::new() + .push_opcode(OP_PUSHNUM_3) + + // automatically pre-fixes with OP_PUSHBYTES_32 (as per size of hash) + .push_slice(&merkle_root_hash_bytes) + + .into_script(); + p2mrScriptBuf::new(script) + } + + /// Returns the script as a reference. + pub fn as_script(&self) -> &Script { + self.inner.as_script() + } +} +``` + +## 1.4. p2mr Control Block + +Closely related to P2TR control block. +Difference being that _internal public key_ is not included. + + +``` +/// A control block for p2mr (Pay to Quantum Resistant Hash) script path spending. +/// This is a simplified version of Taproot's control block that excludes key-related fields. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct p2mrControlBlock { + /// The version of the leaf. + pub leaf_version: LeafVersion, + /// The merkle branch of the leaf. + pub merkle_branch: TaprootMerkleBranch, +} +``` + +# 2. Witness Program + +New p2mr related functions that allow for creation of a new V3 _witness program_ given a merkle_root only. + +Found in bitcoin/src/blockdata/script/witness_program.rs + +``` +/// Creates a [`WitnessProgram`] from a 32 byte merkle root. +fn new_p2mr(program: [u8; 32]) -> Self { + WitnessProgram { version: WitnessVersion::V3, program: ArrayVec::from_slice(&program) } +} + +/// Creates a pay to quantum resistant hash address from a merkle root. +pub fn p2mr(merkle_root: Option) -> Self { + let merkle_root = merkle_root.unwrap(); + WitnessProgram::new_p2mr(merkle_root.to_byte_array()) +} +``` + +# 3. Address + +New _p2mr_ function that allows for creation of a new _p2mr_ Address given a merkle_root only. + +Found in bitcoin/src/address/mod.rs + +``` +/// Creates a pay to quantum resistant hash address from a merkle root. +pub fn p2mr(merkle_root: Option, hrp: impl Into) -> Address { + let program = WitnessProgram::p2mr(merkle_root); + Address::from_witness_program(program, hrp) +} +``` diff --git a/bip-0360/ref-impl/rust/docs/images/crypto_key_characteristics.png b/bip-0360/ref-impl/rust/docs/images/crypto_key_characteristics.png new file mode 100644 index 0000000000..901d57a859 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/crypto_key_characteristics.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/faucet_1.png b/bip-0360/ref-impl/rust/docs/images/faucet_1.png new file mode 100644 index 0000000000..826057475b Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/faucet_1.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/faucet_2.png b/bip-0360/ref-impl/rust/docs/images/faucet_2.png new file mode 100644 index 0000000000..4ac08e24c4 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/faucet_2.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/funding_utxo_id.png b/bip-0360/ref-impl/rust/docs/images/funding_utxo_id.png new file mode 100644 index 0000000000..e409d695bb Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/funding_utxo_id.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/mempool_next_block.png b/bip-0360/ref-impl/rust/docs/images/mempool_next_block.png new file mode 100644 index 0000000000..89754f1411 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/mempool_next_block.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/mempool_spending_tx_1.png b/bip-0360/ref-impl/rust/docs/images/mempool_spending_tx_1.png new file mode 100644 index 0000000000..14aa99bc94 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/mempool_spending_tx_1.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/mempool_spending_tx_2.png b/bip-0360/ref-impl/rust/docs/images/mempool_spending_tx_2.png new file mode 100644 index 0000000000..e92fada18c Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/mempool_spending_tx_2.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/merkletree.png b/bip-0360/ref-impl/rust/docs/images/merkletree.png new file mode 100644 index 0000000000..a4ed868819 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/merkletree.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/p2mr_construction.png b/bip-0360/ref-impl/rust/docs/images/p2mr_construction.png new file mode 100644 index 0000000000..9ac23a5f93 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/p2mr_construction.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/p2mr_witness.png b/bip-0360/ref-impl/rust/docs/images/p2mr_witness.png new file mode 100644 index 0000000000..b1e7c72c85 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/p2mr_witness.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/tap_tree_concatenated.png b/bip-0360/ref-impl/rust/docs/images/tap_tree_concatenated.png new file mode 100644 index 0000000000..7a392eecc9 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/tap_tree_concatenated.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/tap_tree_mixed.png b/bip-0360/ref-impl/rust/docs/images/tap_tree_mixed.png new file mode 100644 index 0000000000..d4c0a7d6b1 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/tap_tree_mixed.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/tap_tree_schnorr_only.png b/bip-0360/ref-impl/rust/docs/images/tap_tree_schnorr_only.png new file mode 100644 index 0000000000..9445608596 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/tap_tree_schnorr_only.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/tap_tree_slh_dsa_only.png b/bip-0360/ref-impl/rust/docs/images/tap_tree_slh_dsa_only.png new file mode 100644 index 0000000000..eb51b26fc9 Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/tap_tree_slh_dsa_only.png differ diff --git a/bip-0360/ref-impl/rust/docs/images/workshop_deployment_arch.png b/bip-0360/ref-impl/rust/docs/images/workshop_deployment_arch.png new file mode 100644 index 0000000000..8435e2181a Binary files /dev/null and b/bip-0360/ref-impl/rust/docs/images/workshop_deployment_arch.png differ diff --git a/bip-0360/ref-impl/rust/docs/p2mr-end-to-end.adoc b/bip-0360/ref-impl/rust/docs/p2mr-end-to-end.adoc new file mode 100644 index 0000000000..f09c5bc117 --- /dev/null +++ b/bip-0360/ref-impl/rust/docs/p2mr-end-to-end.adoc @@ -0,0 +1,527 @@ +:scrollbar: +:data-uri: +:toc2: +:linkattrs: + += P2MR End-to-End Tutorial + +:numbered: + +This tutorial is inspired by the link:https://learnmeabitcoin.com/technical/upgrades/taproot/#example-3-script-path-spend-signature[script-path-spend-signature] example of the _learnmeabitcoin_ tutorial. + +It is customized to create, fund and spend from a P2MR UTXO to a P2WPKH address. + +In addition, this tutorial allows for the (un)locking mechanism of the script to optionally use _Post Quantum Cryptography_ (PQC). + +The purpose of this tutorial is to demonstrate construction and spending of a link:https://github.com/cryptoquick/bips/blob/p2qrh/bip-0360.mediawiki[bip-360] `p2mr` UTXO (optionally using _Post-Quantum Cryptography_). + +The steps outlined in this tutorial are executed using a custom Bitcoin Core instance running either in `regtest` or `signet`. + +== Pre-reqs + +=== Bitcoin Core + +If participating in a workshop, your instructor will provide a bitcoin environment. +Related: your instructor should also provide you with a wallet. + +Otherwise, if running this tutorial on your own, follow the instructions in the appendix of this doc: <>. + + +=== Shell Environment + +. *docker / podman* ++ +NOTE: If you have built the custom `p2mr` enabled Bitcoin Core, you do not need docker (nor podman) installed. Skip this section. ++ +This tutorial makes use of a `p2mr` enabled _bitcoin-cli_ utility. +This utility is made available as a docker (or podman) container. +Ensure your host machine has either docker or podman installed. + +. *bitcoin-cli* command line utility: ++ +NOTE: If you have built the custom `p2mr` enabled Bitcoin Core, you can simply use the `bitcoin-cli` utility found in the `build/bin/` directory. No need to use the _dockerized_ utility described below. + +.. You will need a `bitcoin-cli` binary that is `p2mr` enabled. +For this purpose, a docker container with this `bitcoin-cli` utility is provided: ++ +----- +docker pull quay.io/jbride2000/bitcoin-cli:p2mr-pqc-0.0.1 +----- + +.. Configure an alias to the `bitcoin-cli` command that connects to your customized bitcoin-core node. ++ +----- +alias b-cli='docker run --rm --network host bitcoin-cli:p2mr-pqc-0.0.1 -rpcconnect=192.168.122.1 -rpcport=18443 -rpcuser=regtest -rpcpassword=regtest' +----- + +. *jq*: ensure json parsing utility is link:https://jqlang.org/download/[installed] and available via your $PATH. +. *awk* : standard utility for all Linux distros (often packaged as `gawk`). +. *Rust* development environment with _cargo_ utility. Use link:https://rustup[Rustup] to install. + +== Create & Fund P2MR UTXO + +The purpose of this workshop is to demonstrate construction and spending of a link:https://github.com/cryptoquick/bips/blob/p2qrh/bip-0360.mediawiki[bip-360] _P2MR_ address (optionally using _Post-Quantum Cryptography_). + +In this section of the workshop, you create and fund a P2MR address. + +The following depicts the construction of a P2MR _TapTree_ and computation its _scriptPubKey_. + +image::images/p2mr_construction.png[] + +A P2MR address is created by adding locking scripts to leaves of a _TapTree_. +The locking scripts can use either _Schnorr_ (as per BIP-360) or _SLH-DSA_ (defined in a future BIP) cryptography. + +. Set an environment variable specific to your Bitcoin network environment (regtest, signet, etc) ++ +[source,bash] +----- +export BITCOIN_NETWORK=regtest +----- ++ +Doing so influences the P2MR address that you'll create later in this tutorial. + + +. Define number of total leaves in tap tree : ++ +[source,bash] +----- +export TOTAL_LEAF_COUNT=5 +----- + +. OPTIONAL: Indicate what type of cryptography to use in the locking scripts of your TapTree leaves. +Valid options are: `MIXED`, `SCHNORR_ONLY`, `SLH_DSA_ONLY`, and `CONCATENATED_SCHNORR_AND_SLH_DSA`. +Default is `MIXED`. ++ +[source,bash] +----- +export TAP_TREE_LOCK_TYPE=MIXED +----- + +.. If you set _TAP_TREE_LOCK_TYPE=SCHNORR_ONLY_, then the locking script of your TapTree leaves will utilize _Schnorr_ cryptography. ++ +Schnorr is not quantum-resistant. However, its signature size is relatively small: 64 bytes. +A _SCHNORR_ONLY_ tap tree with 5 leaves (aka: TOTAL_LEAF_COUNT) could be represented as follows: ++ +image::images/tap_tree_schnorr_only.png[s,300] + +.. If you set _TAP_TREE_LOCK_TYPE=SLH_DSA_ONLY_, then the locking script of your TapTree leaves will utilize _SLH-DSA_ cryptography. +A _SLH_DSA_ONLY_ tap tree with 5 leaves (aka: TOTAL_LEAF_COUNT) could be represented as follows: ++ +image::images/tap_tree_slh_dsa_only.png[l,300] ++ +SLH_DSA is quantum-resistant. However, the trade-off is the much larger signature size 7,856 bytes when spending. ++ +image::images/crypto_key_characteristics.png[] ++ +NOTE: PQC cryptography is made available to this BIP-360 reference implementation via the link:https://crates.io/crates/bitcoinpqc[libbitcoinpqc Rust bindings]. + +.. If you set _MIXED_, then each leaf of the taptree will consist of *either* a Schnorr based locking script or a SLH-DSA based locking script. +A _MIXED_ tap tree with 5 leaves (aka: TOTAL_LEAF_COUNT) could be represented as follows: ++ +image::images/tap_tree_mixed.png[t,300] ++ +NOTE: The benefit of constructing a taptree with a mixed set of cryptography used as locking scripts in the leaves is articulated nicely in link:https://www.bitmex.com/blog/Taproot%20Quantum%20Spend%20Paths[this article from BitMex]. + +.. If you set _TAP_TREE_LOCK_TYPE=CONCATENATED_SCHNORR_AND_SLH_DSA_, then the locking script of your TapTree leaves will be secured using both SCHNORR and SLH-DSA cryptography in a concatenated / serial manner. +Private keys for both SCHNORR and SLH-DSA will be needed when unlocking. +A _CONCATENATED_SCHNORR_AND_SLH_DSA_ tap tree with 5 leaves (aka: TOTAL_LEAF_COUNT) could be represented as follows: ++ +image::images/tap_tree_concatenated.png[p,300] + +. Set the tap leaf index to later use as the unlocking script (when spending) For example, to later spend from the 5th leaf of the tap tree: ++ +[source,bash] +----- +export LEAF_TO_SPEND_FROM=4 +----- + +. Generate a P2MR scripPubKey with multi-leaf taptree: ++ +[source,bash] +----- +export BITCOIN_ADDRESS_INFO=$( cargo run --example p2mr_construction ) \ + && echo $BITCOIN_ADDRESS_INFO | jq -r . +----- ++ +NOTE: In `regtest`, you can expect a P2MR address that starts with: `bcrt1z` . ++ +[subs=+quotes] +++++ +
+What just happened? +The Rust based reference implementation for BIP-0360 is leveraged to construct a transaction with a `p2mr` UTXO as follows: + +
    +
  • A configurable number of leaves are generated each with their own locking script.
    • +
  • Each of these leaves are added to a Huffman tree that sorts the leaves by weight.
    • +
  • The merkle root of the tree is calculated and subsequently used to generate the p2mr witness program and BIP0350 address.
    • +
+

+The source code for the above logic is found in this project: src/lib.rs + +
+++++ + +. Only if you previously set `TAP_TREE_LOCK_TYPE=MIXED`, set the environment variable `SPENDING_LEAF_TYPE`. +Valid values are `SHNORR_ONLY` or `SLH_DSA_ONLY` based on the type of locking script that was used in the leaf you will spend from later in this lab. The logs from the previous step tell you the appropriate value to set. For instance: ++ +----- +NOTE: TAP_TREE_LOCK_TYPE=MIXED requires setting SPENDING_LEAF_TYPE when spending (based on leaf_script_type in output above) as follows: + export SPENDING_LEAF_TYPE=SCHNORR_ONLY +----- + +. Set some env vars (for use in later steps in this tutorial) based on previous result: ++ +[source,bash] +----- +export MERKLE_ROOT=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.tree_root_hex' ) \ + && export LEAF_SCRIPT_PRIV_KEYS_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.leaf_script_priv_keys_hex' ) \ + && export LEAF_SCRIPT_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.leaf_script_hex' ) \ + && export CONTROL_BLOCK_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.control_block_hex' ) \ + && export FUNDING_SCRIPT_PUBKEY=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.utxo_return.script_pubkey_hex' ) \ + && export P2MR_ADDR=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.utxo_return.bech32m_address' ) +----- + +. View tapscript used in target leaf of taptree: ++ +[source,bash] +----- +b-cli decodescript $LEAF_SCRIPT_HEX | jq -r '.asm' +----- ++ +NOTE: If not using PQC, notice that this script commits to a Schnorr 32-byte x-only public key. +If using PQC, this script commits to a Schnorr 32-byte SLH-DSA pub key and a OP_SUCCESS127 (represented as `OP_SUBSTR`) opcode. + +. Fund this P2MR address with the coinbase reward of a newly generated block: ++ +Choose from one of the following networks: + +.. Regtest ++ +If on `regtest` network, execute the following: ++ +[source,bash] +----- +export COINBASE_REWARD_TX_ID=$( b-cli -named generatetoaddress nblocks=1 address="$P2MR_ADDR" maxtries=5 | jq -r '.[]' ) \ + && echo $COINBASE_REWARD_TX_ID +----- ++ +NOTE: Sometimes Bitcoin Core may not hit a block (even on regtest). If so, just try the above command again. + +.. Signet ++ +If on `signet` network, then execute the following: ++ +[source,bash] +----- +$BITCOIN_SOURCE_DIR/contrib/signet/miner --cli "bitcoin-cli -conf=$HOME/anduro-360/configs/bitcoin.conf.signet" generate \ + --address $P2MR_ADDR \ + --grind-cmd "$BITCOIN_SOURCE_DIR/build/bin/bitcoin-util grind" \ + --min-nbits --set-block-time $(date +%s) \ + --poolid "MARA Pool" +----- + +. view summary of all txs that have funded P2MR address ++ +[source,bash] +----- +export P2MR_DESC=$( b-cli getdescriptorinfo "addr($P2MR_ADDR)" | jq -r '.descriptor' ) \ + && echo $P2MR_DESC \ + && b-cli scantxoutset start '[{"desc": "'''$P2MR_DESC'''"}]' +----- + +. grab txid of first tx with unspent funds: ++ +[source,bash] +----- +export FUNDING_TX_ID=$( b-cli scantxoutset start '[{"desc": "'''$P2MR_DESC'''"}]' | jq -r '.unspents[0].txid' ) \ + && echo $FUNDING_TX_ID +----- + +. Set FUNDING_UTXO_INDEX env var (used later to correctly identify funding UTXO when generating the spending tx) ++ +[source,bash] +----- +export FUNDING_UTXO_INDEX=0 +----- + +. view details of funding UTXO to the P2MR address: ++ +[source,bash] +----- +export FUNDING_UTXO=$( b-cli getrawtransaction $FUNDING_TX_ID 1 | jq -r '.vout['''$FUNDING_UTXO_INDEX''']' ) \ + && echo $FUNDING_UTXO | jq -r . +----- ++ +NOTE: the above only works when Bitcoin Core is started with the following arg: -txindex + + +== Spend P2MR UTXO + +In the previous section, you created and funded a P2MR UTXO. +That UTXO includes a leaf script locked with a key-pair (optionally based on PQC) known to you. + +In this section, you spend from that P2MR UTXO. +Specifically, you will generate an appropriate _SigHash_ and sign it (to create a signature) using the known private key that unlocks the known leaf script of the P2MR UTXO. + +For the purpose of this tutorial, you will spend funds to a new P2WPKH utxo. (there is nothing novel about this P2WPKH utxo). + + +. Determine value (in sats) of the funding P2MR utxo: ++ +[source,bash] +----- +export FUNDING_UTXO_AMOUNT_SATS=$(echo $FUNDING_UTXO | jq -r '.value' | awk '{printf "%.0f", $1 * 100000000}') \ + && echo $FUNDING_UTXO_AMOUNT_SATS +----- + +. Generate additional blocks. ++ +This is necessary if you have only previously generated less than 100 blocks. ++ +Otherwise, you may see an error from bitcoin core such as the following when attempting to spend: ++ +_bad-txns-premature-spend-of-coinbase, tried to spend coinbase at depth 1_ + +.. regtest ++ +[source,bash] +----- +b-cli -generate 110 +----- + +.. signet ++ +This will involve having the signet miner generate about 110 blocks .... which can take about 10 minutes. ++ +The `common/utils` directory of this project provides a script called: link:../../common/utils/signet_miner_loop.sh[signet_miner_loop.sh]. + + +. Referencing the funding tx (via $FUNDING_TX_ID and $FUNDING_UTXO_INDEX), create the spending tx: ++ +[source,bash] +----- +export SPEND_DETAILS=$( cargo run --example p2mr_spend ) +----- ++ +[subs=+quotes] +++++ +
+What just happened? +The Rust based reference implementation for BIP-0360 is leveraged to construct a transaction that spends from the `p2mr` UTXO as follows: + +
    +
  • Create a transaction template (aka: SigHash) that serves as the message to be signed.
    • +
  • Using the known private key and the SigHash, create a signature that is capable of unlocking one of the leaf scripts of the P2MR tree.
    • +
  • Add this signature to the witness section of the transaction.
    • +
+

+The source code for the above logic is found in this project: src/lib.rs + +
+++++ + +. Set environment variables passed to _bitcoin-cli_ when spending: ++ +[source,bash] +----- +export RAW_P2MR_SPEND_TX=$( echo $SPEND_DETAILS | jq -r '.tx_hex' ) \ + && echo "RAW_P2MR_SPEND_TX = $RAW_P2MR_SPEND_TX" \ + && export SIG_HASH=$( echo $SPEND_DETAILS | jq -r '.sighash' ) \ + && echo "SIG_HASH = $SIG_HASH" \ + && export SIG_BYTES=$( echo $SPEND_DETAILS | jq -r '.sig_bytes' ) \ + && echo "SIG_BYTES = $SIG_BYTES" +----- + +. Inspect the spending tx: ++ +[source,bash] +----- +b-cli decoderawtransaction $RAW_P2MR_SPEND_TX +----- ++ +Pay particular attention to the `vin.txinwitness` field. +Do the three elements (script input, script and control block) of the witness stack for this script path spend make sense ? +What do you observe as the first byte of the `control block` element ? + +. Test standardness of the spending tx by sending to local mempool of p2mr enabled Bitcoin Core: ++ +[source,bash] +----- +b-cli testmempoolaccept '["'''$RAW_P2MR_SPEND_TX'''"]' +----- + +. Submit tx: ++ +[source,bash] +----- +export P2MR_SPENDING_TX_ID=$( b-cli sendrawtransaction $RAW_P2MR_SPEND_TX ) \ + && echo $P2MR_SPENDING_TX_ID +----- ++ +NOTE: Should return same tx id as was included in $RAW_P2MR_SPEND_TX + +== Mine P2MR Spend TX + +. View tx in mempool: ++ +[source,bash] +----- +b-cli getrawtransaction $P2MR_SPENDING_TX_ID 1 +----- ++ +NOTE: There will not yet be a field `blockhash` in the response. + +. Mine 1 block: + +.. regtest: ++ +[source,bash] +----- +b-cli -generate 1 +----- + +.. signet: ++ +If on `signet` network, then execute the following: ++ +[source,bash] +----- +$BITCOIN_SOURCE_DIR/contrib/signet/miner --cli "bitcoin-cli -conf=$HOME/anduro-360/configs/bitcoin.conf.signet" generate \ + --address $P2MR_ADDR \ + --grind-cmd "$BITCOIN_SOURCE_DIR/build/bin/bitcoin-util grind" \ + --min-nbits --set-block-time $(date +%s) \ + --poolid "MARA Pool" +----- + +. Obtain `blockhash` field of mined tx: ++ +[source,bash] +----- +export BLOCK_HASH=$( b-cli getrawtransaction $P2MR_SPENDING_TX_ID 1 | jq -r '.blockhash' ) \ + && echo $BLOCK_HASH +----- + +. View tx in block: ++ +[source,bash] +----- +b-cli getblock $BLOCK_HASH | jq -r .tx +----- + +== Appendix + +[[build_p2mr]] +=== Build P2MR / PQC Enabled Bitcoin Core + +The link:https://github.com/jbride/bitcoin/tree/p2mr[p2mr branch] of bitcoin core is needed. + +Build instructions for the `p2mr` branch are the same as `master` and is documented link:https://github.com/bitcoin/bitcoin/blob/master/doc/build-unix.md[here]. + +As such, the following is an example series of steps (on a Fedora 42 host) to compile and run the `p2mr` branch of bitcoin core: + +. Set BITCOIN_SOURCE_DIR ++ +----- +export BITCOIN_SOURCE_DIR=/path/to/root/dir/of/cloned/bitcoin/source +----- + +. build ++ +----- +cmake -B build \ + -DWITH_ZMQ=ON \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ + -DBUILD_BENCH=ON \ + -DBUILD_DAEMON=ON \ + -DSANITIZERS=address,undefined + +cmake --build build -j$(nproc) +----- + +. run in either `regtest` or `signet` mode: + +.. regtest: ++ +----- +./build/bin/bitcoind -daemon=0 -regtest=1 -txindex -prune=0 +----- + +.. signet: ++ +----- +./build/bin/bitcoind -daemon=0 -signet=1 -txindex -prune=0 +----- ++ +NOTE: If running in `signet`, your bitcoin core will need to be configured with the `signetchallenge` property. +link:https://edil.com.br/blog/creating-a-custom-bitcoin-signet[This tutorial] provides a nice overview of the topic. + +=== libbitcoinpqc build + +The `p2mr-pqc` branch of this project includes a dependency on the link:https://crates.io/crates/libbitcoinpqc[libbitcoinpqc crate]. +libbitcoinpqc contains native code (C/C++/ASM) and is made available to Rust projects via Rust bindings. +This C/C++/ASM code is provided in the libbitcoinpqc crate as source code (not prebuilt binaries). + +Subsequently, the `Cargo` utility needs to build this libbitcoinpqc C native code on your local machine. +You will need to have C development related libraries installed on your local machine. + +Every developer or CI machine building `p2mr-ref` must have cmake and a C toolchain installed locally. + +==== Linux + +. Debian / Ubuntu ++ +----- +sudo apt update +sudo apt install cmake build-essential clang libclang-dev +----- + +. Fedora / RHEL ++ +----- +sudo dnf5 update +sudo dnf5 install cmake make gcc gcc-c++ clang clang-libs llvm-devel +----- + +==== OSX + +[[bitcoin_core_wallet]] +=== Bitcoin Core Wallet + +This tutorial assumes that a bitcoin core wallet is available. + +. For example, the following would be sufficient: ++ +----- + +export W_NAME=anduro + +b-cli -named createwallet \ + wallet_name=$W_NAME \ + descriptors=true \ + load_on_startup=true +----- + +=== Schnorr + SLH-DSA + +----- + OP_CHECKSIG OP_SUBSTR OP_BOOLAND OP_VERIFY +----- + + +The logic flow is: + +. OP_CHECKSIG: Verify Schnorr signature against Schnorr pubkey +. OP_SUBSTR: Verify SLH-DSA signature against SLH-DSA pubkey (using OP_SUBSTR for the SLH-DSA verification) +. OP_BOOLAND: Ensure both signature verifications succeeded +. OP_VERIFY: Final verification that the script execution succeeded +. This creates a "both signatures required" locking condition, which is exactly what you want for SCHNORR_AND_SLH_DSA scripts. + + +===== Sighash bytes + +Sighash bytes are appended to each signature, instead of being separate witness elements: + +. SlhDsaOnly: SLH-DSA signature + sighash byte appended +. SchnorrOnly: Schnorr signature + sighash byte appended +. SchnorrAndSlhDsa: Schnorr signature (no sighash) + SLH-DSA signature + sighash byte appended to the last signature diff --git a/bip-0360/ref-impl/rust/docs/p2mr-signet-workshop.adoc b/bip-0360/ref-impl/rust/docs/p2mr-signet-workshop.adoc new file mode 100644 index 0000000000..0afaaac8a4 --- /dev/null +++ b/bip-0360/ref-impl/rust/docs/p2mr-signet-workshop.adoc @@ -0,0 +1,524 @@ +:scrollbar: +:data-uri: +:toc2: +:linkattrs: + += P2MR End-to-End workshop + +:numbered: + +Welcome to the BIP-360 / _Pay-To-Tap-Script-Hash_ (P2MR) workshop ! + +In this workshop, you will interact with a custom Signet environment to create, fund and spend from a _P2MR_ address. + +_P2MR_ is a new Bitcoin address type defined in link:https://bip360.org/bip360.html[bip-360]. + + +In addition, this workshop allows for the (un)locking mechanism of the leaf scripts of your P2MR address to optionally use _Post Quantum Cryptography_ (PQC). +The use of PQC is alluded to in BIP-360 and will be further defined in future BIPs. + +The steps outlined in this workshop are executed using a P2MR/PQC enabled Bitcoin Core instance running on a signet environment. +*The target audience of the workshop is Bitcoin developers and ops personnel. +As such, the workshop makes heavy use of the _bitcoin-cli_ at the command line.* + +== Pre-reqs + +=== *docker / podman* + +This workshop environment is provided as a _docker_ container. +Subsequently, ensure your host machine has either link:https://docs.docker.com/desktop/[docker] or link:https://podman.io/docs/installation[podman] installed. + +=== *p2mr_demo* docker container + +==== Obtain container + +Once docker or podman is installed on your machine, you can obtain the workshop docker container via any of the following: + +. Pull from _quay.io_ : ++ +[source,bash] +----- +sudo docker pull quay.io/jbride2000/p2mr_demo:0.1 +----- ++ +NOTE: The container image is 1.76GB in size. This approach may be slow depending on network bandwidth. + +. Download container image archive file from local HTTP server: ++ +*TO_DO* + +. Obtain container image archive file from instructor: + +.. Workshop instructors have the container image available via USB thumb drives. +If you feel comfortable with this approach, ask an instructor for a thumb drive. + +... Mount the USB thumb drive and copy for the file called: _p2mr_demo-image.tar_. +... Load the container image into your docker environment as per the following: ++ +[source,bash] +----- +docker load -i /path/to/p2mr_demo-image.tar +----- + +==== Start container + +You will need to start the workshop container using the docker infrastructure on your machine. + +. If working at the command line, the following is an example to run the container and obtain a command prompt: ++ +[source,bash] +----- + +sudo docker run -it --rm --entrypoint /bin/bash --network host \ + -e RPC_CONNECT=10.21.3.194 \ + quay.io/jbride2000/p2mr_demo:0.1 +----- + +. You should see a _bash_ shell command prompt similar to the following: ++ +----- +bip360@0aa9edf3d201:~/bips/bip-0360/ref-impl/rust$ ls + + +Cargo.lock Cargo.toml README.md docs examples src tests +----- ++ +As per the `ls` command seen above, your command prompt path defaults to the link:https://github.com/jbride/bips/tree/p2mr/bip-0360/ref-impl/rust[Rust based reference implementation] for BIP-360. + +==== Container contents +Your docker environment already includes a P2MR/PQC enabled `bitcoin-cli` utility. +In addition, an alias to this custom bitcoin-cli utility configured for the signet workshop environment has also been provided. + +. You can view this alias as follows (execute all commands within workshop container image): ++ +[source,bash] +----- +declare -f b-cli +----- ++ +You should see a response similar to the following: ++ +----- +b-cli () +{ + /usr/local/bin/bitcoin-cli -rpcconnect=${RPC_CONNECT:-192.168.122.1} -rpcport=${RPC_PORT:-18443} -rpcuser=${RPC_USER:-signet} -rpcpassword=${RPC_PASSWORD:-signet} "$@" +} +----- + +. Test interaction between your _b-cli_ utility and the workshop's signet node via the following: ++ +[source,bash] +----- +b-cli getnetworkinfo +----- ++ +[source,bash] +----- +b-cli getblockcount +----- + +. In addition, your docker environment also comes pre-installed with the following utilities needed for this workshop: + +. *jq*: json parsing utility +. *awk* +. *Rust* development environment with _cargo_ utility + +== Bitcoin Environment + +Your workshop instructors have provided you with a _P2MR/PQC_ enabled Bitcoin environment running in _signet_. + +You will send RPC commands to this custom Bitcoin node via the _b-cli_of your docker container. + +image::images/workshop_deployment_arch.png[] + +Via your browser, you will interact with the P2MR enabled _mempool.space_ for the workshop at: link:http://signet.bip360.org[signet.bip360.org]. + + +== Create & Fund P2MR Address + +The purpose of this workshop is to demonstrate construction and spending of a link:https://github.com/cryptoquick/bips/blob/p2qrh/bip-0360.mediawiki[bip-360] _P2MR_ address (optionally using _Post-Quantum Cryptography_). + +In this section of the workshop, you create and fund a P2MR address. + +The following depicts the construction of a P2MR _TapTree_ and computation its _scriptPubKey_. + +image::images/p2mr_construction.png[] + +A P2MR address is created by adding locking scripts to leaves of a _TapTree_. +The locking scripts can use either _Schnorr_ (as per BIP-360) or _SLH-DSA_ (defined in a future BIP) cryptography. + +. Define number of total leaves in tap tree : ++ +[source,bash] +----- +export TOTAL_LEAF_COUNT=5 +----- + +. In your container image, indicate what type of cryptography to use in the locking scripts of your TapTree leaves. +Valid options are: `MIXED`, `SLH_DSA_ONLY`, `SCHNORR_ONLY`, `CONCATENATED_SCHNORR_AND_SLH_DSA`. +Default is `MIXED`. ++ +[source,bash] +----- +export TAP_TREE_LOCK_TYPE=MIXED +----- + +.. If you set _TAP_TREE_LOCK_TYPE=SCHNORR_ONLY_, then the locking script of your TapTree leaves will utilize _Schnorr_ cryptography. ++ +Schnorr is not quantum-resistant. However, its signature size is relatively small: 64 bytes. +A _SCHNORR_ONLY_ tap tree with 5 leaves (aka: TOTAL_LEAF_COUNT) could be represented as follows: ++ +image::images/tap_tree_schnorr_only.png[s,300] + +.. If you set _TAP_TREE_LOCK_TYPE=SLH_DSA_ONLY_, then the locking script of your TapTree leaves will utilize _SLH-DSA_ cryptography. +A _SLH_DSA_ONLY_ tap tree with 5 leaves (aka: TOTAL_LEAF_COUNT) could be represented as follows: ++ +image::images/tap_tree_slh_dsa_only.png[l,300] ++ +SLH_DSA is quantum-resistant. However, the trade-off is the much larger signature size 7,856 bytes when spending. ++ +image::images/crypto_key_characteristics.png[] ++ +NOTE: PQC cryptography is made available to this BIP-360 reference implementation via the link:https://crates.io/crates/bitcoinpqc[libbitcoinpqc Rust bindings]. + +.. If you set _MIXED_, then each leaf of the taptree will consist of *either* a Schnorr based locking script or a SLH-DSA based locking script. +A _MIXED_ tap tree with 5 leaves (aka: TOTAL_LEAF_COUNT) could be represented as follows: ++ +image::images/tap_tree_mixed.png[t,300] ++ +NOTE: The benefit of constructing a taptree with a mixed set of cryptography used as locking scripts in the leaves is articulated nicely in link:https://www.bitmex.com/blog/Taproot%20Quantum%20Spend%20Paths[this article from BitMex]. + +.. If you set _TAP_TREE_LOCK_TYPE=CONCATENATED_SCHNORR_AND_SLH_DSA_, then the locking script of your TapTree leaves will be secured using both SCHNORR and SLH-DSA cryptography in a concatenated / serial manner. +Private keys for both SCHNORR and SLH-DSA will be needed when unlocking. +A _CONCATENATED_SCHNORR_AND_SLH_DSA_ tap tree with 5 leaves (aka: TOTAL_LEAF_COUNT) could be represented as follows: ++ +image::images/tap_tree_concatenated.png[p,300] + +. Set the tap leaf index to later use as the unlocking script (when spending) For example, to later spend from the 5th leaf of the tap tree: ++ +[source,bash] +----- +export LEAF_TO_SPEND_FROM=4 +----- + +. Generate a P2MR scripPubKey with multi-leaf taptree: ++ +[source,bash] +----- +export BITCOIN_ADDRESS_INFO=$( cargo run --example p2mr_construction ) \ + && echo $BITCOIN_ADDRESS_INFO | jq -r . +----- ++ +NOTE: In signet, you can expect a P2MR address that starts with the following prefix: `tb1z` . ++ +[subs=+quotes] +++++ +
+What just happened? +The Rust based reference implementation for BIP-0360 is leveraged to construct a transaction with a P2MR UTXO as follows: + +
    +
  • A configurable number of leaves are generated each with their own locking script.
    • +
  • Each of these leaves are added to a Huffman tree that sorts the leaves by weight.
    • +
  • The merkle root of the tree is calculated and subsequently used to generate the P2MR witness program and BIP0350 address.
    • +
+

+ +
+++++ ++ +The source code for the above logic is found in this project's source file: link:../src/lib.rs[src/lib.rs] + +. Only if you previously set `TAP_TREE_LOCK_TYPE=MIXED`, set the environment variable `SPENDING_LEAF_TYPE`. Valid values are `SHNORR_ONLY` or `SLH_DSA_ONLY` based on the type of locking script that was used in the leaf you will spend from later in this lab. The logs from the previous step tell you the appropriate value to set. For instance: ++ +----- +NOTE: TAP_TREE_LOCK_TYPE=MIXED requires setting SPENDING_LEAF_TYPE when spending (based on leaf_script_type in output above) as follows: + export SPENDING_LEAF_TYPE=SCHNORR_ONLY +----- + +. Fund this P2MR address using workshop's signet faucet + +.. In a browser tab, navigate to: link:http://faucet.bip360.org/[faucet.bip360.org]. +.. Copy-n-paste the value of `bech32m_address` (found in the json response from the previous step) ++ +image::images/faucet_1.png[] ++ +Press the `Request` button. +.. The faucet should allocate bitcoin to your address. ++ +image::images/faucet_2.png[] + +.. Click on the link of your transaction id. +This will take you a detailed view of the transaction. +Scroll down to the the _Inputs & Outputs_ section of the transaction and identify the _vout_ index of funds sent to your _P2MR_ address. ++ +image::images/funding_utxo_id.png[] + +.. Return back to your terminal and set a _FUNDING_UTXO_INDEX_ environment variable (used later to correctly identify funding UTXO when generating the spending tx) ++ +[source,bash] +----- +export FUNDING_UTXO_INDEX= +----- + +.. Return back to your browser tab at navigate to: link:https://signet.bip360.org[signet.bip360.org] and wait until a new block mines the transaction from the faucet that funded your P2MR address. ++ +image::images/mempool_next_block.png[] + +. Set some env vars (for use in later steps in this workshop) based on previous json result: ++ +[source,bash] +----- +export MERKLE_ROOT=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.tree_root_hex' ) \ + && export LEAF_SCRIPT_PRIV_KEYS_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.leaf_script_priv_keys_hex' ) \ + && export LEAF_SCRIPT_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.leaf_script_hex' ) \ + && export CONTROL_BLOCK_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.control_block_hex' ) \ + && export FUNDING_SCRIPT_PUBKEY=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.utxo_return.script_pubkey_hex' ) \ + && export P2MR_ADDR=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.utxo_return.bech32m_address' ) +----- + +. View tapscript used in target leaf of taptree: ++ +[source,bash] +----- +b-cli decodescript $LEAF_SCRIPT_HEX | jq -r '.asm' +----- ++ +NOTE: If not using Schnorr crypto, this script commits to a Schnorr 32-byte x-only public key. +If using SLH_DSA, this script commits to a 32-byte SLH-DSA pub key and a OP_SUCCESS127 (represented as `OP_SUBSTR`) opcode., +If using SCHNORR + SLH_DSA, then you should see a locking script in the leaf similar to the following: ++ +----- +886fc1edb7a8a364da65aef57343de451c1449d8a6c5b766fe150667d50d3e80 OP_CHECKSIG 479f93fbd251863c3e3e72da6e26ea82f87313da13090de10e57eca1f8b5e0f3 OP_SUBSTR OP_BOOLAND OP_VERIFY +----- + +. view summary of all txs that have funded P2MR address ++ +[source,bash] +----- +export P2MR_DESC=$( b-cli getdescriptorinfo "addr($P2MR_ADDR)" | jq -r '.descriptor' ) \ + && echo $P2MR_DESC \ + && b-cli scantxoutset start '[{"desc": "'''$P2MR_DESC'''"}]' +----- ++ +NOTE: You will likely have to wait a few minutes until a new block (containing the tx that funds your P2MR address) is mined. + +. grab txid of first tx with unspent funds: ++ +[source,bash] +----- +export FUNDING_TX_ID=$( b-cli scantxoutset start '[{"desc": "'''$P2MR_DESC'''"}]' | jq -r '.unspents[0].txid' ) \ + && echo $FUNDING_TX_ID +----- + +. view details of funding UTXO to the P2MR address: ++ +[source,bash] +----- +export FUNDING_UTXO=$( b-cli getrawtransaction $FUNDING_TX_ID 1 | jq -r '.vout['''$FUNDING_UTXO_INDEX''']' ) \ + && echo $FUNDING_UTXO | jq -r . +----- + + +== Spend P2MR UTXO + +In the previous section, you created and funded a P2MR UTXO. +That UTXO includes a leaf script locked with a key-pair (optionally based on PQC) known to you. + +In this section, you spend from that P2MR UTXO. +Specifically, you will generate an appropriate _SigHash_ and sign it (to create a signature) using the known private key that unlocks the known leaf script of the P2MR UTXO. + +The target address type that you send funds to is: P2WPKH. + + +. Determine value (in sats) of the funding P2MR utxo: ++ +[source,bash] +----- +export FUNDING_UTXO_AMOUNT_SATS=$(echo $FUNDING_UTXO | jq -r '.value' | awk '{printf "%.0f", $1 * 100000000}') \ + && echo $FUNDING_UTXO_AMOUNT_SATS +----- + +. Referencing the funding tx (via $FUNDING_TX_ID and $FUNDING_UTXO_INDEX), create the spending tx: ++ +[source,bash] +----- +export SPEND_DETAILS=$( cargo run --example p2mr_spend ) +----- ++ +[subs=+quotes] +++++ +
+What just happened? +The Rust based reference implementation for BIP-0360 is leveraged to construct a transaction that spends from the P2MR UTXO as follows: + +
    +
  • Create a transaction template (aka: SigHash) that serves as the message to be signed.
    • +
  • Using the known private key and the SigHash, create a signature that is capable of unlocking one of the leaf scripts of the P2MR tree.
    • +
  • Add this signature to the witness section of the transaction.
    • +
+

+ +
+++++ ++ +The source code for the above logic is found in this project's source file: link:../src/lib.rs[src/lib.rs] + +. Set environment variables passed to _bitcoin-cli_ when spending: ++ +[source,bash] +----- +export RAW_P2MR_SPEND_TX=$( echo $SPEND_DETAILS | jq -r '.tx_hex' ) \ + && echo "RAW_P2MR_SPEND_TX = $RAW_P2MR_SPEND_TX" \ + && export SIG_HASH=$( echo $SPEND_DETAILS | jq -r '.sighash' ) \ + && echo "SIG_HASH = $SIG_HASH" \ + && export SIG_BYTES=$( echo $SPEND_DETAILS | jq -r '.sig_bytes' ) \ + && echo "SIG_BYTES = $SIG_BYTES" +----- + +. Inspect the spending tx: ++ +[source,bash] +----- +b-cli decoderawtransaction $RAW_P2MR_SPEND_TX +----- ++ +Pay particular attention to the `vin.txinwitness` field. +The following depicts the elements of a P2MR witness stack. ++ +image::images/p2mr_witness.png[] ++ +Do the three elements (script input, script and control block) of the witness stack for this _script path spend_ correspond ? +What do you observe as the first byte of the `control block` element ? + + +. Test standardness of the spending tx by sending to local mempool of P2MR enabled Bitcoin Core: ++ +[source,bash] +----- +b-cli testmempoolaccept '["'''$RAW_P2MR_SPEND_TX'''"]' +----- + +. Submit tx: ++ +[source,bash] +----- +export P2MR_SPENDING_TX_ID=$( b-cli sendrawtransaction $RAW_P2MR_SPEND_TX ) \ + && echo $P2MR_SPENDING_TX_ID +----- ++ +NOTE: Should return same tx id as was included in $RAW_P2MR_SPEND_TX + +== Mine P2MR Spend TX + +. View tx in mempool: ++ +[source,bash] +----- +b-cli getrawtransaction $P2MR_SPENDING_TX_ID 1 +----- ++ +NOTE: There will not yet be a field `blockhash` in the response. + +. Monitor the mempool.space instance at link:http://signet.bip360.org[signet.bip360.org] until a new block is mined. + +. While still in the mempool.space instance at link:http://signet.bip360.org[signet.bip360.org], lookup your tx (denoted by: $P2MR_SPENDING_TX_ID ) in the top-right search bar: ++ +image::images/mempool_spending_tx_1.png[] ++ +Click on the `Details` button at the top-right of the `Inputs & Outputs` section. + +.. Study the elements of the `Witness. Approximately how large is each element of the witness stack? + +.. View the values of the `Previous output script` and `Previous output type` fields: ++ +image::images/mempool_spending_tx_2.png[] + +. Obtain `blockhash` field of mined tx: ++ +[source,bash] +----- +export BLOCK_HASH=$( b-cli getrawtransaction $P2MR_SPENDING_TX_ID 1 | jq -r '.blockhash' ) \ + && echo $BLOCK_HASH +----- + +. View txs in block: ++ +[source,bash] +----- +b-cli getblock $BLOCK_HASH | jq -r .tx +----- ++ +You should see your tx (as per $P2MR_SPENDING_TX_ID) in the list. ++ +Congratulations!! You have created, funded and spent from a P2MR address. + +== Appendix + +[[build_p2mr]] +=== Build P2MR / PQC Enabled Bitcoin Core + +*FOR THE PURPOSE OF THE WORKSHOP, YOU CAN IGNORE THIS SECTION* + +The link:https://github.com/jbride/bitcoin/tree/p2mr[p2mr branch] of bitcoin core is needed. + +Build instructions for the `p2mr` branch are the same as `master` and is documented link:https://github.com/bitcoin/bitcoin/blob/master/doc/build-unix.md[here]. + +As such, the following is an example series of steps (on a Fedora 42 host) to compile and run the `p2mr` branch of bitcoin core: + +. Set BITCOIN_SOURCE_DIR ++ +----- +export BITCOIN_SOURCE_DIR=/path/to/root/dir/of/cloned/bitcoin/source +----- + +. build ++ +----- +cmake -B build \ + -DWITH_ZMQ=ON \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ + -DBUILD_BENCH=ON \ + -DBUILD_DAEMON=ON \ + -DSANITIZERS=address,undefined + +cmake --build build -j$(nproc) +----- + +. run bitcoind in signet mode: ++ +----- +./build/bin/bitcoind -daemon=0 -signet=1 -txindex -prune=0 +----- ++ +NOTE: If running in `signet`, your bitcoin core will need to be configured with the `signetchallenge` property. +link:https://edil.com.br/blog/creating-a-custom-bitcoin-signet[This workshop] provides a nice overview of the topic. + +=== libbitcoinpqc Rust bindings + +*FOR THE PURPOSE OF THE WORKSHOP, YOU CAN IGNORE THIS SECTION* + +The `p2mr-pqc` branch of this project includes a dependency on the link:https://crates.io/crates/libbitcoinpqc[libbitcoinpqc crate]. +libbitcoinpqc contains native code (C/C++/ASM) and is made available to Rust projects via Rust bindings. +This C/C++/ASM code is provided in the libbitcoinpqc crate as source code (not prebuilt binaries). + +Subsequently, the `Cargo` utility needs to build this libbitcoinpqc C native code on your local machine. +You will need to have C development related libraries installed on your local machine. + +Every developer or CI machine building `p2mr-ref` must have cmake and a C toolchain installed locally. + +==== Linux + +. Debian / Ubuntu ++ +----- +sudo apt update +sudo apt install cmake build-essential clang libclang-dev +----- + +. Fedora / RHEL ++ +----- +sudo dnf5 update +sudo dnf5 install cmake make gcc gcc-c++ clang clang-libs llvm-devel +----- diff --git a/bip-0360/ref-impl/rust/docs/p2tr-end-to-end.adoc b/bip-0360/ref-impl/rust/docs/p2tr-end-to-end.adoc new file mode 100644 index 0000000000..51e0a2fdb1 --- /dev/null +++ b/bip-0360/ref-impl/rust/docs/p2tr-end-to-end.adoc @@ -0,0 +1,236 @@ +:scrollbar: +:data-uri: +:toc2: +:linkattrs: + += P2TR End-to-End Tutorial + +:numbered: + +This tutorial is inspired from the link:https://learnmeabitcoin.com/technical/upgrades/taproot/#example-3-script-path-spend-signature[script-path-spend-signature] example of the _learnmeabitcoin_ tutorial. + +It is customized to create, fund and spend from a P2TR UTXO to a P2WPKH address. + +Execute in Bitcoin Core `regtest` mode. + +== Pre-reqs + +=== Bitcoin Core + +The link:https://github.com/jbride/bitcoin/tree/p2mr-pqc[p2mr branch] of bitcoin core is needed. + +Build instructions for the `p2mr` branch are the same as `master` and is documented link:https://github.com/bitcoin/bitcoin/blob/master/doc/build-unix.md[here]. + +As such, the following is an example series of steps (on a Fedora 42 host) to compile and run the `p2mr` branch of bitcoin core: + +. build ++ +----- +$ cmake -B build \ + -DWITH_ZMQ=ON \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ + -DBUILD_BENCH=ON \ + -DSANITIZERS=address,undefined + +$ cmake --build build -j$(nproc) +----- + +. run in `regtest` mode ++ +----- +$ ./build/bin/bitcoind -daemon=0 -regtest=1 -txindex +----- + +=== Shell Environment + +. *b-reg* command line alias: ++ +Configure an alias to the `bitcoin-cli` command that connects to your customized bitcoin-core node running in `regtest` mode. +. *jq*: ensure json parsing utility is installed and available via your $PATH. +. *awk* : standard utility for all Linux distros (often packaged as `gawk`). + +=== Bitcoin Core Wallet + +This tutorial assumes that a bitcoin core wallet is available. +For example, the following would be sufficient: + +----- +$ export W_NAME=regtest \ + && export WPASS=regtest + +$ b-reg -named createwallet \ + wallet_name=$W_NAME \ + descriptors=true \ + passphrase="$WPASS" \ + load_on_startup=true +----- + +== Fund P2TR UTXO + +. OPTIONAL: Define number of leaves in tap tree as well as the tap leaf to later use as the unlocking script: ++ +----- +$ export TOTAL_LEAF_COUNT=5 \ + && export LEAF_TO_SPEND_FROM=4 +----- ++ +NOTE: Defaults are 4 leaves with the first leaf (leaf 0 ) as the script to later use as the unlocking script. + + +. Generate a P2TR scripPubKey with multi-leaf taptree: ++ +----- +$ export BITCOIN_NETWORK=regtest \ + && export BITCOIN_ADDRESS_INFO=$( cargo run --example p2tr_construction ) \ + && echo $BITCOIN_ADDRESS_INFO | jq -r . +----- ++ +NOTE: In `regtest`, you can expect a P2TR address that starts with: `bcrt1q` . ++ +NOTE: In the context of P2TR, the _tree_root_hex_ from the response is in reference to the _merkle_root_ used in this tutorial. + +. Set some env vars (for use in later steps in this tutorial) based on previous result: ++ +----- +$ export MERKLE_ROOT=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.tree_root_hex' ) \ + && export LEAF_SCRIPT_PRIV_KEYS_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.leaf_script_priv_keys_hex' ) \ + && export LEAF_SCRIPT_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.leaf_script_hex' ) \ + && export CONTROL_BLOCK_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.control_block_hex' ) \ + && export FUNDING_SCRIPT_PUBKEY=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.utxo_return.script_pubkey_hex' ) \ + && export P2TR_ADDR=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.utxo_return.bech32m_address' ) +----- + +. View tapscript used in target leaf of taptree: ++ +----- +$ b-reg decodescript $LEAF_SCRIPT_HEX | jq -r '.asm' +----- ++ +NOTE: Notice that this script commits to a Schnorr 32-byte x-only public key. + +. fund this P2TR address with the coinbase reward of a newly generated block: ++ +----- +$ export COINBASE_REWARD_TX_ID=$( b-reg -named generatetoaddress 1 $P2TR_ADDR 5 | jq -r '.[]' ) \ + && echo $COINBASE_REWARD_TX_ID +----- ++ +NOTE: Sometimes Bitcoin Core may not hit a block (even on regtest). If so, just try the above command again. + +. view summary of all txs that have funded P2TR address ++ +----- +$ export P2TR_DESC=$( b-reg getdescriptorinfo "addr($P2TR_ADDR)" | jq -r '.descriptor' ) \ + && echo $P2TR_DESC \ + && b-reg scantxoutset start '[{"desc": "'''$P2TR_DESC'''"}]' +----- + +. grab txid of first tx with unspent funds: ++ +----- +$ export FUNDING_TX_ID=$( b-reg scantxoutset start '[{"desc": "'''$P2TR_DESC'''"}]' | jq -r '.unspents[0].txid' ) \ + && echo $FUNDING_TX_ID +----- + +. Set FUNDING_UTXO_INDEX env var (used later to correctly identify funding UTXO when generating the spending tx) ++ +----- +$ export FUNDING_UTXO_INDEX=0 +----- + +. view details of funding UTXO to the P2TR address: ++ +----- +$ export FUNDING_UTXO=$( b-reg getrawtransaction $FUNDING_TX_ID 1 | jq -r '.vout['''$FUNDING_UTXO_INDEX''']' ) \ + && echo $FUNDING_UTXO | jq -r . +----- ++ +NOTE: the above only works when Bitcoin Core is started with the following arg: -txindex + +== Spend P2TR UTXO + + +. Determine value (in sats) of funding utxo: ++ +----- +$ export FUNDING_UTXO_AMOUNT_SATS=$(echo $FUNDING_UTXO | jq -r '.value' | awk '{printf "%.0f", $1 * 100000000}') \ + && echo $FUNDING_UTXO_AMOUNT_SATS +----- + +. Generate additional blocks. ++ +This is necessary if you have only previously generated less than 100 blocks. ++ +----- +$ b-reg -generate 110 +----- ++ +Otherwise, you may see an error from bitcoin core such as the following when attempting to spend: ++ +_bad-txns-premature-spend-of-coinbase, tried to spend coinbase at depth 1_ + +. Referencing the funding tx (via $FUNDING_TX_ID and $FUNDING_UTXO_INDEX), create the spending tx: ++ +----- +$ export SPEND_DETAILS=$( cargo run --example p2tr_spend ) + +$ export RAW_P2TR_SPEND_TX=$( echo $SPEND_DETAILS | jq -r '.tx_hex' ) \ + && echo "RAW_P2TR_SPEND_TX = $RAW_P2TR_SPEND_TX" \ + && export SIG_HASH=$( echo $SPEND_DETAILS | jq -r '.sighash' ) \ + && echo "SIG_HASH = $SIG_HASH" \ + && export SIG_BYTES=$( echo $SPEND_DETAILS | jq -r '.sig_bytes' ) \ + && echo "SIG_BYTES = $SIG_BYTES" +----- + +. Inspect the spending tx: ++ +----- +$ b-reg decoderawtransaction $RAW_P2TR_SPEND_TX +----- + +. Test standardness of the spending tx by sending to local mempool of p2tr enabled Bitcoin Core: + + +----- +$ b-reg testmempoolaccept '["'''$RAW_P2TR_SPEND_TX'''"]' +----- + +. Submit tx: ++ +----- +$ export P2TR_SPENDING_TX_ID=$( b-reg sendrawtransaction $RAW_P2TR_SPEND_TX ) \ + && echo $P2TR_SPENDING_TX_ID +----- ++ +NOTE: Should return same tx id as was included in $RAW_P2TR_SPEND_TX + +== Mine P2TR Spend TX + +. View tx in mempool: ++ +----- +$ b-reg getrawtransaction $P2TR_SPENDING_TX_ID 1 +----- ++ +NOTE: There will not yet be a field `blockhash` in the response. + +. Mine 1 block: ++ +----- +$ b-reg -generate 1 +----- + +. Obtain `blockhash` field of mined tx: ++ +----- +$ export BLOCK_HASH=$( b-reg getrawtransaction $P2TR_SPENDING_TX_ID 1 | jq -r '.blockhash' ) \ + && echo $BLOCK_HASH +----- + +. View tx in block: ++ +----- +$ b-reg getblock $BLOCK_HASH | jq -r .tx +----- + +== TO-DO diff --git a/bip-0360/ref-impl/rust/docs/quantum_root_tap_tree.txt b/bip-0360/ref-impl/rust/docs/quantum_root_tap_tree.txt new file mode 100644 index 0000000000..f032d13111 --- /dev/null +++ b/bip-0360/ref-impl/rust/docs/quantum_root_tap_tree.txt @@ -0,0 +1,36 @@ + ┌───────────────────────┐ + │ tapleaf Merkle root │ + │ │ + └───────────────────────┘ + | + ┌───────────────────────┐ + │ 5 tagged_hash │ + │ QuantumRoot │ + └───────────|───────────┘ + ┌───────────|───────────┐ + ┌───────────────────────────────►│ 4 tagged_hash ◄─────────────────────┐ + │ │ TapBranch │ │ + │ └───────────────────────┘ │ + │ │ + │ │ + │ │ + │ │ + │ │ + │ ┌─────────────┼───────────┐ + │ │ 3 tagged_hash │ + │ ┌──►│ TapBranch ◄───────┐ + │ │ └─────────────────────────┘ │ + │ │ │ + │ │ │ + ┌───────────┼────────────┐ ┌───────┼────────┐ │ + ┌─────►│ 2 tagged_hash ◄────┐ ┌─────►│ 2 tagged_hash ◄────┐ │ + │ │ TapBranch │ │ │ │ TapBranch │ │ │ + │ └────────────────────────┘ │ │ └────────────────┘ │ │ + │ │ │ │ │ + │ │ ┌─────┼────────┐ ┌───────|───-─┐ ┌──────┴──────┐ + ┌───┼──────────┐ ┌──────────┼──┐ │ 1 tagged_hash│ │1 tagged_hash│ │1 tagged_hash│ + │1 tagged_hash │ │1 tagged_hash│ │ Tapleaf │ │ Tapleaf │ │ Tapleaf │ + │ Tapleaf │ │ Tapleaf │ └──────────────┘ └─────────────┘ └─────────────┘ + └──▲───────────┘ └──────▲──────┘ ▲ ▲ ▲ + │ │ │ │ │ + version | A script version | B script version | C script version | D script version|E script diff --git a/bip-0360/ref-impl/rust/docs/stack_element_size_performance_tests.adoc b/bip-0360/ref-impl/rust/docs/stack_element_size_performance_tests.adoc new file mode 100644 index 0000000000..0addb22bc3 --- /dev/null +++ b/bip-0360/ref-impl/rust/docs/stack_element_size_performance_tests.adoc @@ -0,0 +1,358 @@ +:scrollbar: +:data-uri: +:toc2: +:linkattrs: + += Stack Element Size Performance Tests + +:numbered: + +== Overview + +BIP-0360 proposes an increase in stack element size from current 520 bytes (v0.29) to 8kb. + +Subsequently, there is a need to determine the performance and stability related consequences of doing so. + +== Regression Tests + +The following regression tests failed with `MAX_SCRIPT_ELEMENT_SIZE` set to 8000 . + +[cols="1,1,2"] +|=== +|feature_taproot.py | line 1338 | Missing error message 'Push value size limit exceeded' from block response 'mandatory-script-verify-flag-failed (Stack size must be exactly one after execution)' +|p2p_filter.py | lines 130-132 | Check that too large data element to add to the filter is rejected +|p2p_segwit.py | lines 1047-1049 | mandatory-script-verify-flag-failed (Push value size limit exceeded) +|rpc_createmultisig.py | lines 75-75 | No exception raised: redeemScript exceeds size limit: 684 > 520" +|=== + +**Analysis** + +These 4 tests explicitly test for a stack element size of 520 and are expected to fail with a stack element size of 8Kb. +Subsequently, no further action needed. + + +== Performance Tests + +=== OP_SHA256 + +The following Bitcoin script is used to conduct this performance test: + +----- + OP_SHA256 OP_DROP OP_1 +----- + +When executed, this script adds the pre-image array of arbitrary data to the stack. +Immediately after, a SHA256 hash function pops the pre-image array off the stack, executes a hash and adds the result to the top of the stack. +The `OP_DROP` operation removes the hash result from the stack. + + +==== Results Summary + +[cols="3,1,1,1,1,1,1,1,1,1", options="header"] +|=== +| Stack Element Size (Bytes) | ns/op | op/s | err% | ins/op | cyc/op | IPC | bra/op |miss% | total +| 1 | 637.28 | 1,569,165.30 | 0.3% | 8,736.00 | 1,338.55 | 6.526 | 832.00 | 0.0% | 5.53 +| 64 | 794.85 | 1,258,098.46 | 0.4% | 11,107.00 | 1,666.92 | 6.663 | 827.00 | 0.0% | 5.61 +| 65 | 831.95 | 1,201,996.30 | 0.5% | 11,144.00 | 1,698.26 | 6.562 | 841.00 | 0.0% | 5.53 +| 100 | 794.82 | 1,258,139.86 | 0.2% | 11,139.00 | 1,673.89 | 6.655 | 837.00 | 0.0% | 5.50 +| 520 | 1,946.67 | 513,697.88 | 0.2% | 27,681.00 | 4,095.57 | 6.759 | 885.00 | 0.0% | 5.50 +| 8000 | 20,958.63 | 47,713.05 | 2.7% | 304,137.02 | 43,789.86 | 6.945 | 1,689.02 | 0.4% | 5.63 +|=== + +**Analysis** + +The following observations are made from the performance test: + +. **Performance Scaling**: The increase from 520 bytes to 8000 bytes (15.4x size increase) results in approximately 9.8x performance degradation (19,173 ns/op vs 1,947 ns/op). +This represents sub-linear scaling, which suggests the implementation handles large data efficiently. + +. **Instruction Count Scaling**: Instructions per operation increase from 27,681 to 285,220 (10.3x increase), closely matching the performance degradation, indicating the bottleneck is primarily computational rather than memory bandwidth. + +. **Throughput Impact**: Operations per second decrease from 513,698 op/s to 52,158 op/s, representing a 9.8x reduction in throughput. + +. **Cache Efficiency**: The IPC (Instructions Per Cycle) remains relatively stable (6.759 to 7.094), suggesting good CPU pipeline utilization despite the increased data size. + +. **Memory Access Patterns**: The branch mis-prediction rate increases slightly (0.0% to 0.4%), indicating minimal impact on branch prediction accuracy. + + +**key** + +[cols="1,6", options="header"] +|=== +| Metric | Description +| ns/op | Nanoseconds per operation - average time it takes to complete one benchmark iteration +| op/s | Operations per second - throughput rate showing how many benchmark iterations can be completed per second +| err% | Error percentage - statistical margin of error in the measurement, indicating the reliability of the benchmark results +| ins/op | Instructions per operation - the number of CPU instructions executed for each benchmark iteration +| cyc/op | CPU cycles per operation - the number of CPU clock cycles consumed for each benchmark iteration +| IPC | Instructions per cycle - the ratio of instructions executed per CPU cycle, indicating CPU efficiency and pipeline utilization +| bra/op | Branches per operation - the number of conditional branch instructions executed for each benchmark iteration +| miss% | Branch misprediction percentage - the rate at which the CPU incorrectly predicts branch outcomes, causing pipeline stalls +| total | Total benchmark time - the total wall-clock time spent running the entire benchmark in seconds +|=== + +==== Detailed Results + +===== Stack Element Size = 1 Byte + +[cols="2,1,1,1,1,1,1,1,1", options="header"] +|=== +|ns/op |op/s |err% |ins/op |cyc/op |IPC |bra/op |miss% |total +|637.28 |1,569,165.30 |0.3% |8,736.00 |1,338.55 |6.526 |832.00 |0.0% |5.53 +|=== + +===== Stack Element Size = 64 Bytes + +[cols="2,1,1,1,1,1,1,1,1", options="header"] +|=== +| ns/op | op/s | err% | ins/op | cyc/op | IPC | bra/op | miss% | total +| 794.85 | 1,258,098.46 | 0.4% | 11,107.00 | 1,666.92 | 6.663 | 827.00 | 0.0% | 5.61 +|=== + +====== Explanation + +Even though 64 bytes doesn't require padding (it's exactly one SHA256 block), the ins/op still increases from 8,736 to 11,107 instructions. Here's why: + +. Data Movement Overhead + + * 1 byte: Minimal data to copy into the SHA256 processing buffer + * 64 bytes: 64x more data to move from the witness stack into the SHA256 input buffer + * Memory copying operations add instructions + +. SHA256 State Initialization + + * 1 byte: The 1-byte input gets padded to 64 bytes internally, but the padding is mostly zeros + * 64 bytes: All 64 bytes are actual data that needs to be processed + * The SHA256 algorithm may have different code paths for handling "real" data vs padded data + +. Memory Access Patterns + + * 1 byte: Single byte access, likely cache-friendly + * 64 bytes: Sequential access to 64 bytes, potentially different memory access patterns + * May trigger different CPU optimizations or cache behavior + +. Bit Length Processing + + * 1 byte: The SHA256 algorithm needs to set the bit length field (8 bits) + * 64 bytes: The bit length field is 512 bits + * Different bit length values may cause different code paths in the SHA256 implementation + +. Loop Unrolling and Optimization + + * 1 byte: Compiler might optimize the single-block case differently + * 64 bytes: May use different loop structures or optimization strategies + * The SHA256 implementation might have specialized code paths for different input sizes + +. Witness Stack Operations + + * 1 byte: Small witness element, minimal stack manipulation + * 64 bytes: Larger witness element, more complex stack operations + * The Bitcoin script interpreter has to handle larger data on the stack + +The increase from 8,736 to 11,107 instructions (~27% increase) suggests that even without padding overhead, the additional data movement and processing of "real" data vs padded data adds significant instruction count. +This is a good example of how seemingly small changes in input size can affect the underlying implementation's code paths and optimization strategies. + +===== Stack Element Size = 65 Bytes + +1 byte more than the SHA256 _block_ size + +[cols="2,1,1,1,1,1,1,1,1", options="header"] +|=== +|ns/op |op/s |err% |ins/op |cyc/op |IPC |bra/op | miss% | total +| 831.95 | 1,201,996.30 |0.5% |11,144.00 |1,698.26 | 6.562 |841.00 | 0.0% | 5.53 +|=== + +===== Stack Element Size = 100 Bytes + +[cols="2,1,1,1,1,1,1,1,1", options="header"] +|=== +|ns/op |op/s |err% |ins/op |cyc/op |IPC |bra/op | miss% | total +| 794.82 | 1,258,139.86 | 0.2% | 11,139.00 | 1,673.89 | 6.655 | 837.00 | 0.0% | 5.50 +|=== + +===== Stack Element Size = 520 Bytes + +[cols="2,1,1,1,1,1,1,1,1", options="header"] +|=== +|ns/op |op/s |err% |ins/op |cyc/op |IPC |bra/op | miss% | total +| 1,946.67 | 513,697.88 | 0.2% | 27,681.00 | 4,095.57 | 6.759 | 885.00 | 0.0% | 5.50 +|=== + +===== Stack Element Size = 8000 Bytes + +[cols="2,1,1,1,1,1,1,1,1", options="header"] +|=== +|ns/op |op/s |err% |ins/op |cyc/op |IPC |bra/op | miss% | total +| 20,958.63 | 47,713.05 | 2.7% | 304,137.02 | 43,789.86 | 6.945 | 1,689.02 | 0.4% | 5.63 +|=== + +=== OP_DUP OP_SHA256 + +NOTE: This test is likely irrelevant as per latest BIP-0360: _To prevent OP_DUP from creating an 8 MB stack by duplicating stack elements larger than 520 bytes we define OP_DUP to fail on stack elements larger than 520 bytes_. + +This test builds off the previous (involving the hashing of large stack element data) by duplicating that stack element data. + +The following Bitcoin script is used to conduct this performance test: + +----- + OP_DUP OP_SHA256 OP_DROP OP_1 +----- + +When executed, this script adds the pre-image array of arbitrary data to the stack. +Immediately after, a `OP_DUP` operation duplicates the pre-image array on the stack. +Then, a SHA256 hash function pops the pre-image array off the stack, executes a hash and adds the result to the top of the stack. +The `OP_DROP` operation removes the hash result from the stack. + +==== Results Summary + +[cols="3,1,1,1,1,1,1,1,1,1", options="header"] +|=== +| Stack Element Size (Bytes) | ns/op | op/s | err% | ins/op | cyc/op | IPC | bra/op |miss% | total +| 1 | 714.83 | 1,398,937.33 | 0.7% | 9,548.00 | 1,488.22 | 6.416 | 1,012.00 | 0.0% | 5.57 +| 64 | 858.44 | 1,164,905.19 | 0.4% | 11,911.00 | 1,800.87 | 6.614 | 999.00 | 0.0% | 5.11 +| 65 | 868.40 | 1,151,539.31 | 0.8% | 11,968.00 | 1,814.31 | 6.596 | 1,019.00 | 0.0% | 5.56 +| 100 | 864.33 | 1,156,966.91 | 0.4% | 11,963.00 | 1,809.16 | 6.612 | 1,015.00 | 0.0% | 5.49 +| 520 | 2,036.64 | 491,005.94 | 0.7% | 28,615.00 | 4,266.27 | 6.707 | 1,073.00 | 0.0% | 5.52 +| 8000 | 20,883.10 | 47,885.61 | 0.2% | 306,887.04 | 43,782.35 | 7.009 | 2,089.02 | 0.3% | 5.53 +|=== + +==== Analysis + +The following observations are made from the performance test (in comparison to the `OP_SHA256` test): + +. OP_DUP Overhead: The OP_DUP operation adds overhead by duplicating the stack element, which requires: + * Memory allocation for the duplicate + * Data copying from the original to the duplicate + * Additional stack manipulation + +. Size-Dependent Impact on ns/op: + * For small elements (1-100 bytes): Significant overhead (4.4% to 12.2%) + * For medium elements (520 bytes): Moderate overhead (4.6%) + * For large elements (8000 bytes): Negligible difference (-0.4%) + +. Instruction Count Impact: + * 8000 bytes: 304,137 → 306,887 instructions (+2,750 instructions) + * The additional instructions for OP_DUP are relatively small compared to the SHA256 computation + +. Memory Operations: ++ +The OP_DUP operation primarily affects memory operations rather than computational complexity. +This explains why the impact diminishes with larger data sizes where SHA256 computation dominates the performance. + +This analysis shows that the OP_DUP operation has a measurable but manageable performance impact, especially for larger stack elements where the computational overhead of SHA256 dominates the overall execution time. + +=== Procedure + +* Testing is done using functionality found in the link:https://github.com/jbride/bitcoin/tree/p2mr-pqc[p2mr branch] of Bitcoin Core. + +* Compilation of Bitcoin Core is done using the following `cmake` flags: ++ +----- +$ cmake \ + -B build \ + -DWITH_ZMQ=ON \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ + -DBUILD_BENCH=ON + +$ cmake --build build -j$(nproc) +----- + +* Bench tests are conducted similar to the following : ++ +----- +$ export PREIMAGE_SIZE_BYTES=8000 +$ ./build/bin/bench_bitcoin --filter=VerifySHA256Bench -min-time=5000 +----- + +== Failure Analysis + +Goals: + +* Measure stack memory usage to detect overflows or excessive stack growth. +* Monitor heap memory usage to identify increased allocations or leaks caused by larger elements. +* Detect memory errors (e.g., invalid reads/writes, use-after-free) that might arise from modified stack handling. +* Assess performance impacts (e.g., memory allocation overhead) in critical paths like transaction validation. + +=== Memory Errors + +AddressSanitizer is a fast, compiler-based tool (available in GCC/Clang) for detecting memory errors with lower overhead than Valgrind. + +==== Results + +No memory errors or leaks were revealed by AddressSanitizer when running the `OP_SHA256` bench test for 30 minutes. + +==== Procedure + +AddressSanitizer is included with Clang/LLVM + +. Compilation of Bitcoin Core is done using the following `cmake` flags: ++ +----- +$ cmake -B build \ + -DWITH_ZMQ=ON \ + -DBUILD_BENCH=ON \ + -DCMAKE_C_COMPILER=clang \ + -DCMAKE_CXX_COMPILER=clang++ \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ + -DSANITIZERS=address,undefined + +$ cmake --build build -j$(nproc) +----- + +. Check that ASan is statically linked to the _bench_bitcoin_ executable: ++ +----- +$ nm build/bin/bench_bitcoin | grep asan | more +0000000000148240 T __asan_address_is_poisoned +00000000000a2fe6 t __asan_check_load_add_16_R13 + +... + +000000000316c828 b _ZZN6__asanL18GlobalsByIndicatorEmE20globals_by_indicator +0000000003170ccc b _ZZN6__asanL7AsanDieEvE9num_calls +----- + +. Set the following environment variable: ++ +----- +$ export ASAN_OPTIONS="halt_on_error=0:detect_leaks=1:log_path=/tmp/asan_logs/asan" +----- ++ +Doing so ensures that _address sanitizer_ : + +.. avoids halting on the first error +.. is enable memory leak detection +.. writes ASAN related logs to a specified directory + +== Test Environment + +* Fedora 42 +* 8 cores (Intel(R) Core(TM) i7-8665U CPU @ 1.90GHz) +* 32 GB RAM + +* OS settings: ++ +----- +$ ulimit -a +real-time non-blocking time (microseconds, -R) unlimited +core file size (blocks, -c) unlimited +data seg size (kbytes, -d) unlimited +scheduling priority (-e) 0 +file size (blocks, -f) unlimited +pending signals (-i) 126896 +max locked memory (kbytes, -l) 8192 +max memory size (kbytes, -m) unlimited +open files (-n) 1024 +pipe size (512 bytes, -p) 8 +POSIX message queues (bytes, -q) 819200 +real-time priority (-r) 0 +stack size (kbytes, -s) 8192 +cpu time (seconds, -t) unlimited +max user processes (-u) 126896 +virtual memory (kbytes, -v) unlimited +file locks (-x) unlimited +----- + +== Notes + +. test with different thread stack sizes (ie: ulimit -s xxxx ) diff --git a/bip-0360/ref-impl/rust/examples/p2mr-end-to-end.sh b/bip-0360/ref-impl/rust/examples/p2mr-end-to-end.sh new file mode 100644 index 0000000000..2029420dbd --- /dev/null +++ b/bip-0360/ref-impl/rust/examples/p2mr-end-to-end.sh @@ -0,0 +1,30 @@ + +export BITCOIN_SOURCE_DIR=$HOME/bitcoin +export W_NAME=anduro +export USE_PQC=false +export TOTAL_LEAF_COUNT=5 +export LEAF_TO_SPEND_FROM=4 + +b-cli -named createwallet \ + wallet_name=$W_NAME \ + descriptors=true \ + load_on_startup=true + +export BITCOIN_ADDRESS_INFO=$( cargo run --example p2mr_construction ) \ + && echo $BITCOIN_ADDRESS_INFO | jq -r . + +export QUANTUM_ROOT=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.tree_root_hex' ) \ + && export LEAF_SCRIPT_PRIV_KEY_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.leaf_script_priv_key_hex' ) \ + && export LEAF_SCRIPT_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.leaf_script_hex' ) \ + && export CONTROL_BLOCK_HEX=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.taptree_return.control_block_hex' ) \ + && export FUNDING_SCRIPT_PUBKEY=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.utxo_return.script_pubkey_hex' ) \ + && export P2MR_ADDR=$( echo $BITCOIN_ADDRESS_INFO | jq -r '.utxo_return.bech32m_address' ) + +b-cli decodescript $LEAF_SCRIPT_HEX | jq -r '.asm' + +export COINBASE_REWARD_TX_ID=$( b-cli -named generatetoaddress 1 $P2MR_ADDR 5 | jq -r '.[]' ) \ + && echo $COINBASE_REWARD_TX_ID + +export P2MR_DESC=$( b-cli getdescriptorinfo "addr($P2MR_ADDR)" | jq -r '.descriptor' ) \ + && echo $P2MR_DESC \ + && b-cli scantxoutset start '[{"desc": "'''$P2MR_DESC'''"}]' diff --git a/bip-0360/ref-impl/rust/examples/p2mr_construction.rs b/bip-0360/ref-impl/rust/examples/p2mr_construction.rs new file mode 100644 index 0000000000..517ea619b1 --- /dev/null +++ b/bip-0360/ref-impl/rust/examples/p2mr_construction.rs @@ -0,0 +1,27 @@ +use p2mr_ref::{create_p2mr_utxo, create_p2mr_multi_leaf_taptree, tap_tree_lock_type}; +use p2mr_ref::data_structures::{UtxoReturn, TaptreeReturn, ConstructionReturn, LeafScriptType}; +use std::env; +use log::{info, error}; + +// Inspired by: https://learnmeabitcoin.com/technical/upgrades/taproot/#example-3-script-path-spend-signature +fn main() -> ConstructionReturn { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let tap_tree_lock_type = tap_tree_lock_type(); + info!("tap_tree_lock_type: {:?}", tap_tree_lock_type); + + let taptree_return: TaptreeReturn = create_p2mr_multi_leaf_taptree(); + let p2mr_utxo_return: UtxoReturn = create_p2mr_utxo(taptree_return.clone().tree_root_hex); + + // Alert user about SPENDING_LEAF_TYPE requirement when using MIXED mode + if tap_tree_lock_type == LeafScriptType::Mixed { + info!("NOTE: TAP_TREE_LOCK_TYPE=MIXED requires setting SPENDING_LEAF_TYPE when spending (based on leaf_script_type in output above) as follows:"); + info!(" export SPENDING_LEAF_TYPE={}", taptree_return.leaf_script_type); + } + + return ConstructionReturn { + taptree_return: taptree_return, + utxo_return: p2mr_utxo_return, + }; +} diff --git a/bip-0360/ref-impl/rust/examples/p2mr_spend.rs b/bip-0360/ref-impl/rust/examples/p2mr_spend.rs new file mode 100644 index 0000000000..7dcbc15a63 --- /dev/null +++ b/bip-0360/ref-impl/rust/examples/p2mr_spend.rs @@ -0,0 +1,284 @@ +use p2mr_ref::{ pay_to_p2wpkh_tx, verify_schnorr_signature_via_bytes, verify_slh_dsa_via_bytes, tap_tree_lock_type }; + +use p2mr_ref::data_structures::{SpendDetails, LeafScriptType}; +use std::env; +use log::{info, error}; + +// Inspired by: https://learnmeabitcoin.com/technical/upgrades/taproot/#example-3-script-path-spend-signature +fn main() -> SpendDetails { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + // FUNDING_TX_ID environment variable is required + let funding_tx_id: String = env::var("FUNDING_TX_ID") + .unwrap_or_else(|_| { + error!("FUNDING_TX_ID environment variable is required but not set"); + std::process::exit(1); + }); + let funding_tx_id_bytes: Vec = hex::decode(funding_tx_id.clone()).unwrap(); + + // FUNDING_UTXO_AMOUNT_SATS environment variable is required + let funding_utxo_amount_sats: u64 = env::var("FUNDING_UTXO_AMOUNT_SATS") + .unwrap_or_else(|_| { + error!("FUNDING_UTXO_AMOUNT_SATS environment variable is required but not set"); + std::process::exit(1); + }) + .parse::() + .unwrap_or_else(|_| { + error!("FUNDING_UTXO_AMOUNT_SATS must be a valid u64 integer"); + std::process::exit(1); + }); + + // The input index of the funding tx + // Allow override via FUNDING_UTXO_INDEX environment variable + let funding_utxo_index: u32 = env::var("FUNDING_UTXO_INDEX") + .ok() + .and_then(|s| s.parse::().ok()) + .unwrap_or(0); + + info!("Funding tx id: {}, utxo index: {}", funding_tx_id, funding_utxo_index); + + // FUNDING_SCRIPT_PUBKEY environment variable is required + let funding_script_pubkey_bytes: Vec = env::var("FUNDING_SCRIPT_PUBKEY") + .map(|s| hex::decode(s).unwrap()) + .unwrap_or_else(|_| { + error!("FUNDING_SCRIPT_PUBKEY environment variable is required but not set"); + std::process::exit(1); + }); + + let control_block_bytes: Vec = env::var("CONTROL_BLOCK_HEX") + .map(|s| hex::decode(s).unwrap()) + .unwrap_or_else(|_| { + error!("CONTROL_BLOCK_HEX environment variable is required but not set"); + std::process::exit(1); + }); + info!("P2MR control block size: {}", control_block_bytes.len()); + + // TAP_TREE_LOCK_TYPE environment variable is required to determine key structure + let leaf_script_type: LeafScriptType = tap_tree_lock_type(); + info!("leaf_script_type: {:?}", leaf_script_type); + + // For Mixed trees, we need to determine the actual leaf type via SPENDING_LEAF_TYPE + let effective_leaf_type: LeafScriptType = if leaf_script_type == LeafScriptType::Mixed { + match env::var("SPENDING_LEAF_TYPE") { + Ok(value) => match value.as_str() { + "SCHNORR_ONLY" => { + info!("SPENDING_LEAF_TYPE: SCHNORR_ONLY"); + LeafScriptType::SchnorrOnly + }, + "SLH_DSA_ONLY" => { + info!("SPENDING_LEAF_TYPE: SLH_DSA_ONLY"); + LeafScriptType::SlhDsaOnly + }, + _ => { + error!("Invalid SPENDING_LEAF_TYPE '{}'. Must be SCHNORR_ONLY or SLH_DSA_ONLY", value); + std::process::exit(1); + } + }, + Err(_) => { + error!("SPENDING_LEAF_TYPE environment variable is required when TAP_TREE_LOCK_TYPE=MIXED"); + error!("Set SPENDING_LEAF_TYPE to the actual type of the leaf being spent (SCHNORR_ONLY or SLH_DSA_ONLY)."); + error!("The leaf type is returned in the 'leaf_script_type' field of the tree construction output."); + std::process::exit(1); + } + } + } else { + leaf_script_type + }; + + // Parse private keys based on effective script type + let leaf_script_priv_keys_bytes: Vec> = match effective_leaf_type { + LeafScriptType::SlhDsaOnly => { + let priv_keys_hex_array = env::var("LEAF_SCRIPT_PRIV_KEYS_HEX") + .unwrap_or_else(|_| { + error!("LEAF_SCRIPT_PRIV_KEYS_HEX environment variable is required for SLH_DSA_ONLY"); + std::process::exit(1); + }); + // Parse JSON array and extract the first (and only) hex string + let priv_keys_hex: String = serde_json::from_str::>(&priv_keys_hex_array) + .unwrap_or_else(|_| { + error!("Failed to parse LEAF_SCRIPT_PRIV_KEYS_HEX as JSON array"); + std::process::exit(1); + }) + .into_iter() + .next() + .unwrap_or_else(|| { + error!("LEAF_SCRIPT_PRIV_KEYS_HEX array is empty"); + std::process::exit(1); + }); + let priv_keys_bytes = hex::decode(priv_keys_hex).unwrap(); + if priv_keys_bytes.len() != 64 { + error!("SLH-DSA private key must be 64 bytes, got {}", priv_keys_bytes.len()); + std::process::exit(1); + } + vec![priv_keys_bytes] + }, + LeafScriptType::SchnorrOnly => { + let priv_keys_hex_array = env::var("LEAF_SCRIPT_PRIV_KEYS_HEX") + .unwrap_or_else(|_| { + error!("LEAF_SCRIPT_PRIV_KEYS_HEX environment variable is required for SCHNORR_ONLY"); + std::process::exit(1); + }); + // Parse JSON array and extract the first (and only) hex string + let priv_keys_hex: String = serde_json::from_str::>(&priv_keys_hex_array) + .unwrap_or_else(|_| { + error!("Failed to parse LEAF_SCRIPT_PRIV_KEYS_HEX as JSON array"); + std::process::exit(1); + }) + .into_iter() + .next() + .unwrap_or_else(|| { + error!("LEAF_SCRIPT_PRIV_KEYS_HEX array is empty"); + std::process::exit(1); + }); + let priv_keys_bytes = hex::decode(priv_keys_hex).unwrap(); + if priv_keys_bytes.len() != 32 { + error!("Schnorr private key must be 32 bytes, got {}", priv_keys_bytes.len()); + std::process::exit(1); + } + vec![priv_keys_bytes] + }, + LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf => { + let priv_keys_hex_array = env::var("LEAF_SCRIPT_PRIV_KEYS_HEX") + .unwrap_or_else(|_| { + error!("LEAF_SCRIPT_PRIV_KEYS_HEX environment variable is required for SCHNORR_AND_SLH_DSA"); + std::process::exit(1); + }); + // Parse JSON array and extract the hex strings + let priv_keys_hex_vec: Vec = serde_json::from_str(&priv_keys_hex_array) + .unwrap_or_else(|_| { + error!("Failed to parse LEAF_SCRIPT_PRIV_KEYS_HEX as JSON array"); + std::process::exit(1); + }); + + if priv_keys_hex_vec.len() != 2 { + error!("For SCHNORR_AND_SLH_DSA, LEAF_SCRIPT_PRIV_KEYS_HEX must contain exactly 2 hex strings, got {}", priv_keys_hex_vec.len()); + std::process::exit(1); + } + + let schnorr_priv_key_hex = &priv_keys_hex_vec[0]; + let slh_dsa_priv_key_hex = &priv_keys_hex_vec[1]; + + let schnorr_priv_key_bytes = hex::decode(schnorr_priv_key_hex).unwrap(); + let slh_dsa_priv_key_bytes = hex::decode(slh_dsa_priv_key_hex).unwrap(); + + if schnorr_priv_key_bytes.len() != 32 { + error!("Schnorr private key must be 32 bytes, got {}", schnorr_priv_key_bytes.len()); + std::process::exit(1); + } + if slh_dsa_priv_key_bytes.len() != 64 { + error!("SLH-DSA private key must be 64 bytes, got {}", slh_dsa_priv_key_bytes.len()); + std::process::exit(1); + } + + vec![schnorr_priv_key_bytes, slh_dsa_priv_key_bytes] + }, + LeafScriptType::Mixed => { + // This case should never be reached because Mixed is resolved to effective_leaf_type above + unreachable!("Mixed should have been resolved to effective_leaf_type"); + }, + LeafScriptType::NotApplicable => { + panic!("LeafScriptType::NotApplicable is not applicable"); + } + }; + + + // ie: OP_PUSHBYTES_32 6d4ddc0e47d2e8f82cbe2fc2d0d749e7bd3338112cecdc76d8f831ae6620dbe0 OP_CHECKSIG + let leaf_script_bytes: Vec = env::var("LEAF_SCRIPT_HEX") + .map(|s| hex::decode(s).unwrap()) + .unwrap_or_else(|_| { + error!("LEAF_SCRIPT_HEX environment variable is required but not set"); + std::process::exit(1); + }); + + // https://learnmeabitcoin.com/explorer/tx/797505b104b5fb840931c115ea35d445eb1f64c9279bf23aa5bb4c3d779da0c2#outputs + let spend_output_pubkey_hash_bytes: Vec = hex::decode("0de745dc58d8e62e6f47bde30cd5804a82016f9e").unwrap(); + + // OUTPUT_AMOUNT_SATS env var is optional. Default is FUNDING_UTXO_AMOUNT_SATS - 5000 sats + let spend_output_amount_sats: u64 = env::var("OUTPUT_AMOUNT_SATS") + .ok() + .and_then(|s| s.parse::().ok()) + .unwrap_or(funding_utxo_amount_sats.saturating_sub(5000)); + + + let result: SpendDetails = pay_to_p2wpkh_tx( + funding_tx_id_bytes, + funding_utxo_index, + funding_utxo_amount_sats, + funding_script_pubkey_bytes, + control_block_bytes, + leaf_script_bytes.clone(), + leaf_script_priv_keys_bytes, // Now passing Vec> instead of Vec + spend_output_pubkey_hash_bytes, + spend_output_amount_sats, + effective_leaf_type // Use effective type (resolved from SPENDING_LEAF_TYPE if Mixed) + ); + + // Remove first and last byte from leaf_script_bytes to get tapleaf_pubkey_bytes + let tapleaf_pubkey_bytes: Vec = leaf_script_bytes[1..leaf_script_bytes.len()-1].to_vec(); + + match effective_leaf_type { + LeafScriptType::SlhDsaOnly => { + let is_valid: bool = verify_slh_dsa_via_bytes(&result.sig_bytes, &result.sighash, &tapleaf_pubkey_bytes); + info!("is_valid: {}", is_valid); + }, + LeafScriptType::SchnorrOnly => { + let is_valid: bool = verify_schnorr_signature_via_bytes( + &result.sig_bytes, + &result.sighash, + &tapleaf_pubkey_bytes); + info!("is_valid: {}", is_valid); + }, + LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf => { + // For combined scripts, we need to separate the signatures + // The sig_bytes contains: [schnorr_sig (64 bytes), slh_dsa_sig (7856 bytes)] (raw signatures without sighash) + let schnorr_sig_len = 64; // Schnorr signature is 64 bytes + let slh_dsa_sig_len = 7856; // SLH-DSA signature is 7856 bytes + + let expected_min_len = schnorr_sig_len + slh_dsa_sig_len; + + if result.sig_bytes.len() < expected_min_len { + error!("Combined signature length is too short: expected at least {}, got {}", + expected_min_len, result.sig_bytes.len()); + return result; + } + + // Extract Schnorr signature (first 64 bytes) + let schnorr_sig = &result.sig_bytes[..schnorr_sig_len]; + // Extract SLH-DSA signature (next 7856 bytes) + let slh_dsa_sig = &result.sig_bytes[schnorr_sig_len..schnorr_sig_len + slh_dsa_sig_len]; + + // For SCHNORR_AND_SLH_DSA scripts, we need to extract the individual public keys + // The script structure is: OP_PUSHBYTES_32 OP_CHECKSIG OP_PUSHBYTES_32 OP_SUBSTR OP_BOOLAND OP_VERIFY + // So we need to extract the Schnorr pubkey (first 32 bytes after OP_PUSHBYTES_32) + let schnorr_pubkey_bytes = &leaf_script_bytes[1..33]; // Skip OP_PUSHBYTES_32 (0x20), get next 32 bytes + let slh_dsa_pubkey_bytes = &leaf_script_bytes[35..67]; // Skip OP_CHECKSIG (0xac), OP_PUSHBYTES_32 (0x20), get next 32 bytes + + // Verify Schnorr signature + let schnorr_is_valid: bool = verify_schnorr_signature_via_bytes( + schnorr_sig, + &result.sighash, + schnorr_pubkey_bytes); + info!("Schnorr signature is_valid: {}", schnorr_is_valid); + + // Verify SLH-DSA signature + let slh_dsa_is_valid: bool = verify_slh_dsa_via_bytes( + slh_dsa_sig, + &result.sighash, + slh_dsa_pubkey_bytes); + info!("SLH-DSA signature is_valid: {}", slh_dsa_is_valid); + + let both_valid = schnorr_is_valid && slh_dsa_is_valid; + info!("Both signatures valid: {}", both_valid); + } + LeafScriptType::Mixed => { + // This case should never be reached because Mixed is resolved to effective_leaf_type above + unreachable!("Mixed should have been resolved to effective_leaf_type"); + } + LeafScriptType::NotApplicable => { + panic!("LeafScriptType::NotApplicable is not applicable"); + } + } + + return result; +} diff --git a/bip-0360/ref-impl/rust/examples/p2tr_construction.rs b/bip-0360/ref-impl/rust/examples/p2tr_construction.rs new file mode 100644 index 0000000000..328c16fd71 --- /dev/null +++ b/bip-0360/ref-impl/rust/examples/p2tr_construction.rs @@ -0,0 +1,17 @@ +use p2mr_ref::{create_p2tr_utxo, create_p2tr_multi_leaf_taptree}; +use p2mr_ref::data_structures::{UtxoReturn, TaptreeReturn, ConstructionReturn}; + +// Inspired by: https://learnmeabitcoin.com/technical/upgrades/taproot/#example-3-script-path-spend-signature +fn main() -> ConstructionReturn { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let internal_pubkey_hex = "924c163b385af7093440184af6fd6244936d1288cbb41cc3812286d3f83a3329".to_string(); + + let taptree_return: TaptreeReturn = create_p2tr_multi_leaf_taptree(internal_pubkey_hex.clone()); + let utxo_return: UtxoReturn = create_p2tr_utxo(taptree_return.clone().tree_root_hex, internal_pubkey_hex); + return ConstructionReturn { + taptree_return: taptree_return, + utxo_return: utxo_return, + }; +} diff --git a/bip-0360/ref-impl/rust/examples/p2tr_spend.rs b/bip-0360/ref-impl/rust/examples/p2tr_spend.rs new file mode 100644 index 0000000000..636468c168 --- /dev/null +++ b/bip-0360/ref-impl/rust/examples/p2tr_spend.rs @@ -0,0 +1,129 @@ +use p2mr_ref::{ pay_to_p2wpkh_tx , verify_schnorr_signature_via_bytes}; + +use p2mr_ref::data_structures::{SpendDetails, LeafScriptType}; +use std::env; +use log::{info, error}; + +// Inspired by: https://learnmeabitcoin.com/technical/upgrades/taproot/#example-3-script-path-spend-signature +fn main() -> SpendDetails { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + // FUNDING_TX_ID environment variable is required + let funding_tx_id: String = env::var("FUNDING_TX_ID") + .unwrap_or_else(|_| { + error!("FUNDING_TX_ID environment variable is required but not set"); + std::process::exit(1); + }); + let funding_tx_id_bytes: Vec = hex::decode(funding_tx_id.clone()).unwrap(); + + // FUNDING_UTXO_AMOUNT_SATS environment variable is required + let funding_utxo_amount_sats: u64 = env::var("FUNDING_UTXO_AMOUNT_SATS") + .unwrap_or_else(|_| { + error!("FUNDING_UTXO_AMOUNT_SATS environment variable is required but not set"); + std::process::exit(1); + }) + .parse::() + .unwrap_or_else(|_| { + error!("FUNDING_UTXO_AMOUNT_SATS must be a valid u64 integer"); + std::process::exit(1); + }); + + // The input index of the funding tx + // Allow override via FUNDING_UTXO_INDEX environment variable + let funding_utxo_index: u32 = env::var("FUNDING_UTXO_INDEX") + .ok() + .and_then(|s| s.parse::().ok()) + .unwrap_or(0); + + info!("Funding tx id: {}, utxo index: {}", funding_tx_id, funding_utxo_index); + + // FUNDING_SCRIPT_PUBKEY environment variable is required + let funding_script_pubkey_bytes: Vec = env::var("FUNDING_SCRIPT_PUBKEY") + .map(|s| hex::decode(s).unwrap()) + .unwrap_or_else(|_| { + error!("FUNDING_SCRIPT_PUBKEY environment variable is required but not set"); + std::process::exit(1); + }); + + let control_block_bytes: Vec = env::var("CONTROL_BLOCK_HEX") + .map(|s| hex::decode(s).unwrap()) + .unwrap_or_else(|_| { + error!("CONTROL_BLOCK_HEX environment variable is required but not set"); + std::process::exit(1); + }); + info!("P2TR control block size: {}", control_block_bytes.len()); + + // P2TR only supports Schnorr signatures, so we only need one private key + let leaf_script_priv_key_bytes: Vec = { + let priv_keys_hex_array = env::var("LEAF_SCRIPT_PRIV_KEYS_HEX") + .unwrap_or_else(|_| { + error!("LEAF_SCRIPT_PRIV_KEYS_HEX environment variable is required but not set"); + std::process::exit(1); + }); + // Parse JSON array and extract the first (and only) hex string + let priv_keys_hex: String = serde_json::from_str::>(&priv_keys_hex_array) + .unwrap_or_else(|_| { + error!("Failed to parse LEAF_SCRIPT_PRIV_KEYS_HEX as JSON array"); + std::process::exit(1); + }) + .into_iter() + .next() + .unwrap_or_else(|| { + error!("LEAF_SCRIPT_PRIV_KEYS_HEX array is empty"); + std::process::exit(1); + }); + hex::decode(priv_keys_hex).unwrap() + }; + + // Validate that the private key is 32 bytes (Schnorr key size) + if leaf_script_priv_key_bytes.len() != 32 { + error!("P2TR private key must be 32 bytes (Schnorr), got {}", leaf_script_priv_key_bytes.len()); + std::process::exit(1); + } + + // Convert to Vec> format expected by the function + let leaf_script_priv_keys_bytes: Vec> = vec![leaf_script_priv_key_bytes]; + + // ie: OP_PUSHBYTES_32 6d4ddc0e47d2e8f82cbe2fc2d0d749e7bd3338112cecdc76d8f831ae6620dbe0 OP_CHECKSIG + let leaf_script_bytes: Vec = env::var("LEAF_SCRIPT_HEX") + .map(|s| hex::decode(s).unwrap()) + .unwrap_or_else(|_| { + error!("LEAF_SCRIPT_HEX environment variable is required but not set"); + std::process::exit(1); + }); + + // https://learnmeabitcoin.com/explorer/tx/797505b104b5fb840931c115ea35d445eb1f64c9279bf23aa5bb4c3d779da0c2#outputs + let spend_output_pubkey_hash_bytes: Vec = hex::decode("0de745dc58d8e62e6f47bde30cd5804a82016f9e").unwrap(); + + // OUTPUT_AMOUNT_SATS env var is optional. Default is FUNDING_UTXO_AMOUNT_SATS - 5000 sats + let spend_output_amount_sats: u64 = env::var("OUTPUT_AMOUNT_SATS") + .ok() + .and_then(|s| s.parse::().ok()) + .unwrap_or(funding_utxo_amount_sats.saturating_sub(5000)); + + + let result: SpendDetails = pay_to_p2wpkh_tx( + funding_tx_id_bytes, + funding_utxo_index, + funding_utxo_amount_sats, + funding_script_pubkey_bytes, + control_block_bytes, + leaf_script_bytes.clone(), + leaf_script_priv_keys_bytes, // Now passing Vec> format + spend_output_pubkey_hash_bytes.clone(), + spend_output_amount_sats, + LeafScriptType::SchnorrOnly + ); + + // Remove first and last byte from leaf_script_bytes to get tapleaf_pubkey_bytes + let tapleaf_pubkey_bytes: Vec = leaf_script_bytes[1..leaf_script_bytes.len()-1].to_vec(); + + let is_valid: bool = verify_schnorr_signature_via_bytes( + &result.sig_bytes, + &result.sighash, + &tapleaf_pubkey_bytes); + info!("is_valid: {}", is_valid); + + return result; +} diff --git a/bip-0360/ref-impl/rust/examples/schnorr_example.rs b/bip-0360/ref-impl/rust/examples/schnorr_example.rs new file mode 100644 index 0000000000..4723d99bd5 --- /dev/null +++ b/bip-0360/ref-impl/rust/examples/schnorr_example.rs @@ -0,0 +1,69 @@ +use std::env; +use log::info; +use once_cell::sync::Lazy; +use bitcoin::key::{Secp256k1}; +use bitcoin::hashes::{sha256::Hash, Hash as HashTrait}; +use bitcoin::secp256k1::{Message}; + +use p2mr_ref::{ acquire_schnorr_keypair, verify_schnorr_signature }; + +/* Secp256k1 implements the Signing trait when it's initialized in signing mode. + It's important to note that Secp256k1 has different capabilities depending on how it's constructed: + * Secp256k1::new() creates a context capable of both signing and verification + * Secp256k1::signing_only() creates a context that can only sign + * Secp256k1::verification_only() creates a context that can only verify +*/ +static SECP: Lazy> = Lazy::new(Secp256k1::new); + +fn main() { + let _ = env_logger::try_init(); + + // acquire a schnorr keypair (leveraging OS provided random number generator) + let keypair = acquire_schnorr_keypair(); + let (secret_key, public_key) = keypair.as_schnorr().unwrap(); + let message_bytes = b"hello"; + + // secp256k1 operates on a 256-bit (32-byte) field, so inputs must be exactly this size + // subsequently, Schnorr signatures on secp256k1 require exactly a 32-byte input (the curve's scalar field size) + let message_hash: Hash = Hash::hash(message_bytes); + + let message: Message = Message::from_digest_slice(&message_hash.to_byte_array()).unwrap(); + + + /* The secp256k1 library internally generates a random scalar value (aka: nonce or k-value) for each signature + * Every signature is unique - even if you sign the same message with the same private key multiple times + * The randomness is handled automatically by the secp256k1 implementation + * You get different signatures each time for the same inputs + * The nonce is only needed during signing, not during verification + + Schnorr signatures require randomness for security reasons: + * Prevents private key recovery - If the same nonce is used twice, an attacker could potentially derive your private key + * Ensures signature uniqueness - Each signature should be cryptographically distinct + * Protects against replay attacks - Different signatures for the same data + */ + let signature: bitcoin::secp256k1::schnorr::Signature = SECP.sign_schnorr(&message, &secret_key.keypair(&SECP)); + info!("Signature created successfully, size: {}", signature.serialize().len()); + + //let pubkey = public_key; + + + /* + * The nonce provides security during signing (prevents private key recovery) + * The nonce is mathematically eliminated during verification + * The verifier only needs public information (signature, message, public key) + */ + let schnorr_valid = verify_schnorr_signature(signature, message, *public_key); + info!("schnorr_valid: {}", schnorr_valid); + + + let aux_rand = [0u8; 32]; // 32 zero bytes; fine for testing + let signature_aux_rand: bitcoin::secp256k1::schnorr::Signature = SECP.sign_schnorr_with_aux_rand( + &message, + &secret_key.keypair(&SECP), + &aux_rand + ); + info!("aux_rand signature created successfully, size: {}", signature_aux_rand.serialize().len()); + + let schnorr_valid_aux_rand = verify_schnorr_signature(signature_aux_rand, message, *public_key); + info!("schnorr_valid_aux_rand: {}", schnorr_valid_aux_rand); +} diff --git a/bip-0360/ref-impl/rust/examples/slh_dsa_verification_example.rs b/bip-0360/ref-impl/rust/examples/slh_dsa_verification_example.rs new file mode 100644 index 0000000000..c6c965e7a0 --- /dev/null +++ b/bip-0360/ref-impl/rust/examples/slh_dsa_verification_example.rs @@ -0,0 +1,77 @@ +use std::env; +use log::info; +use once_cell::sync::Lazy; +use bitcoin::hashes::{sha256::Hash, Hash as HashTrait}; +use rand::{rng, RngCore}; + +use bitcoinpqc::{ + generate_keypair, public_key_size, secret_key_size, sign, signature_size, verify, Algorithm, KeyPair, +}; + +fn main() { + let _ = env_logger::try_init(); + + /* + In SPHINCS+ (underlying algorithm of SLH-DSA), the random data is used to: + * Initialize hash function parameters within the key generation + * Seed the Merkle tree construction that forms the public key + * Generate the secret key components that enable signing + */ + let random_data = get_random_bytes(128); + println!("Generated random data of size {}", random_data.len()); + + let keypair: KeyPair = generate_keypair(Algorithm::SLH_DSA_128S, &random_data) + .expect("Failed to generate SLH-DSA-128S keypair"); + + let message_bytes = b"SLH-DSA-128S Test Message"; + + println!("Message to sign: {message_bytes:?}"); + + /* No need to hash the message + 1. Variable Input Size: SPHINCS+ can handle messages of arbitrary length directly + 2. Internal Hashing: The SPHINCS+ algorithm internally handles message processing and hashing as part of its design + 3. Hash-Based Design: SPHINCS+ is built on hash functions and Merkle trees, so it's designed to work with variable-length inputs + 4. No Curve Constraints: Unlike elliptic curve schemes, SPHINCS+ doesn't have fixed field size requirements + + SLH-DSA doesn't use nonces like Schnorr does. + With SLH-DSA, randomness is built into the key generation process only ( and not the signing process; ie: SECP256K1) + Thus, no need for aux_rand data fed to the signature function. + The signing algorithm is deterministic and doesn't require random input during signing. + */ + + let signature = sign(&keypair.secret_key, message_bytes).expect("Failed to sign with SLH-DSA-128S"); + + println!( + "Signature created successfully, size: {}", + signature.bytes.len() + ); + println!( + "Signature prefix: {:02x?}", + &signature.bytes[..8.min(signature.bytes.len())] + ); + + // Verify the signature + println!("Verifying signature..."); + let result = verify(&keypair.public_key, message_bytes, &signature); + println!("Verification result: {result:?}"); + + assert!(result.is_ok(), "SLH-DSA-128S signature verification failed"); + + // Try to verify with a modified message - should fail + let modified_message = b"SLH-DSA-128S Modified Message"; + println!("Modified message: {modified_message:?}"); + + let result = verify(&keypair.public_key, modified_message, &signature); + println!("Verification with modified message result: {result:?}"); + + assert!( + result.is_err(), + "SLH-DSA-128S verification should fail with modified message" + ); +} + +fn get_random_bytes(size: usize) -> Vec { + let mut bytes = vec![0u8; size]; + rng().fill_bytes(&mut bytes); + bytes +} diff --git a/bip-0360/ref-impl/rust/src/bin/slh_dsa_key_gen.rs b/bip-0360/ref-impl/rust/src/bin/slh_dsa_key_gen.rs new file mode 100644 index 0000000000..999d487d3d --- /dev/null +++ b/bip-0360/ref-impl/rust/src/bin/slh_dsa_key_gen.rs @@ -0,0 +1,33 @@ +use std::env; +use log::info; +use rand::{rng, RngCore}; + +use bitcoinpqc::{ + generate_keypair, public_key_size, secret_key_size, Algorithm, KeyPair, +}; + +fn main() { + let _ = env_logger::try_init(); + + /* + In SPHINCS+ (underlying algorithm of SLH-DSA), the random data is used to: + * Initialize hash function parameters within the key generation + * Seed the Merkle tree construction that forms the public key + * Generate the secret key components that enable signing + */ + let random_data = get_random_bytes(128); + println!("Generated random data of size {}", random_data.len()); + + let keypair: KeyPair = generate_keypair(Algorithm::SLH_DSA_128S, &random_data) + .expect("Failed to generate SLH-DSA-128S keypair"); + + info!("public key size / value = {}, {}", public_key_size(Algorithm::SLH_DSA_128S), hex::encode(&keypair.public_key.bytes)); + info!("private key size / value = {}, {}", secret_key_size(Algorithm::SLH_DSA_128S), hex::encode(&keypair.secret_key.bytes)); + +} + +fn get_random_bytes(size: usize) -> Vec { + let mut bytes = vec![0u8; size]; + rng().fill_bytes(&mut bytes); + bytes +} diff --git a/bip-0360/ref-impl/rust/src/data_structures.rs b/bip-0360/ref-impl/rust/src/data_structures.rs new file mode 100644 index 0000000000..11f653aec7 --- /dev/null +++ b/bip-0360/ref-impl/rust/src/data_structures.rs @@ -0,0 +1,595 @@ +use std::collections::HashMap; +use serde::{Deserialize, Serialize}; +use log::debug; + +// Add imports for the unified keypair +use bitcoin::secp256k1::{SecretKey, XOnlyPublicKey}; +use bitcoinpqc::{KeyPair, Algorithm}; + +/// Enum representing the type of leaf script to create +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum LeafScriptType { + /// Script requires only SLH-DSA signature + SlhDsaOnly, + /// Script requires only Schnorr signature + SchnorrOnly, + /// Script requires both Schnorr and SLH-DSA signatures (in that order) + ConcatenatedSchnorrAndSlhDsaSameLeaf, + /// Leaves of TapTree are mixed. Some leaves are locked using Schnorr and others are locked using SLH-DSA + Mixed, + /// Script type is not applicable + NotApplicable, +} + +impl LeafScriptType { + /// Check if this script type uses SLH-DSA + pub fn uses_slh_dsa(&self) -> bool { + matches!(self, LeafScriptType::SlhDsaOnly | LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf) + } + + /// Check if this script type uses Schnorr + pub fn uses_schnorr(&self) -> bool { + matches!(self, LeafScriptType::SchnorrOnly | LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf) + } + + /// Check if this script type requires both signature types + pub fn requires_both(&self) -> bool { + matches!(self, LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf) + } + + /// Check if TapTree uses Schnorr for some leaves and SLH-DSA for others + pub fn uses_mixed(&self) -> bool { + matches!(self, LeafScriptType::Mixed) + } + + /// Check if this script type is not applicable + pub fn is_not_applicable(&self) -> bool { + matches!(self, LeafScriptType::NotApplicable) + } + + /// Convert to string representation for serialization + pub fn to_string(&self) -> String { + match self { + LeafScriptType::SlhDsaOnly => "SLH_DSA_ONLY".to_string(), + LeafScriptType::SchnorrOnly => "SCHNORR_ONLY".to_string(), + LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf => "CONCATENATED_SCHNORR_AND_SLH_DSA".to_string(), + LeafScriptType::Mixed => "MIXED".to_string(), + LeafScriptType::NotApplicable => "NOT_APPLICABLE".to_string(), + } + } + + /// Parse from string representation + pub fn from_string(s: &str) -> Self { + match s { + "SLH_DSA_ONLY" => LeafScriptType::SlhDsaOnly, + "SCHNORR_ONLY" => LeafScriptType::SchnorrOnly, + "CONCATENATED_SCHNORR_AND_SLH_DSA" => LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf, + "MIXED" => LeafScriptType::Mixed, + _ => LeafScriptType::NotApplicable, + } + } +} + +#[derive(Debug, Serialize)] +pub struct TestVectors { + pub version: u32, + #[serde(rename = "test_vectors")] + pub test_vectors: Vec, + #[serde(skip, default = "HashMap::new")] + pub test_vector_map: HashMap, +} + +impl<'de> Deserialize<'de> for TestVectors { + fn deserialize(deserializer: D) -> Result + where + D: serde::Deserializer<'de>, + { + #[derive(Deserialize)] + struct Helper { + version: u32, + #[serde(rename = "test_vectors")] + test_vectors: Vec, + } + + let helper = Helper::deserialize(deserializer)?; + + let mut test_vector_map = HashMap::new(); + for test in helper.test_vectors.iter() { + test_vector_map.insert(test.id.clone(), test.clone()); + } + + Ok(TestVectors { + version: helper.version, + test_vectors: helper.test_vectors, + test_vector_map, + }) + } +} + +#[derive(Debug, Serialize, Deserialize, Clone)] +pub struct TestVector { + pub id: String, + pub objective: String, + pub given: TestVectorGiven, + pub intermediary: TestVectorIntermediary, + pub expected: TestVectorExpected, +} + +#[derive(Debug, Serialize, Deserialize, Clone)] +pub struct TestVectorGiven { + + #[serde(rename = "internalPubkey")] + pub internal_pubkey: Option, + + #[serde(rename = "scriptTree")] + pub script_tree: Option, + + #[serde(rename = "scriptInputs")] + pub script_inputs: Option>, + #[serde(rename = "scriptHex")] + pub script_hex: Option, + #[serde(rename = "controlBlock")] + pub control_block: Option, +} + +#[derive(Debug, Serialize, Deserialize, Clone)] +pub struct TestVectorIntermediary { + + #[serde(default)] + #[serde(rename = "leafHashes")] + pub leaf_hashes: Vec, + #[serde(rename = "merkleRoot")] + pub merkle_root: Option +} + + +#[derive(Debug, Serialize, Deserialize, Clone)] +pub struct TestVectorExpected { + #[serde(rename = "scriptPubKey")] + pub script_pubkey: Option, + #[serde(rename = "bip350Address")] + pub bip350_address: Option, + #[serde(default)] + #[serde(rename = "scriptPathControlBlocks")] + pub script_path_control_blocks: Option>, + #[serde(rename = "error")] + pub error: Option, + #[serde(rename = "address")] + pub address: Option, + #[serde(default)] + pub witness: Option +} + +#[derive(Debug, Serialize, Deserialize, Clone)] +pub struct TVScriptLeaf { + pub id: u8, + pub script: String, + #[serde(rename = "leafVersion")] + pub leaf_version: u8, +} + +// Taproot script trees are binary trees, so each branch should have exactly two children. +#[derive(Debug, Serialize, Clone)] +pub enum TVScriptTree { + Leaf(TVScriptLeaf), + Branch { + + // Box is used because Rust needs to know the exact size of types at compile time. + // Without it, we'd have an infinitely size recursive type. + // The enum itself is on the stack, but the Box fields within the Branch variant store pointers to heap-allocated ScriptTree values. + left: Box, + right: Box, + }, +} + +// Add custom deserialize implementation +impl<'de> Deserialize<'de> for TVScriptTree { + fn deserialize(deserializer: D) -> Result + where + D: serde::Deserializer<'de>, + { + #[derive(Deserialize)] + #[serde(untagged)] + enum Helper { + Leaf(TVScriptLeaf), + Branch(Vec), + } + + match Helper::deserialize(deserializer)? { + Helper::Leaf(leaf) => Ok(TVScriptTree::Leaf(leaf)), + Helper::Branch(v) => { + assert!(v.len() == 2, "Branch must have exactly two children"); + let mut iter = v.into_iter(); + Ok(TVScriptTree::Branch { + left: Box::new(iter.next().unwrap()), + right: Box::new(iter.next().unwrap()), + }) + } + } + } +} + +// Add this enum before the TVScriptTree implementation +#[derive(Debug, Copy, Clone, Eq, PartialEq)] +pub enum Direction { + Left, + Right, + Root, +} + +impl TVScriptTree { + /// Implements a "post-order" traversal as follows: left, right, branch + pub fn traverse_with_depth(&self, depth: u8, direction: Direction, f: &mut F) { + match self { + TVScriptTree::Branch { left, right } => { + + right.traverse_with_depth(depth, Direction::Right, f); // Pass Right for right subtree + left.traverse_with_depth(depth, Direction::Left, f); // Pass Left for left subtree + f(self, depth, direction); // Pass the current node's direction + } + TVScriptTree::Leaf { .. } => { + f(self, depth, direction); + } + } + } + + /// Traverses the tree visiting right subtree leaves first, then left subtree leaves. + /// Depth increases by 1 at each branch level. + /* + root (depth 0) + / \ + L0 (depth 1) (subtree) (depth 1) + / \ + L1 (depth 2) L2 (depth 2) + + The new traversal will visit: + L1 at depth 2 -> L2 at depth 2 -> L0 at depth 1 + */ + pub fn traverse_with_right_subtree_first(&self, depth: u8, direction: Direction, f: &mut F) { + match self { + TVScriptTree::Branch { left, right } => { + let next_depth = depth + 1; + // Visit right subtree first + right.traverse_with_right_subtree_first(next_depth, Direction::Right, f); + // Then visit left subtree + left.traverse_with_right_subtree_first(next_depth, Direction::Left, f); + } + TVScriptTree::Leaf { .. } => { + f(self, depth, direction); + } + } + } +} + +impl std::fmt::Display for Direction { + fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + match self { + Direction::Left => write!(f, "L"), + Direction::Right => write!(f, "R"), + Direction::Root => write!(f, "Root"), + } + } +} + +pub struct ScriptTreeHashCache { + pub leaf_hashes: HashMap, + pub branch_hashes: HashMap, +} + +impl ScriptTreeHashCache { + pub fn new() -> Self { + Self { + leaf_hashes: HashMap::new(), + branch_hashes: HashMap::new(), + } + } + + pub fn set_leaf_hash(&mut self, branch_id: u8, direction: Direction, hash: String) { + let key = format!("{branch_id}_{direction}"); + debug!("set_leaf_hash: key: {}, hash: {}", key, hash); + self.leaf_hashes.insert(key, hash); + } + + pub fn set_branch_hash(&mut self, branch_id: u8, hash: String) { + self.branch_hashes.insert(branch_id, hash); + } +} + +fn serialize_hex(bytes: &Vec, s: S) -> Result +where + S: serde::Serializer, +{ + s.serialize_str(&hex::encode(bytes)) +} + +fn deserialize_hex<'de, D>(d: D) -> Result, D::Error> +where + D: serde::Deserializer<'de>, +{ + let s = String::deserialize(d)?; + hex::decode(s).map_err(serde::de::Error::custom) +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct SpendDetails { + pub tx_hex: String, + #[serde(serialize_with = "serialize_hex")] + #[serde(deserialize_with = "deserialize_hex")] + pub sighash: Vec, + #[serde(serialize_with = "serialize_hex")] + #[serde(deserialize_with = "deserialize_hex")] + pub sig_bytes: Vec, + #[serde(serialize_with = "serialize_hex")] + #[serde(deserialize_with = "deserialize_hex")] + pub derived_witness_vec: Vec, +} + +impl std::process::Termination for SpendDetails { + fn report(self) -> std::process::ExitCode { + if let Ok(json) = serde_json::to_string_pretty(&self) { + println!("{}", json); + } else { + println!("{:?}", self); + } + std::process::ExitCode::SUCCESS + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct UtxoReturn { + + pub script_pubkey_hex: String, + pub bech32m_address: String, + pub bitcoin_network: bitcoin::Network, +} + +impl std::process::Termination for UtxoReturn { + fn report(self) -> std::process::ExitCode { + if let Ok(json) = serde_json::to_string_pretty(&self) { + println!("{}", json); + } else { + println!("{:?}", self); + } + std::process::ExitCode::SUCCESS + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct TaptreeReturn { + pub leaf_script_priv_keys_hex: Vec, // Changed to support multiple private keys + pub leaf_script_hex: String, + pub tree_root_hex: String, + pub control_block_hex: String, + /// The script type of the leaf being returned (needed for spending) + pub leaf_script_type: String, +} + +impl std::process::Termination for TaptreeReturn { + fn report(self) -> std::process::ExitCode { + if let Ok(json) = serde_json::to_string_pretty(&self) { + println!("{}", json); + } else { + println!("{:?}", self); + } + std::process::ExitCode::SUCCESS + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ConstructionReturn { + pub taptree_return: TaptreeReturn, + pub utxo_return: UtxoReturn, +} + +impl std::process::Termination for ConstructionReturn { + fn report(self) -> std::process::ExitCode { + if let Ok(json) = serde_json::to_string_pretty(&self) { + println!("{}", json); + } else { + println!("{:?}", self); + } + std::process::ExitCode::SUCCESS + } +} + +/// A unified keypair that can contain either a Schnorr keypair or an SLH-DSA keypair +#[derive(Debug, Clone)] +pub enum UnifiedKeypair { + Schnorr(SecretKey, XOnlyPublicKey), + SlhDsa(KeyPair), +} + +/// A container for multiple keypairs that can be used in a single leaf script +#[derive(Debug, Clone)] +pub struct MultiKeypair { + pub schnorr_keypair: Option, + pub slh_dsa_keypair: Option, +} + +impl MultiKeypair { + /// Create a new MultiKeypair with only a Schnorr keypair + pub fn new_schnorr_only(schnorr_keypair: UnifiedKeypair) -> Self { + Self { + schnorr_keypair: Some(schnorr_keypair), + slh_dsa_keypair: None, + } + } + + /// Create a new MultiKeypair with only an SLH-DSA keypair + pub fn new_slh_dsa_only(slh_dsa_keypair: UnifiedKeypair) -> Self { + Self { + schnorr_keypair: None, + slh_dsa_keypair: Some(slh_dsa_keypair), + } + } + + /// Create a new MultiKeypair with both keypairs + pub fn new_combined(schnorr_keypair: UnifiedKeypair, slh_dsa_keypair: UnifiedKeypair) -> Self { + Self { + schnorr_keypair: Some(schnorr_keypair), + slh_dsa_keypair: Some(slh_dsa_keypair), + } + } + + /// Get all secret key bytes for serialization (in order: schnorr, then slh_dsa if present) + pub fn secret_key_bytes(&self) -> Vec> { + let mut result = Vec::new(); + if let Some(ref schnorr) = self.schnorr_keypair { + result.push(schnorr.secret_key_bytes()); + } + if let Some(ref slh_dsa) = self.slh_dsa_keypair { + result.push(slh_dsa.secret_key_bytes()); + } + result + } + + /// Get all public key bytes for script construction (in order: schnorr, then slh_dsa if present) + pub fn public_key_bytes(&self) -> Vec> { + let mut result = Vec::new(); + if let Some(ref schnorr) = self.schnorr_keypair { + result.push(schnorr.public_key_bytes()); + } + if let Some(ref slh_dsa) = self.slh_dsa_keypair { + result.push(slh_dsa.public_key_bytes()); + } + result + } + + /// Check if this contains a Schnorr keypair + pub fn has_schnorr(&self) -> bool { + self.schnorr_keypair.is_some() + } + + /// Check if this contains an SLH-DSA keypair + pub fn has_slh_dsa(&self) -> bool { + self.slh_dsa_keypair.is_some() + } + + /// Get the Schnorr keypair if present + pub fn schnorr_keypair(&self) -> Option<&UnifiedKeypair> { + self.schnorr_keypair.as_ref() + } + + /// Get the SLH-DSA keypair if present + pub fn slh_dsa_keypair(&self) -> Option<&UnifiedKeypair> { + self.slh_dsa_keypair.as_ref() + } +} + +/// Information about a single leaf in a mixed-type tree +/// Used when different leaves in the same tree use different algorithms +#[derive(Debug, Clone)] +pub struct MixedLeafInfo { + /// The leaf index in the tree + pub leaf_index: u32, + /// The script type for this specific leaf + pub leaf_script_type: LeafScriptType, + /// The keypairs for this leaf + pub keypairs: MultiKeypair, + /// The script for this leaf + pub script: Vec, +} + +impl MixedLeafInfo { + /// Create a new MixedLeafInfo for a Schnorr-only leaf + pub fn new_schnorr(leaf_index: u32, keypairs: MultiKeypair, script: Vec) -> Self { + Self { + leaf_index, + leaf_script_type: LeafScriptType::SchnorrOnly, + keypairs, + script, + } + } + + /// Create a new MixedLeafInfo for an SLH-DSA-only leaf + pub fn new_slh_dsa(leaf_index: u32, keypairs: MultiKeypair, script: Vec) -> Self { + Self { + leaf_index, + leaf_script_type: LeafScriptType::SlhDsaOnly, + keypairs, + script, + } + } + + /// Create a new MixedLeafInfo for a combined Schnorr+SLH-DSA leaf + pub fn new_combined(leaf_index: u32, keypairs: MultiKeypair, script: Vec) -> Self { + Self { + leaf_index, + leaf_script_type: LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf, + keypairs, + script, + } + } + + /// Get the secret key bytes for this leaf + pub fn secret_key_bytes(&self) -> Vec> { + self.keypairs.secret_key_bytes() + } + + /// Get the public key bytes for this leaf + pub fn public_key_bytes(&self) -> Vec> { + self.keypairs.public_key_bytes() + } +} + +impl UnifiedKeypair { + /// Create a new Schnorr keypair + pub fn new_schnorr(secret_key: SecretKey, public_key: XOnlyPublicKey) -> Self { + UnifiedKeypair::Schnorr(secret_key, public_key) + } + + /// Create a new SLH-DSA keypair + pub fn new_slh_dsa(keypair: KeyPair) -> Self { + UnifiedKeypair::SlhDsa(keypair) + } + + /// Get the secret key bytes for serialization + pub fn secret_key_bytes(&self) -> Vec { + match self { + UnifiedKeypair::Schnorr(secret_key, _) => secret_key.secret_bytes().to_vec(), + UnifiedKeypair::SlhDsa(keypair) => keypair.secret_key.bytes.clone(), + } + } + + /// Get the public key bytes for script construction + pub fn public_key_bytes(&self) -> Vec { + match self { + UnifiedKeypair::Schnorr(_, public_key) => public_key.serialize().to_vec(), + UnifiedKeypair::SlhDsa(keypair) => keypair.public_key.bytes.clone(), + } + } + + /// Get the algorithm type + pub fn algorithm(&self) -> &'static str { + match self { + UnifiedKeypair::Schnorr(_, _) => "Schnorr", + UnifiedKeypair::SlhDsa(_) => "SLH-DSA", + } + } + + /// Check if this is a Schnorr keypair + pub fn is_schnorr(&self) -> bool { + matches!(self, UnifiedKeypair::Schnorr(_, _)) + } + + /// Check if this is an SLH-DSA keypair + pub fn is_slh_dsa(&self) -> bool { + matches!(self, UnifiedKeypair::SlhDsa(_)) + } + + /// Get the underlying Schnorr keypair if this is a Schnorr keypair + pub fn as_schnorr(&self) -> Option<(&SecretKey, &XOnlyPublicKey)> { + match self { + UnifiedKeypair::Schnorr(secret_key, public_key) => Some((secret_key, public_key)), + _ => None, + } + } + + /// Get the underlying SLH-DSA keypair if this is an SLH-DSA keypair + pub fn as_slh_dsa(&self) -> Option<&KeyPair> { + match self { + UnifiedKeypair::SlhDsa(keypair) => Some(keypair), + _ => None, + } + } +} diff --git a/bip-0360/ref-impl/rust/src/error.rs b/bip-0360/ref-impl/rust/src/error.rs new file mode 100644 index 0000000000..d2cb98b9e5 --- /dev/null +++ b/bip-0360/ref-impl/rust/src/error.rs @@ -0,0 +1,16 @@ +use thiserror::Error; + +#[derive(Error, Debug)] +pub enum P2MRError { + + #[error("P2TR requires witness version of 1")] + P2trRequiresWitnessVersion1, + + + #[error("P2MR requires a script tree with at least one leaf")] + MissingScriptTreeLeaf, + + // We can add more specific error variants here as needed + #[error("Invalid script tree structure: {0}")] + InvalidScriptTree(String), +} \ No newline at end of file diff --git a/bip-0360/ref-impl/rust/src/lib.rs b/bip-0360/ref-impl/rust/src/lib.rs new file mode 100644 index 0000000000..e9c9816d14 --- /dev/null +++ b/bip-0360/ref-impl/rust/src/lib.rs @@ -0,0 +1,721 @@ +pub mod data_structures; +pub mod error; + +use log::{debug, info, error}; +use std::env; +use std::io::Write; +use rand::{rng, RngCore}; +use once_cell::sync::Lazy; +use bitcoin::hashes::{sha256, Hash}; +use bitcoin::key::{Secp256k1, Parity}; +use bitcoin::secp256k1::{Message, SecretKey, Keypair, rand::rngs::OsRng, rand::thread_rng, rand::Rng, schnorr::Signature}; +use bitcoin::{ Amount, TxOut, WPubkeyHash, + Address, Network, OutPoint, + blockdata::witness::Witness, + Script, ScriptBuf, XOnlyPublicKey, PublicKey, + sighash::{SighashCache, TapSighashType, Prevouts, TapSighash}, + taproot::{LeafVersion, NodeInfo, TapLeafHash, TapNodeHash, TapTree, ScriptLeaves, TaprootMerkleBranch, TaprootBuilder, TaprootSpendInfo, ControlBlock}, + transaction::{Transaction, Sequence} +}; + +use bitcoin::p2mr::{P2mrScriptBuf, P2mrBuilder, P2mrSpendInfo, P2mrControlBlock, P2MR_LEAF_VERSION}; + +use bitcoinpqc::{ + generate_keypair, public_key_size, secret_key_size, Algorithm, KeyPair, sign, verify, +}; + +use data_structures::{SpendDetails, UtxoReturn, TaptreeReturn, UnifiedKeypair, MultiKeypair, LeafScriptType, MixedLeafInfo}; + +/* Secp256k1 implements the Signing trait when it's initialized in signing mode. + It's important to note that Secp256k1 has different capabilities depending on how it's constructed: + * Secp256k1::new() creates a context capable of both signing and verification + * Secp256k1::signing_only() creates a context that can only sign + * Secp256k1::verification_only() creates a context that can only verify +*/ +static SECP: Lazy> = Lazy::new(Secp256k1::new); + +/// Creates a Huffman tree with leaves of the specified script type. +/// +/// For Mixed type, leaves alternate between Schnorr (even indices) and SLH-DSA (odd indices). +/// The LEAF_TO_SPEND_FROM_TYPE env var can override the type for the leaf of interest. +/// +/// Returns: (huffman_entries, keypairs_of_interest, script_buf_of_interest, actual_leaf_type) +fn create_huffman_tree(leaf_script_type: LeafScriptType) -> (Vec<(u32, ScriptBuf)>, MultiKeypair, ScriptBuf, LeafScriptType) { + + let mut total_leaf_count: u32 = 1; + if let Ok(env_value) = env::var("TOTAL_LEAF_COUNT") { + if let Ok(parsed_value) = env_value.parse::() { + total_leaf_count = parsed_value; + } + } + + let mut leaf_to_spend_from: u32 = 0; + if let Ok(env_value) = env::var("LEAF_TO_SPEND_FROM") { + if let Ok(parsed_value) = env_value.parse::() { + leaf_to_spend_from = parsed_value; + } + } + + // For Mixed mode, allow overriding the type of the leaf of interest + let leaf_to_spend_from_type: Option = if leaf_script_type == LeafScriptType::Mixed { + env::var("LEAF_TO_SPEND_FROM_TYPE").ok().map(|s| LeafScriptType::from_string(&s)) + } else { + None + }; + + if total_leaf_count < 1 { + panic!("total_leaf_count must be greater than 0"); + } + if leaf_to_spend_from >= total_leaf_count { + panic!("leaf_to_spend_from must be less than total_leaf_count and greater than 0"); + } + + debug!("Creating multi-leaf taptree with total_leaf_count: {}, leaf_to_spend_from: {}", total_leaf_count, leaf_to_spend_from); + let mut huffman_entries: Vec<(u32, ScriptBuf)> = vec![]; + let mut keypairs_of_interest: Option = None; + let mut script_buf_of_interest: Option = None; + let mut actual_leaf_type_of_interest: LeafScriptType = leaf_script_type; + + for leaf_index in 0..total_leaf_count { + let keypairs: MultiKeypair; + let script_buf: ScriptBuf; + + // Determine the effective script type for this leaf + let effective_script_type = if leaf_script_type == LeafScriptType::Mixed { + // For Mixed mode, check if this is the leaf of interest with an override + if leaf_index == leaf_to_spend_from && leaf_to_spend_from_type.is_some() { + leaf_to_spend_from_type.unwrap() + } else { + // Default pattern: even indices use Schnorr, odd indices use SLH-DSA + if leaf_index % 2 == 0 { + LeafScriptType::SchnorrOnly + } else { + LeafScriptType::SlhDsaOnly + } + } + } else { + leaf_script_type + }; + + match effective_script_type { + LeafScriptType::SchnorrOnly => { + let schnorr_keypair = acquire_schnorr_keypair(); + keypairs = MultiKeypair::new_schnorr_only(schnorr_keypair); + let pubkey_bytes = keypairs.schnorr_keypair().unwrap().public_key_bytes(); + // OP_PUSHBYTES_32 <32-byte xonly pubkey> OP_CHECKSIG + let mut script_buf_bytes = vec![0x20]; + script_buf_bytes.extend_from_slice(&pubkey_bytes); + script_buf_bytes.push(0xac); // OP_CHECKSIG + script_buf = ScriptBuf::from_bytes(script_buf_bytes); + }, + LeafScriptType::SlhDsaOnly => { + let slh_dsa_keypair = acquire_slh_dsa_keypair(); + keypairs = MultiKeypair::new_slh_dsa_only(slh_dsa_keypair); + let pubkey_bytes = keypairs.slh_dsa_keypair().unwrap().public_key_bytes(); + // OP_PUSHBYTES_32 <32-byte pubkey> OP_SUBSTR + let mut script_buf_bytes = vec![0x20]; + script_buf_bytes.extend_from_slice(&pubkey_bytes); + script_buf_bytes.push(0x7f); // OP_SUBSTR + script_buf = ScriptBuf::from_bytes(script_buf_bytes); + }, + LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf => { + // For combined scripts, we need both keypairs + let schnorr_keypair = acquire_schnorr_keypair(); + let slh_dsa_keypair = acquire_slh_dsa_keypair(); + keypairs = MultiKeypair::new_combined(schnorr_keypair, slh_dsa_keypair); + + let schnorr_pubkey = keypairs.schnorr_keypair().unwrap().public_key_bytes(); + let slh_dsa_pubkey = keypairs.slh_dsa_keypair().unwrap().public_key_bytes(); + + // Debug: Print the private key used for script construction + info!("SLH-DSA DEBUG: Script construction using private key: {}", hex::encode(keypairs.slh_dsa_keypair().unwrap().secret_key_bytes())); + info!("SLH-DSA DEBUG: Script construction using public key: {}", hex::encode(&slh_dsa_pubkey)); + + // Combined script: OP_CHECKSIG OP_SUBSTR OP_BOOLAND OP_VERIFY + let mut script_buf_bytes = vec![0x20]; // OP_PUSHBYTES_32 + script_buf_bytes.extend_from_slice(&schnorr_pubkey); + script_buf_bytes.push(0xac); // OP_CHECKSIG + script_buf_bytes.push(0x20); // OP_PUSHBYTES_32 + script_buf_bytes.extend_from_slice(&slh_dsa_pubkey); + script_buf_bytes.push(0x7f); // OP_SUBSTR + script_buf_bytes.push(0x9a); // OP_BOOLAND + script_buf_bytes.push(0x69); // OP_VERIFY + script_buf = ScriptBuf::from_bytes(script_buf_bytes); + } + LeafScriptType::Mixed => { + // This shouldn't happen as Mixed is resolved to a specific type above + panic!("LeafScriptType::Mixed should have been resolved to a specific type"); + } + LeafScriptType::NotApplicable => { + panic!("LeafScriptType::NotApplicable is not applicable"); + } + } + + let random_weight = thread_rng().gen_range(0..total_leaf_count); + + let huffman_entry = (random_weight, script_buf.clone()); + huffman_entries.push(huffman_entry); + if leaf_index == leaf_to_spend_from { + keypairs_of_interest = Some(keypairs); + script_buf_of_interest = Some(script_buf.clone()); + actual_leaf_type_of_interest = effective_script_type; + debug!("Selected leaf {}: type: {:?}, weight: {}, script: {:?}", + leaf_index, effective_script_type, random_weight, script_buf); + } + } + return (huffman_entries, keypairs_of_interest.unwrap(), script_buf_of_interest.unwrap(), actual_leaf_type_of_interest); +} + +/// Parses the TAP_TREE_LOCK_TYPE environment variable and returns the corresponding LeafScriptType. +/// Defaults to LeafScriptType::SchnorrOnly if the environment variable is not set. +/// Exits with error code 1 if an invalid value is provided. +/// +/// Supported values: +/// - SLH_DSA_ONLY: All leaves use SLH-DSA signatures +/// - SCHNORR_ONLY: All leaves use Schnorr signatures +/// - CONCATENATED_SCHNORR_AND_SLH_DSA: All leaves require both Schnorr and SLH-DSA signatures +/// - MIXED: Different leaves use different algorithms (Schnorr or SLH-DSA) (default) +pub fn tap_tree_lock_type() -> LeafScriptType { + match env::var("TAP_TREE_LOCK_TYPE") { + Ok(value) => match value.as_str() { + "SLH_DSA_ONLY" => LeafScriptType::SlhDsaOnly, + "SCHNORR_ONLY" => LeafScriptType::SchnorrOnly, + "CONCATENATED_SCHNORR_AND_SLH_DSA" => LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf, + "MIXED" => LeafScriptType::Mixed, + _ => { + error!("Invalid TAP_TREE_LOCK_TYPE '{}'. Must be one of: SLH_DSA_ONLY, SCHNORR_ONLY, CONCATENATED_SCHNORR_AND_SLH_DSA, MIXED", value); + std::process::exit(1); + } + }, + Err(_) => { + // Default to Mixed if not set + LeafScriptType::Mixed + } + } +} + +pub fn create_p2mr_multi_leaf_taptree() -> TaptreeReturn { + let leaf_script_type = tap_tree_lock_type(); + + let (huffman_entries, keypairs_of_interest, script_buf_of_interest, actual_leaf_type) = create_huffman_tree(leaf_script_type); + let p2mr_builder: P2mrBuilder = P2mrBuilder::with_huffman_tree(huffman_entries).unwrap(); + + + let p2mr_spend_info: P2mrSpendInfo = p2mr_builder.clone().finalize().unwrap(); + let merkle_root:TapNodeHash = p2mr_spend_info.merkle_root.unwrap(); + + + let tap_tree: TapTree = p2mr_builder.clone().into_inner().try_into_taptree().unwrap(); + let mut script_leaves: ScriptLeaves = tap_tree.script_leaves(); + let script_leaf = script_leaves + .find(|leaf| leaf.script() == script_buf_of_interest.as_script()) + .expect("Script leaf not found"); + + let merkle_root_node_info: NodeInfo = p2mr_builder.clone().into_inner().try_into_node_info().unwrap(); + let merkle_root: TapNodeHash = merkle_root_node_info.node_hash(); + + let leaf_hash: TapLeafHash = TapLeafHash::from_script(script_leaf.script(), LeafVersion::from_consensus(P2MR_LEAF_VERSION).unwrap()); + + // Convert leaf hash to big-endian for display (like Bitcoin Core) + let mut leaf_hash_bytes = leaf_hash.as_raw_hash().to_byte_array().to_vec(); + leaf_hash_bytes.reverse(); + + info!("leaf_hash: {}, merkle_root: {}, merkle_root: {}", + hex::encode(leaf_hash_bytes), + merkle_root, + merkle_root); + + let leaf_script = script_leaf.script(); + let merkle_branch: &TaprootMerkleBranch = script_leaf.merkle_branch(); + + info!("Leaf script: {}, merkle branch: {:?}", leaf_script, merkle_branch); + + let control_block: P2mrControlBlock = P2mrControlBlock{ + merkle_branch: merkle_branch.clone(), + }; + + // Not a requirement here but useful to demonstrate what Bitcoin Core does as the verifier when spending from a p2mr UTXO + control_block.verify_script_in_merkle_root_path(leaf_script, merkle_root); + + let control_block_hex: String = hex::encode(control_block.serialize()); + + return TaptreeReturn { + leaf_script_priv_keys_hex: keypairs_of_interest.secret_key_bytes() + .into_iter() + .map(|bytes| hex::encode(bytes)) + .collect(), + leaf_script_hex: leaf_script.to_hex_string(), + tree_root_hex: hex::encode(merkle_root.to_byte_array()), + control_block_hex: control_block_hex, + leaf_script_type: actual_leaf_type.to_string(), + }; +} + +pub fn create_p2tr_multi_leaf_taptree(p2tr_internal_pubkey_hex: String) -> TaptreeReturn { + + let (huffman_entries, keypairs_of_interest, script_buf_of_interest, actual_leaf_type) = create_huffman_tree(LeafScriptType::SchnorrOnly); + + let pub_key_string = format!("02{}", p2tr_internal_pubkey_hex); + let internal_pubkey: PublicKey = pub_key_string.parse::().unwrap(); + let internal_xonly_pubkey: XOnlyPublicKey = internal_pubkey.inner.into(); + + let p2tr_builder: TaprootBuilder = TaprootBuilder::with_huffman_tree(huffman_entries).unwrap(); + let p2tr_spend_info: TaprootSpendInfo = p2tr_builder.clone().finalize(&SECP, internal_xonly_pubkey).unwrap(); + let merkle_root: TapNodeHash = p2tr_spend_info.merkle_root().unwrap(); + + // During taproot construction, the internal key is "tweaked" by adding a scalar (the tap tweak hash) to it. + // If this tweaking operation results in a public key w/ an odd Y-coordinate, the parity bit is set to 1. + // When spending via script path, the verifier needs to know whether the output key has an even or odd Y-coordinate to properly reconstruct & verify the internal key. + // The internal key can be recovered from the output key using the parity bit and the merkle root. + let output_key_parity: Parity = p2tr_spend_info.output_key_parity(); + let output_key: XOnlyPublicKey = p2tr_spend_info.output_key().into(); + + info!("keypairs_of_interest: \n\tsecret_bytes: {:?} \n\tpubkeys: {:?} \n\tmerkle_root: {}", + keypairs_of_interest.secret_key_bytes().iter().map(|bytes| hex::encode(bytes)).collect::>(), // secret_bytes returns big endian + keypairs_of_interest.public_key_bytes().iter().map(|bytes| hex::encode(bytes)).collect::>(), // serialize returns little endian + merkle_root); + + let tap_tree: TapTree = p2tr_builder.clone().try_into_taptree().unwrap(); + let mut script_leaves: ScriptLeaves = tap_tree.script_leaves(); + let script_leaf = script_leaves + .find(|leaf| leaf.script() == script_buf_of_interest.as_script()) + .expect("Script leaf not found"); + let leaf_script = script_leaf.script().to_hex_string(); + let merkle_branch: &TaprootMerkleBranch = script_leaf.merkle_branch(); + debug!("Leaf script: {}, merkle branch: {:?}", leaf_script, merkle_branch); + + let control_block: ControlBlock = ControlBlock{ + leaf_version: LeafVersion::TapScript, + output_key_parity: output_key_parity, + internal_key: internal_xonly_pubkey, + merkle_branch: merkle_branch.clone(), + }; + let control_block_hex: String = hex::encode(control_block.serialize()); + + // Not a requirement but useful to demonstrate what Bitcoin Core does as the verifier when spending from a p2tr UTXO + let verify: bool = verify_taproot_commitment(control_block_hex.clone(), output_key, script_leaf.script()); + info!("verify_taproot_commitment: {}", verify); + + return TaptreeReturn { + leaf_script_priv_keys_hex: keypairs_of_interest.secret_key_bytes() + .into_iter() + .map(|bytes| hex::encode(bytes)) + .collect(), + leaf_script_hex: leaf_script, + tree_root_hex: hex::encode(merkle_root.to_byte_array()), + control_block_hex: control_block_hex, + leaf_script_type: actual_leaf_type.to_string(), + }; +} + +/// Parses the BITCOIN_NETWORK environment variable and returns the corresponding Network. +/// Defaults to Network::Regtest if the environment variable is not set or has an invalid value. +pub fn get_bitcoin_network() -> Network { + let mut bitcoin_network: Network = Network::Regtest; + + // Check for BITCOIN_NETWORK environment variable and override if set + if let Ok(network_str) = std::env::var("BITCOIN_NETWORK") { + bitcoin_network = match network_str.to_lowercase().as_str() { + "regtest" => Network::Regtest, + "testnet" => Network::Testnet, + "signet" => Network::Signet, + _ => { + debug!("Invalid BITCOIN_NETWORK value '{}', using default Regtest network", network_str); + Network::Regtest + } + }; + } + + bitcoin_network +} + +pub fn create_p2mr_utxo(merkle_root_hex: String) -> UtxoReturn { + + let merkle_root_bytes= hex::decode(merkle_root_hex.clone()).unwrap(); + let merkle_root: TapNodeHash = TapNodeHash::from_byte_array(merkle_root_bytes.try_into().unwrap()); + + /* commit (in scriptPubKey) to the merkle root of all the script path leaves. ie: + This output key is what gets committed to in the final P2MR address (ie: scriptPubKey) + */ + let script_buf: P2mrScriptBuf = P2mrScriptBuf::new_p2mr(merkle_root); + let script: &Script = script_buf.as_script(); + let script_pubkey = script.to_hex_string(); + + let bitcoin_network = get_bitcoin_network(); + + // derive bech32m address and verify against test vector + // p2mr address is comprised of network HRP + WitnessProgram (version + program) + let bech32m_address = Address::p2mr(Some(merkle_root), bitcoin_network); + + return UtxoReturn { + script_pubkey_hex: script_pubkey, + bech32m_address: bech32m_address.to_string(), + bitcoin_network, + }; + +} + +// Given script path p2tr or p2mr UTXO details, spend to p2wpkh +pub fn pay_to_p2wpkh_tx( + funding_tx_id_bytes: Vec, + funding_utxo_index: u32, + funding_utxo_amount_sats: u64, + funding_script_pubkey_bytes: Vec, + control_block_bytes: Vec, + leaf_script_bytes: Vec, + leaf_script_priv_keys_bytes: Vec>, // Changed to support multiple private keys + spend_output_pubkey_hash_bytes: Vec, + spend_output_amount_sats: u64, + leaf_script_type: LeafScriptType +) -> SpendDetails { + + let mut txid_little_endian = funding_tx_id_bytes.clone(); // initially in big endian format + txid_little_endian.reverse(); // convert to little endian format + + // vin: Create TxIn from the input utxo + // Details of this input tx are not known at this point + let input_tx_in = bitcoin::TxIn { + previous_output: OutPoint { + txid: bitcoin::Txid::from_slice(&txid_little_endian).unwrap(), // bitcoin::Txid expects the bytes in little-endian format + vout: funding_utxo_index, + }, + script_sig: ScriptBuf::new(), // Empty for segwit transactions - script goes in witness + sequence: Sequence::MAX, // Default sequence, allows immediate spending (no RBF or timelock) + witness: bitcoin::Witness::new(), // Empty for now, will be filled with signature and pubkey after signing + }; + + let spend_wpubkey_hash = WPubkeyHash::from_byte_array(spend_output_pubkey_hash_bytes.try_into().unwrap()); + let spend_output: TxOut = TxOut { + value: Amount::from_sat(spend_output_amount_sats), + script_pubkey: ScriptBuf::new_p2wpkh(&spend_wpubkey_hash), + }; + + // The spend tx to eventually be signed and broadcast + let mut unsigned_spend_tx = Transaction { + version: bitcoin::transaction::Version::TWO, + lock_time: bitcoin::locktime::absolute::LockTime::ZERO, + input: vec![input_tx_in], + output: vec![spend_output], + }; + + // Create the leaf hash + let leaf_script = ScriptBuf::from_bytes(leaf_script_bytes.clone()); + let leaf_hash: TapLeafHash = TapLeafHash::from_script(&leaf_script, LeafVersion::TapScript); + + /* prevouts parameter tells the sighash algorithm: + 1. The value of each input being spent (needed for fee calculation and sighash computation) + 2. The scriptPubKey of each input being spent (ie: type of output & how to validate the spend) + */ + let prevouts = vec![TxOut { + value: Amount::from_sat(funding_utxo_amount_sats), + script_pubkey: ScriptBuf::from_bytes(funding_script_pubkey_bytes.clone()), + }]; + info!("prevouts: {:?}", prevouts); + + let spending_tx_input_index = 0; + + // Create SighashCache + // At this point, sighash_cache does not know the values and type of input UTXO + let mut tapscript_sighash_cache = SighashCache::new(&mut unsigned_spend_tx); + + // Compute the sighash + let tapscript_sighash: TapSighash = tapscript_sighash_cache.taproot_script_spend_signature_hash( + spending_tx_input_index, // input_index + &Prevouts::All(&prevouts), + leaf_hash, + TapSighashType::All + ).unwrap(); + + info!("sighash: {:?}", tapscript_sighash); + + let spend_msg = Message::from(tapscript_sighash); + + let mut derived_witness: Witness = Witness::new(); + let mut sig_bytes = Vec::new(); + match leaf_script_type { + LeafScriptType::SlhDsaOnly => { + if leaf_script_priv_keys_bytes.len() != 1 { + panic!("SlhDsaOnly requires exactly one private key"); + } + let secret_key: bitcoinpqc::SecretKey = bitcoinpqc::SecretKey::try_from_slice( + Algorithm::SLH_DSA_128S, &leaf_script_priv_keys_bytes[0]).unwrap(); + let signature = sign(&secret_key, spend_msg.as_ref()).expect("Failed to sign with SLH-DSA-128S"); + debug!("SlhDsaOnly signature.bytes: {:?}", signature.bytes.len()); + let mut sig_bytes_with_sighash = signature.bytes.clone(); + sig_bytes_with_sighash.push(TapSighashType::All as u8); + derived_witness.push(&sig_bytes_with_sighash); + sig_bytes = signature.bytes; + }, + LeafScriptType::SchnorrOnly => { + if leaf_script_priv_keys_bytes.len() != 1 { + panic!("SchnorrOnly requires exactly one private key"); + } + // assumes bytes are in big endian format + let secret_key = SecretKey::from_slice(&leaf_script_priv_keys_bytes[0]).unwrap(); + + // Spending a p2tr UTXO thus using Schnorr signature + // The aux_rand parameter ensures that signing the same message with the same key produces the same signature + // Otherwise (without providing aux_rand), the secp256k1 library internally generates a random nonce for each signature + let signature: bitcoin::secp256k1::schnorr::Signature = SECP.sign_schnorr_with_aux_rand( + &spend_msg, + &secret_key.keypair(&SECP), + &[0u8; 32] // 32 zero bytes of auxiliary random data + ); + sig_bytes = signature.serialize().to_vec(); + let mut sig_bytes_with_sighash = sig_bytes.clone(); + sig_bytes_with_sighash.push(TapSighashType::All as u8); + derived_witness.push(&sig_bytes_with_sighash); + debug!("SchnorrOnly signature bytes: {:?}", sig_bytes.len()); + }, + LeafScriptType::ConcatenatedSchnorrAndSlhDsaSameLeaf => { + if leaf_script_priv_keys_bytes.len() != 2 { + panic!("SchnorrAndSlhDsa requires exactly two private keys (Schnorr first, then SLH-DSA)"); + } + + // Generate Schnorr signature (first key) + let schnorr_secret_key = SecretKey::from_slice(&leaf_script_priv_keys_bytes[0]).unwrap(); + let schnorr_signature: bitcoin::secp256k1::schnorr::Signature = SECP.sign_schnorr_with_aux_rand( + &spend_msg, + &schnorr_secret_key.keypair(&SECP), + &[0u8; 32] // 32 zero bytes of auxiliary random data + ); + // Build combined signature for return value (without sighash bytes) + let mut combined_sig_bytes = schnorr_signature.serialize().to_vec(); + debug!("SchnorrAndSlhDsa schnorr_sig_bytes: {:?}", combined_sig_bytes.len()); + + // Generate SLH-DSA signature (second key) + let slh_dsa_secret_key: bitcoinpqc::SecretKey = bitcoinpqc::SecretKey::try_from_slice( + Algorithm::SLH_DSA_128S, &leaf_script_priv_keys_bytes[1]).unwrap(); + + // Debug: Print the private key being used for signature creation + info!("SLH-DSA DEBUG: Using private key for signature creation: {}", hex::encode(&leaf_script_priv_keys_bytes[1])); + + let slh_dsa_signature = sign(&slh_dsa_secret_key, spend_msg.as_ref()).expect("Failed to sign with SLH-DSA-128S"); + debug!("SchnorrAndSlhDsa slh_dsa_signature.bytes: {:?}", slh_dsa_signature.bytes.len()); + + // Add SLH-DSA signature to combined signature for return value + combined_sig_bytes.extend_from_slice(&slh_dsa_signature.bytes); + sig_bytes = combined_sig_bytes; + + // Build witness with sighash bytes + let mut witness_sig_bytes = schnorr_signature.serialize().to_vec(); + witness_sig_bytes.push(TapSighashType::All as u8); + witness_sig_bytes.extend_from_slice(&slh_dsa_signature.bytes); + witness_sig_bytes.push(TapSighashType::All as u8); + derived_witness.push(&witness_sig_bytes); + } + LeafScriptType::Mixed => { + // Mixed is not a valid type for spending - the actual leaf type should be used + panic!("LeafScriptType::Mixed is not valid for spending. Use the actual leaf type (SchnorrOnly or SlhDsaOnly)."); + } + LeafScriptType::NotApplicable => { + panic!("LeafScriptType::NotApplicable is not applicable"); + } + } + // Note: sighash byte is now appended to signatures, not as separate witness element + derived_witness.push(&leaf_script_bytes); + derived_witness.push(&control_block_bytes); + + let derived_witness_vec: Vec = derived_witness.iter().flatten().cloned().collect(); + + // Update the witness data for the tx's first input (index 0) + *tapscript_sighash_cache.witness_mut(spending_tx_input_index).unwrap() = derived_witness; + + // Get the signed transaction. + let signed_tx_obj: &mut Transaction = tapscript_sighash_cache.into_transaction(); + + let tx_hex = bitcoin::consensus::encode::serialize_hex(&signed_tx_obj); + + return SpendDetails { + tx_hex, + sighash: tapscript_sighash.as_byte_array().to_vec(), + sig_bytes: sig_bytes, + derived_witness_vec: derived_witness_vec, + }; +} + + +pub fn create_p2tr_utxo(merkle_root_hex: String, internal_pubkey_hex: String) -> UtxoReturn { + + let merkle_root_bytes= hex::decode(merkle_root_hex.clone()).unwrap(); + let merkle_root: TapNodeHash = TapNodeHash::from_byte_array(merkle_root_bytes.try_into().unwrap()); + + let pub_key_string = format!("02{}", internal_pubkey_hex); + let internal_pubkey: PublicKey = pub_key_string.parse::().unwrap(); + let internal_xonly_pubkey: XOnlyPublicKey = internal_pubkey.inner.into(); + + + let script_buf: ScriptBuf = ScriptBuf::new_p2tr(&SECP, internal_xonly_pubkey, Option::Some(merkle_root)); + let script: &Script = script_buf.as_script(); + let script_pubkey = script.to_hex_string(); + + let bitcoin_network = get_bitcoin_network(); + + // 4) derive bech32m address and verify against test vector + // p2mr address is comprised of network HRP + WitnessProgram (version + program) + let bech32m_address = Address::p2tr( + &SECP, + internal_xonly_pubkey, + Option::Some(merkle_root), + bitcoin_network + ); + + return UtxoReturn { + script_pubkey_hex: script_pubkey, + bech32m_address: bech32m_address.to_string(), + bitcoin_network, + }; + +} + + +// https://learnmeabitcoin.com/technical/upgrades/taproot/#examples +pub fn tagged_hash(tag: &str, data: &[u8]) -> String { + + // Create a hash of the tag first + let tag_hash = sha256::Hash::hash(tag.as_bytes()); + + // Create preimage: tag_hash || tag_hash || message + // tag_hash is prefixed twice so that the prefix is 64 bytes in total + let mut preimage = sha256::Hash::engine(); + preimage.write_all(&tag_hash.to_byte_array()).unwrap(); // First tag hash + preimage.write_all(&tag_hash.to_byte_array()).unwrap(); // Second tag hash + preimage.write_all(data).unwrap(); // Message data + let hash = sha256::Hash::from_engine(preimage).to_byte_array(); + hex::encode(hash) +} + +pub fn serialize_script(script: &Vec) -> Vec { + // get length of script as number of bytes + let length = script.len(); + + // return script with compact size prepended + let mut result = compact_size(length as u64); + result.extend_from_slice(&script); + result +} + +/// Encodes an integer into Bitcoin's compact size format +/// Returns a Vec containing the encoded bytes +fn compact_size(n: u64) -> Vec { + if n <= 252 { + vec![n as u8] + } else if n <= 0xffff { + let mut result = vec![0xfd]; + result.extend_from_slice(&(n as u16).to_le_bytes()); + result + } else if n <= 0xffffffff { + let mut result = vec![0xfe]; + result.extend_from_slice(&(n as u32).to_le_bytes()); + result + } else { + let mut result = vec![0xff]; + result.extend_from_slice(&n.to_le_bytes()); + result + } +} + +pub fn acquire_schnorr_keypair() -> UnifiedKeypair { + + /* OsRng typically draws from the OS's entropy pool (hardware random num generators, system events, etc), ie: + * 1. $ cat /proc/sys/kernel/random/entropy_avail + * 2. $ sudo dmesg | grep -i "random\|rng\|entropy" + + The Linux kernel's RNG (/dev/random and /dev/urandom) typically combines multiple entropy sources: ie: + * Hardware RNG (if available) + * CPU RNG instructions (RDRAND/RDSEED) + * Hardware events (disk I/O, network packets, keyboard/mouse input) + * Timer jitter + * Interrupt timing + */ + let keypair = Keypair::new(&SECP, &mut OsRng); + + let privkey: SecretKey = keypair.secret_key(); + let pubkey: (XOnlyPublicKey, Parity) = XOnlyPublicKey::from_keypair(&keypair); + UnifiedKeypair::new_schnorr(privkey, pubkey.0) +} + +pub fn verify_schnorr_signature_via_bytes(signature: &[u8], message: &[u8], pubkey_bytes: &[u8]) -> bool { + + // schnorr is 64 bytes so remove possible trailing Sighash Type byte if present + let mut sig_bytes = signature.to_vec(); + if sig_bytes.len() == 65 { + sig_bytes.pop(); // Remove the last byte + } + let signature = bitcoin::secp256k1::schnorr::Signature::from_slice(&sig_bytes).unwrap(); + let message = Message::from_digest_slice(message).unwrap(); + let pubkey = XOnlyPublicKey::from_slice(pubkey_bytes).unwrap(); + verify_schnorr_signature(signature, message, pubkey) +} + +pub fn verify_slh_dsa_via_bytes(signature: &[u8], message: &[u8], pubkey_bytes: &[u8]) -> bool { + + // Remove possible trailing Sighash Type byte if present (SLH-DSA-128S is 7856 bytes, so 7857 would indicate SIGHASH byte) + let mut sig_bytes = signature.to_vec(); + if sig_bytes.len() == 7857 { + sig_bytes.pop(); // Remove the last byte + } + + info!("verify_slh_dsa_via_bytes: signature length: {:?}, message: {:?}, pubkey_bytes: {:?}", + sig_bytes.len(), + hex::encode(message), + hex::encode(pubkey_bytes)); + + let signature = bitcoinpqc::Signature::try_from_slice(Algorithm::SLH_DSA_128S, &sig_bytes).unwrap(); + let public_key: bitcoinpqc::PublicKey = bitcoinpqc::PublicKey::try_from_slice(Algorithm::SLH_DSA_128S, pubkey_bytes).unwrap(); + verify(&public_key, message, &signature).is_ok() +} + +pub fn verify_schnorr_signature(mut signature: Signature, message: Message, pubkey: XOnlyPublicKey) -> bool { + + // schnorr is 64 bytes so remove possible trailing Sighash Type byte if present + if signature.serialize().to_vec().len() == 65 { + let mut sig_bytes = signature.serialize().to_vec(); + sig_bytes.pop(); // Remove the last byte + signature = bitcoin::secp256k1::schnorr::Signature::from_slice(&sig_bytes).unwrap(); + } + let is_valid: bool = SECP.verify_schnorr(&signature, &message, &pubkey).is_ok(); + if !is_valid { + error!("verify schnorr failed:\n\tsignature: {:?}\n\tmessage: {:?}\n\tpubkey: {:?}", + signature, + message, + hex::encode(pubkey.serialize())); + } + is_valid +} + +/* 1. Re-constructs merkle_root from merkle_path (found in control_block) and provided script. + 2. Determines the parity of the output key via the control byte (found in the control block). + - the parity bit indicates whether the output key has an even or odd Y-coordinate + 3. Computes the tap tweak hash using the internal key and reconstructed merkle root. + - tap_tweak_hash = tagged_hash("TapTweak", internal_key || merkle_root) + 4. Verifies that the provided output key can be derived from the internal key using the tweak. + - tap_tweak_hash = tagged_hash("TapTweak", internal_key || merkle_root) + 5. This proves the script is committed to in the taptree described by the output key. + */ +pub fn verify_taproot_commitment(control_block_hex: String, output_key: XOnlyPublicKey, script: &Script) -> bool { + + let control_block_bytes = hex::decode(control_block_hex).unwrap(); + let control_block: ControlBlock = ControlBlock::decode(&control_block_bytes).unwrap(); + + return control_block.verify_taproot_commitment(&SECP, output_key, script); +} + +fn acquire_slh_dsa_keypair() -> UnifiedKeypair { + /* + In SPHINCS+ (underlying algorithm of SLH-DSA), the random data is used to: + * Initialize hash function parameters within the key generation + * Seed the Merkle tree construction that forms the public key + * Generate the secret key components that enable signing + */ + let random_data = get_random_bytes(128); + let keypair: KeyPair = generate_keypair(Algorithm::SLH_DSA_128S, &random_data) + .expect("Failed to generate SLH-DSA-128S keypair"); + UnifiedKeypair::new_slh_dsa(keypair) +} + +fn get_random_bytes(size: usize) -> Vec { + let mut bytes = vec![0u8; size]; + rng().fill_bytes(&mut bytes); + bytes +} diff --git a/bip-0360/ref-impl/rust/tests/p2mr_construction.rs b/bip-0360/ref-impl/rust/tests/p2mr_construction.rs new file mode 100644 index 0000000000..38d790d104 --- /dev/null +++ b/bip-0360/ref-impl/rust/tests/p2mr_construction.rs @@ -0,0 +1,262 @@ +use std::collections::HashSet; +use bitcoin::{Network, ScriptBuf}; +use bitcoin::taproot::{LeafVersion, TapTree, ScriptLeaves, TapLeafHash, TaprootMerkleBranch, TapNodeHash}; +use bitcoin::p2mr::{P2mrBuilder, P2mrControlBlock, P2mrSpendInfo}; +use bitcoin::hashes::Hash; + +use hex; +use log::debug; +use once_cell::sync::Lazy; + +use p2mr_ref::data_structures::{TVScriptTree, TestVector, Direction, TestVectors, UtxoReturn}; +use p2mr_ref::error::P2MRError; +use p2mr_ref::{create_p2mr_utxo, tagged_hash}; + +// This file contains tests that execute against the BIP360 script-path-only test vectors. + +static TEST_VECTORS: Lazy = Lazy::new(|| { + let bip360_test_vectors = include_str!("../../common/tests/data/p2mr_construction.json"); + let test_vectors: TestVectors = serde_json::from_str(bip360_test_vectors).unwrap(); + assert_eq!(test_vectors.version, 1); + test_vectors +}); + +static P2TR_USING_V2_WITNESS_VERSION_ERROR: &str = "p2tr_using_v2_witness_version_error"; +static P2MR_MISSING_LEAF_SCRIPT_TREE_ERROR_TEST: &str = "p2mr_missing_leaf_script_tree_error"; +static P2MR_SINGLE_LEAF_SCRIPT_TREE_TEST: &str = "p2mr_single_leaf_script_tree"; +static P2MR_DIFFERENT_VERSION_LEAVES_TEST: &str = "p2mr_different_version_leaves"; +static P2MR_TWO_LEAF_SAME_VERSION_TEST: &str = "p2mr_two_leaf_same_version"; +static P2MR_THREE_LEAF_COMPLEX_TEST: &str = "p2mr_three_leaf_complex"; +static P2MR_THREE_LEAF_ALTERNATIVE_TEST: &str = "p2mr_three_leaf_alternative"; +static P2MR_SIMPLE_LIGHTNING_CONTRACT_TEST: &str = "p2mr_simple_lightning_contract"; + +#[test] +fn test_p2tr_using_v2_witness_version_error() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2TR_USING_V2_WITNESS_VERSION_ERROR).unwrap(); + let test_result: anyhow::Result<()> = process_test_vector_p2tr(test_vector); + assert!(matches!(test_result.unwrap_err().downcast_ref::(), + Some(P2MRError::P2trRequiresWitnessVersion1))); +} + +// https://learnmeabitcoin.com/technical/upgrades/taproot/#example-2-script-path-spend-simple +#[test] +fn test_p2mr_missing_leaf_script_tree_error() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_MISSING_LEAF_SCRIPT_TREE_ERROR_TEST).unwrap(); + let test_result: anyhow::Result<()> = process_test_vector_p2mr(test_vector); + assert!(matches!(test_result.unwrap_err().downcast_ref::(), + Some(P2MRError::MissingScriptTreeLeaf))); +} + +// https://learnmeabitcoin.com/technical/upgrades/taproot/#example-2-script-path-spend-simple +#[test] +fn test_p2mr_single_leaf_script_tree() { + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_SINGLE_LEAF_SCRIPT_TREE_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_different_version_leaves() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_DIFFERENT_VERSION_LEAVES_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_simple_lightning_contract() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_SIMPLE_LIGHTNING_CONTRACT_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_two_leaf_same_version() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_TWO_LEAF_SAME_VERSION_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_three_leaf_complex() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_THREE_LEAF_COMPLEX_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_three_leaf_alternative() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_THREE_LEAF_ALTERNATIVE_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +fn process_test_vector_p2tr(test_vector: &TestVector) -> anyhow::Result<()> { + let script_pubkey_hex = test_vector.expected.script_pubkey.as_ref().unwrap(); + let script_pubkey_bytes = hex::decode(script_pubkey_hex).unwrap(); + if script_pubkey_bytes[0] != 0x51 { + return Err(P2MRError::P2trRequiresWitnessVersion1.into()); + } + Ok(()) +} + +fn process_test_vector_p2mr(test_vector: &TestVector) -> anyhow::Result<()> { + + let tv_script_tree: Option<&TVScriptTree> = test_vector.given.script_tree.as_ref(); + + let mut tv_leaf_count: u8 = 0; + let mut current_branch_id: u8 = 0; + + // TaprootBuilder expects the addition of each leaf script with its associated depth + // It then constructs the binary tree in DFS order, sorting siblings lexicographically & combining them via BIP341's tapbranch_hash + // Use of TaprootBuilder avoids user error in constructing branches manually and ensures Merkle tree correctness and determinism + let mut p2mr_builder: P2mrBuilder = P2mrBuilder::new(); + + let mut control_block_data: Vec<(ScriptBuf, LeafVersion)> = Vec::new(); + + // 1) traverse test vector script tree and add leaves to P2MR builder + if let Some(script_tree) = tv_script_tree { + + script_tree.traverse_with_right_subtree_first(0, Direction::Root,&mut |node, depth, direction| { + + if let TVScriptTree::Leaf(tv_leaf) = node { + + let tv_leaf_script_bytes = hex::decode(&tv_leaf.script).unwrap(); + + // NOTE: IOT to execute script_info.control_block(..), will add these to a vector + let tv_leaf_script_buf = ScriptBuf::from_bytes(tv_leaf_script_bytes.clone()); + let tv_leaf_version = LeafVersion::from_consensus(tv_leaf.leaf_version).unwrap(); + control_block_data.push((tv_leaf_script_buf.clone(), tv_leaf_version)); + + let mut modified_depth = depth + 1; + if direction == Direction::Root { + modified_depth = depth; + } + debug!("traverse_with_depth: leaf_count: {}, depth: {}, modified_depth: {}, direction: {}, tv_leaf_script: {}", + tv_leaf_count, depth, modified_depth, direction, tv_leaf.script); + + // NOTE: Some of the the test vectors in this project specify leaves with non-standard versions (ie: 250 / 0xfa) + p2mr_builder = p2mr_builder.clone().add_leaf_with_ver(depth, tv_leaf_script_buf.clone(), tv_leaf_version) + .unwrap_or_else(|e| { + panic!("Failed to add leaf: {:?}", e); + }); + + tv_leaf_count += 1; + } else if let TVScriptTree::Branch { left, right } = node { + // No need to calculate branch hash. + // TaprootBuilder does this for us. + debug!("branch_count: {}, depth: {}, direction: {}", current_branch_id, depth, direction); + current_branch_id += 1; + } + }); + }else { + return Err(P2MRError::MissingScriptTreeLeaf.into()); + } + + let spend_info: P2mrSpendInfo = p2mr_builder.clone() + .finalize() + .unwrap_or_else(|e| { + panic!("finalize failed: {:?}", e); + }); + + let derived_merkle_root: TapNodeHash = spend_info.merkle_root.unwrap(); + + // 2) verify derived merkle root against test vector + let test_vector_merkle_root = test_vector.intermediary.merkle_root.as_ref().unwrap(); + assert_eq!( + derived_merkle_root.to_string(), + *test_vector_merkle_root, + "Merkle root mismatch" + ); + debug!("just passed merkle root validation: {}", test_vector_merkle_root); + + let test_vector_leaf_hashes_vec: Vec = test_vector.intermediary.leaf_hashes.clone(); + let test_vector_leaf_hash_set: HashSet = test_vector_leaf_hashes_vec.iter().cloned().collect(); + let test_vector_control_blocks_vec = &test_vector.expected.script_path_control_blocks; + let test_vector_control_blocks_set: HashSet = test_vector_control_blocks_vec.as_ref().unwrap().iter().cloned().collect(); + let tap_tree: TapTree = p2mr_builder.clone().into_inner().try_into_taptree().unwrap(); + let script_leaves: ScriptLeaves = tap_tree.script_leaves(); + + // TO-DO: Investigate why the ordering of script leaves seems to be reverse of test vectors. + // 3) Iterate through leaves of derived script tree and verify both script leaf hashes and control blocks + for derived_leaf in script_leaves { + + let version = derived_leaf.version(); + let script = derived_leaf.script(); + let merkle_branch: &TaprootMerkleBranch = derived_leaf.merkle_branch(); + + let derived_leaf_hash: TapLeafHash = TapLeafHash::from_script(script, version); + let leaf_hash = hex::encode(derived_leaf_hash.as_raw_hash().to_byte_array()); + assert!( + test_vector_leaf_hash_set.contains(&leaf_hash), + "Leaf hash not found in expected set for {}", leaf_hash + ); + debug!("just passed leaf_hash validation: {}", leaf_hash); + + // Each leaf in the script tree has a corresponding control block. + // Specific to P2TR, the 3 sections of the control block (control byte, public key & merkle path) are highlighted here: + // https://learnmeabitcoin.com/technical/upgrades/taproot/#script-path-spend-control-block + // The control block, which includes the Merkle path, must be 33 + 32 * n bytes, where n is the number of Merkle path hashes (n ≥ 0). + // There is no consensus limit on n, but large Merkle trees increase the witness size, impacting block weight. + // NOTE: Control blocks could have also been obtained from spend_info.control_block(..) using the data in control_block_data + debug!("merkle_branch nodes: {:?}", merkle_branch); + let derived_control_block: P2mrControlBlock = P2mrControlBlock{ + merkle_branch: merkle_branch.clone(), + }; + let serialized_control_block = derived_control_block.serialize(); + debug!("derived_control_block: {:?}, merkle_branch size: {}, control_block size: {}, serialized size: {}", + derived_control_block, + merkle_branch.len(), + derived_control_block.size(), + serialized_control_block.len()); + let derived_serialized_control_block = hex::encode(serialized_control_block); + assert!( + test_vector_control_blocks_set.contains(&derived_serialized_control_block), + "Control block mismatch: {}, expected: {:?}", derived_serialized_control_block, test_vector_control_blocks_set + ); + debug!("leaf_hash: {}, derived_serialized_control_block: {}", leaf_hash, derived_serialized_control_block); + + } + + let p2mr_utxo_return: UtxoReturn = create_p2mr_utxo(derived_merkle_root.to_string()); + + assert_eq!( + p2mr_utxo_return.script_pubkey_hex, + *test_vector.expected.script_pubkey.as_ref().unwrap(), + "Script pubkey mismatch" + ); + debug!("just passed script_pubkey validation. script_pubkey = {}", p2mr_utxo_return.script_pubkey_hex); + + let bech32m_address: String = p2mr_utxo_return.bech32m_address; + debug!("derived bech32m address for bitcoin_network: {} : {}", p2mr_utxo_return.bitcoin_network, bech32m_address); + + if p2mr_utxo_return.bitcoin_network == Network::Bitcoin { + assert_eq!(bech32m_address, *test_vector.expected.bip350_address.as_ref().unwrap(), "Bech32m address mismatch."); + } + + Ok(()) +} diff --git a/bip-0360/ref-impl/rust/tests/p2mr_pqc_construction.rs b/bip-0360/ref-impl/rust/tests/p2mr_pqc_construction.rs new file mode 100644 index 0000000000..a5ca855cad --- /dev/null +++ b/bip-0360/ref-impl/rust/tests/p2mr_pqc_construction.rs @@ -0,0 +1,240 @@ +use std::collections::HashSet; +use bitcoin::{Network, ScriptBuf}; +use bitcoin::taproot::{LeafVersion, TapTree, ScriptLeaves, TapLeafHash, TaprootMerkleBranch, TapNodeHash}; +use bitcoin::p2mr::{P2mrBuilder, P2mrControlBlock, P2mrSpendInfo}; +use bitcoin::hashes::Hash; + +use hex; +use log::debug; +use once_cell::sync::Lazy; + +use p2mr_ref::data_structures::{TVScriptTree, TestVector, Direction, TestVectors, UtxoReturn}; +use p2mr_ref::error::P2MRError; +use p2mr_ref::{create_p2mr_utxo, tagged_hash}; + +// This file contains tests that execute against the BIP360 script-path-only test vectors. + +static TEST_VECTORS: Lazy = Lazy::new(|| { + let bip360_test_vectors = include_str!("../../common/tests/data/p2mr_pqc_construction.json"); + let test_vectors: TestVectors = serde_json::from_str(bip360_test_vectors).unwrap(); + assert_eq!(test_vectors.version, 1); + test_vectors +}); + +static P2MR_MISSING_LEAF_SCRIPT_TREE_ERROR_TEST: &str = "p2mr_missing_leaf_script_tree_error"; +static P2MR_SINGLE_LEAF_SCRIPT_TREE_TEST: &str = "p2mr_single_leaf_script_tree"; +static P2MR_DIFFERENT_VERSION_LEAVES_TEST: &str = "p2mr_different_version_leaves"; +static P2MR_TWO_LEAF_SAME_VERSION_TEST: &str = "p2mr_two_leaf_same_version"; +static P2MR_THREE_LEAF_COMPLEX_TEST: &str = "p2mr_three_leaf_complex"; +static P2MR_THREE_LEAF_ALTERNATIVE_TEST: &str = "p2mr_three_leaf_alternative"; +static P2MR_SIMPLE_LIGHTNING_CONTRACT_TEST: &str = "p2mr_simple_lightning_contract"; + +// https://learnmeabitcoin.com/technical/upgrades/taproot/#example-2-script-path-spend-simple +#[test] +fn test_p2mr_pqc_missing_leaf_script_tree_error() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_MISSING_LEAF_SCRIPT_TREE_ERROR_TEST).unwrap(); + let test_result: anyhow::Result<()> = process_test_vector_p2mr(test_vector); + assert!(matches!(test_result.unwrap_err().downcast_ref::(), + Some(P2MRError::MissingScriptTreeLeaf))); +} + +// https://learnmeabitcoin.com/technical/upgrades/taproot/#example-2-script-path-spend-simple +#[test] +fn test_p2mr_pqc_single_leaf_script_tree() { + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_SINGLE_LEAF_SCRIPT_TREE_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_pqc_different_version_leaves() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_DIFFERENT_VERSION_LEAVES_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_pqc_simple_lightning_contract() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_SIMPLE_LIGHTNING_CONTRACT_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_pqc_two_leaf_same_version() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_TWO_LEAF_SAME_VERSION_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_pqc_three_leaf_complex() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_THREE_LEAF_COMPLEX_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +#[test] +fn test_p2mr_pqc_three_leaf_alternative() { + + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let test_vectors = &*TEST_VECTORS; + let test_vector = test_vectors.test_vector_map.get(P2MR_THREE_LEAF_ALTERNATIVE_TEST).unwrap(); + process_test_vector_p2mr(test_vector).unwrap(); +} + +fn process_test_vector_p2mr(test_vector: &TestVector) -> anyhow::Result<()> { + + let tv_script_tree: Option<&TVScriptTree> = test_vector.given.script_tree.as_ref(); + + let mut tv_leaf_count: u8 = 0; + let mut current_branch_id: u8 = 0; + + // TaprootBuilder expects the addition of each leaf script with its associated depth + // It then constructs the binary tree in DFS order, sorting siblings lexicographically & combining them via BIP341's tapbranch_hash + // Use of TaprootBuilder avoids user error in constructing branches manually and ensures Merkle tree correctness and determinism + let mut p2mr_builder: P2mrBuilder = P2mrBuilder::new(); + + let mut control_block_data: Vec<(ScriptBuf, LeafVersion)> = Vec::new(); + + // 1) traverse test vector script tree and add leaves to P2MR builder + if let Some(script_tree) = tv_script_tree { + + script_tree.traverse_with_right_subtree_first(0, Direction::Root,&mut |node, depth, direction| { + + if let TVScriptTree::Leaf(tv_leaf) = node { + + let tv_leaf_script_bytes = hex::decode(&tv_leaf.script).unwrap(); + + // NOTE: IOT to execute script_info.control_block(..), will add these to a vector + let tv_leaf_script_buf = ScriptBuf::from_bytes(tv_leaf_script_bytes.clone()); + let tv_leaf_version = LeafVersion::from_consensus(tv_leaf.leaf_version).unwrap(); + control_block_data.push((tv_leaf_script_buf.clone(), tv_leaf_version)); + + let mut modified_depth = depth + 1; + if direction == Direction::Root { + modified_depth = depth; + } + debug!("traverse_with_depth: leaf_count: {}, depth: {}, modified_depth: {}, direction: {}, tv_leaf_script: {}", + tv_leaf_count, depth, modified_depth, direction, tv_leaf.script); + + // NOTE: Some of the the test vectors in this project specify leaves with non-standard versions (ie: 250 / 0xfa) + p2mr_builder = p2mr_builder.clone().add_leaf_with_ver(depth, tv_leaf_script_buf.clone(), tv_leaf_version) + .unwrap_or_else(|e| { + panic!("Failed to add leaf: {:?}", e); + }); + + tv_leaf_count += 1; + } else if let TVScriptTree::Branch { left, right } = node { + // No need to calculate branch hash. + // TaprootBuilder does this for us. + debug!("branch_count: {}, depth: {}, direction: {}", current_branch_id, depth, direction); + current_branch_id += 1; + } + }); + }else { + return Err(P2MRError::MissingScriptTreeLeaf.into()); + } + + let spend_info: P2mrSpendInfo = p2mr_builder.clone() + .finalize() + .unwrap_or_else(|e| { + panic!("finalize failed: {:?}", e); + }); + + let derived_merkle_root: TapNodeHash = spend_info.merkle_root.unwrap(); + + // 2) verify derived merkle root against test vector + let test_vector_merkle_root = test_vector.intermediary.merkle_root.as_ref().unwrap(); + assert_eq!( + derived_merkle_root.to_string(), + *test_vector_merkle_root, + "Merkle root mismatch" + ); + debug!("just passed merkle root validation: {}", test_vector_merkle_root); + + let test_vector_leaf_hashes_vec: Vec = test_vector.intermediary.leaf_hashes.clone(); + let test_vector_leaf_hash_set: HashSet = test_vector_leaf_hashes_vec.iter().cloned().collect(); + let test_vector_control_blocks_vec = &test_vector.expected.script_path_control_blocks; + let test_vector_control_blocks_set: HashSet = test_vector_control_blocks_vec.as_ref().unwrap().iter().cloned().collect(); + let tap_tree: TapTree = p2mr_builder.clone().into_inner().try_into_taptree().unwrap(); + let script_leaves: ScriptLeaves = tap_tree.script_leaves(); + + // TO-DO: Investigate why the ordering of script leaves seems to be reverse of test vectors. + // 3) Iterate through leaves of derived script tree and verify both script leaf hashes and control blocks + for derived_leaf in script_leaves { + + let version = derived_leaf.version(); + let script = derived_leaf.script(); + let merkle_branch: &TaprootMerkleBranch = derived_leaf.merkle_branch(); + + let derived_leaf_hash: TapLeafHash = TapLeafHash::from_script(script, version); + let leaf_hash = hex::encode(derived_leaf_hash.as_raw_hash().to_byte_array()); + assert!( + test_vector_leaf_hash_set.contains(&leaf_hash), + "Leaf hash not found in expected set for {}", leaf_hash + ); + debug!("just passed leaf_hash validation: {}", leaf_hash); + + // Each leaf in the script tree has a corresponding control block. + // Specific to P2TR, the 3 sections of the control block (control byte, public key & merkle path) are highlighted here: + // https://learnmeabitcoin.com/technical/upgrades/taproot/#script-path-spend-control-block + // The control block, which includes the Merkle path, must be 33 + 32 * n bytes, where n is the number of Merkle path hashes (n ≥ 0). + // There is no consensus limit on n, but large Merkle trees increase the witness size, impacting block weight. + // NOTE: Control blocks could have also been obtained from spend_info.control_block(..) using the data in control_block_data + debug!("merkle_branch nodes: {:?}", merkle_branch); + let derived_control_block: P2mrControlBlock = P2mrControlBlock{ + merkle_branch: merkle_branch.clone(), + }; + let serialized_control_block = derived_control_block.serialize(); + debug!("derived_control_block: {:?}, merkle_branch size: {}, control_block size: {}, serialized size: {}", + derived_control_block, + merkle_branch.len(), + derived_control_block.size(), + serialized_control_block.len()); + let derived_serialized_control_block = hex::encode(serialized_control_block); + assert!( + test_vector_control_blocks_set.contains(&derived_serialized_control_block), + "Control block mismatch: {}, expected: {:?}", derived_serialized_control_block, test_vector_control_blocks_set + ); + debug!("leaf_hash: {}, derived_serialized_control_block: {}", leaf_hash, derived_serialized_control_block); + + } + + let p2mr_utxo_return: UtxoReturn = create_p2mr_utxo(derived_merkle_root.to_string()); + + assert_eq!( + p2mr_utxo_return.script_pubkey_hex, + *test_vector.expected.script_pubkey.as_ref().unwrap(), + "Script pubkey mismatch" + ); + debug!("just passed script_pubkey validation. script_pubkey = {}", p2mr_utxo_return.script_pubkey_hex); + + let bech32m_address: String = p2mr_utxo_return.bech32m_address; + debug!("derived bech32m address for bitcoin_network: {} : {}", p2mr_utxo_return.bitcoin_network, bech32m_address); + + if p2mr_utxo_return.bitcoin_network == Network::Bitcoin { + assert_eq!(bech32m_address, *test_vector.expected.bip350_address.as_ref().unwrap(), "Bech32m address mismatch."); + } + + Ok(()) +} diff --git a/bip-0360/ref-impl/rust/tests/p2mr_spend.rs b/bip-0360/ref-impl/rust/tests/p2mr_spend.rs new file mode 100644 index 0000000000..c06063bb50 --- /dev/null +++ b/bip-0360/ref-impl/rust/tests/p2mr_spend.rs @@ -0,0 +1,102 @@ +use log::info; +use bitcoin::blockdata::witness::Witness; + +use p2mr_ref::{ pay_to_p2wpkh_tx, serialize_script }; + +use p2mr_ref::data_structures::{SpendDetails, LeafScriptType}; + +/* The rust-bitcoin crate does not provide a single high-level API that builds the full Taproot script-path witness stack for you. + It does expose all the necessary types and primitives to build it manually and correctly. +*/ + +// https://learnmeabitcoin.com/technical/upgrades/taproot/#example-2-script-path-spend-simple +#[test] +fn test_script_path_spend_simple() { + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let script_inputs_count = hex::decode("03").unwrap(); + let script_inputs_bytes: Vec = hex::decode("08").unwrap(); + let leaf_script_bytes: Vec = hex::decode("5887").unwrap(); + let control_block_bytes: Vec = + hex::decode("c1924c163b385af7093440184af6fd6244936d1288cbb41cc3812286d3f83a3329").unwrap(); + let test_witness_bytes: Vec = hex::decode( + "03010802588721c1924c163b385af7093440184af6fd6244936d1288cbb41cc3812286d3f83a3329", + ) + .unwrap(); + + let mut derived_witness: Witness = Witness::new(); + derived_witness.push(script_inputs_count); + derived_witness.push(serialize_script(&script_inputs_bytes)); + derived_witness.push(serialize_script(&leaf_script_bytes)); + derived_witness.push(serialize_script(&control_block_bytes)); + + info!("witness: {:?}", derived_witness); + + let derived_witness_vec: Vec = derived_witness.iter().flatten().cloned().collect(); + + assert_eq!(derived_witness_vec, test_witness_bytes); +} + + +// Inspired by: https://learnmeabitcoin.com/technical/upgrades/taproot/#example-3-script-path-spend-signature +// Spends from a p2mr UTXO to a p2wpk UTXO +#[test] +fn test_script_path_spend_signatures() { + let _ = env_logger::try_init(); // Use try_init to avoid reinitialization error + + let funding_tx_id_bytes: Vec = + hex::decode("d1c40446c65456a9b11a9dddede31ee34b8d3df83788d98f690225d2958bfe3c").unwrap(); + + // The input index of the funding tx + let funding_tx_index: u32 = 0; + + let funding_utxo_amount_sats: u64 = 20000; + + // OP_PUSHBYTES_32 6d4ddc0e47d2e8f82cbe2fc2d0d749e7bd3338112cecdc76d8f831ae6620dbe0 OP_CHECKSIG + let input_leaf_script_bytes: Vec = + hex::decode("206d4ddc0e47d2e8f82cbe2fc2d0d749e7bd3338112cecdc76d8f831ae6620dbe0ac").unwrap(); + + // Modified from learnmeabitcoin example + // Changed from c0 to c1 control byte to reflect p2mr specification: The parity bit of the control byte is always 1 since P2MR does not have a key-spend path. + let input_control_block_bytes: Vec = + hex::decode("c1924c163b385af7093440184af6fd6244936d1288cbb41cc3812286d3f83a3329").unwrap(); + + let input_script_pubkey_bytes: Vec = + hex::decode("5120f3778defe5173a9bf7169575116224f961c03c725c0e98b8da8f15df29194b80") + .unwrap(); + let input_script_priv_key_bytes: Vec = hex::decode("9b8de5d7f20a8ebb026a82babac3aa47a008debbfde5348962b2c46520bd5189").unwrap(); + + // Convert to Vec> format expected by the function + let input_script_priv_keys_bytes: Vec> = vec![input_script_priv_key_bytes]; + + + // https://learnmeabitcoin.com/explorer/tx/797505b104b5fb840931c115ea35d445eb1f64c9279bf23aa5bb4c3d779da0c2#outputs + let spend_output_pubkey_bytes: Vec = hex::decode("0de745dc58d8e62e6f47bde30cd5804a82016f9e").unwrap(); + + let spend_output_amount_sats: u64 = 15000; + + let test_sighash_bytes: Vec = hex::decode("752453d473e511a0da2097d664d69fe5eb89d8d9d00eab924b42fc0801a980c9").unwrap(); + let test_signature_bytes: Vec = hex::decode("01769105cbcbdcaaee5e58cd201ba3152477fda31410df8b91b4aee2c4864c7700615efb425e002f146a39ca0a4f2924566762d9213bd33f825fad83977fba7f").unwrap(); + + // Modified from learnmeabitcoin example + // Changed from c0 to c1 control byte to reflect p2mr specification: The parity bit of the control byte is always 1 since P2MR does not have a key-spend path. + let test_witness_bytes: Vec = hex::decode("01769105cbcbdcaaee5e58cd201ba3152477fda31410df8b91b4aee2c4864c7700615efb425e002f146a39ca0a4f2924566762d9213bd33f825fad83977fba7f01206d4ddc0e47d2e8f82cbe2fc2d0d749e7bd3338112cecdc76d8f831ae6620dbe0acc1924c163b385af7093440184af6fd6244936d1288cbb41cc3812286d3f83a3329").unwrap(); + + let result: SpendDetails = pay_to_p2wpkh_tx(funding_tx_id_bytes, + funding_tx_index, + funding_utxo_amount_sats, + input_script_pubkey_bytes, + input_control_block_bytes, + input_leaf_script_bytes, + input_script_priv_keys_bytes, // Now passing Vec> format + spend_output_pubkey_bytes, + spend_output_amount_sats, + LeafScriptType::SchnorrOnly // This test uses a Schnorr signature + ); + + assert_eq!(result.sighash.as_slice(), test_sighash_bytes.as_slice(), "sighash mismatch"); + assert_eq!(result.sig_bytes, test_signature_bytes, "signature mismatch"); + assert_eq!(result.derived_witness_vec, test_witness_bytes, "derived_witness mismatch"); + +} +