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

package/src/workers/types.ts

@@ -0,0 +1,413 @@
+/**
+ * Worker thread types for parallel signing operations.
+ *
+ * SECURITY NOTES:
+ * - Private keys are NEVER shared via SharedArrayBuffer
+ * - Keys are cloned via postMessage (isolated per worker)
+ * - Keys are zeroed immediately after signing
+ * - Workers are pooled for performance but keys don't persist
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Signature type enum for worker operations.
+ */
+export const SignatureType = {
+    /** ECDSA signature (secp256k1) */
+    ECDSA: 0,
+    /** Schnorr signature (BIP340) */
+    Schnorr: 1,
+} as const;
+
+export type SignatureType = (typeof SignatureType)[keyof typeof SignatureType];
+
+/**
+ * Message sent to worker for signing operation.
+ *
+ * SECURITY: privateKey is cloned via postMessage, NOT shared.
+ * Worker MUST zero the key after signing.
+ */
+export interface SigningTaskMessage {
+    /** Message type discriminator */
+    readonly type: 'sign';
+    /** Task identifier for correlation */
+    readonly taskId: string;
+    /** Hash to sign (32 bytes) */
+    readonly hash: Uint8Array;
+    /** Private key (32 bytes) - WILL BE ZEROED after use */
+    readonly privateKey: Uint8Array;
+    /** Public key for verification (33 or 65 bytes) */
+    readonly publicKey: Uint8Array;
+    /** Signature type (ECDSA or Schnorr) */
+    readonly signatureType: SignatureType;
+    /** Low R signing for ECDSA (optional) */
+    readonly lowR?: boolean | undefined;
+    /** Input index this signature is for */
+    readonly inputIndex: number;
+    /** Sighash type for encoding */
+    readonly sighashType: number;
+    /** Leaf hash for Taproot script-path (optional) */
+    readonly leafHash?: Uint8Array | undefined;
+}
+
+/**
+ * Initialization message for worker with ECC library.
+ */
+export interface WorkerInitMessage {
+    /** Message type discriminator */
+    readonly type: 'init';
+    /** Serialized ECC library functions (or library identifier) */
+    readonly eccLibId: string;
+}
+
+/**
+ * Shutdown message for worker.
+ */
+export interface WorkerShutdownMessage {
+    /** Message type discriminator */
+    readonly type: 'shutdown';
+}
+
+/**
+ * Individual task in a batch (without privateKey - shared across batch).
+ */
+export interface BatchSigningTask {
+    /** Task identifier */
+    readonly taskId: string;
+    /** Hash to sign (32 bytes) */
+    readonly hash: Uint8Array;
+    /** Public key for verification */
+    readonly publicKey: Uint8Array;
+    /** Signature type */
+    readonly signatureType: SignatureType;
+    /** Low R for ECDSA */
+    readonly lowR?: boolean | undefined;
+    /** Input index */
+    readonly inputIndex: number;
+    /** Sighash type */
+    readonly sighashType: number;
+    /** Leaf hash for Taproot */
+    readonly leafHash?: Uint8Array | undefined;
+}
+
+/**
+ * Batch signing message - multiple tasks with single private key.
+ * More efficient than sending tasks one at a time.
+ */
+export interface BatchSigningMessage {
+    /** Message type discriminator */
+    readonly type: 'signBatch';
+    /** Batch identifier for correlation */
+    readonly batchId: string;
+    /** Tasks to sign */
+    readonly tasks: readonly BatchSigningTask[];
+    /** Private key (32 bytes) - WILL BE ZEROED after all tasks */
+    readonly privateKey: Uint8Array;
+}
+
+/**
+ * Individual result from a batch.
+ */
+export interface BatchSigningTaskResult {
+    /** Task identifier */
+    readonly taskId: string;
+    /** Signature bytes */
+    readonly signature: Uint8Array;
+    /** Input index */
+    readonly inputIndex: number;
+    /** Public key used */
+    readonly publicKey: Uint8Array;
+    /** Signature type */
+    readonly signatureType: SignatureType;
+    /** Leaf hash (if applicable) */
+    readonly leafHash?: Uint8Array | undefined;
+}
+
+/**
+ * Individual error from a batch.
+ */
+export interface BatchSigningTaskError {
+    /** Task identifier */
+    readonly taskId: string;
+    /** Input index */
+    readonly inputIndex: number;
+    /** Error message */
+    readonly error: string;
+}
+
+/**
+ * Batch result message from worker.
+ */
+export interface BatchSigningResultMessage {
+    /** Message type discriminator */
+    readonly type: 'batchResult';
+    /** Batch identifier for correlation */
+    readonly batchId: string;
+    /** Successful results */
+    readonly results: readonly BatchSigningTaskResult[];
+    /** Errors */
+    readonly errors: readonly BatchSigningTaskError[];
+}
+
+/**
+ * All possible messages to worker.
+ */
+export type WorkerMessage = SigningTaskMessage | BatchSigningMessage | WorkerInitMessage | WorkerShutdownMessage;
+
+/**
+ * Result from worker after signing.
+ */
+export interface SigningResultMessage {
+    /** Message type discriminator */
+    readonly type: 'result';
+    /** Task identifier for correlation */
+    readonly taskId: string;
+    /** Signature bytes (64 bytes raw for Schnorr, or with sighash for ECDSA) */
+    readonly signature: Uint8Array;
+    /** Input index this signature is for */
+    readonly inputIndex: number;
+    /** Public key used for signing */
+    readonly publicKey: Uint8Array;
+    /** Signature type that was used */
+    readonly signatureType: SignatureType;
+    /** Leaf hash for Taproot script-path spending (if applicable) */
+    readonly leafHash?: Uint8Array | undefined;
+}
+
+/**
+ * Error result from worker.
+ */
+export interface SigningErrorMessage {
+    /** Message type discriminator */
+    readonly type: 'error';
+    /** Task identifier for correlation */
+    readonly taskId: string;
+    /** Error message */
+    readonly error: string;
+    /** Input index that failed */
+    readonly inputIndex: number;
+}
+
+/**
+ * Worker ready message.
+ */
+export interface WorkerReadyMessage {
+    /** Message type discriminator */
+    readonly type: 'ready';
+}
+
+/**
+ * Worker shutdown acknowledgment.
+ */
+export interface WorkerShutdownAckMessage {
+    /** Message type discriminator */
+    readonly type: 'shutdown-ack';
+}
+
+/**
+ * Union of all worker response types.
+ */
+export type WorkerResponse =
+    | SigningResultMessage
+    | SigningErrorMessage
+    | BatchSigningResultMessage
+    | WorkerReadyMessage
+    | WorkerShutdownAckMessage;
+
+/**
+ * Type guard for error responses.
+ */
+export function isSigningError(response: WorkerResponse): response is SigningErrorMessage {
+    return response.type === 'error';
+}
+
+/**
+ * Type guard for success responses.
+ */
+export function isSigningResult(response: WorkerResponse): response is SigningResultMessage {
+    return response.type === 'result';
+}
+
+/**
+ * Type guard for batch result responses.
+ */
+export function isBatchResult(response: WorkerResponse): response is BatchSigningResultMessage {
+    return response.type === 'batchResult';
+}
+
+/**
+ * Type guard for ready responses.
+ */
+export function isWorkerReady(response: WorkerResponse): response is WorkerReadyMessage {
+    return response.type === 'ready';
+}
+
+/**
+ * Interface for the ECC library used by workers.
+ * Provides signing functions for ECDSA and Schnorr signatures.
+ */
+export interface WorkerEccLib {
+    /**
+     * Create an ECDSA signature.
+     *
+     * @param hash - 32-byte hash to sign
+     * @param privateKey - 32-byte private key
+     * @param lowR - Optional: grind for low R value
+     * @returns 64-byte raw signature (r || s)
+     */
+    sign(hash: Uint8Array, privateKey: Uint8Array, lowR?: boolean): Uint8Array;
+
+    /**
+     * Create a Schnorr signature (BIP340).
+     *
+     * @param hash - 32-byte hash to sign
+     * @param privateKey - 32-byte private key
+     * @returns 64-byte Schnorr signature
+     */
+    signSchnorr(hash: Uint8Array, privateKey: Uint8Array): Uint8Array;
+}
+
+/**
+ * Configuration for the worker signing pool.
+ */
+export interface WorkerPoolConfig {
+    /**
+     * Number of workers to create.
+     * Default: number of CPU cores (navigator.hardwareConcurrency or os.cpus().length)
+     */
+    readonly workerCount?: number;
+
+    /**
+     * Timeout per signing operation in milliseconds.
+     * Worker is terminated if exceeded (key safety measure).
+     * Default: 30000 (30 seconds)
+     */
+    readonly taskTimeoutMs?: number;
+
+    /**
+     * Maximum time a worker can hold a private key in milliseconds.
+     * Acts as a safety net - worker is terminated if signing takes too long.
+     * Default: 5000 (5 seconds)
+     */
+    readonly maxKeyHoldTimeMs?: number;
+
+    /**
+     * Whether to verify signatures after signing.
+     * Adds overhead but ensures correctness.
+     * Default: true
+     */
+    readonly verifySignatures?: boolean;
+
+    /**
+     * Whether to preserve workers between signing batches.
+     * true = workers stay alive (faster for multiple batches)
+     * false = workers terminated after each batch (more secure)
+     * Default: true (use preserveWorkers() to enable)
+     */
+    readonly preserveWorkers?: boolean;
+}
+
+/**
+ * Signing task for the worker queue.
+ */
+export interface SigningTask {
+    /** Task identifier */
+    readonly taskId: string;
+    /** Input index */
+    readonly inputIndex: number;
+    /** Hash to sign (32 bytes) */
+    readonly hash: Uint8Array;
+    /** Signature type */
+    readonly signatureType: SignatureType;
+    /** Low R for ECDSA */
+    readonly lowR?: boolean | undefined;
+    /** Sighash type */
+    readonly sighashType: number;
+    /** Leaf hash for Taproot script-path */
+    readonly leafHash?: Uint8Array | undefined;
+}
+
+/**
+ * Signer key pair interface for parallel signing.
+ *
+ * SECURITY: getPrivateKey() is only called when dispatching to worker.
+ * The returned bytes are cloned to the worker and then the original
+ * should be considered potentially compromised (in main thread memory).
+ *
+ * For maximum security, use a hardware wallet that never exposes keys.
+ */
+export interface ParallelSignerKeyPair {
+    /** Public key (compressed 33 bytes or uncompressed 65 bytes) */
+    readonly publicKey: Uint8Array;
+
+    /**
+     * Get private key bytes (32 bytes).
+     *
+     * SECURITY WARNING: This exposes the raw private key.
+     * - Called only when dispatching to worker
+     * - Key is cloned to worker via postMessage
+     * - Original in main thread should be zeroed by caller if possible
+     *
+     * For high-security applications, use hardware wallets instead.
+     */
+    getPrivateKey(): Uint8Array;
+
+    /**
+     * Optional: Sign ECDSA directly (fallback if workers unavailable).
+     */
+    sign?(hash: Uint8Array, lowR?: boolean): Uint8Array;
+
+    /**
+     * Optional: Sign Schnorr directly (fallback if workers unavailable).
+     */
+    signSchnorr?(hash: Uint8Array): Uint8Array;
+}
+
+/**
+ * Result of a parallel signing batch.
+ */
+export interface ParallelSigningResult {
+    /** Whether all signatures were created successfully */
+    readonly success: boolean;
+    /** Signatures indexed by input index */
+    readonly signatures: ReadonlyMap<number, SigningResultMessage>;
+    /** Errors indexed by input index */
+    readonly errors: ReadonlyMap<number, string>;
+    /** Total time taken in milliseconds */
+    readonly durationMs: number;
+}
+
+/**
+ * Worker state for pool management.
+ */
+export const WorkerState = {
+    /** Worker is initializing */
+    Initializing: 0,
+    /** Worker is ready and idle */
+    Idle: 1,
+    /** Worker is processing a task */
+    Busy: 2,
+    /** Worker is shutting down */
+    ShuttingDown: 3,
+    /** Worker has terminated */
+    Terminated: 4,
+} as const;
+
+export type WorkerState = (typeof WorkerState)[keyof typeof WorkerState];
+
+/**
+ * Internal worker wrapper for pool management.
+ */
+export interface PooledWorker {
+    /** Unique worker identifier */
+    readonly id: number;
+    /** Current worker state */
+    state: WorkerState;
+    /** The actual worker instance */
+    readonly worker: Worker;
+    /** Current task ID (if busy) */
+    currentTaskId: string | null;
+    /** Timestamp when current task started */
+    taskStartTime: number | null;
+}

