Bitcoin Core: New HD Wallets vs. Legacy

[tiffy]

Hello

I would like to set up a cold wallet with Bitcoin Core. Here's how I would created the wallet:

Code:

bitcoin-cli -named createwallet wallet_name="MyWalletName" descriptors=false

So far so good only this warning worries me:

Code:

{
  "name": "MyWalletName",
  "warnings": [
    "Wallet created successfully. The legacy wallet type is being deprecated and support for creating and opening legacy wallets will be removed in the future."
  ]
}

I understand that it's all done through hd wallets now. But I can't find any good documentation on how to store and handle this for a cold wallet. What am I backing up there on paper and how do I get it in a simple way? How do I get the private key to an address? Will signing transactions with bitcoin-cli work the same way as with a legacy wallet?

I find it all confusing compared to how it used to be. How long will legacy wallets be supported? What disadvantages do I have when I use a legacy wallet as cold wallet?

I really only want to use bitcoin-cli  (in combination with "bitcoind -noconnect") and the usual Linux tools on my cold wallet machine (Raspberry Pi 2 ). Everything on the terminal. So should I better switch to a hd wallet or can I stay with legacy?
Thank you for your attention.

tiffy

[1714620080]

1714620080

[1714620080]

1714620080

[1714620080]

1714620080

[achow101]

Note that all newly created wallets are HD wallets. "Descriptors" and "legacy" refer to the internal structures of how the wallet manages keys and scripts. Descriptor wallets use output script descriptors specified in BIPs 380-386. Legacy wallets are just a bunch of keys that may or may not be generated deterministically (depending on the wallet version) and have some confusing and unexpected behavior when it comes to determining what transactions belong to the wallet.

But I can't find any good documentation on how to store and handle this for a cold wallet. What am I backing up there on paper and how do I get it in a simple way?

The implementation of descriptor wallets is entirely transparent to the user. The user should not feel or have to do anything meaningfully different with a descriptor wallet than with a legacy wallet. As such, backups are done in the same way - you must backup the entire file. There is no paper backup method.

How do I get the private key to an address?

This is one of the most noticeable differences. With descriptor wallets, you cannot export the private key for one address. This is because a child private key combined with the parent public key can be used to compute the parent private key (and hence all other child private keys). This is a risk inherent in BIP 32's unhardened derivation. As such, descriptor wallets disallow the export of child private keys in order to mitigate the risk of accidentally exposing the parent private key.

But you shouldn't be exporting individual private keys anyways. The wallet does not use just one private key, so having an individual child private key is really not that useful.

Will signing transactions with bitcoin-cli work the same way as with a legacy wallet?

Yes. There is no change in the methods for getting new addresses, or with making transactions. These are kept entirely the same.

I find it all confusing compared to how it used to be.

It's only confusing because both types of wallets can be used right now.

How long will legacy wallets be supported?

They are planned to be dropped entirely in 27.0, which will be released in ~7 months. However there is and will continue to be a tool in Bitcoin Core that allows you to convert a legacy wallet into a descriptor wallet.

What disadvantages do I have when I use a legacy wallet as cold wallet?

It's rather difficult to create a watchonly wallet from a legacy wallet. You want your private keys in cold storage, but you still need to have an online wallet that contains the public things in your wallet so that you can learn about new transactions as well as create unsigned transactions that will be signed on your cold wallet. With a legacy wallet, this is rather difficult to do. Descriptor wallets make this very easy to do.

Since legacy wallets will soon become unsupported, you'll be unable to make use of any new features that may become available on Bitcoin. Notably, legacy wallets already cannot create Taproot addresses, so they are completely unable to use Taproot at all. Descriptor wallets support Taproot out of the box already, and will be able to support any future address types as long as a descriptor is designed for them.

I really only want to use bitcoin-cli  (in combination with "bitcoind -noconnect") and the usual Linux tools on my cold wallet machine (Raspberry Pi 2 ). Everything on the terminal. So should I better switch to a hd wallet or can I stay with legacy?

I suggest that you switch to a descriptor wallet. It will make setup of the watchonly wallet much easier (export the public descriptors and import them on the watchonly). They will also continue to be supported and actually get new features.

[takuma sato]

Hello

I would like to set up a cold wallet with Bitcoin Core. Here's how I would created the wallet:

