|
| 1 | +Wallet |
| 2 | +------ |
| 3 | + |
| 4 | +### Experimental Descriptor Wallets |
| 5 | + |
| 6 | +Please note that Descriptor Wallets are still experimental and not all expected functionality |
| 7 | +is available. Additionally there may be some bugs and current functions may change in the future. |
| 8 | +Bugs and missing functionality can be reported to the [issue tracker](https://github.com/bitcoin/bitcoin/issues). |
| 9 | + |
| 10 | +0.21 introduces a new type of wallet - Descriptor Wallets. Descriptor Wallets store |
| 11 | +scriptPubKey information using descriptors. This is in contrast to the Legacy Wallet |
| 12 | +structure where keys are used to generate scriptPubKeys and addresses. Because of this |
| 13 | +shift to being script based instead of key based, many of the confusing things that Legacy |
| 14 | +Wallets do are not possible with Descriptor Wallets. Descriptor Wallets use a definition |
| 15 | +of "mine" for scripts which is simpler and more intuitive than that used by Legacy Wallets. |
| 16 | +Descriptor Wallets also uses different semantics for watch-only things and imports. |
| 17 | + |
| 18 | +As Descriptor Wallets are a new type of wallet, their introduction does not affect existing wallets. |
| 19 | +Users who already have a Bitcoin Core wallet can continue to use it as they did before without |
| 20 | +any change in behavior. Newly created Legacy Wallets (which is the default type of wallet) will |
| 21 | +behave as they did in previous versions of Bitcoin Core. |
| 22 | + |
| 23 | +The differences between Descriptor Wallets and Legacy Wallets are largely limited to non user facing |
| 24 | +things. They are intended to behave similarly except for the import/export and watchonly functionality |
| 25 | +as described below. |
| 26 | + |
| 27 | +#### Creating Descriptor Wallets |
| 28 | + |
| 29 | +Descriptor Wallets are not created by default. They must be explicitly created using the |
| 30 | +`createwallet` RPC or via the GUI. A `descriptors` option has been added to `createwallet`. |
| 31 | +Setting `descriptors` to `true` will create a Descriptor Wallet instead of a Legacy Wallet. |
| 32 | + |
| 33 | +In the GUI, a checkbox has been added to the Create Wallet Dialog to indicate that a |
| 34 | +Descriptor Wallet should be created. |
| 35 | + |
| 36 | +Without those options being set, a Legacy Wallet will be created instead. Additionally the |
| 37 | +Default Wallet created upon first startup of Bitcoin Core will be a Legacy Wallet. |
| 38 | + |
| 39 | +#### `IsMine` Semantics |
| 40 | + |
| 41 | +`IsMine` refers to the function used to determine whether a script belongs to the wallet. |
| 42 | +This is used to determine whether an output belongs to the wallet. `IsMine` in Legacy Wallets |
| 43 | +returns true if the wallet would be able to sign an input that spends an output with that script. |
| 44 | +Since keys can be involved in a variety of different scripts, this definition for `IsMine` can |
| 45 | +lead to many unexpected scripts being considered part of the wallet. |
| 46 | + |
| 47 | +With Descriptor Wallets, descriptors explicitly specify the set of scripts that are owned by |
| 48 | +the wallet. Since descriptors are deterministic and easily enumerable, users will know exactly |
| 49 | +what scripts the wallet will consider to belong to it. Additionally the implementation of `IsMine` |
| 50 | +in Descriptor Wallets is far simpler than for Legacy Wallets. Notably, in Legacy Wallets, `IsMine` |
| 51 | +allowed for users to take one type of address (e.g. P2PKH), mutate it into another address type |
| 52 | +(e.g. P2WPKH), and the wallet would still detect outputs sending to the new address type |
| 53 | +even without that address being requested from the wallet. Descriptor Wallets does not |
| 54 | +allow for this and will only watch for the addresses that were explicitly requested from the wallet. |
| 55 | + |
| 56 | +These changes to `IsMine` will make it easier to reason about what scripts the wallet will |
| 57 | +actually be watching for in outputs. However for the vast majority of users, this change is |
| 58 | +largely transparent and will not have noticeable effect. |
| 59 | + |
| 60 | +#### Imports and Exports |
| 61 | + |
| 62 | +In Legacy Wallets, raw scripts and keys could be imported to the wallet. Those imported scripts |
| 63 | +and keys are treated separately from the keys generated by the wallet. This complicates the `IsMine` |
| 64 | +logic as it has to distinguish between spendable and watchonly. |
| 65 | + |
| 66 | +Descriptor Wallets handle importing scripts and keys differently. Only complete descriptors can be |
| 67 | +imported. These descriptors are then added to the wallet as if it were a descriptor generated by |
| 68 | +the wallet itself. This simplifies the `IsMine` logic so that it no longer has to distinguish |
| 69 | +between spendable and watchonly. As such, the watchonly model for Descriptor Wallets is also |
| 70 | +different and described in more detail in the next section. |
| 71 | + |
| 72 | +To import into a Descriptor Wallet, a new `importdescriptors` RPC has been added that uses a syntax |
| 73 | +similar to that of `importmulti`. |
| 74 | + |
| 75 | +As Legacy Wallets and Descriptor Wallets use different mechanisms for storing and importing scripts and keys |
| 76 | +the existing import RPCs have been disabled for descriptor wallets. |
| 77 | +New export RPCs for Descriptor Wallets have not yet been added. |
| 78 | + |
| 79 | +The following RPCs are disabled for Descriptor Wallets: |
| 80 | + |
| 81 | +* importprivkey |
| 82 | +* importpubkey |
| 83 | +* importaddress |
| 84 | +* importwallet |
| 85 | +* dumpprivkey |
| 86 | +* dumpwallet |
| 87 | +* importmulti |
| 88 | +* addmultisigaddress |
| 89 | +* sethdseed |
| 90 | + |
| 91 | +#### Watchonly Wallets |
| 92 | + |
| 93 | +A Legacy Wallet contains both private keys and scripts that were being watched. |
| 94 | +Those watched scripts would not contribute to your normal balance. In order to see the watchonly |
| 95 | +balance and to use watchonly things in transactions, an `include_watchonly` option was added |
| 96 | +to many RPCs that would allow users to do that. However it is easy to forget to include this option. |
| 97 | + |
| 98 | +Descriptor Wallets move to a per-wallet watchonly model. Instead an entire wallet is considered to be |
| 99 | +watchonly depending on whether it was created with private keys disabled. This eliminates the need |
| 100 | +to distinguish between things that are watchonly and things that are not within a wallet itself. |
| 101 | + |
| 102 | +This change does have a caveat. If a Descriptor Wallet with private keys *enabled* has |
| 103 | +a multiple key descriptor without all of the private keys (e.g. `multi(...)` with only one private key), |
| 104 | +then the wallet will fail to sign and broadcast transactions. Such wallets would need to use the PSBT |
| 105 | +workflow but the typical GUI Send, `sendtoaddress`, etc. workflows would still be available, just |
| 106 | +non-functional. |
| 107 | + |
| 108 | +This issue is worsened if the wallet contains both single key (e.g. `wpkh(...)`) descriptors and such |
| 109 | +multiple key descriptors as some transactions could be signed and broadast and others not. This is |
| 110 | +due to some transactions containing only single key inputs, while others would contain both single |
| 111 | +key and multiple key inputs, depending on which are available and how the coin selection algorithm |
| 112 | +selects inputs. However this is not considered to be a supported use case; multisigs |
| 113 | +should be in their own wallets which do not already have descriptors. Although users cannot export |
| 114 | +descriptors with private keys for now as explained earlier. |
| 115 | + |
| 116 | +#### BIP 44/49/84 Support |
| 117 | + |
| 118 | +The change to using descriptors changes the default derivation paths used by Bitcoin Core |
| 119 | +to adhere to BIP 44/49/84. Descriptors with different derivation paths can be imported without |
| 120 | +issue. |
0 commit comments