@totemsdk/txpow 1.0.2 → 1.1.1

package/dist/cjs/difficulty.d.ts

@@ -0,0 +1,44 @@
+/**
+ * difficulty.ts — Fetch and manage the TxPoW difficulty target.
+ *
+ * The live value comes from `GET /v1/wallet/txpow-params` on the Axia API.
+ * On any error (timeout, network failure, invalid response) we fall back to
+ * the hardcoded TX_POW_MIN_DIFFICULTY constant, which is the protocol floor.
+ */
+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.
+ *
+ * Falls back to TX_POW_MIN_DIFFICULTY (the hardcoded protocol floor) on any
+ * error: network failure, timeout, or malformed response.
+ *
+ * @param axiaBaseUrl  Base URL of the Axia API, e.g. "https://api.axia.to"
+ * @param timeoutMs    Request timeout in ms (default: 3000)
+ */
+export declare function fetchTxPowTarget(axiaBaseUrl: string, timeoutMs?: number): Promise<Uint8Array>;

package/dist/cjs/difficulty.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * difficulty.ts — Fetch and manage the TxPoW difficulty target.
+ *
+ * The live value comes from `GET /v1/wallet/txpow-params` on the Axia API.
+ * 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.targetFromMinWork = targetFromMinWork;
+exports.resolveTxPowTarget = resolveTxPowTarget;
+exports.fetchTxPowTarget = fetchTxPowTarget;
+const constants_js_1 = require("./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.
+ */
+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`).
+ */
+async function resolveTxPowTarget(source, fallback = constants_js_1.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);
+    for (let i = 0; i < h.length; i += 2) {
+        out[i / 2] = parseInt(h.slice(i, i + 2), 16);
+    }
+    return out;
+}
+/**
+ * Fetch the current minimum TxPoW work from the Axia API.
+ *
+ * Falls back to TX_POW_MIN_DIFFICULTY (the hardcoded protocol floor) on any
+ * error: network failure, timeout, or malformed response.
+ *
+ * @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) {
+    try {
+        const base = axiaBaseUrl.replace(/\/$/, '');
+        const url = `${base}/v1/wallet/txpow-params`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await fetch(url, { signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        const data = (await response.json());
+        if (typeof data.minTxPowWork !== 'string') {
+            throw new Error('Missing minTxPowWork field');
+        }
+        const clean = data.minTxPowWork.replace('0x', '').replace(/\s/g, '');
+        if (clean.length !== 64) {
+            throw new Error(`Invalid minTxPowWork length: ${clean.length} (expected 64 hex chars)`);
+        }
+        return hexToBytes(clean);
+    }
+    catch {
+        return new Uint8Array(constants_js_1.TX_POW_MIN_DIFFICULTY);
+    }
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @totemsdk/txpow
+ *
+ * TxPoW envelope serialization and proof-of-work mining for the Minima protocol.
+ *
+ * USAGE — MEG-side mining (byte-identical to extension current behaviour):
+ *   const txpow = serializeTxPoW(txBytes, witnessBytes);
+ *   // Submit to Axia: node re-mines with correct difficulty
+ *
+ * USAGE — Local mining:
+ *   const target  = await fetchTxPowTarget(axiaBaseUrl);
+ *   const txBody  = serializeTxBody(txBytes, witnessBytes, { txnDifficulty: target });
+ *   const result  = await mineTxPoW(txBody, target);
+ *   const txpow   = concat(result.minedHeaderBytes, new Uint8Array([0x01]), txBody);
+ *
+ * USAGE — Verify (relay nodes):
+ *   const check = verifyProofOfWork(txpowId, mTxnDifficulty);
+ *   if (!check.valid) drop(check.reason);
+ */
+export { serializeTxHeader, serializeTxBody, serializeTxPoW, computeTxPoWId, type TxHeaderOptions, type TxBodyOptions, type TxPoWOptions, } from './serialization.js';
+export { MAX_HASH, ZERO_HASH, TX_POW_MIN_DIFFICULTY, CASCADE_LEVELS, MAIN_NET_CHAIN_ID, } from './constants.js';
+export { serializeMagic } from './magic.js';
+export { mineTxPoW, mineTxPoWInProcess, mineHeaderTail, buildHeaderTail, isLessThan, setBrowserWorkerUrl, type MineResult, type MineOptions, } from './mine.js';
+export { setWasmUrl, getBrowserWasmUrl, isWasmAvailable } from './mine-wasm.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';

package/dist/cjs/index.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * @totemsdk/txpow
+ *
+ * TxPoW envelope serialization and proof-of-work mining for the Minima protocol.
+ *
+ * USAGE — MEG-side mining (byte-identical to extension current behaviour):
+ *   const txpow = serializeTxPoW(txBytes, witnessBytes);
+ *   // Submit to Axia: node re-mines with correct difficulty
+ *
+ * USAGE — Local mining:
+ *   const target  = await fetchTxPowTarget(axiaBaseUrl);
+ *   const txBody  = serializeTxBody(txBytes, witnessBytes, { txnDifficulty: target });
+ *   const result  = await mineTxPoW(txBody, target);
+ *   const txpow   = concat(result.minedHeaderBytes, new Uint8Array([0x01]), txBody);
+ *
+ * USAGE — Verify (relay nodes):
+ *   const check = verifyProofOfWork(txpowId, mTxnDifficulty);
+ *   if (!check.valid) drop(check.reason);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MACHINE_WORK_DOMAIN = exports.MACHINE_WORK_ADMISSION_VERSION = exports.reconstructTxPoWEnvelope = exports.assembleTxPoWEnvelope = exports.buildEmptyBurnWitnessBytes = exports.buildEmptyBurnTxBytes = exports.buildEmptyWitnessBytes = exports.buildEmptyTransactionBytes = exports.buildEmptyBlockBody = exports.computeBlockCandidateId = exports.templateFreshness = exports.computeSuperLevel = exports.isBlockWinner = exports.serializeSuperParents = exports.buildBlockHeaderTail = exports.verifyWorkAdmission = exports.mineWorkAdmission = exports.canonicalAction = exports.computeActionCommitment = exports.canonicalChallenge = exports.challengeFingerprint = exports.validateWorkChallenge = exports.createWorkChallenge = exports.estimateMiningCost = exports.calibrateHashRate = exports.verifyTxPoWParts = exports.verifyTxPoWWork = exports.verifyProofOfWork = exports.resolveTxPowTarget = exports.targetFromMinWork = exports.fetchTxPowTarget = exports.isWasmAvailable = exports.getBrowserWasmUrl = exports.setWasmUrl = exports.setBrowserWorkerUrl = exports.isLessThan = exports.buildHeaderTail = exports.mineHeaderTail = exports.mineTxPoWInProcess = exports.mineTxPoW = exports.serializeMagic = exports.MAIN_NET_CHAIN_ID = exports.CASCADE_LEVELS = exports.TX_POW_MIN_DIFFICULTY = exports.ZERO_HASH = exports.MAX_HASH = exports.computeTxPoWId = exports.serializeTxPoW = exports.serializeTxBody = exports.serializeTxHeader = void 0;
+exports.MAX_CHALLENGE_TTL_MS = exports.DEFAULT_CHALLENGE_TTL_MS = void 0;
+var serialization_js_1 = require("./serialization.js");
+Object.defineProperty(exports, "serializeTxHeader", { enumerable: true, get: function () { return serialization_js_1.serializeTxHeader; } });
+Object.defineProperty(exports, "serializeTxBody", { enumerable: true, get: function () { return serialization_js_1.serializeTxBody; } });
+Object.defineProperty(exports, "serializeTxPoW", { enumerable: true, get: function () { return serialization_js_1.serializeTxPoW; } });
+Object.defineProperty(exports, "computeTxPoWId", { enumerable: true, get: function () { return serialization_js_1.computeTxPoWId; } });
+var constants_js_1 = require("./constants.js");
+Object.defineProperty(exports, "MAX_HASH", { enumerable: true, get: function () { return constants_js_1.MAX_HASH; } });
+Object.defineProperty(exports, "ZERO_HASH", { enumerable: true, get: function () { return constants_js_1.ZERO_HASH; } });
+Object.defineProperty(exports, "TX_POW_MIN_DIFFICULTY", { enumerable: true, get: function () { return constants_js_1.TX_POW_MIN_DIFFICULTY; } });
+Object.defineProperty(exports, "CASCADE_LEVELS", { enumerable: true, get: function () { return constants_js_1.CASCADE_LEVELS; } });
+Object.defineProperty(exports, "MAIN_NET_CHAIN_ID", { enumerable: true, get: function () { return constants_js_1.MAIN_NET_CHAIN_ID; } });
+var magic_js_1 = require("./magic.js");
+Object.defineProperty(exports, "serializeMagic", { enumerable: true, get: function () { return magic_js_1.serializeMagic; } });
+var mine_js_1 = require("./mine.js");
+Object.defineProperty(exports, "mineTxPoW", { enumerable: true, get: function () { return mine_js_1.mineTxPoW; } });
+Object.defineProperty(exports, "mineTxPoWInProcess", { enumerable: true, get: function () { return mine_js_1.mineTxPoWInProcess; } });
+Object.defineProperty(exports, "mineHeaderTail", { enumerable: true, get: function () { return mine_js_1.mineHeaderTail; } });
+Object.defineProperty(exports, "buildHeaderTail", { enumerable: true, get: function () { return mine_js_1.buildHeaderTail; } });
+Object.defineProperty(exports, "isLessThan", { enumerable: true, get: function () { return mine_js_1.isLessThan; } });
+Object.defineProperty(exports, "setBrowserWorkerUrl", { enumerable: true, get: function () { return mine_js_1.setBrowserWorkerUrl; } });
+var mine_wasm_js_1 = require("./mine-wasm.js");
+Object.defineProperty(exports, "setWasmUrl", { enumerable: true, get: function () { return mine_wasm_js_1.setWasmUrl; } });
+Object.defineProperty(exports, "getBrowserWasmUrl", { enumerable: true, get: function () { return mine_wasm_js_1.getBrowserWasmUrl; } });
+Object.defineProperty(exports, "isWasmAvailable", { enumerable: true, get: function () { return mine_wasm_js_1.isWasmAvailable; } });
+var difficulty_js_1 = require("./difficulty.js");
+Object.defineProperty(exports, "fetchTxPowTarget", { enumerable: true, get: function () { return difficulty_js_1.fetchTxPowTarget; } });
+Object.defineProperty(exports, "targetFromMinWork", { enumerable: true, get: function () { return difficulty_js_1.targetFromMinWork; } });
+Object.defineProperty(exports, "resolveTxPowTarget", { enumerable: true, get: function () { return difficulty_js_1.resolveTxPowTarget; } });
+var verify_js_1 = require("./verify.js");
+Object.defineProperty(exports, "verifyProofOfWork", { enumerable: true, get: function () { return verify_js_1.verifyProofOfWork; } });
+Object.defineProperty(exports, "verifyTxPoWWork", { enumerable: true, get: function () { return verify_js_1.verifyTxPoWWork; } });
+Object.defineProperty(exports, "verifyTxPoWParts", { enumerable: true, get: function () { return verify_js_1.verifyTxPoWParts; } });
+var calibrate_js_1 = require("./calibrate.js");
+Object.defineProperty(exports, "calibrateHashRate", { enumerable: true, get: function () { return calibrate_js_1.calibrateHashRate; } });
+Object.defineProperty(exports, "estimateMiningCost", { enumerable: true, get: function () { return calibrate_js_1.estimateMiningCost; } });
+// ── Machine Work Admission ──────────────────────────────────────────────────
+// Receiver-controlled computational admission bound to a real Minima block
+// candidate. The same nonce search that admits a machine action also searches
+// for Minima blocks (Super-0 … Super-31).
+var index_js_1 = require("./admission/index.js");
+Object.defineProperty(exports, "createWorkChallenge", { enumerable: true, get: function () { return index_js_1.createWorkChallenge; } });
+Object.defineProperty(exports, "validateWorkChallenge", { enumerable: true, get: function () { return index_js_1.validateWorkChallenge; } });
+Object.defineProperty(exports, "challengeFingerprint", { enumerable: true, get: function () { return index_js_1.challengeFingerprint; } });
+Object.defineProperty(exports, "canonicalChallenge", { enumerable: true, get: function () { return index_js_1.canonicalChallenge; } });
+Object.defineProperty(exports, "computeActionCommitment", { enumerable: true, get: function () { return index_js_1.computeActionCommitment; } });
+Object.defineProperty(exports, "canonicalAction", { enumerable: true, get: function () { return index_js_1.canonicalAction; } });
+Object.defineProperty(exports, "mineWorkAdmission", { enumerable: true, get: function () { return index_js_1.mineWorkAdmission; } });
+Object.defineProperty(exports, "verifyWorkAdmission", { enumerable: true, get: function () { return index_js_1.verifyWorkAdmission; } });
+Object.defineProperty(exports, "buildBlockHeaderTail", { enumerable: true, get: function () { return index_js_1.buildBlockHeaderTail; } });
+Object.defineProperty(exports, "serializeSuperParents", { enumerable: true, get: function () { return index_js_1.serializeSuperParents; } });
+Object.defineProperty(exports, "isBlockWinner", { enumerable: true, get: function () { return index_js_1.isBlockWinner; } });
+Object.defineProperty(exports, "computeSuperLevel", { enumerable: true, get: function () { return index_js_1.computeSuperLevel; } });
+Object.defineProperty(exports, "templateFreshness", { enumerable: true, get: function () { return index_js_1.templateFreshness; } });
+Object.defineProperty(exports, "computeBlockCandidateId", { enumerable: true, get: function () { return index_js_1.computeBlockCandidateId; } });
+Object.defineProperty(exports, "buildEmptyBlockBody", { enumerable: true, get: function () { return index_js_1.buildEmptyBlockBody; } });
+Object.defineProperty(exports, "buildEmptyTransactionBytes", { enumerable: true, get: function () { return index_js_1.buildEmptyTransactionBytes; } });
+Object.defineProperty(exports, "buildEmptyWitnessBytes", { enumerable: true, get: function () { return index_js_1.buildEmptyWitnessBytes; } });
+Object.defineProperty(exports, "buildEmptyBurnTxBytes", { enumerable: true, get: function () { return index_js_1.buildEmptyBurnTxBytes; } });
+Object.defineProperty(exports, "buildEmptyBurnWitnessBytes", { enumerable: true, get: function () { return index_js_1.buildEmptyBurnWitnessBytes; } });
+Object.defineProperty(exports, "assembleTxPoWEnvelope", { enumerable: true, get: function () { return index_js_1.assembleTxPoWEnvelope; } });
+Object.defineProperty(exports, "reconstructTxPoWEnvelope", { enumerable: true, get: function () { return index_js_1.reconstructTxPoWEnvelope; } });
+Object.defineProperty(exports, "MACHINE_WORK_ADMISSION_VERSION", { enumerable: true, get: function () { return index_js_1.MACHINE_WORK_ADMISSION_VERSION; } });
+Object.defineProperty(exports, "MACHINE_WORK_DOMAIN", { enumerable: true, get: function () { return index_js_1.MACHINE_WORK_DOMAIN; } });
+Object.defineProperty(exports, "DEFAULT_CHALLENGE_TTL_MS", { enumerable: true, get: function () { return index_js_1.DEFAULT_CHALLENGE_TTL_MS; } });
+Object.defineProperty(exports, "MAX_CHALLENGE_TTL_MS", { enumerable: true, get: function () { return index_js_1.MAX_CHALLENGE_TTL_MS; } });

package/dist/cjs/magic.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+export declare function serializeMagic(): Uint8Array;

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);
+}