Code:

bitcoin-cli -named createwallet wallet_name="MyWalletName" descriptors=false

So far so good only this warning worries me:

Code:

{
  "name": "MyWalletName",
  "warnings": [
    "Wallet created successfully. The legacy wallet type is being deprecated and support for creating and opening legacy wallets will be removed in the future."
  ]
}

I understand that it's all done through hd wallets now. But I can't find any good documentation on how to store and handle this for a cold wallet. What am I backing up there on paper and how do I get it in a simple way? How do I get the private key to an address? Will signing transactions with bitcoin-cli work the same way as with a legacy wallet?

I find it all confusing compared to how it used to be. How long will legacy wallets be supported? What disadvantages do I have when I use a legacy wallet as cold wallet?

I really only want to use bitcoin-cli  (in combination with "bitcoind -noconnect") and the usual Linux tools on my cold wallet machine (Raspberry Pi 2 ). Everything on the terminal. So should I better switch to a hd wallet or can I stay with legacy?
Thank you for your attention.

tiffy

https://bitcoincore.org/en/doc/25.0.0/rpc/wallet/migratewallet/


As far as for how long they will be supported:

https://github.com/bitcoin/bitcoin/issues/20160

Always make backups, but if everything fails you can always run an older Bitcoin Core version. A main goal of Bitcoin is to make it as backwards compatible as possible.

[LoyceV]

How do I get the private key to an address?

This is one of the most noticeable differences. With descriptor wallets, you cannot export the private key for one address. This is because a child private key combined with the parent public key can be used to compute the parent private key (and hence all other child private keys). This is a risk inherent in BIP 32's unhardened derivation. As such, descriptor wallets disallow the export of child private keys in order to mitigate the risk of accidentally exposing the parent private key.

Wouldn't it have been a much better choice to use hardened derivation?

But you shouldn't be exporting individual private keys anyways. The wallet does not use just one private key, so having an individual child private key is really not that useful.

I can think of something: I once needed to (quickly) use CPFP, but Bitcoin Core's GUI didn't allow me to use an unconfirmed input from a third party, so I exported the private key and imported it into Electrum.

I guess I'll have to give up my non-HD-wallet eventually, but I don't like it. Importing a private key is so much easier in a non-descriptor wallet.

[nc50lc]

But you shouldn't be exporting individual private keys anyways. The wallet does not use just one private key, so having an individual child private key is really not that useful.

I can think of something: I once needed to (quickly) use CPFP, but Bitcoin Core's GUI didn't allow me to use an unconfirmed input from a third party, so I exported the private key and imported it into Electrum.

It's much much safer with descriptor wallet, something similar can be done by importing the address' parent "extended public key" to Electrum instead and perform CPFP with it.
The exported PSBT transaction is compatible with Bitcoin Core, you only have to enable the necessary options if you're using the GUI to sign and broadcast it: "Settings->Options...->Wallet->Enable PSBT controls".

When importing the 'xpub' to Electrum, it should be converted to 'zpub' or 'ypub' with the command convert_xkey to match the target script type.
Example:  convert_xkey(xkey="xpub.........",xtype="p2wpkh-p2sh") or convert_xkey(xkey="xpub.........",xtype="p2wpkh")

[achow101]

Wouldn't it have been a much better choice to use hardened derivation?

Hardened does not allow for child pubkeys to be derived from the parent xpub.

I can think of something: I once needed to (quickly) use CPFP, but Bitcoin Core's GUI didn't allow me to use an unconfirmed input from a third party, so I exported the private key and imported it into Electrum.

That's a workaround, not a use case. You could still do this workaround by exporting the descriptor with private keys.

You can use the RPCs to make such a transaction since you can manually specify the inputs.

Importing a private key is so much easier in a non-descriptor wallet.

It's pretty easy with a descriptor wallet, you make a combo(<privkey>) descriptor and import that. With descriptor wallets, it's also possible to import more complicated things like anything involving an xpub, and you'll be importing exactly what the descriptor describes instead of also things that you don't expect when you try to do something similar with a legacy wallet.

[tiffy]

Hello achow101

Thank you so much for your detailed answers. I really appreciate it.

