@btc-vision/bitcoin 7.0.0-alpha.9 → 7.0.0-beta.1

package/README.md

@@ -1,5 +1,8 @@
 # @btc-vision/bitcoin
 
+> **Experimental Feature: P2MR (Pay-to-Merkle-Root, BIP 360)**
+> This library includes experimental support for P2MR, a SegWit version 2 output type that enables script-path-only spending from a bare Merkle root. P2MR addresses start with `bc1z`. See the [P2MR section](#p2mr-pay-to-merkle-root-bip-360) below for usage details. This feature is subject to change as BIP 360 is still a draft proposal.
+
 ![Bitcoin](https://img.shields.io/badge/Bitcoin-000?style=for-the-badge&logo=bitcoin&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
 ![NodeJS](https://img.shields.io/badge/Node%20js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
@@ -38,6 +41,28 @@ npm install tiny-secp256k1
 
 Requires Node.js >= 24.0.0.
 
+## Performance
+
+Benchmarked against `bitcoinjs-lib` v7.0.1 and `@scure/btc-signer` on Node.js v25.6.0 (Linux x64). The fork column uses the fastest backend for each scenario.
+
+| Operation | Inputs | @btc-vision/bitcoin | @scure/btc-signer | bitcoinjs-lib | Fork vs Official |
+|-----------|-------:|--------------------:|------------------:|--------------:|:----------------:|
+| PSBT Creation | 100 | 2.08ms | 2.60ms | 303ms | **145x** |
+| PSBT Creation | 500 | 9.73ms | 11.07ms | 6,870ms | **706x** |
+| P2WPKH Sign | 100 | 40ms | 124ms | 348ms | **8.7x** |
+| P2WPKH Sign | 500 | 283ms | 1,200ms | 7,250ms | **25.6x** |
+| P2TR Sign | 100 | 21ms | 420ms | 44ms | **2.1x** |
+| P2TR Sign | 500 | 102ms | 3,290ms | 522ms | **5.1x** |
+| E2E P2WPKH | 100 | 41ms | 125ms | 342ms | **8.3x** |
+| E2E P2TR | 100 | 22ms | 431ms | 55ms | **2.6x** |
+| Parallel Sign (4 workers) | 500 | 102ms | N/A | 6,470ms | **63.3x** |
+
+Parallel signing via `worker_threads` / Web Workers is exclusive to this fork. See [benchmark-compare/BENCHMARK.md](benchmark-compare/BENCHMARK.md) for detailed methodology, three-way analysis, and ECC backend comparison.
+
+```bash
+cd benchmark-compare && npm install && npm run bench
+```
+
 ## Quick Start
 
 ### Initialize the ECC Library
@@ -320,6 +345,7 @@ import { toBytes32, toBytes20, toSatoshi } from '@btc-vision/bitcoin';
 | P2WPKH | `p2wpkh()` | `P2WPKH` | SegWit v0 Public Key Hash |
 | P2WSH | `p2wsh()` | `P2WSH` | SegWit v0 Script Hash |
 | P2TR | `p2tr()` | `P2TR` | Taproot (SegWit v1) |
+| P2MR | `p2mr()` | `P2MR` | Pay-to-Merkle-Root (SegWit v2, BIP 360) |
 | P2OP | `p2op()` | `P2OP` | OPNet (SegWit v16) |
 | Embed | `p2data()` | `Embed` | OP_RETURN data |
 
@@ -472,6 +498,101 @@ If `react-native-worklets` is not installed, `createSigningPool()` returns a `Se
 - `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())`
 
+## P2MR (Pay-to-Merkle-Root, BIP 360)
+
+P2MR is a SegWit version 2 output type defined in [BIP 360](https://github.com/nicbn/bips/blob/bip-p2mr/bip-0360.mediawiki). It commits to a bare Merkle root with no internal public key, providing script-path-only spending. This makes P2MR outputs resistant to quantum long-exposure attacks since no public key is revealed until spend time.
+
+**Key differences from P2TR (Taproot):**
+
+| | P2TR (v1) | P2MR (v2) |
+|---|---|---|
+| Address prefix | `bc1p` | `bc1z` |
+| ScriptPubKey | `OP_1 <32-byte tweaked_pubkey>` | `OP_2 <32-byte merkle_root>` |
+| Key-path spend | Yes | No |
+| Script-path spend | Yes | Yes |
+| Control block | `[1 + 32 + 32*m]` bytes (includes internal pubkey) | `[1 + 32*m]` bytes (no pubkey) |
+| Parity bit | 0 or 1 | Always 1 |
+| Sighash | BIP 342 | BIP 342 (same) |
+
+### Create a P2MR Output
+
+```typescript
+import { payments } from '@btc-vision/bitcoin';
+
+// From a script tree (single leaf)
+const p2mr = payments.p2mr({
+    scriptTree: { output: leafScript },
+});
+console.log(p2mr.address);  // bc1z...
+console.log(p2mr.output);   // OP_2 <merkle_root>
+console.log(p2mr.hash);     // raw merkle root bytes
+
+// From a multi-leaf script tree
+const p2mrMulti = payments.p2mr({
+    scriptTree: [
+        { output: leafA },
+        { output: leafB },
+    ],
+});
+
+// From a known address or hash
+const fromAddr = payments.p2mr({
+    address: 'bc1z4rf73uru6qdyrv9w3nq9f3dwqlqmec4sdwj03hexu7n7r7dkehjs592djq',
+});
+```
+
+### Spend a P2MR Output (PSBT)
+
+P2MR spending uses the same PSBT taproot signing flow. The library automatically detects P2MR inputs and routes them to script-path finalization.
+
+```typescript
+import {
+    Psbt, payments, initEccLib,
+    LEAF_VERSION_TAPSCRIPT, tapleafHash,
+} from '@btc-vision/bitcoin';
+import type { EccLib, Satoshi, Script } from '@btc-vision/bitcoin';
+
+// ECC must be initialized before signing (see Quick Start above)
+initEccLib(ecc as EccLib);
+
+// Build the P2MR payment with a redeem script to get the witness/control block
+const scriptTree = { output: leafScript, version: LEAF_VERSION_TAPSCRIPT };
+const p2mr = payments.p2mr({
+    scriptTree,
+    redeem: { output: leafScript, redeemVersion: LEAF_VERSION_TAPSCRIPT },
+});
+
+const psbt = new Psbt();
+
+// Add the P2MR input with taproot-style fields
+psbt.addInput({
+    hash: txid,
+    index: vout,
+    witnessUtxo: {
+        value: amount as Satoshi,
+        script: p2mr.output as Script,
+    },
+    tapLeafScript: [{
+        leafVersion: LEAF_VERSION_TAPSCRIPT,
+        script: leafScript,
+        controlBlock: p2mr.witness![1]!, // control block (second witness element)
+    }],
+    tapMerkleRoot: p2mr.hash as Uint8Array,
+});
+
+psbt.addOutput({ address: destinationAddress, value: outputAmount as Satoshi });
+
+// Sign using the leaf hash
+const leafHash = tapleafHash({ output: leafScript, version: LEAF_VERSION_TAPSCRIPT });
+psbt.signTaprootInput(0, keyPair, leafHash);
+
+// Finalize and extract — P2MR always uses script-path finalization
+psbt.finalizeInput(0);
+const tx = psbt.extractTransaction();
+```
+
+The final witness stack for a P2MR script-path spend is: `[signatures...] [leaf_script] [control_block]`, where the control block is `[leafVersion | 0x01, merkle_path...]` (no internal pubkey).
+
 ## Running Tests
 
 ```bash

package/benchmark-compare/BENCHMARK.md

@@ -0,0 +1,159 @@
+# Benchmark: @btc-vision/bitcoin vs bitcoinjs-lib vs @scure/btc-signer
+
+Comprehensive performance comparison between `@btc-vision/bitcoin` (this fork), the official `bitcoinjs-lib` v7.0.1, and `@scure/btc-signer`.
+
+## Environment
+
+| Property | Value |
+|----------|-------|
+| Node.js | v25.6.0 |
+| OS | Linux 6.8.0-100-generic x64 |
+| Libraries | `@btc-vision/bitcoin` 7.0.0-rc.1, `bitcoinjs-lib` 7.0.1, `@scure/btc-signer` latest |
+| ECC backends | `@noble/secp256k1` 3.x (pure JS), `tiny-secp256k1` 2.2.4 (WASM), `@noble/curves` (scure built-in) |
+
+## Methodology
+
+- **Warmup**: 5 iterations (discarded) before each measurement
+- **Iterations**: 30 for small inputs, 10 for 250 inputs, 5 for 500 inputs
+- **Metric**: Median of all iterations (resistant to outlier spikes)
+- **Fairness**: All libraries use identical key material derived from the same seed. Each scenario builds its own PSBTs/transactions with the correct types for each library.
+- **Cold-start**: Library initialization measured via separate Node.js subprocess per iteration for true cold-start timing.
+- **ECC backends**: The fork is tested with both Noble (pure JS) and tiny-secp256k1 (WASM). The official library only supports tiny-secp256k1. Scure uses its built-in `@noble/curves` backend.
+
+## Results
+
+### 1. Library Initialization (cold-start)
+
+| Configuration | Median |
+|--------------|--------|
+| Fork + Noble (pure JS) | 53.44ms |
+| Fork + tiny-secp256k1 (WASM) | 7.16ms |
+| Scure (@noble/curves) | 26.27ms |
+| Official + tiny-secp256k1 (WASM) | 7.16ms |
+
+Both the fork and official library have identical initialization time when using the same WASM backend. Scure sits in the middle at ~26ms due to its pure-JS `@noble/curves` dependency. The Noble backend is ~53ms due to pure-JS module loading, but eliminates the WASM dependency entirely -- critical for React Native and edge runtimes without WASM support.
+
+### 2. PSBT / Transaction Creation (addInput + addOutput)
+
+| Inputs | Fork | Scure | Official | Fork Speedup |
+|--------|------|-------|----------|:------------:|
+| 10 | 0.26ms | 0.58ms | 6.40ms | **24x** |
+| 50 | 1.09ms | 1.56ms | 83.80ms | **77x** |
+| 100 | 2.08ms | 2.60ms | 303.32ms | **145x** |
+| 250 | 4.96ms | 5.86ms | 1.73s | **349x** |
+| 500 | 9.73ms | 11.07ms | 6.87s | **706x** |
+
+The fork's PSBT creation scales linearly (O(n)). Scure's `Transaction` also scales linearly but is ~1.1-1.2x slower than the fork. The official library exhibits O(n^2) behavior -- each `addInput()` call triggers increasingly expensive internal validation passes over all existing inputs. At 500 inputs, the official library takes over **6.87 seconds** just to build the PSBT, while the fork completes in under **10 milliseconds** and scure in **11ms**.
+
+### 3. P2WPKH Signing (create + sign, SegWit v0)
+
+| Inputs | Fork (Noble) | Fork (tiny) | Scure | Official | Best Fork Speedup |
+|--------|-------------|-------------|-------|----------|:-----------------:|
+| 10 | 6.89ms | 4.04ms | 11.05ms | 9.36ms | **2.3x** |
+| 50 | 31.33ms | 19.52ms | 54.85ms | 101.59ms | **5.2x** |
+| 100 | 65.27ms | 39.96ms | 123.83ms | 348.15ms | **8.7x** |
+| 250 | 171.40ms | 110.99ms | 413.48ms | 1.89s | **17x** |
+| 500 | 378.57ms | 282.93ms | 1.20s | 7.25s | **25.6x** |
+
+This benchmark includes PSBT/transaction creation + signing. The fork's advantage compounds: faster PSBT construction plus efficient sighash caching. Scure is ~3x slower than the fork (tiny) but still ~6x faster than official at 500 inputs. With tiny-secp256k1, the fork's raw signing speed matches the official library, but the PSBT overhead dominates at scale.
+
+### 4. P2TR Taproot Signing (Schnorr, SegWit v1)
+
+| Inputs | Fork (Noble) | Fork (tiny) | Scure | Official | Best Fork Speedup |
+|--------|-------------|-------------|-------|----------|:-----------------:|
+| 10 | 22.55ms | 2.44ms | 39.17ms | 3.62ms | **1.5x** |
+| 50 | 105.59ms | 10.72ms | 197.94ms | 18.72ms | **1.7x** |
+| 100 | 211.00ms | 21.33ms | 420.13ms | 44.27ms | **2.1x** |
+| 250 | 520.22ms | 51.69ms | 1.24s | 171.77ms | **3.3x** |
+| 500 | 1.04s | 102.31ms | 3.29s | 521.88ms | **5.1x** |
+
+With tiny-secp256k1, the fork is consistently faster due to its O(n) Taproot sighash caching (the official library recomputes more per input). Scure is the slowest here at ~3.29s for 500 inputs, as its pure-JS Schnorr implementation carries significant per-signature overhead. Noble's pure-JS Schnorr is also slower than WASM for raw signing, which shows at small input counts, but the fork's architectural advantages compound at scale.
+
+### 5. End-to-End Lifecycle (100 inputs)
+
+Full lifecycle: create PSBT/tx + add inputs/outputs + sign + finalize + extract + serialize.
+
+| Type | Fork (Noble) | Fork (tiny) | Scure | Official | Best Fork Speedup |
+|------|-------------|-------------|-------|----------|:-----------------:|
+| P2WPKH | 66.62ms | 41.13ms | 125.32ms | 341.76ms | **8.3x** |
+| P2TR | 210.98ms | 21.60ms | 431.07ms | 55.12ms | **2.6x** |
+
+P2WPKH end-to-end is **8.3x faster** with the fork (tiny-secp256k1 backend). Scure is ~3x slower than the fork but still ~2.7x faster than official for P2WPKH. For P2TR, the fork with tiny-secp256k1 is **2.6x faster** than official. Scure's pure-JS Schnorr signing makes it the slowest for Taproot at 431ms vs 22ms (fork tiny) and 55ms (official).
+
+### 6. Parallel Signing (fork-exclusive)
+
+Worker-based parallel signing using `NodeWorkerSigningPool` with 4 `worker_threads`.
+
+| Inputs | Fork Sequential | Fork Parallel (4w) | Official Sequential | Speedup vs Seq | Speedup vs Official |
+|--------|----------------|-------------------|--------------------|----|------|
+| 100 | 64.27ms | 21.73ms | 310.42ms | 3.0x | **14.3x** |
+| 500 | 380.27ms | 102.25ms | 6.47s | 3.7x | **63.3x** |
+
+Parallel signing is **exclusive to the fork**. At 500 inputs, parallel signing completes in 102ms vs the official library's 6.47s sequential signing -- a **63.3x improvement**.
+
+## Scure vs Official vs Fork
+
+`@scure/btc-signer` sits between the fork and official library in most scenarios:
+
+**Where Scure beats Official:**
+- Transaction creation is O(n) like the fork, making it dramatically faster than official's O(n^2) PSBT creation at scale (11ms vs 6.87s at 500 inputs)
+- P2WPKH signing is ~6x faster than official at 500 inputs, though ~4x slower than the fork
+
+**Where Scure is slowest:**
+- P2TR (Taproot) signing is the weakest spot -- 3.29s for 500 inputs vs 102ms (fork tiny) and 522ms (official). Its pure-JS Schnorr implementation has significant per-signature overhead
+- No parallel signing support
+
+**Bottom line:** Scure is a solid zero-dependency pure-JS option that avoids official's O(n^2) PSBT creation bottleneck, but its signing performance (especially Taproot) falls behind both the fork and official library.
+
+## The tiny-secp256k1 Reality
+
+A common assumption is that `tiny-secp256k1` (WASM) is always faster. The raw signing numbers tell a nuanced story:
+
+**Where WASM wins:**
+- Raw Schnorr signing throughput is ~2x faster per operation than Noble's pure JS implementation
+- For P2TR-heavy workloads with few inputs, the per-signature difference matters
+
+**Where it doesn't matter:**
+- The PSBT construction overhead completely dominates at scale. The official library's O(n^2) behavior means PSBT creation alone takes 6.87s at 500 inputs vs 10ms in the fork -- a difference so large that the choice of signing backend is irrelevant
+- P2WPKH signing with Noble is only ~1.5x slower per operation than WASM, and the fork's PSBT improvements more than compensate
+
+**Where WASM is a liability:**
+- ~1.2MB WASM binary added to bundle size vs ~12KB for Noble
+- WASM initialization requires WebAssembly support -- unavailable in some React Native runtimes and edge environments
+- Cold-start adds measurable overhead in serverless / Lambda contexts
+
+**Bottom line:** The fork with Noble (pure JS) outperforms the official library with WASM for all real-world P2WPKH workloads. For P2TR-heavy workloads, the fork with tiny-secp256k1 is the fastest option and still outperforms both the official library and scure. The Noble backend provides portability across Node.js, browsers, and React Native with no WASM dependency.
+
+## Summary
+
+| Scenario | Inputs | @btc-vision/bitcoin | @scure/btc-signer | bitcoinjs-lib | Fork vs Official |
+|----------|--------|--------------------:|------------------:|--------------:|:----------------:|
+| PSBT Creation | 100 | 2.08ms | 2.60ms | 303ms | **145x** |
+| PSBT Creation | 500 | 9.73ms | 11.07ms | 6,870ms | **706x** |
+| P2WPKH Sign | 100 | 40ms | 124ms | 348ms | **8.7x** |
+| P2WPKH Sign | 500 | 283ms | 1,200ms | 7,250ms | **25.6x** |
+| P2TR Sign | 100 | 21ms | 420ms | 44ms | **2.1x** |
+| P2TR Sign | 500 | 102ms | 3,290ms | 522ms | **5.1x** |
+| E2E P2WPKH | 100 | 41ms | 125ms | 342ms | **8.3x** |
+| E2E P2TR | 100 | 22ms | 431ms | 55ms | **2.6x** |
+| Parallel (4w) | 500 | 102ms | N/A | 6,470ms | **63.3x** |
+
+## How to Reproduce
+
+```bash
+cd benchmark-compare
+npm install
+npm run bench
+
+# With GC control (recommended for stable results):
+npm run bench:gc
+```
+
+The benchmark requires the parent project to be built first:
+
+```bash
+cd ..
+npm run build
+cd benchmark-compare
+npm run bench
+```