Crate khodpay_bip39

Expand description

§BIP39 - Mnemonic Code for Cryptocurrency Wallets

A production-ready Rust implementation of the BIP39 standard for generating deterministic keys in cryptocurrency wallets.

§Overview

BIP39 (Bitcoin Improvement Proposal 39) defines a method for creating mnemonic phrases (12-24 words) that can be used to generate deterministic cryptocurrency wallet keys. This implementation provides a safe, ergonomic, and fully-tested Rust API.

§Features

Full BIP39 Compliance - Implements the complete BIP39 specification
Multi-Language Support - 9 languages supported
Type-Safe API - Leverages Rust’s type system for safety
Comprehensive Testing - 184+ tests including unit, doc, and integration tests
Cryptographically Secure - Uses system CSPRNG for entropy generation
Zero Unsafe Code - Pure safe Rust implementation

§Quick Start

use khodpay_bip39::{Mnemonic, WordCount, Language};

// Generate a new 12-word mnemonic
let mnemonic = Mnemonic::generate(WordCount::Twelve, Language::English)?;

// Display the phrase (user should write this down!)
println!("Recovery phrase: {}", mnemonic.phrase());

// Generate a cryptographic seed for key derivation
let seed = mnemonic.to_seed("optional passphrase")?;

§Core Types

§`Mnemonic`

The main struct representing a BIP39 mnemonic phrase.

Constructors:

Mnemonic::new(entropy, language) - Create from raw entropy bytes
Mnemonic::from_phrase(phrase, language) - Parse existing phrase
Mnemonic::generate(word_count, language) - Generate random mnemonic

Methods:

phrase() - Get the mnemonic phrase as a string
entropy() - Get the entropy bytes
word_count() - Get the word count
to_seed(passphrase) - Generate cryptographic seed

§`WordCount`

Type-safe enum for BIP39 word counts (12, 15, 18, 21, or 24 words).

§`Language`

Enum for supported languages (English, Japanese, Korean, Spanish, French, Italian, Czech, Portuguese, Chinese Simplified).

§`Error`

Comprehensive error type for all BIP39 operations.

§Usage Examples

§Creating a New Wallet

use khodpay_bip39::{Mnemonic, WordCount, Language};

// Generate a new mnemonic with 24 words (highest security)
let mnemonic = Mnemonic::generate(WordCount::TwentyFour, Language::English)?;

// Show the phrase to the user (they should write it down!)
println!("Your recovery phrase:");
println!("{}", mnemonic.phrase());

// Generate seed with passphrase for additional security
let seed = mnemonic.to_seed("my secure passphrase")?;

§Recovering a Wallet

use khodpay_bip39::{Mnemonic, Language};

// User enters their recovery phrase
let phrase = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";

// Parse and validate the phrase
let mnemonic = Mnemonic::from_phrase(phrase, Language::English)?;

// Regenerate the seed (must use same passphrase!)
let seed = mnemonic.to_seed("my secure passphrase")?;

§Creating from Known Entropy

use khodpay_bip39::{Mnemonic, Language};

// From hardware wallet or external entropy source
let entropy = [42u8; 32]; // 256 bits = 24 words

// Create mnemonic from entropy
let mnemonic = Mnemonic::new(&entropy, Language::English)?;

println!("Mnemonic: {}", mnemonic.phrase());

§Using Utility Functions

use khodpay_bip39::{generate_mnemonic, validate_phrase, phrase_to_seed, WordCount};

// Generate a phrase directly
let phrase = generate_mnemonic(WordCount::Twelve)?;

// Validate it
validate_phrase(&phrase)?;

// Generate seed from phrase
let seed = phrase_to_seed(&phrase, "passphrase")?;

§Security Considerations

§⚠️ Important Security Notes

Entropy Generation: Uses system CSPRNG (rand::thread_rng())
Mnemonic Storage: Never store mnemonics in plain text
Passphrase Security: Passphrases add a “25th word” for additional security
Memory Safety: Consider zeroing sensitive data after use

§Best Practices

use khodpay_bip39::{Mnemonic, WordCount, Language};

// ✓ DO: Generate with maximum entropy
let mnemonic = Mnemonic::generate(WordCount::TwentyFour, Language::English)?;

// ✓ DO: Use passphrases for additional security
let seed = mnemonic.to_seed("strong passphrase")?;

// ✗ DON'T: Store mnemonics in application state
// ✗ DON'T: Log or transmit mnemonics

§Testing

The crate includes comprehensive test coverage:

Unit Tests: 138 tests covering all modules
Doc Tests: 35 tests in documentation
Integration Tests: 11 end-to-end workflow tests

Run tests with:

cargo test

§References

Structs§

Mnemonic: A BIP39 mnemonic phrase with associated metadata.

Enums§

Error: Comprehensive error types for BIP39 mnemonic operations.
Language: Supported languages for BIP39 mnemonic phrases.
WordCount: Represents the valid word counts for BIP39 mnemonics.

Functions§

generate_mnemonic: Generates a new random BIP39 mnemonic phrase in English.
generate_mnemonic_in_language: Generates a new random BIP39 mnemonic phrase with language support.
phrase_to_seed: Converts a BIP39 mnemonic phrase into a cryptographic seed (English).
phrase_to_seed_in_language: Converts a BIP39 mnemonic phrase into a cryptographic seed with language support.
validate_phrase: Validates a BIP39 mnemonic phrase in English.
validate_phrase_in_language: Validates a BIP39 mnemonic phrase in the specified language.

Type Aliases§

Result: Convenient type alias for std::result::Result with our Error type.