@totemsdk/txpow 0.1.0

package/dist/calibrate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * calibrate.ts — Hash rate measurement and mining cost estimation.
+ *
+ * calibrateHashRate() measures how many SHA3-256 hashes/sec the current
+ * environment can produce. Used by the extension UX to show a warning
+ * before starting a mine on slow devices.
+ *
+ * estimateMiningCost() converts a difficulty target + hash rate into an
+ * expected time and confidence label.
+ */
+export interface MiningEstimate {
+    expectedHashes: bigint;
+    expectedSeconds: number;
+    confidence: 'fast' | 'normal' | 'slow';
+}
+/**
+ * Run 100K trial SHA3-256 hashes and return the measured hash rate (hashes/sec).
+ *
+ * Call once per session and cache the result — the cost is ~50ms on a
+ * typical desktop and ~300ms on a mid-range mobile.
+ */
+export declare function calibrateHashRate(): Promise<number>;
+/**
+ * Given a difficulty target and a measured hash rate, return the expected
+ * number of hashes, expected wall-clock time, and a confidence label.
+ *
+ * expectedHashes ≈ MAX_HASH / txnDifficulty
+ *   (geometric distribution: each hash has P(valid) = txnDifficulty / MAX_HASH)
+ *
+ * Confidence labels:
+ *   fast   < 2 s
+ *   normal 2 – 15 s
+ *   slow   > 15 s
+ */
+export declare function estimateMiningCost(txnDifficulty: Uint8Array, hashRatePerSec: number): MiningEstimate;

package/dist/calibrate.js

@@ -0,0 +1,64 @@
+/**
+ * calibrate.ts — Hash rate measurement and mining cost estimation.
+ *
+ * calibrateHashRate() measures how many SHA3-256 hashes/sec the current
+ * environment can produce. Used by the extension UX to show a warning
+ * before starting a mine on slow devices.
+ *
+ * estimateMiningCost() converts a difficulty target + hash rate into an
+ * expected time and confidence label.
+ */
+import { sha3_256 } from '@noble/hashes/sha3.js';
+/**
+ * Run 100K trial SHA3-256 hashes and return the measured hash rate (hashes/sec).
+ *
+ * Call once per session and cache the result — the cost is ~50ms on a
+ * typical desktop and ~300ms on a mid-range mobile.
+ */
+export async function calibrateHashRate() {
+    const TRIAL_COUNT = 100000;
+    const data = new Uint8Array(150).fill(0xab);
+    const start = typeof performance !== 'undefined'
+        ? performance.now()
+        : Date.now();
+    for (let i = 0; i < TRIAL_COUNT; i++) {
+        sha3_256(data);
+    }
+    const elapsed = (typeof performance !== 'undefined' ? performance.now() : Date.now()) - start;
+    return Math.round(TRIAL_COUNT / (elapsed / 1000));
+}
+/**
+ * Given a difficulty target and a measured hash rate, return the expected
+ * number of hashes, expected wall-clock time, and a confidence label.
+ *
+ * expectedHashes ≈ MAX_HASH / txnDifficulty
+ *   (geometric distribution: each hash has P(valid) = txnDifficulty / MAX_HASH)
+ *
+ * Confidence labels:
+ *   fast   < 2 s
+ *   normal 2 – 15 s
+ *   slow   > 15 s
+ */
+export function estimateMiningCost(txnDifficulty, hashRatePerSec) {
+    if (hashRatePerSec <= 0) {
+        throw new Error('hashRatePerSec must be positive');
+    }
+    const diffBigInt = txnDifficulty.reduce((acc, b) => (acc << 8n) | BigInt(b), 0n);
+    if (diffBigInt === 0n) {
+        return { expectedHashes: 0n, expectedSeconds: 0, confidence: 'fast' };
+    }
+    const MAX_HASH_BIGINT = (2n ** 256n) - 1n;
+    const expectedHashes = MAX_HASH_BIGINT / diffBigInt;
+    const expectedSeconds = Number(expectedHashes) / hashRatePerSec;
+    let confidence;
+    if (expectedSeconds < 2) {
+        confidence = 'fast';
+    }
+    else if (expectedSeconds < 15) {
+        confidence = 'normal';
+    }
+    else {
+        confidence = 'slow';
+    }
+    return { expectedHashes, expectedSeconds, confidence };
+}