Note that all newly created wallets are HD wallets. "Descriptors" and "legacy" refer to the internal structures of how the wallet manages keys and scripts. Descriptor wallets use output script descriptors specified in BIPs 380-386. Legacy wallets are just a bunch of keys that may or may not be generated deterministically (depending on the wallet version) and have some confusing and unexpected behavior when it comes to determining what transactions belong to the wallet.

Good to know. I still have a lot to learn.

The implementation of descriptor wallets is entirely transparent to the user. The user should not feel or have to do anything meaningfully different with a descriptor wallet than with a legacy wallet. As such, backups are done in the same way - you must backup the entire file. There is no paper backup method.

This is currently my main problem with the new hd wallet. I can find instructions on the net on how to save something on paper again. But they are quite obscure instructions and so far I do not really understand what I would really do there. Not having a paper wallet, not having my keys on paper, makes me feel insecure. I'm creating something, backing it up, but I don't understand exactly what it is.

How do I get the private key to an address?

This is one of the most noticeable differences. With descriptor wallets, you cannot export the private key for one address. This is because a child private key combined with the parent public key can be used to compute the parent private key (and hence all other child private keys). This is a risk inherent in BIP 32's unhardened derivation. As such, descriptor wallets disallow the export of child private keys in order to mitigate the risk of accidentally exposing the parent private key.

Thank you for pointing this out. It shows me once again how little I know. Now I understand a little bit better why the client does not give out the keys, I think.

But you shouldn't be exporting individual private keys anyways. The wallet does not use just one private key, so having an individual child private key is really not that useful.

Why not? Every Bitcoin address still corresponds to a ECDSA keypair where the private key gives me control over the corresponding UTXO. Or does the hd wallet change anything about that?

What disadvantages do I have when I use a legacy wallet as cold wallet?

It's rather difficult to create a watchonly wallet from a legacy wallet. You want your private keys in cold storage, but you still need to have an online wallet that contains the public things in your wallet so that you can learn about new transactions as well as create unsigned transactions that will be signed on your cold wallet. With a legacy wallet, this is rather difficult to do. Descriptor wallets make this very easy to do.

In a pinch, I can just use a web blockchain explorer.

Since legacy wallets will soon become unsupported, you'll be unable to make use of any new features that may become available on Bitcoin. Notably, legacy wallets already cannot create Taproot addresses, so they are completely unable to use Taproot at all. Descriptor wallets support Taproot out of the box already, and will be able to support any future address types as long as a descriptor is designed for them.

I don't even know what taproot is.

Working without printed keys or at least a seed goes against my personal guidelines of robustness. Of course, I could get over it, but I wouldn't feel safe with it. Having the private keys for the UTXO on paper is just a good feeling. When I only have wallet backups on electronic storage media, this is not robust for my taste. Software changes. The keys remain. I have to save the keys anyway. Why shouldn't I be able to write them down as well? It's just my emergency backup when everything else is lost. And it's independent of electronic devices. That's just to explain my motivation. Am I missing something or is my position suboptimal?

What actually happens when I convert a legacy wallet to an hd wallet? Then the already existing ECDSA keypairs remain the same or not? Please excuse the many questions without proper understanding. For me hd wallets are completely new.

[achow101]

You keep talking about HD wallets, and I want to stress that both legacy and descriptor wallets are HD wallets. There is no way to create a non-HD wallet in Bitcoin Core. Regardless of whether you make a legacy wallet or a descriptor wallet, you will be making an HD wallet. Being HD or not is not really relevant to your question.

This is currently my main problem with the new hd wallet. I can find instructions on the net on how to save something on paper again. But they are quite obscure instructions and so far I do not really understand what I would really do there. Not having a paper wallet, not having my keys on paper, makes me feel insecure. I'm creating something, backing it up, but I don't understand exactly what it is.

The only official method for backing up any Bitcoin Core wallet (since the very beginning) is to have a copy of the wallet file. Modern versions of Bitcoin Core have specific buttons in the GUI and RPCs for safely making this backup file and restoring it in the future. The wallet file contains everything that is necessary to spend your Bitcoin, as well as metadata. All of the information that you see displayed about your wallet is contained in the wallet file.

