@btc-vision/transaction
Version:
OPNet transaction library allows you to create and sign transactions for the OPNet network.
338 lines • 14.2 kB
TypeScript
import { Network, PublicKey, XOnlyPublicKey } from '../../node_modules/@btc-vision/bitcoin/browser/index.js';
import { IP2WSHAddress } from '../transaction/mineable/IP2WSHAddress.js';
import { MLDSASecurityLevel } from '../../node_modules/@btc-vision/bip32/src/cjs/index.cjs';
import { HybridPublicKey, MLDSAHashedPublicKey } from '../branded/Branded.js';
/**
* Objects of type "Address" represent hashed ML-DSA (quantum) public keys (using SHA256 of quantum keys) and maintain classical public keys separately.
* This class supports a hybrid quantum-classical architecture, allowing conversion to different address formats and management of both key types.
*
* The Address internally stores the SHA256 hash of the ML-DSA public key as its primary content, while maintaining
* the classical public key in a separate field. This enables quantum-resistant addressing while preserving
* compatibility with traditional Bitcoin cryptography.
*
* @category KeyPair
*/
export declare class Address extends Uint8Array implements Disposable {
#private;
constructor(mldsaPublicKey?: ArrayLike<number>, publicKeyOrTweak?: ArrayLike<number>);
/**
* Prevent TypedArray methods (subarray, slice, etc.) from creating Address
* instances. Without this, @noble/hashes and other libraries that call
* subarray() on an Address would invoke the Address constructor that recomputes
* everything leading to bad performance.
*/
static get [Symbol.species](): Uint8ArrayConstructor;
get mldsaLevel(): MLDSASecurityLevel | undefined;
set mldsaLevel(level: MLDSASecurityLevel | undefined);
get originalMDLSAPublicKey(): Uint8Array | undefined;
set originalMDLSAPublicKey(key: Uint8Array | undefined);
/**
* If available, this will return the original public key associated with the address.
* @returns {Uint8Array} The original public key used to create the address.
*/
get originalPublicKey(): PublicKey | undefined;
get mldsaPublicKey(): MLDSAHashedPublicKey | undefined;
/**
* Get the legacy public key (32-byte tweaked x-only after processing).
* Triggers lazy processing if not yet done.
*/
private get legacyPublicKey();
/**
* Get the key pair for the address
* @description This is only for internal use. Please use address.tweakedBytes instead.
*/
private get keyPair();
static dead(): Address;
/**
* Create an address from a hex string
* @param {string} mldsaPublicKey The ml-dsa public key in hex format
* @param {string} legacyPublicKey The classical public key in hex format
* @returns {Address} The address
*/
static fromString(mldsaPublicKey: string, legacyPublicKey?: string): Address;
/**
* Create an address from a public key
* @returns {Address} The address
* @param {ArrayLike<number>} bytes The public key
*/
static wrap(bytes: ArrayLike<number>): Address;
static uncompressedToCompressed(publicKey: ArrayLike<number>): Uint8Array;
/**
* Creates an Address instance from a BigInt value.
*
* Converts a 256-bit unsigned integer into a 32-byte address by splitting it
* into four 64-bit chunks and writing them in big-endian format using DataView.
* This is the inverse operation of toBigInt().
*
* @param {bigint} value - The 256-bit unsigned integer to convert (0 to 2^256-1)
* @param {bigint} [tweakedValue] - Optional tweaked public key as a 256-bit unsigned integer
* @returns {Address} A new Address instance containing the converted value
*
* @throws {RangeError} If the value is negative or exceeds 2^256-1
*
* @example
* ```typescript
* const bigIntValue = 12345678901234567890n;
* const address = Address.fromBigInt(bigIntValue);
* console.log(address.toHex()); // 0x0000000000000000000000000000000000000000000000000000abc123...
* ```
*/
static fromBigInt(value: bigint, tweakedValue?: bigint): Address;
/**
* Creates an Address instance from four 64-bit unsigned integers.
*
* Constructs a 32-byte address by combining four 64-bit big-endian unsigned integers.
* This is the inverse operation of toUint64Array() and provides an efficient way
* to create addresses from word-aligned data.
*
* @param {bigint} w0 - Most significant 64 bits (bytes 0-7)
* @param {bigint} w1 - Second 64 bits (bytes 8-15)
* @param {bigint} w2 - Third 64 bits (bytes 16-23)
* @param {bigint} w3 - Least significant 64 bits (bytes 24-31)
* @returns {Address} A new Address instance containing the combined value
*
* @throws {RangeError} If any value exceeds 64 bits (2^64-1)
*
* @example
* ```typescript
* const address = Address.fromUint64Array(
* 0x0123456789abcdefn,
* 0xfedcba9876543210n,
* 0x1111222233334444n,
* 0x5555666677778888n
* );
* console.log(address.toHex());
* ```
*/
static fromUint64Array(w0: bigint, w1: bigint, w2: bigint, w3: bigint): Address;
private static bigintToUint8Array;
[Symbol.dispose](): void;
/**
* Converts the address to four 64-bit unsigned integers.
*
* Splits the 32-byte (256-bit) address into four 64-bit big-endian unsigned integers.
* This representation is useful for efficient storage, comparison operations, or
* interfacing with systems that work with 64-bit word sizes.
*
* @returns {[bigint, bigint, bigint, bigint]} An array of four 64-bit unsigned integers
* representing the address from most significant to least significant bits
*
* @example
* ```typescript
* const address = Address.fromString('0x0123456789abcdef...');
* const [w0, w1, w2, w3] = address.toUint64Array();
* console.log(w0); // Most significant 64 bits
* console.log(w3); // Least significant 64 bits
* ```
*/
toUint64Array(): [bigint, bigint, bigint, bigint];
/**
* Check if the address is the dead address
* @returns {boolean}
*/
isDead(): boolean;
/**
* Converts the address to a hex string
* @returns {string} The hex string
*/
toHex(): string;
/**
* Converts the classical public key to a hex string
* @returns {string} The hex string
*/
tweakedToHex(): string;
/**
* Converts the address content (SHA256 hash of ML-DSA public key) to a Uint8Array
* @returns {Uint8Array} The Uint8Array containing the hashed ML-DSA public key
*/
toBuffer(): MLDSAHashedPublicKey;
/**
* Converts the classical public key to a Uint8Array
* @returns {Uint8Array} The Uint8Array
*/
tweakedPublicKeyToBuffer(): XOnlyPublicKey;
toUncompressedHex(): string;
toUncompressedBuffer(): PublicKey;
toHybridPublicKeyHex(): string;
toHybridPublicKeyBuffer(): HybridPublicKey;
originalPublicKeyBuffer(): PublicKey;
/**
* Converts the address to a BigInt representation.
*
* This method uses an optimized DataView approach to read the 32-byte address
* as four 64-bit big-endian unsigned integers, then combines them using bitwise
* operations. This is approximately 10-20x faster than string-based conversion.
*
* @returns {bigint} The address as a 256-bit unsigned integer
*
* @example
* ```typescript
* const address = Address.fromString('0x0123456789abcdef...');
* const bigIntValue = address.toBigInt();
* console.log(bigIntValue); // 123456789...n
* ```
*/
toBigInt(): bigint;
/**
* Converts the tweaked public key to a BigInt representation.
*
* This method uses an optimized DataView approach to read the 32-byte address
* as four 64-bit big-endian unsigned integers, then combines them using bitwise
* operations. This is approximately 10-20x faster than string-based conversion.
*
* @returns {bigint} The address as a 256-bit unsigned integer
*
* @example
* ```typescript
* const address = Address.fromString('0x0123456789abcdef...', '0xtweaked...');
* const bigIntValue = address.tweakedToBigInt();
* console.log(bigIntValue); // 123456789...n
* ```
*/
tweakedToBigInt(): bigint;
equals(a: Address): boolean;
/**
* Check if the address is bigger than another address
* @returns {boolean} If bigger
*/
lessThan(a: Address): boolean;
/**
* Check if the address is smaller than another address
* @returns {boolean} If smaller
*/
greaterThan(a: Address): boolean;
/**
* Set the public key
* @param {ArrayLike<number>} mldsaPublicKey ML-DSA public key
* @returns {void}
*/
set(mldsaPublicKey: ArrayLike<number>): void;
/**
* Check if the public key is valid
* @param {Network} network The network
* @returns {boolean} If the public key is valid
*/
isValidLegacyPublicKey(network: Network): boolean;
/**
* Get the public key as address
*/
p2pk(): string;
/**
* Get the address in p2wpkh format
* @param {Network} network The network
*/
p2wpkh(network: Network): string;
/**
* Get the address in p2pkh format
* @param {Network} network The network
*/
p2pkh(network: Network): string;
/**
* Get the address in p2sh-p2wpkh format
* @param {Network} network The network
*/
p2shp2wpkh(network: Network): string;
/**
* Convert the address to a string
*/
toString(): string;
/**
* Convert the address to a JSON string
*/
toJSON(): string;
/**
* Get the address in p2tr format
* @param {Network} network The network
*/
p2tr(network: Network): string;
/**
* Generate a P2WDA (Pay-to-Witness-Data-Authentication) address
*
* P2WDA addresses are a special type of P2WSH address that allows embedding
* authenticated data directly in the witness field, achieving 75% cost reduction
* through Bitcoin's witness discount.
*
* The witness script pattern is: (OP_2DROP * 5) <pubkey> OP_CHECKSIG
* This allows up to 10 witness data fields (5 * 2 = 10), where each field
* can hold up to 80 bytes of data due to relay rules.
*
* @param {Network} network - The Bitcoin network to use
* @returns {IP2WSHAddress} The P2WDA address
* @throws {Error} If the public key is not set or address generation fails
*
* @example
* ```typescript
* const address = Address.fromString('0x02...');
* const p2wdaAddress = address.p2wda(networks.bitcoin);
* console.log(p2wdaAddress); // bc1q...
* ```
*/
p2wda(network: Network): IP2WSHAddress;
/**
* Generate a P2WSH address with CSV (CheckSequenceVerify) time lock
* The resulting address can only be spent after the specified number of blocks
* have passed since the UTXO was created.
*
* @param {bigint | number | string} duration - The number of blocks that must pass before spending (1-65535)
* @param {Network} network - The Bitcoin network to use
* @returns {IP2WSHAddress} The timelocked address and its witness script
* @throws {Error} If the block number is out of range or public key is not available
*/
toCSV(duration: bigint | number | string, network: Network): IP2WSHAddress;
/**
* Generate a P2TR address with CSV (CheckSequenceVerify) time lock
* The resulting address can only be spent after the specified number of blocks
* have passed since the UTXO was created.
*
* @param {bigint | number | string} duration - The number of blocks that must pass before spending (1-65535)
* @param {Network} network - The Bitcoin network to use
* @returns {IP2WSHAddress} The timelocked address and its witness script
* @throws {Error} If the block number is out of range or public key is not available
*/
toCSVTweaked(duration: bigint | number | string, network: Network): string;
/**
* Generate a P2MR address with CSV (CheckSequenceVerify) time lock
* The resulting address can only be spent after the specified number of blocks
* have passed since the UTXO was created. Uses P2MR (BIP 360) instead of P2TR.
*
* @param {bigint | number | string} duration - The number of blocks that must pass before spending (1-65535)
* @param {Network} network - The Bitcoin network to use
* @returns {string} The timelocked P2MR address
* @throws {Error} If the block number is out of range or public key is not available
*/
toCSVP2MR(duration: bigint | number | string, network: Network): string;
/**
* Returns the OPNet address encoded in bech32m format, derived from the SHA256 hash of the ML-DSA public key
* (which is what the Address internally stores).
*
* This method generates a P2OP (Pay-to-OPNet) address using witness version 16, suitable for
* quantum-resistant transactions on the OPNet protocol.
*
* @param network - The Bitcoin network to use (mainnet, testnet, regtest)
* @returns The P2OP address in bech32m format
*/
p2op(network: Network): string;
toTweakedHybridPublicKeyHex(): string;
toTweakedHybridPublicKeyBuffer(): Uint8Array;
/**
* Lazily generates the tweaked uncompressed/hybrid key from the legacy public key.
* Only called when toTweakedHybridPublicKey* methods are accessed.
*/
private ensureTweakedUncompressed;
/**
* Sets the MLDSA key portion of the address.
* @param {ArrayLike<number>} mldsaPublicKey - The MLDSA public key or its hash
*/
private setMldsaKey;
/**
* Lazy processing of legacy key - defers expensive EC operations until actually needed.
* Does the EXACT same logic as the original set() method did for legacy keys.
*/
private ensureLegacyProcessed;
/**
* Processes a 33 or 65 byte public key, performing EC operations.
* Sets #tweakedPublicKey to 32-byte tweaked x-only (same as original behavior).
*/
private autoFormat;
}
//# sourceMappingURL=Address.d.ts.map