@@ -112,7 +112,129 @@ Wallet
112112- The wallet can create a transaction without change even when the keypool is
113113 empty. Previously it failed. (#17219 )
114114
115- #### Wallet RPC changes
115+ - The ` -salvagewallet ` startup option has been removed. A new ` salvage ` command
116+ has been added to the ` bitcoin-wallet ` tool which performs the salvage
117+ operations that ` -salvagewallet ` did. (#18918 )
118+
119+ ### Experimental Descriptor Wallets
120+
121+ Please note that Descriptor Wallets are still experimental and not all expected functionality
122+ is available. Additionally there may be some bugs and current functions may change in the future.
123+ Bugs and missing functionality can be reported to the [ issue tracker] ( https://github.com/bitcoin/bitcoin/issues ) .
124+
125+ 0.21 introduces a new type of wallet - Descriptor Wallets. Descriptor Wallets store
126+ scriptPubKey information using descriptors. This is in contrast to the Legacy Wallet
127+ structure where keys are used to generate scriptPubKeys and addresses. Because of this
128+ shift to being script based instead of key based, many of the confusing things that Legacy
129+ Wallets do are not possible with Descriptor Wallets. Descriptor Wallets use a definition
130+ of "mine" for scripts which is simpler and more intuitive than that used by Legacy Wallets.
131+ Descriptor Wallets also uses different semantics for watch-only things and imports.
132+
133+ As Descriptor Wallets are a new type of wallet, their introduction does not affect existing wallets.
134+ Users who already have a Bitcoin Core wallet can continue to use it as they did before without
135+ any change in behavior. Newly created Legacy Wallets (which is the default type of wallet) will
136+ behave as they did in previous versions of Bitcoin Core.
137+
138+ The differences between Descriptor Wallets and Legacy Wallets are largely limited to non user facing
139+ things. They are intended to behave similarly except for the import/export and watchonly functionality
140+ as described below.
141+
142+ #### Creating Descriptor Wallets
143+
144+ Descriptor Wallets are not created by default. They must be explicitly created using the
145+ ` createwallet ` RPC or via the GUI. A ` descriptors ` option has been added to ` createwallet ` .
146+ Setting ` descriptors ` to ` true ` will create a Descriptor Wallet instead of a Legacy Wallet.
147+
148+ In the GUI, a checkbox has been added to the Create Wallet Dialog to indicate that a
149+ Descriptor Wallet should be created.
150+
151+ Without those options being set, a Legacy Wallet will be created instead. Additionally the
152+ Default Wallet created upon first startup of Bitcoin Core will be a Legacy Wallet.
153+
154+ #### ` IsMine ` Semantics
155+
156+ ` IsMine ` refers to the function used to determine whether a script belongs to the wallet.
157+ This is used to determine whether an output belongs to the wallet. ` IsMine ` in Legacy Wallets
158+ returns true if the wallet would be able to sign an input that spends an output with that script.
159+ Since keys can be involved in a variety of different scripts, this definition for ` IsMine ` can
160+ lead to many unexpected scripts being considered part of the wallet.
161+
162+ With Descriptor Wallets, descriptors explicitly specify the set of scripts that are owned by
163+ the wallet. Since descriptors are deterministic and easily enumerable, users will know exactly
164+ what scripts the wallet will consider to belong to it. Additionally the implementation of ` IsMine `
165+ in Descriptor Wallets is far simpler than for Legacy Wallets. Notably, in Legacy Wallets, ` IsMine `
166+ allowed for users to take one type of address (e.g. P2PKH), mutate it into another address type
167+ (e.g. P2WPKH), and the wallet would still detect outputs sending to the new address type
168+ even without that address being requested from the wallet. Descriptor Wallets does not
169+ allow for this and will only watch for the addresses that were explicitly requested from the wallet.
170+
171+ These changes to ` IsMine ` will make it easier to reason about what scripts the wallet will
172+ actually be watching for in outputs. However for the vast majority of users, this change is
173+ largely transparent and will not have noticeable effect.
174+
175+ #### Imports and Exports
176+
177+ In Legacy Wallets, raw scripts and keys could be imported to the wallet. Those imported scripts
178+ and keys are treated separately from the keys generated by the wallet. This complicates the ` IsMine `
179+ logic as it has to distinguish between spendable and watchonly.
180+
181+ Descriptor Wallets handle importing scripts and keys differently. Only complete descriptors can be
182+ imported. These descriptors are then added to the wallet as if it were a descriptor generated by
183+ the wallet itself. This simplifies the ` IsMine ` logic so that it no longer has to distinguish
184+ between spendable and watchonly. As such, the watchonly model for Descriptor Wallets is also
185+ different and described in more detail in the next section.
186+
187+ To import into a Descriptor Wallet, a new ` importdescriptors ` RPC has been added that uses a syntax
188+ similar to that of ` importmulti ` .
189+
190+ As Legacy Wallets and Descriptor Wallets use different mechanisms for storing and importing scripts and keys
191+ the existing import RPCs have been disabled for descriptor wallets.
192+ New export RPCs for Descriptor Wallets have not yet been added.
193+
194+ The following RPCs are disabled for Descriptor Wallets:
195+
196+ * importprivkey
197+ * importpubkey
198+ * importaddress
199+ * importwallet
200+ * dumpprivkey
201+ * dumpwallet
202+ * importmulti
203+ * addmultisigaddress
204+ * sethdseed
205+
206+ #### Watchonly Wallets
207+
208+ A Legacy Wallet contains both private keys and scripts that were being watched.
209+ Those watched scripts would not contribute to your normal balance. In order to see the watchonly
210+ balance and to use watchonly things in transactions, an ` include_watchonly ` option was added
211+ to many RPCs that would allow users to do that. However it is easy to forget to include this option.
212+
213+ Descriptor Wallets move to a per-wallet watchonly model. Instead an entire wallet is considered to be
214+ watchonly depending on whether it was created with private keys disabled. This eliminates the need
215+ to distinguish between things that are watchonly and things that are not within a wallet itself.
216+
217+ This change does have a caveat. If a Descriptor Wallet with private keys * enabled* has
218+ a multiple key descriptor without all of the private keys (e.g. ` multi(...) ` with only one private key),
219+ then the wallet will fail to sign and broadcast transactions. Such wallets would need to use the PSBT
220+ workflow but the typical GUI Send, ` sendtoaddress ` , etc. workflows would still be available, just
221+ non-functional.
222+
223+ This issue is worsened if the wallet contains both single key (e.g. ` wpkh(...) ` ) descriptors and such
224+ multiple key descriptors as some transactions could be signed and broadast and others not. This is
225+ due to some transactions containing only single key inputs, while others would contain both single
226+ key and multiple key inputs, depending on which are available and how the coin selection algorithm
227+ selects inputs. However this is not considered to be a supported use case; multisigs
228+ should be in their own wallets which do not already have descriptors. Although users cannot export
229+ descriptors with private keys for now as explained earlier.
230+
231+ #### BIP 44/49/84 Support
232+
233+ The change to using descriptors changes the default derivation paths used by Bitcoin Core
234+ to adhere to BIP 44/49/84. Descriptors with different derivation paths can be imported without
235+ issue.
236+
237+ ### Wallet RPC changes
116238
117239- The ` upgradewallet ` RPC replaces the ` -upgradewallet ` command line option.
118240 (#15761 )
0 commit comments