package/dist/constants.d.ts

@@ -0,0 +1,27 @@
+/**
+ * constants.ts — TxPoW-level constants matching Minima Java protocol values.
+ *
+ * ZERO_HASH:              32-byte all-zeros — used for MMRRoot, CustomHash, super-parent slot.
+ * MAX_HASH:               32-byte all-0xFF — default mBlockDifficulty / mTxnDifficulty for
+ *                         MEG-side-mined paths. Rejected by checkTxPoWSimple() at block level.
+ * TX_POW_MIN_DIFFICULTY:  Safe transaction difficulty target.
+ *                         ≈ MAX_HASH / 1,000,000 = Magic.getMinTxPowWork() floor.
+ *                         Local-mining paths MUST use a target ≤ this value.
+ * 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.
+ */
+export declare const CASCADE_LEVELS = 32;
+export declare const ZERO_HASH: Uint8Array<ArrayBuffer>;
+export declare const MAX_HASH: Uint8Array;
+/**
+ * TX_POW_MIN_DIFFICULTY = floor((2^256 - 1) / 1_000_000)
+ *
+ * This is the hardcoded floor constant matching Magic.getMinTxPowWork().
+ * Any locally mined TxPoW must have mTxnDifficulty ≤ this value to pass
+ * TxPoWChecker.checkTxPoWSimple() at block inclusion.
+ *
+ * Computed: (2n**256n - 1n) / 1_000_000n
+ * Hex: 0x000010C6F7A0B5ED8538AACDD46595F0C7AC73E0E9DBF12F70000000000000000
+ */
+export declare const TX_POW_MIN_DIFFICULTY: Uint8Array;
+export declare const MAIN_NET_CHAIN_ID: Uint8Array<ArrayBuffer>;

package/dist/constants.js

@@ -0,0 +1,44 @@
+/**
+ * constants.ts — TxPoW-level constants matching Minima Java protocol values.
+ *
+ * ZERO_HASH:              32-byte all-zeros — used for MMRRoot, CustomHash, super-parent slot.
+ * MAX_HASH:               32-byte all-0xFF — default mBlockDifficulty / mTxnDifficulty for
+ *                         MEG-side-mined paths. Rejected by checkTxPoWSimple() at block level.
+ * TX_POW_MIN_DIFFICULTY:  Safe transaction difficulty target.
+ *                         ≈ MAX_HASH / 1,000,000 = Magic.getMinTxPowWork() floor.
+ *                         Local-mining paths MUST use a target ≤ this value.
+ * 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.
+ */
+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;
+})();
+/**
+ * TX_POW_MIN_DIFFICULTY = floor((2^256 - 1) / 1_000_000)
+ *
+ * This is the hardcoded floor constant matching Magic.getMinTxPowWork().
+ * Any locally mined TxPoW must have mTxnDifficulty ≤ this value to pass
+ * TxPoWChecker.checkTxPoWSimple() at block inclusion.
+ *
+ * Computed: (2n**256n - 1n) / 1_000_000n
+ * Hex: 0x000010C6F7A0B5ED8538AACDD46595F0C7AC73E0E9DBF12F70000000000000000
+ */
+export const TX_POW_MIN_DIFFICULTY = (() => {
+    const maxHashBigInt = (2n ** 256n) - 1n;
+    const minDiffBigInt = maxHashBigInt / 1000000n;
+    let hex = minDiffBigInt.toString(16);
+    if (hex.length % 2 !== 0)
+        hex = '0' + hex;
+    while (hex.length < 64)
+        hex = '00' + hex;
+    const bytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+})();
+export const MAIN_NET_CHAIN_ID = new Uint8Array([0x00]);