package/test/address.spec.ts

@@ -7,8 +7,11 @@ import * as bscript from '../src/script.js';
 import fixtures from './fixtures/address.json' with { type: 'json' };
 
 import { initEccLib } from '../src/index.js';
+import type { EccLib } from '../src/index.js';
 import type { Network } from '../src/networks.js';
 import * as networks from '../src/networks.js';
+import { toHex, fromHex } from '../src/io/index.js';
+import type { Bytes20 } from '../src/types.js';
 
 const NETWORKS: Record<string, Network> = Object.assign(
     {
@@ -37,7 +40,7 @@ describe('address', () => {
                 const decode = baddress.fromBase58Check(f.base58check);
 
                 assert.strictEqual(decode.version, f.version);
-                assert.strictEqual(decode.hash.toString('hex'), f.hash);
+                assert.strictEqual(toHex(decode.hash), f.hash);
             });
         });
 
@@ -68,7 +71,7 @@ describe('address', () => {
                     validPrefixes.includes(actual.prefix),
                     `Expected prefix to be one of [${validPrefixes.join(', ')}], got ${actual.prefix}`,
                 );
-                assert.strictEqual(actual.data.toString('hex'), f.data);
+                assert.strictEqual(toHex(actual.data), f.data);
             });
         });
 
@@ -82,7 +85,7 @@ describe('address', () => {
     });
 
     describe('fromOutputScript', () => {
-        initEccLib(ecc);
+        initEccLib(ecc as unknown as EccLib);
         fixtures.standard.forEach((f) => {
             it('encodes ' + f.script.slice(0, 30) + '... (' + f.network + ')', () => {
                 const script = bscript.fromASM(f.script);
@@ -108,7 +111,7 @@ describe('address', () => {
             if (!f.base58check) return;
 
             it('encodes ' + f.hash + ' (' + f.network + ')', () => {
-                const address = baddress.toBase58Check(Buffer.from(f.hash, 'hex'), f.version);
+                const address = baddress.toBase58Check(fromHex(f.hash) as Bytes20, f.version);
 
                 assert.strictEqual(address, f.base58check);
             });
@@ -118,7 +121,7 @@ describe('address', () => {
     describe('toBech32', () => {
         fixtures.bech32.forEach((f) => {
             if (!f.address) return;
-            const data = Buffer.from(f.data, 'hex');
+            const data = fromHex(f.data);
 
             it('encode ' + f.address, () => {
                 assert.deepStrictEqual(
@@ -134,7 +137,7 @@ describe('address', () => {
 
             it('encode fails (' + f.exception, () => {
                 assert.throws(() => {
-                    baddress.toBech32(Buffer.from(f.data, 'hex'), f.version, f.prefix);
+                    baddress.toBech32(fromHex(f.data), f.version, f.prefix);
                 }, new RegExp(f.exception));
             });
         });

package/test/bitcoin.core.spec.ts

@@ -2,6 +2,8 @@ import assert from 'assert';
 import base58 from 'bs58';
 import { describe, it } from 'vitest';
 import * as bitcoin from '../src/index.js';
+import type { Bytes20, Satoshi, Script } from '../src/types.js';
+import { toHex, fromHex, reverseCopy } from '../src/io/index.js';
 import base58EncodeDecode from './fixtures/core/base58_encode_decode.json' with { type: 'json' };
 import base58KeysInvalid from './fixtures/core/base58_keys_invalid.json' with { type: 'json' };
 import base58KeysValid from './fixtures/core/base58_keys_valid.json' with { type: 'json' };
@@ -20,13 +22,13 @@ describe('Bitcoin-core', () => {
 
             it('can decode ' + fb58, () => {
                 const buffer = base58.decode(fb58);
-                const actual = Buffer.from(buffer).toString('hex');
+                const actual = toHex(new Uint8Array(buffer));
 
                 assert.strictEqual(actual, fhex);
             });
 
             it('can encode ' + fhex, () => {
-                const buffer = Buffer.from(fhex, 'hex');
+                const buffer = fromHex(fhex);
                 const actual = base58.encode(buffer);
 
                 assert.strictEqual(actual, fb58);
@@ -43,7 +45,7 @@ describe('Bitcoin-core', () => {
 
         base58KeysValid.forEach((f) => {
             const expected = f[0];
-            const hash = Buffer.from(f[1] as any, 'hex');
+            const hash = fromHex(f[1] as any);
             const params = f[2] as any;
 
             if (params.isPrivkey) return;
@@ -55,7 +57,7 @@ describe('Bitcoin-core', () => {
             const version = network[typeMap[params.addrType]];
 
             it(`can export ${expected as string}`, () => {
-                assert.strictEqual(bitcoin.address.toBase58Check(hash, version), expected);
+                assert.strictEqual(bitcoin.address.toBase58Check(hash as Bytes20, version), expected);
             });
         });
     });
@@ -114,7 +116,7 @@ describe('Bitcoin-core', () => {
                     const input = inputs[i];
 
                     // reverse because test data is reversed
-                    const prevOutHash = Buffer.from(input[0] as string, 'hex').reverse();
+                    const prevOutHash = reverseCopy(fromHex(input[0] as string));
                     const prevOutIndex = input[1];
 
                     assert.deepStrictEqual(txIn.hash, prevOutHash);
@@ -153,23 +155,20 @@ describe('Bitcoin-core', () => {
                 const transaction = bitcoin.Transaction.fromHex(txHex);
                 assert.strictEqual(transaction.toHex(), txHex);
 
-                const script = Buffer.from(scriptHex, 'hex');
+                const script = fromHex(scriptHex);
                 const scriptChunks = bitcoin.script.decompile(script);
-                assert.strictEqual(
-                    bitcoin.script.compile(scriptChunks!).toString('hex'),
-                    scriptHex,
-                );
+                assert.strictEqual(toHex(bitcoin.script.compile(scriptChunks!)), scriptHex);
 
-                const hash = transaction.hashForSignature(inIndex, script, hashType);
+                const hash = transaction.hashForSignature(inIndex, script as Script, hashType);
 
                 // reverse because test data is reversed
-                assert.strictEqual((hash.reverse() as Buffer).toString('hex'), expectedHash);
+                assert.strictEqual(toHex(reverseCopy(hash)), expectedHash);
 
                 assert.doesNotThrow(() =>
                     transaction.hashForWitnessV0(
                         inIndex,
-                        script,
-                        0,
+                        script as Script,
+                        0n as Satoshi,
                         // convert to UInt32
                         hashType < 0 ? 0x100000000 + hashType : hashType,
                     ),
@@ -180,13 +179,13 @@ describe('Bitcoin-core', () => {
 
     describe('script.signature.decode', () => {
         sigCanonical.forEach((hex) => {
-            const buffer = Buffer.from(hex, 'hex');
+            const buffer = fromHex(hex);
 
             it('can parse ' + hex, () => {
                 const parsed = bitcoin.script.signature.decode(buffer);
                 const actual = bitcoin.script.signature.encode(parsed.signature, parsed.hashType);
 
-                assert.strictEqual(actual.toString('hex'), hex);
+                assert.strictEqual(toHex(actual), hex);
             });
         });
 
@@ -195,7 +194,7 @@ describe('Bitcoin-core', () => {
             if (i % 2 !== 0) return;
 
             const description = sigNoncanonical[i - 1].slice(0, -1);
-            const buffer = Buffer.from(hex, 'hex');
+            const buffer = fromHex(hex);
 
             it('throws on ' + description, () => {
                 const reg = new RegExp(

package/test/block.spec.ts

@@ -1,6 +1,7 @@
 import assert from 'assert';
 import { beforeEach, describe, it } from 'vitest';
 import { Block } from '../src/index.js';
+import { toHex } from '../src/io/index.js';
 
 import fixtures from './fixtures/block.json' with { type: 'json' };
 
@@ -22,7 +23,7 @@ describe('Block', () => {
             it('returns ' + f.expected + ' for 0x' + f.bits, () => {
                 const bits = parseInt(f.bits, 16);
 
-                assert.strictEqual(Block.calculateTarget(bits).toString('hex'), f.expected);
+                assert.strictEqual(toHex(Block.calculateTarget(bits)), f.expected);
             });
         });
     });
@@ -33,10 +34,10 @@ describe('Block', () => {
                 const block = Block.fromHex(f.hex);
 
                 assert.strictEqual(block.version, f.version);
-                assert.strictEqual(block.prevHash!.toString('hex'), f.prevHash);
-                assert.strictEqual(block.merkleRoot!.toString('hex'), f.merkleRoot);
+                assert.strictEqual(toHex(block.prevHash!), f.prevHash);
+                assert.strictEqual(toHex(block.merkleRoot!), f.merkleRoot);
                 if (block.witnessCommit) {
-                    assert.strictEqual(block.witnessCommit.toString('hex'), f.witnessCommit);
+                    assert.strictEqual(toHex(block.witnessCommit), f.witnessCommit);
                 }
                 assert.strictEqual(block.timestamp, f.timestamp);
                 assert.strictEqual(block.bits, f.bits);
@@ -83,7 +84,7 @@ describe('Block', () => {
             });
 
             it('returns ' + f.id + ' for ' + f.description, () => {
-                assert.strictEqual(block.getHash().toString('hex'), f.hash);
+                assert.strictEqual(toHex(block.getHash()), f.hash);
                 assert.strictEqual(block.getId(), f.id);
             });
         });
@@ -123,7 +124,7 @@ describe('Block', () => {
 
             it('returns ' + f.merkleRoot + ' for ' + f.id, () => {
                 assert.strictEqual(
-                    Block.calculateMerkleRoot(block.transactions!).toString('hex'),
+                    toHex(Block.calculateMerkleRoot(block.transactions!)),
                     f.merkleRoot,
                 );
             });
@@ -131,7 +132,7 @@ describe('Block', () => {
             if (f.witnessCommit) {
                 it('returns witness commit ' + f.witnessCommit + ' for ' + f.id, () => {
                     assert.strictEqual(
-                        Block.calculateMerkleRoot(block.transactions!, true).toString('hex'),
+                        toHex(Block.calculateMerkleRoot(block.transactions!, true)),
                         f.witnessCommit,
                     );
                 });