@totemsdk/txpow 1.0.2 → 1.1.1

package/dist/cjs/serialization.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * serialization.ts — TxPoW envelope serialization.
+ *
+ * Ports serializeTxHeader / serializeTxBody / serializeTxPoW from
+ * packages/totem-extension/src/core/transaction/MinimaTransactionBuilder.ts
+ * into the standalone @totemsdk/txpow package.
+ *
+ * KEY DESIGN DECISIONS
+ * ─────────────────────────────────────────────────────────────────────────
+ * • serializeTxBody accepts PRE-SERIALIZED transaction bytes and witness bytes.
+ *   Callers use @totemsdk/core's serializeTransaction() + their own witness
+ *   serializer, then pass the byte arrays here. This keeps @totemsdk/txpow
+ *   free of WotsSignatureData / InputScriptInfo / CoinProof dependencies.
+ *
+ * • txnDifficulty defaults to MAX_HASH (all 0xFF) to produce byte-identical
+ *   output to the extension's current MEG-mined path. For locally mined TxPoWs
+ *   the caller MUST pass a value ≤ TX_POW_MIN_DIFFICULTY, otherwise the
+ *   transaction will fail TxPoWChecker.checkTxPoWSimple() at block inclusion.
+ *
+ * • nonce defaults to 0n (the mining loop updates it). timeMilli defaults to
+ *   Date.now() at call time.
+ *
+ * WIRE FORMAT REFERENCE
+ * ─────────────────────────────────────────────────────────────────────────
+ * TxHeader.writeDataStream():
+ *   1. mNonce           MiniNumber
+ *   2. mChainID         MiniData   (MAIN_NET = [0x00])
+ *   3. mTimeMilli       MiniNumber
+ *   4. mBlockNumber     MiniNumber (0 for fresh TxPoW)
+ *   5. mBlockDifficulty MiniData   (MAX_HASH for fresh TxPoW)
+ *   6. Super Parents    RLE: 1 byte count + writeHashToStream(parent)
+ *   7. mMMRRoot         writeHashToStream (ZERO_HASH for fresh TxPoW)
+ *   8. mMMRTotal        MiniNumber (0)
+ *   9. mMagic           Magic.writeDataStream()
+ *  10. mCustomHash      writeHashToStream (ZERO_HASH)
+ *  11. mTxBodyHash      writeHashToStream
+ *
+ * TxBody.writeDataStream():
+ *   1. mPRNG            writeHashToStream (32 random bytes)
+ *   2. mTxnDifficulty   MiniData
+ *   3. mTransaction     Transaction.writeDataStream() (pre-serialized)
+ *   4. mWitness         Witness.writeDataStream() (pre-serialized)
+ *   5. mBurnTransaction Transaction.writeDataStream() (empty)
+ *   6. mBurnWitness     Witness.writeDataStream() (empty)
+ *   7. mTxPowIDList     MiniNumber(0)
+ *
+ * TxPoW.writeDataStream():
+ *   TxHeader bytes + MiniByte(0x01=hasBody) + TxBody bytes
+ *
+ * TxPoW ID:
+ *   SHA3-256( TxHeader bytes )  — Java: Crypto.getInstance().hashObject(mHeader)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeTxHeader = serializeTxHeader;
+exports.computeTxPoWId = computeTxPoWId;
+exports.serializeTxBody = serializeTxBody;
+exports.serializeTxPoW = serializeTxPoW;
+const core_1 = require("@totemsdk/core");
+const core_2 = require("@totemsdk/core");
+const magic_js_1 = require("./magic.js");
+const constants_js_1 = require("./constants.js");
+/**
+ * Serialize a TxHeader per Minima's TxHeader.writeDataStream().
+ *
+ * @param txBodyHash  SHA3-256 of the serialized TxBody (32 bytes)
+ * @param options     Optional nonce and timeMilli overrides
+ */
+function serializeTxHeader(txBodyHash, options) {
+    const nonce = options?.nonce ?? 0n;
+    const timeMilli = options?.timeMilli ?? BigInt(Date.now());
+    const parts = [];
+    parts.push((0, core_2.writeMiniNumber)(nonce, 0));
+    parts.push((0, core_2.writeMiniData)(constants_js_1.MAIN_NET_CHAIN_ID));
+    parts.push((0, core_2.writeMiniNumber)(timeMilli, 0));
+    parts.push((0, core_2.writeMiniNumber)(0n, 0));
+    parts.push((0, core_2.writeMiniData)(constants_js_1.MAX_HASH));
+    parts.push(new Uint8Array([constants_js_1.CASCADE_LEVELS]));
+    parts.push((0, core_2.writeHashToStream)(constants_js_1.ZERO_HASH));
+    parts.push((0, core_2.writeHashToStream)(constants_js_1.ZERO_HASH));
+    parts.push((0, core_2.writeMiniNumber)(0n, 0));
+    parts.push((0, magic_js_1.serializeMagic)());
+    parts.push((0, core_2.writeHashToStream)(constants_js_1.ZERO_HASH));
+    parts.push((0, core_2.writeHashToStream)(txBodyHash));
+    return (0, core_2.concat)(...parts);
+}
+/**
+ * Compute TxPoW ID = SHA3-256(TxHeader bytes).
+ * Matches Java: Crypto.getInstance().hashObject(mHeader) via SHA3Digest(256).
+ */
+function computeTxPoWId(headerBytes) {
+    return (0, core_1.sha3_256)(headerBytes);
+}
+/**
+ * Build the empty burn transaction bytes.
+ *
+ * Equivalent to serializeTransaction({ linkHash: new Uint8Array([0x00]),
+ *                                       inputs: [], outputs: [], state: [] })
+ * which produces:
+ *   writeMiniNumber(0n)              inputs count
+ *   writeMiniNumber(0n)              outputs count
+ *   writeMiniNumber(0n)              state count
+ *   writeHashToStream([0x00])        linkHash = ZERO_TXPOWID (1 byte)
+ */
+function buildEmptyBurnTxBytes() {
+    return (0, core_2.concat)((0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeHashToStream)(new Uint8Array([0x00])));
+}
+/**
+ * Build the empty burn witness bytes.
+ *
+ * Equivalent to serializeWitness() with no arguments:
+ *   writeMiniNumber(0n)   signature count
+ *   writeMiniNumber(0n)   coinproof count
+ *   writeMiniNumber(0n)   scriptproof count
+ */
+function buildEmptyBurnWitnessBytes() {
+    return (0, core_2.concat)((0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0));
+}
+/**
+ * Serialize a TxBody per Minima's TxBody.writeDataStream().
+ *
+ * @param txBytes       Pre-serialized Transaction bytes (from @totemsdk/core's serializeTransaction)
+ * @param witnessBytes  Pre-serialized Witness bytes (from extension's serializeWitness)
+ * @param options       Optional txnDifficulty override and test PRNG
+ */
+function serializeTxBody(txBytes, witnessBytes, options) {
+    const txnDifficulty = options?.txnDifficulty ?? constants_js_1.MAX_HASH;
+    let prng;
+    if (options?.prng) {
+        prng = options.prng;
+    }
+    else {
+        const fresh = new Uint8Array(32);
+        if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
+            throw new Error('SECURITY: crypto.getRandomValues unavailable — cannot generate secure random bytes for transaction PRNG');
+        }
+        crypto.getRandomValues(fresh);
+        prng = fresh;
+    }
+    return (0, core_2.concat)((0, core_2.writeHashToStream)(prng), (0, core_2.writeMiniData)(txnDifficulty), txBytes, witnessBytes, buildEmptyBurnTxBytes(), buildEmptyBurnWitnessBytes(), (0, core_2.writeMiniNumber)(0n, 0));
+}
+/**
+ * Serialize a complete TxPoW per Minima's TxPoW.writeDataStream().
+ *
+ * Assembles TxBody from pre-serialized tx+witness bytes, hashes the body to
+ * obtain mTxBodyHash, builds TxHeader with nonce=0, then concatenates:
+ *   TxHeader | 0x01 (hasBody) | TxBody
+ *
+ * The returned bytes have nonce=0. Pass them to mineTxPoW() to find a valid
+ * nonce for local mining, or send as-is when MEG will re-mine.
+ *
+ * @param txBytes       Pre-serialized Transaction bytes
+ * @param witnessBytes  Pre-serialized Witness bytes
+ * @param options       Optional txnDifficulty, nonce, timeMilli, prng
+ */
+function serializeTxPoW(txBytes, witnessBytes, options) {
+    const txBody = serializeTxBody(txBytes, witnessBytes, options);
+    const txBodyHash = (0, core_1.sha3_256)(txBody);
+    return (0, core_2.concat)(serializeTxHeader(txBodyHash, options), new Uint8Array([0x01]), txBody);
+}

