Wallet

Overview

Manages both classical (ECDSA/Schnorr) and quantum-resistant (ML-DSA) key pairs in a unified interface. The Wallet class encapsulates key derivation, address generation for all Bitcoin address types, and secure disposal of private key material. It integrates with the Mnemonic class for BIP39/BIP360 hierarchical deterministic derivation.

The Wallet implements Disposable for secure zeroing of private key buffers.

The full source code is available on GitHub at Wallet.ts.

Import

import { Wallet } from '@btc-vision/transaction';
import { MLDSASecurityLevel } from '@btc-vision/bip32';
import { networks } from '@btc-vision/bitcoin';

Constructor

constructor()

Signature

new Wallet(privateKeyOrWif: string, mldsaPrivateKeyOrBase58: string, network?: Network, securityLevel?: MLDSASecurityLevel, chainCode?: Uint8Array)

Description

Creates a new Wallet instance from both a classical private key and a quantum ML-DSA private key.

The constructor:

Parses the classical private key (hex or WIF) and creates an ECDSA signer.
Parses the ML-DSA private key (hex or base58) and creates a quantum signer.
Creates an Address from both public keys.
Pre-computes all address formats (P2TR, P2WPKH, P2PKH, P2SH-P2WPKH, P2WDA).

Parameters

Name	Type	Required	Default	Description
privateKeyOrWif	string	Yes	-	The classical private key. Accepts 0x-prefixed hex, raw hex, or WIF-encoded format.
mldsaPrivateKeyOrBase58	string	Yes	-	The ML-DSA private key. Accepts 0x-prefixed hex, raw hex, or base58-encoded quantum key (from toBase58()).
network	Network	No	networks.bitcoin	The Bitcoin network.
securityLevel	MLDSASecurityLevel	No	MLDSASecurityLevel.LEVEL2	The ML-DSA security level. Ignored if mldsaPrivateKeyOrBase58 is base58 (level is embedded).
chainCode	Uint8Array	No	new Uint8Array(32)	The 32-byte BIP32 chain code for hierarchical derivation.

Throws

Type	Description
Error	Thrown if the ML-DSA key length does not match the expected size for the given security level.
Error	Thrown if the chain code is provided but is not exactly 32 bytes.

Static Methods

fromWif()

Signature

static fromWif(wif: string, quantumPrivateKeyHex: string, network?: Network, securityLevel?: MLDSASecurityLevel, chainCode?: Uint8Array): Wallet

Description

Creates a Wallet from a WIF-encoded classical private key and a hex-encoded quantum private key. This is a convenience wrapper around the constructor.

Parameters

Name	Type	Required	Default	Description
wif	string	Yes	-	The WIF-encoded classical private key.
quantumPrivateKeyHex	string	Yes	-	The ML-DSA private key in hex format.
network	Network	No	networks.bitcoin	The Bitcoin network.
securityLevel	MLDSASecurityLevel	No	MLDSASecurityLevel.LEVEL2	The ML-DSA security level.
chainCode	Uint8Array	No	-	Optional BIP32 chain code.

Returns

Type	Description
Wallet	The new Wallet object.

typescript

const wallet = Wallet.fromWif(
    'L4rK1yDtCWekvXuE6oXD9jCYfFNV2cWRpVuPLBcCU2z8TrisoyY1',
    '0xaabbccdd...',
    networks.bitcoin,
);

fromPrivateKeys()

Signature

static fromPrivateKeys(privateKeyHexOrWif: string, mldsaPrivateKeyOrBase58: string, network?: Network, securityLevel?: MLDSASecurityLevel, chainCode?: Uint8Array): Wallet

Description

Creates a Wallet from either hex or WIF classical private keys and either hex or base58 quantum private keys. This is the most flexible factory method.

Parameters

Name	Type	Required	Default	Description
privateKeyHexOrWif	string	Yes	-	Classical private key (hex or WIF).
mldsaPrivateKeyOrBase58	string	Yes	-	ML-DSA private key (hex or base58).
network	Network	No	networks.bitcoin	The Bitcoin network.
securityLevel	MLDSASecurityLevel	No	MLDSASecurityLevel.LEVEL2	The ML-DSA security level.
chainCode	Uint8Array	No	-	Optional BIP32 chain code.

Returns

Type	Description
Wallet	The new Wallet object.

generate()

Signature

static generate(network?: Network, securityLevel?: MLDSASecurityLevel): Wallet

Description

Generates a completely new random wallet with both classical and quantum key pairs.

Parameters

Name	Type	Required	Default	Description
network	Network	No	networks.bitcoin	The Bitcoin network.
securityLevel	MLDSASecurityLevel	No	MLDSASecurityLevel.LEVEL2	The ML-DSA security level.

Returns

Type	Description
Wallet	The new Wallet object.

Throws

Type	Description
Error	Thrown if quantum key generation fails.

typescript

const wallet = Wallet.generate(networks.bitcoin, MLDSASecurityLevel.LEVEL2);
console.log(wallet.p2tr);      // 'bc1p...'
console.log(wallet.p2wpkh);    // 'bc1q...'

Instance Methods

toWIF()

Signature

toWIF(): string

Description

Exports the classical private key in Wallet Import Format (WIF).

Returns

Type	Description
string	The WIF-encoded classical private key.

typescript

const wif = wallet.toWIF();
console.log(wif); // 'L4rK1yDt...'

toPrivateKeyHex()

Signature

toPrivateKeyHex(): string

Description

Exports the classical private key as a hex string.

Returns

Type	Description
string	The classical private key as a hex string.

Throws

Type	Description
Error	Thrown if the private key is not available.

toPublicKeyHex()

Signature

toPublicKeyHex(): string

Description

Exports the classical public key as a hex string.

