@totemsdk/txpow 0.1.5 → 0.1.6

package/README.md

@@ -69,6 +69,17 @@ const estimatedMs     = estimateMiningCost(targetDifficulty, hashesPerSecond);
 console.log(`Expected mining time: ${estimatedMs}ms`);
 ```
 
+## Upstream Java source
+
+This package is a TypeScript port of Minima's TxPoW envelope structures. Canonical upstream references:
+
+- [`objects/TxPoW.java`](https://github.com/spartacusrex-minima/minima-core/blob/main/src/org/minima/objects/TxPoW.java) — full TxPoW envelope
+- [`objects/TxBody.java`](https://github.com/spartacusrex-minima/minima-core/blob/main/src/org/minima/objects/TxBody.java) — body serialization
+- [`objects/TxHeader.java`](https://github.com/spartacusrex-minima/minima-core/blob/main/src/org/minima/objects/TxHeader.java) — header serialization
+- [`objects/Witness.java`](https://github.com/spartacusrex-minima/minima-core/blob/main/src/org/minima/objects/Witness.java) — witness/signature data
+- [`objects/CoinProof.java`](https://github.com/spartacusrex-minima/minima-core/blob/main/src/org/minima/objects/CoinProof.java) — coin proof structure
+- [`objects/ScriptProof.java`](https://github.com/spartacusrex-minima/minima-core/blob/main/src/org/minima/objects/ScriptProof.java) — script proof structure
+
 ## See also
 
 - [`@totemsdk/tx-builder`](https://www.npmjs.com/package/@totemsdk/tx-builder) — construct `txBodyBytes` before mining

package/dist/index.d.ts

@@ -20,7 +20,8 @@
 export { serializeTxHeader, serializeTxBody, serializeTxPoW, computeTxPoWId, type TxHeaderOptions, type TxBodyOptions, type TxPoWOptions, } from './serialization.js';
 export { MAX_HASH, ZERO_HASH, TX_POW_MIN_DIFFICULTY, CASCADE_LEVELS, MAIN_NET_CHAIN_ID, } from './constants.js';
 export { serializeMagic } from './magic.js';
-export { mineTxPoW, isLessThan, type MineResult, type MineOptions, } from './mine.js';
+export { mineTxPoW, mineTxPoWInProcess, isLessThan, setBrowserWorkerUrl, type MineResult, type MineOptions, } from './mine.js';
+export { setWasmUrl, getBrowserWasmUrl, isWasmAvailable } from './mine-wasm.js';
 export { fetchTxPowTarget, type TxPowParams } from './difficulty.js';
-export { verifyProofOfWork, verifyTxPoWWork, type VerifyResult } from './verify.js';
+export { verifyProofOfWork, verifyTxPoWWork, verifyTxPoWParts, type VerifyResult } from './verify.js';
 export { calibrateHashRate, estimateMiningCost, type MiningEstimate, } from './calibrate.js';

package/dist/index.js

@@ -19,7 +19,7 @@
  *   if (!check.valid) drop(check.reason);
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.estimateMiningCost = exports.calibrateHashRate = exports.verifyTxPoWWork = exports.verifyProofOfWork = exports.fetchTxPowTarget = exports.isLessThan = exports.mineTxPoW = exports.serializeMagic = exports.MAIN_NET_CHAIN_ID = exports.CASCADE_LEVELS = exports.TX_POW_MIN_DIFFICULTY = exports.ZERO_HASH = exports.MAX_HASH = exports.computeTxPoWId = exports.serializeTxPoW = exports.serializeTxBody = exports.serializeTxHeader = void 0;
+exports.estimateMiningCost = exports.calibrateHashRate = exports.verifyTxPoWParts = exports.verifyTxPoWWork = exports.verifyProofOfWork = exports.fetchTxPowTarget = exports.isWasmAvailable = exports.getBrowserWasmUrl = exports.setWasmUrl = exports.setBrowserWorkerUrl = exports.isLessThan = exports.mineTxPoWInProcess = exports.mineTxPoW = exports.serializeMagic = exports.MAIN_NET_CHAIN_ID = exports.CASCADE_LEVELS = exports.TX_POW_MIN_DIFFICULTY = exports.ZERO_HASH = exports.MAX_HASH = exports.computeTxPoWId = exports.serializeTxPoW = exports.serializeTxBody = exports.serializeTxHeader = void 0;
 var serialization_js_1 = require("./serialization.js");
 Object.defineProperty(exports, "serializeTxHeader", { enumerable: true, get: function () { return serialization_js_1.serializeTxHeader; } });
 Object.defineProperty(exports, "serializeTxBody", { enumerable: true, get: function () { return serialization_js_1.serializeTxBody; } });
@@ -35,12 +35,19 @@ var magic_js_1 = require("./magic.js");
 Object.defineProperty(exports, "serializeMagic", { enumerable: true, get: function () { return magic_js_1.serializeMagic; } });
 var mine_js_1 = require("./mine.js");
 Object.defineProperty(exports, "mineTxPoW", { enumerable: true, get: function () { return mine_js_1.mineTxPoW; } });
+Object.defineProperty(exports, "mineTxPoWInProcess", { enumerable: true, get: function () { return mine_js_1.mineTxPoWInProcess; } });
 Object.defineProperty(exports, "isLessThan", { enumerable: true, get: function () { return mine_js_1.isLessThan; } });
+Object.defineProperty(exports, "setBrowserWorkerUrl", { enumerable: true, get: function () { return mine_js_1.setBrowserWorkerUrl; } });
+var mine_wasm_js_1 = require("./mine-wasm.js");
+Object.defineProperty(exports, "setWasmUrl", { enumerable: true, get: function () { return mine_wasm_js_1.setWasmUrl; } });
+Object.defineProperty(exports, "getBrowserWasmUrl", { enumerable: true, get: function () { return mine_wasm_js_1.getBrowserWasmUrl; } });
+Object.defineProperty(exports, "isWasmAvailable", { enumerable: true, get: function () { return mine_wasm_js_1.isWasmAvailable; } });
 var difficulty_js_1 = require("./difficulty.js");
 Object.defineProperty(exports, "fetchTxPowTarget", { enumerable: true, get: function () { return difficulty_js_1.fetchTxPowTarget; } });
 var verify_js_1 = require("./verify.js");
 Object.defineProperty(exports, "verifyProofOfWork", { enumerable: true, get: function () { return verify_js_1.verifyProofOfWork; } });
 Object.defineProperty(exports, "verifyTxPoWWork", { enumerable: true, get: function () { return verify_js_1.verifyTxPoWWork; } });
+Object.defineProperty(exports, "verifyTxPoWParts", { enumerable: true, get: function () { return verify_js_1.verifyTxPoWParts; } });
 var calibrate_js_1 = require("./calibrate.js");
 Object.defineProperty(exports, "calibrateHashRate", { enumerable: true, get: function () { return calibrate_js_1.calibrateHashRate; } });
 Object.defineProperty(exports, "estimateMiningCost", { enumerable: true, get: function () { return calibrate_js_1.estimateMiningCost; } });

package/dist/mine-wasm.d.ts

@@ -0,0 +1,69 @@
+/**
+ * mine-wasm.ts — WASM mining loop loader and wrapper.
+ *
+ * Loads the pre-compiled `miner.wasm` binary and provides `mineChunkWasm()`.
+ * Falls back gracefully when the binary is unavailable.
+ *
+ * ── Memory layout (must match miner.wat) ──
+ *   [0  .. 31 ] — hash output buffer (host sha3_256 writes here)
+ *   [32 .. 32+headerLen-1 ] — header buffer  (set by caller before each call)
+ *   [32+headerLen .. 32+headerLen+31] — target buffer (set once per mine)
+ *
+ * ── Runtime detection ──
+ *   Node.js  → reads dist/wasm/miner.wasm via fs.readFileSync
+ *   Browser  → fetches the URL supplied by setWasmUrl() (Task #114 supplies it)
+ *
+ * ── WASM binary compilation ──
+ *   node scripts/compile-wasm.js   (uses wabt npm package, no Emscripten needed)
+ *   npm run build                  (postbuild copies miner.wasm → dist/wasm/)
+ *
+ * ── WASM module interface (miner.wat) ──
+ *   import env.sha3_256(headerPtr, headerLen, outPtr)  ← host provides via @noble/hashes
+ *   export mine(headerPtr, headerLen, nonceOffset, nonceLen,
+ *               targetPtr, startNonce, chunkSize) → i32
+ *   export memory
+ *
+ * mine() returns the found nonce, or -1 (0xFFFFFFFF) if no nonce found in chunk.
+ */
+/** First byte of the header region (after the 32-byte hash output buffer). */
+export declare const WASM_HEADER_OFFSET = 32;
+/**
+ * Configure the URL from which the browser loads `miner.wasm`.
+ *
+ * Call this once at app startup in browser contexts. The extension build
+ * (Task #114) resolves this URL from the bundler's output.
+ *
+ * @example
+ *   import { setWasmUrl } from '@totemsdk/txpow';
+ *   setWasmUrl(browser.runtime.getURL('miner.wasm'));
+ */
+export declare function setWasmUrl(url: string): void;
+/**
+ * Return the current browser WASM URL, or null if not yet configured.
+ * Used by the main thread to pass the URL into spawned browser Web Workers.
+ */
+export declare function getBrowserWasmUrl(): string | null;
+/**
+ * Returns true when the WASM binary is loaded and `mine` is ready to use.
+ * Cached after the first call; subsequent calls are synchronous (via memoised flag).
+ */
+export declare function isWasmAvailable(): Promise<boolean>;
+/**
+ * Mine a chunk using the WASM binary.
+ *
+ * Copies `headerBuf` and `target` into WASM linear memory at the correct
+ * offsets, calls `mine()`, and returns the found nonce — or `null` if:
+ *   - WASM binary is unavailable
+ *   - No valid nonce was found within the specified chunk
+ *
+ * Grows WASM memory if needed (single-page default = 64 KB is ample for
+ * any realistic TxHeader, but growth is handled for safety).
+ *
+ * @param headerBuf   Full TxHeader bytes for the current nonce encoding range.
+ * @param nonceOffset Byte offset of the nonce VALUE in the header (always 2).
+ * @param nonceLen    Byte length of the nonce value (1 for 0–127, 2 for 128–32767, …).
+ * @param target      32-byte difficulty target (big-endian).
+ * @param startNonce  First nonce value to try.
+ * @param chunkCount  Number of consecutive nonce values to try.
+ */
+export declare function mineChunkWasm(headerBuf: Uint8Array, nonceOffset: number, nonceLen: number, target: Uint8Array, startNonce: bigint, chunkCount: bigint): Promise<bigint | null>;

package/dist/mine-wasm.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * mine-wasm.ts — WASM mining loop loader and wrapper.
+ *
+ * Loads the pre-compiled `miner.wasm` binary and provides `mineChunkWasm()`.
+ * Falls back gracefully when the binary is unavailable.
+ *
+ * ── Memory layout (must match miner.wat) ──
+ *   [0  .. 31 ] — hash output buffer (host sha3_256 writes here)
+ *   [32 .. 32+headerLen-1 ] — header buffer  (set by caller before each call)
+ *   [32+headerLen .. 32+headerLen+31] — target buffer (set once per mine)
+ *
+ * ── Runtime detection ──
+ *   Node.js  → reads dist/wasm/miner.wasm via fs.readFileSync
+ *   Browser  → fetches the URL supplied by setWasmUrl() (Task #114 supplies it)
+ *
+ * ── WASM binary compilation ──
+ *   node scripts/compile-wasm.js   (uses wabt npm package, no Emscripten needed)
+ *   npm run build                  (postbuild copies miner.wasm → dist/wasm/)
+ *
+ * ── WASM module interface (miner.wat) ──
+ *   import env.sha3_256(headerPtr, headerLen, outPtr)  ← host provides via @noble/hashes
+ *   export mine(headerPtr, headerLen, nonceOffset, nonceLen,
+ *               targetPtr, startNonce, chunkSize) → i32
+ *   export memory
+ *
+ * mine() returns the found nonce, or -1 (0xFFFFFFFF) if no nonce found in chunk.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WASM_HEADER_OFFSET = void 0;
+exports.setWasmUrl = setWasmUrl;
+exports.getBrowserWasmUrl = getBrowserWasmUrl;
+exports.isWasmAvailable = isWasmAvailable;
+exports.mineChunkWasm = mineChunkWasm;
+const sha3_js_1 = require("@noble/hashes/sha3.js");
+/** Byte offset in WASM linear memory where the hash output is written. */
+const HASH_OUT_OFFSET = 0;
+/** First byte of the header region (after the 32-byte hash output buffer). */
+exports.WASM_HEADER_OFFSET = 32;
+/**
+ * Sentinel returned by WASM mine() when no nonce is found in the chunk.
+ * The WAT uses `i32.const -1` (= 0xFFFFFFFF bit pattern).
+ * WebAssembly i32 return values are sign-extended to JavaScript Number,
+ * so 0xFFFFFFFF arrives as -1, NOT as 4294967295.
+ */
+const NOT_FOUND = -1;
+// ─────────────────────────────────────────────────────────────────────────────
+// Browser WASM URL configuration
+// ─────────────────────────────────────────────────────────────────────────────
+let _browserWasmUrl = null;
+/**
+ * Configure the URL from which the browser loads `miner.wasm`.
+ *
+ * Call this once at app startup in browser contexts. The extension build
+ * (Task #114) resolves this URL from the bundler's output.
+ *
+ * @example
+ *   import { setWasmUrl } from '@totemsdk/txpow';
+ *   setWasmUrl(browser.runtime.getURL('miner.wasm'));
+ */
+function setWasmUrl(url) {
+    _browserWasmUrl = url;
+    _loadAttempted = false;
+    _instance = null;
+    _memory = null;
+}
+/**
+ * Return the current browser WASM URL, or null if not yet configured.
+ * Used by the main thread to pass the URL into spawned browser Web Workers.
+ */
+function getBrowserWasmUrl() {
+    return _browserWasmUrl;
+}
+let _instance = null;
+let _memory = null;
+let _loadAttempted = false;
+/** Build the WebAssembly import object, wiring sha3_256 from @noble/hashes. */
+function buildImports() {
+    return {
+        env: {
+            /**
+             * sha3_256(headerPtr, headerLen, outPtr)
+             * Reads header bytes from WASM linear memory, computes SHA3-256,
+             * writes 32-byte digest back into WASM linear memory at outPtr.
+             */
+            sha3_256(headerPtr, headerLen, outPtr) {
+                if (!_memory)
+                    return;
+                const memView = new Uint8Array(_memory.buffer);
+                // Slice to get a clean copy unaffected by future mutations
+                const input = memView.slice(headerPtr, headerPtr + headerLen);
+                const hash = (0, sha3_js_1.sha3_256)(input);
+                memView.set(hash, outPtr);
+            },
+        },
+    };
+}
+/**
+ * Load the WASM binary once per process (idempotent).
+ * Returns the instantiated module, or null if unavailable.
+ */
+async function loadWasm() {
+    if (_loadAttempted)
+        return _instance;
+    _loadAttempted = true;
+    if (typeof WebAssembly === 'undefined')
+        return null;
+    try {
+        let wasmBytes;
+        if (typeof process !== 'undefined' && process.versions?.node) {
+            // ── Node.js path ──────────────────────────────────────────────────────
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const fs = require('fs');
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const path = require('path');
+            const wasmPath = path.join(__dirname, 'wasm', 'miner.wasm');
+            if (!fs.existsSync(wasmPath))
+                return null;
+            // Use new Uint8Array(nodeBuffer) — correct copy that respects
+            // Buffer byteOffset/byteLength, avoiding the shared pool pitfall
+            // of accessing .buffer directly on a pooled Node.js Buffer.
+            const nodeBuffer = fs.readFileSync(wasmPath);
+            wasmBytes = new Uint8Array(nodeBuffer);
+        }
+        else if (_browserWasmUrl !== null) {
+            // ── Browser path ──────────────────────────────────────────────────────
+            const resp = await globalThis.fetch(_browserWasmUrl);
+            if (!resp.ok)
+                return null;
+            const ab = await resp.arrayBuffer();
+            wasmBytes = new Uint8Array(ab);
+        }
+        else {
+            // Browser context but no URL configured yet.
+            // Call setWasmUrl() to enable WASM in the browser (Task #114).
+            return null;
+        }
+        // Compile and instantiate with host imports
+        const buf = wasmBytes.buffer.slice(wasmBytes.byteOffset, wasmBytes.byteOffset + wasmBytes.byteLength);
+        const wasmModule = await WebAssembly.compile(buf);
+        const instance = await WebAssembly.instantiate(wasmModule, buildImports());
+        const exports = instance.exports;
+        if (typeof exports.mine !== 'function')
+            return null;
+        if (!(exports.memory instanceof WebAssembly.Memory))
+            return null;
+        _instance = instance;
+        _memory = exports.memory;
+        return _instance;
+    }
+    catch {
+        return null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Returns true when the WASM binary is loaded and `mine` is ready to use.
+ * Cached after the first call; subsequent calls are synchronous (via memoised flag).
+ */
+async function isWasmAvailable() {
+    return (await loadWasm()) !== null;
+}
+/**
+ * Mine a chunk using the WASM binary.
+ *
+ * Copies `headerBuf` and `target` into WASM linear memory at the correct
+ * offsets, calls `mine()`, and returns the found nonce — or `null` if:
+ *   - WASM binary is unavailable
+ *   - No valid nonce was found within the specified chunk
+ *
+ * Grows WASM memory if needed (single-page default = 64 KB is ample for
+ * any realistic TxHeader, but growth is handled for safety).
+ *
+ * @param headerBuf   Full TxHeader bytes for the current nonce encoding range.
+ * @param nonceOffset Byte offset of the nonce VALUE in the header (always 2).
+ * @param nonceLen    Byte length of the nonce value (1 for 0–127, 2 for 128–32767, …).
+ * @param target      32-byte difficulty target (big-endian).
+ * @param startNonce  First nonce value to try.
+ * @param chunkCount  Number of consecutive nonce values to try.
+ */
+async function mineChunkWasm(headerBuf, nonceOffset, nonceLen, target, startNonce, chunkCount) {
+    const inst = await loadWasm();
+    if (!inst || !_memory)
+        return null;
+    // Renamed to wasmExports to avoid shadowing the CJS module-level `exports` object.
+    // If named `exports`, `exports.WASM_HEADER_OFFSET` would resolve to the WASM
+    // instance exports (which has no such property → undefined), making headerPtr=0.
+    const wasmExports = inst.exports;
+    // Memory layout: [0..31]=hash output, [32..32+headerLen-1]=header, [32+headerLen..32+headerLen+31]=target
+    const headerPtr = exports.WASM_HEADER_OFFSET;
+    const targetPtr = headerPtr + headerBuf.length;
+    const totalNeeded = targetPtr + 32;
+    // Grow memory if necessary
+    let memView = new Uint8Array(_memory.buffer);
+    if (memView.byteLength < totalNeeded) {
+        const pagesNeeded = Math.ceil((totalNeeded - memView.byteLength) / 65536) + 1;
+        try {
+            _memory.grow(pagesNeeded);
+            memView = new Uint8Array(_memory.buffer);
+        }
+        catch {
+            return null;
+        }
+    }
+    // Write header and target into WASM memory
+    memView.set(headerBuf, headerPtr);
+    memView.set(target, targetPtr);
+    const result = wasmExports.mine(headerPtr, headerBuf.length, nonceOffset, nonceLen, targetPtr, Number(startNonce), Number(chunkCount));
+    // result === -1  →  no nonce found (WASM i32 0xFFFFFFFF sign-extended to JS -1)
+    // result >= 0    →  found nonce; use >>> 0 to treat as unsigned before BigInt
+    return result === NOT_FOUND ? null : BigInt(result >>> 0);
+}

package/dist/mine.d.ts

@@ -12,7 +12,19 @@
  *      value bytes in place — no per-iteration allocation.
  *   4. At each MiniNumber encoding boundary (nonce 128, 32768, 8388608, …) we
  *      re-allocate a new header buffer with the wider nonce field.
- *   5. Between chunks we yield to the event loop so the caller thread isn't blocked.
+ *   5. Between chunks we yield to the event loop so the calling thread is never blocked.
+ *   6. When the pre-compiled WASM binary is present (`dist/wasm/miner.wasm`), the
+ *      inner loop runs in WASM for ~5-10x throughput. Falls back to pure JS otherwise.
+ *   7. In Node.js (main thread), mining runs inside a `worker_threads` Worker so the
+ *      event loop is never blocked. In browser contexts the in-process loop is used
+ *      until Task #114 wires up the Web Worker entry point.
+ *
+ * Control-flow invariant (IMPORTANT):
+ *   WASM and JS are mutually exclusive per chunk — we never re-mine a chunk that
+ *   WASM already scanned. When WASM returns null (nonce not found in chunk), we
+ *   advance to the next chunk rather than falling back to JS for the same range.
+ *   This means `source` is always accurate: 'wasm' when the binary was used for
+ *   the winning chunk; 'js' when the JS path found the nonce.
  */
 export interface MineResult {
     /** Fully serialized TxHeader bytes with the winning nonce. */
@@ -21,7 +33,7 @@ export interface MineResult {
     txpowId: Uint8Array;
     nonce: bigint;
     elapsedMs: number;
-    /** 'wasm' when the WASM binary is present; 'js' otherwise. */
+    /** 'wasm' when the pre-compiled WASM binary found the nonce; 'js' otherwise. */
     source: 'wasm' | 'js';
 }
 export interface MineOptions {
@@ -37,20 +49,59 @@ export interface MineOptions {
     maxIterations?: number;
     /** AbortSignal — rejects the Promise when aborted. */
     signal?: AbortSignal;
+    /**
+     * Override the header timestamp (milliseconds since epoch).
+     * Defaults to Date.now(). Set a fixed value for deterministic testing.
+     */
+    timeMilli?: bigint;
+    /**
+     * Force the pure-JS mining path even when `miner.wasm` is present.
+     * Useful for testing the JS fallback or comparing JS vs WASM performance.
+     */
+    forceJs?: boolean;
+    /**
+     * Internal: skip spawning a Node.js worker_threads Worker.
+     * Set by node.worker.ts to prevent recursive worker creation.
+     * Also forces in-process execution when set programmatically.
+     * @internal
+     */
+    _skipWorker?: boolean;
 }
 /**
  * Big-endian 256-bit comparison: true if a < b.
  * Used to check: txpowId < mTxnDifficulty.
  */
 export declare function isLessThan(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Configure the URL of the browser.worker.js bundle so that `mineTxPoW()`
+ * can spawn a Web Worker in browser contexts.
+ *
+ * Call this once at extension/dApp startup. The bundled worker file exposes
+ * the same message protocol as node.worker.ts.
+ *
+ * @example
+ *   import { setBrowserWorkerUrl } from '@totemsdk/txpow';
+ *   setBrowserWorkerUrl(browser.runtime.getURL('mine-worker.js'));
+ */
+export declare function setBrowserWorkerUrl(url: string): void;
+/**
+ * Run the mining loop in the current thread/task.
+ * Called directly by the Node.js worker, and by the browser code path.
+ */
+export declare function mineTxPoWInProcess(txBodyBytes: Uint8Array, txnDifficulty: Uint8Array, options?: MineOptions): Promise<MineResult>;
 /**
  * Mine a TxPoW locally by iterating the header nonce until
  *   SHA3-256( TxHeader ) < txnDifficulty
  *
+ * In Node.js (main thread), delegates to a `worker_threads` Worker so the
+ * event loop is never blocked. In browsers or Jest, runs in-process with
+ * periodic `setImmediate`/`setTimeout(0)` yields between chunks.
+ *
+ * Uses the pre-compiled `miner.wasm` binary for inner-loop throughput when
+ * available. Falls back to pure JS automatically when the binary is absent.
+ *
  * @param txBodyBytes   Pre-serialized TxBody bytes (from serializeTxBody).
  * @param txnDifficulty 32-byte target. MUST be ≤ TX_POW_MIN_DIFFICULTY.
- *                      Passing MAX_HASH here will loop forever and be rejected
- *                      at block level by TxPoWChecker.checkTxPoWSimple().
- * @param options       Chunk size, max iterations, abort signal.
+ * @param options       Chunk size, max iterations, abort signal, timeMilli override.
  */
 export declare function mineTxPoW(txBodyBytes: Uint8Array, txnDifficulty: Uint8Array, options?: MineOptions): Promise<MineResult>;

package/dist/mine.js

@@ -13,15 +13,30 @@
  *      value bytes in place — no per-iteration allocation.
  *   4. At each MiniNumber encoding boundary (nonce 128, 32768, 8388608, …) we
  *      re-allocate a new header buffer with the wider nonce field.
- *   5. Between chunks we yield to the event loop so the caller thread isn't blocked.
+ *   5. Between chunks we yield to the event loop so the calling thread is never blocked.
+ *   6. When the pre-compiled WASM binary is present (`dist/wasm/miner.wasm`), the
+ *      inner loop runs in WASM for ~5-10x throughput. Falls back to pure JS otherwise.
+ *   7. In Node.js (main thread), mining runs inside a `worker_threads` Worker so the
+ *      event loop is never blocked. In browser contexts the in-process loop is used
+ *      until Task #114 wires up the Web Worker entry point.
+ *
+ * Control-flow invariant (IMPORTANT):
+ *   WASM and JS are mutually exclusive per chunk — we never re-mine a chunk that
+ *   WASM already scanned. When WASM returns null (nonce not found in chunk), we
+ *   advance to the next chunk rather than falling back to JS for the same range.
+ *   This means `source` is always accurate: 'wasm' when the binary was used for
+ *   the winning chunk; 'js' when the JS path found the nonce.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isLessThan = isLessThan;
+exports.setBrowserWorkerUrl = setBrowserWorkerUrl;
+exports.mineTxPoWInProcess = mineTxPoWInProcess;
 exports.mineTxPoW = mineTxPoW;
 const sha3_js_1 = require("@noble/hashes/sha3.js");
 const core_1 = require("@totemsdk/core");
 const magic_js_1 = require("./magic.js");
 const constants_js_1 = require("./constants.js");
+const mine_wasm_js_1 = require("./mine-wasm.js");
 // ─────────────────────────────────────────────────────────────────────────────
 // Internal helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -65,7 +80,7 @@ function buildHeaderTail(txBodyHash, timeMilli) {
  * Mutates headerBuf in place — only the nonce value bytes at offset 2 change.
  * Returns the found nonce, or null if not found in this chunk.
  */
-function mineChunk(headerBuf, nonceValueLen, target, startNonce, endNonce) {
+function mineChunkJs(headerBuf, nonceValueLen, target, startNonce, endNonce) {
     const nonceValueOffset = 2;
     for (let nonce = startNonce; nonce < endNonce; nonce++) {
         let n = nonce;
@@ -80,27 +95,208 @@ function mineChunk(headerBuf, nonceValueLen, target, startNonce, endNonce) {
     return null;
 }
 // ─────────────────────────────────────────────────────────────────────────────
-// Public API
+// Browser Web Worker dispatch (optional URL-based)
 // ─────────────────────────────────────────────────────────────────────────────
+let _browserWorkerUrl = null;
 /**
- * Mine a TxPoW locally by iterating the header nonce until
- *   SHA3-256( TxHeader ) < txnDifficulty
+ * Configure the URL of the browser.worker.js bundle so that `mineTxPoW()`
+ * can spawn a Web Worker in browser contexts.
  *
- * @param txBodyBytes   Pre-serialized TxBody bytes (from serializeTxBody).
- * @param txnDifficulty 32-byte target. MUST be ≤ TX_POW_MIN_DIFFICULTY.
- *                      Passing MAX_HASH here will loop forever and be rejected
- *                      at block level by TxPoWChecker.checkTxPoWSimple().
- * @param options       Chunk size, max iterations, abort signal.
+ * Call this once at extension/dApp startup. The bundled worker file exposes
+ * the same message protocol as node.worker.ts.
+ *
+ * @example
+ *   import { setBrowserWorkerUrl } from '@totemsdk/txpow';
+ *   setBrowserWorkerUrl(browser.runtime.getURL('mine-worker.js'));
  */
-async function mineTxPoW(txBodyBytes, txnDifficulty, options) {
+function setBrowserWorkerUrl(url) {
+    _browserWorkerUrl = url;
+}
+/**
+ * Spawn a browser Web Worker to run the mining loop off the main thread.
+ * Requires a prior call to setBrowserWorkerUrl() to configure the worker URL.
+ */
+async function mineTxPoWViaBrowserWorker(txBodyBytes, txnDifficulty, options) {
+    if (!_browserWorkerUrl) {
+        throw new Error('Browser Web Worker URL not configured. Call setBrowserWorkerUrl() first.');
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const WorkerClass = globalThis.Worker;
+    const worker = new WorkerClass(_browserWorkerUrl);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (fn) => {
+            if (!settled) {
+                settled = true;
+                fn();
+            }
+        };
+        if (options?.signal) {
+            const abortHandler = () => {
+                settle(() => reject(new DOMException('Mining aborted', 'AbortError')));
+                worker.terminate();
+            };
+            if (options.signal.aborted) {
+                abortHandler();
+                return;
+            }
+            options.signal.addEventListener('abort', abortHandler, { once: true });
+        }
+        worker.onmessage = (e) => {
+            const msg = e.data;
+            if (msg['error']) {
+                settle(() => reject(new Error(String(msg['error']))));
+            }
+            else {
+                settle(() => resolve({
+                    minedHeaderBytes: Uint8Array.from(msg['minedHeaderBytes']),
+                    txpowId: Uint8Array.from(msg['txpowId']),
+                    nonce: BigInt(msg['nonce']),
+                    elapsedMs: msg['elapsedMs'],
+                    source: msg['source'],
+                }));
+            }
+        };
+        worker.onerror = (e) => {
+            settle(() => reject(new Error(e.message)));
+        };
+        // Pass the WASM URL so the worker can call setWasmUrl() in its own JS context.
+        // Web Workers have isolated module state — the main thread's setWasmUrl() call
+        // does not carry over. Without this the worker mines in pure JS.
+        const wasmUrl = (0, mine_wasm_js_1.getBrowserWasmUrl)();
+        worker.postMessage({
+            txBodyBytes: Array.from(txBodyBytes),
+            txnDifficulty: Array.from(txnDifficulty),
+            wasmUrl: wasmUrl ?? undefined,
+            chunkSize: options?.chunkSize,
+            maxIterations: options?.maxIterations !== undefined
+                ? options.maxIterations.toString()
+                : undefined,
+            timeMilli: options?.timeMilli !== undefined
+                ? options.timeMilli.toString()
+                : undefined,
+            forceJs: options?.forceJs,
+        });
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Node.js worker_threads dispatch
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Returns true when mining should be delegated to a Node.js worker_threads Worker.
+ *
+ * Conditions for using a worker:
+ *   - Running in Node.js (process.versions.node is set)
+ *   - Not already inside a worker thread (isMainThread === true)
+ *   - _skipWorker option is not set
+ *   - Not in a Jest test environment (ts-jest runs from source, dist/workers/*.js
+ *     may not exist yet; Jest's own worker processes also have isMainThread=false
+ *     which handles the common --maxWorkers case automatically)
+ */
+function shouldUseNodeWorker(options) {
+    if (options?._skipWorker)
+        return false;
+    if (typeof process === 'undefined' || !process.versions?.node)
+        return false;
+    // In Jest, skip worker spawning: source workers are not compiled .js files
+    // and Jest's own worker pool already sets isMainThread=false for most runners.
+    if (process.env.NODE_ENV === 'test' ||
+        process.env.JEST_WORKER_ID !== undefined) {
+        return false;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const wt = require('worker_threads');
+        return wt.isMainThread;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Dispatch mining to a Node.js `worker_threads` Worker.
+ * The worker runs `mineTxPoWInProcess` with `_skipWorker: true` to prevent
+ * recursive worker spawning.
+ */
+async function mineTxPoWViaNodeWorker(txBodyBytes, txnDifficulty, options) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { Worker } = require('worker_threads');
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { join } = require('path');
+    const workerPath = join(__dirname, 'workers', 'node.worker.js');
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (fn) => {
+            if (!settled) {
+                settled = true;
+                fn();
+            }
+        };
+        const worker = new Worker(workerPath, {
+            workerData: {
+                txBodyBytes: Array.from(txBodyBytes),
+                txnDifficulty: Array.from(txnDifficulty),
+                chunkSize: options?.chunkSize,
+                maxIterations: options?.maxIterations !== undefined
+                    ? options.maxIterations.toString()
+                    : undefined,
+                timeMilli: options?.timeMilli !== undefined
+                    ? options.timeMilli.toString()
+                    : undefined,
+                forceJs: options?.forceJs,
+            },
+        });
+        if (options?.signal) {
+            const abortHandler = () => {
+                settle(() => reject(new DOMException('Mining aborted', 'AbortError')));
+                worker.terminate().catch(() => { });
+            };
+            if (options.signal.aborted) {
+                abortHandler();
+                return;
+            }
+            options.signal.addEventListener('abort', abortHandler, { once: true });
+        }
+        worker.on('message', (msg) => {
+            if (msg['error']) {
+                settle(() => reject(new Error(String(msg['error']))));
+            }
+            else {
+                settle(() => resolve({
+                    minedHeaderBytes: Uint8Array.from(msg['minedHeaderBytes']),
+                    txpowId: Uint8Array.from(msg['txpowId']),
+                    nonce: BigInt(msg['nonce']),
+                    elapsedMs: msg['elapsedMs'],
+                    source: msg['source'],
+                }));
+            }
+        });
+        worker.on('error', (err) => settle(() => reject(err)));
+        worker.on('exit', (code) => {
+            if (code !== 0) {
+                settle(() => reject(new Error(`Mining worker exited with non-zero code ${code}`)));
+            }
+        });
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// In-process mining loop
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Run the mining loop in the current thread/task.
+ * Called directly by the Node.js worker, and by the browser code path.
+ */
+async function mineTxPoWInProcess(txBodyBytes, txnDifficulty, options) {
     const chunkSize = BigInt(options?.chunkSize ?? 10000);
     const maxIterations = options?.maxIterations !== undefined
         ? BigInt(options.maxIterations)
         : undefined;
     const signal = options?.signal;
+    const timeMilli = options?.timeMilli ?? BigInt(Date.now());
+    const forceJs = options?.forceJs ?? false;
     const bodyHash = (0, sha3_js_1.sha3_256)(txBodyBytes);
-    const timeMilli = BigInt(Date.now());
     const headerTail = buildHeaderTail(bodyHash, timeMilli);
+    const useWasm = !forceJs && (await (0, mine_wasm_js_1.isWasmAvailable)());
     const startTime = Date.now();
     let totalIterations = 0n;
     let nonce = 0n;
@@ -116,7 +312,19 @@ async function mineTxPoW(txBodyBytes, txnDifficulty, options) {
         const nonceBytes = (0, core_1.writeMiniNumber)(nonce);
         const nonceValueLen = nonceBytes.length - 2;
         const headerBuf = (0, core_1.concat)(nonceBytes, headerTail);
-        const found = mineChunk(headerBuf, nonceValueLen, txnDifficulty, nonce, chunkEnd);
+        // ── CRITICAL: WASM and JS are mutually exclusive per chunk ──────────────
+        // When WASM returns null (no nonce in chunk), the chunk has been fully
+        // scanned by WASM — we do NOT re-scan it with JS. Doing so would double
+        // work and could incorrectly set source='wasm' on a JS-found nonce.
+        let found;
+        if (useWasm) {
+            found = await (0, mine_wasm_js_1.mineChunkWasm)(headerBuf.slice(), // WASM gets its own copy to avoid aliasing
+            2, nonceValueLen, txnDifficulty, nonce, chunkEnd - nonce);
+        }
+        else {
+            found = mineChunkJs(headerBuf, nonceValueLen, txnDifficulty, nonce, chunkEnd);
+        }
+        // ── End mutually exclusive section ───────────────────────────────────────
         if (found !== null) {
             const finalNonceBytes = (0, core_1.writeMiniNumber)(found);
             const finalHeader = (0, core_1.concat)(finalNonceBytes, headerTail);
@@ -126,7 +334,7 @@ async function mineTxPoW(txBodyBytes, txnDifficulty, options) {
                 txpowId,
                 nonce: found,
                 elapsedMs: Date.now() - startTime,
-                source: 'js',
+                source: useWasm ? 'wasm' : 'js',
             };
         }
         totalIterations += chunkEnd - nonce;
@@ -141,3 +349,37 @@ async function mineTxPoW(txBodyBytes, txnDifficulty, options) {
         });
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Mine a TxPoW locally by iterating the header nonce until
+ *   SHA3-256( TxHeader ) < txnDifficulty
+ *
+ * In Node.js (main thread), delegates to a `worker_threads` Worker so the
+ * event loop is never blocked. In browsers or Jest, runs in-process with
+ * periodic `setImmediate`/`setTimeout(0)` yields between chunks.
+ *
+ * Uses the pre-compiled `miner.wasm` binary for inner-loop throughput when
+ * available. Falls back to pure JS automatically when the binary is absent.
+ *
+ * @param txBodyBytes   Pre-serialized TxBody bytes (from serializeTxBody).
+ * @param txnDifficulty 32-byte target. MUST be ≤ TX_POW_MIN_DIFFICULTY.
+ * @param options       Chunk size, max iterations, abort signal, timeMilli override.
+ */
+async function mineTxPoW(txBodyBytes, txnDifficulty, options) {
+    // ── Node.js: spawn a worker_threads Worker (keeps event loop unblocked) ──
+    if (shouldUseNodeWorker(options)) {
+        return mineTxPoWViaNodeWorker(txBodyBytes, txnDifficulty, options);
+    }
+    // ── Browser: spawn a Web Worker when the URL has been configured ──────────
+    // The extension build (Task #114) calls setBrowserWorkerUrl() at startup.
+    // Without a configured URL, mine falls back to in-process (setImmediate loop).
+    if (!options?._skipWorker &&
+        typeof process === 'undefined' && // not Node.js
+        _browserWorkerUrl !== null) {
+        return mineTxPoWViaBrowserWorker(txBodyBytes, txnDifficulty, options);
+    }
+    // ── In-process fallback (browser without worker URL, or explicit skip) ────
+    return mineTxPoWInProcess(txBodyBytes, txnDifficulty, options);
+}

package/dist/verify.d.ts

@@ -4,10 +4,30 @@
  * verifyProofOfWork checks that a given txpowId beats the difficulty target
  * without re-mining. Used by relay nodes to reject under-work submissions.
  *
- * verifyTxPoWWork is a convenience wrapper for relay nodes that receive raw
- * TxPoW hex: it hashes the full bytes as a proxy txpowId and checks against
- * the network minimum difficulty. PureMinima performs authoritative validation
- * on submission; this is a first-pass spam filter.
+ * verifyTxPoWWork receives raw TxPoW hex, parses the header/body split by
+ * verifying the embedded body-hash field, computes the canonical txpowId
+ * (SHA3-256 of the header only), extracts mTxnDifficulty from the TxBody,
+ * and checks txpowId < mTxnDifficulty. Falls back to the TX_POW_MIN_DIFFICULTY
+ * floor when parsing fails (malformed or non-standard TxPoW).
+ *
+ * verifyTxPoWParts is the low-level variant for callers who already hold
+ * pre-split header/body bytes.
+ *
+ * ── Wire format reference ─────────────────────────────────────────────────
+ * @totemsdk/core's writeHashToStream(hash) uses a 4-byte big-endian length
+ * prefix followed by the bytes: for a 32-byte hash → [0x00,0x00,0x00,0x20, ...32 bytes]
+ * = 36 bytes total. writeMiniData uses the same 4-byte prefix format.
+ *
+ * TxPoW wire format:  TxHeader bytes | 0x01 (hasBody) | TxBody bytes
+ * TxPoW ID:           SHA3-256(TxHeader bytes)
+ *
+ * TxHeader ends with:
+ *   writeHashToStream(mCustomHash)  — [0x00,0x00,0x00,0x20, ...32 zeros]   36 bytes
+ *   writeHashToStream(mTxBodyHash) — [0x00,0x00,0x00,0x20, ...32 bytes]   36 bytes
+ *
+ * TxBody starts with:
+ *   writeHashToStream(mPRNG)        — [0x00,0x00,0x00,0x20, ...32 bytes]   36 bytes
+ *   writeMiniData(mTxnDifficulty)   — [0x00,0x00,0x00,len,  ...len bytes]  4+len bytes
  */
 export interface VerifyResult {
     valid: boolean;
@@ -24,14 +44,33 @@ export interface VerifyResult {
  * @param mTxnDifficulty The 32-byte difficulty target from the TxBody.
  */
 export declare function verifyProofOfWork(txpowId: Uint8Array, mTxnDifficulty: Uint8Array): VerifyResult;
+/**
+ * Verify a TxPoW from pre-split header and body bytes.
+ *
+ * Computes SHA3-256(headerBytes) as the txpowId, extracts mTxnDifficulty
+ * from the body, and checks txpowId < mTxnDifficulty. Falls back to
+ * TX_POW_MIN_DIFFICULTY when the body cannot be parsed.
+ *
+ * @param headerBytes  Raw TxHeader bytes (SHA3-256 of these is the txpowId).
+ * @param bodyBytes    Raw TxBody bytes (mTxnDifficulty extracted from here).
+ */
+export declare function verifyTxPoWParts(headerBytes: Uint8Array, bodyBytes: Uint8Array): VerifyResult;
 /**
  * Relay-side work verification from raw TxPoW hex.
  *
- * Validates hex format, minimum length (spam filter), then computes
- * SHA3-256 of the serialized bytes as a proxy txpowId and checks it
- * against TX_POW_MIN_DIFFICULTY.
+ * Parses the TxPoW hex into header and body by locating the hasBody byte via
+ * body-hash verification. Computes the canonical TxPoW ID (SHA3-256 of the
+ * header only), extracts mTxnDifficulty from the TxBody, and verifies:
+ *   txpowId < mTxnDifficulty
+ *
+ * Falls back to TX_POW_MIN_DIFFICULTY as a spam filter when:
+ *   - The hex is invalid or malformed
+ *   - No valid header/body split can be found (non-standard structure)
+ *   - mTxnDifficulty cannot be extracted from the body
+ *
+ * PureMinima performs authoritative work verification on submission; this
+ * function is a first-pass relay-side filter.
  *
- * Note: full structural parsing of TxPoW headers is deferred to a future
- * parser. PureMinima performs authoritative work verification on submission.
+ * @param txpowHex  Hex-encoded serialized TxPoW (TxHeader | 0x01 | TxBody).
  */
 export declare function verifyTxPoWWork(txpowHex: string): VerifyResult;

package/dist/verify.js

@@ -5,20 +5,50 @@
  * verifyProofOfWork checks that a given txpowId beats the difficulty target
  * without re-mining. Used by relay nodes to reject under-work submissions.
  *
- * verifyTxPoWWork is a convenience wrapper for relay nodes that receive raw
- * TxPoW hex: it hashes the full bytes as a proxy txpowId and checks against
- * the network minimum difficulty. PureMinima performs authoritative validation
- * on submission; this is a first-pass spam filter.
+ * verifyTxPoWWork receives raw TxPoW hex, parses the header/body split by
+ * verifying the embedded body-hash field, computes the canonical txpowId
+ * (SHA3-256 of the header only), extracts mTxnDifficulty from the TxBody,
+ * and checks txpowId < mTxnDifficulty. Falls back to the TX_POW_MIN_DIFFICULTY
+ * floor when parsing fails (malformed or non-standard TxPoW).
+ *
+ * verifyTxPoWParts is the low-level variant for callers who already hold
+ * pre-split header/body bytes.
+ *
+ * ── Wire format reference ─────────────────────────────────────────────────
+ * @totemsdk/core's writeHashToStream(hash) uses a 4-byte big-endian length
+ * prefix followed by the bytes: for a 32-byte hash → [0x00,0x00,0x00,0x20, ...32 bytes]
+ * = 36 bytes total. writeMiniData uses the same 4-byte prefix format.
+ *
+ * TxPoW wire format:  TxHeader bytes | 0x01 (hasBody) | TxBody bytes
+ * TxPoW ID:           SHA3-256(TxHeader bytes)
+ *
+ * TxHeader ends with:
+ *   writeHashToStream(mCustomHash)  — [0x00,0x00,0x00,0x20, ...32 zeros]   36 bytes
+ *   writeHashToStream(mTxBodyHash) — [0x00,0x00,0x00,0x20, ...32 bytes]   36 bytes
+ *
+ * TxBody starts with:
+ *   writeHashToStream(mPRNG)        — [0x00,0x00,0x00,0x20, ...32 bytes]   36 bytes
+ *   writeMiniData(mTxnDifficulty)   — [0x00,0x00,0x00,len,  ...len bytes]  4+len bytes
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.verifyProofOfWork = verifyProofOfWork;
+exports.verifyTxPoWParts = verifyTxPoWParts;
 exports.verifyTxPoWWork = verifyTxPoWWork;
+const sha3_js_1 = require("@noble/hashes/sha3.js");
 const mine_js_1 = require("./mine.js");
 const serialization_js_1 = require("./serialization.js");
 const constants_js_1 = require("./constants.js");
 function toHex(bytes) {
     return '0x' + Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
 }
+/** Read a big-endian 4-byte unsigned integer from bytes at offset. */
+function readUint32BE(bytes, offset) {
+    return (((bytes[offset] << 24) |
+        (bytes[offset + 1] << 16) |
+        (bytes[offset + 2] << 8) |
+        bytes[offset + 3]) >>>
+        0);
+}
 /**
  * Verify that a TxPoW ID beats the stated difficulty target.
  *
@@ -52,15 +82,123 @@ function verifyProofOfWork(txpowId, mTxnDifficulty) {
         reason: valid ? undefined : 'txpowId ≥ mTxnDifficulty',
     };
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// TxPoW header/body parser
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Attempt to split raw TxPoW bytes into (headerBytes, bodyBytes).
+ *
+ * TxPoW wire format:  TxHeader | 0x01 (hasBody byte) | TxBody
+ * TxPoW ID:           SHA3-256(TxHeader)
+ *
+ * The header always ends with `writeHashToStream(sha3_256(TxBody))`.
+ * @totemsdk/core writeHashToStream uses a 4-byte big-endian length prefix:
+ *   [0x00, 0x00, 0x00, 0x20, ...32 body-hash bytes] = 36 bytes
+ *
+ * We scan forward looking for a 0x01 hasBody byte where:
+ *   - The preceding 36 bytes are [0,0,0,32] + 32-byte bodyHash
+ *   - sha3_256(bodyBytes) == those 32 bytes
+ * When found the split is authenticated by the hash.
+ *
+ * Returns null when no valid split is found.
+ */
+function tryParseTxPoW(bytes) {
+    // writeHashToStream(32-byte hash) = 36 bytes
+    const HASH_FIELD_LEN = 36;
+    // Minimum body: PRNG (36 bytes) + mTxnDifficulty prefix+data (4+1 minimum)
+    const MIN_BODY = 41;
+    // Minimum header must end with txBodyHash field (36 bytes)
+    const MIN_HEADER = HASH_FIELD_LEN;
+    const MIN_TOTAL = MIN_HEADER + 1 + MIN_BODY;
+    if (bytes.length < MIN_TOTAL)
+        return null;
+    for (let i = MIN_HEADER; i <= bytes.length - MIN_BODY - 1; i++) {
+        if (bytes[i] !== 0x01)
+            continue;
+        const headerBytes = bytes.slice(0, i);
+        if (headerBytes.length < HASH_FIELD_LEN)
+            continue;
+        // Last 36 bytes of header = writeHashToStream(bodyHash)
+        // = [0x00, 0x00, 0x00, 0x20, ...32 bytes]
+        const hashFieldStart = headerBytes.length - HASH_FIELD_LEN;
+        if (headerBytes[hashFieldStart] !== 0x00 ||
+            headerBytes[hashFieldStart + 1] !== 0x00 ||
+            headerBytes[hashFieldStart + 2] !== 0x00 ||
+            headerBytes[hashFieldStart + 3] !== 0x20) {
+            continue;
+        }
+        const embeddedBodyHash = headerBytes.slice(hashFieldStart + 4);
+        const bodyBytes = bytes.slice(i + 1);
+        const actualBodyHash = (0, sha3_js_1.sha3_256)(bodyBytes);
+        if (actualBodyHash.every((b, j) => b === embeddedBodyHash[j])) {
+            return { headerBytes, bodyBytes };
+        }
+    }
+    return null;
+}
+/**
+ * Extract mTxnDifficulty from TxBody bytes.
+ *
+ * TxBody wire format (using @totemsdk/core serialization):
+ *   [0..3]   [0x00,0x00,0x00,0x20]   4-byte big-endian length (32) for PRNG
+ *   [4..35]  prng bytes               32-byte random nonce
+ *   [36..39] [0x00,0x00,0x00,len]    4-byte big-endian length for mTxnDifficulty
+ *   [40..40+len-1] difficulty bytes  len bytes (standard: 32)
+ *
+ * Returns null when the body is too short or length prefixes are invalid.
+ */
+function extractTxnDifficulty(bodyBytes) {
+    // PRNG field: 4-byte length prefix + 32 bytes = 36 bytes total
+    if (bodyBytes.length < 40)
+        return null;
+    // Length prefix for PRNG must be 0x00000020 (= 32)
+    if (bodyBytes[0] !== 0x00 ||
+        bodyBytes[1] !== 0x00 ||
+        bodyBytes[2] !== 0x00 ||
+        bodyBytes[3] !== 0x20) {
+        return null;
+    }
+    // After PRNG (36 bytes), the next 4 bytes are the length prefix for mTxnDifficulty
+    const diffLen = readUint32BE(bodyBytes, 36);
+    if (diffLen === 0 || 40 + diffLen > bodyBytes.length)
+        return null;
+    return bodyBytes.slice(40, 40 + diffLen);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Public verification API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Verify a TxPoW from pre-split header and body bytes.
+ *
+ * Computes SHA3-256(headerBytes) as the txpowId, extracts mTxnDifficulty
+ * from the body, and checks txpowId < mTxnDifficulty. Falls back to
+ * TX_POW_MIN_DIFFICULTY when the body cannot be parsed.
+ *
+ * @param headerBytes  Raw TxHeader bytes (SHA3-256 of these is the txpowId).
+ * @param bodyBytes    Raw TxBody bytes (mTxnDifficulty extracted from here).
+ */
+function verifyTxPoWParts(headerBytes, bodyBytes) {
+    const txpowId = (0, serialization_js_1.computeTxPoWId)(headerBytes);
+    const difficulty = extractTxnDifficulty(bodyBytes) ?? constants_js_1.TX_POW_MIN_DIFFICULTY;
+    return verifyProofOfWork(txpowId, difficulty);
+}
 /**
  * Relay-side work verification from raw TxPoW hex.
  *
- * Validates hex format, minimum length (spam filter), then computes
- * SHA3-256 of the serialized bytes as a proxy txpowId and checks it
- * against TX_POW_MIN_DIFFICULTY.
+ * Parses the TxPoW hex into header and body by locating the hasBody byte via
+ * body-hash verification. Computes the canonical TxPoW ID (SHA3-256 of the
+ * header only), extracts mTxnDifficulty from the TxBody, and verifies:
+ *   txpowId < mTxnDifficulty
+ *
+ * Falls back to TX_POW_MIN_DIFFICULTY as a spam filter when:
+ *   - The hex is invalid or malformed
+ *   - No valid header/body split can be found (non-standard structure)
+ *   - mTxnDifficulty cannot be extracted from the body
+ *
+ * PureMinima performs authoritative work verification on submission; this
+ * function is a first-pass relay-side filter.
  *
- * Note: full structural parsing of TxPoW headers is deferred to a future
- * parser. PureMinima performs authoritative work verification on submission.
+ * @param txpowHex  Hex-encoded serialized TxPoW (TxHeader | 0x01 | TxBody).
  */
 function verifyTxPoWWork(txpowHex) {
     if (typeof txpowHex !== 'string' || !/^[0-9a-fA-F]+$/.test(txpowHex)) {
@@ -80,6 +218,15 @@ function verifyTxPoWWork(txpowHex) {
         };
     }
     const bytes = Uint8Array.from(Buffer.from(txpowHex, 'hex'));
+    // Attempt to parse the TxPoW into header + body using body-hash verification
+    const parsed = tryParseTxPoW(bytes);
+    if (parsed) {
+        return verifyTxPoWParts(parsed.headerBytes, parsed.bodyBytes);
+    }
+    // Fallback: use sha3_256 of the full bytes as a proxy id against the floor
     const proxyId = (0, serialization_js_1.computeTxPoWId)(bytes);
-    return verifyProofOfWork(proxyId, constants_js_1.TX_POW_MIN_DIFFICULTY);
+    return {
+        ...verifyProofOfWork(proxyId, constants_js_1.TX_POW_MIN_DIFFICULTY),
+        reason: 'could not parse TxPoW structure — used proxy id against floor difficulty',
+    };
 }

package/dist/workers/browser.worker.d.ts

@@ -0,0 +1,26 @@
+/**
+ * browser.worker.ts — Browser Web Worker entry point for TxPoW mining.
+ *
+ * This file is the Web Worker counterpart to node.worker.ts.
+ * It is designed to be bundled by the extension's build system (webpack / vite)
+ * as part of Task #114. It cannot be loaded directly from a CJS context.
+ *
+ * Usage (from the extension):
+ *   import MinerWorker from '@totemsdk/txpow/dist/workers/browser.worker.js?worker';
+ *   const worker = new MinerWorker();
+ *   worker.postMessage({ txBodyBytes, txnDifficulty, wasmUrl, options });
+ *   worker.onmessage = (e) => { const result: MineResult = e.data; };
+ *
+ * Communication protocol (mirrors node.worker.ts):
+ *   Input  (onmessage e.data): BrowserWorkerInput  — serialized mining parameters
+ *   Output (postMessage):      BrowserWorkerOutput — serialized MineResult or error
+ *
+ * WASM in the worker:
+ *   The browser Web Worker runs in its own JS context, so `setWasmUrl()` called
+ *   on the main thread does NOT carry over. Pass the WASM URL in the input
+ *   message (`wasmUrl` field) so the worker can call `setWasmUrl()` before
+ *   starting the mining loop. Without `wasmUrl`, the worker mines in pure JS.
+ *
+ * See mine.ts for details on the BigInt string encoding and Uint8Array [] encoding.
+ */
+export {};

package/dist/workers/browser.worker.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * browser.worker.ts — Browser Web Worker entry point for TxPoW mining.
+ *
+ * This file is the Web Worker counterpart to node.worker.ts.
+ * It is designed to be bundled by the extension's build system (webpack / vite)
+ * as part of Task #114. It cannot be loaded directly from a CJS context.
+ *
+ * Usage (from the extension):
+ *   import MinerWorker from '@totemsdk/txpow/dist/workers/browser.worker.js?worker';
+ *   const worker = new MinerWorker();
+ *   worker.postMessage({ txBodyBytes, txnDifficulty, wasmUrl, options });
+ *   worker.onmessage = (e) => { const result: MineResult = e.data; };
+ *
+ * Communication protocol (mirrors node.worker.ts):
+ *   Input  (onmessage e.data): BrowserWorkerInput  — serialized mining parameters
+ *   Output (postMessage):      BrowserWorkerOutput — serialized MineResult or error
+ *
+ * WASM in the worker:
+ *   The browser Web Worker runs in its own JS context, so `setWasmUrl()` called
+ *   on the main thread does NOT carry over. Pass the WASM URL in the input
+ *   message (`wasmUrl` field) so the worker can call `setWasmUrl()` before
+ *   starting the mining loop. Without `wasmUrl`, the worker mines in pure JS.
+ *
+ * See mine.ts for details on the BigInt string encoding and Uint8Array [] encoding.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/// <reference lib="webworker" />
+const mine_js_1 = require("../mine.js");
+const mine_wasm_js_1 = require("../mine-wasm.js");
+self.onmessage = async (e) => {
+    const input = e.data;
+    // Configure WASM inside this worker's JS context before mining starts.
+    // The main thread's setWasmUrl() call does not carry over to a Web Worker.
+    if (input.wasmUrl) {
+        (0, mine_wasm_js_1.setWasmUrl)(input.wasmUrl);
+    }
+    try {
+        const result = await (0, mine_js_1.mineTxPoWInProcess)(new Uint8Array(input.txBodyBytes), new Uint8Array(input.txnDifficulty), {
+            chunkSize: input.chunkSize,
+            maxIterations: input.maxIterations !== undefined
+                ? Number(input.maxIterations)
+                : undefined,
+            timeMilli: input.timeMilli !== undefined ? BigInt(input.timeMilli) : undefined,
+            forceJs: input.forceJs,
+            _skipWorker: true,
+        });
+        const output = {
+            minedHeaderBytes: Array.from(result.minedHeaderBytes),
+            txpowId: Array.from(result.txpowId),
+            nonce: result.nonce.toString(),
+            elapsedMs: result.elapsedMs,
+            source: result.source,
+        };
+        self.postMessage(output);
+    }
+    catch (err) {
+        const output = {
+            error: err instanceof Error ? err.message : String(err),
+        };
+        self.postMessage(output);
+    }
+};

package/dist/workers/node.worker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * node.worker.ts — Node.js worker_threads entry point for TxPoW mining.
+ *
+ * This file is compiled to `dist/workers/node.worker.js` and spawned by
+ * `mineTxPoW()` in the main thread via `new Worker(workerPath, { workerData })`.
+ *
+ * Communication protocol:
+ *   Input  (workerData): NodeWorkerInput  — serialized mining parameters
+ *   Output (postMessage): NodeWorkerOutput — serialized MineResult or error
+ *
+ * BigInt values (nonce, timeMilli, maxIterations) are transmitted as strings
+ * to avoid structured-clone limitations on older Node.js versions.
+ * Uint8Arrays are transmitted as number[] for reliable structured-clone transfer.
+ */
+declare const workerData: any, parentPort: import("worker_threads").MessagePort | null;
+declare const mineTxPoWInProcess: typeof import("../mine").mineTxPoWInProcess;
+interface NodeWorkerInput {
+    txBodyBytes: number[];
+    txnDifficulty: number[];
+    chunkSize?: number;
+    maxIterations?: string;
+    timeMilli?: string;
+    forceJs?: boolean;
+}
+interface NodeWorkerOutput {
+    minedHeaderBytes?: number[];
+    txpowId?: number[];
+    nonce?: string;
+    elapsedMs?: number;
+    source?: 'wasm' | 'js';
+    error?: string;
+}
+declare function run(): Promise<void>;

package/dist/workers/node.worker.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * node.worker.ts — Node.js worker_threads entry point for TxPoW mining.
+ *
+ * This file is compiled to `dist/workers/node.worker.js` and spawned by
+ * `mineTxPoW()` in the main thread via `new Worker(workerPath, { workerData })`.
+ *
+ * Communication protocol:
+ *   Input  (workerData): NodeWorkerInput  — serialized mining parameters
+ *   Output (postMessage): NodeWorkerOutput — serialized MineResult or error
+ *
+ * BigInt values (nonce, timeMilli, maxIterations) are transmitted as strings
+ * to avoid structured-clone limitations on older Node.js versions.
+ * Uint8Arrays are transmitted as number[] for reliable structured-clone transfer.
+ */
+/* eslint-disable @typescript-eslint/no-var-requires */
+const { workerData, parentPort } = require('worker_threads');
+const { mineTxPoWInProcess } = require('../mine');
+async function run() {
+    const input = workerData;
+    try {
+        const result = await mineTxPoWInProcess(new Uint8Array(input.txBodyBytes), new Uint8Array(input.txnDifficulty), {
+            chunkSize: input.chunkSize,
+            maxIterations: input.maxIterations !== undefined
+                ? Number(input.maxIterations)
+                : undefined,
+            timeMilli: input.timeMilli !== undefined ? BigInt(input.timeMilli) : undefined,
+            forceJs: input.forceJs,
+            _skipWorker: true,
+        });
+        const output = {
+            minedHeaderBytes: Array.from(result.minedHeaderBytes),
+            txpowId: Array.from(result.txpowId),
+            nonce: result.nonce.toString(),
+            elapsedMs: result.elapsedMs,
+            source: result.source,
+        };
+        parentPort?.postMessage(output);
+    }
+    catch (err) {
+        const output = {
+            error: err instanceof Error ? err.message : String(err),
+        };
+        parentPort?.postMessage(output);
+    }
+}
+run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totemsdk/txpow",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "TxPoW envelope serialization and proof-of-work mining for the Minima protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,11 +13,12 @@
   },
   "files": [
     "dist",
+    "src/wasm/miner.wasm",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@totemsdk/core": "^1.0.9"
+    "@totemsdk/core": "^1.1.0"
   },
   "peerDependencies": {
     "@noble/hashes": "^2.0.0"
@@ -64,6 +65,9 @@
   ],
   "scripts": {
     "build": "tsc",
+    "postbuild": "node -e \"const fs=require('fs'),p=require('path');const src=p.join(__dirname,'src','wasm','miner.wasm');const dst=p.join(__dirname,'dist','wasm','miner.wasm');if(fs.existsSync(src)){fs.mkdirSync(p.dirname(dst),{recursive:true});fs.copyFileSync(src,dst);console.log('[@totemsdk/txpow] miner.wasm → dist/wasm/')}else{console.log('[@totemsdk/txpow] Note: miner.wasm not compiled — JS fallback only. Run npm run build:wasm with Emscripten to enable WASM acceleration.')}\"",
+    "compile:wasm": "node scripts/compile-wasm.js",
+    "build:wasm": "npm run compile:wasm && npm run build",
     "clean": "rm -rf dist",
     "test": "jest --passWithNoTests"
   }