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

package/src/ecc/context.ts

@@ -4,9 +4,8 @@
  *
  * @packageDocumentation
  */
-import type { EccLib } from './types.js';
-import { equals, fromHex } from '../io/index.js';
-import type { Bytes32, XOnlyPublicKey } from '../types.js';
+import type { CryptoBackend } from '@btc-vision/ecpair';
+import { verifyCryptoBackend } from '@btc-vision/ecpair';
 
 /**
  * Context class for managing the ECC library instance.
@@ -15,10 +14,11 @@ import type { Bytes32, XOnlyPublicKey } from '../types.js';
  * @example
  * ```typescript
  * import { EccContext } from '@btc-vision/bitcoin';
- * import * as secp256k1 from 'tiny-secp256k1';
+ * import { createNobleBackend } from '@btc-vision/ecpair';
  *
  * // Initialize once at app startup
- * EccContext.init(secp256k1);
+ * const backend = createNobleBackend();
+ * EccContext.init(backend);
  *
  * // Get instance anywhere in your code
  * const ecc = EccContext.get();
@@ -29,16 +29,16 @@ import type { Bytes32, XOnlyPublicKey } from '../types.js';
  */
 export class EccContext {
     static #instance: EccContext | undefined;
-    readonly #lib: EccLib;
+    readonly #lib: CryptoBackend;
 
-    private constructor(lib: EccLib) {
+    private constructor(lib: CryptoBackend) {
         this.#lib = lib;
     }
 
     /**
      * The underlying ECC library instance.
      */
-    get lib(): EccLib {
+    get lib(): CryptoBackend {
         return this.#lib;
     }
 
@@ -46,20 +46,24 @@ export class EccContext {
      * 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
+     * @param lib - The CryptoBackend instance to initialize
      * @returns The initialized EccContext instance
-     * @throws Error if the ECC library fails verification
+     * @throws Error if the CryptoBackend fails verification
      *
      * @example
      * ```typescript
      * import { EccContext } from '@btc-vision/bitcoin';
-     * import * as secp256k1 from 'tiny-secp256k1';
+     * import { createNobleBackend } from '@btc-vision/ecpair';
      *
-     * const context = EccContext.init(secp256k1);
+     * const context = EccContext.init(createNobleBackend());
      * ```
      */
-    static init(lib: EccLib): EccContext {
-        verifyEcc(lib);
+    static init(lib: CryptoBackend): EccContext {
+        // Skip re-verification if same lib is already initialized
+        if (EccContext.#instance && EccContext.#instance.#lib === lib) {
+            return EccContext.#instance;
+        }
+        verifyCryptoBackend(lib);
         EccContext.#instance = new EccContext(lib);
         return EccContext.#instance;
     }
@@ -75,7 +79,7 @@ export class EccContext {
      * import { EccContext } from '@btc-vision/bitcoin';
      *
      * const context = EccContext.get();
-     * const isValid = context.lib.isXOnlyPoint(someKey);
+     * const tweaked = context.lib.xOnlyPointAddTweak(key, tweak);
      * ```
      */
     static get(): EccContext {
@@ -113,7 +117,7 @@ export class EccContext {
      * import { EccContext } from '@btc-vision/bitcoin';
      *
      * if (!EccContext.isInitialized()) {
-     *     EccContext.init(secp256k1);
+     *     EccContext.init(createNobleBackend());
      * }
      * ```
      */
@@ -127,22 +131,22 @@ export class EccContext {
  * 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
+ * @param eccLib - The CryptoBackend instance to initialize, or undefined to clear
+ * @throws Error if the CryptoBackend fails verification
  *
  * @example
  * ```typescript
  * import { initEccLib } from '@btc-vision/bitcoin';
- * import * as secp256k1 from 'tiny-secp256k1';
+ * import { createNobleBackend } from '@btc-vision/ecpair';
  *
  * // Initialize the ECC library
- * initEccLib(secp256k1);
+ * initEccLib(createNobleBackend());
  *
  * // Clear the library
  * initEccLib(undefined);
  * ```
  */
-export function initEccLib(eccLib: EccLib | undefined): void {
+export function initEccLib(eccLib: CryptoBackend | undefined): void {
     if (eccLib === undefined) {
         EccContext.clear();
         return;
@@ -154,127 +158,20 @@ export function initEccLib(eccLib: EccLib | undefined): void {
  * Retrieves the initialized ECC library instance.
  * This is a convenience function that wraps EccContext.get().lib.
  *
- * @returns The ECC library instance
+ * @returns The CryptoBackend 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';
+ * import { createNobleBackend } from '@btc-vision/ecpair';
  *
- * initEccLib(secp256k1);
+ * initEccLib(createNobleBackend());
  *
  * const ecc = getEccLib();
- * const isValid = ecc.isXOnlyPoint(somePublicKey);
+ * const tweaked = ecc.xOnlyPointAddTweak(pubkey, tweak);
  * ```
  */
-export function getEccLib(): EccLib {
+export function getEccLib(): CryptoBackend {
     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

@@ -7,8 +7,8 @@
  * @packageDocumentation
  */
 
-// Core types
-export type { EccLib, XOnlyPointAddTweakResult, Parity } from './types.js';
+// Core types (CryptoBackend is the canonical name; EccLib is a deprecated alias)
+export type { CryptoBackend, EccLib, XOnlyPointAddTweakResult, Parity } from './types.js';
 
 // Context management
 export { EccContext, initEccLib, getEccLib } from './context.js';

package/src/ecc/types.ts

@@ -1,147 +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, SchnorrSignature, Signature, 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');
+}