BIP-39 Mnemonic Phrases

import * as Bip39 from '@tevm/voltaire/crypto/bip39';

// Generate 12-word mnemonic (128-bit entropy)
const mnemonic12 = Bip39.generateMnemonic(128);
// "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"

// Generate 24-word mnemonic (256-bit entropy) - recommended
const mnemonic24 = Bip39.generateMnemonic(256);

// Validate mnemonic
const isValid = Bip39.validateMnemonic(mnemonic12);
console.log(isValid); // true

// Convert to seed (async)
const seed = await Bip39.mnemonicToSeed(mnemonic12, 'optional passphrase');
console.log(seed); // Uint8Array(64)

// Convert to seed (sync)
const seedSync = Bip39.mnemonicToSeedSync(mnemonic12, 'optional passphrase');

// 12-word mnemonic (128-bit security)
const mnemonic12 = Bip39.generateMnemonic(128);

// 24-word mnemonic (256-bit security, recommended)
const mnemonic24 = Bip39.generateMnemonic(256);

// Default (256-bit)
const mnemonic = Bip39.generateMnemonic();

const entropy = crypto.getRandomValues(Bytes32()); // 256 bits
const mnemonic = Bip39.entropyToMnemonic(entropy);

const isValid = Bip39.validateMnemonic('abandon abandon abandon...');
if (!isValid) {
  console.error('Invalid mnemonic phrase');
}

try {
  Bip39.assertValidMnemonic(userProvidedMnemonic);
  // Proceed with valid mnemonic
} catch (error) {
  console.error('Invalid mnemonic:', error.message);
}

// Without passphrase
const seed = await Bip39.mnemonicToSeed(mnemonic);

// With passphrase (BIP-39 standard)
const seed = await Bip39.mnemonicToSeed(mnemonic, 'my secure passphrase');

const seed = Bip39.mnemonicToSeedSync(mnemonic);

Bip39.getWordCount(128); // 12
Bip39.getWordCount(256); // 24

Bip39.getEntropyBits(12); // 128
Bip39.getEntropyBits(24); // 256

Bip39.ENTROPY_128  // 128 bits = 12 words
Bip39.ENTROPY_160  // 160 bits = 15 words
Bip39.ENTROPY_192  // 192 bits = 18 words
Bip39.ENTROPY_224  // 224 bits = 21 words
Bip39.ENTROPY_256  // 256 bits = 24 words
Bip39.SEED_LENGTH  // 64 bytes

import { wordlist as english } from '@scure/bip39/wordlists/english.js';
import { wordlist as spanish } from '@scure/bip39/wordlists/spanish.js';

const mnemonicES = Bip39.generateMnemonic(256, spanish);

const mnemonic = Bip39.generateMnemonic(256);

// Same mnemonic, different passphrases = different seeds
const seed1 = await Bip39.mnemonicToSeed(mnemonic, 'password123');
const seed2 = await Bip39.mnemonicToSeed(mnemonic, 'different');
// seed1 !== seed2

// No passphrase (equivalent to empty string)
const seed3 = await Bip39.mnemonicToSeed(mnemonic);
const seed4 = await Bip39.mnemonicToSeed(mnemonic, '');
// seed3 === seed4

seed = PBKDF2(
  password: mnemonic (normalized to NFKD),
  salt: "mnemonic" + passphrase (normalized to NFKD),
  iterations: 2048,
  hash: SHA-512,
  outputLength: 64 bytes
)

// Valid - uses official wordlist
const mnemonic = Bip39.generateMnemonic(256);

// Invalid - custom words fail checksum
Bip39.validateMnemonic('custom words not in wordlist'); // false

// ✅ SECURE - Uses crypto.getRandomValues()
const mnemonic = Bip39.generateMnemonic(256);

// ❌ NEVER use Math.random() or user-provided "randomness"
const badEntropy = new Uint8Array(32).map(() => Math.floor(Math.random() * 256));

const mnemonic = Bip39.generateMnemonic(256);

// Different passphrases = different wallets
const wallet1 = await Bip39.mnemonicToSeed(mnemonic, 'decoy passphrase');
const wallet2 = await Bip39.mnemonicToSeed(mnemonic, 'real passphrase');
// wallet1 !== wallet2

// Use case: Keep small balance in decoy wallet under duress
// Real funds protected by separate passphrase

// ❌ DANGEROUS
fetch('https://api.example.com', {
  body: JSON.stringify({ mnemonic })
});

// ✅ SAFE - Only transmit public data
const seed = await Bip39.mnemonicToSeed(mnemonic);
const hdKey = HDWallet.fromSeed(seed);
const publicKey = HDWallet.getPublicKey(hdKey);

function importWallet(userMnemonic: string) {
  if (!Bip39.validateMnemonic(userMnemonic)) {
    throw new Error('Invalid mnemonic phrase. Please check for typos.');
  }
  const seed = await Bip39.mnemonicToSeed(userMnemonic);
  // Proceed with seed...
}

// Recommended for significant funds
const mnemonic = Bip39.generateMnemonic(256); // 24 words = 256-bit security

// Acceptable for low-value wallets
const mnemonic12 = Bip39.generateMnemonic(128); // 12 words = 128-bit security

// Invalid word
Bip39.validateMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon xyz');
// false - "xyz" not in wordlist

// Wrong word count
Bip39.validateMnemonic('abandon abandon abandon');
// false - must be 12, 15, 18, 21, or 24 words

// Invalid checksum
Bip39.validateMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon');
// false - checksum invalid

// Wrong entropy length
const badEntropy = new Uint8Array(20); // 160 bits, but wrong
Bip39.entropyToMnemonic(badEntropy); // Error

// Correct
const goodEntropy = Bytes32(); // 256 bits
Bip39.entropyToMnemonic(goodEntropy); // Valid 24-word mnemonic

import * as Bip39 from '@tevm/voltaire/crypto/bip39';
import * as HDWallet from '@tevm/voltaire/crypto/hdwallet';

// 1. Generate mnemonic
const mnemonic = Bip39.generateMnemonic(256);

// 2. Derive seed
const seed = await Bip39.mnemonicToSeed(mnemonic);

// 3. Create HD wallet root
const root = HDWallet.fromSeed(seed);

// 4. Derive accounts (BIP-44)
const eth0 = HDWallet.deriveEthereum(root, 0, 0); // m/44'/60'/0'/0/0
const eth1 = HDWallet.deriveEthereum(root, 0, 1); // m/44'/60'/0'/0/1

// 5. Get keys
const privateKey0 = HDWallet.getPrivateKey(eth0);
const publicKey0 = HDWallet.getPublicKey(eth0);

// From BIP-39 spec
const testMnemonic = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
const testSeed = await Bip39.mnemonicToSeed(testMnemonic, 'TREZOR');

// Expected seed (hex):
// 0c1e24e5...c6e8bc39 (64 bytes)