@btc-vision/bitcoin 6.5.5 → 7.0.0-alpha.0

package/src/ecc/context.ts

@@ -0,0 +1,277 @@
+/**
+ * ECC library context management with dependency injection.
+ * Provides initialization, access, and lifecycle management for the ECC library.
+ *
+ * @packageDocumentation
+ */
+import type { EccLib } from './types.js';
+import { fromHex, equals } from '../io/index.js';
+import type { Bytes32, XOnlyPublicKey } from '../types.js';
+
+/**
+ * Context class for managing the ECC library instance.
+ * Uses dependency injection pattern instead of global singleton.
+ *
+ * @example
+ * ```typescript
+ * import { EccContext } from '@btc-vision/bitcoin';
+ * import * as secp256k1 from 'tiny-secp256k1';
+ *
+ * // Initialize once at app startup
+ * EccContext.init(secp256k1);
+ *
+ * // Get instance anywhere in your code
+ * const ecc = EccContext.get();
+ *
+ * // Clear when done (optional, for testing)
+ * EccContext.clear();
+ * ```
+ */
+export class EccContext {
+    static #instance: EccContext | undefined;
+    readonly #lib: EccLib;
+
+    private constructor(lib: EccLib) {
+        this.#lib = lib;
+    }
+
+    /**
+     * Initializes the ECC context with the provided library.
+     * The library is verified before being set as active.
+     *
+     * @param lib - The ECC library instance to initialize
+     * @returns The initialized EccContext instance
+     * @throws Error if the ECC library fails verification
+     *
+     * @example
+     * ```typescript
+     * import { EccContext } from '@btc-vision/bitcoin';
+     * import * as secp256k1 from 'tiny-secp256k1';
+     *
+     * const context = EccContext.init(secp256k1);
+     * ```
+     */
+    static init(lib: EccLib): EccContext {
+        verifyEcc(lib);
+        EccContext.#instance = new EccContext(lib);
+        return EccContext.#instance;
+    }
+
+    /**
+     * Gets the initialized ECC context.
+     *
+     * @returns The EccContext instance
+     * @throws Error if the context has not been initialized
+     *
+     * @example
+     * ```typescript
+     * import { EccContext } from '@btc-vision/bitcoin';
+     *
+     * const context = EccContext.get();
+     * const isValid = context.lib.isXOnlyPoint(someKey);
+     * ```
+     */
+    static get(): EccContext {
+        if (!EccContext.#instance) {
+            throw new Error(
+                'ECC library not initialized. Call EccContext.init() or initEccLib() first.',
+            );
+        }
+        return EccContext.#instance;
+    }
+
+    /**
+     * Clears the ECC context.
+     * Useful for testing or when reinitializing with a different library.
+     *
+     * @example
+     * ```typescript
+     * import { EccContext } from '@btc-vision/bitcoin';
+     *
+     * EccContext.clear();
+     * // Context is now uninitialized
+     * ```
+     */
+    static clear(): void {
+        EccContext.#instance = undefined;
+    }
+
+    /**
+     * Checks if the ECC context has been initialized.
+     *
+     * @returns True if initialized
+     *
+     * @example
+     * ```typescript
+     * import { EccContext } from '@btc-vision/bitcoin';
+     *
+     * if (!EccContext.isInitialized()) {
+     *     EccContext.init(secp256k1);
+     * }
+     * ```
+     */
+    static isInitialized(): boolean {
+        return EccContext.#instance !== undefined;
+    }
+
+    /**
+     * The underlying ECC library instance.
+     */
+    get lib(): EccLib {
+        return this.#lib;
+    }
+}
+
+/**
+ * Initializes the ECC library with the provided instance.
+ * This is a convenience function that wraps EccContext.init().
+ * Pass `undefined` to clear the library.
+ *
+ * @param eccLib - The ECC library instance to initialize, or undefined to clear
+ * @throws Error if the ECC library fails verification
+ *
+ * @example
+ * ```typescript
+ * import { initEccLib } from '@btc-vision/bitcoin';
+ * import * as secp256k1 from 'tiny-secp256k1';
+ *
+ * // Initialize the ECC library
+ * initEccLib(secp256k1);
+ *
+ * // Clear the library
+ * initEccLib(undefined);
+ * ```
+ */
+export function initEccLib(eccLib: EccLib | undefined): void {
+    if (eccLib === undefined) {
+        EccContext.clear();
+        return;
+    }
+    EccContext.init(eccLib);
+}
+
+/**
+ * Retrieves the initialized ECC library instance.
+ * This is a convenience function that wraps EccContext.get().lib.
+ *
+ * @returns The ECC library instance
+ * @throws Error if the ECC library has not been initialized
+ *
+ * @example
+ * ```typescript
+ * import { getEccLib, initEccLib } from '@btc-vision/bitcoin';
+ * import * as secp256k1 from 'tiny-secp256k1';
+ *
+ * initEccLib(secp256k1);
+ *
+ * const ecc = getEccLib();
+ * const isValid = ecc.isXOnlyPoint(somePublicKey);
+ * ```
+ */
+export function getEccLib(): EccLib {
+    return EccContext.get().lib;
+}
+
+// ============================================================================
+// Verification
+// ============================================================================
+
+interface TweakAddVector {
+    pubkey: string;
+    tweak: string;
+    parity: 0 | 1 | -1;
+    result: string | null;
+}
+
+const TWEAK_ADD_VECTORS: TweakAddVector[] = [
+    {
+        pubkey: '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798',
+        tweak: 'fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364140',
+        parity: -1,
+        result: null,
+    },
+    {
+        pubkey: '1617d38ed8d8657da4d4761e8057bc396ea9e4b9d29776d4be096016dbd2509b',
+        tweak: 'a8397a935f0dfceba6ba9618f6451ef4d80637abf4e6af2669fbc9de6a8fd2ac',
+        parity: 1,
+        result: 'e478f99dab91052ab39a33ea35fd5e6e4933f4d28023cd597c9a1f6760346adf',
+    },
+    {
+        pubkey: '2c0b7cf95324a07d05398b240174dc0c2be444d96b159aa6c7f7b1e668680991',
+        tweak: '823c3cd2142744b075a87eade7e1b8678ba308d566226a0056ca2b7a76f86b47',
+        parity: 0,
+        result: '9534f8dc8c6deda2dc007655981c78b49c5d96c778fbf363462a11ec9dfd948c',
+    },
+];
+
+/**
+ * Verifies that the ECC library implementation is correct.
+ * Tests `isXOnlyPoint` and `xOnlyPointAddTweak` with known test vectors.
+ *
+ * @param ecc - The ECC library to verify
+ * @throws Error if any verification test fails
+ */
+function verifyEcc(ecc: EccLib): void {
+    if (typeof ecc.isXOnlyPoint !== 'function') {
+        throw new Error('ECC library missing isXOnlyPoint function');
+    }
+
+    // Test isXOnlyPoint with valid points
+    const validPoints = [
+        '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798',
+        'fffffffffffffffffffffffffffffffffffffffffffffffffffffffeeffffc2e',
+        'f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9',
+        '0000000000000000000000000000000000000000000000000000000000000001',
+    ];
+
+    for (const hex of validPoints) {
+        if (!ecc.isXOnlyPoint(fromHex(hex))) {
+            throw new Error(`ECC library isXOnlyPoint failed for valid point: ${hex}`);
+        }
+    }
+
+    // Test isXOnlyPoint with invalid points
+    const invalidPoints = [
+        '0000000000000000000000000000000000000000000000000000000000000000',
+        'fffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f',
+    ];
+
+    for (const hex of invalidPoints) {
+        if (ecc.isXOnlyPoint(fromHex(hex))) {
+            throw new Error(`ECC library isXOnlyPoint should reject invalid point: ${hex}`);
+        }
+    }
+
+    // Test xOnlyPointAddTweak
+    if (typeof ecc.xOnlyPointAddTweak !== 'function') {
+        throw new Error('ECC library missing xOnlyPointAddTweak function');
+    }
+
+    for (const vector of TWEAK_ADD_VECTORS) {
+        const result = ecc.xOnlyPointAddTweak(fromHex(vector.pubkey) as XOnlyPublicKey, fromHex(vector.tweak) as Bytes32);
+
+        if (vector.result === null) {
+            if (result !== null) {
+                throw new Error(
+                    `ECC library xOnlyPointAddTweak should return null for: ${vector.pubkey}`,
+                );
+            }
+        } else {
+            if (result === null) {
+                throw new Error(
+                    `ECC library xOnlyPointAddTweak returned null unexpectedly for: ${vector.pubkey}`,
+                );
+            }
+            if (result.parity !== vector.parity) {
+                throw new Error(
+                    `ECC library xOnlyPointAddTweak parity mismatch for: ${vector.pubkey}`,
+                );
+            }
+            if (!equals(result.xOnlyPubkey, fromHex(vector.result))) {
+                throw new Error(
+                    `ECC library xOnlyPointAddTweak result mismatch for: ${vector.pubkey}`,
+                );
+            }
+        }
+    }
+}