If you really want to have a paper backup, it is possible to do this with descriptor wallets by using the RPC listdescriptors true. This will output all of the descriptors in the wallet (there aren't many) with their private keys included. You can write that down on paper if you really want to. Note that it is case sensitive. Also, you can't do this with legacy wallets.

Why not? Every Bitcoin address still corresponds to a ECDSA keypair where the private key gives me control over the corresponding UTXO. Or does the hd wallet change anything about that?

A wallet consists of multiple keys, and will have multiple UTXOs, typically associated with different keys (you shouldn't reuse addresses). When you make a transaction, you'll probably be using multiple UTXOs. So a single key is unlikely to even be able to fully sign a transaction.

Working without printed keys or at least a seed goes against my personal guidelines of robustness. Of course, I could get over it, but I wouldn't feel safe with it. Having the private keys for the UTXO on paper is just a good feeling. When I only have wallet backups on electronic storage media, this is not robust for my taste. Software changes. The keys remain. I have to save the keys anyway. Why shouldn't I be able to write them down as well? It's just my emergency backup when everything else is lost. And it's independent of electronic devices. That's just to explain my motivation. Am I missing something or is my position suboptimal?

If you insist on doing that, I still recommend that you use a descriptor wallet. Descriptors are standardized and intended to be imported into other wallet software. With a legacy wallet, you'll have a seed that is not at all standardized (Bitcoin Core does not use seed phrases). This seed also looks like a private key, so can be easily confused for one which is detrimental in a restoration scenario. Otherwise, you'd have a couple thousand individual private keys (although these can be regenerated given the seed). Lastly, that seed is essentially a Bitcoin Core specific thing, so if you ever wanted to use a different software, you basically can't.

What actually happens when I convert a legacy wallet to an hd wallet? Then the already existing ECDSA keypairs remain the same or not? Please excuse the many questions without proper understanding. For me hd wallets are completely new.

In the legacy to descriptor migration, descriptors are created for everything in the legacy wallet and placed into a new descriptor wallet. New descriptors (and hence new keys) are generated and will be used. However, as the wallet contains descriptors for all your previous keys, no funds are lost and you can still receive with any addresses that you have previously given out.

[achow101]

I have few question,
1. By "convert a legacy wallet...", do you mean all kinds of legacy wallet or just HD legacy wallet?

All legacy wallets.

2. By tool, do you mean CLI tools just like bitcoin-wallet binary?

No, built into bitcoind and bitcoin-qt itself. It'll be the migratewallet RPC, and the File > Migrate Wallet menu item in the GUI

[DaveF]

Always make backups, but if everything fails you can always run an older Bitcoin Core version. A main goal of Bitcoin is to make it as backwards compatible as possible.

The only downfall with that is what might happen with VERY old wallets. You have to think in the possibility of DECADES.
Even now getting older software to run at times requires VMs and other things.
Some versions of the bitcoin client are difficult to find.
And so on.

Just something to think about.

-Dave

[philipma1957]

Always make backups, but if everything fails you can always run an older Bitcoin Core version. A main goal of Bitcoin is to make it as backwards compatible as possible.

The only downfall with that is what might happen with VERY old wallets. You have to think in the possibility of DECADES.
Even now getting older software to run at times requires VMs and other things.
Some versions of the bitcoin client are difficult to find.
And so on.

Just something to think about.

-Dave

yeah I had this happen to me with 2 Eth coins.

While not btc these got stuck in an old Mac OS  wallet due to the giant fix  done early with eth . they were worth 6+6 dollars. when they got to 500 each 1000 total I really tried to free them and could not. So I am out 2 eth or  3500 usd at this moment.

[tiffy]

You keep talking about HD wallets, and I want to stress that both legacy and descriptor wallets are HD wallets. There is no way to create a non-HD wallet in Bitcoin Core. Regardless of whether you make a legacy wallet or a descriptor wallet, you will be making an HD wallet. Being HD or not is not really relevant to your question.

Hello achow101

Thank you for your patience. Yes, I thought hd wallets and descriptor wallets were synonyms. Now I understand it much better. So excuse my ignorance.

If you really want to have a paper backup, it is possible to do this with descriptor wallets by using the RPC listdescriptors true. This will output all of the descriptors in the wallet (there aren't many) with their private keys included. You can write that down on paper if you really want to. Note that it is case sensitive. Also, you can't do this with legacy wallets.

Thank you. That is already close. I have experimented with it and also used "bitcoin-cli getaddressinfo". To calculate the missing private keys in the hdkeypath I therefore followed these instructions

https://bitcointalk.org/index.php?topic=5351210.msg60007045#msg60007045

The tool calculates the public key for my test address in the keypath correctly but shows another bitcoin address.  

I will research further there. But if you have any idea what could be the reason, please let me know.

You have helped me enough as it is. Thanks again for that.

[achow101]

Thank you. That is already close. I have experimented with it and also used "bitcoin-cli getaddressinfo". To calculate the missing private keys in the hdkeypath I therefore followed these instructions

https://bitcointalk.org/index.php?topic=5351210.msg60007045#msg60007045

The tool calculates the public key for my test address in the keypath correctly but shows another bitcoin address.  

I will research further there. But if you have any idea what could be the reason, please let me know.

The reason is that keys are not the same as addresses, and it is not a one-to-one mapping of pubkey to address. There are multiple addresses for a single pubkey as there are multiple address types. The purpose of descriptors is to make it clear which address type to create. However you've completely bypassed that by taking the key out of the descriptor and trying to compute the address manually. The reason you don't get the same address is most likely because you have chosen the wrong address type.

[nc50lc]

https://bitcointalk.org/index.php?topic=5351210.msg60007045#msg60007045

The tool calculates the public key for my test address in the keypath correctly but shows another bitcoin address.  

I see that you've referred to my reply there.
Since you've successfully derived the correct public key, the issue is the selected tab under derivation path:

IanColeman's BIP39 tool has reserved different address type per tab,
Where the standards "BIP44", "BIP49" and "BIP84" tabs derive legacy, nested-SegWit and native-SegWit respectively.
While in "BIP32" tab, it'll default to legacy no matter what the derivation path is; and in "BIP141" tab, it'll derive the one selected in "Script Semantics" drop-down menu.

[tiffy]

The reason is that keys are not the same as addresses, and it is not a one-to-one mapping of pubkey to address. There are multiple addresses for a single pubkey as there are multiple address types. The purpose of descriptors is to make it clear which address type to create. However you've completely bypassed that by taking the key out of the descriptor and trying to compute the address manually. The reason you don't get the same address is most likely because you have chosen the wrong address type.

I see that you've referred to my reply there.
Since you've successfully derived the correct public key, the issue is the selected tab under derivation path:

IanColeman's BIP39 tool has reserved different address type per tab,
Where the standards "BIP44", "BIP49" and "BIP84" tabs derive legacy, nested-SegWit and native-SegWit respectively.
While in "BIP32" tab, it'll default to legacy no matter what the derivation path is; and in "BIP141" tab, it'll derive the one selected in "Script Semantics" drop-down menu.

Through your explanations, I think I finally understood. Thanks a lot. It was in front of my eyes all the time. My hdkeypath starts with "m/84". This means that it is an address in BIP84 format. Gosh, now I understand what those numbers in front of the paths mean. IanColeman's BIP39 tool generates all addresses, pubkeys and privkeys when I select BIP84. Great.

Is BIP84 ok? Can I use such an address normally on an online exchange like Kraken? I did nothing else. Bitcoin Core has chosen this format itself. Thus, I would hope that it is a common standard.

When I call "listdescriptors true" I get 8 entries, but they all have the same xprivkey. If I call "listdescriptors" I also get 8 entries, but with a total of 4 xpubkeys. IanColeman's BIP39 tool also shows me one xpubkey out of the four. In the line "Account Extended Public Key". With this xpubkey I can then make myself a watch-only wallet right?

Can I then also create unsigned transactions with the watch-only wallet, which I then sign on my cold wallet?

I will of course never transfer a private key to the watch-only wallet. Another thing I'm wondering: Aren't hd wallets easier to crack? After all, you "only" have to guess a private child key and then you can use the xpubkey to calculate the xprivkey. Right?

[nc50lc]

Through your explanations, I think I finally understood. Thanks a lot. It was in front of my eyes all the time. My hdkeypath starts with "m/84". This means that it is an address in BIP84 format. Gosh, now I understand what those numbers in front of the paths mean. IanColeman's BIP39 tool generates all addresses, pubkeys and privkeys when I select BIP84. Great.

Is BIP84 ok? Can I use such an address normally on an online exchange like Kraken? I did nothing else. Bitcoin Core has chosen this format itself. Thus, I would hope that it is a common standard.

Actually, in the descriptor, the script type is the "wpkh" at the start of it.
The derivation path can be other than 84' but Bitcoin uses BIP84 with it for standards.

Read this for more info about descriptors: https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md#features

When I call "listdescriptors true" I get 8 entries, but they all have the same xprivkey. If I call "listdescriptors" I also get 8 entries, but with a total of 4 xpubkeys. IanColeman's BIP39 tool also shows me one xpubkey out of the four. In the line "Account Extended Public Key". With this xpubkey I can then make myself a watch-only wallet right?

Yes, depending on the wallet.
If it's Bitcoin Core, you just have to import those descriptors to a "blank", "private keys disabled", "descriptor" wallet; with the right flags.
Namely, "internal" to false or true depending if the descriptor is for receiving or change; and "active" so that it'll be used when you request for new address of a specific address type.

The reason for the same xprv key is because it's your wallet's "master private key" which is the 'm' in the derivation path which is at the upper most level of the hierarchy.
The different xpubs on the other hand, are derived down to the account level (see its position in the descriptor) which are derived with different derivation paths as seen in your 8 descriptors.

Example descriptors:
Native SegWit receiving addresses:

Code:

"desc": "wpkh([de651e9f/84'/0'/0']xpub.....P47q7oqHx/0/*)#9vhqdhat",

Code:

"desc": "script-type([master fingerprint/purpose'/coin'/account']<--account extended public key/external/*)#checksum",

Native SegWit change addresses:

Code:

"desc": "wpkh([de651e9f/84'/0'/0']xpub.....P47q7oqHx/1/*)#5cjpszdn",

Code:

"desc": "script-type([master fingerprint/purpose'/coin'/account']<--account extended public key/internal/*)#checksum",

Can I then also create unsigned transactions with the watch-only wallet, which I then sign on my cold wallet?

In Bitcoin Core, it can be done with RPC commands.
Or in the GUI, you'll just need to activate "Enable PSBT controls" in the wallet settings.

[tiffy]

The reason for the same xprv key is because it's your wallet's "master private key" which is the 'm' in the derivation path which is at the upper most level of the hierarchy.
The different xpubs on the other hand, are derived down to the account level (see its position in the descriptor) which are derived with different derivation paths as seen in your 8 descriptors.

They implement the different address types? (I see: pkh, sh(wpkh), tr and wpkh). When I switch to BIP 44 (in IanColeman's BIP39 tool), I get legacy addresses. Exactly the legacy addresses that getnewaddress outputs with:

Code:

bitcoin-cli -rpcwallet=MyWallet getnewaddress -address_type legacy

And as Account Extended Public Key the xpubkey of the corresponding descriptor is displayed. I think I'm starting to understand this. I don't understand the math but what it does.  

Example descriptors:

Yes, that's what they look like. When you talk about "change", do you mean the Bitcoins, which are transferred to yourself if you do not spend the total amount in the inputs? This is the path with the "1" (m/84'/0'/0'/1) I think.  
If I set "External / Internal" to "1" in the BIP39 tool, the path changes and other addresses are generated. These are then the internal addresses for the change?

Can I then also create unsigned transactions with the watch-only wallet, which I then sign on my cold wallet?

In Bitcoin Core, it can be done with RPC commands.
Or in the GUI, you'll just need to activate "Enable PSBT controls" in the wallet settings.

You have helped me a lot again.

[nc50lc]

They implement the different address types?

Yes, even in legacy HD wallets, each private key derives three different address types in exception to TapRoot.
In Descriptor wallets, each address types are derived from their corresponding descriptors which are pre-generated when the wallet is created.

The math is defined in BIP32: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki

Yes, that's what they look like. When you talk about "change", do you mean the Bitcoins, which are transferred to yourself if you do not spend the total amount in the inputs? This is the path with the "1" (m/84'/0'/0'/1) I think.  
If I set "External / Internal" to "1" in the BIP39 tool, the path changes and other addresses are generated. These are then the internal addresses for the change?

Yes.

You can get more information in BIP44; in BIP39 and BIP84, only the "purpose" field is different.
BIP44: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki