path: root/95/7ff6801c8866a7e5bd3606547345dfd18a9dd1

Return-Path: <salvatore.ingala@gmail.com>
Received: from smtp1.osuosl.org (smtp1.osuosl.org [IPv6:2605:bc80:3010::138])
 by lists.linuxfoundation.org (Postfix) with ESMTP id 1BA18C002D
 for <bitcoin-dev@lists.linuxfoundation.org>;
 Thu,  5 May 2022 14:32:49 +0000 (UTC)
Received: from localhost (localhost [127.0.0.1])
 by smtp1.osuosl.org (Postfix) with ESMTP id F34EA83F46
 for <bitcoin-dev@lists.linuxfoundation.org>;
 Thu,  5 May 2022 14:32:48 +0000 (UTC)
X-Virus-Scanned: amavisd-new at osuosl.org
X-Spam-Flag: NO
X-Spam-Score: -2.098
X-Spam-Level: 
X-Spam-Status: No, score=-2.098 tagged_above=-999 required=5
 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1,
 DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001,
 HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001,
 SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Authentication-Results: smtp1.osuosl.org (amavisd-new);
 dkim=pass (2048-bit key) header.d=gmail.com
Received: from smtp1.osuosl.org ([127.0.0.1])
 by localhost (smtp1.osuosl.org [127.0.0.1]) (amavisd-new, port 10024)
 with ESMTP id 07MxH2PuzzY5
 for <bitcoin-dev@lists.linuxfoundation.org>;
 Thu,  5 May 2022 14:32:46 +0000 (UTC)
X-Greylist: whitelisted by SQLgrey-1.8.0
Received: from mail-pg1-x531.google.com (mail-pg1-x531.google.com
 [IPv6:2607:f8b0:4864:20::531])
 by smtp1.osuosl.org (Postfix) with ESMTPS id ABD0D83F3E
 for <bitcoin-dev@lists.linuxfoundation.org>;
 Thu,  5 May 2022 14:32:46 +0000 (UTC)
Received: by mail-pg1-x531.google.com with SMTP id 7so3755061pga.12
 for <bitcoin-dev@lists.linuxfoundation.org>;
 Thu, 05 May 2022 07:32:46 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112;
 h=mime-version:from:date:message-id:subject:to;
 bh=+VU2j8R7XBYRplJZVTJkG5oxmrqetkIY9NK1ZXwyPyY=;
 b=Owd3tBQNnsqy7PW18I6pjFSPY/pxH3E4SLelgNBPXegT8VXj0bwHjlJs87OcugLgBn
 t07E/P7bl1DYZSMDBBMMZVrqlhdRDv5GNJ+va1RzoxDmzc+/qfFBw+TQ90w7Rg3u4z3N
 5WH4itY31QAv2+Co0bDOWdS4N7ElBDjyGEyl/46zkvjl5tP4vIpWbHP/8OFQCHN/688D
 AjCU+y+tROEY7UTRo1UqugTgiicchzjROzC2rX/6cEkSgskAl8xVXLE9inQFclSe8arK
 ei81UpJpxOcfF0SoPBBi+/ztkhWLnRQIACTDuiFNOjiguNj4+/mB4ak86S95rPr2LmFd
 I1+w==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20210112;
 h=x-gm-message-state:mime-version:from:date:message-id:subject:to;
 bh=+VU2j8R7XBYRplJZVTJkG5oxmrqetkIY9NK1ZXwyPyY=;
 b=Bv1eCUw0Zaf6sqfxEKsGZkdBfDnoXQvt0GDOFYszcsrOkLJrr+MYDMp0GghYiOKY8d
 DZdI10u4V8x7toGJ/zicifmVVNBUDmqu95hq49vAid1ZbrLI2agbhXFC+Cr+4ultiuCA
 RhQfp2brFSOkzaLaJXi53H1MmjxBLYb0UG4eCu/tjKV+xtoVZC5GgyORd/pvuZKhnrn4
 eX+2VMtApR1bz+V30+kbZzTxL/GkS9FyaFNJ1nEgcbMrsMLGsrOP2gzXVHNxExQ4W2XI
 wwvf2s1OWivZMAT5x0o3uuaN99YoTdnbVhRp+GtVRy21cARn1FQRxpseNCS3EllEl9WA
 Hm4w==
X-Gm-Message-State: AOAM531l5k01UoDCqTZbxLFjY9pDTulPcdCfc7VNm8gdkThoJFulu4B2
 n5xpj1XyiflEPMyxsgTVus+Z0Pqi7yAzPVbEGIameLuAu5X88c8B
X-Google-Smtp-Source: ABdhPJyUq14eNcRLpUL6leFj6eGXh3h3gZl/g3ZkW1tOc3YfKRUHLkQ0nQ+GTjyv/4f6/Uj1kCOiiCIaAhKFv4pU5bM=
X-Received: by 2002:a65:414a:0:b0:3ab:84c3:3beb with SMTP id
 x10-20020a65414a000000b003ab84c33bebmr22533831pgp.369.1651761165294; Thu, 05
 May 2022 07:32:45 -0700 (PDT)
