@totemsdk/txpow 1.0.1 → 1.1.0

package/dist/cjs/magic.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * magic.ts — Serialize the Minima Magic struct.
+ *
+ * Ported from the extension's MinimaTransactionBuilder.ts::serializeMagic().
+ * Matches Magic.writeDataStream() in Java exactly.
+ *
+ * Magic contains two copies of 4 fields (current + desired parameters):
+ *   maxTxPoWSize  (MiniNumber)
+ *   maxKISSVMOps  (MiniNumber)
+ *   maxTxnPerBlock(MiniNumber)
+ *   minTxPoWWork  (MiniData — 32 bytes)
+ *
+ * Default values from Magic.java:
+ *   maxTxPoWSize  = 65536
+ *   maxKISSVMOps  = 1024
+ *   maxTxnPerBlock = 256
+ *   minTxPoWWork  = MAX_HASH (all 0xFF, 32 bytes) — placeholder in fresh TxPoW
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeMagic = serializeMagic;
+const core_1 = require("@totemsdk/core");
+const constants_js_1 = require("./constants.js");
+function serializeMagic() {
+    const parts = [];
+    parts.push((0, core_1.writeMiniNumber)(65536n, 0));
+    parts.push((0, core_1.writeMiniNumber)(1024n, 0));
+    parts.push((0, core_1.writeMiniNumber)(256n, 0));
+    parts.push((0, core_1.writeMiniData)(constants_js_1.MAX_HASH));
+    parts.push((0, core_1.writeMiniNumber)(65536n, 0));
+    parts.push((0, core_1.writeMiniNumber)(1024n, 0));
+    parts.push((0, core_1.writeMiniNumber)(256n, 0));
+    parts.push((0, core_1.writeMiniData)(constants_js_1.MAX_HASH));
+    return (0, core_1.concat)(...parts);
+}

package/dist/cjs/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 @totemsdk/core
+ *   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/cjs/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 @totemsdk/core
+ *   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 core_1 = require("@totemsdk/core");
+/** 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 @totemsdk/core. */
+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, core_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/cjs/mine.d.ts

@@ -0,0 +1,131 @@
+/**
+ * mine.ts — Local TxPoW proof-of-work mining loop.
+ *
+ * Algorithm (from TxPoWChecker.java):
+ *   txpowId = SHA3-256( serialize(TxHeader) )
+ *   valid   = txpowId < mTxnDifficulty   (big-endian 256-bit comparison)
+ *
+ * Strategy:
+ *   1. The TxBody is fixed during mining — only mNonce in the header changes.
+ *   2. We precompute the "header tail" (everything after mNonce) once per mine.
+ *   3. Within each chunk (fixed nonce encoding length), we update only the nonce
+ *      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 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. */
+    minedHeaderBytes: Uint8Array;
+    /** SHA3-256(minedHeaderBytes) — the canonical TxPoW ID. */
+    txpowId: Uint8Array;
+    nonce: bigint;
+    elapsedMs: number;
+    /** 'wasm' when the pre-compiled WASM binary found the nonce; 'js' otherwise. */
+    source: 'wasm' | 'js';
+}
+export interface MineOptions {
+    /**
+     * Hash iterations per async yield (default: 10_000).
+     * Lower = more responsive UI; higher = slightly faster mining.
+     */
+    chunkSize?: number;
+    /**
+     * Hard cap on total iterations (default: unlimited).
+     * Throws if exhausted without finding a valid nonce.
+     */
+    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;
+/**
+ * Build the "header tail" — the part of TxHeader that follows mNonce.
+ *
+ * This is computed once at the start of a mine and never changes during it.
+ *
+ * This is the fresh-transaction header shape (blockNumber=0, MAX_HASH block
+ * difficulty, zero super-parents, zero MMR, zero customHash). Block-candidate
+ * mining (Machine Work Admission) builds its own tail via
+ * `admission/template.ts` with real chain state and a customHash commitment.
+ */
+export declare function buildHeaderTail(txBodyHash: Uint8Array, timeMilli: bigint): Uint8Array;
+/**
+ * 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;
+/**
+ * Core mining loop over a pre-built header tail.
+ *
+ * Iterates the nonce in the serialized TxHeader (nonce value at offset 2,
+ * followed by `headerTail`) until `SHA3-256(header) < target`. Shared by the
+ * transaction miner (`mineTxPoWInProcess`) and the Machine Work Admission
+ * miner (`admission/mine.ts`), which supplies its own block-candidate tail.
+ *
+ * @param headerTail  Serialized TxHeader bytes AFTER the nonce field.
+ * @param target      32-byte difficulty target (big-endian 256-bit).
+ * @param options     Chunk size, max iterations, abort signal, timeMilli override.
+ */
+export declare function mineHeaderTail(headerTail: Uint8Array, target: Uint8Array, options?: MineOptions): Promise<MineResult>;
+/**
+ * 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.
+ * @param options       Chunk size, max iterations, abort signal, timeMilli override.
+ */
+export declare function mineTxPoW(txBodyBytes: Uint8Array, txnDifficulty: Uint8Array, options?: MineOptions): Promise<MineResult>;