diff options
| -rw-r--r-- | .github/workflows/github-action-checks.yml | 9 | ||||
| -rw-r--r-- | .typos.toml | 44 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 12 | ||||
| -rw-r--r-- | README.mediawiki | 7 | ||||
| -rw-r--r-- | bip-0046.mediawiki | 2 | ||||
| -rw-r--r-- | bip-0075.mediawiki | 2 | ||||
| -rw-r--r-- | bip-0094.mediawiki | 120 | ||||
| -rw-r--r-- | bip-0119.mediawiki | 4 | ||||
| -rw-r--r-- | bip-0152.mediawiki | 2 | ||||
| -rw-r--r-- | bip-0352.mediawiki | 2 | ||||
| -rw-r--r-- | bip-0386.mediawiki | 2 | ||||
| -rw-r--r-- | bip-0388.mediawiki | 25 |
12 files changed, 219 insertions, 12 deletions
diff --git a/.github/workflows/github-action-checks.yml b/.github/workflows/github-action-checks.yml index 8a7d2ac..ad76317 100644 --- a/.github/workflows/github-action-checks.yml +++ b/.github/workflows/github-action-checks.yml @@ -20,3 +20,12 @@ jobs: with: fetch-depth: 2 - run: scripts/diffcheck.sh + Typo-Checks: + name: "Typo Checks" + runs-on: ubuntu-latest + steps: + - name: Checkout Actions Repository + uses: actions/checkout@v4 + + - name: Check spelling + uses: crate-ci/typos@master diff --git a/.typos.toml b/.typos.toml new file mode 100644 index 0000000..15d831f --- /dev/null +++ b/.typos.toml @@ -0,0 +1,44 @@ +[default] +extend-ignore-re = [ + # NOTE: use here for regex patterns + "xpub.*", + "xprv.*", + "3.*", # address + "5.*", # address + "private_key .*", + "privkey .*", + "tt.*", # <tt> tags + "code.*", # <code> tags + "\\w*<sub>", # prefix for <sub> tags + "OP_SUCCESSx|\\d+", + "pay.*", + "ser.*", + "prefix.*", + "value: .*", +] + +[default.extend-words] +# NOTE: use here for false-positives +anc = "anc" +PSBT = "PSBT" +ser = "ser" +# Names +Atack = "Atack" +Meni = "Meni" +Ono = "Ono" + +[files] +extend-exclude = [ + "/*/*.csv", + "/*.d*", + "/*/*.d*", + "/*/*.go", + "/*/*.json", + "/*/*/*.json", + "/*/*.mod", + "/*/*.proto", + "/*/*.py", + "scripts", + "/*/*.s*", + "/*/*.t*", +] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..df6d947 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,12 @@ +# Contributing Guidelines + +Apart from following [BIP 2](./bip-0002.mediawiki), +we do CI checks to ensure that the proposed BIPs do not have common typos. +These checks are done using [`typos`](https://github.com/crate-ci/typos). +To check for typos locally, +install [`typos`](https://github.com/crate-ci/typos) +and then run in the root directory: + +```bash +typos +``` diff --git a/README.mediawiki b/README.mediawiki index 7adaf72..170b053 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -498,6 +498,13 @@ Those proposing changes should consider that ultimately consent may rest with th | Informational | Draft |- +| [[bip-0094.mediawiki|94]] +| Applications +| Testnet 4 +| Fabian Jahr +| Standard +| Draft +|- | [[bip-0098.mediawiki|98]] | Consensus (soft fork) | Fast Merkle Trees diff --git a/bip-0046.mediawiki b/bip-0046.mediawiki index 1602f81..2bc4039 100644 --- a/bip-0046.mediawiki +++ b/bip-0046.mediawiki @@ -107,7 +107,7 @@ A certificate message can be created by another application external to this sta Almost all wallets implementing this standard can use their already-existing "Sign Message" function to sign the certificate message. As the certificate message itself is always an ASCII string, the wallet may not need to specially implement this section at all but just rely on users copypasting their certificate message into the already-existing "Sign Message" user interface. This works as long as the wallet knows how to use the private key of the timelocked address for signing messages. -It is most important for wallet implementions of this standard to support creating the certificate signature. Verifying the certificate signature is less important. +It is most important for wallet implementations of this standard to support creating the certificate signature. Verifying the certificate signature is less important. == Test vectors == diff --git a/bip-0075.mediawiki b/bip-0075.mediawiki index ebd5b37..5057206 100644 --- a/bip-0075.mediawiki +++ b/bip-0075.mediawiki @@ -219,7 +219,7 @@ message EncryptedProtocolMessage { ==Payment Protocol Process with InvoiceRequests== The full process overview for using '''InvoiceRequests''' in the Payment Protocol is defined below. <br/><br/> -All Payment Protocol messages MUST be encapsulated in either a [[#ProtocolMessage|ProtocolMessage]] or [[#EncryptedProcotolMessage|EncryptedProtocolMessage]]. Once the process begins using [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] messages, all subsequent communications MUST use [[#EncryptedProtocolMessage|EncryptedProtocolMessages]]. +All Payment Protocol messages MUST be encapsulated in either a [[#ProtocolMessage|ProtocolMessage]] or [[#EncryptedProtocolMessage|EncryptedProtocolMessage]]. Once the process begins using [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] messages, all subsequent communications MUST use [[#EncryptedProtocolMessage|EncryptedProtocolMessages]]. <br/><br/> All Payment Protocol messages SHOULD be communicated using [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] encapsulating messages with the exception that an [[#InvoiceRequest|InvoiceRequest]] MAY be communicated using the [[#ProtocolMessage|ProtocolMessage]] if the receiver's public key is unknown. <br/><br/> diff --git a/bip-0094.mediawiki b/bip-0094.mediawiki new file mode 100644 index 0000000..d7e436d --- /dev/null +++ b/bip-0094.mediawiki @@ -0,0 +1,120 @@ +<pre> + BIP: 94 + Layer: Applications + Title: Testnet 4 + Author: Fabian Jahr <fjahr@protonmail.com> + Comments-Summary: No comments yet. + Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0094 + Status: Draft + Type: Standards Track + Created: 2024-05-27 + License: CC0-1.0 + Post-History: https://gnusha.org/pi/bitcoindev/CADL_X_eXjbRFROuJU0b336vPVy5Q2RJvhcx64NSNPH-3fDCUfw@mail.gmail.com/ + https://gnusha.org/pi/bitcoindev/a6e3VPsXJf9p3gt_FmNF_Up-wrFuNMKTN30-xCSDHBKXzXnSpVflIZIj2NQ8Wos4PhQCzI2mWEMvIms_FAEs7rQdL15MpC_Phmu_fnR9iTg=@protonmail.com/ + https://github.com/bitcoin/bitcoin/pull/29775 +</pre> + +== Abstract == + +A new test network with the goal to replace Testnet 3. This network comes with small but important improvements of the consensus rules, that should make it impractical to attack the network using only CPU mining. + +== Motivation == + +Quoting the original mailing list post from Jameson Lopp<ref>https://gnusha.org/pi/bitcoindev/CADL_X_eXjbRFROuJU0b336vPVy5Q2RJvhcx64NSNPH-3fDCUfw@mail.gmail.com/</ref>: + +<blockquote><poem> +Testnet3 has been running for 13 years. It's on block 2.5 million something and the block reward is down to ~0.014 TBTC, so mining is not doing a great job at distributing testnet coins anymore. + +The reason the block height is insanely high is due to a rather amusing edge case bug that causes the difficulty to regularly get reset to 1, which causes a bit of havoc. If you want a deep dive into the quirk: https://blog.lopp.net/the-block-storms-of-bitcoins-testnet/ + +Testnet3 is being actively used for scammy airdrops; those of us who tend to be generous with our testnet coins are getting hounded by non-developers chasing cheap gains. + +As a result, TBTC is being actively bought and sold; one could argue that the fundamental principle of testnet coins having no value has been broken. +</poem></blockquote> + +Since then the issue with block storms has been further demonstrated on Testnet 3 when three years' worth of blocks were mined in a few weeks while rendering the network practically unusable at the same time. + +== Specification == + +Consensus of Testnet 4 follows the same rules as mainnet with the exception of the three rules detailed below. Additionally all soft forks that are active on mainnet as of May 2024 are enforced from genesis. + +=== 20-minute Exception === + +This rule was already previously implemented and active in Testnet 3<ref>https://github.com/bitcoin/bitcoin/pull/686</ref>. + +A block with a timestamp that is more than 20 minutes past the timestamp of the previous block must have a minimum difficulty of 1 (the network's minimum difficulty) instead of whatever the actual difficulty level currently is. This applies to all blocks in a difficulty period except for the first block. This means the blocks must change their <code>nBits</code> field from the actual difficulty level to the minimum difficulty value <code>0x1d00ffff</code>. + +This rule also led to the block storms<ref>https://blog.lopp.net/the-block-storms-of-bitcoins-testnet/</ref> which the following rule seeks to fix. + +=== Block Storm Fix === + +The work required for a new difficulty period is calculated as multiplication factor to the difficulty of the previous period (but no less than 1/4th and no more than 4x), depending on the duration of the previous difficulty period. On Mainnet and Testnet 3, this factor is applied to the difficulty value of the last block. + +Block storms happen organically whenever the 20-minute exception is applied to a difficulty period’s last block, causing the block to be mined at a difficulty of 1. The difficulty adjustment rules then limit the subsequent period’s difficulty to a value between 1 (the minimum) and 4. Blocks will be generated rapidly in the subsequent low-difficulty periods while the difficulty climbs back to an adequate range. An arbitrarily large number of blocks can be generated quickly by repeatedly using the 20-minute exception on every last block of difficulty periods. The block storm is then bounded only by miner hash rate, the need for last blocks to have a timestamp 20 minutes after the second to last block, the Median-Time-Past nTime rule, and the requirement that blocks can't be more than 2 hours in the future. Overall a sustained attack would eventually be limited to a maximum cadence of six blocks per second. + +A block storm does not require a time warp attack, but one can be used to amplify<ref>A perpetual block storm attack with entire difficulty periods being authored in less than 3.5 days that resets the difficulty to the minimum in the last block of every difficulty period would adjust to a new actual difficulty of 4 every period. An attacker that additionally leverages a time warp attack would start their attack by holding back timestamps until the latest block’s timestamp is at least two weeks in the past, and then limiting their block rate to six blocks per second, incrementing the timestamp on every sixth block. Only on the last block they would use the current time, which both resets the difficulty to one per the 20-minute exception and would result in a difficulty adjustment keeping the difficulty at the minimum due to the elapsed time exceeding the target. This would allow lower the difficulty for all blocks to difficulty 1 instead of difficulty 4</ref> it. + +The mitigation consists of no longer applying the adjustment factor to the last block of the previous difficulty period. Instead, the first block of the difficulty period is used as the base. + +The first block must contain the actual difficulty of the network and can therefore be used as the base for the calculation of the new difficulty level. Note that the first block in new difficulty period does not allow usage of the 20-minute exception (this is prior behavior). This means that in each difficulty period the first block should always have the actual difficulty even if all other blocks were mined with the 20-minute exception. + +=== Time Warp Fix === + +In addition to a time warp attack potentially exacerbating the perpetual block storm attack, a time warp attack provides an alternative way to increase the block production rate even if the unintended reset of the actual difficulty due to the 20-minute exception was mitigated. + +To protect against the time warp attack, the following rule proposed as part of The Great Consensus Cleanup<ref>https://github.com/TheBlueMatt/bips/blob/cleanup-softfork/bip-XXXX.mediawiki</ref> is enforced: "The nTime field of each block whose height, mod 2016, is 0 must be greater than or equal to the nTime field of the immediately prior block minus 600. For the avoidance of doubt, such blocks must still comply with existing Median-Time-Past nTime restrictions." + +== Rationale == + +The applied changes were the result of discussions on the mailing list and the PR. The selected changes try to strike a balance between minimal changes to the network (keeping it as close to mainnet as possible) while making it more robust against attackers that try to disrupt the network. Several alternative designs were considered: + +* For the block storm fix an alternative fix could have been to prevent the last block in a difficulty period from applying the existing difficulty exception. Both solutions were deemed acceptable and there was no clear preference among reviewers. +* Removal of the 20-minute exception was discussed but dismissed since several reviewers insisted that it was a useful feature allowing non-standard transactions to be mined with just a CPU. The 20-minute exception also allows CPU users to move the chain forward (except on the first block that needs to be mined at actual difficulty) in case a large amount of hash power suddenly leaves the network. This would allow the chain to recover to a normal difficulty level faster if left stranded at high difficulty. +* Increase of minimum difficulty was discussed but dismissed as it would categorically prevent participation in the network using a CPU miner (utilizing the 20-minute exception). +* Increase of the delay in the 20-minute exception was suggested but did not receive significant support. +* Re-enabling <code>acceptnonstdtxn</code> in bitcoin core by default was dismissed as it had led to confusion among layer-2s that had used testnet for transaction propagation tests and expected it to behave similar to mainnet. +* Motivating miners to re-org min difficulty blocks was suggested, but was considered out of scope for this BIP, since adoption of such a mining policy remains available after Testnet 4 is deployed. As 20-minute exception blocks only contribute work corresponding to difficulty one to the chaintip, and actual difficulty blocks should have a difficulty magnitudes higher, a block mined at actual difficulty could easily replace even multiple 20-minute exception blocks. +* Persisting the real difficulty in the version field was suggested to robustly prevent exploits of the 20-minute exception while allowing it to be used on any block, but did not receive a sufficient level of support to justify the more invasive change. + +One known downside of the chosen approach is that if the difficulty is gradually raised by a miner with significant hash rate, and this miner disappears, then each difficulty adjustment period requires one block at the actual difficulty. + +This would cause the network to stall once per difficulty adjustment period until the real difficulty is adjusted downwards enough for the remaining hash rate to find this block in reasonable time. + +== Network Parameters == + +=== Consensus Rules === + +All consensus rules active on mainnet at the time of this proposal are enforced from block 1, the newest of these rules being the Taproot softfork. + +=== Genesis Block === + +* Message: <code>03/May/2024 000000000000000000001ebd58c244970b3aa9d783bb001011fbe8ea8e98e00e</code> +* Pubkey: <code>000000000000000000000000000000000000000000000000000000000000000000</code> +* Time stamp: 1714777860 +* Nonce: 393743547 +* Difficulty: <code>0x1d00ffff</code> +* Version: 1 + +The resulting genesis block hash is <code>00000000da84f2bafbbc53dee25a72ae507ff4914b867c565be350b0da8bf043</code>, and the block hex is <code>0100000000000000000000000000000000000000000000000000000000000000000000004e7b2b9128fe0291db0693af2ae418b767e657cd407e80cb1434221eaea7a07a046f3566ffff001dbb0c78170101000000010000000000000000000000000000000000000000000000000000000000000000ffffffff5504ffff001d01044c4c30332f4d61792f323032342030303030303030303030303030303030303030303165626435386332343439373062336161396437383362623030313031316662653865613865393865303065ffffffff0100f2052a010000002321000000000000000000000000000000000000000000000000000000000000000000ac00000000</code>. + +=== Message Start === + +The message start is defined as <code>0x1c163f28</code>. These four bytes were randomly generated and have no special meaning. + +== Backwards Compatibility == + +The rules used by Testnet 4 are backwards compatible to the rules of Testnet 3. Existing software that implements support for Testnet 3 would only require addition of the network parameters (magic number, genesis block, etc.) to be able to follow Testnet 4. + +However, implementations that only implement Testnet 3’s rules would accept a chain that violates Testnet 4’s rules and are therefore susceptible to being forked off. It is recommended that any implementations check blocks in regard to all the new rules of Testnet 4 and reject blocks that fail to comply. + +== Reference implementation == + +Pull request at https://github.com/bitcoin/bitcoin/pull/29775 + +== References == + +<references/> + +== Copyright == + +This document is licensed under the Creative Commons CC0 1.0 Universal license. diff --git a/bip-0119.mediawiki b/bip-0119.mediawiki index be1f70c..6ca0adb 100644 --- a/bip-0119.mediawiki +++ b/bip-0119.mediawiki @@ -392,7 +392,7 @@ transaction preimages. =====Using Non-Tagged Hashes===== The Taproot/Schnorr BIPs use Tagged Hashes -(`SHA256(SHA256(tag)||SHA256(tag)||msg)`) to prevent taproot leafs, branches, +(`SHA256(SHA256(tag)||SHA256(tag)||msg)`) to prevent taproot leaves, branches, tweaks, and signatures from overlapping in a way that might introduce a security [vulnerability https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-June/016091.html]. @@ -494,7 +494,7 @@ The preimage argument passed to CHECKTEMPLATEVERIFY may be unknown or otherwise However, requiring knowledge that an address is spendable from is incompatible with sender's ability to spend to any address (especially, OP_RETURN). If a sender needs to know the template can be spent from before sending, they may request a signature of an provably non-transaction challenge string -from the leafs of the CHECKTEMPLATEVERIFY tree. +from the leaves of the CHECKTEMPLATEVERIFY tree. ====Forwarding Addresses==== diff --git a/bip-0152.mediawiki b/bip-0152.mediawiki index fad1746..eb7d545 100644 --- a/bip-0152.mediawiki +++ b/bip-0152.mediawiki @@ -209,7 +209,7 @@ There are several design goals for the Short ID calculation: * '''Space''' cmpctblock messages are never optional in this protocol, and contain a short ID for each non-prefilled transaction in the block. Thus, the size of short IDs is directly proportional to the maximum bandwidth savings possible. * '''Collision resistance''' It should be hard for network participants to create transactions that cause collisions. If an attacker were able to cause such collisions, filling mempools (and, thus, blocks) with them would cause poor network propagation of new (or non-attacker, in the case of a miner) blocks. -SipHash is a secure, fast, and simple 64-bit MAC designed for network traffic authentication and collision-resistant hash tables. We truncate the output from SipHash-2-4 to 48 bits (see next section) in order to minimize space. The resulting 48-bit hash is certainly not large enough to avoid intentionally created individual collisons, but by using the block hash as a key to SipHash, an attacker cannot predict what keys will be used once their transactions are actually included in a relayed block. We mix in a per-connection 64-bit nonce to obtain independent short IDs on every connection, so that even block creators cannot control where collisions occur, and random collisions only ever affect a small number of connections at any given time. The mixing is done using SHA256(block_header || nonce), which is slow compared to SipHash, but only done once per block. It also adds the ability for nodes to choose the nonce in a better than random way to minimize collisions, though that is not necessary for correct behaviour. Conversely, nodes can also abuse this ability to increase their ability to introduce collisions in the blocks they relay themselves. However, they can already cause more problems by simply refusing to relay blocks. That is inevitable, and this design only seeks to prevent network-wide misbehavior. +SipHash is a secure, fast, and simple 64-bit MAC designed for network traffic authentication and collision-resistant hash tables. We truncate the output from SipHash-2-4 to 48 bits (see next section) in order to minimize space. The resulting 48-bit hash is certainly not large enough to avoid intentionally created individual collisions, but by using the block hash as a key to SipHash, an attacker cannot predict what keys will be used once their transactions are actually included in a relayed block. We mix in a per-connection 64-bit nonce to obtain independent short IDs on every connection, so that even block creators cannot control where collisions occur, and random collisions only ever affect a small number of connections at any given time. The mixing is done using SHA256(block_header || nonce), which is slow compared to SipHash, but only done once per block. It also adds the ability for nodes to choose the nonce in a better than random way to minimize collisions, though that is not necessary for correct behaviour. Conversely, nodes can also abuse this ability to increase their ability to introduce collisions in the blocks they relay themselves. However, they can already cause more problems by simply refusing to relay blocks. That is inevitable, and this design only seeks to prevent network-wide misbehavior. ====Random collision probability==== diff --git a/bip-0352.mediawiki b/bip-0352.mediawiki index 634e179..4462efc 100644 --- a/bip-0352.mediawiki +++ b/bip-0352.mediawiki @@ -99,7 +99,7 @@ In our simplified example we have been referring to Alice's transactions as havi Alice performs the tweak with the sum of her input private keys in the following manner: * Let ''a = a<sub>1</sub> + a<sub>2</sub> + ... + a<sub>n</sub>'' -* Let ''input_hash = hash(outpoint<sub>L</sub> || (a·G))'', where ''outpoint<sub>L</sub>'' is the smallest outpoint lexicographically<ref name="why_smallest_outpoint">'''Why use the lexicographically smallest outpoint for the hash?''' Recall that the purpose of including the input hash is so that the sender and receiver can both come up with a deterministic nonce that ensures that a unique address is generated each time, even when reusing the same scriptPubKey as an input. Choosing the smallest outpoint lexicographically satisifes this requirement, while also ensuring that the generated output is not dependent on the final ordering of inputs in the transaction. Using a single outpoint also works well with memory constrained devices (such as hardware signing devices) as it does not require the device to have the entire transaction in memory in order to generate the silent payment output.</ref> +* Let ''input_hash = hash(outpoint<sub>L</sub> || (a·G))'', where ''outpoint<sub>L</sub>'' is the smallest outpoint lexicographically<ref name="why_smallest_outpoint">'''Why use the lexicographically smallest outpoint for the hash?''' Recall that the purpose of including the input hash is so that the sender and receiver can both come up with a deterministic nonce that ensures that a unique address is generated each time, even when reusing the same scriptPubKey as an input. Choosing the smallest outpoint lexicographically satisfies this requirement, while also ensuring that the generated output is not dependent on the final ordering of inputs in the transaction. Using a single outpoint also works well with memory constrained devices (such as hardware signing devices) as it does not require the device to have the entire transaction in memory in order to generate the silent payment output.</ref> * Let ''P<sub>0</sub> = B + hash(input_hash·a·B || 0)·G'' ''' Spend and Scan Key ''' diff --git a/bip-0386.mediawiki b/bip-0386.mediawiki index 55f0d15..600d14e 100644 --- a/bip-0386.mediawiki +++ b/bip-0386.mediawiki @@ -101,7 +101,7 @@ Valid descriptors followed by the scripts they produce. Descriptors involving de Invalid Descriptors -* Uncompressed private key: <tt>tr(5kyzdueo39z3fprtux2qbbwgnnp5ztd7yyr2sc1j299sbcnwjss)</tt> +* Uncompressed private key: <tt>tr(5KYZdUEo39z3FPrtuX2QbbwGnNP5zTd7yyr2SC1j299sBCnWjss)</tt> * Uncompressed public key: <tt>tr(04a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd5b8dec5235a0fa8722476c7709c02559e3aa73aa03918ba2d492eea75abea235)</tt> * <tt>tr()</tt> nested in <tt>wsh</tt>: <tt>wsh(tr(a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd))</tt> * <tt>tr()</tt> nested in <tt>sh</tt>: <tt>sh(tr(a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd))</tt> diff --git a/bip-0388.mediawiki b/bip-0388.mediawiki index dc1b508..895e5a0 100644 --- a/bip-0388.mediawiki +++ b/bip-0388.mediawiki @@ -14,7 +14,10 @@ == Abstract == -Wallet policies build on top of output script descriptors to represent the types of descriptors that are typically used to represent "accounts" in a software wallet, or a hardware signing device, in a compact, reviewable way. A wallet policy always represents exactly two descriptors, which produce the receive and change addresses that are logically part of the same account. +Software wallets and hardware signing devices typically partition funds into separate "accounts". When signing or visualizing a transaction, aggregate flows of funds of all accounts affected by the transaction may (and should) be displayed to the user. + +Wallet policies build on top of output script descriptors to represent such accounts in a compact, reviewable way. +An account encompasses a logical group of receive and change addresses, and each wallet policy represents all descriptors necessary to describe an account in its entirety. We simplify the language to suit devices with limited memory, where even keeping the entire descriptor in memory could be a major hurdle, by reducing the generality of descriptors to just the essential features and by separating the extended pubkeys and other key information from the descriptor. @@ -40,9 +43,9 @@ Moreover, other limitations like the limited size of the screen might affect wha A more native, compact representation of the wallet receive and change addresses might also benefit the UX of software wallets when they use descriptors (possibly with miniscript) for representing complex locking conditions. -We remark that wallet policies are not related to the ''policy'' language, a higher level language that can be compiled to miniscript. +We remark that wallet policies are not related to the ''policy'' language, a higher level language that can be compiled to [[bip-0379.md|miniscript]]. -=== Security and UX concerns for hardware signing devices === +=== Security, privacy and UX concerns for hardware signing devices === The usage of complex scripts presents challenges in terms of both security and user experience for a hardware signing device. @@ -57,6 +60,18 @@ The hardware signing device must guarantee that the user knows precisely what "p This makes it impossible for an attacker to surreptitiously modify the policy, therefore stealing or burning the user's funds. +==== Avoiding key reuse ==== + +Reusing public keys within a script is a source of malleability when using miniscript policies, which has potential security implications. + +Reusing keys across different UTXOs harms user privacy by allowing external parties to link these UTXOs to the same entity once they are spent. + +By constraining the derivation path patterns to have a uniform structure, wallet policies prevent key reuse among the same or different UTXOs of the same account. + +It is strongly recommended to avoid key reuse across accounts. Distinct public keys per account can be guaranteed by using distinct hardened derivation paths. This specification does not mandate hardened derivation in order to maintain compatibility with existing deployments that do not adhere to this recommendation. + +It is out of scope for this document to guarantee that users do not reuse extended public keys among different wallet accounts. This is still very important, but the responsibility is left to the users and their software wallet. + ==== UX issues ==== Miniscript (and taproot trees) allow substantially more complex spending policies. It is a challenge to ensure that the user can practically verify such spending policies per the screen. @@ -125,6 +140,8 @@ A ''wallet descriptor template'' is a <tt>SCRIPT</tt> expression. * <tt>tr(KP)</tt> or <tt>tr(KP,TREE)</tt> (top level only): P2TR output with the specified key as internal key, and optionally a tree of script paths. * any valid miniscript template (inside <tt>wsh</tt> or <tt>tr</tt> only). +See [[bip-0379.md|BIP-379]] for a precise specification of all the valid miniscript <tt>SCRIPT</tt> expressions. + <tt>TREE</tt> expressions: * any <tt>SCRIPT</tt> expression * An open brace <tt>{</tt>, a <tt>TREE</tt> expression, a comma <tt>,</tt>, a <tt>TREE</tt> expression, and a closing brace <tt>}</tt> @@ -189,8 +206,6 @@ Implementations can add additional metadata that is stored together with the wal Any implementation in a software wallet that allows wallet policies not matching any of the specifications in [[bip-0044.mediawiki|BIP-44]], [[bip-0049.mediawiki|BIP-49]], [[bip-0084.mediawiki|BIP-84]], [[bip-0086.mediawiki|BIP-86]] (especially if involving external cosigners) should put great care into a process for backing up the wallet policy that represents the account. In fact, unlike standard single-signature scenarios, the seed alone is no longer enough to discover wallet policies with existing funds, and the loss of the backup is likely to lead to permanent loss of funds. Unlike the seed, leaking such backups only affects the privacy of the user, but it does not allow the attacker to steal funds. -Avoiding key reuse among different wallet accounts is also extremely important, but out of scope for this document. - === Optional derivation paths === In order to allow supporting legacy derivation schemes (for example, using simply <tt>/*</tt> instead of the more common <tt>/<M;N>/*</tt> scheme most software wallets use today), or other schemes that are not covered in this document, implementations might choose to permit additional derivation patterns for the key placeholder (<tt>KP</tt>) expressions. |