EcKeyPair

Overview

Provides static utility methods for working with classical ECDSA/Schnorr key pairs on Bitcoin. EcKeyPair handles key generation, derivation, address generation, Taproot tweaking, multi-signature address creation, and address verification. It uses the secp256k1 curve with precomputed tables for optimized performance.

This class is entirely static and is not meant to be instantiated.

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

Import

import { EcKeyPair } from '@btc-vision/transaction';
import { networks } from '@btc-vision/bitcoin';

Static Methods

Key Pair Creation

fromWIF()

Signature

static fromWIF(wif: string, network?: Network): UniversalSigner

Description

Creates a key pair from a Wallet Import Format (WIF) encoded private key.

Parameters

Name	Type	Required	Default	Description
wif	string	Yes	-	The WIF-encoded private key string.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
UniversalSigner	A key pair capable of both ECDSA and Schnorr signing.

typescript

const signer = EcKeyPair.fromWIF('L1a2b3c4d5...', networks.bitcoin);
console.log(signer.publicKey); // Uint8Array (33 bytes compressed)

fromPrivateKey()

Signature

static fromPrivateKey(privateKey: Uint8Array | PrivateKey, network?: Network): UniversalSigner

Description

Creates a key pair from a raw private key.

Parameters

Name	Type	Required	Default	Description
privateKey	Uint8Array \| PrivateKey	Yes	-	The 32-byte raw private key.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
UniversalSigner	A key pair capable of both ECDSA and Schnorr signing.

typescript

import { fromHex } from '@btc-vision/bitcoin';

const privKey = fromHex('e8f32e723decf4051aefac8e2c93c9c5b214313817cdb01a1494b917c8436b35');
const signer = EcKeyPair.fromPrivateKey(privKey, networks.testnet);

fromPublicKey()

Signature

static fromPublicKey(publicKey: Uint8Array | PublicKey, network?: Network): UniversalSigner

Description

Creates a verification-only key pair from a public key. The resulting signer can verify signatures but cannot sign.

Parameters

Name	Type	Required	Default	Description
publicKey	Uint8Array \| PublicKey	Yes	-	The 33-byte compressed public key.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
UniversalSigner	A verification-only key pair.

generateRandomKeyPair()

Signature

static generateRandomKeyPair(network?: Network): UniversalSigner

Description

Generates a cryptographically random key pair using secure random bytes.

Parameters

Name	Type	Required	Default	Description
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
UniversalSigner	A key pair capable of both ECDSA and Schnorr signing.

typescript

const randomSigner = EcKeyPair.generateRandomKeyPair(networks.bitcoin);
console.log(randomSigner.toWIF()); // WIF-encoded private key

fromSeed()

Signature

static fromSeed(seed: Uint8Array, network?: Network): BIP32Interface

Description

Creates a BIP32 hierarchical deterministic key from a seed. The returned BIP32Interface supports path derivation.

Parameters

Name	Type	Required	Default	Description
seed	Uint8Array	Yes	-	The seed bytes (typically 64 bytes from a mnemonic).
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
BIP32Interface

fromSeedKeyPair()

Signature

static fromSeedKeyPair(seed: Uint8Array, network?: Network): UniversalSigner

Description

Creates a UniversalSigner directly from a seed by deriving the root key pair.

Parameters

Name	Type	Required	Default	Description
seed	Uint8Array	Yes	-	The seed bytes.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
UniversalSigner	A key pair capable of both ECDSA and Schnorr signing.

Throws

Type	Description
Error	Thrown if the private key cannot be derived.

Wallet Generation

generateWallet()

Signature

static generateWallet(network?: Network, securityLevel?: MLDSASecurityLevel): IWallet

Description

Generates a complete random wallet with both classical (ECDSA) and quantum-resistant (ML-DSA) keys.

Parameters

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

Returns

Type	Description
IWallet	The new wallet.

typescript

const wallet = EcKeyPair.generateWallet(networks.bitcoin);
console.log(wallet.address);          // 'bc1q...'
console.log(wallet.publicKey);        // hex string
console.log(wallet.quantumPublicKey); // hex string (ML-DSA)

generateQuantumKeyPair()

Signature

static generateQuantumKeyPair(securityLevel?: MLDSASecurityLevel, network?: Network): MLDSAKeyPair

Description

Generates a standalone quantum-resistant ML-DSA key pair without BIP32 derivation.

Parameters

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

Returns

Type	Description
MLDSAKeyPair	An object with privateKey and publicKey as Uint8Array.

Address Generation

