Documentation

Using Mnemonic

Overview

A mnemonic phrase, also known as a seed phrase or recovery phrase, is a human-readable representation of the cryptographic seed used to generate wallet keys. Typically consisting of 12 or 24 words selected from a standardized word list (BIP39), this phrase encodes the entropy required to deterministically derive an entire hierarchy of private keys and addresses.

Mnemonic phrases are essential for wallet security and recovery. Rather than backing up individual private keys, users can store a single mnemonic phrase that can regenerate all associated keys and addresses. This approach simplifies backup procedures while maintaining robust security. If a device is lost, stolen, or damaged, the wallet can be fully restored using the mnemonic phrase.

The derivation process follows a deterministic path defined by standards such as BIP32 and BIP44. From the mnemonic, a master seed is generated, which then derives a hierarchical tree of key pairs. Each derivation path produces a unique private key and corresponding address, enabling wallets to manage multiple accounts and address types from a single mnemonic.

Refers to the Mnemonic Reference section for technical information about the Mnemonic class.

Generating a Mnemonic

Basic Generation

To generate a basic 24 words mnemonic with LEVEL2 security, call the generate() method on the Mnemonic class without any parameters. This uses the default settings for entropy and security level.

typescript
Generate default 24 words/level2 quantum support
import { Mnemonic, MnemonicStrength } from '@btc-vision/transaction';
import { MLDSASecurityLevel } from '@btc-vision/bip32';
import { networks } from '@btc-vision/bitcoin';

// Generate with default 24 words and LEVEL2 security
const mnemonic = Mnemonic.generate();

console.log('Mnemonic phrase:', mnemonic.phrase);
console.log('Security Level:', mnemonic.securityLevel);

With Custom Strength and Security Level

To generate a mnemonic with custom settings, pass MnemonicStrength and MLDSASecurityLevel values to the generate() method. This allows you to specify the desired entropy level and quantum security strength.

typescript
Generate 12 words/level2 quantum support
import { Mnemonic, MnemonicStrength } from '@btc-vision/transaction';
import { MLDSASecurityLevel } from '@btc-vision/bip32';
import { networks } from '@btc-vision/bitcoin';

const mnemonic = Mnemonic.generate(
    MnemonicStrength.MINIMUM,            // 12 words
    '',                                  // No passphrase
    networks.bitcoin,                    // Mainnet
    MLDSASecurityLevel.LEVEL3            // LEVEL3
);

With Network and Passphrase

Using a passphrase for additional security.

typescript
Using passphrase
import { Mnemonic, MnemonicStrength } from '@btc-vision/transaction';
import { MLDSASecurityLevel } from '@btc-vision/bip32';
import { networks } from '@btc-vision/bitcoin';

// Same mnemonic with different passphrases produces completely different wallets
const mnemonic1 = new Mnemonic(phrase, 'passphrase-A', networks.bitcoin);
const mnemonic2 = new Mnemonic(phrase, 'passphrase-B', networks.bitcoin);

const wallet1 = mnemonic1.derive(0);
const wallet2 = mnemonic2.derive(0);

console.log(wallet1.p2tr === wallet2.p2tr); // false -- different passphrases = different keys

Wallet Derivation

Generate a new wallet from a fresh mnemonic

typescript
Generate a new wallet
import { Mnemonic, MnemonicStrength } from '@btc-vision/transaction';
import { MLDSASecurityLevel } from '@btc-vision/bip32';
import { networks } from '@btc-vision/bitcoin';

// Generate a 24-word mnemonic
const mnemonic = Mnemonic.generate(
    MnemonicStrength.MAXIMUM,
    '',
    networks.bitcoin,
    MLDSASecurityLevel.LEVEL2,
);

// IMPORTANT: Save this phrase securely!
console.log('Mnemonic phrase:', mnemonic.phrase);

// Derive the first wallet
const wallet = mnemonic.derive(0);
console.log('Taproot address:', wallet.p2tr);
console.log('SegWit address:', wallet.p2wpkh);
console.log('Legacy address:', wallet.legacy);

Derive multiple wallets for an HD wallet UI

typescript
Derive multiple wallets
const mnemonic = Mnemonic.generate();

// Derive 10 receiving wallets
const wallets = mnemonic.deriveMultiple(10, 0, 0, false, BIPStandard.BIP84);

for (let i = 0; i < wallets.length; i++) {
    console.log(`Wallet ${i}: ${wallets[i].p2wpkh}`);
}

OPWallet-compatible derivation

typescript
OPWallet-compatible derivation
import { AddressTypes } from '@btc-vision/transaction';

const mnemonic = new Mnemonic(phrase, '', networks.bitcoin);

// Derive as OPWallet would for Taproot
const taprootWallet = mnemonic.deriveOPWallet(AddressTypes.P2TR, 0);
console.log('OPWallet Taproot:', taprootWallet.p2tr);

// Derive multiple OPWallet-compatible wallets
const wallets = mnemonic.deriveMultipleUnisat(AddressTypes.P2TR, 5);
for (const w of wallets) {
    console.log(w.p2tr);
}

Custom derivation paths

typescript
Custom derivation paths
const mnemonic = new Mnemonic(phrase, '', networks.bitcoin);

const wallet = mnemonic.deriveCustomPath(
    "m/86'/0'/0'/0/0",   // Classical: BIP86 Taproot path
    "m/360'/0'/0'/0/0",  // Quantum: BIP360 path
);

console.log(wallet.p2tr);

Loading Existing Mnemonic

From Phrase

To restore a wallet from an existing mnemonic phrase, create a new Mnemonic object and pass the phrase as the first parameter of the constructor.

typescript
Restore a wallet from an existing mnemonic
import { Mnemonic, MnemonicStrength } from '@btc-vision/transaction';
import { MLDSASecurityLevel } from '@btc-vision/bip32';
import { networks } from '@btc-vision/bitcoin';

const phrase = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';

const mnemonic = new Mnemonic(
    phrase,
    '',                                  // Passphrase (use same as generation)
    networks.bitcoin,                    // Network
    MLDSASecurityLevel.LEVEL2            // RECOMMENDED DEFAULT (BIP360) - must match original
);
const wallet = mnemonic.derive(0);

console.log('Restored address:', wallet.p2tr);

Secure disposal

The Mnemoninc class implements the disposable pattern, allowing sensitive key material to be securely zeroed when the object goes out of scope. Using the using keyword ensures automatic cleanup without manual intervention, preventing key data from persisting in memory after use.

typescript
How to securely dispose mnemonic
{
    using mnemonic = Mnemonic.generate();

    const wallet = mnemonic.derive(0);
    const address = wallet.p2tr;

    // ... use wallet for signing
} // mnemonic seed and root keys are zeroed automatically
On this page