MIME-Version: 1.0
From: Salvatore Ingala <salvatore.ingala@gmail.com>
Date: Thu, 5 May 2022 16:32:34 +0200
Message-ID: <CAMhCMoHfdsQMsVigFqPexTE_q-Cyg7pfRvORUoy2sZtvyzd1cg@mail.gmail.com>
To: Bitcoin Protocol Discussion <bitcoin-dev@lists.linuxfoundation.org>
Content-Type: multipart/alternative; boundary="00000000000082df1705de449dfa"
X-Mailman-Approved-At: Thu, 05 May 2022 14:39:23 +0000
Subject: [bitcoin-dev] Wallet policies for descriptor wallets
X-BeenThere: bitcoin-dev@lists.linuxfoundation.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: Bitcoin Protocol Discussion <bitcoin-dev.lists.linuxfoundation.org>
List-Unsubscribe: <https://lists.linuxfoundation.org/mailman/options/bitcoin-dev>, 
 <mailto:bitcoin-dev-request@lists.linuxfoundation.org?subject=unsubscribe>
List-Archive: <http://lists.linuxfoundation.org/pipermail/bitcoin-dev/>
List-Post: <mailto:bitcoin-dev@lists.linuxfoundation.org>
List-Help: <mailto:bitcoin-dev-request@lists.linuxfoundation.org?subject=help>
List-Subscribe: <https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev>, 
 <mailto:bitcoin-dev-request@lists.linuxfoundation.org?subject=subscribe>
X-List-Received-Date: Thu, 05 May 2022 14:32:49 -0000

--00000000000082df1705de449dfa
Content-Type: text/plain; charset="UTF-8"

In the implementation work to implement descriptors and miniscript support
in hardware wallets [a][b], I encountered a number of challenges. Some of
them are technical in nature (e.g. due to constraints of embedded
development). Others are related to the attempts of shaping a good user
experience; with bitcoin reaching more people who are not tech-savvy,
self-custody is only as secure as what those newcomers can use easily
enough.

The main tool that I am using to address some of these challenges is a
layer that sits _on top_ of descriptors/miniscript, while staying very
close to it. Since there is nothing that is vendor-specific in the vast
majority of the approach I'm currently using, I tried to distill it here
for your comments, and will propose a BIP if this is deemed valuable.

I called the language "wallet policies" (suggestions for a better name are
welcome). I believe an approach based on wallet policies can benefit all
hardware wallets (stateless or not) that want to securely support complex
scripts; moreover, wallet policies are close enough to descriptors that
their integration should be extremely easy for any software wallet that is
currently using descriptors.

[a]: https://blog.ledger.com/bitcoin-2 - early demo
[b]: https://blog.ledger.com/miniscript-is-coming - miniscript example


Salvatore Ingala


======================================================

This document starts with a discussion on the motivation for wallet
policies, followed by their formal definition, and some recommendations for
implementations.

== Rationale ==

Output script descriptors [1] 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 bitcoin-core's descriptor-based
wallets).

Unfortunately, descriptors are not a perfect match for the typical usage of
hardware wallets. Most hardware wallets have the following limitations
compared to a general-purpose machine running bitcoin-core:

- they are embedded devices with limited RAM and computational power;
- they might not be able to import additional private keys (all the keys
are generated from a single seed via [BIP-32](
https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki));
- they might not have permanent storage (*stateless* hardware wallet
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.

A more native, compact representation of the wallet receive/change would
also benefit the UX of software wallets using descriptors to represent
software wallets using descriptors/miniscript for multisignature or other
complex locking conditions.

=== Security and UX concerns of scripts in hardware wallets ===

For a hardware wallet, 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 wallets strive to guarantee is
the following: **as long as the user correctly verifies the information
that is shown on the hardware wallet'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 hardware wallet, 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 wallet must guarantee that the user knows precisely *what*
"policy" is being used to spend the funds, and that the "unspent" funds (if
any) will be protected by the same policy. This makes it impossible for an
attacker to surreptitiously modify the policy, therefore stealing or
burning 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 able _in practice_ 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-129 [2] for an approach designed for multisignature
wallets.

=== 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
wallet. The "wallet policy" must contain enough information to generate all
the relevant addresses/scripts, and for the hardware wallet 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 wallet. While the details of the process
are out of scope in this document, the flow should be something similar to
the following:

1) The software wallet initiates a _wallet policy registration_ on the
hardware wallet; the information should include the wallet policy, but also
a unique *name* that identifies the policy.
2) The hardware wallet shows the wallet policy to the user using the secure
screen.
3) After inspecting the policy and comparing it with a trusted source (for
example a printed backup), the user approves the policy.
4) If stateful, the hardware wallet persists the policy in its permanent
memory; if stateless, it returns a "proof of registration".