Returns

Type	Description
string	The classical public key as a hex string.

toQuantumBase58()

Signature

toQuantumBase58(): string

Description

Exports the quantum ML-DSA key pair in base58 encoding. This format includes the chain code and security level, making it suitable for storage and re-import.

Returns

Type	Description
string	The quantum ML-DSA key pair in base58 encoding.

typescript

const base58 = wallet.toQuantumBase58();
// Later, reconstruct:
const restored = new Wallet('...wif...', base58, networks.bitcoin);

derivePath()

Signature

derivePath(path: string): Wallet

Description

Derives a child wallet at the given BIP32 path. Both the classical and quantum keys are derived along the same path.

Parameters

Name	Type	Required	Description
path	string	Yes	A BIP32 derivation path (e.g., "m/84'/0'/0'/0/0").

Returns

Type	Description
Wallet	A new child wallet.

Throws

Type	Description
Error	Thrown if the wallet has no private key (watch-only) or if derivation fails.

typescript


                    const child = wallet.derivePath("m/84'/0'/0'/0/0");
                    console.log(child.p2wpkh); // derived SegWit address

zeroize()

Signature

zeroize(): void

Description

Zeroes all private key material in-place. This includes the classical private key, the quantum private key, and the chain code. After calling zeroize(), the wallet can no longer sign transactions.

Note

JavaScript runtime constraints mean that copies made by the runtime (e.g., during garbage collection) cannot be zeroed. This method eliminates the primary references.

[Symbol.dispose]()

Signature

[Symbol.dispose](): void

Description

Implements the Disposable interface. Calls zeroize() to securely clear all private key material.

typescript

{
    using wallet = Wallet.generate();
    const signed = wallet.keypair.sign(messageHash);
    // ... use wallet
} // wallet.zeroize() called automatically

Properties

address

Signature

get address(): Address

Description

Get the unified Address object containing both ML-DSA hash and classical tweaked key.

Returns

Type	Description
Address	The unified Address object.

p2tr

Signature

get p2tr(): string

Description

Get the Taproot (P2TR) address (e.g., bc1p...).

Returns

Type	Description
string	The Taproot (P2TR) address.

p2wpkh

Signature

get p2wpkh(): string

Description

Get the native SegWit (P2WPKH) address (e.g., bc1q...).

Returns

Type	Description
string	The native SegWit (P2WPKH) address.

legacy

Signature

get legacy(): string

Description

Get the legacy (P2PKH) address (e.g., 1...).

Returns

Type	Description
string	The legacy (P2PKH) address.

segwitLegacy

Signature

get segwitLegacy(): string

Description

Get the nested SegWit (P2SH-P2WPKH) address (e.g., 3...).

Returns

Type	Description
string	The nested SegWit (P2SH-P2WPKH) address.

p2wda

Signature

get p2wda(): IP2WSHAddress

Description

Get the P2WDA address object with address and witnessScript.

Returns

Type	Description
IP2WSHAddress	The P2WDA address object.

addresses

Signature

get addresses(): string[]

Description

Get an array of all four standard address formats: [p2wpkh, p2tr, legacy, segwitLegacy].

Returns

Type	Description
string[]	An array of all four standard address.

keypair

Signature

get keypair(): UniversalSigner

Description

Get the classical ECDSA/Schnorr key pair. Can sign and verify.

Returns

Type	Description
UniversalSigner	The classical ECDSA/Schnorr key pair.

mldsaKeypair

Signature

get mldsaKeypair(): QuantumBIP32Interface

Description

Get the quantum ML-DSA key pair. Supports BIP32-style derivation.

Returns

Type	Description
QuantumBIP32Interface	The quantum ML-DSA key pair.

publicKey

Signature

get publicKey(): Uint8Array

Description

Get the 33-byte compressed classical public key.

Returns

Type	Description
Uint8Array	The compressed classical public key.

tweakedPubKeyKey

Signature

get tweakedPubKeyKey(): Uint8Array

Description

Get the 32-byte x-only tweaked classical public key.

Returns

Type	Description
Uint8Array	The x-only tweaked classical public key.

xOnly

Signature

get xOnly(): Uint8Array

Description

Get the x-only (32-byte) classical public key (before tweaking).

Returns

Type	Description
Uint8Array	The x-only classical public key.

quantumPublicKey

Signature

get quantumPublicKey(): Uint8Array

Description

Get the raw ML-DSA public key bytes (copy).

Returns

Type	Description
Uint8Array	The raw ML-DSA public key.

quantumPrivateKey

Signature

get quantumPrivateKey(): Uint8Array

Description

Get the raw ML-DSA private key bytes (copy).

Returns

Type	Description
Uint8Array	The raw ML-DSA private key.

Throws

Type	Description
Error	Throws if not available.

quantumPublicKeyHex

Signature

get quantumPublicKeyHex(): string

Description

Get the ML-DSA public key as a hex string.

Returns

Type	Description
string	The ML-DSA public key.

quantumPrivateKeyHex

Signature

get quantumPrivateKeyHex(): string

Description

Get the ML-DSA private key as a hex string.

Returns

Type	Description
string	The ML-DSA private key.

Throws

Type	Description
Error	Throws if not available.

securityLevel

Signature

get securityLevel(): MLDSASecurityLevel

Description

Get the ML-DSA security level of this wallet.

Returns

Type	Description
MLDSASecurityLevel	The ML-DSA security level.

chainCode

Signature

get chainCode(): Uint8Array

Description

Get the 32-byte BIP32 chain code.

Returns

Type	Description
Uint8Array	The BIP32 chain code.

network

Signature

get network(): Network

Description

Get the Bitcoin network this wallet is configured for.

Returns

Type	Description
Network	The Bitcoin network.