WalletD Mnemonics

You're probably familiar with how most cryptocurrencies provide you with a 12-25 word secret phrase in order to access your cryptocurrency. This secret phrase, also known as a mnemonic phrase, represents the seed used to derive your wallet's keys and addresses. A seed consists of bytes of data that serve as the foundation for generating the cryptographic elements of a wallet. The mnemonic phrase provides a human-readable representation of the seed, making it easier for users to manage their wallets. In this guide, we'll look at mnemonics handling in WalletD.

BIP39 Mnemonic

use walletd::walletd_bip39::prelude::*;
use walletd::walletd_bip39;

BIP39 Mnemonics follows the BIP39 standard for HD wallet mnemonic phrases. In this section, we'll guide you on how to use WalletD to access BIP39 mnemonics.

Make a Mnemonic

Here's how you can create a new randomly generated BIP39 mnemonic using the default specifications:

// call the a builder from `Bip39Mnemonic`, this gives you the default settings 
// calling the build method will generate a new random bip39 mnemonic within the default specs
let mnemonic = Bip39Mnemonic::builder().build()?;
// display the generated mnemonic phrase
println!("mnemonic phrase: {}", mnemonic.phrase());

The default specifications for the Bip39MnemonicBuilder are: English language, 12 words in the mnemonic phrase, with no passphrase specified. You should see that the mnemonic phrase that was printed consisted of 12 English words.

We can get the mnemonic seed which is related to the mnemonic phrase.

Show the mnemonic seed as bytes:

println!("mnemonic seed as bytes: {:?}", mnemonic.to_seed().as_bytes());

Show the mnemonic seed as a hex string:

println!("mnemonic seed hex: {:x}", mnemonic.to_seed());

Specify Options

You can override the default specifications by providing your desired specifications to the builder. You can also reuse the Bip39MnemonicBuilder object in a mutable way to create multiple BIP39 mnemonics and even override previous specifications. Also we can see the number entropy bits linked to a mnemonic.

 let mut mnemonic_builder = Bip39Mnemonic::builder();

 // specify that the mnemonic phrase should consist of 24 words
 let mnemonic_1 = mnemonic_builder.mnemonic_type(Bip39MnemonicType::Words24).build()?;
 println!("mnemonic_1 phrase: {}", mnemonic_1.phrase());
 println!("mnemonic_1 seed hex: {:x}", mnemonic_1.to_seed());
 // see the number of entropy bits for the specified mnemonic type
 println!("mnemonic_1 number of entropy bits: {}", mnemonic_1.mnemonic_type().entropy_bits());

 // reuse builder but now specify 18 words in the mnemonic phrase
 let mnemonic_2 = mnemonic_builder.mnemonic_type(Bip39MnemonicType::Words18).build()?;
 println!("mnemonic_2 phrase: {}", mnemonic_2.phrase());
 println!("mnemonic_2 seed hex: {:x}", mnemonic_2.to_seed());
 println!("mnemonic_2 number of entropy bits: {}", mnemonic_2.mnemonic_type().entropy_bits());

It may be useful in some cases to provide all of the specifications even when using the some of the default settings.

Use of Optional Passphrase

You can specify a passphrase to use when generating the mnemonic. Note that the same passphrase must be used when recovering the mnemonic.

Warning: If a Bip39Mnemonic mnemonic phrase is generated using a specification of passphrase, both the mnemonic phrase and the passphrase is required to recover the Bip39Mnemonic. The specified passphrase is not stored in the Bip39Mnemonic struct. It is important to store the passphrase you specified securely as well as the mnemonic phrase to enable recovery of the Bip39Mnemonic.

let mnemonic_3 = Bip39Mnemonic::builder()
     .passphrase("mypassphrase")
     .mnemonic_type(Bip39MnemonicType::Words12)
     .language(Bip39Language::English)
     .build()?;
println!("mnemonic_3 phrase: {}", mnemonic_3.phrase());
println!("mnemonic_3 seed hex: {:x}", mnemonic_3.to_seed());

Restoring a Mnemonic

A Bip39Mnemonic can be restored from a specified valid mnemonic phrase or from a specified valid mnemonic phrase and passphrase if a passphrase was specified when the mnemonic was generated.

 let mnemonic_phrase = "outer ride neither foil glue number place usage ball shed dry point";
 let restored_mnemonic_1 = Bip39Mnemonic::builder().mnemonic_phrase(mnemonic_phrase).build()?;
 println!("restored_mnemonic_1 phrase: {}", restored_mnemonic_1.phrase());
 println!("restored_mnemonic_1 seed hex: {:x}", restored_mnemonic_1.to_seed());

 let specified_passphrase = "mypassphrase";
 let restored_mnemonic_2 = Bip39Mnemonic::builder().mnemonic_phrase(mnemonic_phrase).passphrase(specified_passphrase).build()?;
 println!("restored_mnemonic_2 phrase: {}", restored_mnemonic_2.phrase());
 println!("restored_mnemonic_2 seed hex: {:x}", restored_mnemonic_2.to_seed());