package/src/ecc/index.ts

@@ -0,0 +1,14 @@
+/**
+ * ECC (Elliptic Curve Cryptography) module.
+ *
+ * Provides dependency injection for the secp256k1 elliptic curve library
+ * required for Taproot (BIP340/BIP341) operations.
+ *
+ * @packageDocumentation
+ */
+
+// Core types
+export type { EccLib, XOnlyPointAddTweakResult, Parity } from './types.js';
+
+// Context management
+export { EccContext, initEccLib, getEccLib } from './context.js';

package/src/ecc/types.ts

@@ -0,0 +1,154 @@
+/**
+ * ECC (Elliptic Curve Cryptography) type definitions.
+ * Defines interfaces for secp256k1 operations used in Taproot and signatures.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+    Bytes32,
+    PrivateKey,
+    PublicKey,
+    Signature,
+    SchnorrSignature,
+    XOnlyPublicKey,
+} from '../branded.js';
+
+/**
+ * Parity of the y-coordinate for an x-only public key.
+ * - 0: even y-coordinate
+ * - 1: odd y-coordinate
+ */
+export type Parity = 0 | 1;
+
+/**
+ * Result of x-only point addition with tweak.
+ */
+export interface XOnlyPointAddTweakResult {
+    /** Parity of the resulting y-coordinate (0 = even, 1 = odd) */
+    readonly parity: Parity;
+    /** The resulting x-only public key */
+    readonly xOnlyPubkey: XOnlyPublicKey;
+}
+
+/**
+ * Interface for the ECC library used by this library.
+ * This is compatible with tiny-secp256k1 and @noble/secp256k1.
+ *
+ * @example
+ * ```typescript
+ * import { EccLib, initEccLib } from '@btc-vision/bitcoin';
+ * import * as secp256k1 from 'tiny-secp256k1';
+ *
+ * // tiny-secp256k1 implements EccLib
+ * const ecc: EccLib = secp256k1;
+ * initEccLib(ecc);
+ * ```
+ */
+export interface EccLib {
+    /**
+     * Checks if a 32-byte value is a valid x-only public key.
+     *
+     * @param p - 32-byte x-coordinate
+     * @returns True if the point is valid on the secp256k1 curve
+     */
+    isXOnlyPoint(p: Uint8Array): boolean;
+
+    /**
+     * Adds a tweak to an x-only public key.
+     *
+     * @param p - 32-byte x-only public key
+     * @param tweak - 32-byte scalar to add
+     * @returns The tweaked public key with parity, or null if result is invalid
+     */
+    xOnlyPointAddTweak(p: XOnlyPublicKey, tweak: Bytes32): XOnlyPointAddTweakResult | null;
+
+    /**
+     * Signs a 32-byte message hash with a private key (ECDSA).
+     * Optional - only needed for signing operations.
+     *
+     * @param hash - 32-byte message hash
+     * @param privateKey - 32-byte private key
+     * @returns DER-encoded signature
+     */
+    sign?(hash: Bytes32, privateKey: PrivateKey): Signature;
+
+    /**
+     * Signs a 32-byte message hash with a private key (Schnorr/BIP340).
+     * Optional - only needed for Taproot key-path signing.
+     *
+     * @param hash - 32-byte message hash
+     * @param privateKey - 32-byte private key
+     * @returns 64-byte Schnorr signature
+     */
+    signSchnorr?(hash: Bytes32, privateKey: PrivateKey): SchnorrSignature;
+
+    /**
+     * Verifies an ECDSA signature.
+     * Optional - only needed for signature verification.
+     *
+     * @param hash - 32-byte message hash
+     * @param publicKey - 33 or 65-byte public key
+     * @param signature - DER-encoded signature
+     * @returns True if signature is valid
+     */
+    verify?(hash: Bytes32, publicKey: PublicKey, signature: Signature): boolean;
+
+    /**
+     * Verifies a Schnorr/BIP340 signature.
+     * Optional - only needed for Taproot signature verification.
+     *
+     * @param hash - 32-byte message hash
+     * @param publicKey - 32-byte x-only public key
+     * @param signature - 64-byte Schnorr signature
+     * @returns True if signature is valid
+     */
+    verifySchnorr?(hash: Bytes32, publicKey: XOnlyPublicKey, signature: SchnorrSignature): boolean;
+
+    /**
+     * Derives a public key from a private key.
+     * Optional - only needed for key derivation.
+     *
+     * @param privateKey - 32-byte private key
+     * @param compressed - Whether to return compressed (33-byte) or uncompressed (65-byte)
+     * @returns The public key, or null if private key is invalid
+     */
+    pointFromScalar?(privateKey: PrivateKey, compressed?: boolean): PublicKey | null;
+
+    /**
+     * Computes the x-only public key from a private key.
+     * Optional - only needed for Taproot key derivation.
+     *
+     * @param privateKey - 32-byte private key
+     * @returns 32-byte x-only public key, or null if private key is invalid
+     */
+    xOnlyPointFromScalar?(privateKey: PrivateKey): XOnlyPublicKey | null;
+
+    /**
+     * Converts a full public key to x-only format.
+     * Optional - only needed when working with x-only keys.
+     *
+     * @param pubkey - 33 or 65-byte public key
+     * @returns 32-byte x-only public key
+     */
+    xOnlyPointFromPoint?(pubkey: PublicKey): XOnlyPublicKey;
+
+    /**
+     * Adds a scalar to a private key.
+     * Optional - only needed for key tweaking.
+     *
+     * @param privateKey - 32-byte private key
+     * @param tweak - 32-byte scalar to add
+     * @returns The tweaked private key, or null if result is invalid
+     */
+    privateAdd?(privateKey: PrivateKey, tweak: Bytes32): PrivateKey | null;
+
+    /**
+     * Negates a private key.
+     * Optional - only needed for Taproot parity handling.
+     *
+     * @param privateKey - 32-byte private key
+     * @returns The negated private key
+     */
+    privateNegate?(privateKey: PrivateKey): PrivateKey;
+}

