@totemsdk/txpow 0.1.5 → 0.1.7

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 core_1 = require("@totemsdk/core");
 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, core_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,15 @@
+/**
+ * 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.
+ */
+export {};

package/dist/workers/node.worker.js

@@ -0,0 +1,48 @@
+"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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/* 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.7",
   "description": "TxPoW envelope serialization and proof-of-work mining for the Minima protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,23 +17,14 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@totemsdk/core": "^1.0.9"
-  },
-  "peerDependencies": {
-    "@noble/hashes": "^2.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@noble/hashes": {
-      "optional": false
-    }
+    "@totemsdk/core": "^1.2.8"
   },
   "devDependencies": {
-    "@noble/hashes": "^2.2.0",
-    "@types/jest": "^29.0.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
-    "jest": "^29.0.0",
+    "jest": "^30.4.2",
     "ts-jest": "^29.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=16.0.0"
@@ -43,14 +34,14 @@
   },
   "license": "MIT",
   "author": "Totem SDK",
-  "homepage": "https://totemsdk.com",
+  "homepage": "https://totem.ing",
   "bugs": {
-    "url": "https://github.com/MrGheek/axia-totem/issues"
+    "url": "https://github.com/totem-sdk/totem-sdk/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/MrGheek/axia-totem.git",
-    "directory": "packages/totem-sdk/packages/txpow"
+    "url": "git+https://github.com/totem-sdk/totem-sdk.git",
+    "directory": "packages/txpow"
   },
   "keywords": [
     "totem",
@@ -59,12 +50,14 @@
     "blockchain",
     "quantum-resistant",
     "wots",
-    "kissvm",
     "utxo"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "npm run build:wasm && 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",
     "clean": "rm -rf dist",
-    "test": "jest --passWithNoTests"
+    "test": "jest"
   }
 }