package/dist/cjs/verify.d.ts

@@ -0,0 +1,76 @@
+/**
+ * verify.ts — TxPoW proof-of-work verification.
+ *
+ * verifyProofOfWork checks that a given txpowId beats the difficulty target
+ * without re-mining. Used by relay nodes to reject under-work submissions.
+ *
+ * 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;
+    txpowId: string;
+    difficulty: string;
+    reason?: string;
+}
+/**
+ * Verify that a TxPoW ID beats the stated difficulty target.
+ *
+ * valid = txpowId < mTxnDifficulty (big-endian 256-bit comparison)
+ *
+ * @param txpowId        The 32-byte TxPoW ID (SHA3-256 of the header).
+ * @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.
+ *
+ * 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.
+ *
+ * @param txpowHex  Hex-encoded serialized TxPoW (TxHeader | 0x01 | TxBody).
+ */
+export declare function verifyTxPoWWork(txpowHex: string): VerifyResult;

package/dist/cjs/verify.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * verify.ts — TxPoW proof-of-work verification.
+ *
+ * verifyProofOfWork checks that a given txpowId beats the difficulty target
+ * without re-mining. Used by relay nodes to reject under-work submissions.
+ *
+ * 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.
+ *
+ * valid = txpowId < mTxnDifficulty (big-endian 256-bit comparison)
+ *
+ * @param txpowId        The 32-byte TxPoW ID (SHA3-256 of the header).
+ * @param mTxnDifficulty The 32-byte difficulty target from the TxBody.
+ */
+function verifyProofOfWork(txpowId, mTxnDifficulty) {
+    if (txpowId.length !== 32) {
+        return {
+            valid: false,
+            txpowId: toHex(txpowId),
+            difficulty: toHex(mTxnDifficulty),
+            reason: `txpowId must be 32 bytes, got ${txpowId.length}`,
+        };
+    }
+    if (mTxnDifficulty.length !== 32) {
+        return {
+            valid: false,
+            txpowId: toHex(txpowId),
+            difficulty: toHex(mTxnDifficulty),
+            reason: `mTxnDifficulty must be 32 bytes, got ${mTxnDifficulty.length}`,
+        };
+    }
+    const valid = (0, mine_js_1.isLessThan)(txpowId, mTxnDifficulty);
+    return {
+        valid,
+        txpowId: toHex(txpowId),
+        difficulty: toHex(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.
+ *
+ * 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.
+ *
+ * @param txpowHex  Hex-encoded serialized TxPoW (TxHeader | 0x01 | TxBody).
+ */
+function verifyTxPoWWork(txpowHex) {
+    if (typeof txpowHex !== 'string' || !/^[0-9a-fA-F]+$/.test(txpowHex)) {
+        return {
+            valid: false,
+            txpowId: '',
+            difficulty: toHex(constants_js_1.TX_POW_MIN_DIFFICULTY),
+            reason: 'invalid hex encoding',
+        };
+    }
+    if (txpowHex.length < 200) {
+        return {
+            valid: false,
+            txpowId: '',
+            difficulty: toHex(constants_js_1.TX_POW_MIN_DIFFICULTY),
+            reason: 'TxPoW too short (spam filter: minimum 100 bytes)',
+        };
+    }
+    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),
+        reason: 'could not parse TxPoW structure — used proxy id against floor difficulty',
+    };
+}

package/dist/cjs/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/cjs/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/cjs/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.js").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/cjs/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.js');
+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/dist/constants.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * constants.ts — TxPoW-level constants matching Minima Java protocol values.
  *
@@ -11,11 +10,9 @@
  * MAIN_NET_CHAIN_ID:      1-byte [0x00] — Java MiniData("0x00") = MAIN_NET chain ID.
  * CASCADE_LEVELS:         32 — number of super-parent slots in a fresh TxPoW header.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAIN_NET_CHAIN_ID = exports.TX_POW_MIN_DIFFICULTY = exports.MAX_HASH = exports.ZERO_HASH = exports.CASCADE_LEVELS = void 0;
-exports.CASCADE_LEVELS = 32;
-exports.ZERO_HASH = new Uint8Array(32);
-exports.MAX_HASH = (() => {
+export const CASCADE_LEVELS = 32;
+export const ZERO_HASH = new Uint8Array(32);
+export const MAX_HASH = (() => {
     const b = new Uint8Array(32);
     b.fill(0xff);
     return b;
@@ -30,7 +27,7 @@ exports.MAX_HASH = (() => {
  * Computed: (2n**256n - 1n) / 1_000_000n
  * Hex: 0x000010C6F7A0B5ED8538AACDD46595F0C7AC73E0E9DBF12F70000000000000000
  */
-exports.TX_POW_MIN_DIFFICULTY = (() => {
+export const TX_POW_MIN_DIFFICULTY = (() => {
     const maxHashBigInt = (2n ** 256n) - 1n;
     const minDiffBigInt = maxHashBigInt / 1000000n;
     let hex = minDiffBigInt.toString(16);
@@ -44,4 +41,4 @@ exports.TX_POW_MIN_DIFFICULTY = (() => {
     }
     return bytes;
 })();
-exports.MAIN_NET_CHAIN_ID = new Uint8Array([0x00]);
+export const MAIN_NET_CHAIN_ID = new Uint8Array([0x00]);