The details of how to create a proof of registration are out of scope for
this document; using a *message authentication codes* 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 wallet can perform the usual
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 wallet 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 its name), and *as long as the policy
registration was executed securely*, hardware wallets 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 MuSig
- a script tree with a tree of 10 different 3-of-3 MuSig2 scripts, that are
generated, plus a leaf with a fallback *3*-of-*5* multisignature using
plain multisignature (with `OP_CHECKSIGADD`).

This could look similar to:

```
tr(musig2(xpubA,xpubB,xpubC,xpubD,xpubE)/<0;1>/*), {
  {
    {
      pk(musig2(xpubA,xpubB,xpubC)/<2;3>/*),
      {
        pk(musig2(xpubA,xpubB,xpubD)/<4;5>/*)
        pk(musig2(xpubA,xpubB,xpubE)/<6;7>/*),
      }
    },
    {
      pk(musig2(xpubA,xpubC,xpubD)/<8;9>/*),
      {
        pk(musig2(xpubA,xpubC,xpubE)/<10;11>/*),
        pk(musig2(xpubA,xpubD,xpubE)/<12;13>/*)
      }
    }
  },
  {
    {
      pk(musig2(xpubB,xpubC,xpubD)/<14;15>/*),
      pk(musig2(xpubB,xpubC,xpubE)/<16;17>/*)
    },
    {
      pk(musig2(xpubB,xpubD,xpubE)/<18;19>/*),
      {
        pk(musig2(xpubC,xpubD,xpubE)/<20;21>/*),
        sortedmulti_a(3,
          xpubA/<22;23>/*,
          xpubB/<22;23>/*,
          xpubC/<22;23>/*,
          xpubD/<22;23>/*,
          xpubE/<22;23>/*)
      }
    }
  }
})
```

Note that 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
gets *exponentially* 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 in the
registration flow.

=== Restrictions on the supported descriptors ====

The policy language proposed in this document purposely targets only a
stricter subset of the output descriptors language, and it attempts to
generalize in the most natural way the approach that is already used for
single-signature *accounts* (as described in BIP-44 [3], BIP-49 [4], BIP-84
[5], or BIP-86 [6]), or in multisignature setups (see for example BIP-48
[7] and BIP-87 [8]).

Unlike the BIPs mentioned above, it is not tied to any specific script
template, as it applies to arbitrary scripts that can be represented with
descriptors and miniscript.

Supporting only a reduced feature set when compared to output descriptors
helps in implementations (especially on hardware wallets), while attempting
to capture all the common use cases. More features can be added in the
future if motivated by real world necessity.

By keeping the structure of the wallet policy language very close to that
of descriptors, it should be straightforward to:
- write wallet policy parsers;
- extract the descriptors defined by a wallet policy;
- convert a pair of descriptors describing a wallet "account" used in
current implementations into the corresponding wallet policy.


== Wallet policies ==

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 (use
`addr` if you only know the pubkey hash).
- `wpkh(KP)` (top level or inside `sh` only): P2WPKH output for the given
compressed pubkey.
- `multi(k,KP_1,KP_2,...,KP_n)`: k-of-n multisig script.
- `sortedmulti(k,KP_1,KP_2,...,KP_n)`: 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 `}`

Note: "miniscript templates" are not formally defined in this version of
the document, but it is straightforward to adapt this approach.

`KP` expressions (key placeholders) consist of
- a single character `@`
- followed by a non-negative decimal number, with no leading zeros (except
for `@0`).
- possibly followed by either:
  - the string  `/**`, or
  - a string of the form `/<NUM;NUM>/*`, for two distinct decimal numbers
`NUM` representing unhardened derivations

The `/**` in the placeholder template represents commonly used paths for
receive/change addresses, and is equivalent to `<0;1>`.

The placeholder `@i` for some number *i* represents the *i*-th key in the
vector of key origin information (which must be of size at least *i* + 1,
or the wallet policy is invalid).

==== Key informations 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 [BIP32](
https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) for details)
  - Followed by zero or more `/NUM'` path elements to indicate hardened
derivation steps between the fingerprint and the xpub that follows
  - A closing bracket `]`
- Followed by the actual key, which is either
  - a hex-encoded pubkey, which is either
    - inside `wpkh` and `wsh`, only compressed public keys are permitted
(exactly 66 hex characters starting with `02` or `03`.
    - inside `tr`, x-only pubkeys are also permitted (exactly 64 hex
characters).
  - a serialized extended public key (`xpub`) (as defined in [BIP 32](
https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki))

The placeholder `@i` for some number *i* represents the *i*-th key in the
vector of key orIgin information (which must be of size at least *i* + 1,
or the wallet policy is invalid).

The policy template is invalid if any placeholder `@i` has derivation steps
while the corresponding `(i+1)`-th element of the keys vector is not an
xpub.

==== Additional rules ====

The wallet policy is invalid if any placeholder expression with additional
derivation steps is used when the corresponding key information is not an
xpub.

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
informations), one can therefore obtain the 1-dimensional descriptor for
receive and change addresses by:

