Documentation

Using Wallet

The Wallet class is the primary output of Mnemonic.derive(). When you derive wallets from a mnemonic phrase, each derived wallet contains both classical and quantum keys at the specified index.

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

Deriving Wallets

Once a mnemonic is created or restored, derive wallets using the derive() method on the Mnemonic instance. For generating multiple wallets from the same seed, the deriveMultiple() method provides a convenient batch operation.

Advanced derivation options are available for specialized requirements. The deriveCustomPath() method accepts explicit BIP32 paths for both classical and quantum keys. For compatibility with the OPWallet, use deriveOPWallet() or deriveMultipleOPWallet() to generate wallets following OPWallet-specific derivation paths.

Single Wallet Derivation

The following example demonstrates deriving a wallet at index 0 from a generated mnemonic. The resulting wallet provides access to all address formats including Taproot, SegWit, and legacy, as well as both classical and quantum key pairs for signing operations.

typescript
How to derive a single wallet
import { Mnemonic, MnemonicStrength, MLDSASecurityLevel } from '@btc-vision/transaction';
import { networks } from '@btc-vision/bitcoin';

const mnemonic = Mnemonic.generate();

// Derive the first wallet (index 0)
const wallet = mnemonic.derive(0);

// Access all address formats
console.log('Taproot:', wallet.p2tr);
console.log('SegWit:', wallet.p2wpkh);
console.log('Legacy:', wallet.legacy);

// Access key pairs for signing
const classicalSigner = wallet.keypair;
const quantumSigner   = wallet.mldsaKeypair;

Multiple Wallet Derivation

The deriveMultiple() method generates a batch of wallets in a single call. The following example derives five wallets from the same mnemonic and displays their Taproot addresses along with their OP_NET identifiers.

typescript
How to derive multiple wallets
import { Mnemonic, MnemonicStrength, MLDSASecurityLevel } from '@btc-vision/transaction';
import { networks } from '@btc-vision/bitcoin';

const mnemonic = Mnemonic.generate();

// Derive first 5 wallets
const wallets = mnemonic.deriveMultiple(5);

wallets.forEach((wallet, index) => {
    console.log(`Wallet ${index}:`);
    console.log('  P2TR:', wallet.p2tr);
    console.log('  ML-DSA Hash:', wallet.address.toHex());
});

Custom Derivation Path

The deriveCustomPath() method accepts explicit derivation paths for both classical and quantum keys. The following example derives a wallet using BIP84 for the classical key and BIP360 for the quantum key at a specific account and index.

typescript
Use a custom path to derive a single wallet
import { Mnemonic, MnemonicStrength, MLDSASecurityLevel } from '@btc-vision/transaction';
import { networks } from '@btc-vision/bitcoin';

const mnemonic = Mnemonic.generate();

// Custom BIP44/BIP84 path
const customWallet = mnemonic.deriveCustomPath(
    "m/84'/0'/0'/0/5",  // BIP84 path for account 0, index 5
    "m/360'/0'/0'/0/5"  // BIP360 quantum path (parallel)
);

console.log('Custom wallet address:', customWallet.p2wpkh);

Wallet Creation

Creating a Wallet From Existing Keys

When private keys already exist, the Wallet.fromPrivateKeys() method creates a wallet instance directly without mnemonic derivation. This is useful for importing keys from external sources or migrating existing wallets.

typescript
Creating a wallet from existing keys
import { Wallet } from '@btc-vision/transaction';
import { networks } from '@btc-vision/bitcoin';

const wallet = Wallet.fromPrivateKeys(
    '0xe8f32e723decf4051aefac8e2c93c9c5b214313817cdb01a1494b917c8436b35',
    '0xaabbccddee...',  // ML-DSA private key hex
    networks.bitcoin,
);

console.log('P2TR:', wallet.p2tr);
console.log('Address hex:', wallet.address.toHex());

Generating a New Wallet

The Wallet.generate() method creates a new wallet with randomly generated classical and quantum key pairs. The resulting keys can be exported in WIF format for the classical key and Base58 for the quantum key, enabling secure backup and later restoration.

typescript
Generating a new wallet
import { Wallet } from '@btc-vision/transaction';
import { MLDSASecurityLevel } from '@btc-vision/bip32';

const wallet = Wallet.generate(networks.bitcoin, MLDSASecurityLevel.LEVEL2);

// Save keys for later
const wif = wallet.toWIF();
const quantumBase58 = wallet.toQuantumBase58();

console.log('Save this WIF:', wif);
console.log('Save this quantum key:', quantumBase58);

Exporting and Restoring

Wallets can be exported to portable formats for backup and later restored. The toWIF() method exports the classical private key, while toQuantumBase58() exports the quantum key. The Wallet.fromWif() method reconstructs the wallet from these exported values.

typescript
Exporting and restoring
// Export
const wif = wallet.toWIF();
const quantumBase58 = wallet.toQuantumBase58();

// Restore
const restored = Wallet.fromWif(wif, quantumBase58, networks.bitcoin);
console.log(restored.p2tr === wallet.p2tr); // true

Deriving Child Wallets

The derivePath() method derives child wallets from a parent wallet using BIP32 derivation paths. Each unique path produces a distinct child wallet, enabling hierarchical key management from a single parent.

typescript
Deriving child wallets
const parentWallet = new Wallet(classicalWif, quantumBase58, networks.bitcoin);
const child0 = parentWallet.derivePath("m/84'/0'/0'/0/0");
const child1 = parentWallet.derivePath("m/84'/0'/0'/0/1");

console.log(child0.p2wpkh); // Different from child1
console.log(child1.p2wpkh);

Secure disposal

The Wallet 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 wallet
{
    using wallet = Wallet.fromPrivateKeys(classicalHex, quantumHex, networks.bitcoin);

    // Sign a transaction
    const signature = wallet.keypair.sign(txHash);

    // ... broadcast transaction
} // Private keys are automatically zeroed here
On this page