AddressVerificator

Overview

Provides static utility methods for validating and detecting Bitcoin address types. AddressVerificator can identify P2PKH, P2WPKH, P2TR, P2MR, P2WSH, P2SH, P2OP, and P2WDA addresses, validate public keys (both classical and ML-DSA), and determine whether a P2WSH address is actually a P2WDA address by inspecting its witness script.

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

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

Import

import { AddressVerificator, AddressTypes } from '@btc-vision/transaction';
import { networks } from '@btc-vision/bitcoin';

Enums and Interfaces

AddressTypes

Signature

enum AddressTypes {
    P2PKH                = 'P2PKH',
    P2OP                 = 'P2OP',
    P2SH_OR_P2SH_P2WPKH  = 'P2SH_OR_P2SH-P2WPKH',
    P2PK                 = 'P2PK',
    P2TR                 = 'P2TR',
    P2MR                 = 'P2MR',
    P2WPKH               = 'P2WPKH',
    P2WSH                = 'P2WSH',
    P2WDA                = 'P2WDA',
}

Description

An enum representing all recognized Bitcoin address types.

Enumeration Values

Value	Description
P2PKH	Legacy Pay-to-Public-Key-Hash (starts with 1).
P2OP	Pay-to-OPNet (witness version 16, bech32m).
P2SH_OR_P2SH_P2WPKH	Pay-to-Script-Hash or nested SegWit (starts with 3). Cannot distinguish without the redeem script.
P2PK	Pay-to-Public-Key (detected when input is a valid public key hex).
P2TR	Pay-to-Taproot (witness version 1, 32-byte program, starts with bc1p).
P2MR	Pay-to-Merkle-Root / BIP 360 (witness version 2, 32-byte program, starts with bc1z). Quantum-safe, no key-path spend.
P2WPKH	Pay-to-Witness-Public-Key-Hash (witness version 0, 20-byte program, starts with bc1q).
P2WSH	Pay-to-Witness-Script-Hash (witness version 0, 32-byte program, starts with bc1q).
P2WDA	Pay-to-Witness-Data-Authentication (a P2WSH variant with a specific witness script pattern).

ValidatedP2WDAAddress

Signature

interface ValidatedP2WDAAddress {
    readonly isValid: boolean;
    readonly isPotentiallyP2WDA: boolean;
    readonly isDefinitelyP2WDA: boolean;
    readonly publicKey?: Uint8Array;
    readonly error?: string;
}

Description

The result of a detailed P2WDA address validation.

Parameters

Name	Type	Required	Description
isValid	boolean	-	Whether the base address structure is valid.
isPotentiallyP2WDA	boolean	-	Whether the address could be a P2WDA (is a valid P2WSH).
isDefinitelyP2WDA	boolean	-	Whether the witness script confirms a P2WDA pattern.
publicKey	Uint8Array \| undefined	-	The public key extracted from the P2WDA witness script, if confirmed.
error	string \| undefined	-	Error message if validation failed.

Static Methods

isValidP2TRAddress()

Signature

static isValidP2TRAddress(inAddress: string, network: Network): boolean

Description

Validates whether a string is a valid Taproot (P2TR) address on the given network. Checks bech32m encoding, witness version 1, and the ability to produce a valid output script.

Parameters

Name	Type	Required	Description
inAddress	string	Yes	The address string to validate.
network	Network	Yes	The Bitcoin network.

Returns

Type	Description
boolean	true if valid valid Taproot (P2TR) address, false otherwise.

typescript

const isP2TR = AddressVerificator.isValidP2TRAddress('bc1p...', networks.bitcoin);
console.log(isP2TR); // true

isP2WPKHAddress()

Signature

static isP2WPKHAddress(inAddress: string, network: Network): boolean

Description

Validates whether a string is a valid native SegWit (P2WPKH) address. Checks bech32 encoding, witness version 0, and 20-byte program length.

Parameters

Name	Type	Required	Description
inAddress	string	Yes	The address string to validate.
network	Network	Yes	The Bitcoin network.

