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

package/build/workers/WorkerSigningPool.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Worker-based parallel signing pool.
+ *
+ * Provides secure parallel signature computation using worker threads.
+ * Private keys are isolated per-worker and zeroed immediately after signing.
+ *
+ * SECURITY ARCHITECTURE:
+ * - Keys are NEVER shared via SharedArrayBuffer
+ * - Each key is cloned to ONE worker via postMessage
+ * - Keys are zeroed in worker immediately after signing
+ * - Workers can be preserved for performance or terminated for security
+ *
+ * @example
+ * ```typescript
+ * import { WorkerSigningPool } from '@btc-vision/bitcoin';
+ *
+ * // Get singleton pool instance
+ * const pool = WorkerSigningPool.getInstance();
+ *
+ * // Preserve workers for multiple signing operations (faster)
+ * pool.preserveWorkers();
+ *
+ * // Sign multiple inputs in parallel
+ * const result = await pool.signBatch(tasks, keyPair);
+ *
+ * // Shutdown when done (optional - cleans up workers)
+ * await pool.shutdown();
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { WorkerPoolConfig, SigningTask, ParallelSignerKeyPair, ParallelSigningResult } from './types.js';
+/**
+ * Worker-based parallel signing pool.
+ *
+ * Manages a pool of worker threads for parallel signature computation.
+ * Provides secure key handling with immediate zeroing after use.
+ *
+ * @example
+ * ```typescript
+ * // Initialize pool at app startup
+ * const pool = WorkerSigningPool.getInstance({ workerCount: 4 });
+ * pool.preserveWorkers();
+ *
+ * // Use for PSBT signing
+ * const tasks = prepareSigningTasks(psbt, keyPair);
+ * const result = await pool.signBatch(tasks, keyPair);
+ *
+ * // Apply signatures to PSBT
+ * applySignatures(psbt, result.signatures);
+ * ```
+ */
+export declare class WorkerSigningPool {
+    #private;
+    /**
+     * Creates a new WorkerSigningPool.
+     *
+     * @param config - Pool configuration
+     */
+    private constructor();
+    /**
+     * Gets the singleton pool instance.
+     *
+     * @param config - Optional configuration (only used on first call)
+     * @returns The singleton pool instance
+     *
+     * @example
+     * ```typescript
+     * const pool = WorkerSigningPool.getInstance({ workerCount: 8 });
+     * ```
+     */
+    static getInstance(config?: WorkerPoolConfig): WorkerSigningPool;
+    /**
+     * Resets the singleton instance (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Number of workers in the pool.
+     */
+    get workerCount(): number;
+    /**
+     * Number of idle workers available.
+     */
+    get idleWorkerCount(): number;
+    /**
+     * Number of busy workers.
+     */
+    get busyWorkerCount(): number;
+    /**
+     * Whether workers are being preserved between batches.
+     */
+    get isPreservingWorkers(): boolean;
+    /**
+     * Enables worker preservation between signing batches.
+     *
+     * When enabled, workers remain alive after completing a batch,
+     * ready for the next signing operation. This is faster but
+     * keeps workers in memory.
+     *
+     * Call shutdown() when done to terminate all workers.
+     *
+     * @example
+     * ```typescript
+     * const pool = WorkerSigningPool.getInstance();
+     * pool.preserveWorkers(); // Enable at app startup
+     *
+     * // ... do many signing operations ...
+     *
+     * await pool.shutdown(); // Cleanup at app shutdown
+     * ```
+     */
+    preserveWorkers(): void;
+    /**
+     * Disables worker preservation.
+     *
+     * Workers will be terminated after each signing batch.
+     * More secure (no persistent workers) but slower for multiple batches.
+     */
+    releaseWorkers(): void;
+    /**
+     * Initializes the worker pool.
+     *
+     * Creates workers and waits for them to be ready.
+     * Called automatically on first signBatch() if not called manually.
+     *
+     * @returns Promise that resolves when all workers are ready
+     */
+    initialize(): Promise<void>;
+    /**
+     * Signs a batch of tasks in parallel.
+     *
+     * SECURITY: Private keys are obtained via keyPair.getPrivateKey() and
+     * cloned to workers. Keys are zeroed in workers immediately after signing.
+     *
+     * Tasks are distributed across workers and processed in batches for efficiency.
+     *
+     * @param tasks - Signing tasks (hashes, input indices, etc.)
+     * @param keyPair - Key pair with getPrivateKey() method
+     * @returns Promise resolving to signing results
+     *
+     * @example
+     * ```typescript
+     * const tasks: SigningTask[] = [
+     *     { taskId: '1', inputIndex: 0, hash: hash0, signatureType: SignatureType.ECDSA, sighashType: 0x01 },
+     *     { taskId: '2', inputIndex: 1, hash: hash1, signatureType: SignatureType.Schnorr, sighashType: 0x00 },
+     * ];
+     *
+     * const result = await pool.signBatch(tasks, keyPair);
+     *
+     * if (result.success) {
+     *     for (const [inputIndex, sig] of result.signatures) {
+     *         console.log(`Input ${inputIndex}: ${sig.signature}`);
+     *     }
+     * }
+     * ```
+     */
+    signBatch(tasks: readonly SigningTask[], keyPair: ParallelSignerKeyPair): Promise<ParallelSigningResult>;
+    /**
+     * Shuts down the pool and terminates all workers.
+     *
+     * Call this when the application is done with signing operations.
+     *
+     * @returns Promise that resolves when all workers are terminated
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Convenience function to get the singleton pool instance.
+ *
+ * @param config - Optional configuration
+ * @returns The singleton pool instance
+ */
+export declare function getSigningPool(config?: WorkerPoolConfig): WorkerSigningPool;
+//# sourceMappingURL=WorkerSigningPool.d.ts.map

package/build/workers/WorkerSigningPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerSigningPool.d.ts","sourceRoot":"","sources":["../../src/workers/WorkerSigningPool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACR,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,qBAAqB,EAOxB,MAAM,YAAY,CAAC;AA6BpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAiB;;IAmD1B;;;;OAIG;IACH,OAAO;IAKP;;;;;;;;;;OAUG;WACW,WAAW,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,iBAAiB;IAOvE;;OAEG;WACW,aAAa,IAAI,IAAI;IAOnC;;OAEG;IACH,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;OAEG;IACH,IAAW,eAAe,IAAI,MAAM,CAEnC;IAED;;OAEG;IACH,IAAW,eAAe,IAAI,MAAM,CAEnC;IAED;;OAEG;IACH,IAAW,mBAAmB,IAAI,OAAO,CAExC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACI,eAAe,IAAI,IAAI;IAI9B;;;;;OAKG;IACI,cAAc,IAAI,IAAI;IAI7B;;;;;;;OAOG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBxC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACU,SAAS,CAClB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,EAAE,qBAAqB,GAC/B,OAAO,CAAC,qBAAqB,CAAC;IA4FjC;;;;;;OAMG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAiQzC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,iBAAiB,CAE3E"}