@btc-vision/transaction 1.8.0-beta.3 → 1.8.0-beta.5

package/build/keypair/Address.d.ts

@@ -1,57 +1,327 @@
-import { Network } from '@btc-vision/bitcoin';
-import { IP2WSHAddress } from '../transaction/mineable/IP2WSHAddress.js';
+import { type Network, type PublicKey, type XOnlyPublicKey } from '@btc-vision/bitcoin';
+import type { IP2WSHAddress } from '../transaction/mineable/IP2WSHAddress.js';
 import { MLDSASecurityLevel } from '@btc-vision/bip32';
-export declare class Address extends Uint8Array {
+import type { 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);
+    set mldsaLevel(level: MLDSASecurityLevel | undefined);
     get originalMDLSAPublicKey(): Uint8Array | undefined;
-    set originalMDLSAPublicKey(key: Buffer | Uint8Array);
-    get originalPublicKey(): Uint8Array | undefined;
-    get mldsaPublicKey(): 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>): Buffer;
+    static uncompressedToCompressed(publicKey: ArrayLike<number>): Uint8Array;
+    [Symbol.dispose](): void;
+    /**
+     * 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;
+    /**
+     * 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;
-    toBuffer(): Buffer;
-    tweakedPublicKeyToBuffer(): Buffer;
+    /**
+     * 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(): Buffer;
+    toUncompressedBuffer(): PublicKey;
     toHybridPublicKeyHex(): string;
-    toHybridPublicKeyBuffer(): Buffer;
-    originalPublicKeyBuffer(): Buffer;
+    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;
+    /**
+     * 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(): Buffer;
+    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

package/build/keypair/Address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Address.d.ts","sourceRoot":"","sources":["../../src/keypair/Address.ts"],"names":[],"mappings":"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"}