Returns

Type	Description
boolean	true if valid native SegWit (P2WPKH) address, false otherwise.

typescript

const isSegWit = AddressVerificator.isP2WPKHAddress('bc1q...', networks.bitcoin);
console.log(isSegWit); // true

isP2PKHOrP2SH()

Signature

static isP2PKHOrP2SH(addy: string, network: Network): boolean

Description

Validates whether a string is a valid P2PKH or P2SH address (base58check encoded).

Parameters

Name	Type	Required	Description
addy	string	Yes	The address string to validate.
network	Network	Yes	The Bitcoin network.

Returns

Type	Description
boolean	true if the address decodes as either P2PKH or P2SH on the given network.

typescript

const isLegacy = AddressVerificator.isP2PKHOrP2SH('1A1zP1...', networks.bitcoin);
console.log(isLegacy); // true

requireRedeemScript()

Signature

static requireRedeemScript(addy: string, network: Network): boolean

Description

Determines whether the address is a P2SH address that requires a redeem script for spending. Returns false for P2PKH addresses.

Parameters

Name	Type	Required	Description
addy	string	Yes	The address string to check.
network	Network	Yes	The Bitcoin network.

Returns

Type	Description
boolean	true if the address is P2SH (requires a redeem script), false otherwise.

isValidP2OPAddress()

Signature

static isValidP2OPAddress(inAddress: string, network: Network): boolean

Description

Validates whether a string is a valid P2OP (Pay-to-OPNet) address. Checks for witness version 16 and a 21-byte witness program.

Parameters

Name	Type	Required	Description
inAddress	string	Yes	The address string to validate.
network	Network	Yes	The Bitcoin network.

Returns

Type	Description
boolean	true if valid P2OP, false otherwise.

typescript

const isP2OP = AddressVerificator.isValidP2OPAddress('bc1s...', networks.bitcoin);
console.log(isP2OP); // true or false

isValidPublicKey()

Signature

static isValidPublicKey(input: string, network: Network): boolean

Description

Validates whether a hex string represents a valid classical Bitcoin public key. Supports compressed (33-byte), uncompressed (65-byte), x-only (32-byte), and hybrid (65-byte with prefix 0x06 or 0x07) formats.

Parameters

Name	Type	Required	Description
input	string	Yes	The hex-encoded public key (with optional 0x prefix).
network	Network	Yes	The Bitcoin network.

Returns

Type	Description
boolean	true if valid classical Bitcoin public key, false otherwise.

typescript

const isValid = AddressVerificator.isValidPublicKey(
    '0x020373626d317ae8788ce3280b491068610d840c23ecb64c14075bbb9f670af52c',
    networks.bitcoin,
);

console.log(isValid); // true

isValidMLDSAPublicKey()

Signature

static isValidMLDSAPublicKey(input: string | Uint8Array): MLDSASecurityLevel | null

Description

Validates whether the input is a valid ML-DSA public key based on its byte length. Returns the corresponding security level if valid, or null if the key length does not match any ML-DSA variant.

Parameters

Name	Type	Required	Description
input	string \| Uint8Array	Yes	The public key as hex string (with optional 0x prefix) or raw bytes.

Returns

Name	Type	Description
-	MLDSASecurityLevel	The corresponding security level if valid.
-	null	If the key length does not match any ML-DSA variant.

typescript

const level = AddressVerificator.isValidMLDSAPublicKey('0xaabb...');
if (level !== null) {
    console.log('Valid ML-DSA key at security level:', level);
} else {
    console.log('Not a valid ML-DSA public key');
}

isP2WDAWitnessScript()

Signature

static isP2WDAWitnessScript(witnessScript: Uint8Array): boolean

Description

Checks whether a witness script matches the P2WDA pattern: (OP_2DROP * 5) <pubkey> OP_CHECKSIG.

Parameters

Name	Type	Required	Description
witnessScript	Uint8Array	Yes	The raw witness script bytes.

Returns