- replacing each key placeholder with the corresponding key origin
information;
- replacing every `/**`  with `/0/*` for the receive descriptor, and `/1/*`
for the change descriptor;
- replacing every `/<M,N>` with  `/M` for the receive descriptor, and `/N`
for the change descriptor.

For example, the wallet descriptor `pkh(@0/**)` with key information
`["[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL"]`
produces the following two descriptors:

- Receive descriptor:
`pkh([d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0/*)`

- Change descriptor:
`pkh([d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/1/*)`

=== Implementation guidelines ===

Implementations must not necessarily implement all of 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 general-purpose software wallet allowing arbitrary
scripts (or any scripts that involve external cosigners) should put great
care into a process for backing up a wallet policy. In fact, unlike typical
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.

Avoiding key reuse among different wallet accounts is also extremely
important, but out of scope for this document.

== Examples ==

Some examples of wallet descriptor templates (vectors of keys omitted for
simplicity):
- Template for a native segwit account:
  wpkh(@0/**)
- Template for a taproot BIP86 account:
  tr(@0/**)
- Template for a native segwit 2-of-3:
  wsh(sortedmulti(2,@0/**,@1/**,@2/**))
- Template with miniscript for "1 of 2 equally likely keys":
  wsh(or_b(pk(@0/**),s:pk(@1/**)))

More examples (esp. targeting miniscript on taproot) will be added in the
future.

== References ==

* [1] - Output Script Descriptors:
https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md
* [2] - BIP-129 (Bitcoin Secure Multisig Setup):
https://github.com/bitcoin/bips/blob/master/bip-0129.mediawiki
* [3] - BIP-44:
https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki
* [4] - BIP-49:
https://github.com/bitcoin/bips/blob/master/bip-0049.mediawiki
* [5] - BIP-84:
https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki
* [6] - BIP-86:
https://github.com/bitcoin/bips/blob/master/bip-0086.mediawiki
* [7] - BIP-48:
https://github.com/bitcoin/bips/blob/master/bip-0048.mediawiki
* [8] - BIP-87:
https://github.com/bitcoin/bips/blob/master/bip-0087.mediawiki

--00000000000082df1705de449dfa
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr">In the implementation work to implement descriptors and mi=
niscript support in hardware wallets [a][b], I encountered a number of chal=
lenges. Some of them are technical in nature (e.g. due to constraints of em=
bedded development). Others are related to the attempts of shaping a good u=
ser experience; with bitcoin reaching more people who are not tech-savvy, s=
elf-custody is only as secure as what those newcomers can use easily enough=
.<br><br>The main tool that I am using to address some of these challenges =
is a layer that sits _on top_ of descriptors/miniscript, while staying very=
 close to it. Since there is nothing that is vendor-specific in the vast ma=
jority of the approach I&#39;m currently using, I tried to distill it here =
for your comments, and will propose a BIP if this is deemed valuable.<br><b=
r>I called the language &quot;wallet policies&quot; (suggestions for a bett=
er name are welcome). I believe an approach based on wallet policies can be=
nefit all hardware wallets (stateless or not) that want to securely support=
 complex scripts; moreover, wallet policies are close enough to descriptors=
 that their integration should be extremely easy for any software wallet th=
at=C2=A0is currently using descriptors.<br><br>[a]: <a href=3D"https://blog=
.ledger.com/bitcoin-2">https://blog.ledger.com/bitcoin-2</a> - early demo<d=
iv>[b]:=C2=A0<a href=3D"https://blog.ledger.com/miniscript-is-coming">https=
://blog.ledger.com/miniscript-is-coming</a> - miniscript example<br><br><br=
></div><div>Salvatore Ingala<br><br></div><div><br></div><div>=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
<br><br>This document starts with a discussion on the motivation for wallet=
 policies, followed by their formal definition, and some recommendations fo=
r implementations.</div><div><br>=3D=3D Rationale =3D=3D<br><br></div><div>=
Output script descriptors [1] were introduced in bitcoin-core as a way to r=
epresent collections of output scripts. It is a very general and flexible l=
anguage, designed to catch all the possible use-cases of bitcoin wallets (t=
hat is, if you know the script and you have the necessary keys, it will be =
possible to sign transactions with bitcoin-core&#39;s descriptor-based wall=
ets).<br><br>Unfortunately, descriptors are not a perfect match for the typ=
ical usage of hardware wallets. Most hardware wallets have the following li=
mitations compared to a general-purpose machine running bitcoin-core:<br><b=
r>- they are embedded devices with limited RAM and computational power;<br>=
- they might not be able to import additional private keys (all the keys ar=
e generated from a single seed via [BIP-32](<a href=3D"https://github.com/b=
itcoin/bips/blob/master/bip-0032.mediawiki)">https://github.com/bitcoin/bip=
s/blob/master/bip-0032.mediawiki)</a>);<br>- they might not have permanent =
storage (*stateless* hardware wallet design).<br><br>Moreover, other limita=
tions like the limited size of the screen might affect what design choices =
are available in practice. Therefore, minimizing the size of the informatio=
n shown on-screen is important for a good user experience.<br><br>A more na=
tive, compact representation of the wallet receive/change would also benefi=
t the UX of software wallets using descriptors to represent software wallet=
s using descriptors/miniscript for multisignature or other complex locking =
conditions.<br><br>=3D=3D=3D Security and UX concerns of scripts in hardwar=
e wallets =3D=3D=3D<br><br></div><div>For a hardware wallet, allowing the u=
sage of complex scripts presents challenges in terms of both security and u=
ser experience.<br><br>=3D=3D=3D=3D Security issues =3D=3D=3D=3D</div><div>=
<br>One of the security properties that hardware wallets strive to guarante=
e is the following: **as long as the user correctly verifies the informatio=
n that is shown on the hardware wallet&#39;s screen before approving, no ac=
tion can be performed without the user&#39;s consent**.<br>This must hold e=
ven in scenarios where the attacker has full control of the machine that is=
 connected to the hardware wallet, and can execute arbitrary requests or ta=
mper with the legitimate user&#39;s requests.<br><br>Therefore, it is not a=
t all trivial to allow complex scripts, especially if they contain keys tha=
t belong to third parties.<br>The hardware wallet must guarantee that the u=
ser knows precisely *what* &quot;policy&quot; is being used to spend the fu=
nds, and that the &quot;unspent&quot; funds (if any) will be protected by t=
he same policy. This makes it impossible for an attacker to surreptitiously=
 modify the policy, therefore stealing or burning user&#39;s funds.<br><br>=
=3D=3D=3D=3D UX issues =3D=3D=3D=3D</div><div><br>With miniscript (and tapr=
oot trees) allowing substantially more complex spending policies to be used=
, it becomes more challenging to make sure that the user is able _in practi=
ce_ to verify the information on the screen. Therefore, there are two funda=
mental design goals to strive for:<br>- Minimize the amount of information =
that is shown on screen - so that the user can actually validate it.<br>- M=
inimize the number of times the user has to validate such information.<br><=
br>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-129 [2] for an approach designed for multisignature=
 wallets.<br><br>=3D=3D=3D Policy registration as a solution =3D=3D=3D</div=
><div><br>A solution to address the security concerns, and part of the UX c=
oncerns, is to have a *registration* flow for the wallet policy in the hard=
ware wallet. The &quot;wallet policy&quot; must contain enough information =
to generate all the relevant addresses/scripts, and for the hardware wallet=
 to identify the keys that it controls and that are needed to spend the fun=
ds sent to those addresses.<br><br>Before a new policy is used for the firs=
t time, the user will register a `wallet policy` into the hardware wallet. =
While the details of the process are out of scope in this document, the flo=
w should be something similar to the following:<br><br>1) The software wall=
et initiates a _wallet policy registration_ on the hardware wallet; the inf=
ormation should include the wallet policy, but also a unique *name* that id=
entifies the policy.<br>2) The hardware wallet shows the wallet policy to t=
he user using the secure screen.<br>3) After inspecting the policy and comp=
aring it with a trusted source (for example a printed backup), the user app=
roves the policy.<br>4) If stateful, the hardware wallet persists the polic=
y in its permanent memory; if stateless, it returns a &quot;proof of regist=
ration&quot;.<br><br>The details of how to create a proof of registration a=
re out of scope for this document; using a *message authentication codes* o=
n a hash committing to the wallet policy, its name and any additional metad=
ata is an effective solution if correctly executed.<br><br>Once a policy is=
 registered, the hardware wallet can perform the usual operations securely:=
<br>- generating receive and change addresses;<br>- showing addresses on th=
e secure screen;<br>- sign transactions spending from a wallet, while corre=
ctly identifying change addresses and computing the transaction fees.<br><b=
r>Before any of the actions mentioned above, the hardware wallet will retri=
eve the policy from its permanent storage if stateful; if stateless it will=
 validate the _proof of registration_ before using the wallet policy provid=
ed by the client.<br>Once the previously registered policy is correctly ide=
ntified and approved by the user (for example by its name), and *as long as=
 the policy registration was executed securely*, hardware wallets can provi=
de a user experience similar to the usual one for single-signature transact=
ions.<br><br>=3D=3D=3D Avoiding blowup in descriptor size =3D=3D=3D</div><d=
iv><br>While reusing a pubkey in different branches of a miniscript is expl=
icitly forbidden by miniscript (as it has certain negative security implica=
tions), it is still reasonable to reuse the same *xpub* in multiple places,=
 albeit with different final steps of derivation (so that the actual pubkey=
s that are used in the script are indeed different).<br><br>For example, us=
ing Taproot, a *3*-of-*5* multisignature wallet could use:<br>- a key path =
with a 5-of-5 MuSig<br>- a script tree with a tree of 10 different 3-of-3 M=
uSig2 scripts, that are generated, plus a leaf with a fallback *3*-of-*5* m=
ultisignature using plain multisignature (with `OP_CHECKSIGADD`).<br><br>Th=
is could look similar to:<br><br>```<br>tr(musig2(xpubA,xpubB,xpubC,xpubD,x=
pubE)/&lt;0;1&gt;/*), {<br>=C2=A0 {<br>=C2=A0 =C2=A0 {<br>=C2=A0 =C2=A0 =C2=
=A0 pk(musig2(xpubA,xpubB,xpubC)/&lt;2;3&gt;/*),<br>=C2=A0 =C2=A0 =C2=A0 {<=
br>=C2=A0 =C2=A0 =C2=A0 =C2=A0 pk(musig2(xpubA,xpubB,xpubD)/&lt;4;5&gt;/*)<=
br>=C2=A0 =C2=A0 =C2=A0 =C2=A0 pk(musig2(xpubA,xpubB,xpubE)/&lt;6;7&gt;/*),=
<br>=C2=A0 =C2=A0 =C2=A0 }<br>=C2=A0 =C2=A0 },<br>=C2=A0 =C2=A0 {<br>=C2=A0=
 =C2=A0 =C2=A0 pk(musig2(xpubA,xpubC,xpubD)/&lt;8;9&gt;/*),<br>=C2=A0 =C2=
=A0 =C2=A0 {<br>=C2=A0 =C2=A0 =C2=A0 =C2=A0 pk(musig2(xpubA,xpubC,xpubE)/&l=
t;10;11&gt;/*),<br>=C2=A0 =C2=A0 =C2=A0 =C2=A0 pk(musig2(xpubA,xpubD,xpubE)=
/&lt;12;13&gt;/*)<br>=C2=A0 =C2=A0 =C2=A0 }<br>=C2=A0 =C2=A0 }<br>=C2=A0 },=
<br>=C2=A0 {<br>=C2=A0 =C2=A0 {<br>=C2=A0 =C2=A0 =C2=A0 pk(musig2(xpubB,xpu=
bC,xpubD)/&lt;14;15&gt;/*),<br>=C2=A0 =C2=A0 =C2=A0 pk(musig2(xpubB,xpubC,x=
pubE)/&lt;16;17&gt;/*)<br>=C2=A0 =C2=A0 },<br>=C2=A0 =C2=A0 {<br>=C2=A0 =C2=
=A0 =C2=A0 pk(musig2(xpubB,xpubD,xpubE)/&lt;18;19&gt;/*),<br>=C2=A0 =C2=A0 =
=C2=A0 {<br>=C2=A0 =C2=A0 =C2=A0 =C2=A0 pk(musig2(xpubC,xpubD,xpubE)/&lt;20=
;21&gt;/*),<br>=C2=A0 =C2=A0 =C2=A0 =C2=A0 sortedmulti_a(3,<br>=C2=A0 =C2=
=A0 =C2=A0 =C2=A0 =C2=A0 xpubA/&lt;22;23&gt;/*,<br>=C2=A0 =C2=A0 =C2=A0 =C2=
=A0 =C2=A0 xpubB/&lt;22;23&gt;/*,<br>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 xpu=
bC/&lt;22;23&gt;/*,<br>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 xpubD/&lt;22;23&g=
t;/*,<br>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 xpubE/&lt;22;23&gt;/*)<br>=C2=
=A0 =C2=A0 =C2=A0 }<br>=C2=A0 =C2=A0 }<br>=C2=A0 }<br>})<br>```<br><br>Note=
 that 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 get=
s *exponentially* worse with larger multisignature schemes).<br><br>Replaci=
ng the common part of the key with a short key placeholder and moving the k=
ey expression separately helps to keep the size of the wallet policy small,=
 which is crucial to allow human inspection in the registration flow.<br><b=
r>=3D=3D=3D Restrictions on the supported descriptors =3D=3D=3D=3D<br><br>T=
he policy language proposed in this document purposely targets only a stric=
ter subset of the output descriptors language, and it attempts to generaliz=
e in the most natural way the approach that is already used for single-sign=
ature *accounts* (as described in BIP-44 [3], BIP-49 [4], BIP-84 [5], or BI=
P-86 [6]), or in multisignature setups (see for example BIP-48 [7] and BIP-=
87 [8]).</div><div><br>Unlike the BIPs mentioned above, it is not tied to a=
ny specific script template, as it applies to arbitrary scripts that can be=
 represented with descriptors and miniscript.<br><br>Supporting only a redu=
ced feature set when compared to output descriptors helps in implementation=
s (especially on hardware wallets), while attempting to capture all the com=
mon use cases. More features can be added in the future if motivated by rea=
l world necessity.<br><br>By keeping the structure of the wallet policy lan=
guage very close to that of descriptors, it should be straightforward to:<b=
r>- write wallet policy parsers;<br>- extract the descriptors defined by a =
wallet policy;<br>- convert a pair of descriptors describing a wallet &quot=
;account&quot; used in current implementations into the corresponding walle=
t policy.<br><br><br>=3D=3D Wallet policies =3D=3D</div><div><br>This secti=
on formally defines wallet policies, and how they relate to output script d=
escriptors.</div><div><br>=3D=3D=3D Formal definition =3D=3D=3D</div><div><=
br></div><div>A wallet policy is composed by a wallet descriptor template, =
together with a vector of key information items.<br><br>=3D=3D=3D=3D Wallet=
 descriptor template =3D=3D=3D=3D<br><br>A wallet descriptor template is a =
`SCRIPT` expression.<br><br>`SCRIPT` expressions:<br>- `sh(SCRIPT)` (top le=
vel only): P2SH embed the argument.<br>- `wsh(SCRIPT)` (top level or inside=
 `sh` only): P2WSH embed the argument.<br>- `pkh(KP)` (not inside `tr`): P2=
PKH output for the given public key (use `addr` if you only know the pubkey=
 hash).<br>- `wpkh(KP)` (top level or inside `sh` only): P2WPKH output for =
the given compressed pubkey.<br>- `multi(k,KP_1,KP_2,...,KP_n)`: k-of-n mul=
tisig script.<br>- `sortedmulti(k,KP_1,KP_2,...,KP_n)`: k-of-n multisig scr=
ipt with keys sorted lexicographically in the resulting script.<br>- `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.</div><div>- any valid=
 miniscript template (inside `wsh` or `tr` only).</div><div><br>`TREE` expr=
essions:<br>- any `SCRIPT` expression<br>- An open brace `{`, a `TREE` expr=
ession, a comma `,`, a `TREE` expression, and a closing brace `}`<br><br><d=
iv>Note: &quot;miniscript templates&quot; are not formally=C2=A0defined in =
this version of the document, but it is straightforward=C2=A0to adapt this =
approach.<br></div><br>`KP` expressions (key placeholders) consist of<br>- =
a single character `@`<br>- followed by a non-negative decimal number, with=
 no leading zeros (except for `@0`).<br>- possibly followed by either:<br>=
=C2=A0 - the string =C2=A0`/**`, or<br>=C2=A0 - a string of the form `/&lt;=
NUM;NUM&gt;/*`, for two distinct decimal numbers `NUM` representing unharde=
ned derivations<br><br>The `/**` in the placeholder template represents com=
monly used paths for receive/change addresses, and is equivalent to `&lt;0;=
1&gt;`.<br><br>The placeholder `@i` for some number *i* represents the *i*-=
th key in the vector of key origin information (which must be of size at le=
ast *i* + 1, or the wallet policy is invalid).<br></div><div><br></div><div=
>=3D=3D=3D=3D Key informations vector =3D=3D=3D=3D<br><br>Each element of t=
he key origin information vector is a `KEY` expression.<br><br>- Optionally=
, key origin information, consisting of:<br>=C2=A0 - An open bracket `[`<br=
>=C2=A0 - Exactly 8 hex characters for the fingerprint of the master key fr=
om which this key is derived from (see [BIP32](<a href=3D"https://github.co=
m/bitcoin/bips/blob/master/bip-0032.mediawiki">https://github.com/bitcoin/b=
ips/blob/master/bip-0032.mediawiki</a>) for details)<br>=C2=A0 - Followed b=
y zero or more `/NUM&#39;` path elements to indicate hardened derivation st=
eps between the fingerprint and the xpub that follows<br>=C2=A0 - A closing=
 bracket `]`<br>- Followed by the actual key, which is either<br>=C2=A0 - a=
 hex-encoded pubkey, which is either<br>=C2=A0 =C2=A0 - inside=C2=A0`wpkh`=
=C2=A0and=C2=A0`wsh`, only compressed public keys are permitted (exactly 66=
 hex characters starting with `02` or `03`.<br>=C2=A0 =C2=A0 - inside `tr`,=
 x-only pubkeys are also permitted (exactly 64 hex characters).<br>=C2=A0 -=
 a serialized extended public key (`xpub`) (as defined in [BIP 32](<a href=
=3D"https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki">https:/=
/github.com/bitcoin/bips/blob/master/bip-0032.mediawiki</a>))<br><br>The pl=
aceholder `@i` for some number *i* represents the *i*-th key in the vector =
of key orIgin information=C2=A0(which must be of size at least *i* + 1, or =
the wallet policy is invalid).<br><br>The policy template is invalid if any=
 placeholder `@i` has derivation steps while the corresponding `(i+1)`-th e=
lement of the keys vector is not an xpub.<br><br>=3D=3D=3D=3D Additional ru=
les =3D=3D=3D=3D</div><div><br>The wallet policy is invalid if any placehol=
der expression with additional derivation steps is used when the correspond=
ing key information is not an xpub.<br><br>The key information vector *shou=
ld* be ordered so that placeholder `@i` never appear for the first time bef=
ore an occurrence of `@j` =C2=A0for some `j &lt; i`; for example, the first=
 placeholder is always `@0`, the next one is `@1`, etc.<br><br>=3D=3D=3D De=
scriptor derivation =3D=3D=3D</div><div><br>From a wallet descriptor templa=
te (and the associated vector of key informations), one can therefore obtai=
n the 1-dimensional descriptor for receive and change addresses by:<br><br>=
- replacing each key placeholder with the corresponding key origin informat=
ion;<br>- replacing every `/**` =C2=A0with `/0/*` for the receive descripto=
r, and `/1/*` for the change descriptor;<br>- replacing every `/&lt;M,N&gt;=
` with =C2=A0`/M` for the receive descriptor, and `/N` for the change descr=
iptor.<br><br>For example, the wallet descriptor `pkh(@0/**)` with key info=
rmation `[&quot;[d34db33f/44&#39;/0&#39;/0&#39;]xpub6ERApfZwUNrhLCkDtcHTcxd=
75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvL=
JuZZvRcEL&quot;]` produces the following two descriptors:<br><br>- Receive =
descriptor: `pkh([d34db33f/44&#39;/0&#39;/0&#39;]xpub6ERApfZwUNrhLCkDtcHTcx=
d75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJv=
LJuZZvRcEL/0/*)`<br><br>- Change descriptor: `pkh([d34db33f/44&#39;/0&#39;/=
0&#39;]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4=
koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/1/*)`<br><br>=3D=3D=3D Implemen=
tation guidelines =3D=3D=3D</div><div><br>Implementations must not necessar=
ily implement all of the possible wallet policies defined by this standard,=
 but it is recommended to clearly document any limitation. =C2=A0<br><br>Im=
plementations 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.=
<br><br>Any implementation in a general-purpose software wallet allowing ar=
bitrary scripts (or any scripts that involve external cosigners) should put=
 great care into a process for backing up a wallet policy. In fact, unlike =
typical single-signature scenarios, the seed alone is no longer enough to d=
iscover wallet policies with existing funds, and the loss of the backup is =
likely to lead to permanent loss of funds.<br><br>Avoiding key reuse among =
different wallet accounts is also extremely important, but out of scope for=
 this document.<br><br>=3D=3D Examples =3D=3D<br><br>Some examples of walle=
t descriptor templates (vectors of keys omitted for simplicity):</div><div>=
- Template for a native segwit account:</div><div>=C2=A0 wpkh(@0/**)<br><di=
v>- Template for a taproot BIP86 account:</div><div>=C2=A0 tr(@0/**)<br></d=
iv></div><div>- Template for a native segwit 2-of-3:</div><div>=C2=A0 wsh(s=
ortedmulti(2,@0/**,@1/**,@2/**))</div><div>- Template with miniscript for &=
quot;1 of 2 equally likely keys&quot;:</div><div>=C2=A0 wsh(or_b(pk(@0/**),=
s:pk(@1/**)))</div><div><br></div><div>More examples (esp. targeting minisc=
ript on taproot) will be added in the future.</div><div><br></div><div>=3D=
=3D References =3D=3D<br></div><div><br></div><div>* [1] - Output Script De=
scriptors: <a href=3D"https://github.com/bitcoin/bitcoin/blob/master/doc/de=
scriptors.md">https://github.com/bitcoin/bitcoin/blob/master/doc/descriptor=
s.md</a></div><div>* [2] - BIP-129 (Bitcoin Secure Multisig Setup): <a href=
=3D"https://github.com/bitcoin/bips/blob/master/bip-0129.mediawiki">https:/=
/github.com/bitcoin/bips/blob/master/bip-0129.mediawiki</a><br></div><div>*=
 [3] - BIP-44: <a href=3D"https://github.com/bitcoin/bips/blob/master/bip-0=
044.mediawiki">https://github.com/bitcoin/bips/blob/master/bip-0044.mediawi=
ki</a></div><div>* [4] - BIP-49: <a href=3D"https://github.com/bitcoin/bips=
/blob/master/bip-0049.mediawiki">https://github.com/bitcoin/bips/blob/maste=
r/bip-0049.mediawiki</a></div><div>* [5] - BIP-84: <a href=3D"https://githu=
b.com/bitcoin/bips/blob/master/bip-0084.mediawiki">https://github.com/bitco=
in/bips/blob/master/bip-0084.mediawiki</a></div><div>* [6] - BIP-86: <a hre=
f=3D"https://github.com/bitcoin/bips/blob/master/bip-0086.mediawiki">https:=
//github.com/bitcoin/bips/blob/master/bip-0086.mediawiki</a></div><div>* [7=
] - BIP-48: <a href=3D"https://github.com/bitcoin/bips/blob/master/bip-0048=
.mediawiki">https://github.com/bitcoin/bips/blob/master/bip-0048.mediawiki<=
/a></div><div>* [8] - BIP-87: <a href=3D"https://github.com/bitcoin/bips/bl=
ob/master/bip-0087.mediawiki">https://github.com/bitcoin/bips/blob/master/b=
ip-0087.mediawiki</a></div><div><br></div></div>

--00000000000082df1705de449dfa--