package/src/ecpair.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Ambient module declaration for ecpair.
+ *
+ * The upstream ecpair@3 .d.ts files depend on valibot@^0.37 type-level APIs.
+ * When a different valibot major is hoisted (e.g. v1.x required by bip32),
+ * @typescript-eslint resolves valibot from the project root instead of
+ * ecpair's nested node_modules, turning every ecpair type into an error type.
+ *
+ * This local declaration re-exports the subset of ecpair's public API that
+ * this project actually uses, without any valibot dependency.
+ */
+declare module 'ecpair' {
+    interface Network {
+        messagePrefix: string | Uint8Array;
+        bech32: string;
+        bip32: {
+            public: number;
+            private: number;
+        };
+        pubKeyHash: number;
+        scriptHash: number;
+        wif: number;
+    }
+
+    interface Signer {
+        publicKey: Uint8Array;
+        network?: unknown;
+        sign(hash: Uint8Array, lowR?: boolean): Uint8Array;
+    }
+
+    interface SignerAsync {
+        publicKey: Uint8Array;
+        network?: unknown;
+        sign(hash: Uint8Array, lowR?: boolean): Promise<Uint8Array>;
+    }
+
+    interface ECPairInterface extends Signer {
+        compressed: boolean;
+        network: Network;
+        lowR: boolean;
+        privateKey?: Uint8Array;
+        toWIF(): string;
+        tweak(t: Uint8Array): ECPairInterface;
+        verify(hash: Uint8Array, signature: Uint8Array): boolean;
+        verifySchnorr(hash: Uint8Array, signature: Uint8Array): boolean;
+        signSchnorr(hash: Uint8Array): Uint8Array;
+    }
+
+    interface ECPairOptions {
+        compressed?: boolean;
+        network?: Network;
+        rng?: (arg?: number) => Uint8Array;
+    }
+
+    interface ECPairAPI {
+        isPoint(maybePoint: unknown): boolean;
+        fromPrivateKey(buffer: Uint8Array, options?: ECPairOptions): ECPairInterface;
+        fromPublicKey(buffer: Uint8Array, options?: ECPairOptions): ECPairInterface;
+        fromWIF(wifString: string, network?: Network | Network[]): ECPairInterface;
+        makeRandom(options?: ECPairOptions): ECPairInterface;
+    }
+
+    interface TinySecp256k1Interface {
+        isPoint(p: Uint8Array): boolean;
+        pointCompress(p: Uint8Array, compressed?: boolean): Uint8Array;
+        isPrivate(d: Uint8Array): boolean;
+        pointFromScalar(d: Uint8Array, compressed?: boolean): Uint8Array | null;
+        xOnlyPointAddTweak(
+            p: Uint8Array,
+            tweak: Uint8Array,
+        ): { parity: 1 | 0; xOnlyPubkey: Uint8Array } | null;
+        privateAdd(d: Uint8Array, tweak: Uint8Array): Uint8Array | null;
+        privateNegate(d: Uint8Array): Uint8Array;
+        sign(h: Uint8Array, d: Uint8Array, e?: Uint8Array): Uint8Array;
+        signSchnorr?(h: Uint8Array, d: Uint8Array, e?: Uint8Array): Uint8Array;
+        verify(h: Uint8Array, Q: Uint8Array, signature: Uint8Array, strict?: boolean): boolean;
+        verifySchnorr?(h: Uint8Array, Q: Uint8Array, signature: Uint8Array): boolean;
+    }
+
+    const networks: {
+        bitcoin: Network;
+        testnet: Network;
+    };
+
+    function ECPairFactory(ecc: TinySecp256k1Interface): ECPairAPI;
+    export default ECPairFactory;
+
+    export {
+        ECPairFactory,
+        Signer,
+        SignerAsync,
+        ECPairAPI,
+        ECPairInterface,
+        ECPairOptions,
+        TinySecp256k1Interface,
+        Network,
+        networks,
+    };
+}

package/src/errors.ts

@@ -0,0 +1,163 @@
+/**
+ * Custom error types for the Bitcoin library.
+ * @packageDocumentation
+ */
+
+/**
+ * Base error class for all Bitcoin-related errors.
+ *
+ * @example
+ * ```typescript
+ * import { BitcoinError } from '@btc-vision/bitcoin';
+ *
+ * if (error instanceof BitcoinError) {
+ *     console.log('Bitcoin library error:', error.message);
+ * }
+ * ```
+ */
+export class BitcoinError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'BitcoinError';
+        // Maintains proper stack trace for where error was thrown (V8 engines)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, BitcoinError);
+        }
+    }
+}
+
+/**
+ * Error thrown when input validation fails.
+ *
+ * @example
+ * ```typescript
+ * import { ValidationError } from '@btc-vision/bitcoin';
+ *
+ * throw new ValidationError('Invalid public key length');
+ * ```
+ */
+export class ValidationError extends BitcoinError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+/**
+ * Error thrown when an invalid input is provided to a transaction.
+ *
+ * @example
+ * ```typescript
+ * import { InvalidInputError } from '@btc-vision/bitcoin';
+ *
+ * throw new InvalidInputError('Input index out of range');
+ * ```
+ */
+export class InvalidInputError extends BitcoinError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'InvalidInputError';
+    }
+}
+
+/**
+ * Error thrown when an invalid output is provided to a transaction.
+ *
+ * @example
+ * ```typescript
+ * import { InvalidOutputError } from '@btc-vision/bitcoin';
+ *
+ * throw new InvalidOutputError('Output value exceeds maximum');
+ * ```
+ */
+export class InvalidOutputError extends BitcoinError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'InvalidOutputError';
+    }
+}
+
+/**
+ * Error thrown when a script operation fails.
+ *
+ * @example
+ * ```typescript
+ * import { ScriptError } from '@btc-vision/bitcoin';
+ *
+ * throw new ScriptError('Failed to decompile script');
+ * ```
+ */
+export class ScriptError extends BitcoinError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'ScriptError';
+    }
+}
+
+/**
+ * Error thrown when a PSBT operation fails.
+ *
+ * @example
+ * ```typescript
+ * import { PsbtError } from '@btc-vision/bitcoin';
+ *
+ * throw new PsbtError('Cannot finalize unsigned input');
+ * ```
+ */
+export class PsbtError extends BitcoinError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'PsbtError';
+    }
+}
+
+/**
+ * Error thrown when ECC library is not initialized.
+ *
+ * @example
+ * ```typescript
+ * import { EccError } from '@btc-vision/bitcoin';
+ *
+ * throw new EccError('ECC library must be initialized before use');
+ * ```
+ */
+export class EccError extends BitcoinError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'EccError';
+    }
+}
+
+/**
+ * Error thrown when address encoding/decoding fails.
+ *
+ * @example
+ * ```typescript
+ * import { AddressError } from '@btc-vision/bitcoin';
+ *
+ * throw new AddressError('Invalid address checksum');
+ * ```
+ */
+export class AddressError extends BitcoinError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AddressError';
+    }
+}
+
+/**
+ * Error thrown when signature operations fail.
+ *
+ * @example
+ * ```typescript
+ * import { SignatureError } from '@btc-vision/bitcoin';
+ *
+ * throw new SignatureError('Invalid signature format');
+ * ```
+ */
+export class SignatureError extends BitcoinError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'SignatureError';
+    }
+}