Inside Bitcoin

251
252New settings
253------------
254
255- The `startupnotify` option is used to specify a command to
256  execute when Bitcoin Core has finished with its startup
257  sequence. (#15367)
258
259Wallet
260------
261
262- Backwards compatibility has been dropped for two `getaddressinfo` RPC
263  deprecations, as notified in the 0.20 release notes. The deprecated `label`
264  field has been removed as well as the deprecated `labels` behavior of
265  returning a JSON object containing `name` and `purpose` key-value pairs. Since
266  0.20, the `labels` field returns a JSON array of label names. (#19200)
267
268- To improve wallet privacy, the frequency of wallet rebroadcast attempts is
269  reduced from approximately once every 15 minutes to once every 12-36 hours.
270  To maintain a similar level of guarantee for initial broadcast of wallet
271  transactions, the mempool tracks these transactions as a part of the newly
272  introduced unbroadcast set. See the "P2P and network changes" section for
273  more information on the unbroadcast set. (#18038)
274
275- The `sendtoaddress` and `sendmany` RPCs accept an optional `verbose=True`
276  argument to also return the fee reason about the sent tx. (#19501)
277
278- The wallet can create a transaction without change even when the keypool is
279  empty. Previously it failed. (#17219)
280
281- The `-salvagewallet` startup option has been removed. A new `salvage` command
282  has been added to the `bitcoin-wallet` tool which performs the salvage
283  operations that `-salvagewallet` did. (#18918)
284
285- A new configuration flag `-maxapsfee` has been added, which sets the max
286  allowed avoid partial spends (APS) fee. It defaults to 0 (i.e. fee is the
287  same with and without APS). Setting it to -1 will disable APS, unless
288  `-avoidpartialspends` is set. (#14582)
289
290- The wallet will now avoid partial spends (APS) by default, if this does not
291  result in a difference in fees compared to the non-APS variant. The allowed
292  fee threshold can be adjusted using the new `-maxapsfee` configuration
293  option. (#14582)
294
295- The `createwallet`, `loadwallet`, and `unloadwallet` RPCs now accept
296  `load_on_startup` options to modify the settings list. Unless these options
297  are explicitly set to true or false, the list is not modified, so the RPC
298  methods remain backwards compatible. (#15937)
299
300- A new `send` RPC with similar syntax to `walletcreatefundedpsbt`, including
301  support for coin selection and a custom fee rate, is added. The `send` RPC is
302  experimental and may change in subsequent releases. (#16378)
303
304- The `estimate_mode` parameter is now case-insensitive in the `bumpfee`,
305  `fundrawtransaction`, `sendmany`, `sendtoaddress`, `send` and
306  `walletcreatefundedpsbt` RPCs. (#11413)
307
308- The `bumpfee` RPC now uses `conf_target` rather than `confTarget` in the
309  options. (#11413)
310
311- `fundrawtransaction` and `walletcreatefundedpsbt` when used with the
312  `lockUnspents` argument now lock manually selected coins, in addition to
313  automatically selected coins. Note that locked coins are never used in
314  automatic coin selection, but can still be manually selected. (#18244)
315
316- The `-zapwallettxes` startup option has been removed and its functionality
317  removed from the wallet.  This option was originally intended to allow for
318  rescuing wallets which were affected by a malleability attack. More recently,
319  it has been used in the fee bumping of transactions that did not signal RBF.
320  This functionality has been superseded with the abandon transaction feature. (#19671)
321
322- The error code when no wallet is loaded, but a wallet RPC is called, has been
323  changed from `-32601` (method not found) to `-18` (wallet not found).
324  (#20101)
325
326### Automatic wallet creation removed
327
328Bitcoin Core will no longer automatically create new wallets on startup. It will
329load existing wallets specified by `-wallet` options on the command line or in
330`bitcoin.conf` or `settings.json` files. And by default it will also load a
331top-level unnamed ("") wallet. However, if specified wallets don't exist,
332Bitcoin Core will now just log warnings instead of creating new wallets with
333new keys and addresses like previous releases did.
334
335New wallets can be created through the GUI (which has a more prominent create
336wallet option), through the `bitcoin-cli createwallet` or `bitcoin-wallet
337create` commands, or the `createwallet` RPC. (#15454, #20186)
338
339### Experimental Descriptor Wallets
340
341Please note that Descriptor Wallets are still experimental and not all expected functionality
342is available. Additionally there may be some bugs and current functions may change in the future.
343Bugs and missing functionality can be reported to the [issue tracker](https://github.com/bitcoin/bitcoin/issues).
344
3450.21 introduces a new type of wallet - Descriptor Wallets. Descriptor Wallets store
346scriptPubKey information using output descriptors. This is in contrast to the Legacy Wallet
347structure where keys are used to implicitly generate scriptPubKeys and addresses. Because of this
348shift to being script based instead of key based, many of the confusing things that Legacy
349Wallets do are not possible with Descriptor Wallets. Descriptor Wallets use a definition
350of "mine" for scripts which is simpler and more intuitive than that used by Legacy Wallets.
351Descriptor Wallets also uses different semantics for watch-only things and imports.
352
353As Descriptor Wallets are a new type of wallet, their introduction does not affect existing wallets.
354Users who already have a Bitcoin Core wallet can continue to use it as they did before without
355any change in behavior. Newly created Legacy Wallets (which remains the default type of wallet) will
356behave as they did in previous versions of Bitcoin Core.
357
358The differences between Descriptor Wallets and Legacy Wallets are largely limited to non user facing
359things. They are intended to behave similarly except for the import/export and watchonly functionality
360as described below.
361
362#### Creating Descriptor Wallets
363
364Descriptor wallets are not the default type of wallet.
365
366In the GUI, a checkbox has been added to the Create Wallet Dialog to indicate that a
367Descriptor Wallet should be created. And a `descriptors` option has been added to `createwallet` RPC.
368Setting `descriptors` to `true` will create a Descriptor Wallet instead of a Legacy Wallet.
369
370Without those options being set, a Legacy Wallet will be created instead.
371
372#### `IsMine` Semantics
373
374`IsMine` refers to the function used to determine whether a script belongs to the wallet.
375This is used to determine whether an output belongs to the wallet. `IsMine` in Legacy Wallets
376returns true if the wallet would be able to sign an input that spends an output with that script.
377Since keys can be involved in a variety of different scripts, this definition for `IsMine` can
378lead to many unexpected scripts being considered part of the wallet.
379
380With Descriptor Wallets, descriptors explicitly specify the set of scripts that are owned by
381the wallet. Since descriptors are deterministic and easily enumerable, users will know exactly
382what scripts the wallet will consider to belong to it. Additionally the implementation of `IsMine`
383in Descriptor Wallets is far simpler than for Legacy Wallets. Notably, in Legacy Wallets, `IsMine`
384allowed for users to take one type of address (e.g. P2PKH), mutate it into another address type
385(e.g. P2WPKH), and the wallet would still detect outputs sending to the new address type
386even without that address being requested from the wallet. Descriptor Wallets do not
387allow for this and will only watch for the addresses that were explicitly requested from the wallet.
388
389These changes to `IsMine` will make it easier to reason about what scripts the wallet will
390actually be watching for in outputs. However for the vast majority of users, this change is
391largely transparent and will not have noticeable effect.
392
393#### Imports and Exports
394
395In Legacy Wallets, raw scripts and keys could be imported to the wallet. Those imported scripts
396and keys are treated separately from the keys generated by the wallet. This complicates the `IsMine`
397logic as it has to distinguish between spendable and watchonly.
398
399Descriptor Wallets handle importing scripts and keys differently. Only complete descriptors can be
400imported. These descriptors are then added to the wallet as if it were a descriptor generated by
401the wallet itself. This simplifies the `IsMine` logic so that it no longer has to distinguish
402between spendable and watchonly. As such, the watchonly model for Descriptor Wallets is also
403different and described in more detail in the next section.
404
405To import into a Descriptor Wallet, a new `importdescriptors` RPC has been added that uses a syntax
406similar to that of `importmulti`.
407
408As Legacy Wallets and Descriptor Wallets use different mechanisms for storing and importing scripts and keys
409the existing import RPCs have been disabled for descriptor wallets.
410New export RPCs for Descriptor Wallets have not yet been added.
411
412The following RPCs are disabled for Descriptor Wallets:
413
414* `importprivkey`
415* `importpubkey`
416* `importaddress`
417* `importwallet`
418* `dumpprivkey`
419* `dumpwallet`
420* `importmulti`
421* `addmultisigaddress`
422* `sethdseed`
423
424#### Watchonly Wallets
425
426A Legacy Wallet contains both private keys and scripts that were being watched.
427Those watched scripts would not contribute to your normal balance. In order to see the watchonly
428balance and to use watchonly things in transactions, an `include_watchonly` option was added
429to many RPCs that would allow users to do that. However it is easy to forget to include this option.
430
431Descriptor Wallets move to a per-wallet watchonly model. Instead an entire wallet is considered to be
432watchonly depending on whether it was created with private keys disabled. This eliminates the need
433to distinguish between things that are watchonly and things that are not within a wallet itself.
434
435This change does have a caveat. If a Descriptor Wallet with private keys *enabled* has
436a multiple key descriptor without all of the private keys (e.g. `multi(...)` with only one private key),
437then the wallet will fail to sign and broadcast transactions. Such wallets would need to use the PSBT
438workflow but the typical GUI Send, `sendtoaddress`, etc. workflows would still be available, just
439non-functional.
440
441This issue is worsened if the wallet contains both single key (e.g. `wpkh(...)`) descriptors and such
442multiple key descriptors as some transactions could be signed and broadcast and others not. This is
443due to some transactions containing only single key inputs, while others would contain both single
444key and multiple key inputs, depending on which are available and how the coin selection algorithm
445selects inputs. However this is not considered to be a supported use case; multisigs
446should be in their own wallets which do not already have descriptors. Although users cannot export
447descriptors with private keys for now as explained earlier.
448
449#### BIP 44/49/84 Support
450
451The change to using descriptors changes the default derivation paths used by Bitcoin Core
452to adhere to BIP 44/49/84. Descriptors with different derivation paths can be imported without
453issue.
454
455#### SQLite Database Backend
456
457Descriptor wallets use SQLite for the wallet file instead of the Berkeley DB used in legacy wallets.
458This will break compatibility with any existing tooling that operates on wallets, however compatibility
459was already being broken by the move to descriptors.
460
461### Wallet RPC changes
462
463- The `upgradewallet` RPC replaces the `-upgradewallet` command line option.
464  (#15761)
465
466- The `settxfee` RPC will fail if the fee was set higher than the `-maxtxfee`
467  command line setting. The wallet will already fail to create transactions
468  with fees higher than `-maxtxfee`. (#18467)
469
470- A new `fee_rate` parameter/option denominated in satoshis per vbyte (sat/vB)
471  is introduced to the `sendtoaddress`, `sendmany`, `fundrawtransaction` and
472  `walletcreatefundedpsbt` RPCs as well as to the experimental new `send`
473  RPC. The legacy `feeRate` option in `fundrawtransaction` and
474  `walletcreatefundedpsbt` still exists for setting a fee rate in BTC per 1,000
475  vbytes (BTC/kvB), but it is expected to be deprecated soon to avoid
476  confusion. For these RPCs, the fee rate error message is updated from BTC/kB
477  to sat/vB and the help documentation in BTC/kB is updated to BTC/kvB. The
478  `send` and `sendtoaddress` RPC examples are updated to aid users in creating
479  transactions with explicit fee rates. (#20305, #11413)
480
481- The `bumpfee` RPC `fee_rate` option is changed from BTC/kvB to sat/vB and the
482  help documentation is updated. Users are warned that this is a breaking API
483  change, but it should be relatively benign: the large (100,000 times)
484  difference between BTC/kvB and sat/vB units means that a transaction with a
485  fee rate mistakenly calculated in BTC/kvB rather than sat/vB should raise an
486  error due to the fee rate being set too low. In the worst case, the
487  transaction may send at 1 sat/vB, but as Replace-by-Fee (BIP125 RBF) is active
488  by default when an explicit fee rate is used, the transaction fee can be
489  bumped. (#20305)
490
491GUI changes
492-----------
493
494- Wallets created or loaded in the GUI will now be automatically loaded on
495  startup, so they don't need to be manually reloaded next time Bitcoin Core is
496  started. The list of wallets to load on startup is stored in
497  `\<datadir\>/settings.json` and augments any command line or `bitcoin.conf`
498  `-wallet=` settings that specify more wallets to load. Wallets that are
499  unloaded in the GUI get removed from the settings list so they won't load
500  again automatically next startup. (#19754)