@totemsdk/txpow 1.0.2 → 1.1.0

package/dist/cjs/mine.js

@@ -0,0 +1,407 @@
+"use strict";
+/**
+ * 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 calling thread is never blocked.
+ *   6. When the pre-compiled WASM binary is present (`dist/wasm/miner.wasm`), the
+ *      inner loop runs in WASM for ~5-10x throughput. Falls back to pure JS otherwise.
+ *   7. In Node.js (main thread), mining runs inside a `worker_threads` Worker so the
+ *      event loop is never blocked. In browser contexts the in-process loop is used
+ *      until Task #114 wires up the Web Worker entry point.
+ *
+ * Control-flow invariant (IMPORTANT):
+ *   WASM and JS are mutually exclusive per chunk — we never re-mine a chunk that
+ *   WASM already scanned. When WASM returns null (nonce not found in chunk), we
+ *   advance to the next chunk rather than falling back to JS for the same range.
+ *   This means `source` is always accurate: 'wasm' when the binary was used for
+ *   the winning chunk; 'js' when the JS path found the nonce.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLessThan = isLessThan;
+exports.buildHeaderTail = buildHeaderTail;
+exports.setBrowserWorkerUrl = setBrowserWorkerUrl;
+exports.mineHeaderTail = mineHeaderTail;
+exports.mineTxPoWInProcess = mineTxPoWInProcess;
+exports.mineTxPoW = mineTxPoW;
+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");
+const mine_wasm_js_1 = require("./mine-wasm.js");
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Big-endian 256-bit comparison: true if a < b.
+ * Used to check: txpowId < mTxnDifficulty.
+ */
+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 = (0, core_2.writeMiniNumber)(nonce, 0).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.
+ *
+ * This is the fresh-transaction header shape (blockNumber=0, MAX_HASH block
+ * difficulty, zero super-parents, zero MMR, zero customHash). Block-candidate
+ * mining (Machine Work Admission) builds its own tail via
+ * `admission/template.ts` with real chain state and a customHash commitment.
+ */
+function buildHeaderTail(txBodyHash, timeMilli) {
+    return (0, core_2.concat)((0, core_2.writeMiniData)(constants_js_1.MAIN_NET_CHAIN_ID), (0, core_2.writeMiniNumber)(timeMilli, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniData)(constants_js_1.MAX_HASH), new Uint8Array([constants_js_1.CASCADE_LEVELS]), (0, core_2.writeHashToStream)(constants_js_1.ZERO_HASH), (0, core_2.writeHashToStream)(constants_js_1.ZERO_HASH), (0, core_2.writeMiniNumber)(0n, 0), (0, magic_js_1.serializeMagic)(), (0, core_2.writeHashToStream)(constants_js_1.ZERO_HASH), (0, core_2.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 mineChunkJs(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 = (0, core_1.sha3_256)(headerBuf);
+        if (isLessThan(hash, target))
+            return nonce;
+    }
+    return null;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Browser Web Worker dispatch (optional URL-based)
+// ─────────────────────────────────────────────────────────────────────────────
+let _browserWorkerUrl = null;
+/**
+ * Configure the URL of the browser.worker.js bundle so that `mineTxPoW()`
+ * can spawn a Web Worker in browser contexts.
+ *
+ * Call this once at extension/dApp startup. The bundled worker file exposes
+ * the same message protocol as node.worker.ts.
+ *
+ * @example
+ *   import { setBrowserWorkerUrl } from '@totemsdk/txpow';
+ *   setBrowserWorkerUrl(browser.runtime.getURL('mine-worker.js'));
+ */
+function setBrowserWorkerUrl(url) {
+    _browserWorkerUrl = url;
+}
+/**
+ * Spawn a browser Web Worker to run the mining loop off the main thread.
+ * Requires a prior call to setBrowserWorkerUrl() to configure the worker URL.
+ */
+async function mineTxPoWViaBrowserWorker(txBodyBytes, txnDifficulty, options) {
+    if (!_browserWorkerUrl) {
+        throw new Error('Browser Web Worker URL not configured. Call setBrowserWorkerUrl() first.');
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const WorkerClass = globalThis.Worker;
+    const worker = new WorkerClass(_browserWorkerUrl);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (fn) => {
+            if (!settled) {
+                settled = true;
+                fn();
+            }
+        };
+        if (options?.signal) {
+            const abortHandler = () => {
+                settle(() => reject(new DOMException('Mining aborted', 'AbortError')));
+                worker.terminate();
+            };
+            if (options.signal.aborted) {
+                abortHandler();
+                return;
+            }
+            options.signal.addEventListener('abort', abortHandler, { once: true });
+        }
+        worker.onmessage = (e) => {
+            const msg = e.data;
+            if (msg['error']) {
+                settle(() => reject(new Error(String(msg['error']))));
+            }
+            else {
+                settle(() => resolve({
+                    minedHeaderBytes: Uint8Array.from(msg['minedHeaderBytes']),
+                    txpowId: Uint8Array.from(msg['txpowId']),
+                    nonce: BigInt(msg['nonce']),
+                    elapsedMs: msg['elapsedMs'],
+                    source: msg['source'],
+                }));
+            }
+        };
+        worker.onerror = (e) => {
+            settle(() => reject(new Error(e.message)));
+        };
+        // Pass the WASM URL so the worker can call setWasmUrl() in its own JS context.
+        // Web Workers have isolated module state — the main thread's setWasmUrl() call
+        // does not carry over. Without this the worker mines in pure JS.
+        const wasmUrl = (0, mine_wasm_js_1.getBrowserWasmUrl)();
+        worker.postMessage({
+            txBodyBytes: Array.from(txBodyBytes),
+            txnDifficulty: Array.from(txnDifficulty),
+            wasmUrl: wasmUrl ?? undefined,
+            chunkSize: options?.chunkSize,
+            maxIterations: options?.maxIterations !== undefined
+                ? options.maxIterations.toString()
+                : undefined,
+            timeMilli: options?.timeMilli !== undefined
+                ? options.timeMilli.toString()
+                : undefined,
+            forceJs: options?.forceJs,
+        });
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Node.js worker_threads dispatch
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Returns true when mining should be delegated to a Node.js worker_threads Worker.
+ *
+ * Conditions for using a worker:
+ *   - Running in Node.js (process.versions.node is set)
+ *   - Not already inside a worker thread (isMainThread === true)
+ *   - _skipWorker option is not set
+ *   - Not in a Jest test environment (ts-jest runs from source, dist/workers/*.js
+ *     may not exist yet; Jest's own worker processes also have isMainThread=false
+ *     which handles the common --maxWorkers case automatically)
+ */
+function shouldUseNodeWorker(options) {
+    if (options?._skipWorker)
+        return false;
+    if (typeof process === 'undefined' || !process.versions?.node)
+        return false;
+    // In Jest, skip worker spawning: source workers are not compiled .js files
+    // and Jest's own worker pool already sets isMainThread=false for most runners.
+    if (process.env.NODE_ENV === 'test' ||
+        process.env.JEST_WORKER_ID !== undefined) {
+        return false;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const wt = require('worker_threads');
+        return wt.isMainThread;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Dispatch mining to a Node.js `worker_threads` Worker.
+ * The worker runs `mineTxPoWInProcess` with `_skipWorker: true` to prevent
+ * recursive worker spawning.
+ */
+async function mineTxPoWViaNodeWorker(txBodyBytes, txnDifficulty, options) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { Worker } = require('worker_threads');
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { join } = require('path');
+    const workerPath = join(__dirname, 'workers', 'node.worker.js');
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (fn) => {
+            if (!settled) {
+                settled = true;
+                fn();
+            }
+        };
+        const worker = new Worker(workerPath, {
+            workerData: {
+                txBodyBytes: Array.from(txBodyBytes),
+                txnDifficulty: Array.from(txnDifficulty),
+                chunkSize: options?.chunkSize,
+                maxIterations: options?.maxIterations !== undefined
+                    ? options.maxIterations.toString()
+                    : undefined,
+                timeMilli: options?.timeMilli !== undefined
+                    ? options.timeMilli.toString()
+                    : undefined,
+                forceJs: options?.forceJs,
+            },
+        });
+        if (options?.signal) {
+            const abortHandler = () => {
+                settle(() => reject(new DOMException('Mining aborted', 'AbortError')));
+                worker.terminate().catch(() => { });
+            };
+            if (options.signal.aborted) {
+                abortHandler();
+                return;
+            }
+            options.signal.addEventListener('abort', abortHandler, { once: true });
+        }
+        worker.on('message', (msg) => {
+            if (msg['error']) {
+                settle(() => reject(new Error(String(msg['error']))));
+            }
+            else {
+                settle(() => resolve({
+                    minedHeaderBytes: Uint8Array.from(msg['minedHeaderBytes']),
+                    txpowId: Uint8Array.from(msg['txpowId']),
+                    nonce: BigInt(msg['nonce']),
+                    elapsedMs: msg['elapsedMs'],
+                    source: msg['source'],
+                }));
+            }
+        });
+        worker.on('error', (err) => settle(() => reject(err)));
+        worker.on('exit', (code) => {
+            if (code !== 0) {
+                settle(() => reject(new Error(`Mining worker exited with non-zero code ${code}`)));
+            }
+        });
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// In-process mining loop
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Core mining loop over a pre-built header tail.
+ *
+ * Iterates the nonce in the serialized TxHeader (nonce value at offset 2,
+ * followed by `headerTail`) until `SHA3-256(header) < target`. Shared by the
+ * transaction miner (`mineTxPoWInProcess`) and the Machine Work Admission
+ * miner (`admission/mine.ts`), which supplies its own block-candidate tail.
+ *
+ * @param headerTail  Serialized TxHeader bytes AFTER the nonce field.
+ * @param target      32-byte difficulty target (big-endian 256-bit).
+ * @param options     Chunk size, max iterations, abort signal, timeMilli override.
+ */
+async function mineHeaderTail(headerTail, target, options) {
+    const chunkSize = BigInt(options?.chunkSize ?? 10000);
+    const maxIterations = options?.maxIterations !== undefined
+        ? BigInt(options.maxIterations)
+        : undefined;
+    const signal = options?.signal;
+    const forceJs = options?.forceJs ?? false;
+    const useWasm = !forceJs && (await (0, mine_wasm_js_1.isWasmAvailable)());
+    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 = (0, core_2.writeMiniNumber)(nonce, 0);
+        const nonceValueLen = nonceBytes.length - 2;
+        const headerBuf = (0, core_2.concat)(nonceBytes, headerTail);
+        // ── CRITICAL: WASM and JS are mutually exclusive per chunk ──────────────
+        // When WASM returns null (no nonce in chunk), the chunk has been fully
+        // scanned by WASM — we do NOT re-scan it with JS. Doing so would double
+        // work and could incorrectly set source='wasm' on a JS-found nonce.
+        let found;
+        if (useWasm) {
+            found = await (0, mine_wasm_js_1.mineChunkWasm)(headerBuf.slice(), // WASM gets its own copy to avoid aliasing
+            2, nonceValueLen, target, nonce, chunkEnd - nonce);
+        }
+        else {
+            found = mineChunkJs(headerBuf, nonceValueLen, target, nonce, chunkEnd);
+        }
+        // ── End mutually exclusive section ───────────────────────────────────────
+        if (found !== null) {
+            const finalNonceBytes = (0, core_2.writeMiniNumber)(found, 0);
+            const finalHeader = (0, core_2.concat)(finalNonceBytes, headerTail);
+            const txpowId = (0, core_1.sha3_256)(finalHeader);
+            return {
+                minedHeaderBytes: finalHeader,
+                txpowId,
+                nonce: found,
+                elapsedMs: Date.now() - startTime,
+                source: useWasm ? 'wasm' : 'js',
+            };
+        }
+        totalIterations += chunkEnd - nonce;
+        nonce = chunkEnd;
+        await new Promise(resolve => {
+            if (typeof setImmediate !== 'undefined') {
+                setImmediate(resolve);
+            }
+            else {
+                setTimeout(resolve, 0);
+            }
+        });
+    }
+}
+/**
+ * Run the mining loop in the current thread/task.
+ * Called directly by the Node.js worker, and by the browser code path.
+ */
+async function mineTxPoWInProcess(txBodyBytes, txnDifficulty, options) {
+    const timeMilli = options?.timeMilli ?? BigInt(Date.now());
+    const bodyHash = (0, core_1.sha3_256)(txBodyBytes);
+    const headerTail = buildHeaderTail(bodyHash, timeMilli);
+    return mineHeaderTail(headerTail, txnDifficulty, options);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Mine a TxPoW locally by iterating the header nonce until
+ *   SHA3-256( TxHeader ) < txnDifficulty
+ *
+ * In Node.js (main thread), delegates to a `worker_threads` Worker so the
+ * event loop is never blocked. In browsers or Jest, runs in-process with
+ * periodic `setImmediate`/`setTimeout(0)` yields between chunks.
+ *
+ * Uses the pre-compiled `miner.wasm` binary for inner-loop throughput when
+ * available. Falls back to pure JS automatically when the binary is absent.
+ *
+ * @param txBodyBytes   Pre-serialized TxBody bytes (from serializeTxBody).
+ * @param txnDifficulty 32-byte target. MUST be ≤ TX_POW_MIN_DIFFICULTY.
+ * @param options       Chunk size, max iterations, abort signal, timeMilli override.
+ */
+async function mineTxPoW(txBodyBytes, txnDifficulty, options) {
+    // ── Node.js: spawn a worker_threads Worker (keeps event loop unblocked) ──
+    if (shouldUseNodeWorker(options)) {
+        return mineTxPoWViaNodeWorker(txBodyBytes, txnDifficulty, options);
+    }
+    // ── Browser: spawn a Web Worker when the URL has been configured ──────────
+    // The extension build (Task #114) calls setBrowserWorkerUrl() at startup.
+    // Without a configured URL, mine falls back to in-process (setImmediate loop).
+    if (!options?._skipWorker &&
+        typeof process === 'undefined' && // not Node.js
+        _browserWorkerUrl !== null) {
+        return mineTxPoWViaBrowserWorker(txBodyBytes, txnDifficulty, options);
+    }
+    // ── In-process fallback (browser without worker URL, or explicit skip) ────
+    return mineTxPoWInProcess(txBodyBytes, txnDifficulty, options);
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/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;

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