Date: Wed, 17 Apr 2024 18:25:00 -0400
Subject: [PATCH 03/20] BIP 387: multi_a() descriptor
---
README.mediawiki | 7 ++++
bip-0387.mediawiki | 101 +++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 108 insertions(+)
create mode 100644 bip-0387.mediawiki
diff --git a/README.mediawiki b/README.mediawiki
index 43e60a40..b6139442 100644
--- a/README.mediawiki
+++ b/README.mediawiki
@@ -1163,6 +1163,13 @@ Those proposing changes should consider that ultimately consent may rest with th
| Informational
| Draft
|-
+| [[bip-0387.mediawiki|387]]
+| Applications
+| Tapscript Multisig Output Script Descriptors
+| Pieter Wuille, Ava Chow
+| Informational
+| Draft
+|-
| [[bip-0389.mediawiki|389]]
| Applications
| Multipath Descriptor Key Expressions
diff --git a/bip-0387.mediawiki b/bip-0387.mediawiki
new file mode 100644
index 00000000..5c039b8f
--- /dev/null
+++ b/bip-0387.mediawiki
@@ -0,0 +1,101 @@
+
+ BIP: 387
+ Layer: Applications
+ Title: Tapscript Multisig Output Script Descriptors
+ Author: Pieter Wuille
+ Ava Chow
+ Comments-Summary: No comments yet.
+ Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0387
+ Status: Draft
+ Type: Informational
+ Created: 2024-04-17
+ License: BSD-2-Clause
+
+
+==Abstract==
+
+This document specifies multi_a() and sortedmulti_a() output script descriptors.
+Like BIP 383's multi() and sortedmulti(), both functions take a threshold and one
+or more public keys and produce a multisig script. The primary distinction is that multi_a()
+and sortedmulti_a() only produce tapscripts and are only allowed in a tapscript context.
+
+==Copyright==
+
+This BIP is licensed under the BSD 2-clause license.
+
+==Motivation==
+
+The most common complex script used in Bitcoin is a threshold multisig.
+These expressions allow specifying multisig scripts as a descriptor.
+
+==Specification==
+
+Two new script expressions are defined: multi_a() and sortedmulti_a().
+Both expressions produce the scripts of the same template and take the same arguments.
+They are written as multi_a(k,KEY_1,KEY_2,...,KEY_n).
+k is the threshold - the number of keys that must sign the input for the script to be valid.
+KEY_1,KEY_2,...,KEY_n are the key expressions for the multisig. k must be less than or equal to n.
+
+multi_a() and sortedmulti_a() expressions can only be used inside of a tr() descriptor.
+The maximum number of keys is 999.
+
+The output script produced also depends on the value of k. If k is less than or equal to 16:
+
+KEY_1 OP_CHECKSIG KEY_2 OP_CHECKSIGADD ... KEY_n OP_CHECKSIGADD OP_k OP_NUMEQUAL
+
+
+if k is greater than 16:
+
+KEY_1 OP_CHECKSIG KEY_2 OP_CHECKSIGADD ... KEY_n OP_CHECKSIGADD k OP_NUMEQUAL
+
+
+===sortedmulti_a()===
+
+The only change for sortedmulti_a() is that the x-only public keys are sorted lexicographically prior to the creation of the output script.
+This sorting is on the keys that are to be put into the output script, i.e. after all extended keys are derived.
+
+===Multiple Extended Keys===
+
+When one or more of the key expressions in a multi_a() or sortedmulti_a() expression are extended keys, the derived keys use the same child index.
+This changes the keys in lockstep and allows for output scripts to be indexed in the same way that the derived keys are indexed.
+
+==Test Vectors==
+
+Valid descriptors followed by the scripts they produce. Descriptors involving derived child keys will have the 0th, 1st, and 2nd scripts listed.
+
+* tr(L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1,multi_a(1,KzoAz5CanayRKex3fSLQ2BwJpN7U52gZvxMyk78nDMHuqrUxuSJy))
+** 5120eb5bd3894327d75093891cc3a62506df7d58ec137fcd104cdd285d67816074f3
+* tr(a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd,multi_a(1,669b8afcec803a0d323e9a17f3ea8e68e8abe5a278020a929adbec52421adbd0))
+** 5120eb5bd3894327d75093891cc3a62506df7d58ec137fcd104cdd285d67816074f3
+* tr(50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0,multi_a(2,[00000000/111'/222]xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc,xprv9uPDJpEQgRQfDcW7BkF7eTya6RPxXeJCqCJGHuCJ4GiRVLzkTXBAJMu2qaMWPrS7AANYqdq6vcBcBUdJCVVFceUvJFjaPdGZ2y9WACViL4L/0))
+** 51202eea93581594a43c0c8423b70dc112e5651df63984d108d4fc8ccd3b63b4eafa
+* tr(50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0,sortedmulti_a(2,[00000000/111'/222]xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc,xprv9uPDJpEQgRQfDcW7BkF7eTya6RPxXeJCqCJGHuCJ4GiRVLzkTXBAJMu2qaMWPrS7AANYqdq6vcBcBUdJCVVFceUvJFjaPdGZ2y9WACViL4L/0))
+** 512016fa6a6ba7e98c54b5bf43b3144912b78a61b60b02f6a74172b8dcb35b12bc30
+* tr(50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0,sortedmulti_a(2,xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/*,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0/0/*))
+** 5120abd47468515223f58a1a18edfde709a7a2aab2b696d59ecf8c34f0ba274ef772
+** 5120fe62e7ed20705bd1d3678e072bc999acb014f07795fa02cb8f25a7aa787e8cbd
+** 51201311093750f459039adaa2a5ed23b0f7a8ae2c2ffb07c5390ea37e2fb1050b41
+* tr(50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0,multi_a(2,xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U/2147483647'/0,xprv9vHkqa6EV4sPZHYqZznhT2NPtPCjKuDKGY38FBWLvgaDx45zo9WQRUT3dKYnjwih2yJD9mkrocEZXo1ex8G81dwSM1fwqWpWkeS3v86pgKt/1/2/*,xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi/10/20/30/40/*'))
+** 5120e4c8f2b0a7d3a688ac131cb03248c0d4b0a59bbd4f37211c848cfbd22a981192
+** 5120827faedaa21e52fca2ac83b53afd1ab7d4d1e6ce67ff42b19f2723d48b5a19ab
+** 5120647495ed09de61a3a324704f9203c130d655bf3141f9b748df8f7be7e9af55a4
+
+Invalid descriptors
+
+* Unsupported top level: multi_a(1,03669b8afcec803a0d323e9a17f3ea8e68e8abe5a278020a929adbec52421adbd0)
+* Unsupported sh() context: sh(multi_a(1,03669b8afcec803a0d323e9a17f3ea8e68e8abe5a278020a929adbec52421adbd0))
+* Unsupported wsh() context: wsh(multi_a(1,03669b8afcec803a0d323e9a17f3ea8e68e8abe5a278020a929adbec52421adbd0))
+* Invalid threshold: tr(50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0,multi_a(a,03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd))
+* Threshold of 0: tr(50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0,multi_a(0,03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd))
+* Uncompressed pubkey: tr(50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0,multi_a(1,04a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd5b8dec5235a0fa8722476c7709c02559e3aa73aa03918ba2d492eea75abea235))
+* Threshold larger than keys: tr(50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0,multi_a(3,L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1,5KYZdUEo39z3FPrtuX2QbbwGnNP5zTd7yyr2SC1j299sBCnWjss))
+
+==Backwards Compatibility==
+
+multi_a() and sortedmulti_a() descriptors use the format and general operation specified in [[bip-0380.mediawiki|380]].
+As these are wholly new descriptors, they are not compatible with any implementation.
+However, the scripts produced are standard scripts, so existing software are likely to be familiar with them.
+
+==Reference Implementation==
+
+multi_a() and sortedmulti_a() descriptors were implemented in Bitcoin Core in https://github.com/bitcoin/bitcoin/pull/24043 and have been available since version 24.0.
From 44798a2a9e19643040af61818a7acb4cded47e00 Mon Sep 17 00:00:00 2001
From: Salvatore Ingala <6681844+bigspider@users.noreply.github.com>
Date: Thu, 1 Sep 2022 15:30:54 +0200
Subject: [PATCH 04/20] New BIP: Wallet Policies
---
bip-wallet-policies.mediawiki | 343 +++++++++++++++++++++++++
bip-wallet-policies/wallet_policies.py | 200 ++++++++++++++
2 files changed, 543 insertions(+)
create mode 100644 bip-wallet-policies.mediawiki
create mode 100644 bip-wallet-policies/wallet_policies.py
diff --git a/bip-wallet-policies.mediawiki b/bip-wallet-policies.mediawiki
new file mode 100644
index 00000000..e46df1c6
--- /dev/null
+++ b/bip-wallet-policies.mediawiki
@@ -0,0 +1,343 @@
+
+ BIP: wallet-policies
+ Layer: Applications
+ Title: Wallet Policies for Descriptor Wallets
+ Author: Salvatore Ingala
+ Comments-Summary: No comments yet.
+ Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-wallet-policies
+ Status: Draft
+ Type: Informational
+ Created: 2022-11-16
+ License: BSD-2-Clause
+
+
+== Abstract ==
+
+Wallet policies build on top of output descriptors to represent in a compact, easier to inspect way the types of descriptors that are typically used to represent "accounts" in a software wallet, or a hardware signing device. A wallet policy always represents exactly two descriptors, which produce the receive and change addresses that are logically part of the same account.
+
+Reducing the generality of descriptors to just the essential features, and separating the extended pubkeys and other key information from the descriptor, allows to simplify the language in a way that suits devices with limited memory, where even keeping the entire descriptor in memory could be a major hurdle.
+
+Moreover, together with the gain in compactness, this simplifies user's inspection of the policy.
+
+Finally, by keeping the language extremely close to that of output script descriptors, the compilation of wallet policies to the corresponding descriptor is extremely easy, and even the reverse process is not too difficult for supported descriptors.
+
+== Copyright ==
+
+This BIP is licensed under the BSD 2-clause license.
+
+== Motivation ==
+
+''[[bip-0380.mediawiki|Output Script Descriptors]]'' were introduced in bitcoin-core as a way to represent collections of output scripts. It is a very general and flexible language, designed to catch all the possible use-cases of bitcoin wallets (that is, if you know the script and you have the necessary keys, it will be possible to sign transactions with any descriptor-based software wallet).
+
+Unfortunately, descriptors are not a perfect match for the typical usage of hardware signing devices (often also called ''hardware wallets''). Most of them have some of the following limitations when compared to a general-purpose machine running bitcoin-core:
+
+* they are embedded devices with limited RAM, and computational power;
+* they cannot import additional private keys (that is, they can only sign with keys derived from a single seed via [[bip-0032.mediawiki|BIP-32]]);
+* they have limited storage, or they might not have persistent storage at all (''stateless design'').
+
+Moreover, other limitations like the limited size of the screen might affect what design choices are available in practice. Therefore, minimizing the size of the information shown on-screen is important for a good user experience; that is crucial since the ability for the user to completely validate on-screen the kind of script used (and each of the involved keys) is a prerequisite for secure usage, as the machine that is interacting with the hardware signer (and running the software wallet) is considered untrusted.
+
+A more native, compact representation of the wallet receive/change might also benefit the UX of software wallets using descriptors to represent software wallets using descriptors (possibly with miniscript) for 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.
+
+=== Security and UX concerns for hardware signing devices ===
+
+For a hardware signing device, allowing the usage of complex scripts presents challenges in terms of both security and user experience.
+
+==== Security issues ====
+
+One of the security properties that hardware signing devices strive to guarantee is the following: as long as the user correctly verifies the information that is shown on the device's screen before approving, no action can be performed without the user's consent.
+
+This must hold even in scenarios where the attacker has full control of the machine that is connected to the signing device, and can execute arbitrary requests, or tamper with the legitimate user's requests.
+
+Therefore, it is not at all trivial to allow complex scripts, especially if they contain keys that belong to third parties.
+The hardware signing device must guarantee that the user knows precisely what "policy" is being used to spend the funds, and that any "unspent" funds (if any) that is sent to a change address will be protected by the same policy.
+
+This makes it impossible for an attacker to surreptitiously modify the policy, therefore stealing or burning the user's funds.
+
+==== UX issues ====
+
+With miniscript (and taproot trees) allowing substantially more complex spending policies to be used, it becomes more challenging to make sure that the user is practically able to verify the information on the screen.
+
+Therefore, there are two fundamental design goals to strive for:
+* Minimize the amount of information that is shown on screen - so that the user can actually validate it.
+* Minimize the number of times the user has to validate such information.
+
+Designing a secure protocol for the coordination of a descriptor wallet among distant parties is also a challenging problem that is out of scope in this document. See [[bip-00129.mediawiki|BIP-129 (Bitcoin Secure Multisig Setup)]] for an approach designed for multisignature wallets. Regardless the approach, the ability for the user to carefully verify all the details of the spending policies using the hardware signer's screen is a prerequisite for security in adversarial environments.
+
+=== Policy registration as a solution ===
+
+A solution to address the security concerns, and part of the UX concerns, is to have a registration flow for the wallet policy in the hardware signing device. The ''wallet policy'' must contain enough information to generate all the relevant addresses/scripts, and for the hardware signing device to identify the keys that it controls and that are needed to spend the funds sent to those addresses.
+
+Before a new policy is used for the first time, the user will register a wallet policy into the hardware device. While the details of the process are out of scope in this document, the flow should be something similar to the following:
+
+# The software wallet initiates a ''wallet policy registration'' on the hardware signing device; the information should include the wallet policy, but also a unique ''name'' that identifies the policy.
+# The device shows the wallet policy to the user using the secure screen.
+# After inspecting the policy and comparing it with a trusted source (for example a printed backup), the user approves the policy.
+# If stateful, the hardware signing device persists the policy in its permanent memory; if stateless, it returns a "proof of registration".
+
+The proof of registration will allow the hardware signer to verify that a certain policy was indeed previously approved by the user, and is therefore safe to use without repeating the expensive user verification procedure. The details of how to create a proof of registration are out of scope for this document; using a Message Authentication Code on a hash committing to the wallet policy, its name and any additional metadata is an effective solution if correctly executed.
+
+Once a policy is registered, the hardware signing device can perform the typical operations securely:
+* generating receive and change addresses;
+* showing addresses on the secure screen;
+* sign transactions spending from a wallet, while correctly identifying change addresses and computing the transaction fees.
+
+Before any of the actions mentioned above, the hardware signing device will retrieve the policy from its permanent storage if stateful; if stateless it will validate the _proof of registration_ before using the wallet policy provided by the client.
+
+Once the previously registered policy is correctly identified and approved by the user (for example by showing its name), and as long as the policy registration was executed securely, hardware signing devices can provide a user experience similar to the usual one for single-signature transactions.
+
+=== Avoiding blowup in descriptor size ===
+
+While reusing a pubkey in different branches of a miniscript is explicitly forbidden by miniscript (as it has certain negative security implications), it is still reasonable to reuse the same xpub in multiple places, albeit with different final steps of derivation (so that the actual pubkeys that are used in the script are indeed different).
+
+For example, using Taproot, a 3-of-5 multisignature wallet could use:
+* a key path with a 5-of-5 MuSig2 aggregated key
+* a script tree with 11 leaves:
+** 10 different script using a 3-of-3 MuSig2 aggregated key, plus
+** a final leaf with a fallback 3-of-5 multisignature using OP_CHECKSIGADD (in case interactive signing is not available).
+
+This could look similar to:
+
+
+tr(musig(xpubA,xpubB,xpubC,xpubD,xpubE)/<0;1>/*), {
+ {
+ {
+ pk(musig(xpubA,xpubB,xpubC)/<2;3>/*),
+ {
+ pk(musig(xpubA,xpubB,xpubD)/<4;5>/*)
+ pk(musig(xpubA,xpubB,xpubE)/<6;7>/*),
+ }
+ },
+ {
+ pk(musig(xpubA,xpubC,xpubD)/<8;9>/*),
+ {
+ pk(musig(xpubA,xpubC,xpubE)/<10;11>/*),
+ pk(musig(xpubA,xpubD,xpubE)/<12;13>/*)
+ }
+ }
+ },
+ {
+ {
+ pk(musig(xpubB,xpubC,xpubD)/<14;15>/*),
+ pk(musig(xpubB,xpubC,xpubE)/<16;17>/*)
+ },
+ {
+ pk(musig(xpubB,xpubD,xpubE)/<18;19>/*),
+ {
+ pk(musig(xpubC,xpubD,xpubE)/<20;21>/*),
+ sortedmulti_a(3,
+ xpubA/<22;23>/*,
+ xpubB/<22;23>/*,
+ xpubC/<22;23>/*,
+ xpubD/<22;23>/*,
+ xpubE/<22;23>/*)
+ }
+ }
+ }
+})
+
+
+Notice how each root xpub appears 8 times. With xpubs being up to 118 bytes long, the length of the full descriptor can get extremely long (the problem rapidly gets worse with larger multisignature schemes).
+
+Replacing the common part of the key with a short key placeholder and moving the key expression separately helps to keep the size of the wallet policy small, which is crucial to allow human inspection during the registration flow.
+
+== Specification ==
+
+This section formally defines wallet policies, and how they relate to output script descriptors.
+
+=== Formal definition ===
+
+A ''wallet policy'' is composed by a ''wallet descriptor template'', together with a vector of ''key information items''.
+
+==== Wallet descriptor template ====
+
+A ''wallet descriptor template'' is a SCRIPT expression.
+
+SCRIPT expressions:
+* sh(SCRIPT) (top level only): P2SH embed the argument.
+* wsh(SCRIPT) (top level or inside sh only): P2WSH embed the argument.
+* pkh(KP) (not inside tr): P2PKH output for the given public key.
+* wpkh(KP) (top level or inside sh only): P2WPKH output for the given compressed pubkey.
+* multi(k,KP_1,KP_2,...,KP_n) (inside sh or wsh only): ''k''-of-''n'' multisig script.
+* sortedmulti(k,KP_1,KP_2,...,KP_n) (inside sh or wsh only): ''k''-of-''n'' multisig script with keys sorted lexicographically in the resulting script.
+* tr(KP) or tr(KP,TREE) (top level only): P2TR output with the specified key as internal key, and optionally a tree of script paths.
+* any valid miniscript template (inside wsh or tr only).
+
+TREE expressions:
+* any SCRIPT expression
+* An open brace {, a TREE expression, a comma ,, a TREE expression, and a closing brace }
+
+
+KP expressions (key placeholders) consist of
+* a single character @
+* followed by a non-negative decimal number, with no leading zeros (except for @0)
+* ''always'' followed by either:
+** the string /**, or
+** a string of the form //*, for two distinct decimal numbers NUM representing unhardened derivations, or
+** any of the additional, implementation-specific valid derivation path patterns (see [[#Optional_derivation_paths|Optional derivation paths]] below).
+
+The /** in the placeholder template represents commonly used paths for receive/change addresses, and is equivalent to <0;1>/*.
+
+Note that while [[bip-0389.mediawiki|BIP-389]] allows multipath `/` expressions with an arbitrary number of options, this specification restricts it to exactly 2 choices (with the typical meaning of receive/change addresses).
+
+The placeholder @i for some number ''i'' represents the ''i''-th key in the vector of key information items (which must be of size at least ''i + 1'', or the wallet policy is invalid).
+
+Note: while descriptor templates for miniscript are not formally defined in this version of the document (pending standardization) it is straightforward to adapt this approach by adding additional SCRIPT expressions.
+
+==== Keys information vector ====
+
+Each element of the key origin information vector is a KEY expression.
+
+* Optionally, key origin information, consisting of:
+** An open bracket [
+** Exactly 8 hex characters for the fingerprint of the master key from which this key is derived from (see [[bip-0032.mediawiki|BIP-32]] for details)
+** Followed by zero or more /NUM' or /NUM path elements to indicate hardened or unhardened derivation steps between the fingerprint and the xpub that follows
+** A closing bracket ]
+* Followed by the actual key, which is a serialized extended public key (as defined in [[bip-0032.mediawiki|BIP-32]]).
+
+==== Additional rules ====
+
+A wallet policy must have at least one key placeholder and the corresponding key.
+
+The public keys obtained by deserializing elements of the keys information vector must be pairwise distinct['''Why must public keys be distinct?''' Reusing pubkeys could be insecure in the conext of wallet policies containing [https://bitcoin.sipa.be/miniscript/ miniscript]. Avoiding repeated public keys altogether avoids the problem at the source.].
+
+If two key placeholders are @i//* and @i//* for the same index i, then the sets {M, N} and {P, Q} must be disjoint.
+
+The key information vector should be ordered so that placeholder @i never appear for the first time before an occurrence of @j for some j < i; for example, the first placeholder is always @0, the next one is @1, etc.
+
+=== Descriptor derivation ===
+
+From a wallet descriptor template (and the associated vector of key information items), one can therefore obtain the corresponding multipath descriptor by:
+
+* replacing each key placeholder with the corresponding key origin
+information;
+* replacing every /** with /<0;1>/*.
+
+For example, the wallet descriptor pkh(@0/**) with key information
+["[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL"]
+produces the following multipath descriptor:
+
+pkh([d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/<0;1>/*)
+
+=== Implementation guidelines ===
+
+Implementations must not necessarily implement all the possible wallet policies defined by this standard, but it is recommended to clearly document any limitation.
+
+Implementations can add additional metadata that is stored together with the wallet policy for the purpose of wallet policy registration and later usage. Metadata can be vendor-specific and is out of the scope of this document.
+
+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 /* instead of the more common //* 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 (KP) expressions.
+
+However, care needs to be taken in view of the following considerations:
+
+* Allowing derivation schemes with a different length or cardinality in the same wallet policy would make it difficult to guarantee that there are no repeated pubkeys for every possible address generated by the policy. For example, `@0/<0;1>/*` and `@1/*` would generate the same pubkeys if the second public key in the keys information vector is one of the first two unhardened children of the first public key. This could cause malleability with potential security implications (for example, in policies containing miniscript).
+* Allowing naked pubkeys with no /* suffix (for example a descriptor template like wsh(multi(2,@0,@1/<0;1>/*))) would cause a pubkey to be repeated in every output generated from the policy, which would result in a total loss of privacy.
+
+== Examples ==
+
+In the examples in this section, the vector of key information items is omitted. See the test vectors below for complete examples.
+
+Common single-signature account patterns:
+* pkh(@0/**) (legacy).
+* wpkh(@0/**) (native segwit).
+* sh(wpkh(@0/**)) (nested segwit).
+* tr(@0/**) (taproot single-signature account).
+
+Common multisignature schemes:
+* wsh(multi(2,@0/**,@1/**)) - SegWit 2-of-2 multisignature, keys in order.
+* sh(sortedmulti(2,@0/**,@1/**,@2/**)) - Legacy 2-of-3 multisignature, sorted keys.
+
+Some miniscript policies in wsh:
+* wsh(and_v(v:pk(@0/**),or_d(pk(@1/**),older(12960)))) - Trust-minimized second factor, degrading to a single signature after about 90 days.
+* wsh(thresh(3,pk(@0/**),s:pk(@1/**),s:pk(@2/**),sln:older(12960))) - A 3-of-3 wallet that becomes a 2-of-3 if coins are not spent for about 90 days.
+* wsh(or_d(pk(@0/**),and_v(v:multi(2,@1/**,@2/**,@3/**),older(65535)))) - A singlesig wallet with automatic inheritance to a timelocked 2-of-3 multisig of family members.
+
+== Test Vectors ==
+
+=== Valid policies ===
+
+[[bip-0044.mediawiki|BIP-44]], first account
+ Descriptor template: pkh(@0/**)
+ Keys info: ["[6738736c/44'/0'/0']xpub6Br37sWxruYfT8ASpCjVHKGwgdnYFEn98DwiN76i2oyY6fgH1LAPmmDcF46xjxJr22gw4jmVjTE2E3URMnRPEPYyo1zoPSUba563ESMXCeb"]
+ Descriptor:pkh([6738736c/44'/0'/0']xpub6Br37sWxruYfT8ASpCjVHKGwgdnYFEn98DwiN76i2oyY6fgH1LAPmmDcF46xjxJr22gw4jmVjTE2E3URMnRPEPYyo1zoPSUba563ESMXCeb)
+
+[[bip-0049.mediawiki|BIP-49]], second account
+ Descriptor template: sh(wpkh(@0/**))
+ Keys info: ["[6738736c/49'/0'/1']xpub6Bex1CHWGXNNwGVKHLqNC7kcV348FxkCxpZXyCWp1k27kin8sRPayjZUKDjyQeZzGUdyeAj2emoW5zStFFUAHRgd5w8iVVbLgZ7PmjAKAm9"]
+ Descriptor:sh(wpkh([6738736c/49'/0'/1']xpub6Bex1CHWGXNNwGVKHLqNC7kcV348FxkCxpZXyCWp1k27kin8sRPayjZUKDjyQeZzGUdyeAj2emoW5zStFFUAHRgd5w8iVVbLgZ7PmjAKAm9))
+
+[[bip-0084.mediawiki|BIP-84]], third account
+ Descriptor template: wpkh(@0/**)
+ Keys info: ["[6738736c/84'/0'/2']xpub6CRQzb8u9dmMcq5XAwwRn9gcoYCjndJkhKgD11WKzbVGd932UmrExWFxCAvRnDN3ez6ZujLmMvmLBaSWdfWVn75L83Qxu1qSX4fJNrJg2Gt"]
+ Descriptor:wpkh([6738736c/84'/0'/2']xpub6CRQzb8u9dmMcq5XAwwRn9gcoYCjndJkhKgD11WKzbVGd932UmrExWFxCAvRnDN3ez6ZujLmMvmLBaSWdfWVn75L83Qxu1qSX4fJNrJg2Gt)
+
+[[bip-0086.mediawiki|BIP-86]], first account
+ Descriptor template: tr(@0/**)
+ Keys info: ["[6738736c/86'/0'/0']xpub6CryUDWPS28eR2cDyojB8G354izmx294BdjeSvH469Ty3o2E6Tq5VjBJCn8rWBgesvTJnyXNAJ3QpLFGuNwqFXNt3gn612raffLWfdHNkYL"]
+ Descriptor:tr([6738736c/86'/0'/0']xpub6CryUDWPS28eR2cDyojB8G354izmx294BdjeSvH469Ty3o2E6Tq5VjBJCn8rWBgesvTJnyXNAJ3QpLFGuNwqFXNt3gn612raffLWfdHNkYL)
+
+[[bip-0048.mediawiki|BIP-48]] P2WSH multisig
+ Descriptor template: wsh(sortedmulti(2,@0/**,@1/**))
+ Keys info: ["[6738736c/48'/0'/0'/2']xpub6FC1fXFP1GXLX5TKtcjHGT4q89SDRehkQLtbKJ2PzWcvbBHtyDsJPLtpLtkGqYNYZdVVAjRQ5kug9CsapegmmeRutpP7PW4u4wVF9JfkDhw", "[b2b1f0cf/48'/0'/0'/2']xpub6EWhjpPa6FqrcaPBuGBZRJVjzGJ1ZsMygRF26RwN932Vfkn1gyCiTbECVitBjRCkexEvetLdiqzTcYimmzYxyR1BZ79KNevgt61PDcukmC7"]
+ Descriptor:wsh(sortedmulti(2,[6738736c/48'/0'/0'/2']xpub6FC1fXFP1GXLX5TKtcjHGT4q89SDRehkQLtbKJ2PzWcvbBHtyDsJPLtpLtkGqYNYZdVVAjRQ5kug9CsapegmmeRutpP7PW4u4wVF9JfkDhw,[b2b1f0cf/48'/0'/0'/2']xpub6EWhjpPa6FqrcaPBuGBZRJVjzGJ1ZsMygRF26RwN932Vfkn1gyCiTbECVitBjRCkexEvetLdiqzTcYimmzYxyR1BZ79KNevgt61PDcukmC7))
+
+Miniscript: A 3-of-3 that becomes a 2-of-3 after 90 days
+ Descriptor template: wsh(thresh(3,pk(@0/**),s:pk(@1/**),s:pk(@2/**),sln:older(12960)))
+ Keys info: ["[6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa", "[b2b1f0cf/44'/0'/0'/100']xpub6EYajCJHe2CK53RLVXrN14uWoEttZgrRSaRztujsXg7yRhGtHmLBt9ot9Pd5ugfwWEu6eWyJYKSshyvZFKDXiNbBcoK42KRZbxwjRQpm5Js", "[a666a867/44'/0'/0'/100']xpub6Dgsze3ujLi1EiHoCtHFMS9VLS1UheVqxrHGfP7sBJ2DBfChEUHV4MDwmxAXR2ayeytpwm3zJEU3H3pjCR6q6U5sP2p2qzAD71x9z5QShK2"]
+ Descriptor:wsh(thresh(3,pk([6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa/<0,1>/*),s:pk([b2b1f0cf/44'/0'/0'/100']xpub6EYajCJHe2CK53RLVXrN14uWoEttZgrRSaRztujsXg7yRhGtHmLBt9ot9Pd5ugfwWEu6eWyJYKSshyvZFKDXiNbBcoK42KRZbxwjRQpm5Js/<0,1>/*),s:pk([a666a867/44'/0'/0'/100']xpub6Dgsze3ujLi1EiHoCtHFMS9VLS1UheVqxrHGfP7sBJ2DBfChEUHV4MDwmxAXR2ayeytpwm3zJEU3H3pjCR6q6U5sP2p2qzAD71x9z5QShK2/<0,1>/*),sln:older(12960)))
+
+Miniscript: A singlesig wallet with automatic inheritance to a timelocked 2-of-3 multisig
+ Descriptor template: wsh(or_d(pk(@0/**),and_v(v:multi(2,@1/**,@2/**,@3/**),older(65535))))
+ Keys info: ["[6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa", "[b2b1f0cf/44'/0'/0'/100']xpub6EYajCJHe2CK53RLVXrN14uWoEttZgrRSaRztujsXg7yRhGtHmLBt9ot9Pd5ugfwWEu6eWyJYKSshyvZFKDXiNbBcoK42KRZbxwjRQpm5Js", "[a666a867/44'/0'/0'/100']xpub6Dgsze3ujLi1EiHoCtHFMS9VLS1UheVqxrHGfP7sBJ2DBfChEUHV4MDwmxAXR2ayeytpwm3zJEU3H3pjCR6q6U5sP2p2qzAD71x9z5QShK2", "[bb641298/44'/0'/0'/100']xpub6Dz8PHFmXkYkykQ83ySkruky567XtJb9N69uXScJZqweYiQn6FyieajdiyjCvWzRZ2GoLHMRE1cwDfuJZ6461YvNRGVBJNnLA35cZrQKSRJ"]
+ Descriptor:wsh(or_d(pk([6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa),and_v(v:multi(2,[b2b1f0cf/44'/0'/0'/100']xpub6EYajCJHe2CK53RLVXrN14uWoEttZgrRSaRztujsXg7yRhGtHmLBt9ot9Pd5ugfwWEu6eWyJYKSshyvZFKDXiNbBcoK42KRZbxwjRQpm5Js,[a666a867/44'/0'/0'/100']xpub6Dgsze3ujLi1EiHoCtHFMS9VLS1UheVqxrHGfP7sBJ2DBfChEUHV4MDwmxAXR2ayeytpwm3zJEU3H3pjCR6q6U5sP2p2qzAD71x9z5QShK2,[bb641298/44'/0'/0'/100']xpub6Dz8PHFmXkYkykQ83ySkruky567XtJb9N69uXScJZqweYiQn6FyieajdiyjCvWzRZ2GoLHMRE1cwDfuJZ6461YvNRGVBJNnLA35cZrQKSRJ),older(65535))))
+
+
+TBD: add examples with taproot scripts and miniscript.
+
+=== Invalid policies ===
+
+The following descriptor templates are invalid:
+
+* pkh(@0): Key placeholder with no path following it
+* pkh(@0/0/**): Key placeholder with an explicit path present
+* sh(multi(1,@1/**,@0/**)): Key placeholders out of order
+* sh(multi(1,@0/**,@2/**)): Skipped key placeholder @1
+* sh(multi(1,@0/**,@0/**)): Repeated keys with the same path expression
+* sh(multi(1,@0/<0;1>/*,@0/<1;2>/*)): Non-disjoint multipath expressions (@0/1/* appears twice)
+* sh(multi(1,@0/**,xpub6AHA9hZDN11k2ijHMeS5QqHx2KP9aMBRhTDqANMnwVtdyw2TDYRmF8PjpvwUFcL1Et8Hj59S3gTSMcUQ5gAqTz3Wd8EsMTmF3DChhqPQBnU/<0;1>/*)): Expression with a non KP key present
+* pkh(@0/<0;1;2>/*): Solved cardinality > 2
+
+Remark: some of the descriptor templates above might be valid if optional extensions allowing them are added in the implementation.
+
+== Backwards Compatibility ==
+
+The @ character used for key placeholders is not part of the syntax of output script descriptors, therefore any valid output descriptor with at least one `KEY` expression is not a valid descriptor template. Vice versa, any descriptor template with at least one key placeholder is not a valid output script descriptor.
+
+Adoption of wallet policies in software and harder wallets is opt-in. Conversion from wallet policies to the corresponding descriptors is programmatically extremely easy, and conversion from descriptors to wallet policies (when respecting the required patterns) can be automated. See the reference implementation below for some examples of conversion.
+
+Software wallets are recommended to allow exporting plain descriptors for the purposes of interoperability with software not using wallet policies.
+
+== Reference Implementation ==
+
+Wallet policies are implemented in
+* the [https://github.com/LedgerHQ/app-bitcoin-new Ledger bitcoin application] since version 2.1.0;
+* the [https://github.com/digitalbitbox/bitbox02-firmware BitBox02 firmware] since version v9.15.0;
+* [https://github.com/Blockstream/Jade Blockstream Jade] since version v1.0.24, via [https://github.com/ElementsProject/libwally-core libwally-core] v1.0.0.
+
+For development and testing purposes, we provide a [[bip-wallet-policies/wallet_policies.py|Python 3.7 reference implementation]] of simple classes to handle wallet policies, and the conversion to/from output script descriptors.
+The reference implementation is for demonstration purposes only and not to be used in production environments.
+
+==Footnotes==
+
+
+
+== Acknowledgments ==
+
+The authors would like to thank the people who provided feedback in the bitcoin-dev list, and in person.
diff --git a/bip-wallet-policies/wallet_policies.py b/bip-wallet-policies/wallet_policies.py
new file mode 100644
index 00000000..42f615a2
--- /dev/null
+++ b/bip-wallet-policies/wallet_policies.py
@@ -0,0 +1,200 @@
+from typing import Iterable, List, Mapping, Tuple, Generator
+
+
+def find_all(text: str, pattern: str, start: int = 0) -> Generator[int, None, None]:
+ """Generates all the positions of `pattern` as a substring of `text`, starting from index at least `start`."""
+ while True:
+ start = text.find(pattern, start)
+ if start == -1:
+ return
+ yield start
+ start += len(pattern)
+
+
+def find_first(text: str, start_pos: int, patterns: Iterable[str]) -> int:
+ """Returns the position of the first occurrence of any of the elements in `patterns` as a substring of `text`,
+ or -1 if none of the patterns is found."""
+ matches = (text.find(x, start_pos) for x in patterns)
+ return min((x for x in matches if x != -1), default=-1)
+
+
+def find_key_end_position(desc: str, start_pos: int) -> int:
+ """Assuming that `start_pos` is the beginning of a KEY expression (and not musig), finds the position of the end
+ of the key expression, excluding (if present) the final derivation steps after an xpub. This is the information
+ that goes into an entry of the vector of key information of the wallet policy."""
+
+ has_orig_info = True if desc[start_pos] == '[' else False
+
+ if has_orig_info:
+ closing_bracket_pos = desc.find("]", start_pos)
+ if closing_bracket_pos == -1:
+ raise Exception("Invalid descriptor: could not find closing ']'")
+ key_pos_start = closing_bracket_pos + 1
+ else:
+ key_pos_start = start_pos
+
+ # find the earliest occurrence of ",", a ")" or a "/" (it must find at least 1)
+ end_pos = find_first(desc, key_pos_start, [",", ")", "/"])
+ if end_pos == -1:
+ raise Exception(
+ "Invalid descriptor: cannot find the end of key expression")
+
+ return end_pos
+
+
+class WalletPolicy(object):
+ """Simple class to represent wallet policies. This is a toy implementation that does not parse the descriptor
+ template. A more robust implementation would build the abstract syntax tree of the template and of the descriptor,
+ allowing one to detect errors, and manipulate it semantically instead of relying on string manipulation."""
+
+ def __init__(self, descriptor_template: str, keys_info: List[str]):
+ self.descriptor_template = descriptor_template
+ self.keys_info = keys_info
+
+ def to_descriptor(self) -> str:
+ """Converts a wallet policy into the descriptor (with the / syntax, if present)."""
+
+ desc = self.descriptor_template
+
+ # replace each "/**" with "/<0;1>/*"
+ desc = desc.replace("/**", "/<0;1>/*")
+
+ # process all the @N expressions in decreasing order. This guarantees that string replacements
+ # works as expected (as any prefix expression is processed after).
+ for i in reversed(range(len(self.keys_info))):
+ desc = desc.replace(f"@{i}", self.keys_info[i])
+
+ # there should not be any remaining "@" expressions
+ if desc.find("@") != -1:
+ return Exception("Invalid descriptor template: contains invalid key index")
+
+ return desc
+
+ @classmethod
+ def from_descriptor(cls, descriptor: str) -> 'WalletPolicy':
+ """Converts a "reasonable" descriptor (with the / syntax) into the corresponding wallet policy."""
+
+ # list of pairs of integers, where the tuple (m,n) with m < n means a key expression starts at
+ # m (inclusive) and at n (exclusive)
+ key_expressions: List[Tuple[int, int]] = []
+
+ key_with_orig_pos_start = None
+
+ def parse_key_expressions(only_first=False, handle_musig=False):
+ # Starting at the position in `key_with_orig_pos_start`, parses a number of key expressions, and updates
+ # the `key_expressions` array accordingly.
+ # If `only_first` is `True`, it stops after parsing a single key expression.
+ # If `handle_musig` is `True`, and a key expression is a `musig` operator, it recursively parses
+ # the keys in the musig expression. `musig` inside `musig` is not allowed.
+
+ nonlocal key_with_orig_pos_start
+ if key_with_orig_pos_start is None:
+ raise Exception("Unexpected error")
+
+ while True:
+ if handle_musig and descriptor[key_with_orig_pos_start:].startswith("musig"):
+ closing_parenthesis_pos = find_first(
+ descriptor, key_with_orig_pos_start, [")"])
+ if closing_parenthesis_pos == -1:
+ raise Exception(
+ "Invalid descriptor: musig without closing parenthesis")
+ key_with_orig_pos_start = key_with_orig_pos_start + \
+ len("musig(")
+ parse_key_expressions(
+ only_first=False, handle_musig=False)
+
+ key_pos_end = closing_parenthesis_pos + 1
+ else:
+ key_pos_end = find_key_end_position(
+ descriptor, key_with_orig_pos_start)
+ key_expressions.append(
+ (key_with_orig_pos_start, key_pos_end))
+
+ if descriptor[key_pos_end] == '/':
+ # find the actual end (comma or closing parenthesis)
+ key_pos_end = find_first(
+ descriptor, key_pos_end, [",", ")"])
+ if key_pos_end == -1:
+ raise Exception(
+ "Invalid descriptor: unterminated key expression")
+
+ if descriptor[key_pos_end] == ',':
+ # There is another key expression, repeat from after the comma
+ key_with_orig_pos_start = key_pos_end + 1
+ else:
+ break
+
+ if only_first:
+ break
+
+ # operators for which the KEY is the first argument
+ operators_key_first = ["pk", "pkh", "pk_h", "pk_k", "tr"]
+ # operators for which the KEY is everything except the first argument
+ operators_key_all_but_first = [
+ "multi", "sortedmulti", "multi_a", "sortedmulti_a"]
+ for op in operators_key_first + operators_key_all_but_first:
+ for op_pos_start in find_all(descriptor, op + "("):
+
+ # ignore if not a whole word (otherwise "sortedmulti" would be found inside "multi")
+ if op_pos_start > 0 and 'a' <= desc[op_pos_start - 1] <= 'z':
+ continue
+
+ if op in operators_key_all_but_first:
+ # skip the first argument (we now it's not a KEY expression, so it does not have a comma)
+ first_comma_pos = descriptor.find(",", op_pos_start)
+ if first_comma_pos == -1:
+ raise Exception(
+ "Invalid descriptor: multi, sortedmulti, multi_a and sortedmulti_a must have at least two arguments")
+ key_with_orig_pos_start = 1 + first_comma_pos
+ else:
+ # other operators, the first argument is already a KEY expression
+ key_with_orig_pos_start = op_pos_start + len(op) + 1
+
+ only_first = op in operators_key_first
+ parse_key_expressions(
+ only_first=only_first, handle_musig=True)
+
+ result: List[str] = []
+ keys: List[str] = []
+ keys_to_idx: Mapping[str, int] = {}
+
+ prev_end = 0
+ for start, end in sorted(key_expressions):
+ result.append(descriptor[prev_end:start])
+
+ key = descriptor[start:end]
+ if key not in keys_to_idx:
+ idx = len(keys)
+ keys.append(key)
+ keys_to_idx[key] = idx
+ else:
+ idx = keys_to_idx[key]
+ result.append(f"@{idx}")
+
+ prev_end = end
+
+ result.append(descriptor[prev_end:])
+
+ return cls("".join(result), keys)
+
+
+if __name__ == "__main__":
+ descriptors = [
+ "pkh([d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/**)",
+ "wsh(multi(1,xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB/**,xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/**))",
+ "tr([12345678/44'/0'/0']xpub6BVZ6JrGsWsUbpP74S8rnz13hVFDtYtKyuTTEYPNSF6GFpDFpL1YXWg3BpwpUWAnsZZ7Qe3XKz7GL3BEx3RQVq61cxqSkjceq25S1xFKFVa,{pk(xpub6AGdromjXf5yf3m7ndaCoR9Ac3UjwTvQ7QQkZoyoh2vfGE9i1AwB2vCbvjTpBL1KRERUsGszg63SVNXsHZU3CiykQqtZPrdXKMdaG2vs6uu),pk(xpub6AnhdkteWC4kPQvkY3QQXGmDCMfmFoYzEQ7FwRFa4BQ1a22k4VL4BD3Jdcog2Sf2KzBscXXAdPRMgjCBDeq6bAryqnMaWX2FaVUGPxWMLDh)})",
+ "tr(xpub6AEWqA1MNRzBBXenkug4NtNguDKTNcXoKQj8fU9VQyid38yikruFRffjoDm9UEaHGEJ6jQxjYdWWZRxR7Xy5ePrQNjohXJuNzkRNSiiBUcE,sortedmulti_a(2,[11223344/44'/0'/0']xpub6AyJhEKxcPaPnYNuA7VBeUQ24v6mEzzPSX5AJm3TSyg1Zsti7rnGKy1Hg6JAdXKF4QUmFZbby9p97AjBNm2VFCEec2ip5C9JntyxosmCeMW,xpub6AQVHBgieCHpGo4GhpGAo4v9v7hfr2Kr4D8ZQJqJwbEyZwtW3pWYSLRQyrNYbTzpoq6XpFtaKZGnEGUMtiydCgqsJDAZNqs9L5QDNKqUBsV))",
+ "tr([11111111/44'/0'/0']xpub6CLZSUDtcUhJVDoPSY8pSRKi4W1RSSLBgwZ2AYmwTH9Yv5tPVFHZxJBUQ27QLLwHej6kfo9DQQbwaHmpXsQq59CjtsE2gNLHmojwgMrsQNe/**,{and_v(v:pk([22222222/44'/0'/0']xpub6CiztfGsUxmpwkWe6gvz8d5VHyFLDoiPpeUfWmQ2vWAhQL3Z1hhEc6PE4irFs4bzjS7dCB4yyinaubrCpFJq4bcKGCD4jjqTxaWiKAJ7mvJ/**),older(52596)),multi_a(2,[33333333/44'/0'/0']xpub6DTZd6od7is2wxXndmE7zaUifzFPwVKshVSGEZedfTJtUjfLyhy4hgCW15hvxRpGaDmtiFoJKaCEaSRfXrQBuYRx18zwquy46dwBsJnsrz2/**,[44444444/44'/0'/0']xpub6BnK4wFbPeLZM4VNjoUA4yLCru6kCT3bhDJNBhbzHLGp1fmgK6muz27h4drixJZeHG8vSS5U5EYyE3gE8ozG94iNg3NDYE8M5YafvhzhMR9/**)})",
+ "tr(musig([33333333/44'/0'/0']xpub6DTZd6od7is2wxXndmE7zaUifzFPwVKshVSGEZedfTJtUjfLyhy4hgCW15hvxRpGaDmtiFoJKaCEaSRfXrQBuYRx18zwquy46dwBsJnsrz2,[44444444/44'/0'/0']xpub6BnK4wFbPeLZM4VNjoUA4yLCru6kCT3bhDJNBhbzHLGp1fmgK6muz27h4drixJZeHG8vSS5U5EYyE3gE8ozG94iNg3NDYE8M5YafvhzhMR9)/**,{and_v(v:pk([22222222/44'/0'/0']xpub6CiztfGsUxmpwkWe6gvz8d5VHyFLDoiPpeUfWmQ2vWAhQL3Z1hhEc6PE4irFs4bzjS7dCB4yyinaubrCpFJq4bcKGCD4jjqTxaWiKAJ7mvJ/**),older(52596)),pk([11111111/44'/0'/0']xpub6CLZSUDtcUhJVDoPSY8pSRKi4W1RSSLBgwZ2AYmwTH9Yv5tPVFHZxJBUQ27QLLwHej6kfo9DQQbwaHmpXsQq59CjtsE2gNLHmojwgMrsQNe/**)})",
+ ]
+
+ for desc in descriptors:
+ # Demoes the conversion from a "sane" descriptor to a wallet policy
+ print(f"Descriptor:\n{desc}")
+ wp = WalletPolicy.from_descriptor(desc)
+ print(f"Policy descriptor template:\n{wp.descriptor_template}")
+ print(f"Keys:\n{wp.keys_info}")
+ print("======================================================\n")
+
+ # Converting back to descriptors also works, as long as we take care of /**
+ assert wp.to_descriptor().replace("/<0;1>/*", "/**") == desc
From 25657cbee641fa63936a0313700c009466cd56d6 Mon Sep 17 00:00:00 2001
From: Salvatore Ingala <6681844+bigspider@users.noreply.github.com>
Date: Mon, 8 Jan 2024 11:41:17 +0100
Subject: [PATCH 05/20] Update assigned BIP number; change type to "Standards
Track"
---
bip-wallet-policies.mediawiki => bip-0388.mediawiki | 6 +++---
{bip-wallet-policies => bip-0388}/wallet_policies.py | 0
2 files changed, 3 insertions(+), 3 deletions(-)
rename bip-wallet-policies.mediawiki => bip-0388.mediawiki (99%)
rename {bip-wallet-policies => bip-0388}/wallet_policies.py (100%)
diff --git a/bip-wallet-policies.mediawiki b/bip-0388.mediawiki
similarity index 99%
rename from bip-wallet-policies.mediawiki
rename to bip-0388.mediawiki
index e46df1c6..a7114dd2 100644
--- a/bip-wallet-policies.mediawiki
+++ b/bip-0388.mediawiki
@@ -1,12 +1,12 @@
- BIP: wallet-policies
+ BIP: 388
Layer: Applications
Title: Wallet Policies for Descriptor Wallets
Author: Salvatore Ingala
Comments-Summary: No comments yet.
- Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-wallet-policies
+ Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0388
Status: Draft
- Type: Informational
+ Type: Standards Track
Created: 2022-11-16
License: BSD-2-Clause
diff --git a/bip-wallet-policies/wallet_policies.py b/bip-0388/wallet_policies.py
similarity index 100%
rename from bip-wallet-policies/wallet_policies.py
rename to bip-0388/wallet_policies.py
From 40c7760d781e760fe01bb6fe86a7731f506daa07 Mon Sep 17 00:00:00 2001
From: Salvatore Ingala <6681844+bigspider@users.noreply.github.com>
Date: Sun, 5 May 2024 11:38:49 -0500
Subject: [PATCH 06/20] Apply suggestions from code review
Co-authored-by: Mark "Murch" Erhardt
---
bip-0388.mediawiki | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/bip-0388.mediawiki b/bip-0388.mediawiki
index a7114dd2..f34d2e84 100644
--- a/bip-0388.mediawiki
+++ b/bip-0388.mediawiki
@@ -9,6 +9,7 @@
Type: Standards Track
Created: 2022-11-16
License: BSD-2-Clause
+ Post-History: 2022-05-10: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2022-May/020423.html
== Abstract ==
@@ -64,7 +65,7 @@ Therefore, there are two fundamental design goals to strive for:
* Minimize the amount of information that is shown on screen - so that the user can actually validate it.
* Minimize the number of times the user has to validate such information.
-Designing a secure protocol for the coordination of a descriptor wallet among distant parties is also a challenging problem that is out of scope in this document. See [[bip-00129.mediawiki|BIP-129 (Bitcoin Secure Multisig Setup)]] for an approach designed for multisignature wallets. Regardless the approach, the ability for the user to carefully verify all the details of the spending policies using the hardware signer's screen is a prerequisite for security in adversarial environments.
+Designing a secure protocol for the coordination of a descriptor wallet among distant parties is also a challenging problem that is out of scope in this document. See [[bip-00129.mediawiki|BIP-129 (Bitcoin Secure Multisig Setup)]] for an approach designed for multisignature wallets. Regardless of the approach, the ability for the user to carefully verify all the details of the spending policies using the hardware signer's screen is a prerequisite for security in adversarial environments.
=== Policy registration as a solution ===
@@ -320,7 +321,7 @@ Remark: some of the descriptor templates above might be valid if optional extens
The @ character used for key placeholders is not part of the syntax of output script descriptors, therefore any valid output descriptor with at least one `KEY` expression is not a valid descriptor template. Vice versa, any descriptor template with at least one key placeholder is not a valid output script descriptor.
-Adoption of wallet policies in software and harder wallets is opt-in. Conversion from wallet policies to the corresponding descriptors is programmatically extremely easy, and conversion from descriptors to wallet policies (when respecting the required patterns) can be automated. See the reference implementation below for some examples of conversion.
+Adoption of wallet policies in software and hardware wallets is opt-in. Conversion from wallet policies to the corresponding descriptors is programmatically extremely easy, and conversion from descriptors to wallet policies (when respecting the required patterns) can be automated. See the reference implementation below for some examples of conversion.
Software wallets are recommended to allow exporting plain descriptors for the purposes of interoperability with software not using wallet policies.
From 95cf53916113a44487e0381029d3602e5bb1db6a Mon Sep 17 00:00:00 2001
From: Salvatore Ingala <6681844+bigspider@users.noreply.github.com>
Date: Tue, 7 May 2024 10:51:46 +0200
Subject: [PATCH 07/20] Improvements from PR review.
- Removed large example of taproot policy; replaced with the textual description
- Added an example of a taproot wallet policy containing miniscript
---
bip-0388.mediawiki | 56 ++++++++--------------------------------------
1 file changed, 9 insertions(+), 47 deletions(-)
diff --git a/bip-0388.mediawiki b/bip-0388.mediawiki
index f34d2e84..a62b262c 100644
--- a/bip-0388.mediawiki
+++ b/bip-0388.mediawiki
@@ -93,54 +93,13 @@ Once the previously registered policy is correctly identified and approved by th
While reusing a pubkey in different branches of a miniscript is explicitly forbidden by miniscript (as it has certain negative security implications), it is still reasonable to reuse the same xpub in multiple places, albeit with different final steps of derivation (so that the actual pubkeys that are used in the script are indeed different).
-For example, using Taproot, a 3-of-5 multisignature wallet could use:
+In fact, there are many reasonable spending policies with a quadratic size in the number of participants. For example, using Taproot, a 3-of-5 multisignature wallet could use:
* a key path with a 5-of-5 MuSig2 aggregated key
* a script tree with 11 leaves:
-** 10 different script using a 3-of-3 MuSig2 aggregated key, plus
-** a final leaf with a fallback 3-of-5 multisignature using OP_CHECKSIGADD (in case interactive signing is not available).
+** 10 different scripts using a 3-of-3 MuSig2 aggregated key, plus
+** a final leaf with a fallback 3-of-5 multisignature using multi_a (in case interactive signing is not available).
-This could look similar to:
-
-
-tr(musig(xpubA,xpubB,xpubC,xpubD,xpubE)/<0;1>/*), {
- {
- {
- pk(musig(xpubA,xpubB,xpubC)/<2;3>/*),
- {
- pk(musig(xpubA,xpubB,xpubD)/<4;5>/*)
- pk(musig(xpubA,xpubB,xpubE)/<6;7>/*),
- }
- },
- {
- pk(musig(xpubA,xpubC,xpubD)/<8;9>/*),
- {
- pk(musig(xpubA,xpubC,xpubE)/<10;11>/*),
- pk(musig(xpubA,xpubD,xpubE)/<12;13>/*)
- }
- }
- },
- {
- {
- pk(musig(xpubB,xpubC,xpubD)/<14;15>/*),
- pk(musig(xpubB,xpubC,xpubE)/<16;17>/*)
- },
- {
- pk(musig(xpubB,xpubD,xpubE)/<18;19>/*),
- {
- pk(musig(xpubC,xpubD,xpubE)/<20;21>/*),
- sortedmulti_a(3,
- xpubA/<22;23>/*,
- xpubB/<22;23>/*,
- xpubC/<22;23>/*,
- xpubD/<22;23>/*,
- xpubE/<22;23>/*)
- }
- }
- }
-})
-
-
-Notice how each root xpub appears 8 times. With xpubs being up to 118 bytes long, the length of the full descriptor can get extremely long (the problem rapidly gets worse with larger multisignature schemes).
+With each xpub being 118 bytes long, the repetition of xpubs makes the descriptor become extremely large.
Replacing the common part of the key with a short key placeholder and moving the key expression separately helps to keep the size of the wallet policy small, which is crucial to allow human inspection during the registration flow.
@@ -299,8 +258,11 @@ Miniscript: A singlesig wallet with automatic inheritance to a timelocked 2-of-3
Keys info: ["[6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa", "[b2b1f0cf/44'/0'/0'/100']xpub6EYajCJHe2CK53RLVXrN14uWoEttZgrRSaRztujsXg7yRhGtHmLBt9ot9Pd5ugfwWEu6eWyJYKSshyvZFKDXiNbBcoK42KRZbxwjRQpm5Js", "[a666a867/44'/0'/0'/100']xpub6Dgsze3ujLi1EiHoCtHFMS9VLS1UheVqxrHGfP7sBJ2DBfChEUHV4MDwmxAXR2ayeytpwm3zJEU3H3pjCR6q6U5sP2p2qzAD71x9z5QShK2", "[bb641298/44'/0'/0'/100']xpub6Dz8PHFmXkYkykQ83ySkruky567XtJb9N69uXScJZqweYiQn6FyieajdiyjCvWzRZ2GoLHMRE1cwDfuJZ6461YvNRGVBJNnLA35cZrQKSRJ"]
Descriptor:wsh(or_d(pk([6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa),and_v(v:multi(2,[b2b1f0cf/44'/0'/0'/100']xpub6EYajCJHe2CK53RLVXrN14uWoEttZgrRSaRztujsXg7yRhGtHmLBt9ot9Pd5ugfwWEu6eWyJYKSshyvZFKDXiNbBcoK42KRZbxwjRQpm5Js,[a666a867/44'/0'/0'/100']xpub6Dgsze3ujLi1EiHoCtHFMS9VLS1UheVqxrHGfP7sBJ2DBfChEUHV4MDwmxAXR2ayeytpwm3zJEU3H3pjCR6q6U5sP2p2qzAD71x9z5QShK2,[bb641298/44'/0'/0'/100']xpub6Dz8PHFmXkYkykQ83ySkruky567XtJb9N69uXScJZqweYiQn6FyieajdiyjCvWzRZ2GoLHMRE1cwDfuJZ6461YvNRGVBJNnLA35cZrQKSRJ),older(65535))))
-
-TBD: add examples with taproot scripts and miniscript.
+Taproot wallet policy with sortedmulti_a and a miniscript leaf
+ Descriptor template: tr(@0/**,{sortedmulti_a(1,@0/<2;3>/*,@1/**),or_b(pk(@2/**),s:pk(@3/**))})
+ Keys info: ["[6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa", "xpub6Fc2TRaCWNgfT49nRGG2G78d1dPnjhW66gEXi7oYZML7qEFN8e21b2DLDipTZZnfV6V7ivrMkvh4VbnHY2ChHTS9qM3XVLJiAgcfagYQk6K", "xpub6GxHB9kRdFfTqYka8tgtX9Gh3Td3A9XS8uakUGVcJ9NGZ1uLrGZrRVr67DjpMNCHprZmVmceFTY4X4wWfksy8nVwPiNvzJ5pjLxzPtpnfEM", "xpub6GjFUVVYewLj5no5uoNKCWuyWhQ1rKGvV8DgXBG9Uc6DvAKxt2dhrj1EZFrTNB5qxAoBkVW3wF8uCS3q1ri9fueAa6y7heFTcf27Q4gyeh6"]
+ Descriptor:tr([6738736c/48'/0'/0'/100']xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa/<0;1>/*,{sortedmulti_a(1,xpub6FC1fXFP1GXQpyRFfSE1vzzySqs3Vg63bzimYLeqtNUYbzA87kMNTcuy9ubr7MmavGRjW2FRYHP4WGKjwutbf1ghgkUW9H7e3ceaPLRcVwa/<2;3>/*,xpub6Fc2TRaCWNgfT49nRGG2G78d1dPnjhW66gEXi7oYZML7qEFN8e21b2DLDipTZZnfV6V7ivrMkvh4VbnHY2ChHTS9qM3XVLJiAgcfagYQk6K/<0;1>/*),or_b(pk(xpub6GxHB9kRdFfTqYka8tgtX9Gh3Td3A9XS8uakUGVcJ9NGZ1uLrGZrRVr67DjpMNCHprZmVmceFTY4X4wWfksy8nVwPiNvzJ5pjLxzPtpnfEM/<0;1>/*),s:pk(xpub6GjFUVVYewLj5no5uoNKCWuyWhQ1rKGvV8DgXBG9Uc6DvAKxt2dhrj1EZFrTNB5qxAoBkVW3wF8uCS3q1ri9fueAa6y7heFTcf27Q4gyeh6/<0;1>/*))})
+
=== Invalid policies ===
From a0c8501f960ac29878e137c03dcd6d8a3b9096b5 Mon Sep 17 00:00:00 2001
From: Salvatore Ingala <6681844+bigspider@users.noreply.github.com>
Date: Tue, 7 May 2024 10:55:55 +0200
Subject: [PATCH 08/20] Added BIP-388 to README
---
README.mediawiki | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/README.mediawiki b/README.mediawiki
index be18dcf8..0ce7b8e8 100644
--- a/README.mediawiki
+++ b/README.mediawiki
@@ -1184,6 +1184,13 @@ Those proposing changes should consider that ultimately consent may rest with th
| Informational
| Draft
|-
+| [[bip-0388.mediawiki|388]]
+| Applications
+| Wallet Policies for Descriptor Wallets
+| Salvatore Ingala
+| Standard
+| Draft
+|-
| [[bip-0389.mediawiki|389]]
| Applications
| Multipath Descriptor Key Expressions
From 4ddb0cc8933fe677103b8c1b2407922c76b98f71 Mon Sep 17 00:00:00 2001
From: katesalazar <52637275+katesalazar@users.noreply.github.com>
Date: Sat, 4 May 2024 15:17:28 +0000
Subject: [PATCH 09/20] Update bip-0038.mediawiki
Add missing closing double single quote. The italicized paragraph gets
cautiously closed.
---
bip-0038.mediawiki | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/bip-0038.mediawiki b/bip-0038.mediawiki
index f5013db3..8a79bf66 100644
--- a/bip-0038.mediawiki
+++ b/bip-0038.mediawiki
@@ -39,7 +39,7 @@ This proposal is hereby placed in the public domain.
:'''''User story:''' As a Bitcoin user who uses paper wallets, I would like the ability to add encryption, so that my Bitcoin paper storage can be two factor: something I have plus something I know.''
:'''''User story:''' As a Bitcoin user who would like to pay a person or a company with a private key, I do not want to worry that any part of the communication path may result in the interception of the key and theft of my funds. I would prefer to offer an encrypted private key, and then follow it up with the password using a different communication channel (e.g. a phone call or SMS).''
:'''''User story:''' (EC-multiplied keys) As a user of physical bitcoins, I would like a third party to be able to create password-protected Bitcoin private keys for me, without them knowing the password, so I can benefit from the physical bitcoin without the issuer having access to the private key. I would like to be able to choose a password whose minimum length and required format does not preclude me from memorizing it or engraving it on my physical bitcoin, without exposing me to an undue risk of password cracking and/or theft by the manufacturer of the item.''
-:'''''User story:''' (EC-multiplied keys) As a user of paper wallets, I would like the ability to generate a large number of Bitcoin addresses protected by the same password, while enjoying a high degree of security (highly expensive scrypt parameters), but without having to incur the scrypt delay for each address I generate.
+:'''''User story:''' (EC-multiplied keys) As a user of paper wallets, I would like the ability to generate a large number of Bitcoin addresses protected by the same password, while enjoying a high degree of security (highly expensive scrypt parameters), but without having to incur the scrypt delay for each address I generate.''
==Specification==
This proposal makes use of the following functions and definitions:
From c88a018409e6ce8ae07a2ef9b950cd8e9afcbb70 Mon Sep 17 00:00:00 2001
From: katesalazar <52637275+katesalazar@users.noreply.github.com>
Date: Sat, 4 May 2024 15:21:20 +0000
Subject: [PATCH 10/20] Update bip-0038.mediawiki
Separating the bold and the italic markup helps inconsistent parsing
(see screenshots in PR #1586).
---
bip-0038.mediawiki | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/bip-0038.mediawiki b/bip-0038.mediawiki
index 8a79bf66..ffae832e 100644
--- a/bip-0038.mediawiki
+++ b/bip-0038.mediawiki
@@ -36,10 +36,10 @@ Password and passphrase-protected private keys enable new practical use cases fo
This proposal is hereby placed in the public domain.
==Rationale==
-:'''''User story:''' As a Bitcoin user who uses paper wallets, I would like the ability to add encryption, so that my Bitcoin paper storage can be two factor: something I have plus something I know.''
-:'''''User story:''' As a Bitcoin user who would like to pay a person or a company with a private key, I do not want to worry that any part of the communication path may result in the interception of the key and theft of my funds. I would prefer to offer an encrypted private key, and then follow it up with the password using a different communication channel (e.g. a phone call or SMS).''
-:'''''User story:''' (EC-multiplied keys) As a user of physical bitcoins, I would like a third party to be able to create password-protected Bitcoin private keys for me, without them knowing the password, so I can benefit from the physical bitcoin without the issuer having access to the private key. I would like to be able to choose a password whose minimum length and required format does not preclude me from memorizing it or engraving it on my physical bitcoin, without exposing me to an undue risk of password cracking and/or theft by the manufacturer of the item.''
-:'''''User story:''' (EC-multiplied keys) As a user of paper wallets, I would like the ability to generate a large number of Bitcoin addresses protected by the same password, while enjoying a high degree of security (highly expensive scrypt parameters), but without having to incur the scrypt delay for each address I generate.''
+:'' '''User story:''' As a Bitcoin user who uses paper wallets, I would like the ability to add encryption, so that my Bitcoin paper storage can be two factor: something I have plus something I know.''
+:'' '''User story:''' As a Bitcoin user who would like to pay a person or a company with a private key, I do not want to worry that any part of the communication path may result in the interception of the key and theft of my funds. I would prefer to offer an encrypted private key, and then follow it up with the password using a different communication channel (e.g. a phone call or SMS).''
+:'' '''User story:''' (EC-multiplied keys) As a user of physical bitcoins, I would like a third party to be able to create password-protected Bitcoin private keys for me, without them knowing the password, so I can benefit from the physical bitcoin without the issuer having access to the private key. I would like to be able to choose a password whose minimum length and required format does not preclude me from memorizing it or engraving it on my physical bitcoin, without exposing me to an undue risk of password cracking and/or theft by the manufacturer of the item.''
+:'' '''User story:''' (EC-multiplied keys) As a user of paper wallets, I would like the ability to generate a large number of Bitcoin addresses protected by the same password, while enjoying a high degree of security (highly expensive scrypt parameters), but without having to incur the scrypt delay for each address I generate.''
==Specification==
This proposal makes use of the following functions and definitions:
From cf2250e27cc682289facc27e1e2ff16e94d12aab Mon Sep 17 00:00:00 2001
From: Salvatore Ingala <6681844+bigspider@users.noreply.github.com>
Date: Tue, 7 May 2024 22:10:44 +0200
Subject: [PATCH 11/20] Apply suggestions from code review
Co-authored-by: Mark "Murch" Erhardt
---
bip-0388.mediawiki | 36 ++++++++++++++++++------------------
1 file changed, 18 insertions(+), 18 deletions(-)
diff --git a/bip-0388.mediawiki b/bip-0388.mediawiki
index a62b262c..d7ed0bec 100644
--- a/bip-0388.mediawiki
+++ b/bip-0388.mediawiki
@@ -14,13 +14,13 @@
== Abstract ==
-Wallet policies build on top of output descriptors to represent in a compact, easier to inspect way the types of descriptors that are typically used to represent "accounts" in a software wallet, or a hardware signing device. A wallet policy always represents exactly two descriptors, which produce the receive and change addresses that are logically part of the same account.
+Wallet policies build on top of output 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.
-Reducing the generality of descriptors to just the essential features, and separating the extended pubkeys and other key information from the descriptor, allows to simplify the language in a way that suits devices with limited memory, where even keeping the entire descriptor in memory could be a major hurdle.
+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.
-Moreover, together with the gain in compactness, this simplifies user's inspection of the policy.
+This results in a more compact representation and simplifies the inspection of the policy by the user.
-Finally, by keeping the language extremely close to that of output script descriptors, the compilation of wallet policies to the corresponding descriptor is extremely easy, and even the reverse process is not too difficult for supported descriptors.
+The compilation of wallet policies to the corresponding descriptor is trivial, and the reverse process is easy for supported descriptors, because the language is kept similar to that of output script descriptors.
== Copyright ==
@@ -28,27 +28,27 @@ This BIP is licensed under the BSD 2-clause license.
== Motivation ==
-''[[bip-0380.mediawiki|Output Script Descriptors]]'' were introduced in bitcoin-core as a way to represent collections of output scripts. It is a very general and flexible language, designed to catch all the possible use-cases of bitcoin wallets (that is, if you know the script and you have the necessary keys, it will be possible to sign transactions with any descriptor-based software wallet).
+''[[bip-0380.mediawiki|Output Script Descriptors]]'' were introduced in Bitcoin Core as a way to represent collections of output scripts. It is a general and flexible language, designed to catch all the possible use-cases of bitcoin wallets (that is, if you know the script and you have the necessary keys, it will be possible to sign transactions with any descriptor-based software wallet).
-Unfortunately, descriptors are not a perfect match for the typical usage of hardware signing devices (often also called ''hardware wallets''). Most of them have some of the following limitations when compared to a general-purpose machine running bitcoin-core:
+Unfortunately, descriptors are not a perfect match for the typical usage of hardware signing devices (often also called ''hardware wallets''). Most of them have some of the following limitations when compared to a general-purpose machine running Bitcoin Core:
* they are embedded devices with limited RAM, and computational power;
* they cannot import additional private keys (that is, they can only sign with keys derived from a single seed via [[bip-0032.mediawiki|BIP-32]]);
* they have limited storage, or they might not have persistent storage at all (''stateless design'').
-Moreover, other limitations like the limited size of the screen might affect what design choices are available in practice. Therefore, minimizing the size of the information shown on-screen is important for a good user experience; that is crucial since the ability for the user to completely validate on-screen the kind of script used (and each of the involved keys) is a prerequisite for secure usage, as the machine that is interacting with the hardware signer (and running the software wallet) is considered untrusted.
+Moreover, other limitations like the limited size of the screen might affect what design choices are available in practice. Therefore, minimizing the amount of information shown on-screen is important for a good user experience. The ability for the user to completely validate on-screen the kind of script used (and each of the involved keys) is crucial for secure usage, as the machine that is interacting with the hardware signer (and running the software wallet) is considered untrusted.
-A more native, compact representation of the wallet receive/change might also benefit the UX of software wallets using descriptors to represent software wallets using descriptors (possibly with miniscript) for complex locking conditions.
+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.
=== Security and UX concerns for hardware signing devices ===
-For a hardware signing device, allowing the usage of complex scripts presents challenges in terms of both security and user experience.
+The usage of complex scripts presents challenges in terms of both security and user experience for a hardware signing device.
==== Security issues ====
-One of the security properties that hardware signing devices strive to guarantee is the following: as long as the user correctly verifies the information that is shown on the device's screen before approving, no action can be performed without the user's consent.
+Hardware signing devices strive to guarantee that no action can be performed without the user’s consent as long as the user correctly verifies the information that is shown on the device’s screen before approving.
This must hold even in scenarios where the attacker has full control of the machine that is connected to the signing device, and can execute arbitrary requests, or tamper with the legitimate user's requests.
@@ -59,9 +59,9 @@ This makes it impossible for an attacker to surreptitiously modify the policy, t
==== UX issues ====
-With miniscript (and taproot trees) allowing substantially more complex spending policies to be used, it becomes more challenging to make sure that the user is practically able to verify the information on the screen.
+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.
-Therefore, there are two fundamental design goals to strive for:
+We set two fundamental design goals:
* Minimize the amount of information that is shown on screen - so that the user can actually validate it.
* Minimize the number of times the user has to validate such information.
@@ -144,7 +144,7 @@ Note that while [[bip-0389.mediawiki|BIP-389]] allows multipath `/@i for some number ''i'' represents the ''i''-th key in the vector of key information items (which must be of size at least ''i + 1'', or the wallet policy is invalid).
-Note: while descriptor templates for miniscript are not formally defined in this version of the document (pending standardization) it is straightforward to adapt this approach by adding additional SCRIPT expressions.
+Note: while descriptor templates for miniscript are not formally defined in this version of the document (pending standardization), it is straightforward to adapt this approach by adding additional SCRIPT expressions.
==== Keys information vector ====
@@ -161,11 +161,11 @@ Each element of the key origin information vector is a KEY expression.
A wallet policy must have at least one key placeholder and the corresponding key.
-The public keys obtained by deserializing elements of the keys information vector must be pairwise distinct['''Why must public keys be distinct?''' Reusing pubkeys could be insecure in the conext of wallet policies containing [https://bitcoin.sipa.be/miniscript/ miniscript]. Avoiding repeated public keys altogether avoids the problem at the source.].
+The public keys obtained by deserializing elements of the keys information vector must be pairwise distinct['''Why must public keys be distinct?''' Reusing pubkeys could be insecure in the context of wallet policies containing [https://bitcoin.sipa.be/miniscript/ miniscript]. Avoiding repeated public keys altogether avoids the problem at the source.].
If two key placeholders are @i//* and @i//* for the same index i, then the sets {M, N} and {P, Q} must be disjoint.
-The key information vector should be ordered so that placeholder @i never appear for the first time before an occurrence of @j for some j < i; for example, the first placeholder is always @0, the next one is @1, etc.
+The key information vector should be ordered so that placeholder @i never appears for the first time before an occurrence of @j for some j < i; for example, the first placeholder is always @0, the next one is @1, etc.
=== Descriptor derivation ===
@@ -183,7 +183,7 @@ produces the following multipath descriptor:
=== Implementation guidelines ===
-Implementations must not necessarily implement all the possible wallet policies defined by this standard, but it is recommended to clearly document any limitation.
+It is acceptable to implement only a subset of the possible wallet policies defined by this standard. It is recommended that any limitations are clearly documented.
Implementations can add additional metadata that is stored together with the wallet policy for the purpose of wallet policy registration and later usage. Metadata can be vendor-specific and is out of the scope of this document.
@@ -274,10 +274,10 @@ The following descriptor templates are invalid:
* sh(multi(1,@0/**,@2/**)): Skipped key placeholder @1
* sh(multi(1,@0/**,@0/**)): Repeated keys with the same path expression
* sh(multi(1,@0/<0;1>/*,@0/<1;2>/*)): Non-disjoint multipath expressions (@0/1/* appears twice)
-* sh(multi(1,@0/**,xpub6AHA9hZDN11k2ijHMeS5QqHx2KP9aMBRhTDqANMnwVtdyw2TDYRmF8PjpvwUFcL1Et8Hj59S3gTSMcUQ5gAqTz3Wd8EsMTmF3DChhqPQBnU/<0;1>/*)): Expression with a non KP key present
+* sh(multi(1,@0/**,xpub6AHA9hZDN11k2ijHMeS5QqHx2KP9aMBRhTDqANMnwVtdyw2TDYRmF8PjpvwUFcL1Et8Hj59S3gTSMcUQ5gAqTz3Wd8EsMTmF3DChhqPQBnU/<0;1>/*)): Expression with a non-KP key present
* pkh(@0/<0;1;2>/*): Solved cardinality > 2
-Remark: some of the descriptor templates above might be valid if optional extensions allowing them are added in the implementation.
+Remark: some of the examples of invalid descriptor templates may be valid via optional extensions.
== Backwards Compatibility ==
From 7d0c08e38acac3ef14095d0e8664c7332b7be381 Mon Sep 17 00:00:00 2001
From: Salvatore Ingala <6681844+bigspider@users.noreply.github.com>
Date: Tue, 7 May 2024 22:24:23 +0200
Subject: [PATCH 12/20] More nits from PR review
---
bip-0388.mediawiki | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/bip-0388.mediawiki b/bip-0388.mediawiki
index d7ed0bec..4efc5881 100644
--- a/bip-0388.mediawiki
+++ b/bip-0388.mediawiki
@@ -14,7 +14,7 @@
== Abstract ==
-Wallet policies build on top of output 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.
+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.
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.
@@ -101,7 +101,7 @@ In fact, there are many reasonable spending policies with a quadratic size in th
With each xpub being 118 bytes long, the repetition of xpubs makes the descriptor become extremely large.
-Replacing the common part of the key with a short key placeholder and moving the key expression separately helps to keep the size of the wallet policy small, which is crucial to allow human inspection during the registration flow.
+Replacing the common part of the key with a short key placeholder and organizing all the key expressions in a separate list helps to keep the size of the wallet policy small, which is crucial to allow human inspection during the registration flow.
== Specification ==
@@ -146,7 +146,7 @@ The placeholder @i for some number ''i'' represents the ''i''-th key in
Note: while descriptor templates for miniscript are not formally defined in this version of the document (pending standardization), it is straightforward to adapt this approach by adding additional SCRIPT expressions.
-==== Keys information vector ====
+==== Key information vector ====
Each element of the key origin information vector is a KEY expression.
@@ -161,7 +161,7 @@ Each element of the key origin information vector is a KEY expression.
A wallet policy must have at least one key placeholder and the corresponding key.
-The public keys obtained by deserializing elements of the keys information vector must be pairwise distinct['''Why must public keys be distinct?''' Reusing pubkeys could be insecure in the context of wallet policies containing [https://bitcoin.sipa.be/miniscript/ miniscript]. Avoiding repeated public keys altogether avoids the problem at the source.].
+The public keys obtained by deserializing elements of the key information vector must be pairwise distinct['''Why must public keys be distinct?''' Reusing pubkeys could be insecure in the context of wallet policies containing [https://bitcoin.sipa.be/miniscript/ miniscript]. Avoiding repeated public keys altogether avoids the problem at the source.].
If two key placeholders are @i//* and @i//* for the same index i, then the sets {M, N} and {P, Q} must be disjoint.
@@ -197,7 +197,7 @@ In order to allow supporting legacy derivation schemes (for example, using simpl
However, care needs to be taken in view of the following considerations:
-* Allowing derivation schemes with a different length or cardinality in the same wallet policy would make it difficult to guarantee that there are no repeated pubkeys for every possible address generated by the policy. For example, `@0/<0;1>/*` and `@1/*` would generate the same pubkeys if the second public key in the keys information vector is one of the first two unhardened children of the first public key. This could cause malleability with potential security implications (for example, in policies containing miniscript).
+* Allowing derivation schemes with a different length or cardinality in the same wallet policy would make it difficult to guarantee that there are no repeated pubkeys for every possible address generated by the policy. For example, `@0/<0;1>/*` and `@1/*` would generate the same pubkeys if the second public key in the key information vector is one of the first two unhardened children of the first public key. This could cause malleability with potential security implications (for example, in policies containing miniscript).
* Allowing naked pubkeys with no /* suffix (for example a descriptor template like wsh(multi(2,@0,@1/<0;1>/*))) would cause a pubkey to be repeated in every output generated from the policy, which would result in a total loss of privacy.
== Examples ==
@@ -281,7 +281,7 @@ Remark: some of the examples of invalid descriptor templates may be valid via op
== Backwards Compatibility ==
-The @ character used for key placeholders is not part of the syntax of output script descriptors, therefore any valid output descriptor with at least one `KEY` expression is not a valid descriptor template. Vice versa, any descriptor template with at least one key placeholder is not a valid output script descriptor.
+The @ character used for key placeholders is not part of the syntax of output script descriptors, therefore any valid descriptor with at least one `KEY` expression is not a valid descriptor template. Vice versa, any descriptor template with at least one key placeholder is not a valid output script descriptor.
Adoption of wallet policies in software and hardware wallets is opt-in. Conversion from wallet policies to the corresponding descriptors is programmatically extremely easy, and conversion from descriptors to wallet policies (when respecting the required patterns) can be automated. See the reference implementation below for some examples of conversion.
From 96f4e5a4c4cd2e5ba4e74212077b858a3b047f31 Mon Sep 17 00:00:00 2001
From: josibake
Date: Mon, 15 Jan 2024 12:23:22 +0100
Subject: [PATCH 13/20] Add BIP for Silent Payments
Co-Authored-By: Ruben Somsen
---
bip-0352.mediawiki | 437 ++++++++++++++++++++
bip-0352/scan_data_downloader_per_month.png | Bin 0 -> 54276 bytes
2 files changed, 437 insertions(+)
create mode 100644 bip-0352.mediawiki
create mode 100644 bip-0352/scan_data_downloader_per_month.png
diff --git a/bip-0352.mediawiki b/bip-0352.mediawiki
new file mode 100644
index 00000000..2f8f767b
--- /dev/null
+++ b/bip-0352.mediawiki
@@ -0,0 +1,437 @@
+
+ BIP: 352
+ Layer: Applications
+ Title: Silent Payments
+ Author: josibake
+ Ruben Somsen
+ Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0352
+ Status: Draft
+ Type: Standards Track
+ Created: 2023-03-09
+ License: BSD-2-Clause
+
+
+== Introduction ==
+
+=== Abstract ===
+
+This document specifies a protocol for static payment addresses in Bitcoin without on-chain linkability of payments or a need for on-chain notifications.
+
+=== Copyright ===
+
+This BIP is licensed under the BSD 2-clause license.
+
+=== Motivation ===
+
+Using a new address for each Bitcoin transaction is a crucial aspect of maintaining privacy. This often requires a secure interaction between sender and receiver so that the receiver can hand out a fresh address, a batch of fresh addresses, or a method for the sender to generate addresses on-demand, such as an xpub.
+
+However, interaction is often infeasible and in many cases undesirable. To solve for this, various protocols have been proposed which use a static payment address and notifications sent via the blockchain['''Why not use out-of-band notifications''' Out of band notifications (e.g. using something other than the Bitcoin blockchain) have been proposed as a way of addressing the privacy and cost concerns of using the Bitcoin blockchain as a messaging layer. This, however, simply moves the privacy and cost concerns somewhere else and increases the risk of losing money due to a notification not being reliably delivered, or even censored, and makes this notification data critical for backup to recover funds.]. These protocols eliminate the need for interaction, but at the expense of increased costs for one-time payments and a noticeable footprint in the blockchain, potentially revealing metadata about the sender and receiver. Notification schemes also allow the receiver to link all payments from the same sender, compromising sender privacy.
+
+This proposal aims to address the limitations of these current approaches by presenting a solution that eliminates the need for interaction, eliminates the need for notifications, and protects both sender and receiver privacy. These benefits come at the cost of requiring wallets to scan the blockchain in order to detect payments. This added requirement is generally feasible for full nodes but poses a challenge for light clients. While it is possible today to implement a privacy-preserving light client at the cost of increased bandwidth, light client support is considered an area of open research (see [[#appendix-a-light-client-support|Appendix A: Light Client Support]]).
+
+The design keeps collaborative transactions such as CoinJoins and inputs with MuSig and FROST keys in mind, but it is recommended that the keys of all inputs of a transaction belong to the same entity as there is no formal proof that the protocol is secure in a collaborative setting.
+
+== Goals ==
+
+We aim to present a protocol which satisfies the following properties:
+
+* No increase in the size or cost of transactions
+* Resulting transactions blend in with other bitcoin transactions and can't be distinguished
+* Transactions can't be linked to a silent payment address by an outside observer
+* No sender-receiver interaction required
+* No linking of multiple payments to the same sender
+* Each silent payment goes to a unique address, avoiding accidental address reuse
+* Supports payment labeling
+* Uses existing seed phrase or descriptor methods for backup and recovery
+* Separates scanning and spending responsibilities
+* Compatible with other spending protocols, such as CoinJoin
+* Light client/SPV wallet support
+* Protocol is upgradeable
+
+== Overview ==
+
+We first present an informal overview of the protocol. In what follows, uppercase letters represent public keys, lowercase letters represent private keys, ''||'' refers to byte concatenation, ''G'' represents the generator point for secp256k1, and ''n'' represents the curve order for secp256k1. Each section of the overview is incomplete on its own and is meant to build on the previous section in order to introduce and briefly explain each aspect of the protocol. For the full protocol specification, see [[#specification|Specification]].
+
+''' Simple case '''
+
+Bob publishes a public key ''B'' as a silent payment address. Alice discovers Bob's silent payment address, selects a UTXO with private key ''a'', public key ''A'' and creates a destination output ''P'' for Bob in the following manner:
+
+* Let ''P = B + hash(a·B)·G''
+* Encode ''P'' as a [https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki BIP341] taproot output
+
+Since ''a·B == b·A'' ([https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman Elliptic-curve Diffie–Hellman]), Bob scans with his private key ''b'' by collecting the input public keys for each transaction with at least one unspent taproot output and performing the ECDH calculation until ''P'' is found (i.e. calculating ''P = B + hash(b·A)·G'' and seeing that ''P'' is present in the transaction outputs).
+
+''' Creating more than one output '''
+
+In order to allow Alice to create more than one output for Bob['''Why allow for more than one output?''' Allowing Alice to break her payment to Bob into multiple amounts opens up a number of privacy improving techniques for Alice, making the transaction look like a CoinJoin or better hiding the change amount by splitting both the payment and change outputs into multiple amounts. It also allows for Alice and Carol to both have their own unique output paying Bob in the event they are in a collaborative transaction and both paying Bob's silent payment address.], we include an integer in the following manner:
+
+* Let ''k = 0''
+* Let ''P0 = B + hash(a·B || k)·G''
+* For additional outputs:
+** Increment ''k'' by one (''k++'')
+** Let ''Pi = B + hash(a·B || k)·G''
+
+Bob detects this output the same as before by searching for ''P0 = B + hash(b·A || 0)·G''. Once he detects the first output, he must:
+
+* Check for ''P1 = B + hash(b·A || 1)·G''
+* If ''P1'' is not found, stop
+* If ''P1'' is found, continue to check for ''P2'' and so on until an additional output is not found
+
+Since Bob will only perform these subsequent checks after a transaction with at least one output paying him is found, the increase to his overall scanning requirement is negligible. It should also be noted that the order in which these outputs appear in the transaction does not affect the outcome.
+
+''' Preventing address reuse '''
+
+If Alice were to use a different UTXO from the same public key ''A'' for a subsequent payment to Bob, she would end up deriving the same destinations ''Pi''. To prevent this, Alice should include an input hash in the following manner:
+
+* Let ''input_hash = hash(outpoint || A)''['''Why include A in the input hash calculation?''' By committing to A in input hash, this ensures that the sender cannot maliciously choose a private key ''a′'' in a subsequent transaction where ''a′ = input_hash·a / input_hash′'', which would force address reuse in the protocol.]
+* Let ''P0 = B + hash(input_hash·a·B || 0)·G''
+
+Bob must calculate the same ''input_hash'' when scanning.
+
+''' Using all inputs '''
+
+In our simplified example we have been referring to Alice's transactions as having only one input ''A'', but in reality a Bitcoin transaction can have many inputs. Instead of requiring Alice to pick a particular input and requiring Bob to check each input separately, we can instead require Alice to perform the tweak with the sum of the input public keys['''What about inputs without public keys?''' Inputs without public keys can still be spent in the transaction but are simply ignored in the silent payments protocol.]. This significantly reduces Bob's scanning requirement, makes light client support more feasible['''How does using all inputs help light clients?''' If Alice uses a random input for the tweak, Bob necessarily has to have access to and check all transaction inputs, which requires performing an ECC multiplication per input. If instead Alice performs the tweak with the sum of the input public keys, Bob only needs the summed 33 byte public key per transaction and only does one ECC multiplication per transaction. Bob can then use BIP158 block filters to determine if any of the outputs exist in a block and thus avoids downloading transactions which don't belong to him. It is still an open question as to how Bob can source the 33 bytes per transaction in a trustless manner, see [[#appendix-a-light-client-support|Appendix A: Light Client Support]] for more details.], and protects Alice's privacy in collaborative transaction protocols such as CoinJoin['''Why does using all inputs matter for CoinJoin?''' If Alice uses a random input to create the output for Bob, this necessarily reveals to Bob which input Alice has control of. If Alice is paying Bob as part of a CoinJoin, this would reveal which input belongs to her, degrading the anonymity set of the CoinJoin and giving Bob more information about Alice. If instead all inputs are used, Bob has no way of knowing which input(s) belong to Alice. This comes at the cost of increased complexity as the CoinJoin participants now need to coordinate to create the silent payment output and would need to use [https://gist.github.com/RubenSomsen/be7a4760dd4596d06963d67baf140406 Blind Diffie–Hellman] to prevent the other participants from learning who Alice is paying. Note it is currently not recommended to use this protocol for CoinJoins due to a lack of a formal security proof.].
+
+Alice performs the tweak with the sum of her input private keys in the following manner:
+
+* Let ''A = A1 + A2 + ... + An''
+* Let ''input_hash = hash(outpointL || A)'', where ''outpointL'' is the smallest outpoint lexicographically['''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.]
+* Let ''a = a1 + a2 + ... + an''
+* Let ''P0 = B + hash(input_hash·a·B || 0)·G''
+
+''' Spend and Scan Key '''
+
+Since Bob needs his private key ''b'' to check for incoming payments, this requires ''b'' to be exposed to an online device. To minimize the risks involved, Bob can instead publish an address of the form ''(Bscan, Bspend)''. This allows Bob to keep ''bspend'' in offline cold storage and perform the scanning with the public key ''Bspend'' and private key ''bscan''. Alice performs the tweak using both of Bob's public keys in the following manner:
+
+* Let ''P0 = Bspend + hash(input_hash·a·Bscan || 0)·G''
+
+Bob detects this payment by calculating ''P0 = Bspend + hash(input_hash·bscan·A || 0)·G'' with his online device and can spend from his cold storage signing device using ''(bspend + hash(input_hash·bscan·A || 0)) mod n'' as the private key.
+
+''' Labels '''
+
+For a single silent payment address of the form ''(Bscan, Bspend)'', Bob may wish to differentiate incoming payments. Naively, Bob could publish multiple silent payment addresses, but this would require him to scan for each one, which becomes prohibitively expensive. Instead, Bob can label his spend public key ''Bspend'' with an integer ''m'' in the following way:
+
+* Let ''Bm = Bspend + hash(bscan || m)·G'' where m is an incrementable integer starting from 1
+* Publish ''(Bscan, B1)'', ''(Bscan, B2)'' etc.
+
+Alice performs the tweak as before using one of the published ''(Bscan, Bm)'' pairs. Bob detects the labeled payment in the following manner:
+
+* Let ''P0 = Bspend + hash(input_hash·bscan·A || 0)·G''
+* Subtract ''P0'' from each of the transaction outputs and check if the remainder matches any of the labels (''hash(bscan || 1)·G'', ''hash(bscan || 2)·G'' etc.) that the wallet has previously used
+
+It is important to note that an outside observer can easily deduce that each published ''(Bscan, Bm)'' pair is owned by the same entity as each published address will have ''Bscan'' in common. As such, labels are not meant as a way for Bob to manage separate identities, but rather a way for Bob to determine the source of an incoming payment.
+
+''' Labels for change '''
+
+Bob can also use labels for managing his own change outputs. We reserve ''m = 0'' for this use case. This gives Bob an alternative to using BIP32 for managing change, while still allowing him to know which of his unspent outputs were change when recovering his wallet from the master key. It is important that the wallet never hands out the label with ''m = 0'' in order to ensure nobody else can create payments that are wrongly labeled as change.
+
+While the use of labels is optional, every receiving silent payments wallet should at least scan for the change label when recovering from backup in order to ensure maximum cross-compatibility.
+
+== Specification ==
+
+We use the following functions and conventions:
+
+* ''outpoint'' (36 bytes): the COutPoint of an input (32-byte txid, least significant byte first || 4-byte vout, least significant byte first)['''Why are outpoints little-endian?''' Despite using big endian throughout the rest of the BIP, outpoints are sorted and hashed matching their transaction serialization, which is little-endian. This allows a wallet to parse a serialized transaction for use in silent payments without needing to re-order the bytes when computing the input hash. Note: despite outpoints being stored and serialized as little-endian, the transaction hash (txid) is always displayed as big-endian.]
+* ser32(i): serializes a 32-bit unsigned integer ''i'' as a 4-byte sequence, most significant byte first.
+* ser256(p): serializes the integer p as a 32-byte sequence, most significant byte first.
+* serP(P): serializes the coordinate pair P = (x,y) as a byte sequence using SEC1's compressed form: (0x02 or 0x03) || ser256(x), where the header byte depends on the parity of the omitted Y coordinate.
+
+For everything not defined above, we use the notation from [https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki#specification BIP340]. This includes the ''hashtag(x)'' notation to refer to ''SHA256(SHA256(tag) || SHA256(tag) || x)''.
+
+=== Versions ===
+
+This document defines version 0 (''sp1q''). Version is communicated through the address in the same way as Segwit addresses. Future upgrades to silent payments will require a new version. As much as possible, future upgrades should support receiving from older wallets (e.g. a silent payments v0 wallet can send to both v0 and v1 addresses). Any changes that break compatibility with older silent payment versions should be a new BIP.
+
+Future silent payments versions will use the following scheme:
+
+{| class="wikitable"
+|-
+!
+!0
+!1
+!2
+!3
+!4
+!5
+!6
+!7
+!Compatibility
+|-
+!+0
+|q||p||z||r||y||9||x||8||rowspan="4" | backwards compatible
+|-
+!+8
+|g||f||2||t||v||d||w||0
+|-
+!+16
+|s||3||j||n||5||4||k||h
+|-
+!+24
+|c||e||6||m||u||a||7|| -
+|}
+
+''v31'' (l) is reserved for a backwards incompatible change, if needed. For silent payments v0:
+
+* If the receiver's silent payment address version is:
+** ''v0'': check that the data part is exactly 66-bytes. Otherwise, fail
+** ''v1'' through ''v30'': read the first 66-bytes of the data part and discard the remaining bytes
+** ''v31'': fail
+* Receiver addresses are always [https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki BIP341] taproot outputs['''Why only taproot outputs?''' Providing too much optionality for the protocol makes it difficult to implement and can be at odds with the goal of providing the best privacy. Limiting to taproot outputs helps simplify the implementation significantly while also putting users in the best eventual anonymity set.]
+* The sender should sign with one of the sighash flags ''DEFAULT'', ''ALL'', ''SINGLE'', ''NONE'' (''ANYONECANPAY'' is unsafe). It is strongly recommended implementations use ''SIGHASH_ALL'' (''SIGHASH_DEFAULT'' for taproot inputs) when possible['''Why is it unsafe to use ''SIGHASH_ANYONECANPAY''?''' Since the output address for the receiver is derived from the sum of the [[#inputs-for-shared-secret-derivation|Inputs For Shared Secret Derivation]] public keys, the inputs must not change once the sender has signed the transaction. If the inputs are allowed to change after the fact, the receiver will not be able to calculate the shared secret needed to find and spend the output. It is currently an open question on how a future version of silent payments could be made to work with new sighash flags such as ''SIGHASH_GROUP'' and ''SIGHASH_ANYPREVOUT''.]
+* Inputs used to derive the shared secret are from the ''[[#inputs-for-shared-secret-derivation|Inputs For Shared Secret Derivation]]'' list
+
+=== Scanning silent payment eligible transactions ===
+
+For silent payments v0 a transaction MUST be scanned if and only if all of the following are true:
+
+* The transaction contains at least one BIP341 taproot output (note: spent transactions optionally can be skipped by only considering transactions with at least one unspent taproot output)
+* The transaction has at least one input from the ''[[#inputs-for-shared-secret-derivation|Inputs For Shared Secret Derivation]]'' list
+* The transaction does not spend an output with SegWit version > 1['''Why skip transactions that spend SegWit version > 1?''' Skipping transactions that spend unknown output scripts allows us to have a clean upgrade path for silent payments by avoiding the need to scan the same transaction multiple times with different rule sets. If a new SegWit version is added in the future and silent payments v1 is released with support, we would want to avoid having to first scan the transaction with the silent payment v0 rules and then again with the silent payment v1 rules. Note: this restriction only applies to the inputs of a transaction.]
+
+=== Address encoding ===
+
+A silent payment address is constructed in the following manner:
+
+* Let ''Bscan, bscan = Receiver's scan public key and corresponding private key''
+* Let ''Bspend, bspend = Receiver's spend public key and corresponding private key''
+* Let ''Bm = Bspend + hashBIP0352/Label(ser256(bscan) || ser32(m))·G'', where ''hashBIP0352/Label(ser256(bscan) || ser32(m))·G'' is an optional integer tweak for labeling
+** If no label is applied then ''Bm = Bspend''
+* The final address is a [https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki Bech32m] encoding of:
+** The human-readable part "sp" for mainnet, "tsp" for testnets (e.g. signet, testnet)
+** The data-part values:
+*** The character "q", to represent a silent payment address of version 0
+*** The 66 byte concatenation of the receiver's public keys, ''serP(Bscan) || serP(Bm)''
+
+Note: [https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki BIP173] imposes a 90 character limit for Bech32 segwit addresses and limits versions to 0 through 16, whereas a silent payment address requires ''at least'' 117 characters[ ''' Why do silent payment addresses need at least 117 characters?''' A silent payment address is a bech32m encoding comprised of the following parts:
+
+
+* HRP [2-3 characters]
+* separator [1 character]
+* version [1-2 characters]
+* payload, 66 bytes concatenated pubkeys [ceil(66*8/5) = 106 characters]
+* checksum [6 characters]
+
+
+For a silent payments v0 address, this results in a 117 character address when using a 3 character HRP. Future versions of silent payment addresses may add to the payload, which is why a 1023 character limit is suggested.] and allows versions up to 31. Additionally, since higher versions may add to the data field, it is recommended implementations use a limit of 1023 characters (see [https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#checksum-design BIP173: Checksum design] for more details).
+
+=== Inputs For Shared Secret Derivation ===
+
+While any UTXO with known output scripts can be used to fund the transaction, the sender and receiver MUST use inputs from the following list when deriving the shared secret:
+
+* ''P2TR''
+* ''P2WPKH''
+* ''P2SH-P2WPKH''
+* ''P2PKH''
+
+Inputs with conditional branches or multiple public keys (e.g. ''CHECKMULTISIG'') are excluded from shared secret derivation as this introduces malleability and would allow a sender to re-sign with a different set of public keys after the silent payment output has been derived. This is not a concern when the sender controls all of the inputs, but is an issue for CoinJoins and other collaborative protocols, where a malicious participant can participate in deriving the silent payment address with one set of keys and then re-broadcast the transaction with signatures for a different set of public keys. P2TR can have hidden conditional branches (script path), but we work around this by using only the output public key.
+
+For all of the output types listed, only X-only and compressed public keys are permitted[''' Why only compressed public keys ''' Uncompressed and hybrid public keys are less common than compressed keys and generally considered to be a bad idea due to their blockspace inefficiency. Additionally, [https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki#restrictions-on-public-key-type BIP143] recommends restricting P2WPKH inputs to compressed keys as a default policy.].
+
+''' P2TR '''
+
+'' Keypath spend ''
+
+ witness:
+ scriptSig: (empty)
+ scriptPubKey: 1 <32-byte-x-only-key>
+ (0x5120{32-byte-x-only-key})
+
+The sender uses the private key corresponding to the taproot output key (i.e. the tweaked private key). This can be a single private key or an aggregate key (e.g. taproot outputs using MuSig or FROST)['''Are key aggregation techniques like FROST and MuSig supported?''' While we do not recommend it due to lack of a security proof (except if all participants are trusted or are the same entity), any taproot output able to do a key path theoretically is supported. Any offline key aggregation technique can be used, such as FROST or MuSig. This would require participants to perform the ECDH step collaboratively e.g. ''ECDH = a1·Bscan + a2·Bscan + ... + at·Bscan'' and ''P = Bspend + hash(input_hash·ECDH || 0)·G''. Additionally, it may be necessary for the participants to provide a DLEQ proof to ensure they are not acting maliciously.]. The receiver obtains the public key from the ''scriptPubKey'' (i.e. the taproot output key).
+
+'' Script path spend ''
+
+ witness:
+ scriptSig: (empty)
+ scriptPubKey: 1 <32-byte-x-only-key>
+ (0x5120{32-byte-x-only-key})
+
+Same as a keypath spend, the sender MUST use the private key corresponding to the taproot output key. If this key is not available, the output cannot be included as an input to the transaction. Same as a keypath spend, the receiver obtains the public key from the ''scriptPubKey'' (i.e. the taproot output key)[''' Why not skip all taproot script path spends? ''' This causes malleability issues for CoinJoins. If the silent payments protocol skipped taproot script path spends, this would allow an attacker to join a CoinJoin round, participate in deriving the silent payment address using the tweaked private key for a key path spend, and then broadcast their own version of the transaction using the script path spend. If the receiver were to only consider key path spends, they would skip the attacker's script path spend input when deriving the shared secret and not be able to find the funds. Additionally, there may be scenarios where the sender can perform ECDH with the key path private key but spends the output using the script path.].
+
+The one exception is script path spends that use NUMS point ''H'' as their internal key (where ''H'' is constructed by taking the hash of the standard uncompressed encoding of the secp256k1 base point ''G'' as X coordinate, see [https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#constructing-and-spending-taproot-outputs BIP341: Constructing and spending Taproot outputs] for more details), in which case the input will be skipped for the purposes of shared secret derivation['''Why skip outputs with H as the internal taproot key?''' If use cases get popularized where the taproot key path cannot be used, these outputs can still be included without getting in the way of making a silent payment, provided they specifically use H as their internal taproot key.]. The receiver determines whether or not to skip the input by checking in the control block if the taproot internal key is equal to ''H''.
+
+''' P2WPKH '''
+
+ witness: <33-byte-compressed-key>
+ scriptSig: (empty)
+ scriptPubKey: 0 <20-byte-key-hash>
+ (0x0014{20-byte-key-hash})
+
+The sender performs the tweak using the private key for the output and the receiver obtains the public key as the last witness item.
+
+''' P2SH-P2WPKH '''
+
+ witness: <33-byte-compressed-key>
+ scriptSig: <0 <20-byte-key-hash>>
+ (0x160014{20-byte-key-hash})
+ scriptPubKey: HASH160 <20-byte-script-hash> EQUAL
+ (0xA914{20-byte-script-hash}87)
+
+The sender performs the tweak using the private key for the nested ''P2WPKH'' output and the receiver obtains the public key as the last witness item.
+
+''' P2PKH '''
+
+ scriptSig: <33-byte-compressed-key>
+ scriptPubKey: OP_DUP HASH160 <20-byte-key-hash> OP_EQUALVERIFY OP_CHECKSIG
+ (0x76A914{20-byte-key-hash}88AC)
+
+The receiver obtains the public key from the ''scriptSig''. The receiver MUST parse the ''scriptSig'' for the public key, even if the ''scriptSig'' does not match the template specified (e.g. OP_DROP ). This is to address the [https://en.bitcoin.it/wiki/Transaction_malleability third-party malleability of ''P2PKH'' ''scriptSigs''].
+
+=== Input hash ===
+
+The sender and receiver MUST calculate an input hash for the transaction in the following manner:
+
+* Let ''A = A1 + A2 + ... + An'', where each ''Ai'' is the public key of an input from the ''[[#inputs-for-shared-secret-derivation|Inputs For Shared Secret Derivation]]'' list['''Why do taproot private keys need to be checked?''' Recall from [https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki BIP340] that each X-only public key has two corresponding private keys, ''d'' and ''n - d''. To maintain parity between sender and receiver, it is necessary to use the private key corresponding to the even Y coordinate when performing the ECDH step since the receiver will assume the even Y coordinate when summing the taproot X-only public keys.]
+* Let ''a = a1 + a2 + ... + an'', where each ''ai'' has been negated if necessary
+* Group receiver silent payment addresses by ''Bscan'' (e.g. each group consists of one ''Bscan'' and one or more ''Bm'')
+* For each group:
+** Let ''ecdh_shared_secret = input_hash·a·Bscan''
+** Let ''k = 0''
+** For each ''Bm'' in the group:
+*** Let ''tk = hashBIP0352/SharedSecret(serP(ecdh_shared_secret) || ser32(k))''
+**** If ''tk'' is not valid tweak, i.e., if ''tk = 0'' or ''tk'' is larger or equal to the secp256k1 group order, fail
+*** Let ''Pmn = Bm + tk·G''
+*** Encode ''Pmn'' as a [https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki BIP341] taproot output
+*** Optionally, repeat with k++ to create additional outputs for the current ''Bm''
+*** If no additional outputs are required, continue to the next ''Bm'' with ''k++''[''' Why not re-use ''tk'' when paying different labels to the same receiver?''' If paying the same entity but to two separate labeled addresses in the same transaction without incrementing ''k'', an outside observer could subtract the two output values and observe that this value is the same as the difference between two published silent payment addresses and learn who the recipient is.]
+** Optionally, if the sending wallet implements receiving silent payments, it can create change outputs by sending to its own silent payment address using label ''m = 0'', following the steps above
+
+=== Receiver ===
+
+==== Key Derivation ====
+
+Two keys are needed to create a silent payments address: the spend key and the scan key. To ensure compatibility, wallets MAY use BIP32 derivation with the following derivation paths for the spend and scan key. When using BIP32 derivation, wallet software MUST use hardened derivation['''Why use BIP32 hardened derivation?''' Using BIP32 derivation allows users to add silent payments to an existing master seed. It also ensures that a user's silent payment funds are recoverable in any BIP32/BIP43 compatible wallet. Using hardened derivation ensures that it is safe to export the scan private key without exposing the master key or spend private key.] for both the spend and scan key.
+
+A scan and spend key pair using BIP32 derivation are defined (taking inspiration from [https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki BIP44]) in the following manner:
+
+ scan_private_key: m / purpose' / coin_type' / account' / 1' / 0
+ spend_private_key: m / purpose' / coin_type' / account' / 0' / 0
+
+purpose is a constant set to ''352'' following the BIP43 recommendation. Refer to [https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki BIP43] and [https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki BIP44] for more details.
+
+==== Scanning ====
+
+If each of the checks in ''[[#scanning-silent-payment-eligible-transactions|Scanning silent payment eligible transactions]]'' passes, the receiving wallet must:
+
+* Generate the ''input_hash'' with the smallest outpoint lexicographically, using the method described above
+* Let ''A = A1 + A2 + ... + An'', where each ''Ai'' is the public key of an input from the ''[[#inputs-for-shared-secret-derivation|Inputs For Shared Secret Derivation]]'' list
+* Let ''ecdh_shared_secret = input_hash·bscan·A''
+* Check for outputs:
+** Let ''outputs_to_check'' be the taproot output keys from all taproot outputs in the transaction (spent and unspent).
+** Starting with ''k = 0'':
+*** Let ''tk = hashBIP0352/SharedSecret(serP(ecdh_shared_secret) || ser32(k))''
+**** If ''tk'' is not valid tweak, i.e., if ''tk = 0'' or ''tk'' is larger or equal to the secp256k1 group order, fail
+*** Compute ''Pk = Bspend + tk·G''
+*** For each ''output'' in ''outputs_to_check'':
+**** If ''Pk'' equals ''output'':
+***** Add ''Pk'' to the wallet
+***** Remove ''output'' from ''outputs_to_check'' and rescan ''outputs_to_check'' with ''k++''
+**** Else, check for labels (always check for the change label, i.e. ''hashBIP0352/Label(ser256(bscan) || ser32(m))'' where ''m = 0'')[''' Why precompute labels?''' Precomputing the labels is not strictly necessary: a wallet could track the max number of labels it has used (call it ''M'') and scan for labels by adding ''hash(bscan || m)·G'' to ''P0'' for each label ''m'' up to ''M'' and comparing to the transaction outputs. This is more performant than precomputing the labels and checking via subtraction in cases where the number of eligible outputs exceeds the number of labels in use. In practice this will mainly apply to users that choose never to use labels, or users that use a single label for generating silent payment change outputs. If using a large number of labels, the wallet would need to add all possible labels to each output. This ends up being ''n·M'' additions, where ''n'' is the number of outputs in the transaction and ''M'' is the number of labels in the wallet. By precomputing the labels, the wallet only needs to compute ''hash(bscan || m)·G'' once when creating the labeled address and can determine if a label was used via a lookup, rather than adding each label to each output.]:
+***** Compute ''label = output - Pk''
+***** Check if ''label'' exists in the list of labels used by the wallet
+***** If a match is found:
+****** Add ''Pk + label'' to the wallet
+****** Remove ''output'' from ''outputs_to_check'' and rescan ''outputs_to_check'' with ''k++''
+***** If a label is not found, negate ''output'' and check a second time[''' Why negate the output?''' Unfortunately taproot outputs are X-only, meaning we don't know what the correct Y coordinate is. This causes this specific calculation to fail 50% of the time, so we need to repeat it with the other Y coordinate by negating the output.]
+*** If no matches are found, stop
+
+==== Spending ====
+
+Recall that a silent payment output is of the form ''Bspend + tk·G + hashBIP0352/Label(ser256(bscan) || ser32(m))·G'', where ''hashBIP0352/Label(ser256(bscan) || ser32(m))·G'' is an optional label. To spend a silent payment output:
+
+* Let ''d = (bspend + tk + hashBIP0352/Label(ser256(bscan) || ser32(m))) mod n'', where ''hashBIP0352/Label(ser256(bscan) || ser32(m))'' is the optional label
+* Spend the [https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki BIP341] output with the private key ''d''
+
+==== Backup and Recovery ====
+
+Since each silent payment output address is derived independently, regular backups are recommended. When recovering from a backup, the wallet will need to scan since the last backup to detect new payments.
+
+If using a seed/seed phrase only style backup, the user can recover the wallet's unspent outputs from the UTXO set (i.e. only scanning transactions with at least one unspent taproot output) and can recover the full wallet history by scanning the blockchain starting from the wallet birthday. If a wallet uses labels, this information SHOULD be included in the backup. If the user does not know whether labels were used, it is strongly recommended they always precompute and check a large number of labels (e.g. 100k labels) to use when re-scanning. This ensures that the wallet can recover all funds from only a seed/seed phrase backup. The change label should simply always be scanned for, even when no other labels were used. This ensures the use of a change label is not critical for backups and maximizes cross-compatibility.
+
+== Backward Compatibility ==
+
+Silent payments introduces a new address format and protocol for sending and as such is not compatible with older wallet software or wallets which have not implemented the silent payments protocol.
+
+=== Functional tests ===
+
+Below is a list of functional tests which should be included in sending and receiving implementations.
+
+==== Sending ====
+
+* Ensure taproot outputs are excluded during coin selection if the sender does not have access to the key path private key (unless using ''H'' as the taproot internal key)
+* Ensure the silent payment address is re-derived if inputs are added or removed during RBF
+
+==== Receiving ====
+
+* Ensure the public key can be extracted from non-standard ''P2PKH'' scriptSigs
+* Ensure taproot script path spends are included, using the taproot output key (unless ''H'' is used as the taproot internal key)
+* Ensure the scanner can extract the public key from each of the input types supported (e.g. ''P2WPKH'', ''P2SH-P2WPKH'', etc.)
+
+== Appendix A: Light Client Support ==
+
+This section proposes a few ideas for how light clients could support scanning for incoming silent payments (sending is fairly straightforward) in ways that preserve bandwidth and privacy. While this is out of scope for the current BIP, it is included to motivate further research into this topic. In this context, a light client refers to any bitcoin wallet client which does not process blocks and does not have a direct connection to a node which does process blocks (e.g. a full node). Based on this definition, clients that directly connect to a personal electrum server or a bitcoin node are not light clients.
+
+This distinction makes the problem for light clients more clear: light clients need a way to source the necessary data for performing the tweaks and a way of determining if any of the generated outputs exist in a block.
+
+=== Tweak Data ===
+
+Recall that a silent payment eligible transaction follows [[#scanning-silent-payment-eligible-transactions|certain conditions]] and should have at least one unspent taproot output. Full nodes (or any index server backed by a full node, such as electrum server) can build an index which collects all of the eligible public keys for a silent payments eligible transaction, sums them up, multiplies the sum by the ''input_hash'', and serves them to clients. This would be 33 bytes per silent payment eligible transaction.
+
+For a typical bitcoin block of ~3500 txs, lets assume every transaction is a silent payments eligible transaction. This means a client would need to request ''33 bytes * 3500'' of data per block (roughly 100 kB per block). If a client were to request data for every block, this would amount to ~450 MB per month, assuming 100% taproot usage and all outputs remain unspent for > 1 month. As of today, these numbers are closer to 2–10 kB per block (10–50 MB per month)[''' Data for Appendix A ''' These numbers are based on data from January 2023 until June 2023 (the last 6 months of data at time time of writing). See [https://github.com/josibake/bitcoin-data-analysis/blob/main/notebooks/silent-payments-light-client-data.ipynb Silent payments light client data] for the full analysis.].
+
+=== Transaction cut-through ===
+
+It is unlikely a light client would need to scan every block and as such can take advantage of transaction cut-through, depending on how often they choose to scan for new blocks. Empirically, ~75% of transactions with at least one unspent taproot output will have spent all taproot UTXOs in 326 blocks or less}E(5gihb!8@11jU00wDY95
zU%88A!XTb5k5)Cc5fpebjX*AP&eSmAAOdC*)YQ`3OJ&x8B+_E73}MYTFOwF!$tR9Z
z_#=RRR}-Bxv&!#|i&fF4El@7KSBhH<=>4@|Y5{0*d}p%wFWI05Z{PV>h&!cV0&z|3xmn
zG>qvA|7guMM{Pr7pFuYd*fW$%A4K|To0*vbmYvENnAb)Xt?mz28}_CEt4tCS5+>c|
zI4~zjvo0?M;-wQ@@S1Yzfh{0xE=jh^Yl^-kot3=9
zRQKec-nc+!FCTs2FDc8JCb=>k5QBvFhp9me3vv~`Qrm4}bBP)5F0JcPUI)lWA9Tr#
z-N@vPyr^-raE0~u&R;ALYk-^C1WuW7_h&GI(tZvYFIf=a8!!$WvZH)pZ~gdy<9WU9
zViJgfb(WK~KsU3eU`ItsX~*(3HX?$WlQRKmNI2dd>w>QqRBG$30ITu5Ux2*f^tkND*AQ^G-CW8|2;kf?6W7VI@bP8cl;S<3=c$pR*CFAH`ha
ziuei$#=!{zs#CaKYKfXL_*w>Xiq$8^d%f$0<>f5EEuFd2g(KHMDM|bMIWV-?)$Y^M
z`cEH3Cuy8NO)}@fnGV9yyq6%+#{8dVAnDCqxWWaA1mHSza!POG&GzZGWSV3}VhV_=
zy%ppWec=`Lgu;#7v@AGCA!HvBn%O>aUARS`2*II0*OfehA1`xy_F7SD>?bD|47pGn
zr_!Q_lVe()UlflzlC`vZ>)
zE;uIn<5}ySpRs(_SHl(VWpMK(;O6zcj<|p=%>YP-Du9g)s9&5_K+oIG#|L+@1&ka{
zAinwqTui|e)PTG0xc~E88)+8!jsm9jB&n?zm~sM3FW>-`kbn<AqtidbN9XT$@`W{Qe&ZcAiXb=~x}soFplIOHP>uW|Tu@{A{g+N9N0y_1+1VF2}+Bh^F8g8*`0*3)buGKvw6@xXFzw;qV>k!QrjPRPz5oQ%Y`?>nDpr
zdpYHqBVkQtDfEOiquZjsIKFgBcq(1Yky)
zk{)S1&b1sXp8g_z{g`aayfS{llRoNhz~fK_W?k#52A~Mg`H&@|NuQ$vSsb@`o7c~l
zO@`w_YiC!h&Q%`XvcJx#h%Z&Vg-2X)#PexY>A*|Azq3REP)__9o4;f40?2WsaQUdZ+q
zEQS<3A84U+Y|&LptU<*8`?@ByI=H59`+>ij)aV5Qz)$3&q_yc9P9$0Gf1A>Qhzjr9
z->NKT%j*Ay=@st?C|cilQM>)(x;)F*eGBWs8@lFkrI79m&-)rMD*ZV+-T3Zaj1hIp
z6l@qPiT{nPEGkr}J*F_T5*llXwvTT;qOMd*bX8Mm%2?N2Xc567HO>Uk^yfb#ua(UR
z*>ZHykBNy5kK$Mq+Wcq;tUD39KAo|WuYc859{}>fL*BYDk(gn+&K`}T*}j*d=?fTi
zg7kB4ba;f~830`yNR=|z!OkdbKGZ!3z!BkD&wBv$F`eTp>p1J)@Fs)nGQPGvo)olC
z`q4ScR*RoFGKQIY#`SxDT&aRVpw>cA8Tc%M&+z%I?rFlSw2`W?`%TeG%R%n9J7(W;
z**;>8JSF4AA_-{4APK-Fir3MEeZ4ExaoL*(4S;(q|5#m+$j|YB*)PT`;u@`*nHs>I
z;l|ZApvZb;N8FYkIqySq=XXT_u030quoGy%!X$G3
zQbDCs(tgUgXo9u+l?Zafept}<_aL5$uU+s%342pHU3X`55b$8YL&NuM4nQ)b;~5~p
zEQERTw0hJ97b`@UC|iMI1XNSu>2*RU?@xfn@n|_^oI*?GdJsOL2>Syj6s{xBRZyI;
z&kjC`3@{EMKN)OeZjz4qGFq_DDezJBZ^sLT^186cx`No^wu?c~3OWFw8UvV|s7-#h
z()}ty4=FG%TEsSoqhwJi44_5l7(?FAckz5MIyxt-4@GMFW!-x&BwkK9v<07!cyD2V
zsmJ1ZFPq~b*9XC^H~6eO-w+#3j}W^iyED@lVsgsf7Deg%NzkaC;=K(A<6s812Fkf)
zIXlA;kCyBvj-TTQzxHuNonJ2csmW**BoF~_LN})-H+rQs=?Yqw!PsW>{e0l~Q8Nl|
z
zZmyIIevyQ+nvj2q
z^Mx4O?b9^9;qx+}`Vj7;K{b_yfQi4=aFpw+Mgg0VMfaDSJSetdg|({XzA#;`=_^-Qc^?=UmC3;qicKwCEU>TrJo?|R
zNvrI^WiESHP-kUM%D1zWYfZ3f2hKl?3Y*N^O7`zd8x;(uzIzh-K8V;^4Pl7N*6PH7
zQw(Z>m^b!NT3m{uRibR1LO)8)tx{M9kJywn(TXB!P`TsJc}13X1!tEm?Uv+Kd6Ag%3jT3~C1D}ao*{3$FYgXdP}vHP*6Q+XmS=u6$N0J@VQ5EF!c
zVe4f`X3Sr|cU4d`2iGUBWH^1Bo+t2sab`0LqQMcGSfel@L
zUC`}S@foxmO!7sP7IHIm_wz}7sdh2b$(vPML!CBoOwSAmtap1Fc^!y)|
z%7saw{ebM!yw=H!vM?CYlzGLdF%wMeodq*kcxa?EjH1oM8q6k*sFoij1_|=2uD~{ve_kTFsvWZwdR$gE
zDl-=4WDs@C`7h`E*ksNO$11y*Gq;w=ZcPT@S%6rqo&`?^vf%gU2WN~J+JxDf-75@b
zY>d+6Qx_PvLUH*??c=(pwe)|hfKtbyVdkyuqY{vx!T5`k_1tD3^dZ1(E*M!ugps-&
z;IC=YDeR1Rh4BvEv5XDo{tSkt#hgknJr-Qes5&YBM179*h8TGZuofO+aynmB#&0Mfnm&6TVC4;>UR%s|wUZa)
z?~iB0LwBDuS}GM-BiI6f4&&|mqufsn3$@PA6iHCn%;?_8rD$X!%pplbGNSZUHF
zX6f||)p38K|FOQbWPzvq8#;KCt0E#h{}EfXN(yfRbtfP`4J0k~q#=8mKSnAS2oUd#
z&n-0T()>4#Rg-`q@%P3B(d6sP=M!O_0+Yi&=^CO%+#SCTNEO3oqRpKq3tcwrt^eoNlYCb8_d{5F}U^yN#huHa1NBpIdtz*y@eDemPa5leN!aL9}@j
zoS7o0zodoyvb9InH#^5kTrD(6Z^C{V%3Ao5bGqK=09hM17-23J(xb^tqG`4WRmel#
zvz5hkXZaqzwRE#|jja5hz*;~hn(c_Qk-BMxOWO%nJpc-yFyYx?(l4mF$nc~|7u3d&
z481z;n3K8a7OriY#_K3N22J{l#==_9cl-og#qsu}<+>OIJ|%2E`8;>pj1+$^G?bRA4SUL#7G~L6A4s&Ynb%
zL1M;Ho~XlIJ}Yox&HHYn_>devY^9$fWZU^B-k7nB<=@s$mbZvS2kZQE0Q(mv<_Q_l
znv^0t5GA(9!D?yImCB`fk3Vb_NavKwb-Qd(t3Q_*f0HB9L9p~`8o>Ce$z>TrHL-`b
zq=~2X?YS>wtpFUbaxWArU9nyf=DF|%Uon(pAc4i3sNU29@tI@C
zA32SSXc2g+JX2_Eviy@KVQ&cfDfgX&igYmM*S_TfF{6LIhN(}Y)Y`p`is?O))Y@Gu
za{L%HvWF}!x2ntGW^TR&ie<#>eEU7#%Dm)z+9%XV_LU^{wl|qv?IrBn<~c&mq<3o#
z^jkZH4<{ZraB%Hm9L?n0P0oEB)VBwvrqOQ?S2f68TjMHB?C}ixF%uZ9PkvLELQV63
zlo2KvF}TdV{jQC)2u=O^dQ4ZDumFOyPC0D*AyktUC0U_0k
z0nMH@Qa@_#*La}k*!kjPQdf?@BUvu__yFCiZqC
zeHPupS;_hNfj0A;=0)dw0v&ZQ=zAdJg;}*k6jqe(D&v8{S46M(gXQlKKM0KGNqy{V
z*nLROVqcoN?jz&lXK*UNe?+C2y{g}k7FbaE-?7&Gw|2&5_#rycxwA&!_|39N`y6gG
zxlrSI(z@sm0~f%WiEk}`FZA4>BUO)waqVJNwB*Q{6N4fpU(Q@;VjqK;0ErIeU?!Ku
zNu5FG2aCMNtl>hMZXFshdA>^9r2Uj
zHweJh(0U)RMB>?>H*_mf;1OI%5sy?M9!A?Am#jP=_)c{Y4f;EDo&AtRBc^f&>mV|d
zWnewI*UyRmgdXC{((#>?Es{RF@pTMfUZhi_YTONeV=&yh;G8)c$tmyo74@ZC7k@eM
zHNr$rwJ<$$CW9e+EGq?45X^{7y$9dbEr9_oF|6}et;+aot@y97*-rw^XvSiN9xV$3
zbDWIR+z5&Bwt{vqD>K+cf+ns{asXGsZe}n+kZYoalby%v(5ry>9fA-qf%qw!l;9Lm-OPOY&nyhcLZKY}qXa&0
zl3Dq@(u$;O(BF%1&2!?>290+OE@Nl?L3|=o(fUo*Leru-jN?^Go#~b
zo=hePCT{1!sS`hTNNrE+d45AWDgQ)eoa#dOIiuE-!pVNRHdYWm|L^VqdFyuFsPhrP0`X=akoP4UqXpZfSP1}~^RxJ3y=4om%w#U{r
z`8T2AKN%9_!vf-|9ptP_ZnBT|#YVd{zaQFexJ9Z#1CQruCyO;M*humuC>#P+`m0>6l(bT+4y;s8>uG0z=sc?<#f9D{7pv$7V#pt`+>0H9d}>$-_F=IB0D&H
zG^vCKdPllrFFYAxw25w30@PW#zaH&|Mzz~MzuczHM0sQQP0&Wa(&=XpK+ZJWkJrrm9`#+n
zmzqytaYrejCu=Z=z@BB3uPqzT?@iQy|lV*O8Y{Voo}Wr#<3iDuyi?L%
zTb;a0(Tjh`(f+BT)Y?3-TU7#^HymtU5B(mOX8E4ryn~j3cR{(TUMM_!!E#W1<>V|w
zKbY9X4&}D&AID!i=Y?uzQ^6jM{2@>VQ(}!Hc(oSj#~8XwhI8S<~d6a
zI?SzcoK2f;cRc&MVH!WJ>C1`y$(#2y9)*EFdnSv&r*E*YBc*5I|Mr&d`xg41`PS8i
zjpjxTvi_jW**Kk=Tb)W%{ok2msmy5(oNk*adx>^JsQ6oz0j-Lm&*Dpp^Mv5_aUWjc
zx4LJFN2K@r(
zNj9I=fW9;@IU=?pn&D@T8{~z%zMQKJdqwoVkFQX>M8aBC-f3iL+ShPS=Dbh1yp40O
z-2Cf=xB96@T*TngrOl~{j!Kc9q7{^1geq+)LVQvJ9X$JYLcU1WQPl%vw~+sGUMUmW
zy}1`79IGS>X=_V~?D_46)ibN^tNJ#^h|_3T$TZEH2j0l_?nDN^;A>97EgZ}}F=I~m
z?g7n~Wgp4*`iU{p0CA%8ik}-JrtRmRT?cN<(|141E_JMFTGhBs?Tl>~XqA)Az(-G;
zn{q&1(0cvuE7X{*X;@K-|1!<)=d0QLI=#13BfU1;ZYJu6Ow4e88S&X9w1unJ^vhYa
z(Q&_%41>d7*dqbCQ8W_LR1UVpS`I6-hv{F7XESrQq2c7d|!sbV1}*F
zj|(Mo+F1>qz_(5;vq+_mCUFy6_d1KfJz;HAn)$&Du{J4lMRiPSmPh9=ZGOIcXxrXf
zkyH-)!|_|Za;24TuyUc@QCd1>Qo2?Y7izZVA|--3QU&xeDy^`KRV(}`+Dv8`_uhN^
z`nzx&AeJ0U5Zo&G>-ZT0!Ld3CuSXTeyz))-VGyRZjJiEb4EWxfd|ceFgkig#r|Dd*m2D|rvL0`%p+l=Q&CzM%v`4`eWH
zQy63%*`5Vy_{r=q&Y~)34!a0qxiGU2uVc!O;dM!6-@|<)sWm`M`*pAo2nI`F?GdEd
zjE0pscq*sN$pa&ChoTQN#~w;%kQrJLI*t7L!7xSW_+*C_1a!wIm#j4WLniFsxcuEl
zo?4vX$u+;RPEW;McX}WBq1U5dGrjSH-u&<3CNjOljJ?Nm(O+`19yTw)EP~;wXjdB4
zI2r2OTa1_6h0v1lFVg2_-nGIxGR;Z2#el&BhWO^wpfrV((W^k6m8}AOPkc6^D3mgRojc0w
zJ|0}+#KPBLUuI2f$WDw2AX-y9HV5Bq8rG$Y$Wu#&-*s~8>dm&Qs?aYWUX-h>NWwh&
zj%`0{PYM*%W!~~HXc%ew#4B^9C9(0=A4C-vfMq8x$PJzdx$jHKd_Oqu=Y5Y#ghbuy~ST)&-3$}ZBVV0;I)P00L(uu`zkT;xqBTfpN
z68N5uKg`Nz4bfNc^am~wBYi6<&arBC)!vcS1zxNa-cK!OnLf@?Qb)JSo~wa1e$XNV
zUt^*9-y=-WB9qe36xicM;4WnkUg_a^+YkFz8(gf92?h^0mOJ
zg`C2TXOi33r!UY_oJ|lGYuyl5_f}y_wlZVWRqFA+ae!@2Hm-qJ>{O8jh>~@njV>{V
zMQ7BbUgW=>UA69@*M;K0zuw!SU8&$UbYhKWMUnzEmXKBtdPXu*!(w~>ye#8uy5T%U
z5}G3BnYM+tF<3um&s3$>LrSb!{dQe_58(rj#%f_7j%xy>?JelCt=ywyF}f8j?nGJr
zdO33kufu1*b#d0FsXH2{rZwn5fF
zbM8s{p7HB!cwAIs4v-&ZG2FspK>Ssymp+&6{7sN?>v&b#+u$8;
zVC&@Yyc;P?TDl9RZV0t2)vI)ui-vh<@=fmUAcM{?kx9Y$m`YHW6Gqzu`DPUjhP>@KX($gYQai_1y^-%Gz~%{I7*X>Bc6)iHG^_))mBOvLg#8L)~0%5T?%%~pU!rH*rjFZ=a6Q
z-oPWv(4qol#UT<_JssrcbLxGkRA-}~L1m7rQ673~0P%CJm&gZsh<;S1#8m`=n
z7%adZuoFx*2_eWyo+@H1bUBhU@|XVbz0;rj?#(altHIJ(u#BAP?K^Xw3t3A
z?APOXJ6sj5)-vcP20V1D{cf#Uzt;IHqMj%9Q%5Lf?ir#k*ic*@^j(e{bYMWjCnSwz
z7Py%(ureU_w5kw-CuRx|(|4Y#zIKQCKQQ@fzGc$Mt${^6YQaz$B5~KY>T=UVmd3XX
zRvef$j2sQ*6vi{sTRjXtB}y{Bc4JuHJdr*lSaD-8Vjx7OK^Ifc=l6a+!U!y;3@a*w
zD@t)=z9MHkM}B#}>vWbgGJvE>xGhn@noNOYefD~mC?W@@iPoFuI%dWkB)h*tqr-F1
zy?3ll&X$x1o1!Pjh9Vog4$I?9SNV&5x;#j!G;fwQXAq303ypG-&ySqGAr`ExGDYCr1ck
zG34F6{hgA5#U($_X@||9hJb3k7=6$0yiv%XWBMR`x*+
zrMQjzjJ)Yp7}+=xIf`;2EOgil-@mh&Cu=s5HO9YUrD6=Z>+x7?{$k*7=*sr1&-w}W
z@o@SaZKh0$Bar_{RSo@1B
zu7F6a94oB_K^d{X*-+#MV#@ZUzXsOycK?%TtoQOuMQx+&nF>^oIQp~x87z
zzF70P%CME9hFCN
z_@Er~v+L(T)DK-gRM|~c+htVC;q_EXLeC=~_oCwm8GCC%w>YM(jYU2PsfG$>?j`|Y
z@LeE_Fr}(?)vYd_V#5M?_OZu#quRauyAql?ic$|#d{Kj&##=teT}0tn24TF9-x56D
z=tEXt7-kcpY0VgRakT2mOYc5qLRFHerG7l2bs@CQiv=qj>QRhuvzA<9h&0vCSMWb3*^Eqymr!!uFp=O7CD#s_yhp+6D34VUP3ibTH;)(kR)cko;s#i@soTCcQH
zRR`HH4wG3tg9@#(bEKXpOT;(4&$b*K4Ak7~
zH5}2VH@baWUfpN)<*_lJvP)KQ{F-@Tff0k#(^^%0b$^rIz^=4JqwgRjgngx-Xj#z7
zpX^+bi7{QhI>i3LsR1!U)yVdGI1#+%OVKM!m`rdoebg5Lvx4|57xrbMHyKHpxQX5|
znMbx&5zTB6RKHH>o@c*B7BANjPmd3ix<5hqrZFi}BZ@G^drKio;)VP}%k@RfwAAbv;Y!VGlEjC4Om6ur5lA;(2Ms$f%NIieCW{P9
z=zCXFNgcA*ayv@vU3O2=KMjqLO+)=bd}Yf-NEq0b+$-Tu(0|6@JrKC+@A;waaYjE<
z;ax6|MJa;y@ejV2YI`9|P7`zQ`JmqRwd9m^`-+(2=O>gh*`wD_LJ$IO|nl@4VTj*mfmjuN5u
zad5wmk-udd#QlsN0(r`|!eUzdMbrX#Wt&=2?cyhGkt!yyk$CoF`o4K3uZo)#oKFp^
zPQZDoWCM1|gi-{G$%|is=Bx*#kh|k>7y?G$L5`y0uagvBtmy3*yf#ez1IMJFgkr^?_D6oR!S5q{s!y~r%N7k%
zIO`G7^_R1u#11L`_|q%hlHFfqo_DJt$vvy;_4)JU?F*Z`ySM^E#iIu)UBrw6Dr-wO
zLgIRjpTBK2bDW>C(r+u5ewB0}M=?Jm0H?-)4~p>B1Q#YJA)ce71p(`W?}(Qkod*hS
z#aDmpP`Abh*{{e94_g=+1nCGp_8!OGtf2@~@W$dPE+SD|tTT0Z@IO^z&3E*UK(IW-
z4ac9X(_xImY&~k8dmHQAPUKK|f~%-pH+rpV8XkAs&PtCYU*dOWUPx+Ohw8I~49g@4
zd<2OL36n^VN3lIdqmM82)uN4aA2!pBp$NHlC{dY5lIlV9ea+a3gPZ7g_R;1Tf!w~T
zXRXo61ruvDfqASykGBxg@?i+k&P#BI+`kQ`lV5jI`ZP0YMl^~0CrHNq-5$R%n@4@n
zL?3S5*o!whO#i~TCFMtH{c%y?w`$}k1bHG(5!yD{XbAl#-Wg+D*wWf&P(dHo@EM~r
z#%--xvm$`S9?1nMgy+}SNN|E2>ky`N714HhvC3O06wg3SKI(7T31RKEp2Sgj5+NV-
zoCR+pSTQ{4!Hbn1D$N+FvIeCT(^ebH3(MrEcnUSFynQ-GPbeOjR%_i0ou(*Nzk1XA
zS}&qIiYVCo2_#OY{}G2$L?)!TMwpJUEE(33?*Kc3
z7z>V$vNvQQm>>P*dpQy6iLPZPMp{Sw)WhKD;wMVkP$>Fx;pZK%m)-jpw#m2!F*r9v
z1rKS&goC*33qj&bwx7{?h3e&#sZyse<^B0xA%nei<0T5?SF4bML;B$`d7ow1A>$1L
z%{Hu?z#hvoOIPOC$(W``bPiLRYw%sX7zoJRQqMdD
zkNr^VhBW+qt#{U$JcGc#SFer=lB0RX^^K_Fe9_(73$|gOEG$}e`8)k_>!ZcV4%UNK
z$oEGxd%;H`WZh8LzBtBf|PPaFdp
zI8DK*k3D=b4;Jn57YbM@k|A#HB*;b#&&T(~$DU(FW^u*Zma;Mhy?Fh9I{V6~s-mvl
zLwBd7G)N;YA)O-K4bqLIH0O}gN=S=zi%7SWq|%+zNJ~iEb$s9N{C1Vg3m_YxzaUM;C31o#f=by}O8>GV%6onGlKWW)I3-En`{#BcSD7B0u9J(&1)r
zwwZM&$MBH_pV7IWVgb^OVNbm1zKGnOE?#)|B|2K6qMEZwf?(v45p3ghhnzfSM!Lh{
zqNH+uV&vdUUd0`9JUKhGuO4EC(*lm+q3$%)#Ur8q#x;9Uj7yj%h}(Nutd%XAUe?~Q
zC)zIZ9a>rFqvqDrbS)2|ty&u6$9~hNHG^_SH;mp;^*gQ!ddK~>a8=UsPOGos=S6dW=rtBfjx|&zr!bpOf-{^$I#a2`PiQ~fX7!T0S
z2@Of(U=#==pQ0t{nO6o#nfx64y<{%b-Q#}+(g}Hkc8-@K)v0AQvqqNY?gQNhb6l@D
z0_v7Y^~=>db#+km{zeJ%TJlc*Cz#B#_d^pg!?{D?qve8K_@W4>`7j$jfeEtUMF=?N
zE1PXz8kB-V!5zd@_2Ohu1Kmp1@a`QF)|e5zfmf{4KXERZR_L>1y18X?uAA&1=5dOc
zZ!gy0*io(yePyI1tYrwKw5*??6doqlQ+USl>lN^fdzQpoqZL0+NHx&Yg4OQWy1Hf$
z`7pT<+1xDpE;ZE>j659Ya_I+)`?6%pYNiuDS}F<5?M&zozq#=j15I~!&d$BG4_EzzV&B{!
zwK!jGD=`4~yHkXoEkH+}czPrZSU?fT%YB3V8zI|EAl7`c7zinh{sgi=JLlsz@Y?=J
zxSn1z86Q*=&09eN=!TF3v(yJXLM4JmCmrB|G?WI*C`#gnf|bVJ@$k$y$w7+dstF#m
zWlvH>)=_?<%~p!Oa$j9T!yVal{y2+s1pc=RUlHr1q-BFrdc}(gvuraCLM!`OOAZ{P
zw?UB@3c%CSUvN)1A*HgDh(a1cs}*L%k>kA{z&0Y}ISl`HgaNASc*6bx@>`jgoPm*H^0UJ
zY!mc=LhYA($7o+1B_NzO&4ujMjY)(XbM=3IHDunfps-{EdIATAhmj#*WK-Af>vj0V
zsLoCZ|A$PKfpZ=Xwdsr1T%F3sSxdrrJQkROOeJZ*8KggTWzauwqp$H%hqv2F7Z3_>#o77hk2&^)sAU>7RM;$FljbWvGWMbyz@75EMh`
zlLxPC+C==uIgGY0zinNsebi;JTS6tDu8KTUCISZ${A_HgBN7jOp!8o3CYwK?f*YDP
z-)J)jI~4Zt8i8xi*{nu_df*Iw(~mz3OoIlaHsQi}*=wKpGfC?R3H_DSk+tOgbdoV~
zBLMsbgTEL7>JJ2{VgYh@IzQM?V3Q-`-?v83A|6peE1NMvXbiHjM+<69R&1}YVdGq5
zf8J0QWbl=C+^l1WNf{X$j!#ZP!R*NH?JLlzbR27Ti^!FRb?WYK;JnmKf+unH*#FHN
zg1wQ_**aT1&(xgD@;e}1=3cGE}4_SJG
zchO4f%*=EFe{tbL7SKo>KNMG^lM_;TifnDMHcnO@YT;FDma5HUiIEDkH8=1@^*;y{
zp4Sci{D+9ArDAsFoDFz1EPT=v8pK8+Z^z|4_pUwbbsZ`1{Z9gozZxTSZcF`ET#2xj
zSs%uAim7oCLUnWmu|iMhu9n21_B*!HaWZ1*%mzfwrQ3ZS(O(nHadEd*SzrcU?gkqh
zn;Vz|WN$B}to+^Uh=H9Qi)jDDrj=OCq$2p|u>-Jk_LSJerAl&P=QPJBCg
zu=n=%j`zx|EvL$K3QkLy3tCpIrJKxBLmx9t+jAQhh`#Z<`}HZY|IqgzJ|78(
zJKgF`OVuJ1Z{MRE=|E(rM@T9eo-+FKeoW&;^?c~azue({9S{JS#v%hL_^|qB%$Q>y
z*~QNUNexa=`e8|>My?YXR5Ok$HB7;R~Q~veD03Qyq`ak
zj?Eje#c!xD8^+D3wTB0};@V3E;I=p4s-Wwj^?m*oM`7n6?Xzp~npPBXCTfbtPZ7O)
znwT!YnU~+Q^-ZTWvduc~6=d(S<3W6WVF7Mso#sCOYF3E?1I?uY2O%
z$N&N=Rk4;kfD6Hm#R_qp3>-zFnGR=9)t!7}n@*wnqCgo-QI?RAVjV<4k4mMK6fu;c
z{@<{PwjnpvNO~(572iauYNoTcY(F@t{hc&TqQD;iwI!9?fVg+QX47_idcJsjmkt{5
z*$Hyn2yw00RnhReUmvh$Es5Lt?K^+Dy>JC(3z_3)c=h5;MYEca!pY>AdzLsDOU-+F
zRozhpXp4KdF9plnVuB(}DGetH-To?Q5a~tWJ}B=PZLjn)*3Ly)=K@TK
z02S#$ZP}roKH%GVPOs&Oh-A)}FZ`gN7fet3LjeeTkFPco%r0+0%OYL07%(5v(b0`(
zqt8z6{~m3yn_Yj86C+k+vgE;jRyYD>38&scoA8Ku2@%RcF>VhH6?Q`SbYhVB%~qN)
ziT(?>IYP}-{;l0DYvV?z_U>(-46cpOg^ygO4?W|I=@mW)A!vptCsDkMLb-uz=ycfb
z*@{x9cOkSJxau&Wj!oYP?&DyD0`IJOQH)hf6UIaxfy5Kpjs|6kdn+}&WF|k5Z59TK
zMxaJiV+I1DU9FmI2^1xDd~CU19^%SS4yT(mGg*8FmH-it?zDoyJR*fS64s*<>4Y}C
zhmr?$TET#~uRzKi)XKiBz6;5I@A1?H?tLUw2cY8ZhiWr+RbowVcw$Y;QVBKn=b?V
zZBBz2p9(Iw>(Rq)>&W;qEo-SQ!{1ui22PM74o1VX%$!Vf2cB1R280pV-F<
z%7l%D_~qNnpC_hJ7sKs%Oyt{y)>?WU&Ue|+j*VbiIB@xtc2Fl=|H4}*fo380cItbB
zd`a22)oai85q}2y{E<5?Jgl~Kz=P2cQ-1;cMF9qph3lV?fw}a63WbvH^
zBgBhjY_t-71sFd4p+9sR_`7U9VnUTBh
z#?9Xpri6?XJ)3L4nzkptQo#}H^XwVnMS##p^`u0oU_)8{GO@j8zIdj(98!vbQ#2$^
z*PIkaBDGv7EMXp_sW2S-xXX&K%lk9tG&tC~P0pRCDTy|+?F|w97H=JwRjXdmki;Fg
zct1Xm=eAt67J%o|K^hDQpe0DEGWv_3m&bs5@_yQ%XCBemC_nsIqejDjOvf|yc~Bjd
z$fvcT9nBo|=0x1-()d(%Mut~aj?*UCmy}Z24$x%6mJ{A_D
zble@f<^u}Verg}pJx4X6c=vGoj&Ee2oy3v8c8mZkSsKph!uAOq9r#=NsRn*X(EcMj3c|dTBnodpzW^C}5lOgC8W|>F9i4PX0NOpgDc~^0>aG-GyV=
zJI<0lQ5eWQ^BWmy%=uxy&o0I<1XUX+gwq0#ywo@oS-&z~j&PYizIXgV*k~J2boz=|
zqqv1+NwoL;HQwe4pwK5=&42Q~>!tS9JGP_<*oiniuN+l~x+3JLS!rx&WK=Ced0s4e
zhjD#<-MtOi6>#Ca$ocPw3KAql*L1;X&{xtt-t}m-0rnDrw0nM#WKOXjD
znroALDwDfs?{rC=H4OcvnLNmQu!W;IOld-R|cxkyoD^3|w7kHrLLo
zci1uvv-**MCA+PdoHL|*o@VDYUTuie^PzrXx#7TJBvqHnp1nVMRLjk;1v2nWb5oW>
z2CP!@ImUz_((AbZ6nN&{(D{~fK{gQ4`;)6oE7x&2j-D+`MgNcm$Tqil`fiz4Oi8CT
z5CU~%)zY#ZIhY$kA29Vj`w@q%{x8oSCS)gyGKx&sipXwr!h`RU7d}
zOM8N_Liq_2Ve-f^0nJ+C=o?=;ePuq5bdsafq7QW==td;8{7r@mo9)rE>YS<@APGb@
zAdOhPO`buyD89r)D}sEM)MKs+f-+zcBG&82x3;e9<ppXoFPEDZA!A~`xmoBty9ySshm@6qkO
z%=YwpYp2OUDwEw#KEG((Zct5U*Vm`CMH_DcEFS8X4BEA|)ln{bts&A~8E_n{&-PF8
z`rYk5^Mf=OqK--N>Yw(a0Va=4ISvJo1|&Rp7YbM*q1N&32;z2fX-Ag&53Yo?=IKgB
z55mIW6aDW)S2&C^O^NgblPY{y-&f~E@Y%O@c~=MXKr-BzJ!E}RjmLQ#Rwy#Mw;=iA
z6UG+hDeeg0;9XtN(Mync#96jJ^4DT8bUrNb9@w=uq?>ytz-m8QFPDK0PFn_AejUB;
zCGp#549Uv*rpaAn{G4MEvXtrE%ho~emls_g=RCkF2Hr3}(bBZguOn@4eIIoAMsSBl
zR!%`6{)HYmyDJ>GQ
zJBAMz-+zr;TT5qVVu9+L;-n|{0JA4j|7UVBBdm%1a8NZZ7z%9M-i1bkckFcMXf8|W^!ml0
zJ7m3o0Z&4o`l-U5Cyp>h37;ZWV1l>J)9`twGPw#?>?yoVzAz_q>)R{Jg33?I(}_ybwxrr;5j`EWRpI*
zXCyLOOFKp7Jni@fP*_vbTUz1vtSshH`i%0eT%@I_K_XlttOSOSNKBAgsfWgLVU=Z=
zU$v$rMud7D1ilP?&L0^G7iEws`K>bG)K|-a%AFN?JuU@;b1c{+IZUSWYZRUe1FT-e
zhbeb}q)5A=gu@|)42
zU7aUL!*7^fZOw6!^L6-gkOt}Qxv?!~_cSTRKv95&fN^znR;x^cYWpwe_rMUYX&I@}
zC!1S!Q#h$DqBmLFtPJpkBh~2Wbc3wc-(IX9fn`QQyHp$LTr+e4i{MuYL<0C62-Q%h
zwfAtdgo0J=n*+P^KZ)f+Ch~QKas!m)ACt=xE%jGNER?0gxJZBcHOl<<*N>$B`e7nq
z{B=