getTaprootAddress()

Signature

static getTaprootAddress(keyPair: UniversalSigner | Signer, network?: Network): string

Description

Generates a Taproot (P2TR) address from a key pair using BIP86 derivation (internal pubkey only, no scripts).

Parameters

Name	Type	Required	Default	Description
keyPair	UniversalSigner \| Signer	Yes	-	The key pair to derive the address from.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
string	A bech32m Taproot address (e.g., bc1p...).

typescript

const signer = EcKeyPair.fromWIF('L1a2b3c4...', networks.bitcoin);
const taprootAddr = EcKeyPair.getTaprootAddress(signer, networks.bitcoin);
console.log(taprootAddr); // 'bc1p...'

getP2WPKHAddress()

Signature

static getP2WPKHAddress(keyPair: UniversalSigner | Signer, network?: Network): string

Description

Generates a native SegWit (P2WPKH) address.

Parameters

Name	Type	Required	Default	Description
keyPair	UniversalSigner \| Signer	Yes	-	The key pair.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
string	A bech32 SegWit address (e.g., bc1q...).

getLegacyAddress()

Signature

static getLegacyAddress(keyPair: UniversalSigner, network?: Network): string

Description

Generates a legacy (P2PKH) address.

Parameters

Name	Type	Required	Default	Description
keyPair	UniversalSigner	Yes	-	The key pair.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
string	A legacy address (e.g., 1...).

getLegacySegwitAddress()

Signature

static getLegacySegwitAddress(keyPair: UniversalSigner, network?: Network): string

Description

Generates a nested SegWit (P2SH-P2WPKH) address.

Parameters

Name	Type	Required	Default	Description
keyPair	UniversalSigner	Yes	-	The key pair.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
string	A nested SegWit address (e.g., 3...).

getP2PKH()

Signature

static getP2PKH(publicKey: PublicKey, network?: Network): string

Description

Generates a P2PKH address directly from a public key without requiring a full signer.

Parameters

Name	Type	Required	Default	Description
publicKey	PublicKey	Yes	-	The 33-byte compressed public key.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
string

getP2PKAddress()

Signature

static getP2PKAddress(keyPair: UniversalSigner, network?: Network): string

Description

Gets the P2PK (Pay-to-Public-Key) output script as a 0x-prefixed hex string. Note that P2PK outputs do not have a standard address format; this returns the raw output script.

Parameters

Name	Type	Required	Default	Description
keyPair	UniversalSigner	Yes	-	The key pair.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
string	0x-prefixed hex of the output script.

getTaprootAddressFromAddress()

Signature

static getTaprootAddressFromAddress(inAddr: string, network?: Network): string

Description

Converts an existing address string to a Taproot address.

Parameters

Name	Type	Required	Default	Description
inAddr	string	Yes	-	The input address.
network	Network	No	networks.bitcoin	The Bitcoin network

Returns

Type	Description
string	A Taproot address.

p2op()

Signature

static p2op(bytes: Uint8Array, network?: Network, deploymentVersion?: number): string

Description

Generates a P2OP (Pay-to-OPNet) address using witness version 16 and a hash160 of the input bytes.

Parameters

Name	Type	Required	Default	Description
bytes	Uint8Array	Yes	-	The bytes to hash for the witness program (typically the ML-DSA hash).
network	Network	No	networks.bitcoin	The Bitcoin network.
deploymentVersion	number	No	0	The OPNet deployment version byte.

Returns

Type	Description
string	A bech32m P2OP address.

generateMultiSigAddress()

Signature

static generateMultiSigAddress(pubKeys: Uint8Array[] | PublicKey[], minimumSignatureRequired: number, network?: Network): string

Description

Generates an M-of-N multi-signature P2WSH address from a set of public keys.

Parameters

Name	Type	Required	Default	Description
pubKeys	Uint8Array[] \| PublicKey[]	Yes	-	Array of compressed public keys (33 bytes each).
minimumSignatureRequired	number	Yes	-	The minimum number of signatures required to spend (M in M-of-N).
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
string	A P2WSH multi-sig address (e.g., bc1q...).

Throws

Type	Description
Error	Thrown if any public key is invalid or if address generation fails.

typescript

const multiSigAddr = EcKeyPair.generateMultiSigAddress(
    [pubKeyA, pubKeyB, pubKeyC],
    2,  // 2-of-3
    networks.bitcoin,
);
console.log(multiSigAddr); // 'bc1q...' (P2WSH)

Public Key Operations

tweakPublicKey()

Signature

