Blog

Back to Blog Entries

BIP 32 Wallet compatibility

April 14th 2015

Thanks to the sterling work of GitHub user "gurnec" during Beta testing an incompatibility between MultiBit HD and other hierarchical deterministic (HD) wallets was discovered indicating that they are not BIP 32 compliant. This is important because "BIP 32 compliance" means that a user of one wallet can easily migrate to another in a safe manner simply by providing their "wallet words" during a restore process.

The current MultiBit HD wallets are perfectly good HD wallets but unfortunately we made a mistake in the address generation code so that typing in the same "wallet words" in another wallet will not yield the same addresses and the balance will be incorrect.

This incompatibility is fixed in the Beta 8 and higher (0.0.8beta) versions.

Trezor wallets are not affected since they use the BIP 44 standard.

The vast majority of MultiBit HD users will never see a wallet generated by Beta 7 (0.0.7beta) or earlier (known as "Beta7 wallets"). You can see whether you are affected by going into "Manage wallet | Wallet dashboard" and looking at the section titled "Wallet capabilities". If it says "Beta 7 MultiBit HD wallet" on the first row then you have unlocked a Beta7 wallet and you should migrate. Simply follow the instructions given below.

How to restore a Beta7 wallet

To restore a Beta7 wallet from your wallet words you need to perform the following steps:

  1. Unlock any wallet (you may need to create a new one first if this is a disaster recovery scenario)
  2. Go into "Tools | Labs" and enable the option "Enable restore of Beta7 wallets".
  3. From the password entry screen, press the 'Restore' button and then select the 'Restore wallet' option. Click Next.
  4. On the first screen where you enter your wallet words, make sure the reply to "What created these wallet words ?" is "MultiBit HD (Beta7 - Not BIP 32 compliant)".
  5. Continue through the 'Restore wallet' wizard as normal.

By enabling and selecting this normally hidden option you tell MultiBit HD to use the Beta7 wallet format in order to recover your bitcoins.

While you have your wallet words to hand, you should add a note to them indicating that they are for Beta7.

How to migrate away from a Beta7 wallet

When using MultiBit HD 0.0.8beta (or later) any new wallet and a regular restore from your "wallet words" will produce a BIP 32 compliant wallet. This means you will be generating the same addresses as other BIP 32 wallets such as Lighthouse.

First, create a new BIP 32 wallet:

  1. Create a new BIP 32 wallet by clicking the "Restore" button on the unlock screen
  2. From the list of options choose "Create new wallet" and follow the instructions to completion
  3. Unlock the new wallet
  4. Use "Send/Request | Request" to create an address and then copy it to the clipboard (note the start and end characters)
  5. Use "Exit/Switch | Switch wallet" to return to the unlock screen

Next, you need to empty your old Beta7 wallet into the new one:

  1. Unlock the old Beta7 wallet
  2. Use "Manage Wallet | Empty wallet" to start the emptying process
  3. Paste the new wallet receiving address (verify the start and end characters in case of errors in transcription)
  4. Follow the instructions to completion

Finally, verify that your funds have arrived safely in the new wallet by unlocking it and waiting for sync to complete.

While you have your Beta7 wallet words to hand, you should add a note to them indicating that they are for Beta7.

Do not dispose of your Beta7 wallet words! You must keep them safe in case someone ever sends bitcoin to one of the addresses sometime in the future.

Technical details

This is the GitHub issue describing the technical details : #445

The problem was in the conversion of a BIP 39 mnemonic to its corresponding xpriv. Instead of treating the mnemonic bytes as a seed they were treated as entropy.

Related articles

Here are some related articles: