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

package/src/ecc/types.ts

@@ -1,154 +1,16 @@
 /**
  * ECC (Elliptic Curve Cryptography) type definitions.
- * Defines interfaces for secp256k1 operations used in Taproot and signatures.
+ *
+ * Re-exports {@link CryptoBackend} from `@btc-vision/ecpair` as the canonical
+ * interface for secp256k1 operations. The legacy `EccLib` name is kept as a
+ * type alias for backward compatibility.
  *
  * @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;
-}
+export type { CryptoBackend, XOnlyPointAddTweakResult, Parity } from '@btc-vision/ecpair';
 
 /**
- * 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);
- * ```
+ * @deprecated Use {@link CryptoBackend} from `@btc-vision/ecpair` instead.
  */
-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;
-}
+export type { CryptoBackend as EccLib } from '@btc-vision/ecpair';

package/src/env.ts

@@ -0,0 +1,239 @@
+/**
+ * Runtime capability verification and polyfills.
+ *
+ * Polyfills features that can be shimmed (TextEncoder, Map, Promise.allSettled, Symbol.dispose).
+ * Throws early with a clear error for features that cannot be polyfilled (BigInt, Uint8Array,
+ * structuredClone, DataView BigInt methods).
+ *
+ * Imported as a side effect by the main entry point.
+ *
+ * @packageDocumentation
+ */
+
+// ---------------------------------------------------------------------------
+// Hard requirements — cannot be polyfilled
+// ---------------------------------------------------------------------------
+
+const missing: string[] = [];
+
+if (typeof BigInt === 'undefined') {
+    missing.push('BigInt (ES2020 — required for satoshi values)');
+}
+
+if (typeof Uint8Array === 'undefined') {
+    missing.push('Uint8Array (TypedArrays — required for all binary operations)');
+}
+
+if (typeof DataView !== 'undefined' && typeof DataView.prototype.getBigInt64 !== 'function') {
+    missing.push('DataView.prototype.getBigInt64 (ES2020 — required for transaction parsing)');
+}
+
+if (missing.length > 0) {
+    throw new Error(
+        `@btc-vision/bitcoin: unsupported runtime. Missing capabilities:\n` +
+            missing.map((cap) => `  - ${cap}`).join('\n') +
+            `\n\nThese features cannot be polyfilled. This library requires a modern JavaScript engine (ES2022+).`,
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Polyfills — shim features that can be reasonably implemented
+// ---------------------------------------------------------------------------
+
+// TextEncoder / TextDecoder (for older WebView / jsdom environments)
+if (typeof globalThis.TextEncoder === 'undefined') {
+    globalThis.TextEncoder = class TextEncoder {
+        readonly encoding = 'utf-8';
+
+        encode(input: string = ''): Uint8Array {
+            // Fast path for ASCII
+            const utf8: number[] = [];
+            for (let i = 0; i < input.length; i++) {
+                let code = input.charCodeAt(i);
+                if (code < 0x80) {
+                    utf8.push(code);
+                } else if (code < 0x800) {
+                    utf8.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+                } else if (code >= 0xd800 && code <= 0xdbff) {
+                    // Surrogate pair
+                    const next = input.charCodeAt(++i);
+                    code = 0x10000 + ((code - 0xd800) << 10) + (next - 0xdc00);
+                    utf8.push(
+                        0xf0 | (code >> 18),
+                        0x80 | ((code >> 12) & 0x3f),
+                        0x80 | ((code >> 6) & 0x3f),
+                        0x80 | (code & 0x3f),
+                    );
+                } else {
+                    utf8.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+                }
+            }
+            return new Uint8Array(utf8);
+        }
+
+        encodeInto(src: string, dest: Uint8Array): { read: number; written: number } {
+            const encoded = this.encode(src);
+            const written = Math.min(encoded.length, dest.length);
+            dest.set(encoded.subarray(0, written));
+            return { read: src.length, written };
+        }
+    } as unknown as typeof TextEncoder;
+}
+
+if (typeof globalThis.TextDecoder === 'undefined') {
+    globalThis.TextDecoder = class TextDecoder {
+        readonly encoding = 'utf-8';
+        readonly fatal = false;
+        readonly ignoreBOM = false;
+
+        decode(input?: ArrayBufferView | ArrayBuffer): string {
+            if (!input) return '';
+            const bytes =
+                input instanceof ArrayBuffer
+                    ? new Uint8Array(input)
+                    : new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+
+            let result = '';
+            for (let i = 0; i < bytes.length; ) {
+                const byte = bytes[i]!;
+                let code: number;
+                if (byte < 0x80) {
+                    code = byte;
+                    i++;
+                } else if ((byte & 0xe0) === 0xc0) {
+                    code = ((byte & 0x1f) << 6) | (bytes[i + 1]! & 0x3f);
+                    i += 2;
+                } else if ((byte & 0xf0) === 0xe0) {
+                    code = ((byte & 0x0f) << 12) | ((bytes[i + 1]! & 0x3f) << 6) | (bytes[i + 2]! & 0x3f);
+                    i += 3;
+                } else {
+                    code =
+                        ((byte & 0x07) << 18) |
+                        ((bytes[i + 1]! & 0x3f) << 12) |
+                        ((bytes[i + 2]! & 0x3f) << 6) |
+                        (bytes[i + 3]! & 0x3f);
+                    i += 4;
+                }
+
+                if (code <= 0xffff) {
+                    result += String.fromCharCode(code);
+                } else {
+                    // Surrogate pair
+                    code -= 0x10000;
+                    result += String.fromCharCode(0xd800 + (code >> 10), 0xdc00 + (code & 0x3ff));
+                }
+            }
+            return result;
+        }
+    } as unknown as typeof TextDecoder;
+}
+
+// Map (for extremely old environments)
+if (typeof globalThis.Map === 'undefined') {
+    globalThis.Map = class Map<K, V> {
+        readonly #entries: Array<[K, V]> = [];
+
+        constructor(entries?: Iterable<[K, V]> | null) {
+            if (entries) {
+                for (const [k, v] of entries) {
+                    this.set(k, v);
+                }
+            }
+        }
+
+        get size(): number {
+            return this.#entries.length;
+        }
+
+        has(key: K): boolean {
+            return this.#entries.some(([k]) => k === key);
+        }
+
+        get(key: K): V | undefined {
+            const entry = this.#entries.find(([k]) => k === key);
+            return entry?.[1];
+        }
+
+        set(key: K, value: V): this {
+            const idx = this.#entries.findIndex(([k]) => k === key);
+            if (idx >= 0) {
+                this.#entries[idx] = [key, value];
+            } else {
+                this.#entries.push([key, value]);
+            }
+            return this;
+        }
+
+        delete(key: K): boolean {
+            const idx = this.#entries.findIndex(([k]) => k === key);
+            if (idx >= 0) {
+                this.#entries.splice(idx, 1);
+                return true;
+            }
+            return false;
+        }
+
+        clear(): void {
+            this.#entries.length = 0;
+        }
+
+        forEach(cb: (value: V, key: K, map: Map<K, V>) => void): void {
+            for (const [k, v] of this.#entries) {
+                cb(v, k, this);
+            }
+        }
+
+        keys(): IterableIterator<K> {
+            return this.#entries.map(([k]) => k)[Symbol.iterator]() as IterableIterator<K>;
+        }
+
+        values(): IterableIterator<V> {
+            return this.#entries.map(([, v]) => v)[Symbol.iterator]() as IterableIterator<V>;
+        }
+
+        entries(): IterableIterator<[K, V]> {
+            return this.#entries[Symbol.iterator]() as IterableIterator<[K, V]>;
+        }
+
+        [Symbol.iterator](): IterableIterator<[K, V]> {
+            return this.entries();
+        }
+
+        get [Symbol.toStringTag](): string {
+            return 'Map';
+        }
+    } as unknown as MapConstructor;
+}
+
+// Promise.allSettled (ES2020)
+if (typeof Promise.allSettled !== 'function') {
+    Promise.allSettled = function allSettled<T extends readonly unknown[]>(
+        promises: T,
+    ): Promise<{
+        -readonly [K in keyof T]: PromiseSettledResult<Awaited<T[K]>>;
+    }> {
+        return Promise.all(
+            Array.from(promises as Iterable<unknown>, (p) =>
+                Promise.resolve(p).then(
+                    (value) => ({ status: 'fulfilled' as const, value }),
+                    (reason: unknown) => ({ status: 'rejected' as const, reason }),
+                ),
+            ),
+        ) as Promise<{
+            -readonly [K in keyof T]: PromiseSettledResult<Awaited<T[K]>>;
+        }>;
+    };
+}
+
+// structuredClone (ES2022 — used for PSBT cloning)
+if (typeof globalThis.structuredClone === 'undefined') {
+    globalThis.structuredClone = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+}
+
+// Symbol.dispose / Symbol.asyncDispose (ES2024 — Explicit Resource Management)
+if (typeof Symbol['dispose'] === 'undefined') {
+    (Symbol as unknown as Record<string, symbol>)['dispose'] = Symbol.for('Symbol.dispose');
+}
+if (typeof Symbol['asyncDispose'] === 'undefined') {
+    (Symbol as unknown as Record<string, symbol>)['asyncDispose'] = Symbol.for('Symbol.asyncDispose');
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+import './env.js';
 import type {
     PsbtInput as _PsbtInput,
     PsbtInputUpdate as _PsbtInputUpdate,
@@ -17,6 +18,18 @@ import * as payments from './payments/index.js';
 import * as script from './script.js';
 import * as crypto from './crypto.js';
 import * as Transaction from './transaction.js';
+// Custom error types
+import {
+    AddressError,
+    BitcoinError,
+    EccError,
+    InvalidInputError,
+    InvalidOutputError,
+    PsbtError,
+    ScriptError,
+    SignatureError,
+    ValidationError,
+} from './errors.js';
 
 export * as address from './address.js';
 export * as crypto from './crypto.js';
@@ -27,7 +40,41 @@ export * as script from './script.js';
 export { Block } from './block.js';
 /** @hidden */
 export * from './crypto.js';
-export * from './psbt.js';
+export {
+    Psbt,
+    PsbtCache,
+    PsbtSigner,
+    PsbtFinalizer,
+    PsbtTransaction,
+    transactionFromBuffer,
+    getFinalScripts,
+    prepareFinalScripts,
+} from './psbt.js';
+export type {
+    TransactionInput,
+    PsbtTxInput,
+    TransactionOutput,
+    PsbtTxOutput,
+    ValidateSigFunction,
+    PsbtBaseExtended,
+    PsbtOptsOptional,
+    PsbtOpts,
+    PsbtInputExtended,
+    PsbtOutputExtended,
+    PsbtOutputExtendedScript,
+    HDSigner,
+    HDSignerAsync,
+    Signer,
+    SignerAsync,
+    TaprootHashCheckSigner,
+    PsbtCacheInterface,
+    TxCacheNumberKey,
+    ScriptType,
+    AllScriptType,
+    GetScriptReturn,
+    FinalScriptsFunc,
+    FinalTaprootScriptsFunc,
+} from './psbt.js';
 /** @hidden */
 export { opcodes } from './opcodes.js';
 export { Transaction } from './transaction.js';
@@ -36,7 +83,7 @@ export type { TaprootHashCache } from './transaction.js';
 export type { Network } from './networks.js';
 /** @hidden */
 export { initEccLib, getEccLib, EccContext } from './ecc/context.js';
-export type { EccLib } from './ecc/types.js';
+export type { CryptoBackend, EccLib } from './ecc/types.js';
 export { PaymentType } from './payments/index.js';
 export type {
     Payment,
@@ -96,8 +143,6 @@ export {
     xor,
     fromUtf8,
     toUtf8,
-    MemoryPool,
-    SimpleMemoryPool,
     varuint,
 } from './io/index.js';
 export * from './payments/bip341.js';
@@ -140,19 +185,6 @@ export {
 } from './types.js';
 export type { XOnlyPointAddTweakResult } from './ecc/types.js';
 
-// Custom error types
-import {
-    BitcoinError,
-    ValidationError,
-    InvalidInputError,
-    InvalidOutputError,
-    ScriptError,
-    PsbtError,
-    EccError,
-    AddressError,
-    SignatureError,
-} from './errors.js';
-
 export {
     BitcoinError,
     ValidationError,
@@ -178,23 +210,26 @@ export const errors = {
     SignatureError,
 } as const;
 
-// Worker-based parallel signing
-export * as workers from './workers/index.js';
+// Worker-based parallel signing (browser-safe shared exports only)
+// For createSigningPool / detectRuntime, use '@btc-vision/bitcoin/workers' subpath export
+// which routes to the correct platform-specific implementation.
 export {
     WorkerSigningPool,
     getSigningPool,
     SignatureType,
-    createSigningPool,
     signPsbtParallel,
-} from './workers/index.js';
+    prepareSigningTasks,
+    applySignaturesToPsbt,
+} from './workers/index.shared.js';
 export type {
     WorkerPoolConfig,
     SigningTask,
+    SigningPoolLike,
     ParallelSignerKeyPair,
     ParallelSigningResult,
     ParallelSignOptions,
     PsbtParallelKeyPair,
-} from './workers/index.js';
+} from './workers/index.shared.js';
 
 const bitcoin = {
     networks,

package/src/io/BinaryReader.ts

@@ -70,24 +70,6 @@ export class BinaryReader {
         this.#offset = offset;
     }
 
-    /**
-     * Creates a BinaryReader from a hex string.
-     *
-     * @param hex - Hex string (with or without 0x prefix)
-     * @returns A new BinaryReader instance
-     *
-     * @example
-     * ```typescript
-     * import { BinaryReader } from '@btc-vision/bitcoin';
-     *
-     * const reader = BinaryReader.fromHex('01000000');
-     * const version = reader.readInt32LE(); // 1
-     * ```
-     */
-    public static fromHex(hex: string): BinaryReader {
-        return new BinaryReader(fromHex(hex));
-    }
-
     /**
      * Current read position in the buffer.
      */
@@ -129,6 +111,24 @@ export class BinaryReader {
         return this.#data;
     }
 
+    /**
+     * Creates a BinaryReader from a hex string.
+     *
+     * @param hex - Hex string (with or without 0x prefix)
+     * @returns A new BinaryReader instance
+     *
+     * @example
+     * ```typescript
+     * import { BinaryReader } from '@btc-vision/bitcoin';
+     *
+     * const reader = BinaryReader.fromHex('01000000');
+     * const version = reader.readInt32LE(); // 1
+     * ```
+     */
+    public static fromHex(hex: string): BinaryReader {
+        return new BinaryReader(fromHex(hex));
+    }
+
     /**
      * Reads an 8-bit unsigned integer.
      *

package/src/io/BinaryWriter.ts

@@ -91,26 +91,6 @@ export class BinaryWriter {
         this.#view = new DataView(this.#data.buffer, this.#data.byteOffset, this.#data.byteLength);
     }
 
-    /**
-     * Creates a BinaryWriter with automatic capacity management.
-     *
-     * Initial capacity is 256 bytes, grows as needed.
-     *
-     * @returns A new GrowableBinaryWriter instance
-     *
-     * @example
-     * ```typescript
-     * import { BinaryWriter } from '@btc-vision/bitcoin';
-     *
-     * const writer = BinaryWriter.growable();
-     * writer.writeUInt32LE(1);
-     * writer.writeBytes(new Uint8Array(1000)); // Automatically grows
-     * ```
-     */
-    public static growable(initialCapacity: number = 256): GrowableBinaryWriter {
-        return new GrowableBinaryWriter(initialCapacity);
-    }
-
     /**
      * Current write position in the buffer.
      */
@@ -152,6 +132,26 @@ export class BinaryWriter {
         return this.#data;
     }
 
+    /**
+     * Creates a BinaryWriter with automatic capacity management.
+     *
+     * Initial capacity is 256 bytes, grows as needed.
+     *
+     * @returns A new GrowableBinaryWriter instance
+     *
+     * @example
+     * ```typescript
+     * import { BinaryWriter } from '@btc-vision/bitcoin';
+     *
+     * const writer = BinaryWriter.growable();
+     * writer.writeUInt32LE(1);
+     * writer.writeBytes(new Uint8Array(1000)); // Automatically grows
+     * ```
+     */
+    public static growable(initialCapacity: number = 256): GrowableBinaryWriter {
+        return new GrowableBinaryWriter(initialCapacity);
+    }
+
     /**
      * Writes an 8-bit unsigned integer.
      *
@@ -583,29 +583,6 @@ export class GrowableBinaryWriter {
         return this.#data.length;
     }
 
-    /**
-     * Ensures the buffer has enough space for additional bytes.
-     *
-     * @param additionalBytes - Number of additional bytes needed
-     */
-    #ensureCapacity(additionalBytes: number): void {
-        const required = this.#offset + additionalBytes;
-        if (required <= this.#data.length) {
-            return;
-        }
-
-        // Grow by at least 2x or to required size
-        let newCapacity = this.#data.length * 2;
-        while (newCapacity < required) {
-            newCapacity *= 2;
-        }
-
-        const newData = new Uint8Array(newCapacity);
-        newData.set(this.#data.subarray(0, this.#offset));
-        this.#data = newData;
-        this.#view = new DataView(this.#data.buffer);
-    }
-
     public writeUInt8(value: number): this {
         this.#ensureCapacity(1);
         this.#data[this.#offset++] = value & 0xff;
@@ -693,4 +670,27 @@ export class GrowableBinaryWriter {
     public toHex(): string {
         return toHex(this.finish());
     }
+
+    /**
+     * Ensures the buffer has enough space for additional bytes.
+     *
+     * @param additionalBytes - Number of additional bytes needed
+     */
+    #ensureCapacity(additionalBytes: number): void {
+        const required = this.#offset + additionalBytes;
+        if (required <= this.#data.length) {
+            return;
+        }
+
+        // Grow by at least 2x or to required size
+        let newCapacity = this.#data.length * 2;
+        while (newCapacity < required) {
+            newCapacity *= 2;
+        }
+
+        const newData = new Uint8Array(newCapacity);
+        newData.set(this.#data.subarray(0, this.#offset));
+        this.#data = newData;
+        this.#view = new DataView(this.#data.buffer);
+    }
 }

package/src/io/hex.ts

@@ -49,7 +49,8 @@ const HEX_TO_NIBBLE: readonly number[] = (() => {
 export function toHex(bytes: Uint8Array): string {
     let result = '';
     for (let i = 0; i < bytes.length; i++) {
-        result += BYTE_TO_HEX[bytes[i]!];
+        const hex = BYTE_TO_HEX[bytes[i] as number];
+        result += hex as string;
     }
     return result;
 }