package/dist/difficulty.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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;
+}
+/**
+ * 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/difficulty.js

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+import { TX_POW_MIN_DIFFICULTY } from './constants.js';
+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)
+ */
+export 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(TX_POW_MIN_DIFFICULTY);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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, isLessThan, type MineResult, type MineOptions, } from './mine.js';
+export { fetchTxPowTarget, type TxPowParams } from './difficulty.js';
+export { verifyProofOfWork, type VerifyResult } from './verify.js';
+export { calibrateHashRate, estimateMiningCost, type MiningEstimate, } from './calibrate.js';

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * @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, } 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, isLessThan, } from './mine.js';
+export { fetchTxPowTarget } from './difficulty.js';
+export { verifyProofOfWork } from './verify.js';
+export { calibrateHashRate, estimateMiningCost, } from './calibrate.js';

package/dist/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/magic.js

@@ -0,0 +1,32 @@
+/**
+ * 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
+ */
+import { writeMiniNumber, writeMiniData, concat } from '@totemsdk/core';
+import { MAX_HASH } from './constants.js';
+export function serializeMagic() {
+    const parts = [];
+    parts.push(writeMiniNumber(65536n));
+    parts.push(writeMiniNumber(1024n));
+    parts.push(writeMiniNumber(256n));
+    parts.push(writeMiniData(MAX_HASH));
+    parts.push(writeMiniNumber(65536n));
+    parts.push(writeMiniNumber(1024n));
+    parts.push(writeMiniNumber(256n));
+    parts.push(writeMiniData(MAX_HASH));
+    return concat(...parts);
+}

package/dist/mine.d.ts