static tweakPublicKey(pub: Uint8Array | string): Uint8Array

Description

Applies BIP340 Taproot tweaking to a public key. This performs the standard TapTweak hash-based tweak: the public key is first normalized to even Y, then a tweak scalar is derived from SHA256(SHA256("TapTweak") || SHA256("TapTweak") || x) and applied to the point.

Parameters

Name	Type	Required	Description
pub	Uint8Array \| string	Yes	The public key to tweak. Accepts 33-byte compressed, or a hex string (with optional 0x prefix).

Returns

Type	Description
Uint8Array	The 33-byte compressed tweaked public key.

typescript

const tweaked = EcKeyPair.tweakPublicKey(signer.publicKey);
// tweaked is 33 bytes: [prefix, x0, x1, ..., x31]

tweakBatchSharedT()

Signature

static tweakBatchSharedT(pubkeys: readonly Uint8Array[], tweakScalar: bigint): Uint8Array[]

Description

Tweaks multiple public keys with the same scalar. More efficient than tweaking individually when the same tweak scalar is shared across keys.

Parameters

Name	Type	Required	Description
pubkeys	readonly Uint8Array[]	Yes	Array of public keys to tweak.
tweakScalar	bigint	Yes	The scalar value for tweaking.

Returns

Type	Description
Uint8Array[]	Array of 33-byte compressed tweaked public keys.

tweakedPubKeyToAddress()

Signature

static tweakedPubKeyToAddress(tweakedPubKeyHex: string, network: Network): string

Description

Converts a tweaked public key hex string to a Taproot address. Handles both 32-byte x-only and 33-byte compressed inputs.

Parameters

Name	Type	Required	Description
tweakedPubKeyHex	string	Yes	The tweaked public key in hex (with optional 0x prefix).
network	Network	Yes	The Bitcoin network.

Returns

Type	Description
string	A Taproot address.

tweakedPubKeyBufferToAddress()

Signature

static tweakedPubKeyBufferToAddress(tweakedPubKeyBuffer: XOnlyPublicKey, network: Network): string

Description

Converts a 32-byte x-only tweaked public key buffer to a Taproot address.

Parameters

Name	Type	Required	Description
tweakedPubKeyBuffer	XOnlyPublicKey	Yes	The 32-byte x-only tweaked public key.
network	Network	Yes	The Bitcoin network.

Returns

Type	Description
string	A Taproot address.

xOnlyTweakedPubKeyToAddress()

Signature

static xOnlyTweakedPubKeyToAddress(tweakedPubKeyHex: string, network: Network): string

Description

Converts a strictly 32-byte x-only tweaked public key hex string to a Taproot address. Unlike tweakedPubKeyToAddress(), this throws if the key is not exactly 32 bytes.

Parameters

Name	Type	Required	Description
tweakedPubKeyHex	string	Yes	The 32-byte x-only tweaked public key in hex.
network	Network	Yes	The Bitcoin network.

Returns

Type	Description
string

Throws

Type	Description
Error	Thrown if the key is not exactly 32 bytes.

verifyPubKeys()

Signature

static verifyPubKeys(pubKeys: Uint8Array[], network?: Network): Uint8Array[]

Description

Validates an array of public keys by attempting to create key pairs from each one. Returns the verified public key buffers.

Parameters

Name	Type	Required	Default	Description
pubKeys	Uint8Array[]	Yes	-	Array of public keys to verify.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
Uint8Array[]	Array of verified public key buffers.

Throws

Type	Description
Error	Thrown if any key fails verification.

Address Verification

verifyContractAddress()

Signature

static verifyContractAddress(contractAddress: string, network?: Network): boolean

Description

Verifies that a contract address string can be converted to a valid output script on the given network.

Parameters

Name	Type	Required	Default	Description
contractAddress	string	Yes	-	The address to verify.
network	Network	No	networks.bitcoin	The Bitcoin network.

Returns

Type	Description
boolean	true if the address produces a valid output script.

typescript

const isValid = EcKeyPair.verifyContractAddress('bc1p...', networks.bitcoin);
console.log(isValid); // true

Properties

BIP32

Signature

static BIP32: BIP32API

Description

Get the BIP32 factory instance, initialized with the secp256k1 backend.

Returns

Type	Description
BIP32API	The BIP32 factory instance.

ECPairSigner

Signature

static ECPairSigner: ECPairSigner

Description

Get the reference to the ECPairSigner class for direct access.

Returns

Type	Description
ECPairSigner	The reference to the ECPairSigner.