@btc-vision/bitcoin 7.0.0-alpha.3 → 7.0.0-alpha.5

package/README.md

@@ -43,13 +43,25 @@ Requires Node.js >= 24.0.0.
 ### Initialize the ECC Library
 
 The ECC library must be initialized before using Taproot, signing, or any elliptic curve operations.
+Two backends are available:
+
+**Noble (recommended for browsers)** -- pure JS, no WASM dependency:
+
+```typescript
+import { initEccLib } from '@btc-vision/bitcoin';
+import { createNobleBackend } from '@btc-vision/ecpair';
+
+initEccLib(createNobleBackend());
+```
+
+**tiny-secp256k1** -- WASM-based, faster in Node.js:
 
 ```typescript
 import { initEccLib } from '@btc-vision/bitcoin';
-import type { EccLib } from '@btc-vision/bitcoin';
-import * as ecc from 'tiny-secp256k1';
+import { createLegacyBackend } from '@btc-vision/ecpair';
+import * as tinysecp from 'tiny-secp256k1';
 
-initEccLib(ecc as unknown as EccLib);
+initEccLib(createLegacyBackend(tinysecp));
 ```
 
 ### Create a Key Pair
@@ -172,15 +184,56 @@ const bech32Addr = address.toBech32(decoded.data, decoded.version, 'bc');
 
 ### Parallel Signing with Workers
 
-For high-throughput signing across many inputs, use the worker pool:
+For high-throughput signing across many inputs, use the worker pool.
+
+#### Sign a PSBT in parallel
+
+`signPsbtParallel` analyzes inputs, distributes signing across workers, and applies signatures back to the PSBT:
 
 ```typescript
-import { createSigningPool, SignatureType } from '@btc-vision/bitcoin/workers';
+import { Psbt, networks } from '@btc-vision/bitcoin';
+import { signPsbtParallel, createSigningPool } from '@btc-vision/bitcoin/workers';
 
 // Create a platform-appropriate pool (Node.js worker_threads or Web Workers)
 const pool = await createSigningPool({ workerCount: 4 });
 pool.preserveWorkers();
 
+// Build your PSBT as usual
+const psbt = new Psbt({ network: networks.bitcoin });
+psbt.addInput({ /* ... */ });
+psbt.addInput({ /* ... */ });
+psbt.addOutput({ /* ... */ });
+
+// Sign all signable inputs in parallel — replaces signAllInputs / signAllInputsAsync
+const result = await signPsbtParallel(psbt, keyPair, pool);
+
+if (result.success) {
+    console.log(`Signed ${result.signatures.size} inputs in ${result.durationMs}ms`);
+    psbt.finalizeAllInputs();
+    const tx = psbt.extractTransaction();
+}
+
+// Shut down when done (or keep the pool alive for future PSBTs)
+await pool.shutdown();
+```
+
+You can also pass a config object instead of a pool instance. A temporary pool will be created and
+destroyed automatically:
+
+```typescript
+const result = await signPsbtParallel(psbt, keyPair, { workerCount: 4 });
+```
+
+#### Low-level batch signing
+
+For manual control over sighash computation and task construction:
+
+```typescript
+import { createSigningPool, SignatureType } from '@btc-vision/bitcoin/workers';
+
+const pool = await createSigningPool({ workerCount: 4 });
+pool.preserveWorkers();
+
 const tasks = [
     {
         taskId: 'input-0',
@@ -203,10 +256,6 @@ if (result.success) {
     console.log(`Signed ${result.signatures.size} inputs in ${result.durationMs}ms`);
 }
 
-// Or sign a PSBT directly in parallel
-import { signPsbtParallel } from '@btc-vision/bitcoin/workers';
-await signPsbtParallel(psbt, keyPair, pool);
-
 await pool.shutdown();
 ```
 
@@ -340,10 +389,88 @@ const t = taggedHash('TapLeaf', data); // BIP340 tagged hash
 
 The library ships with a browser-optimized build via the `browser` conditional export. Bundlers that support the `exports` field in `package.json` (Vite, Webpack 5+, esbuild) will automatically resolve to the browser build.
 
-For Taproot operations in the browser, `tiny-secp256k1` relies on WebAssembly. If WASM is unavailable, consider these alternatives:
+For browser environments, use `createNobleBackend()` -- it is pure JavaScript with no WASM dependency. The `tiny-secp256k1` backend requires WebAssembly support and is better suited for Node.js.
+
+## React Native
+
+The library works in React Native with Hermes 0.76+ (BigInt and `crypto.getRandomValues()` required). The core library (PSBT, transactions, addresses, crypto) is pure JS and runs on the main thread. Parallel signing uses `react-native-worklets` when available, otherwise falls back to sequential execution automatically.
+
+### Metro Configuration
+
+Add `react-native` to the condition names in your `metro.config.js`:
+
+```javascript
+const config = {
+    resolver: {
+        unstable_conditionNames: ['react-native', 'import', 'default'],
+    },
+};
+```
+
+### Usage
+
+Usage is identical to Node.js and browsers:
+
+```typescript
+import { initEccLib, Psbt, networks } from '@btc-vision/bitcoin';
+import { createNobleBackend, ECPairSigner } from '@btc-vision/ecpair';
+
+// Initialize ECC (pure JS Noble backend — no WASM needed)
+const backend = createNobleBackend();
+initEccLib(backend);
+
+// Create key pair, build PSBT, sign — same API as Node.js/browser
+const keyPair = ECPairSigner.fromWIF(backend, wif, networks.bitcoin);
+const psbt = new Psbt({ network: networks.bitcoin });
+// ... add inputs/outputs ...
+psbt.signAllInputs(keyPair);
+```
+
+### Parallel Signing
+
+`signPsbtParallel()` and `createSigningPool()` support true parallel signing in React Native via [`react-native-worklets`](https://github.com/margelo/react-native-worklets) (Software Mansion, v0.7+). Each worklet runtime gets its own ECC module instance and signing tasks are distributed round-robin across runtimes.
+
+Install the optional peer dependency to enable parallel signing:
+
+```bash
+npm install react-native-worklets
+```
+
+Usage is identical to Node.js/browser — `createSigningPool()` detects worklets automatically:
+
+```typescript
+import { signPsbtParallel, createSigningPool } from '@btc-vision/bitcoin/workers';
+
+// Automatically uses WorkletSigningPool if react-native-worklets is installed,
+// otherwise falls back to SequentialSigningPool (main-thread, one-by-one)
+const pool = await createSigningPool({ workerCount: 4 });
+pool.preserveWorkers();
+
+const result = await signPsbtParallel(psbt, keyPair, pool);
+await pool.shutdown();
+```
+
+You can also import `WorkletSigningPool` directly for explicit control:
+
+```typescript
+import { WorkletSigningPool } from '@btc-vision/bitcoin/workers';
+
+const pool = WorkletSigningPool.getInstance({ workerCount: 4 });
+pool.preserveWorkers();
+await pool.initialize();
+
+const result = await pool.signBatch(tasks, keyPair);
+await pool.shutdown();
+```
+
+If `react-native-worklets` is not installed, `createSigningPool()` returns a `SequentialSigningPool` that signs inputs one-by-one on the main thread using the same API.
+
+### Requirements
 
-- **`@bitcoinjs-lib/tiny-secp256k1-asmjs`** -- ASM.js fallback (slower)
-- **`@bitcoinerlab/secp256k1`** -- Pure JS with `BigInt` (requires `BigInt` support)
+- **Hermes 0.76+** (React Native 0.76+) for BigInt and `crypto.getRandomValues()` support
+- **`react-native-worklets` >= 0.7.0** (optional) for parallel signing across worklet runtimes
+- `react-native-quick-crypto` is **not** required — the core library uses `@noble/hashes` and `@noble/curves` (pure JS)
+- A future `@btc-vision/react-native-secp256k1` Nitro Module would provide native C++ performance via `initEccLib(createNativeBackend())`
 
 ## Running Tests