@@ -0,0 +1,56 @@
+/**
+ * mine.ts — Local TxPoW proof-of-work mining loop.
+ *
+ * Algorithm (from TxPoWChecker.java):
+ *   txpowId = SHA3-256( serialize(TxHeader) )
+ *   valid   = txpowId < mTxnDifficulty   (big-endian 256-bit comparison)
+ *
+ * Strategy:
+ *   1. The TxBody is fixed during mining — only mNonce in the header changes.
+ *   2. We precompute the "header tail" (everything after mNonce) once per mine.
+ *   3. Within each chunk (fixed nonce encoding length), we update only the nonce
+ *      value bytes in place — no per-iteration allocation.
+ *   4. At each MiniNumber encoding boundary (nonce 128, 32768, 8388608, …) we
+ *      re-allocate a new header buffer with the wider nonce field.
+ *   5. Between chunks we yield to the event loop so the caller thread isn't blocked.
+ */
+export interface MineResult {
+    /** Fully serialized TxHeader bytes with the winning nonce. */
+    minedHeaderBytes: Uint8Array;
+    /** SHA3-256(minedHeaderBytes) — the canonical TxPoW ID. */
+    txpowId: Uint8Array;
+    nonce: bigint;
+    elapsedMs: number;
+    /** 'wasm' when the WASM binary is present; 'js' otherwise. */
+    source: 'wasm' | 'js';
+}
+export interface MineOptions {
+    /**
+     * Hash iterations per async yield (default: 10_000).
+     * Lower = more responsive UI; higher = slightly faster mining.
+     */
+    chunkSize?: number;
+    /**
+     * Hard cap on total iterations (default: unlimited).
+     * Throws if exhausted without finding a valid nonce.
+     */
+    maxIterations?: number;
+    /** AbortSignal — rejects the Promise when aborted. */
+    signal?: AbortSignal;
+}
+/**
+ * Big-endian 256-bit comparison: true if a < b.
+ * Used to check: txpowId < mTxnDifficulty.
+ */
+export declare function isLessThan(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Mine a TxPoW locally by iterating the header nonce until
+ *   SHA3-256( TxHeader ) < txnDifficulty
+ *
+ * @param txBodyBytes   Pre-serialized TxBody bytes (from serializeTxBody).
+ * @param txnDifficulty 32-byte target. MUST be ≤ TX_POW_MIN_DIFFICULTY.
+ *                      Passing MAX_HASH here will loop forever and be rejected
+ *                      at block level by TxPoWChecker.checkTxPoWSimple().
+ * @param options       Chunk size, max iterations, abort signal.
+ */
+export declare function mineTxPoW(txBodyBytes: Uint8Array, txnDifficulty: Uint8Array, options?: MineOptions): Promise<MineResult>;

package/dist/mine.js

@@ -0,0 +1,139 @@
+/**
+ * mine.ts — Local TxPoW proof-of-work mining loop.
+ *
+ * Algorithm (from TxPoWChecker.java):
+ *   txpowId = SHA3-256( serialize(TxHeader) )
+ *   valid   = txpowId < mTxnDifficulty   (big-endian 256-bit comparison)
+ *
+ * Strategy:
+ *   1. The TxBody is fixed during mining — only mNonce in the header changes.
+ *   2. We precompute the "header tail" (everything after mNonce) once per mine.
+ *   3. Within each chunk (fixed nonce encoding length), we update only the nonce
+ *      value bytes in place — no per-iteration allocation.
+ *   4. At each MiniNumber encoding boundary (nonce 128, 32768, 8388608, …) we
+ *      re-allocate a new header buffer with the wider nonce field.
+ *   5. Between chunks we yield to the event loop so the caller thread isn't blocked.
+ */
+import { sha3_256 } from '@noble/hashes/sha3.js';
+import { writeMiniNumber, writeMiniData, writeHashToStream, concat, } from '@totemsdk/core';
+import { serializeMagic } from './magic.js';
+import { MAX_HASH, ZERO_HASH, CASCADE_LEVELS, MAIN_NET_CHAIN_ID } from './constants.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Big-endian 256-bit comparison: true if a < b.
+ * Used to check: txpowId < mTxnDifficulty.
+ */
+export function isLessThan(a, b) {
+    for (let i = 0; i < 32; i++) {
+        if (a[i] < b[i])
+            return true;
+        if (a[i] > b[i])
+            return false;
+    }
+    return false;
+}
+/**
+ * Returns the first nonce value that would require more bytes in its
+ * MiniNumber encoding (i.e. the next boundary at 128, 32768, 8388608, …).
+ *
+ * Pattern: bigIntToByteArray(n) grows by 1 byte at 2^(8k−1) for k=1,2,3,…
+ *   k=1: 2^7  = 128
+ *   k=2: 2^15 = 32768
+ *   k=3: 2^23 = 8388608
+ */
+function nextNonceBoundary(nonce) {
+    const nonceValueLen = writeMiniNumber(nonce).length - 2;
+    return 2n ** BigInt(8 * nonceValueLen - 1);
+}
+/**
+ * Build the "header tail" — the part of TxHeader that follows mNonce.
+ *
+ * This is computed once at the start of a mine and never changes during it.
+ */
+function buildHeaderTail(txBodyHash, timeMilli) {
+    return concat(writeMiniData(MAIN_NET_CHAIN_ID), writeMiniNumber(timeMilli), writeMiniNumber(0n), writeMiniData(MAX_HASH), new Uint8Array([CASCADE_LEVELS]), writeHashToStream(ZERO_HASH), writeHashToStream(ZERO_HASH), writeMiniNumber(0n), serializeMagic(), writeHashToStream(ZERO_HASH), writeHashToStream(txBodyHash));
+}
+/**
+ * Synchronously mine a chunk of nonces within a fixed encoding boundary.
+ *
+ * Mutates headerBuf in place — only the nonce value bytes at offset 2 change.
+ * Returns the found nonce, or null if not found in this chunk.
+ */
+function mineChunk(headerBuf, nonceValueLen, target, startNonce, endNonce) {
+    const nonceValueOffset = 2;
+    for (let nonce = startNonce; nonce < endNonce; nonce++) {
+        let n = nonce;
+        for (let i = nonceValueLen - 1; i >= 0; i--) {
+            headerBuf[nonceValueOffset + i] = Number(n & 0xffn);
+            n >>= 8n;
+        }
+        const hash = sha3_256(headerBuf);
+        if (isLessThan(hash, target))
+            return nonce;
+    }
+    return null;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Mine a TxPoW locally by iterating the header nonce until
+ *   SHA3-256( TxHeader ) < txnDifficulty
+ *
+ * @param txBodyBytes   Pre-serialized TxBody bytes (from serializeTxBody).
+ * @param txnDifficulty 32-byte target. MUST be ≤ TX_POW_MIN_DIFFICULTY.
+ *                      Passing MAX_HASH here will loop forever and be rejected
+ *                      at block level by TxPoWChecker.checkTxPoWSimple().
+ * @param options       Chunk size, max iterations, abort signal.
+ */
+export async function mineTxPoW(txBodyBytes, txnDifficulty, options) {
+    const chunkSize = BigInt(options?.chunkSize ?? 10000);
+    const maxIterations = options?.maxIterations !== undefined
+        ? BigInt(options.maxIterations)
+        : undefined;
+    const signal = options?.signal;
+    const bodyHash = sha3_256(txBodyBytes);
+    const timeMilli = BigInt(Date.now());
+    const headerTail = buildHeaderTail(bodyHash, timeMilli);
+    const startTime = Date.now();
+    let totalIterations = 0n;
+    let nonce = 0n;
+    while (true) {
+        if (signal?.aborted) {
+            throw new DOMException('Mining aborted', 'AbortError');
+        }
+        if (maxIterations !== undefined && totalIterations >= maxIterations) {
+            throw new Error(`Mining exhausted: ${totalIterations} iterations without finding a valid nonce`);
+        }
+        const boundary = nextNonceBoundary(nonce);
+        const chunkEnd = nonce + chunkSize < boundary ? nonce + chunkSize : boundary;
+        const nonceBytes = writeMiniNumber(nonce);
+        const nonceValueLen = nonceBytes.length - 2;
+        const headerBuf = concat(nonceBytes, headerTail);
+        const found = mineChunk(headerBuf, nonceValueLen, txnDifficulty, nonce, chunkEnd);
+        if (found !== null) {
+            const finalNonceBytes = writeMiniNumber(found);
+            const finalHeader = concat(finalNonceBytes, headerTail);
+            const txpowId = sha3_256(finalHeader);
+            return {
+                minedHeaderBytes: finalHeader,
+                txpowId,
+                nonce: found,
+                elapsedMs: Date.now() - startTime,
+                source: 'js',
+            };
+        }
+        totalIterations += chunkEnd - nonce;
+        nonce = chunkEnd;
+        await new Promise(resolve => {
+            if (typeof setImmediate !== 'undefined') {
+                setImmediate(resolve);
+            }
+            else {
+                setTimeout(resolve, 0);
+            }
+        });
+    }
+}

package/dist/serialization.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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)
+ */
+export interface TxHeaderOptions {
+    /** Proof-of-work nonce. Defaults to 0n. The mining loop iterates this. */
+    nonce?: bigint;
+    /** Block timestamp in milliseconds. Defaults to Date.now() at call time. */
+    timeMilli?: bigint;
+}
+export interface TxBodyOptions {
+    /**
+     * Transaction difficulty target (32-byte MiniData).
+     * • MEG-side-mined path:  leave undefined → MAX_HASH (all 0xFF)
+     * • Locally mined path:   MUST be ≤ TX_POW_MIN_DIFFICULTY, typically fetched
+     *   via fetchTxPowTarget() from the same package.
+     * Setting MAX_HASH for locally mined TxPoWs will cause block-level rejection.
+     */
+    txnDifficulty?: Uint8Array;
+    /** Override the 32-byte PRNG field. Useful for deterministic tests only. */
+    prng?: Uint8Array;
+}
+export type TxPoWOptions = TxHeaderOptions & TxBodyOptions;
+/**
+ * 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
+ */
+export declare function serializeTxHeader(txBodyHash: Uint8Array, options?: TxHeaderOptions): Uint8Array;
+/**
+ * Compute TxPoW ID = SHA3-256(TxHeader bytes).
+ * Matches Java: Crypto.getInstance().hashObject(mHeader) via SHA3Digest(256).
+ */
+export declare function computeTxPoWId(headerBytes: Uint8Array): Uint8Array;
+/**
+ * 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
+ */
+export declare function serializeTxBody(txBytes: Uint8Array, witnessBytes: Uint8Array, options?: TxBodyOptions): Uint8Array;
+/**
+ * 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
+ */
+export declare function serializeTxPoW(txBytes: Uint8Array, witnessBytes: Uint8Array, options?: TxPoWOptions): Uint8Array;