@totemsdk/txpow 1.0.2 → 1.1.0

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]);

package/dist/difficulty.d.ts

@@ -8,6 +8,30 @@
 export interface TxPowParams {
     minTxPowWork: string;
 }
+/** Anything that can expose a node's live minimum TxPoW work (hex). */
+export interface MinWorkSource {
+    getMinTxPowWork?(): Promise<string | null>;
+}
+/**
+ * Convert a live `currentmintxpowwork` value (32-byte hex target) into a mining
+ * target, applying the same 10% margin the node's own wallet uses
+ * (`minwork * 10 / 11`, see Java `TxPoWGenerator.generateTxPoW`).
+ *
+ * `TxPoWChecker.checkTxPoWSimple` rejects only when
+ * `txnDifficulty > magic.getMinTxPowWork()`, so a target that is harder than
+ * the live minimum is always accepted; the margin absorbs the tiny per-block
+ * Magic retarget.
+ */
+export declare function targetFromMinWork(minWorkHex: string): Uint8Array;
+/**
+ * Resolve the TxPoW mining target from a live node when it exposes
+ * `getMinTxPowWork()`, otherwise fall back to `TX_POW_MIN_DIFFICULTY`.
+ *
+ * Never throws: a node/protocol hiccup must not block transaction
+ * construction. The fallback is the protocol default target (MAX/1e6), which
+ * is harder than the network hard floor (`Magic.MIN_HASHES = 10000`).
+ */
+export declare function resolveTxPowTarget(source?: MinWorkSource | null, fallback?: Uint8Array): Promise<Uint8Array>;
 /**
  * Fetch the current minimum TxPoW work from the Axia API.
  *

package/dist/difficulty.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * difficulty.ts — Fetch and manage the TxPoW difficulty target.
  *
@@ -6,9 +5,58 @@
  * On any error (timeout, network failure, invalid response) we fall back to
  * the hardcoded TX_POW_MIN_DIFFICULTY constant, which is the protocol floor.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fetchTxPowTarget = fetchTxPowTarget;
-const constants_js_1 = require("./constants.js");
+import { TX_POW_MIN_DIFFICULTY } from './constants.js';
+/**
+ * Convert a live `currentmintxpowwork` value (32-byte hex target) into a mining
+ * target, applying the same 10% margin the node's own wallet uses
+ * (`minwork * 10 / 11`, see Java `TxPoWGenerator.generateTxPoW`).
+ *
+ * `TxPoWChecker.checkTxPoWSimple` rejects only when
+ * `txnDifficulty > magic.getMinTxPowWork()`, so a target that is harder than
+ * the live minimum is always accepted; the margin absorbs the tiny per-block
+ * Magic retarget.
+ */
+export function targetFromMinWork(minWorkHex) {
+    const clean = minWorkHex.replace(/^0x/i, '').trim();
+    if (clean.length === 0 || clean.length > 64 || !/^[0-9a-fA-F]+$/.test(clean)) {
+        throw new Error(`Invalid minTxPowWork: ${minWorkHex}`);
+    }
+    const value = BigInt('0x' + clean);
+    const adjusted = (value * 10n) / 11n;
+    const target = adjusted > 0n ? adjusted : value;
+    let hex = target.toString(16);
+    if (hex.length % 2 !== 0)
+        hex = '0' + hex;
+    while (hex.length < 64)
+        hex = '0' + hex;
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/**
+ * Resolve the TxPoW mining target from a live node when it exposes
+ * `getMinTxPowWork()`, otherwise fall back to `TX_POW_MIN_DIFFICULTY`.
+ *
+ * Never throws: a node/protocol hiccup must not block transaction
+ * construction. The fallback is the protocol default target (MAX/1e6), which
+ * is harder than the network hard floor (`Magic.MIN_HASHES = 10000`).
+ */
+export async function resolveTxPowTarget(source, fallback = TX_POW_MIN_DIFFICULTY) {
+    try {
+        const hex = await source?.getMinTxPowWork?.();
+        if (hex) {
+            const target = targetFromMinWork(hex);
+            if (target.some((b) => b !== 0))
+                return target;
+        }
+    }
+    catch {
+        // fall through to the constant
+    }
+    return new Uint8Array(fallback);
+}
 function hexToBytes(hex) {
     const h = hex.startsWith('0x') ? hex.slice(2) : hex;
     const out = new Uint8Array(h.length / 2);
@@ -26,7 +74,7 @@ function hexToBytes(hex) {
  * @param axiaBaseUrl  Base URL of the Axia API, e.g. "https://api.axia.to"
  * @param timeoutMs    Request timeout in ms (default: 3000)
  */
-async function fetchTxPowTarget(axiaBaseUrl, timeoutMs = 3000) {
+export async function fetchTxPowTarget(axiaBaseUrl, timeoutMs = 3000) {
     try {
         const base = axiaBaseUrl.replace(/\/$/, '');
         const url = `${base}/v1/wallet/txpow-params`;
@@ -53,6 +101,6 @@ async function fetchTxPowTarget(axiaBaseUrl, timeoutMs = 3000) {
         return hexToBytes(clean);
     }
     catch {
-        return new Uint8Array(constants_js_1.TX_POW_MIN_DIFFICULTY);
+        return new Uint8Array(TX_POW_MIN_DIFFICULTY);
     }
 }

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { MAX_HASH, ZERO_HASH, TX_POW_MIN_DIFFICULTY, CASCADE_LEVELS, MAIN_NET_CH
 export { serializeMagic } from './magic.js';
 export { mineTxPoW, mineTxPoWInProcess, mineHeaderTail, buildHeaderTail, 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 { fetchTxPowTarget, targetFromMinWork, resolveTxPowTarget, type TxPowParams, type MinWorkSource, } from './difficulty.js';
 export { verifyProofOfWork, verifyTxPoWWork, verifyTxPoWParts, type VerifyResult } from './verify.js';
 export { calibrateHashRate, estimateMiningCost, type MiningEstimate, } from './calibrate.js';
 export { createWorkChallenge, validateWorkChallenge, challengeFingerprint, canonicalChallenge, computeActionCommitment, canonicalAction, mineWorkAdmission, verifyWorkAdmission, buildBlockHeaderTail, serializeSuperParents, isBlockWinner, computeSuperLevel, templateFreshness, computeBlockCandidateId, buildEmptyBlockBody, buildEmptyTransactionBytes, buildEmptyWitnessBytes, buildEmptyBurnTxBytes, buildEmptyBurnWitnessBytes, assembleTxPoWEnvelope, reconstructTxPoWEnvelope, MACHINE_WORK_ADMISSION_VERSION, MACHINE_WORK_DOMAIN, DEFAULT_CHALLENGE_TTL_MS, MAX_CHALLENGE_TTL_MS, type WorkChallenge, type MachineWorkAction, type MinimaWorkTemplate, type MinimaWorkTemplateProvider, type MinimaWorkRelay, type MachineWorkAdmissionProof, type WorkAdmissionVerification, type MineWorkAdmissionOptions, type VerifyWorkAdmissionOptions, } from './admission/index.js';