Type	Description
boolean	true if witness script matches the P2WDA, false otherwise.

typescript

const isP2WDA = AddressVerificator.isP2WDAWitnessScript(witnessScript);
console.log(isP2WDA); // true if witness script matches P2WDA pattern

validateP2WDAAddress()

Signature

static validateP2WDAAddress(address: string, network: Network, witnessScript?: Uint8Array): ValidatedP2WDAAddress

Description

Performs a comprehensive P2WDA address validation with three levels of certainty:

isValid: The base address is structurally valid;
isPotentiallyP2WDA: The address is a P2WSH (could be P2WDA);
isDefinitelyP2WDA: The witness script matches the P2WDA pattern AND produces the given address.

Parameters

Name	Type	Required	Description
address	string	Yes	The address to validate.
network	Network	Yes	The Bitcoin network.
witnessScript	Uint8Array	No	Optional witness script for definitive validation.

Returns

Type	Description
ValidatedP2WDAAddress	An object containing validation results.

typescript

// Without witness script - can only determine if it's potentially P2WDA
const result1 = AddressVerificator.validateP2WDAAddress('bc1q...', networks.bitcoin);
console.log(result1.isPotentiallyP2WDA); // true if P2WSH

// With witness script - can definitively confirm P2WDA
const result2 = AddressVerificator.validateP2WDAAddress('bc1q...', networks.bitcoin, witnessScript);
console.log(result2.isDefinitelyP2WDA); // true if confirmed P2WDA
console.log(result2.publicKey);         // Uint8Array if public key extracted

detectAddressType()

Signature

static detectAddressType(addy: string, network: Network): AddressTypes | null

Description

Detects the type of a Bitcoin address string. Returns null if the address type cannot be determined. Detection order: checks if input is a valid public key (P2PK), attempts base58 decode for P2PKH or P2SH_OR_P2SH_P2WPKH, then attempts bech32 decode for P2OP, P2WPKH, P2WSH, P2TR, or P2MR.

Parameters

Name	Type	Required	Description
addy	string	Yes	The address or public key string.
network	Network	Yes	The Bitcoin network.

Returns

Name	Type	Description
-	AddressTypes	The address type.
-	null	If the address type cannot be determined.

typescript

const type = AddressVerificator.detectAddressType('bc1p...', networks.bitcoin);
console.log(type); // AddressTypes.P2TR

const type2 = AddressVerificator.detectAddressType('1A1zP1...', networks.bitcoin);
console.log(type2); // AddressTypes.P2PKH

const type3 = AddressVerificator.detectAddressType('bc1q...short', networks.bitcoin);
console.log(type3); // AddressTypes.P2WPKH (if 20-byte program) or P2WSH (if 32-byte)

detectAddressTypeWithWitnessScript()

Signature

static detectAddressTypeWithWitnessScript(addy: string, network: Network, witnessScript?: Uint8Array): AddressTypes | null

Description

Enhanced address type detection that can distinguish P2WDA from regular P2WSH when a witness script is provided. If the base type is P2WSH and a witness script is provided that matches the P2WDA pattern, returns AddressTypes.P2WDA instead of AddressTypes.P2WSH.

Parameters

Name	Type	Required	Description
addy	string	Yes	The address string.
network	Network	Yes	The Bitcoin network.
witnessScript	Uint8Array	No	Optional witness script for P2WDA detection.

Returns

Name	Type	Description
-	AddressTypes	The address type.
-	null	If the address type cannot be determined.

typescript

// Without witness script, P2WDA addresses show as P2WSH
const type1 = AddressVerificator.detectAddressTypeWithWitnessScript(
    'bc1q...',
    networks.bitcoin,
);
console.log(type1); // AddressTypes.P2WSH

// With witness script, P2WDA is correctly identified
const type2 = AddressVerificator.detectAddressTypeWithWitnessScript(
    'bc1q...',
    networks.bitcoin,
    p2wdaWitnessScript,
);
console.log(type2); // AddressTypes.P2WDA