Documentation
Imported from @btc-vision/bip32. Defines the ML-DSA (FIPS 204) security level for quantum-resistant key generation.
Mnemonic
Overview
Manages BIP39 mnemonic phrases with BIP360 quantum-resistant wallet derivation. The Mnemonic class creates both a classical BIP32 HD key tree (for ECDSA/Schnorr) and a quantum BIP32 HD key tree (for ML-DSA) from a single mnemonic seed phrase, enabling deterministic derivation of hybrid wallets that contain both key types.
The Mnemonic implements Disposable for secure zeroing of seed material.
The full source code is available on GitHub at Mnemonic.ts.
Import
import { Mnemonic, MnemonicStrength, BIPStandard } from '@btc-vision/transaction';
import { MLDSASecurityLevel } from '@btc-vision/bip32';
import { networks } from '@btc-vision/bitcoin';Enums and Interfaces
Signature
enum MLDSASecurityLevel {
LEVEL2 = 44,
LEVEL3 = 65,
LEVEL5 = 87,
}Description
Enumeration Values
| Value | Description |
|---|---|
| LEVEL2 | ML-DSA-44 Recommended default. Sufficient quantum resistance with smaller keys. Public key size: 1312 bytes. |
| LEVEL3 | ML-DSA-65 Higher security margin. Public key size: 1952 bytes.> |
| LEVEL5 | ML-DSA-87 Maximum security. Significantly larger keys and signatures. Public key size: 2592 bytes. |
Signature
enum MnemonicStrength {
MINIMUM = 128,
LOW = 160,
MEDIUM = 192,
HIGH = 224,
MAXIMUM = 256,
}Description
Defines the entropy strength (in bits) for mnemonic phrase generation. Higher entropy produces longer phrases with more security.
Enumeration Values
| Value | Description |
|---|---|
| MINIMUM | Entropy: 128 bits Word count: 12 words |
| LOW | Entropy: 160 bits Word count: 15 words |
| MEDIUM | Entropy: 192 bits Word count: 18 words |
| HIGH | Entropy: 224 bits Word count: 21 words"> |
| MAXIMUM | Entropy: 256 bits Word count: 24 words |
Signature
enum BIPStandard {
BIP44 = 44,
BIP49 = 49,
BIP84 = 84,
BIP86 = 86,
}Description
Defines the BIP derivation path standard for classical keys. The quantum path always uses BIP360 (m/360'/...).
Enumeration Values
| Value | Description |
|---|---|
| BIP44 | Purpose: 44 Address type: P2PKH (legacy) |
| BIP49 | Purpose: 49 Address type: P2SH-P2WPKH (nested SegWit) |
| BIP84 | Purpose: 84 Address type: P2WPKH (native SegWit) |
| BIP86 | Purpose: 86 Address type: P2TR (Taproot) |
Constructor
Signature
new Mnemonic(phrase: string, passphrase?: string, network?: Network, securityLevel?: MLDSASecurityLevel)Description
Creates a Mnemonic instance from an existing BIP39 mnemonic phrase.
The constructor:
- Validates the mnemonic phrase using BIP39.
- Derives a 64-byte seed from the phrase and passphrase using PBKDF2.
- Creates a classical BIP32 root key from the seed.
- Creates a quantum BIP32 root key from the seed using the specified ML-DSA security level.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| phrase | string | Yes | - | A valid BIP39 mnemonic phrase (12-24 words separated by spaces). |
| passphrase | string | No | Empty string | An optional BIP39 passphrase for additional entropy. |
| network | Network | No | networks.bitcoin | The Bitcoin network. Affects coin type in derivation paths (0 for mainnet, 1 for testnet/opnetTestnet/regtest). |
| securityLevel | MLDSASecurityLevel | No | MLDSASecurityLevel.LEVEL2 | The ML-DSA security level for quantum key derivation. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the mnemonic phrase is invalid. |
typescript
const mnemonic = new Mnemonic(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
'my-passphrase',
networks.bitcoin,
MLDSASecurityLevel.LEVEL2,
);Static Methods
Signature
static generatePhrase(strength?: MnemonicStrength): stringDescription
Generates a new random BIP39 mnemonic phrase without creating a Mnemonic instance.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| strength | MnemonicStrength | No | MnemonicStrength.MAXIMUM (256 bits / 24 words). | The entropy strength for phrase generation. |
Returns
| Type | Description |
|---|---|
| string | A space-separated BIP39 mnemonic phrase. |
typescript
const phrase = Mnemonic.generatePhrase(MnemonicStrength.MAXIMUM);
console.log(phrase); // 24-word mnemonic phraseSignature
static generate(strength?: MnemonicStrength, passphrase?: string, network?: Network, securityLevel?: MLDSASecurityLevel): MnemonicDescription
Generates a new random mnemonic phrase and creates a fully initialized Mnemonic instance.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| strength | MnemonicStrength | No | MnemonicStrength.MAXIMUM | The entropy strength. |
| passphrase | string | No | Empty string | Optional BIP39 passphrase. |
| network | Network | No | networks.bitcoin | The Bitcoin network. |
| securityLevel | MLDSASecurityLevel | No | MLDSASecurityLevel.LEVEL2 | The ML-DSA security level. |
Returns
| Type | Description |
|---|---|
| Mnemonic | The created object. |
typescript
const mnemonic = Mnemonic.generate(
MnemonicStrength.MAXIMUM,
'',
networks.bitcoin,
MLDSASecurityLevel.LEVEL2,
);
console.log(mnemonic.phrase); // Save this phrase securely!Signature
static validate(phrase: string): booleanDescription
Validates whether a string is a valid BIP39 mnemonic phrase.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| phrase | string | Yes | The mnemonic phrase to validate. |
Returns
| Type | Description |
|---|---|
| boolean | true if valid, false otherwise. |
typescript
const isValid = Mnemonic.validate('abandon abandon abandon ...');
console.log(isValid); // true or falseInstance Methods
Signature
derive(index?: number, account?: number, isChange?: boolean, bipStandard?: BIPStandard): WalletDescription
Derives a Wallet at the specified index using standard BIP derivation paths. Both classical and quantum keys are derived from their respective root keys.
Derivation paths used:
- Classical: m/<purpose>'/<coin_type>'/<account>'/<change>/<index> (purpose depends on bipStandard).
- Quantum: m/360'/<coin_type>'/<account>'/<change>/<index>.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| index | number | No | 0 | The address index within the account. |
| account | number | No | 0 | The account number. |
| isChange | boolean | No | false | Whether to derive from the change chain (true: change, false: receiving). |
| bipStandard | BIPStandard | No | BIPStandard.BIP84 | The BIP standard for classical key derivation path. |
Returns
| Type | Description |
|---|---|
| Wallet | The new Wallet object. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if key derivation fails. |
typescript
const wallet0 = mnemonic.derive(0); // First wallet
const wallet1 = mnemonic.derive(1); // Second wallet
console.log(wallet0.p2tr); // Taproot address for wallet 0
console.log(wallet1.p2wpkh); // SegWit address for wallet 1Signature
deriveOPWallet(addressType?: AddressTypes, index?: number, account?: number, isChange?: boolean): WalletDescription
Derives a wallet using OPWallet-compatible derivation paths. This uses the same path format as the OPWallet browser extension, where the classical key purpose is determined by the target address type.
| Address Type | Purpose | Classical Path |
|---|---|---|
| P2PKH | 44 | m/44'/0'/<account>'/<change>/<index> |
| P2SH_OR_P2SH_P2WPKH | 49 | m/49'/0'/<account>'/<change>/<index> |
| P2WPKH | 84 | m/84'/0'/<account>'/<change>/<index> |
| P2TR | 86 | m/86'/0'/<account>'/<change>/<index> |
The quantum path is always m/360'/<coin_type>'/<account>'/<change>/<index>.
Note
The classical coin type is hardcoded to 0' regardless of network. The quantum coin type is network-aware: 0 for mainnet, 1 for testnet/opnetTestnet/regtest.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| addressType | AddressTypes | No | AddressTypes.P2TR | The target address type, which determines the classical derivation purpose. |
| index | number | No | 0 | The address index. |
| account | number | No | 0 | The account number. |
| isChange | boolean | No | false | Whether to derive from the change chain. |
Returns
| Type | Description |
|---|---|
| Wallet | The new Wallet object. |
Throws
| Type | Description |
|---|---|
| Error | Thrown for unsupported address types. |
typescript
import { AddressTypes } from '@btc-vision/transaction';
const taprootWallet = mnemonic.deriveOPWallet(AddressTypes.P2TR, 0);
const segwitWallet = mnemonic.deriveOPWallet(AddressTypes.P2WPKH, 0);
console.log(taprootWallet.p2tr); // Taproot address
console.log(segwitWallet.p2wpkh); // SegWit addressSignature
deriveMultiple(count: number, startIndex?: number, account?: number, isChange?: boolean, bipStandard?: BIPStandard): Wallet[]Description
Derives multiple wallets in sequence starting from startIndex.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| count | number | Yes | - | The number of wallets to derive. |
| startIndex | number | No | 0 | The starting address index. |
| account | number | No | 0 | The account number. |
| isChange | boolean | No | false | Whether to use the change chain. |
| bipStandard | BIPStandard | No | BIPStandard.BIP84 | The BIP standard for classical paths. |
Returns
| Type | Description |
|---|---|
| Wallet[] | The new Wallets array. |
typescript
const wallets = mnemonic.deriveMultiple(5);
for (const w of wallets) {
console.log(w.p2tr);
}Signature
deriveMultipleOPWallet(addressType?: AddressTypes, count?: number, startIndex?: number, account?: number, isChange?: boolean): Wallet[]Description
Derives multiple wallets using OPWallet-compatible paths.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| addressType | AddressTypes | No | AddressTypes.P2TR | The target address type. |
| count | number | No | 5 | Number of wallets to derive. |
| startIndex | number | No | 0 | Starting index. |
| account | number | No | 0 | Account number. |
| isChange | boolean | No | false | Use change chain. |
Returns
| Type | Description |
|---|---|
| Wallet[] | The new Wallets array. |
Signature
deriveCustomPath(classicalPath: string, quantumPath: string): WalletDescription
Derives a wallet using fully custom derivation paths for both classical and quantum keys.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| classicalPath | string | Yes | The BIP32 derivation path for the classical key (e.g., "m/44'/0'/0'/0/0"). |
| quantumPath | string | Yes | The BIP32 derivation path for the quantum key (e.g., "m/360'/0'/0'/0/0"). |
Returns
| Type | Description |
|---|---|
| Wallet | The new Wallet object. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if either derivation fails. |
typescript
const wallet = mnemonic.deriveCustomPath(
"m/86'/0'/0'/0/0", // Classical: BIP86 Taproot
"m/360'/0'/0'/0/0", // Quantum: BIP360
);Signature
getClassicalRoot(): BIP32InterfaceDescription
Returns the classical BIP32 root key derived from the seed. This can be used for manual derivation or inspection.
Returns
| Type | Description |
|---|---|
| BIP32Interface | The classical BIP32 root key. |
Signature
getQuantumRoot(): QuantumBIP32InterfaceDescription
Returns the quantum BIP32 root key derived from the seed. This can be used for manual derivation or inspection.
Returns
| Type | Description |
|---|---|
| QuantumBIP32Interface | The quantum BIP32 root key. |
Signature
zeroize(): voidDescription
Zeroes the seed buffer and root private keys in-place. The mnemonic phrase and passphrase are JavaScript strings and cannot be zeroed by the runtime.
Signature
[Symbol.dispose](): voidDescription
Implements the Disposable interface. Calls zeroize() to clear secret material.
typescript
{
using mnemonic = Mnemonic.generate();
const wallet = mnemonic.derive(0);
// ... use wallet
} // seed and root keys are zeroed automaticallyProperties
Signature
get phrase(): stringDescription
Get the BIP39 mnemonic phrase.
Returns
| Type | Description |
|---|---|
| string | The BIP39 mnemonic phrase. |
Signature
get network(): NetworkDescription
Get the Bitcoin network this mnemonic is configured for.
Returns
| Type | Description |
|---|---|
| Network | The Bitcoin network. |
Signature
get securityLevel(): MLDSASecurityLevelDescription
Get the ML-DSA security level used for quantum key derivation.
Returns
| Type | Description |
|---|---|
| MLDSASecurityLevel | The ML-DSA security level. |
Signature
get seed(): Uint8ArrayDescription
A copy of the 64-byte seed derived from the mnemonic and passphrase.
Returns
| Type | Description |
|---|---|
| Uint8Array | The 64-byte seed. |
Derivation Paths
Classical Paths
The classical derivation path follows the standard BIP32 format:
m/<purpose>'/<coin_type>'/<account>'/<change>/<index>- purpose: Determined by BIPStandard (44, 49, 84, or 86).
- coin_type: 0 for mainnet, 1 for testnet, opnetTestnet, and regtest.
- account: Account index (hardened).
- change: 0 for receiving addresses, 1 for change addresses.
- index: Address index within the chain.
Quantum Paths
The quantum derivation path always uses purpose 360 (BIP360):
m/360'/<coin_type>'/<account>'/<change>/<index>This ensures quantum keys are derived independently from classical keys while using the same account/index structure.