mirror of
https://github.com/bitcoin/bitcoin.git
synced 2025-01-25 10:43:19 -03:00
doc: Move 0.21 fragments into the main release notes
This commit is contained in:
MarcoFalke
parent
fa1a91657f
commit
fa13c180c7
3 changed files with 123 additions and 124 deletions
|
|
@ -1,120 +0,0 @@
|
|||
Wallet
|
||||
------
|
||||
|
||||
### Experimental Descriptor Wallets
|
||||
|
||||
Please note that Descriptor Wallets are still experimental and not all expected functionality
|
||||
is available. Additionally there may be some bugs and current functions may change in the future.
|
||||
Bugs and missing functionality can be reported to the [issue tracker](https://github.com/bitcoin/bitcoin/issues).
|
||||
|
||||
0.21 introduces a new type of wallet - Descriptor Wallets. Descriptor Wallets store
|
||||
scriptPubKey information using descriptors. This is in contrast to the Legacy Wallet
|
||||
structure where keys are used to generate scriptPubKeys and addresses. Because of this
|
||||
shift to being script based instead of key based, many of the confusing things that Legacy
|
||||
Wallets do are not possible with Descriptor Wallets. Descriptor Wallets use a definition
|
||||
of "mine" for scripts which is simpler and more intuitive than that used by Legacy Wallets.
|
||||
Descriptor Wallets also uses different semantics for watch-only things and imports.
|
||||
|
||||
As Descriptor Wallets are a new type of wallet, their introduction does not affect existing wallets.
|
||||
Users who already have a Bitcoin Core wallet can continue to use it as they did before without
|
||||
any change in behavior. Newly created Legacy Wallets (which is the default type of wallet) will
|
||||
behave as they did in previous versions of Bitcoin Core.
|
||||
|
||||
The differences between Descriptor Wallets and Legacy Wallets are largely limited to non user facing
|
||||
things. They are intended to behave similarly except for the import/export and watchonly functionality
|
||||
as described below.
|
||||
|
||||
#### Creating Descriptor Wallets
|
||||
|
||||
Descriptor Wallets are not created by default. They must be explicitly created using the
|
||||
`createwallet` RPC or via the GUI. A `descriptors` option has been added to `createwallet`.
|
||||
Setting `descriptors` to `true` will create a Descriptor Wallet instead of a Legacy Wallet.
|
||||
|
||||
In the GUI, a checkbox has been added to the Create Wallet Dialog to indicate that a
|
||||
Descriptor Wallet should be created.
|
||||
|
||||
Without those options being set, a Legacy Wallet will be created instead. Additionally the
|
||||
Default Wallet created upon first startup of Bitcoin Core will be a Legacy Wallet.
|
||||
|
||||
#### `IsMine` Semantics
|
||||
|
||||
`IsMine` refers to the function used to determine whether a script belongs to the wallet.
|
||||
This is used to determine whether an output belongs to the wallet. `IsMine` in Legacy Wallets
|
||||
returns true if the wallet would be able to sign an input that spends an output with that script.
|
||||
Since keys can be involved in a variety of different scripts, this definition for `IsMine` can
|
||||
lead to many unexpected scripts being considered part of the wallet.
|
||||
|
||||
With Descriptor Wallets, descriptors explicitly specify the set of scripts that are owned by
|
||||
the wallet. Since descriptors are deterministic and easily enumerable, users will know exactly
|
||||
what scripts the wallet will consider to belong to it. Additionally the implementation of `IsMine`
|
||||
in Descriptor Wallets is far simpler than for Legacy Wallets. Notably, in Legacy Wallets, `IsMine`
|
||||
allowed for users to take one type of address (e.g. P2PKH), mutate it into another address type
|
||||
(e.g. P2WPKH), and the wallet would still detect outputs sending to the new address type
|
||||
even without that address being requested from the wallet. Descriptor Wallets does not
|
||||
allow for this and will only watch for the addresses that were explicitly requested from the wallet.
|
||||
|
||||
These changes to `IsMine` will make it easier to reason about what scripts the wallet will
|
||||
actually be watching for in outputs. However for the vast majority of users, this change is
|
||||
largely transparent and will not have noticeable effect.
|
||||
|
||||
#### Imports and Exports
|
||||
|
||||
In Legacy Wallets, raw scripts and keys could be imported to the wallet. Those imported scripts
|
||||
and keys are treated separately from the keys generated by the wallet. This complicates the `IsMine`
|
||||
logic as it has to distinguish between spendable and watchonly.
|
||||
|
||||
Descriptor Wallets handle importing scripts and keys differently. Only complete descriptors can be
|
||||
imported. These descriptors are then added to the wallet as if it were a descriptor generated by
|
||||
the wallet itself. This simplifies the `IsMine` logic so that it no longer has to distinguish
|
||||
between spendable and watchonly. As such, the watchonly model for Descriptor Wallets is also
|
||||
different and described in more detail in the next section.
|
||||
|
||||
To import into a Descriptor Wallet, a new `importdescriptors` RPC has been added that uses a syntax
|
||||
similar to that of `importmulti`.
|
||||
|
||||
As Legacy Wallets and Descriptor Wallets use different mechanisms for storing and importing scripts and keys
|
||||
the existing import RPCs have been disabled for descriptor wallets.
|
||||
New export RPCs for Descriptor Wallets have not yet been added.
|
||||
|
||||
The following RPCs are disabled for Descriptor Wallets:
|
||||
|
||||
* importprivkey
|
||||
* importpubkey
|
||||
* importaddress
|
||||
* importwallet
|
||||
* dumpprivkey
|
||||
* dumpwallet
|
||||
* importmulti
|
||||
* addmultisigaddress
|
||||
* sethdseed
|
||||
|
||||
#### Watchonly Wallets
|
||||
|
||||
A Legacy Wallet contains both private keys and scripts that were being watched.
|
||||
Those watched scripts would not contribute to your normal balance. In order to see the watchonly
|
||||
balance and to use watchonly things in transactions, an `include_watchonly` option was added
|
||||
to many RPCs that would allow users to do that. However it is easy to forget to include this option.
|
||||
|
||||
Descriptor Wallets move to a per-wallet watchonly model. Instead an entire wallet is considered to be
|
||||
watchonly depending on whether it was created with private keys disabled. This eliminates the need
|
||||
to distinguish between things that are watchonly and things that are not within a wallet itself.
|
||||
|
||||
This change does have a caveat. If a Descriptor Wallet with private keys *enabled* has
|
||||
a multiple key descriptor without all of the private keys (e.g. `multi(...)` with only one private key),
|
||||
then the wallet will fail to sign and broadcast transactions. Such wallets would need to use the PSBT
|
||||
workflow but the typical GUI Send, `sendtoaddress`, etc. workflows would still be available, just
|
||||
non-functional.
|
||||
|
||||
This issue is worsened if the wallet contains both single key (e.g. `wpkh(...)`) descriptors and such
|
||||
multiple key descriptors as some transactions could be signed and broadast and others not. This is
|
||||
due to some transactions containing only single key inputs, while others would contain both single
|
||||
key and multiple key inputs, depending on which are available and how the coin selection algorithm
|
||||
selects inputs. However this is not considered to be a supported use case; multisigs
|
||||
should be in their own wallets which do not already have descriptors. Although users cannot export
|
||||
descriptors with private keys for now as explained earlier.
|
||||
|
||||
#### BIP 44/49/84 Support
|
||||
|
||||
The change to using descriptors changes the default derivation paths used by Bitcoin Core
|
||||
to adhere to BIP 44/49/84. Descriptors with different derivation paths can be imported without
|
||||
issue.
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# Wallet
|
||||
|
||||
The `-salvagewallet` startup option has been removed. A new `salvage` command has been added to the `bitcoin-wallet` tool which performs the salvage operations that `-salvagewallet` did.
|
||||
|
|
@ -112,7 +112,129 @@ Wallet
|
|||
- The wallet can create a transaction without change even when the keypool is
|
||||
empty. Previously it failed. (#17219)
|
||||
|
||||
#### Wallet RPC changes
|
||||
- The `-salvagewallet` startup option has been removed. A new `salvage` command
|
||||
has been added to the `bitcoin-wallet` tool which performs the salvage
|
||||
operations that `-salvagewallet` did. (#18918)
|
||||
|
||||
### Experimental Descriptor Wallets
|
||||
|
||||
Please note that Descriptor Wallets are still experimental and not all expected functionality
|
||||
is available. Additionally there may be some bugs and current functions may change in the future.
|
||||
Bugs and missing functionality can be reported to the [issue tracker](https://github.com/bitcoin/bitcoin/issues).
|
||||
|
||||
0.21 introduces a new type of wallet - Descriptor Wallets. Descriptor Wallets store
|
||||
scriptPubKey information using descriptors. This is in contrast to the Legacy Wallet
|
||||
structure where keys are used to generate scriptPubKeys and addresses. Because of this
|
||||
shift to being script based instead of key based, many of the confusing things that Legacy
|
||||
Wallets do are not possible with Descriptor Wallets. Descriptor Wallets use a definition
|
||||
of "mine" for scripts which is simpler and more intuitive than that used by Legacy Wallets.
|
||||
Descriptor Wallets also uses different semantics for watch-only things and imports.
|
||||
|
||||
As Descriptor Wallets are a new type of wallet, their introduction does not affect existing wallets.
|
||||
Users who already have a Bitcoin Core wallet can continue to use it as they did before without
|
||||
any change in behavior. Newly created Legacy Wallets (which is the default type of wallet) will
|
||||
behave as they did in previous versions of Bitcoin Core.
|
||||
|
||||
The differences between Descriptor Wallets and Legacy Wallets are largely limited to non user facing
|
||||
things. They are intended to behave similarly except for the import/export and watchonly functionality
|
||||
as described below.
|
||||
|
||||
#### Creating Descriptor Wallets
|
||||
|
||||
Descriptor Wallets are not created by default. They must be explicitly created using the
|
||||
`createwallet` RPC or via the GUI. A `descriptors` option has been added to `createwallet`.
|
||||
Setting `descriptors` to `true` will create a Descriptor Wallet instead of a Legacy Wallet.
|
||||
|
||||
In the GUI, a checkbox has been added to the Create Wallet Dialog to indicate that a
|
||||
Descriptor Wallet should be created.
|
||||
|
||||
Without those options being set, a Legacy Wallet will be created instead. Additionally the
|
||||
Default Wallet created upon first startup of Bitcoin Core will be a Legacy Wallet.
|
||||
|
||||
#### `IsMine` Semantics
|
||||
|
||||
`IsMine` refers to the function used to determine whether a script belongs to the wallet.
|
||||
This is used to determine whether an output belongs to the wallet. `IsMine` in Legacy Wallets
|
||||
returns true if the wallet would be able to sign an input that spends an output with that script.
|
||||
Since keys can be involved in a variety of different scripts, this definition for `IsMine` can
|
||||
lead to many unexpected scripts being considered part of the wallet.
|
||||
|
||||
With Descriptor Wallets, descriptors explicitly specify the set of scripts that are owned by
|
||||
the wallet. Since descriptors are deterministic and easily enumerable, users will know exactly
|
||||
what scripts the wallet will consider to belong to it. Additionally the implementation of `IsMine`
|
||||
in Descriptor Wallets is far simpler than for Legacy Wallets. Notably, in Legacy Wallets, `IsMine`
|
||||
allowed for users to take one type of address (e.g. P2PKH), mutate it into another address type
|
||||
(e.g. P2WPKH), and the wallet would still detect outputs sending to the new address type
|
||||
even without that address being requested from the wallet. Descriptor Wallets does not
|
||||
allow for this and will only watch for the addresses that were explicitly requested from the wallet.
|
||||
|
||||
These changes to `IsMine` will make it easier to reason about what scripts the wallet will
|
||||
actually be watching for in outputs. However for the vast majority of users, this change is
|
||||
largely transparent and will not have noticeable effect.
|
||||
|
||||
#### Imports and Exports
|
||||
|
||||
In Legacy Wallets, raw scripts and keys could be imported to the wallet. Those imported scripts
|
||||
and keys are treated separately from the keys generated by the wallet. This complicates the `IsMine`
|
||||
logic as it has to distinguish between spendable and watchonly.
|
||||
|
||||
Descriptor Wallets handle importing scripts and keys differently. Only complete descriptors can be
|
||||
imported. These descriptors are then added to the wallet as if it were a descriptor generated by
|
||||
the wallet itself. This simplifies the `IsMine` logic so that it no longer has to distinguish
|
||||
between spendable and watchonly. As such, the watchonly model for Descriptor Wallets is also
|
||||
different and described in more detail in the next section.
|
||||
|
||||
To import into a Descriptor Wallet, a new `importdescriptors` RPC has been added that uses a syntax
|
||||
similar to that of `importmulti`.
|
||||
|
||||
As Legacy Wallets and Descriptor Wallets use different mechanisms for storing and importing scripts and keys
|
||||
the existing import RPCs have been disabled for descriptor wallets.
|
||||
New export RPCs for Descriptor Wallets have not yet been added.
|
||||
|
||||
The following RPCs are disabled for Descriptor Wallets:
|
||||
|
||||
* importprivkey
|
||||
* importpubkey
|
||||
* importaddress
|
||||
* importwallet
|
||||
* dumpprivkey
|
||||
* dumpwallet
|
||||
* importmulti
|
||||
* addmultisigaddress
|
||||
* sethdseed
|
||||
|
||||
#### Watchonly Wallets
|
||||
|
||||
A Legacy Wallet contains both private keys and scripts that were being watched.
|
||||
Those watched scripts would not contribute to your normal balance. In order to see the watchonly
|
||||
balance and to use watchonly things in transactions, an `include_watchonly` option was added
|
||||
to many RPCs that would allow users to do that. However it is easy to forget to include this option.
|
||||
|
||||
Descriptor Wallets move to a per-wallet watchonly model. Instead an entire wallet is considered to be
|
||||
watchonly depending on whether it was created with private keys disabled. This eliminates the need
|
||||
to distinguish between things that are watchonly and things that are not within a wallet itself.
|
||||
|
||||
This change does have a caveat. If a Descriptor Wallet with private keys *enabled* has
|
||||
a multiple key descriptor without all of the private keys (e.g. `multi(...)` with only one private key),
|
||||
then the wallet will fail to sign and broadcast transactions. Such wallets would need to use the PSBT
|
||||
workflow but the typical GUI Send, `sendtoaddress`, etc. workflows would still be available, just
|
||||
non-functional.
|
||||
|
||||
This issue is worsened if the wallet contains both single key (e.g. `wpkh(...)`) descriptors and such
|
||||
multiple key descriptors as some transactions could be signed and broadast and others not. This is
|
||||
due to some transactions containing only single key inputs, while others would contain both single
|
||||
key and multiple key inputs, depending on which are available and how the coin selection algorithm
|
||||
selects inputs. However this is not considered to be a supported use case; multisigs
|
||||
should be in their own wallets which do not already have descriptors. Although users cannot export
|
||||
descriptors with private keys for now as explained earlier.
|
||||
|
||||
#### BIP 44/49/84 Support
|
||||
|
||||
The change to using descriptors changes the default derivation paths used by Bitcoin Core
|
||||
to adhere to BIP 44/49/84. Descriptors with different derivation paths can be imported without
|
||||
issue.
|
||||
|
||||
### Wallet RPC changes
|
||||
|
||||
- The `upgradewallet` RPC replaces the `-upgradewallet` command line option.
|
||||
(#15761)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue