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

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Status             |
+|---------|--------------------|
+| 6.x     | Supported          |
+| < 6.0   | Not supported      |
+
+## Reporting a Vulnerability
+
+**DO NOT** open a public GitHub issue for security vulnerabilities.
+
+Report vulnerabilities through [GitHub Security Advisories](https://github.com/btc-vision/bitcoin/security/advisories/new).
+
+Include:
+- Description of the vulnerability
+- Affected version(s)
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+## Contact
+
+- **Security Issues**: [GitHub Security Advisories](https://github.com/btc-vision/bitcoin/security/advisories)
+- **General Issues**: [GitHub Issues](https://github.com/btc-vision/bitcoin/issues)
+- **Website**: [opnet.org](https://opnet.org)

package/benchmark/psbt-2000-inputs.bench.ts

@@ -0,0 +1,178 @@
+/**
+ * PSBT 2000 Input Benchmark - Tests Taproot signing performance
+ *
+ * This benchmark measures the O(n^2) -> O(n) optimization for Taproot signing.
+ *
+ * Run with: npx tsx benchmark/psbt-2000-inputs.bench.ts
+ */
+
+import * as ecc from 'tiny-secp256k1';
+import { randomBytes } from 'crypto';
+import { BIP32Factory } from '@btc-vision/bip32';
+import { initEccLib, Psbt, payments, crypto, Transaction } from '../src/index.js';
+import { toXOnly } from '../src/pubkey.js';
+
+// Initialize ECC library
+initEccLib(ecc);
+const bip32 = BIP32Factory(ecc);
+
+// Generate a test keypair for taproot key-path spending
+function generateTaprootKeyPair() {
+    const node = bip32.fromSeed(randomBytes(64));
+    const xOnlyPubkey = toXOnly(node.publicKey);
+
+    // Create tweaked signer for taproot key-path spending
+    const tweakedNode = node.tweak(crypto.taggedHash('TapTweak', xOnlyPubkey));
+
+    return {
+        xOnlyPubkey,
+        signer: tweakedNode,
+    };
+}
+
+// Create a fake previous transaction for nonWitnessUtxo
+function createFakePrevTx(outputScript: Uint8Array, value: bigint, index: number): Buffer {
+    const tx = new Transaction();
+    tx.version = 2;
+    const inputHash = Buffer.alloc(32);
+    inputHash.writeUInt32LE(index, 0);
+    tx.addInput(inputHash, 0);
+    tx.addOutput(outputScript, value);
+    return tx.toBuffer();
+}
+
+async function runBenchmark(inputCount: number, iterations: number = 5) {
+    console.log(`\n--- Benchmarking ${inputCount} P2TR inputs ---`);
+
+    const keyPair = generateTaprootKeyPair();
+
+    const { output } = payments.p2tr({
+        internalPubkey: keyPair.xOnlyPubkey,
+    });
+    if (!output) throw new Error('Failed to create P2TR output');
+
+    const inputValue = 10000n;
+    const totalInput = inputValue * BigInt(inputCount);
+    const fee = 1000n;
+    const outputValue = (totalInput - fee) / 5n;
+
+    console.log(`  Generating ${inputCount} fake previous transactions...`);
+    const setupStart = performance.now();
+
+    const prevTxs: Buffer[] = [];
+    const txIds: Buffer[] = [];
+    for (let i = 0; i < inputCount; i++) {
+        const prevTx = createFakePrevTx(output, inputValue, i);
+        prevTxs.push(prevTx);
+        const hash1 = crypto.sha256(prevTx);
+        const hash2 = crypto.sha256(hash1);
+        const txId = Buffer.from(hash2).reverse();
+        txIds.push(txId);
+    }
+
+    console.log(`  Setup done in ${((performance.now() - setupStart) / 1000).toFixed(2)}s`);
+
+    // Warmup
+    console.log('  Warming up...');
+    {
+        const psbt = new Psbt();
+        for (let i = 0; i < Math.min(100, inputCount); i++) {
+            psbt.addInput({
+                hash: txIds[i],
+                index: 0,
+                nonWitnessUtxo: prevTxs[i],
+                tapInternalKey: keyPair.xOnlyPubkey,
+            });
+        }
+        for (let i = 0; i < 5; i++) {
+            psbt.addOutput({ script: output, value: outputValue });
+        }
+        psbt.signAllInputs(keyPair.signer);
+    }
+
+    const times: number[] = [];
+
+    for (let iter = 0; iter < iterations; iter++) {
+        const psbt = new Psbt();
+
+        for (let i = 0; i < inputCount; i++) {
+            psbt.addInput({
+                hash: txIds[i],
+                index: 0,
+                nonWitnessUtxo: prevTxs[i],
+                tapInternalKey: keyPair.xOnlyPubkey,
+            });
+        }
+
+        for (let i = 0; i < 5; i++) {
+            psbt.addOutput({ script: output, value: outputValue });
+        }
+
+        const start = performance.now();
+        psbt.signAllInputs(keyPair.signer);
+        const elapsed = performance.now() - start;
+        times.push(elapsed);
+
+        console.log(`  Iteration ${iter + 1}: ${elapsed.toFixed(2)}ms`);
+    }
+
+    const avg = times.reduce((a, b) => a + b, 0) / times.length;
+    const min = Math.min(...times);
+    const max = Math.max(...times);
+
+    console.log(`\n  Results for ${inputCount} inputs:`);
+    console.log(`    Average: ${avg.toFixed(2)}ms`);
+    console.log(`    Min: ${min.toFixed(2)}ms`);
+    console.log(`    Max: ${max.toFixed(2)}ms`);
+    console.log(`    Per-input: ${(avg / inputCount).toFixed(4)}ms`);
+
+    return { inputCount, avg, min, max };
+}
+
+async function main() {
+    console.log('='.repeat(70));
+    console.log('  PSBT Taproot Signing Benchmark (prevOuts caching optimization)');
+    console.log('='.repeat(70));
+
+    const inputCounts = [100, 500, 1000, 2000];
+    const results: Array<{ inputCount: number; avg: number; min: number; max: number }> = [];
+
+    for (const count of inputCounts) {
+        const result = await runBenchmark(count, 3);
+        results.push(result);
+    }
+
+    console.log('\n' + '='.repeat(70));
+    console.log('  SUMMARY');
+    console.log('='.repeat(70));
+    console.log('\n  Inputs | Avg (ms) | Min (ms) | Max (ms) | Per-input (ms)');
+    console.log('  -------|----------|----------|----------|---------------');
+    for (const r of results) {
+        console.log(
+            `  ${String(r.inputCount).padStart(6)} | ${r.avg.toFixed(2).padStart(8)} | ${r.min.toFixed(2).padStart(8)} | ${r.max.toFixed(2).padStart(8)} | ${(r.avg / r.inputCount).toFixed(4).padStart(13)}`,
+        );
+    }
+
+    console.log('\n  Scaling Analysis:');
+    if (results.length >= 2) {
+        const first = results[0];
+        const last = results[results.length - 1];
+        const perInputFirst = first.avg / first.inputCount;
+        const perInputLast = last.avg / last.inputCount;
+        const ratio = perInputLast / perInputFirst;
+
+        console.log(`    Per-input time at ${first.inputCount} inputs: ${perInputFirst.toFixed(4)}ms`);
+        console.log(`    Per-input time at ${last.inputCount} inputs: ${perInputLast.toFixed(4)}ms`);
+        console.log(`    Ratio: ${ratio.toFixed(2)}x`);
+
+        if (ratio < 2) {
+            console.log('    Result: O(n) scaling achieved!');
+        } else {
+            console.log('    Result: Scaling is worse than O(n).');
+        }
+    }
+
+    console.log();
+}
+
+main().catch(console.error);

package/benchmark/signing.bench.ts

@@ -0,0 +1,147 @@
+/**
+ * Standalone Worker Signing Benchmark
+ *
+ * Run with: npx tsx benchmark/signing.bench.ts
+ */
+
+import * as ecc from 'tiny-secp256k1';
+import { randomBytes } from 'crypto';
+import { initEccLib } from '../src/ecc/context.js';
+import { SignatureType, type SigningTask } from '../src/workers/types.js';
+
+// Initialize ECC
+initEccLib(ecc);
+
+// Test key pair
+const TEST_PRIVATE_KEY = randomBytes(32);
+const TEST_PUBLIC_KEY = ecc.pointFromScalar(TEST_PRIVATE_KEY, true)!;
+
+const signer = {
+    publicKey: TEST_PUBLIC_KEY,
+    sign: (hash: Uint8Array) => ecc.sign(hash, TEST_PRIVATE_KEY),
+    getPrivateKey: () => new Uint8Array(TEST_PRIVATE_KEY),
+};
+
+async function main() {
+    console.log('='.repeat(70));
+    console.log('  WORKER SIGNING BENCHMARK');
+    console.log('='.repeat(70));
+    console.log();
+
+    const inputCounts = [4, 8, 16, 32, 64, 100, 200, 2000];
+    const iterations = 50;
+
+    // Pre-generate ALL hashes upfront (just random 32-byte arrays)
+    console.log('Generating test hashes...');
+    const setupStart = performance.now();
+
+    const allTasks: Map<number, SigningTask[][]> = new Map();
+    for (const inputCount of inputCounts) {
+        const iters = inputCount >= 2000 ? 10 : iterations;
+        const tasksForCount: SigningTask[][] = [];
+
+        for (let i = 0; i < iters + 5; i++) {
+            const tasks: SigningTask[] = [];
+            for (let j = 0; j < inputCount; j++) {
+                tasks.push({
+                    taskId: `task-${i}-${j}`,
+                    inputIndex: j,
+                    hash: randomBytes(32),
+                    signatureType: SignatureType.ECDSA,
+                    sighashType: 0x01,
+                });
+            }
+            tasksForCount.push(tasks);
+        }
+        allTasks.set(inputCount, tasksForCount);
+    }
+
+    console.log(`Setup done in ${((performance.now() - setupStart) / 1000).toFixed(2)}s`);
+    console.log();
+
+    // Initialize worker pool
+    const { NodeWorkerSigningPool } = await import('../src/workers/WorkerSigningPool.node.js');
+    NodeWorkerSigningPool.resetInstance();
+    const pool = NodeWorkerSigningPool.getInstance({ workerCount: 4 });
+    await pool.initialize();
+    pool.preserveWorkers();
+
+    console.log(`Worker pool: ${pool.workerCount} workers`);
+    console.log(`Iterations: ${iterations} (10 for 2000 inputs)`);
+    console.log();
+
+    const results: Array<{
+        inputs: number;
+        seqAvg: number;
+        parAvg: number;
+        speedup: number;
+    }> = [];
+
+    for (const inputCount of inputCounts) {
+        console.log(`--- ${inputCount} Inputs ---`);
+
+        const testIterations = inputCount >= 2000 ? 10 : iterations;
+        const tasks = allTasks.get(inputCount)!;
+
+        // Warmup sequential
+        for (let i = 0; i < 5; i++) {
+            for (const task of tasks[i]) {
+                signer.sign(task.hash);
+            }
+        }
+
+        // Benchmark sequential
+        const seqTimes: number[] = [];
+        for (let i = 5; i < testIterations + 5; i++) {
+            const start = performance.now();
+            for (const task of tasks[i]) {
+                signer.sign(task.hash);
+            }
+            seqTimes.push(performance.now() - start);
+        }
+
+        // Warmup parallel
+        for (let i = 0; i < 5; i++) {
+            await pool.signBatch(tasks[i], signer);
+        }
+
+        // Benchmark parallel
+        const parTimes: number[] = [];
+        for (let i = 5; i < testIterations + 5; i++) {
+            const start = performance.now();
+            await pool.signBatch(tasks[i], signer);
+            parTimes.push(performance.now() - start);
+        }
+
+        const seqTotal = seqTimes.reduce((a, b) => a + b, 0);
+        const seqAvg = seqTotal / seqTimes.length;
+        const parTotal = parTimes.reduce((a, b) => a + b, 0);
+        const parAvg = parTotal / parTimes.length;
+        const speedup = seqAvg / parAvg;
+
+        console.log(`  Sequential: ${seqAvg.toFixed(2)}ms avg (total: ${(seqTotal / 1000).toFixed(2)}s)`);
+        console.log(`  Parallel:   ${parAvg.toFixed(2)}ms avg (total: ${(parTotal / 1000).toFixed(2)}s)`);
+        console.log(`  Speedup:    ${speedup.toFixed(2)}x`);
+        console.log();
+
+        results.push({ inputs: inputCount, seqAvg, parAvg, speedup });
+    }
+
+    await pool.shutdown();
+
+    // Summary
+    console.log('='.repeat(70));
+    console.log('  SUMMARY');
+    console.log('='.repeat(70));
+    console.log();
+    console.log('  Inputs | Sequential (avg) | Parallel (avg) | Speedup');
+    console.log('  -------|------------------|----------------|--------');
+    for (const r of results) {
+        console.log(
+            `  ${String(r.inputs).padStart(6)} | ${r.seqAvg.toFixed(2).padStart(14)}ms | ${r.parAvg.toFixed(2).padStart(12)}ms | ${r.speedup.toFixed(2).padStart(6)}x`,
+        );
+    }
+    console.log();
+}
+
+main().catch(console.error);

package/browser/address.d.ts

@@ -1,9 +1,13 @@
 import { fromBech32, Bech32Result } from './bech32utils.js';
 import { Network } from './networks.js';
+import { Bytes20 } from './types.js';
 export { fromBech32, type Bech32Result };
+/** base58check decode result */
 export interface Base58CheckResult {
-    hash: Buffer;
-    version: number;
+    /** address hash */
+    readonly hash: Bytes20;
+    /** address version: 0x00 for P2PKH, 0x05 for P2SH */
+    readonly version: number;
 }
 export declare const FUTURE_SEGWIT_MAX_SIZE: number;
 export declare const FUTURE_SEGWIT_MIN_SIZE: number;
@@ -12,11 +16,54 @@ export declare const FUTURE_MAX_VERSION: number;
 export declare const FUTURE_OPNET_VERSION: number;
 export declare const FUTURE_SEGWIT_MIN_VERSION: number;
 export declare const FUTURE_SEGWIT_VERSION_DIFF: number;
-export declare const isUnknownSegwitVersion: (output: Buffer) => boolean;
-export declare function toFutureOPNetAddress(output: Buffer, network: Network): string;
-export declare function _toFutureSegwitAddress(output: Buffer, network: Network): string;
+export declare const isUnknownSegwitVersion: (output: Uint8Array) => boolean;
+/**
+ * Encode a future Taproot-style segwit address (SegWit v2 - v16) using bech32m.
+ * Only for versions not yet assigned specific meanings (future use).
+ *
+ * @param output - Output script buffer containing the version and witness program
+ * @param network - Network object containing bech32 and optional bech32Opnet prefix
+ * @returns Bech32m-encoded future Taproot-style address
+ */
+export declare function toFutureOPNetAddress(output: Uint8Array, network: Network): string;
+export declare function _toFutureSegwitAddress(output: Uint8Array, network: Network): string;
+/**
+ * decode address with base58 specification,  return address version and address hash if valid
+ */
 export declare function fromBase58Check(address: string): Base58CheckResult;
-export declare function toBase58Check(hash: Buffer, version: number): string;
-export declare function toBech32(data: Buffer, version: number, prefix: string, prefixOpnet?: string): string;
-export declare function fromOutputScript(output: Buffer, network?: Network): string;
-export declare function toOutputScript(address: string, network?: Network): Buffer;
+/**
+ * encode address hash to base58 address with version
+ */
+export declare function toBase58Check(hash: Bytes20, version: number): string;
+/**
+ * encode address hash to bech32 address with version and prefix
+ */
+export declare function toBech32(data: Uint8Array, version: number, prefix: string, prefixOpnet?: string): string;
+/**
+ * decode address from output script with network, return address if matched
+ */
+export declare function fromOutputScript(output: Uint8Array, network?: Network): string;
+/**
+ * Options for toOutputScript function.
+ */
+export interface ToOutputScriptOptions {
+    /**
+     * Network to use for encoding. Defaults to bitcoin mainnet.
+     */
+    readonly network?: Network;
+    /**
+     * Optional callback for future segwit version warnings.
+     * If provided, called with FUTURE_SEGWIT_VERSION_WARNING when encoding
+     * to a future segwit version (v2-v15) address.
+     * If not provided, no warning is emitted.
+     */
+    readonly onFutureSegwitWarning?: (warning: string) => void;
+}
+/**
+ * Encodes address to output script with network, return output script if address matched.
+ * @param address - The address to encode
+ * @param networkOrOptions - Network or options object
+ * @returns The output script as Uint8Array
+ */
+export declare function toOutputScript(address: string, networkOrOptions?: Network | ToOutputScriptOptions): Uint8Array;
+//# sourceMappingURL=address.d.ts.map

package/browser/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAS7C,OAAO,EAA4C,KAAK,OAAO,EAAoC,MAAM,YAAY,CAAC;AAEtH,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,CAAC;AAEzC,gCAAgC;AAChC,MAAM,WAAW,iBAAiB;IAC9B,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,sBAAsB,EAAE,MAAW,CAAC;AACjD,eAAO,MAAM,sBAAsB,EAAE,MAAU,CAAC;AAChD,eAAO,MAAM,yBAAyB,EAAE,MAAW,CAAC;AACpD,eAAO,MAAM,kBAAkB,EAAE,MAAW,CAAC;AAC7C,eAAO,MAAM,oBAAoB,EAAE,MAAW,CAAC;AAC/C,eAAO,MAAM,yBAAyB,EAAE,MAAU,CAAC;AACnD,eAAO,MAAM,0BAA0B,EAAE,MAAa,CAAC;AAOvD,eAAO,MAAM,sBAAsB,GAAI,QAAQ,UAAU,KAAG,OAkB3D,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAoCjF;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAgBnF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAWlE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CASpE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACpB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GACrB,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CA2B9E;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,OAAO,GAAG,qBAAqB,GACnD,UAAU,CAuEZ"}

package/browser/bech32utils.d.ts

@@ -1,6 +1,14 @@
+/** bech32 decode result */
 export interface Bech32Result {
+    /** address version: 0x00 for P2WPKH、P2WSH, 0x01 for P2TR*/
     version: number;
+    /** address prefix: bc for P2WPKH、P2WSH、P2TR */
     prefix: string;
-    data: Buffer;
+    /** address data：20 bytes for P2WPKH, 32 bytes for P2WSH、P2TR */
+    data: Uint8Array;
 }
+/**
+ * decode address with bech32 specification,  return address version、address prefix and address data if valid
+ */
 export declare function fromBech32(address: string): Bech32Result;
+//# sourceMappingURL=bech32utils.d.ts.map

package/browser/bech32utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bech32utils.d.ts","sourceRoot":"","sources":["../src/bech32utils.ts"],"names":[],"mappings":"AAMA,2BAA2B;AAC3B,MAAM,WAAW,YAAY;IACzB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,IAAI,EAAE,UAAU,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAuBxD"}

package/browser/bip66.d.ts

@@ -1,6 +1,11 @@
-export declare function check(buffer: Buffer): boolean;
-export declare function decode(buffer: Buffer): {
-    r: Buffer;
-    s: Buffer;
-};
-export declare function encode(r: Buffer, s: Buffer): Buffer;
+/**
+ * DER-encoded signature components.
+ */
+export interface DerSignature {
+    readonly r: Uint8Array;
+    readonly s: Uint8Array;
+}
+export declare function check(buffer: Uint8Array): boolean;
+export declare function decode(buffer: Uint8Array): DerSignature;
+export declare function encode(r: Uint8Array, s: Uint8Array): Uint8Array;
+//# sourceMappingURL=bip66.d.ts.map

package/browser/bip66.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bip66.d.ts","sourceRoot":"","sources":["../src/bip66.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAC;IACvB,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED,wBAAgB,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAsBjD;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,CA6BvD;AAwBD,wBAAgB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAyB/D"}

package/browser/block.d.ts

@@ -1,29 +1,135 @@
 import { Transaction } from './transaction.js';
+import { Bytes32 } from './types.js';
+/**
+ * Represents a Bitcoin block with header fields and optional transactions.
+ *
+ * @example
+ * ```typescript
+ * import { Block, fromHex } from '@btc-vision/bitcoin';
+ *
+ * // Parse a block from hex
+ * const block = Block.fromHex('0100000000000000...');
+ *
+ * // Access block properties
+ * console.log(block.version);
+ * console.log(block.getId());
+ * console.log(block.timestamp);
+ *
+ * // Check proof of work
+ * if (block.checkProofOfWork()) {
+ *     console.log('Valid PoW');
+ * }
+ * ```
+ */
 export declare class Block {
+    #private;
+    /** Block version number */
     version: number;
-    prevHash?: Buffer;
-    merkleRoot?: Buffer;
+    /** Hash of the previous block (32 bytes) */
+    prevHash?: Bytes32;
+    /** Merkle root of the transactions (32 bytes) */
+    merkleRoot?: Bytes32;
+    /** Block timestamp (Unix time) */
     timestamp: number;
-    witnessCommit?: Buffer;
+    /** Witness commitment for SegWit blocks (32 bytes) */
+    witnessCommit?: Bytes32;
+    /** Compact representation of the target threshold */
     bits: number;
+    /** Nonce used for proof of work */
     nonce: number;
+    /** Array of transactions included in the block */
     transactions?: Transaction[];
-    static fromBuffer(buffer: Buffer): Block;
+    /**
+     * Parses a Block from a Uint8Array.
+     * @param buffer - The raw block data (minimum 80 bytes for header only)
+     * @returns Parsed Block instance
+     * @throws Error if buffer is too small
+     */
+    static fromBuffer(buffer: Uint8Array): Block;
+    /**
+     * Parses a Block from a hex string.
+     * @param hex - Hexadecimal representation of the block
+     * @returns Parsed Block instance
+     */
     static fromHex(hex: string): Block;
-    static calculateTarget(bits: number): Buffer;
-    static calculateMerkleRoot(transactions: Transaction[], forWitness?: boolean): Buffer;
-    getWitnessCommit(): Buffer | null;
+    /**
+     * Calculates the target threshold from the compact bits representation.
+     * @param bits - Compact bits value from block header
+     * @returns 32-byte target threshold
+     */
+    static calculateTarget(bits: number): Bytes32;
+    /**
+     * Calculates the merkle root for a list of transactions.
+     * @param transactions - Array of transactions
+     * @param forWitness - If true, calculate witness merkle root (for SegWit)
+     * @returns 32-byte merkle root hash
+     * @throws TypeError if transactions is empty or not an array
+     */
+    static calculateMerkleRoot(transactions: Transaction[], forWitness?: boolean): Bytes32;
+    /**
+     * Extracts the witness commitment from the coinbase transaction.
+     * @returns 32-byte witness commitment or null if not found
+     */
+    getWitnessCommit(): Bytes32 | null;
+    /**
+     * Checks if this block has a witness commitment.
+     * @returns True if the block has a witness commitment
+     */
     hasWitnessCommit(): boolean;
+    /**
+     * Checks if any transaction in this block has witness data.
+     * @returns True if any transaction has witness data
+     */
     hasWitness(): boolean;
+    /**
+     * Calculates the weight of this block.
+     * Weight = (base size * 3) + total size
+     * @returns Block weight in weight units
+     */
     weight(): number;
+    /**
+     * Calculates the serialized byte length of this block.
+     * @param headersOnly - If true, return only header size (80 bytes)
+     * @param allowWitness - If true, include witness data in calculation
+     * @returns Byte length of the serialized block
+     */
     byteLength(headersOnly?: boolean, allowWitness?: boolean): number;
-    getHash(): Buffer;
+    /**
+     * Computes the double-SHA256 hash of the block header.
+     * @returns 32-byte block hash
+     */
+    getHash(): Bytes32;
+    /**
+     * Returns the block ID (hash in reversed hex format, as displayed in block explorers).
+     * @returns Block ID as hex string
+     */
     getId(): string;
+    /**
+     * Converts the block timestamp to a Date object.
+     * @returns UTC date of the block
+     */
     getUTCDate(): Date;
-    toBuffer(headersOnly?: boolean): Buffer;
+    /**
+     * Serializes the block to a Uint8Array.
+     * @param headersOnly - If true, only serialize the 80-byte header
+     * @returns Serialized block data
+     */
+    toBuffer(headersOnly?: boolean): Uint8Array;
+    /**
+     * Serializes the block to a hex string.
+     * @param headersOnly - If true, only serialize the 80-byte header
+     * @returns Hex string representation of the block
+     */
     toHex(headersOnly?: boolean): string;
+    /**
+     * Validates the merkle root and witness commitment (if present).
+     * @returns True if the transaction roots are valid
+     */
     checkTxRoots(): boolean;
+    /**
+     * Validates that the block hash meets the target threshold (proof of work).
+     * @returns True if the block's proof of work is valid
+     */
     checkProofOfWork(): boolean;
-    private __checkMerkleRoot;
-    private __checkWitnessCommit;
 }
+//# sourceMappingURL=block.d.ts.map

package/browser/block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../src/block.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAO1C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,KAAK;;IACd,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAK;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAa;IAC/B,iDAAiD;IACjD,UAAU,CAAC,EAAE,OAAO,CAAa;IACjC,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAK;IACtB,sDAAsD;IACtD,aAAa,CAAC,EAAE,OAAO,CAAa;IACpC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAK;IACjB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAK;IAClB,kDAAkD;IAClD,YAAY,CAAC,EAAE,WAAW,EAAE,CAAa;IAEzC;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,KAAK;IAuC5C;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK;IAIlC;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAY7C;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CAAC,YAAY,EAAE,WAAW,EAAE,EAAE,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO;IAqBtF;;;OAGG;IACH,gBAAgB,IAAI,OAAO,GAAG,IAAI;IAkBlC;;;OAGG;IACH,gBAAgB,IAAI,OAAO;IAO3B;;;OAGG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;OAIG;IACH,MAAM,IAAI,MAAM;IAMhB;;;;;OAKG;IACH,UAAU,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,YAAY,GAAE,OAAc,GAAG,MAAM;IAUvE;;;OAGG;IACH,OAAO,IAAI,OAAO;IAIlB;;;OAGG;IACH,KAAK,IAAI,MAAM;IAIf;;;OAGG;IACH,UAAU,IAAI,IAAI;IAOlB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,UAAU;IA4B3C;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM;IAIpC;;;OAGG;IACH,YAAY,IAAI,OAAO;IAQvB;;;OAGG;IACH,gBAAgB,IAAI,OAAO;CAuB9B"}

package/browser/branded.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Branded type definitions for type-safe primitives.
+ *
+ * @packageDocumentation
+ */
+declare const __brand: unique symbol;
+type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+export type Bytes32 = Brand<Uint8Array, 'Bytes32'>;
+export type Bytes20 = Brand<Uint8Array, 'Bytes20'>;
+export type PublicKey = Brand<Uint8Array, 'PublicKey'>;
+export type XOnlyPublicKey = Brand<Uint8Array, 'XOnlyPublicKey'>;
+export type Satoshi = Brand<bigint, 'Satoshi'>;
+export type PrivateKey = Brand<Uint8Array, 'PrivateKey'>;
+export type Signature = Brand<Uint8Array, 'Signature'>;
+export type SchnorrSignature = Brand<Uint8Array, 'SchnorrSignature'>;
+export type Script = Brand<Uint8Array, 'Script'>;
+export {};
+//# sourceMappingURL=branded.d.ts.map

package/browser/branded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branded.d.ts","sourceRoot":"","sources":["../src/branded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,CAAC,MAAM,OAAO,EAAE,OAAO,MAAM,CAAC;AACrC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAEhE,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AACnD,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AACnD,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;AACjE,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAC/C,MAAM,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;AACzD,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC;AACrE,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC"}

package/browser/crypto/crypto.d.ts

@@ -1 +1,2 @@
 export { createHash, createHmac, pbkdf2Sync, randomBytes } from './crypto-browser.js';
+//# sourceMappingURL=crypto.d.ts.map

package/browser/crypto/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/crypto/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC"}