bip39_dict/lib.rs
1//! BIP39 dictionary
2//!
3//! This can be used to convert arbitrary binary to a sequence of words (from the BIP39 wordlist)
4//! with a user-chosen checksum.
5//!
6//! The API can be used to generate the exact same procedure as BIP39 document, and
7//! can be used to generate a standard BIP39 hdwallet root secret key.
8//!
9//! It also extends the available procedure to allow user to use an arbitrary number of words,
10//! chose different size checksum, and finally for seed making tweak the number of iteration and
11//! output size to the user need.
12//!
13//! For more details about the BIP39 protocol, see
14//! [Bitcoin Improvement Proposal 39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)
15//!
16//! # Rules of encoding
17//!
18//! Each BIP39 word represent 11 bits, and the scheme can encode any byte size.
19//!
20//! The data are all multiple of 8 bits, aka bytestream, and
21//! the number of words represent a multiple of 11 bits. The checksum
22//! is the difference of the two and thus the following relation need
23//! to hold for:
24//!
25//! ```text
26//! data.len() * 8 + checksum = words.len() * 11
27//! ```
28//!
29//! The following are examples of valid encoding:
30//!
31//! * 1 byte data (8 bits) + 3 bits checksum = 1 word (11 bits)
32//! * 2 bytes data (16 bits) + 6 bits checksum = 2 words (22 bits)
33//! * 2 bytes data (16 bits) + 17 bits checksum = 3 words (33 bits)
34//!
35//! # Example
36//!
37//! # Convert an arbitrary 48 bytes entropy value to mnemonics
38//!
39//! ```
40//! use bip39_dict::{Entropy, ENGLISH, seed_from_mnemonics};
41//! // Entropy is a 48-bytes value
42//! # let entropy : Entropy<48> = Entropy([0; 48]);
43//!
44//! // create a 36 words mnemonics with 12 bits checksum
45//! let mnemonics = entropy.to_mnemonics::<36, 12>().unwrap();
46//! let mnemonics_string = mnemonics.to_string(&ENGLISH);
47//! ```
48//1
49//! ## To create a new HDWallet root secret key
50//!
51//!
52//! ```
53//! use bip39_dict::{Entropy, ENGLISH, seed_from_mnemonics};
54//!
55//! // first, you need to generate some entropy (dummy)
56//! let entropy = Entropy::<16>::generate(|| 1);
57//!
58//! // human readable mnemonics (in English) to retrieve the original entropy
59//! // and eventually recover a HDWallet.
60//! let mnemonics = entropy.to_mnemonics::<12, 4>().unwrap();
61//!
62//! // The seed of the Wallet is generated from the mnemonic string
63//! // in the associated language.
64//! let seed: [u8; 64] = seed_from_mnemonics(&ENGLISH, &mnemonics, b"some password", 2048);
65//! ```
66//!
67
68#![cfg_attr(not(feature = "std"), no_std)]
69#![deny(missing_docs)]
70
71#[cfg(test)]
72#[macro_use]
73extern crate std;
74
75#[cfg(not(feature = "std"))]
76extern crate alloc;
77
78mod bits;
79mod dictionary;
80mod entropy;
81mod index;
82mod mnemonics;
83mod seed;
84
85pub use dictionary::*;
86pub use entropy::{Entropy, EntropyError};
87pub use index::MnemonicIndex;
88pub use mnemonics::{MnemonicError, Mnemonics};
89pub use seed::seed_from_mnemonics;
90
91#[cfg(test)]
92mod tests;