Documentation
Creates a new Address instance.
If mldsaPublicKey is omitted, a zeroed 32-byte address is created. If the raw ML-DSA public key is provided (not the hash), the class stores the original and computes the SHA256 hash internally.
Address
Overview
Represents a quantum-resistant address in OP_NET's hybrid cryptographic architecture. An Address internally stores the SHA256 hash of an ML-DSA (quantum) public key as its primary 32-byte content and maintains a classical Bitcoin tweaked public key separately. This dual-key design enables quantum-resistant addressing while preserving full compatibility with traditional Bitcoin address formats (P2TR, P2WPKH, P2PKH, P2SH-P2WPKH, P2WDA, and P2OP).
The Address class extends Uint8Array (always 32 bytes) and implements Disposable for secure memory cleanup.
The full source code is available on GitHub at Address.ts.
Critical Warning
Address.fromString() does NOT accept bech32 addresses. You cannot pass bc1q... or bc1p... strings to this method. It requires two hexadecimal public key parameters: the first is the 32-byte SHA256 hash of the ML-DSA public key, and the second is the 33-byte (or 65-byte) Bitcoin compressed (or uncompressed) public key. Both must be 0x-prefixed hex strings.
If you have a bech32 address and need to create an Address object, you must first resolve it to its public keys using a provider (e.g., await provider.getPublicKeyInfo("bc1q...")).
Lazy Loading Architecture
The Address class uses lazy evaluation for expensive EC operations. When a classical public key is provided, it is stored but not processed until a method that requires it is called (e.g., p2tr(), p2wpkh(), tweakedPublicKeyToBuffer()). This means:
- Creating an Address with both keys is cheap (no EC math at construction time).
- Methods that only use the ML-DSA hash (e.g., toHex(), p2op(), toBigInt()) never trigger legacy key processing.
- The first call to a method requiring the classical key triggers the deferred processing. Subsequent calls use cached results.
This design is critical for performance in hot paths like block parsing, where thousands of addresses may be created but only a fraction require classical key operations.
Import
import { Address } from '@btc-vision/transaction';Constructor
Signature
new Address(mldsaPublicKey?: ArrayLike<number>, publicKeyOrTweak?: ArrayLike<number>)Description
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| mldsaPublicKey | ArrayLike<number> | No | Either a 32-byte SHA256 hash of the ML-DSA public key, or the raw ML-DSA public key (1312, 1952, or 2592 bytes). If raw, it will be hashed with SHA256 automatically. |
| publicKeyOrTweak | ArrayLike<number> | No | The classical Bitcoin public key. Accepts 32-byte x-only, 33-byte compressed, or 65-byte uncompressed formats. Expensive EC operations are deferred until needed. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if publicKeyOrTweak has an invalid length (not 32, 33, or 65 bytes). |
| Error | Thrown if mldsaPublicKey is not 32 bytes and not a valid ML-DSA public key length (1312, 1952, or 2592 bytes). |
Static Methods
Signature
static fromString(mldsaPublicKey: string, legacyPublicKey?: string): AddressDescription
Creates an Address from hex-encoded public key strings. This is the primary factory method for constructing addresses from string representations.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| mldsaPublicKey | string | Yes | The 32-byte SHA256 hash of the ML-DSA public key in hex format. 0x prefix is optional. |
| legacyPublicKey | string | No | The classical Bitcoin public key in hex format (33 bytes compressed or 65 bytes uncompressed). 0x prefix is optional. |
Returns
| Type | Description |
|---|---|
| Address | The new Address object. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if either parameter is not valid hexadecimal. The error message explicitly states that bech32 addresses are not accepted. |
Warning
This method takes hex-encoded public keys, NOT bech32 addresses. Passing bc1q... or bc1p... will throw an error. If you only have an address string, resolve it to a public key first via provider.getPublicKeyInfo().
typescript
// Correct usage with two hex public keys
const address = Address.fromString(
'0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
'0x020373626d317ae8788ce3280b491068610d840c23ecb64c14075bbb9f670af52c',
);
// WRONG - this will throw an error
const bad = Address.fromString('bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh');Signature
static dead(): AddressDescription
Returns a dead/burn address. The ML-DSA hash is all zeros and the classical key is the Bitcoin genesis block coinbase public key. Useful as a placeholder or for burning tokens.
Returns
| Type | Description |
|---|---|
| Address | A dead address with a zeroed ML-DSA hash. |
typescript
const burnAddress = Address.dead();
console.log(burnAddress.isDead()); // trueSignature
static wrap(bytes: ArrayLike<number>): AddressDescription
Creates an Address from raw bytes, treating them as the ML-DSA public key (or its hash). No classical public key is set.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| bytes | ArrayLike<number> | Yes | The raw bytes to use as the ML-DSA key portion. |
Returns
| Type | Description |
|---|---|
| Address | The new Address object. |
Signature
static fromBigInt(value: bigint, tweakedValue?: bigint): AddressDescription
Creates an Address from a 256-bit unsigned integer. The inverse of toBigInt().
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| value | bigint | Yes | The 256-bit unsigned integer representing the ML-DSA hash (0 to 2^256-1). |
| tweakedValue | bigint | No | Optional tweaked public key as a 256-bit unsigned integer. |
Returns
| Type | Description |
|---|---|
| Address | The new Address object. |
typescript
const addr = Address.fromBigInt(12345678901234567890n);
console.log(addr.toBigInt()); // 12345678901234567890nSignature
static fromUint64Array(w0: bigint, w1: bigint, w2: bigint, w3: bigint): AddressDescription
Creates an Address from four 64-bit big-endian unsigned integers. The inverse of toUint64Array(). Useful for efficient serialization or interfacing with word-aligned storage.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| w0 | bigint | Yes | Most significant 64 bits (bytes 0-7). |
| w1 | bigint | Yes | Second 64 bits (bytes 8-15). |
| w2 | bigint | Yes | Third 64 bits (bytes 16-23). |
| w3 | bigint | Yes | Least significant 64 bits (bytes 24-31). |
Returns
| Type | Description |
|---|---|
| Address | The new Address object. |
Signature
static uncompressedToCompressed(publicKey: ArrayLike<number>): Uint8ArrayDescription
Converts a 65-byte uncompressed public key to a 33-byte compressed public key.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| publicKey | ArrayLike<number> | Yes | The 65-byte uncompressed public key (starting with 0x04). |
Returns
| Type | Description |
|---|---|
| Uint8Array | The 33-byte compressed public key. |
Instance Methods
Signature
toHex(): stringDescription
Returns the SHA256 hash of the ML-DSA public key as a 0x-prefixed hex string. This 32-byte value is the universal OP_NET identifier for the address.
Returns
| Type | Description |
|---|---|
| string | 0x-prefixed 64-character hex string. |
typescript
const address = Address.fromString('0xabcd...', '0x02...');
console.log(address.toHex()); // '0xabcd...'Signature
tweakedToHex(): stringDescription
Returns the classical tweaked x-only public key as a 0x-prefixed hex string.
Returns
| Type | Description |
|---|---|
| string | 0x-prefixed hex classical tweaked x-only public key. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
toBuffer(): MLDSAHashedPublicKeyDescription
Returns the address content (SHA256 hash of the ML-DSA public key) as a new Uint8Array.
Returns
| Type | Description |
|---|---|
| Uint8Array | Branded as MLDSAHashedPublicKey. |
Signature
originalPublicKeyBuffer(): PublicKeyDescription
Returns the original compressed classical public key (33 bytes) as a new Uint8Array. This is a copy of the key that was provided to the constructor.
Returns
| Type | Description |
|---|---|
| Uint8Array | The 33-byte compressed public key, branded as PublicKey. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
tweakedPublicKeyToBuffer(): XOnlyPublicKeyDescription
Returns the classical tweaked x-only public key (32 bytes) as a new Uint8Array.
Returns
| Type | Description |
|---|---|
| Uint8Array | Branded as XOnlyPublicKey. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
toUncompressedHex(): stringDescription
Returns the uncompressed classical public key (65 bytes, starting with 0x04) as a 0x-prefixed hex string.
Returns
| Type | Description |
|---|---|
| string | The uncompressed hex classical public key. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
toUncompressedBuffer(): PublicKeyDescription
Returns the uncompressed classical public key (65 bytes) as a Uint8Array.
Returns
| Type | Description |
|---|---|
| Uint8Array | Branded as PublicKey. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
toHybridPublicKeyHex(): stringDescription
Returns the hybrid public key (derived from decompressing the classical public key) as a 0x-prefixed hex string.
Returns
| Type | Description |
|---|---|
| string | 0x-prefixed hex hybrid public key. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
toHybridPublicKeyBuffer(): HybridPublicKeyDescription
Returns the hybrid public key as a Uint8Array.
Returns
| Type | Description |
|---|---|
| Uint8Array | Branded as HybridPublicKey. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
toTweakedHybridPublicKeyHex(): stringDescription
Returns the tweaked hybrid public key (derived from the Taproot-tweaked classical public key) as a 0x-prefixed hex string.
Returns
| Type | Description |
|---|---|
| string | 0x-prefixed hex tweaked hybrid public key. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
toTweakedHybridPublicKeyBuffer(): Uint8ArrayDescription
Returns the tweaked hybrid public key as a Uint8Array.
Returns
| Type | Description |
|---|---|
| Uint8Array | The tweaked hybrid public key as a Uint8Array. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
p2tr(network: Network): stringDescription
Returns the Taproot (P2TR) address derived from the classical tweaked public key.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| string | A bech32m Taproot address (e.g., bc1p...). |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
typescript
import { networks } from '@btc-vision/bitcoin';
const taprootAddr = address.p2tr(networks.bitcoin);
console.log(taprootAddr); // 'bc1p...'Signature
p2wpkh(network: Network): stringDescription
Returns the native SegWit (P2WPKH) address derived from the classical public key.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| string | A bech32 SegWit address (e.g., bc1q...). |
Signature
p2pkh(network: Network): stringDescription
Returns the legacy (P2PKH) address derived from the classical public key.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| string | A legacy address (e.g., 1...). |
Signature
p2shp2wpkh(network: Network): stringDescription
Returns the nested SegWit (P2SH-P2WPKH) address derived from the classical public key.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| string | A nested SegWit address (e.g., 3...). |
Signature
p2wda(network: Network): IP2WSHAddressDescription
Generates a Pay-to-Witness-Data-Authentication (P2WDA) address. P2WDA addresses are special P2WSH addresses that embed authenticated data in the witness field, achieving 75% cost reduction through the SegWit witness discount.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| IP2WSHAddress | An object containing address (the P2WSH address string) and witnessScript (the serialized witness script). |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the public key is not set or if generation fails. |
typescript
const p2wdaInfo = address.p2wda(networks.bitcoin);
console.log(p2wdaInfo.address); // 'bc1q...' (P2WSH format)
console.log(p2wdaInfo.witnessScript); // Uint8Array of witness scriptSignature
p2op(network: Network): stringDescription
Returns the P2OP (Pay-to-OPNet) address encoded in bech32m format with witness version 16. This address is derived from the ML-DSA hash only and does not require the classical public key.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| string | A bech32m P2OP address. |
Signature
p2pk(): stringDescription
Returns the hex-encoded ML-DSA hash (equivalent to toHex()). This is the public-key representation used for Pay-to-Public-Key style outputs.
Returns
| Type | Description |
|---|---|
| string | The hex-encoded ML-DSA hash. |
Signature
override set(mldsaPublicKey: ArrayLike<number>): voidDescription
Overrides Uint8Array.set() to set the ML-DSA public key content. If the provided bytes are a raw ML-DSA public key (1312, 1952, or 2592 bytes), it will be hashed with SHA256 and the hash stored. If it is already 32 bytes, it is stored directly.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| mldsaPublicKey | ArrayLike<number> | Yes | The ML-DSA public key (raw or hashed). |
Signature
equals(other: Address): booleanDescription
Compares two addresses byte-by-byte for equality. Comparison is based on the ML-DSA hash content only (the 32-byte Uint8Array content).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| other | Address | Yes | The address to compare against. |
Returns
| Type | Description |
|---|---|
| boolean | true if the two addresses are equal, false otherwise. |
typescript
const a = Address.fromString('0xabcd...', '0x02...');
const b = Address.fromString('0xabcd...', '0x03...');
console.log(a.equals(b)); // true (same ML-DSA hash)Signature
lessThan(other: Address): booleanDescription
Byte-by-byte comparison of two addresses, treating them as big-endian 256-bit unsigned integers. Useful for sorting or ordering addresses.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| other | Address | Yes | The address to compare against. |
Returns
| Type | Description |
|---|---|
| boolean | true if this address is less than the other address, false otherwise. |
Signature
greaterThan(other: Address): booleanDescription
Byte-by-byte comparison of two addresses, treating them as big-endian 256-bit unsigned integers. Useful for sorting or ordering addresses.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| other | Address | Yes | The address to compare against. |
Returns
| Type | Description |
|---|---|
| boolean | true if this address is greater than the other address, false otherwise. |
Signature
toBigInt(): bigintDescription
Converts the 32-byte ML-DSA hash to a single bigint value. Uses an optimized DataView approach (10-20x faster than string conversion). The result is cached after the first call.
Returns
| Type | Description |
|---|---|
| bigint | ML-DSA hash as a 256-bit unsigned integer. |
Signature
tweakedToBigInt(): bigintDescription
Converts the 32-byte tweaked classical public key to a single bigint value. Cached after the first call.
Returns
| Type | Description |
|---|---|
| bigint | Tweaked classical public key as a 256-bit unsigned integer. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy public key was not set. |
Signature
toUint64Array(): [bigint, bigint, bigint, bigint]Description
Splits the 32-byte address into four 64-bit big-endian unsigned integers. The result is cached.
Returns
| Type | Description |
|---|---|
| [bigint, bigint, bigint, bigint] | [w0, w1, w2, w3] from most significant to least significant. |
Signature
isDead(): booleanDescription
Checks if every byte of the ML-DSA hash is zero (i.e., the dead/burn address).
Returns
| Type | Description |
|---|---|
| boolean | true if the address is the dead address, false otherwise. |
Signature
isValidLegacyPublicKey(network: Network): booleanDescription
Validates the classical public key against the given network.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| boolean | true if valid, false otherwise. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the legacy key was not set. |
Signature
toString(): stringDescription
Returns the 0x-prefixed hex string of the ML-DSA hash. Equivalent to toHex().
Returns
| Type | Description |
|---|---|
| string | The 0x-prefixed hex string of the ML-DSA hash. |
Signature
toJSON(): stringDescription
Returns the 0x-prefixed hex string of the ML-DSA hash. Used for JSON serialization.
Returns
| Type | Description |
|---|---|
| string | The 0x-prefixed hex string of the ML-DSA hash. |
Signature
toCSV(duration: bigint | number | string, network: Network): IP2WSHAddressDescription
Generates a P2WSH address with a CheckSequenceVerify (CSV) time lock. The resulting address can only be spent after the specified number of blocks.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| duration | bigint | number | string | Yes | Number of blocks before spending is allowed (1-65535). |
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| IP2WSHAddress | The time-locked address and its witness script. |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the duration is out of range or the public key is not set. |
Signature
toCSVTweaked(duration: bigint | number | string, network: Network): stringDescription
Generates a P2TR address with a CSV time lock using the tweaked public key.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| duration | bigint | number | string | Yes | Number of blocks before spending is allowed (1-65535). |
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| string | The time-locked Taproot address. |
Signature
toCSVP2MR(duration: bigint | number | string, network: Network): stringDescription
Generates a P2MR address with a CSV time lock. The CSV script uses the tweaked public key for OP_CHECKSIG, but the P2MR output itself commits directly to the Merkle root without exposing an internal public key, providing quantum resistance.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| duration | bigint | number | string | Yes | Number of blocks before spending is allowed (1-65535). |
| network | Network | Yes | The Bitcoin network. |
Returns
| Type | Description |
|---|---|
| string | The time-locked P2MR address (e.g., bc1z...). |
Throws
| Type | Description |
|---|---|
| Error | Thrown if the duration is out of range or the public key is not set. |
typescript
const csvP2MR = address.toCSVP2MR(144, networks.bitcoin);
// Returns a bc1z... address with a 144-block CSV timelockSignature
[Symbol.dispose](): voidDescription
Securely disposes the address by zeroing all internal buffers and clearing cached state. Use this when you are done with the address to minimize secret material exposure.
typescript
Automatically dispose with using keyword
{
using address = new Address(mldsaKey, classicalKey);
// ... use address
} // automatically disposed hereProperties
Signature
get originalPublicKey(): PublicKey | undefinedDescription
Return the original compressed classical public key (33 bytes), if set. Triggers lazy legacy processing.
Returns
| Name | Type | Description |
|---|---|---|
| - | PublicKey | Original compressed classical public key. |
| - | undefined | When not defined. |
Signature
get mldsaPublicKey(): MLDSAHashedPublicKey | undefinedDescription
Return the original (unhashed) ML-DSA public key, if the raw key was provided to the constructor.
Returns
| Name | Type | Description |
|---|---|---|
| - | MLDSAHashedPublicKey | Original (unhashed) ML-DSA public key. |
| - | undefined | When not defined. |
Signature
get originalMDLSAPublicKey(): Uint8Array | undefined
set originalMDLSAPublicKey(key: Uint8Array | undefined)Description
Get/set the original ML-DSA public key bytes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| key | Uint8Array | undefined | - | The original ML-DSA public key bytes or undefined. |
Returns
| Name | Type | Description |
|---|---|---|
| - | Uint8Array | Original ML-DSA public key bytes. |
| - | undefined | When not defined. |
Signature
get mldsaLevel(): MLDSASecurityLevel | undefined
set mldsaLevel(level: MLDSASecurityLevel | undefined)Description
Get/set the ML-DSA security level associated with this address.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| level | MLDSASecurityLevel | undefined | - | The ML-DSA security level or undefined. |
Returns
| Name | Type | Description |
|---|---|---|
| - | MLDSASecurityLevel | The ML-DSA security level. |
| - | undefined | When not defined. |