Mnemonic

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.

Generating a Mnemonic

Mnemonic Strengths

When generating mnemonic phrases in OP_NET, use the MnemonicStrength enum to specify the desired entropy level. This enum defines multiple strength options, each producing a mnemonic of different length and security characteristics.

The following code is from the MnemonicStrength.ts file:

typescript

enum MnemonicStrength {
    MINIMUM = 128,   // 12 words - Standard
    LOW = 160,       // 15 words
    MEDIUM = 192,    // 18 words
    HIGH = 224,      // 21 words
    MAXIMUM = 256    // 24 words - Maximum entropy
}

Basic Generation

To generate a basic 12-word 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.

The following example demonstrate how to generate the default 12 word mnemonic with level2 quantum support:

typescript

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

// Generate with default 12 words and LEVEL2 security (BIP360 RECOMMENDED DEFAULT)
const mnemonic = Mnemonic.generate();

console.log('Mnemonic phrase:', mnemonic.phrase);
console.log('Security Level:', mnemonic.securityLevel); // LEVEL2 (default)
// Output: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"

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.

The following example demonstrate how use custom values to generate a new 24-word mnemonic with quantum support:

typescript

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

// RECOMMENDED: Use LEVEL2 (BIP360 default) for most applications
const recommendedMnemonic = Mnemonic.generate(
    MnemonicStrength.MAXIMUM,            // 24 words
    '',                                  // No passphrase
    networks.bitcoin,                    // Mainnet
    MLDSASecurityLevel.LEVEL2            // RECOMMENDED DEFAULT (BIP360)
);

console.log('Words:', recommendedMnemonic.phrase.split(' ').length); // 24
console.log('Security Level:', recommendedMnemonic.securityLevel);   // LEVEL2

// OPTIONAL: Use LEVEL5 only for maximum security in high-value applications
const maxSecurityMnemonic = Mnemonic.generate(
    MnemonicStrength.MAXIMUM,            // 24 words
    '',                                  // No passphrase
    networks.bitcoin,                    // Mainnet
    MLDSASecurityLevel.LEVEL5            // Maximum quantum security (optional)
);

console.log('Security Level:', maxSecurityMnemonic.securityLevel);   // LEVEL5

With Network and Passphrase

To generate a mnemonic with a specific network and passphrase, pass the Network and BIP39 passphrase values to the generate() method. The passphrase adds an additional layer of security to the mnemonic derivation process.

The following example demonstrate how to generate a new 12-word mnemonic using a passphrase and a network with quantum support:

typescript

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

// Generate for testnet with BIP39 passphrase
const testnetMnemonic = Mnemonic.generate(
    MnemonicStrength.MINIMUM,            // 12 words
    'my-secret-passphrase',              // BIP39 passphrase (optional)
    networks.testnet,                    // Testnet network
    MLDSASecurityLevel.LEVEL2            // RECOMMENDED DEFAULT (BIP360)
);

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.

The following example demonstrate how to load a mnemonic using an existing phrase:

typescript

import { Mnemonic, MnemonicStrength, MLDSASecurityLevel } from '@btc-vision/transaction';
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
);

console.log('Network:', mnemonic.network.bech32);     // 'bc'
console.log('Security:', mnemonic.securityLevel);     // LEVEL2 (BIP360 default)

Validating Mnemonic

Mnemonic validation is performed in Mnemonic constructor. If you need to do it somewhere else install the bip39 package. Install it using npm, then use the validateMnemonic() function to verify that the phrase contains valid words and a correct checksum.

The following example demonstrate how to validate a mnemonic using an existing phrase:

typescript

import * as bip39 from 'bip39';
import {Mnemonic} from '@btc-vision/transaction';

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

// Validate BIP39 mnemonic
if (!bip39.validateMnemonic(phrase)) {
    throw new Error('Invalid mnemonic phrase');
}

const mnemonic = new Mnemonic(phrase);