@totemsdk/txpow 1.0.2 → 1.1.0

package/dist/cjs/admission/verify.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * admission/verify.ts — Machine Work Admission verification.
+ *
+ * Verification NEVER trusts sender-reported hardware speed or self-reported
+ * block metadata (`isBlock`, `superLevel`, `qualifiesAsMinimaBlock`,
+ * `broadcastable`). It recomputes the canonical action commitment, re-derives
+ * the TxPoW ID from the mined header, and checks `txpowId < challenge.target`.
+ * It also checks challenge validity (expiry, recipient, domain) and template
+ * freshness.
+ *
+ * Three distinct claims, never to be confused:
+ *   A. valid — the hash satisfies the challenge target.
+ *   B. superLevel/isBlock — the exact Minima Super level (-1 or 0..31)
+ *      computed from blockDifficulty / txpowId.
+ *   C. broadcastable — isBlock AND the template is current AND a live
+ *      template provider was supplied.
+ *
+ * A stale candidate may remain valid = true (and superLevel >= 0) while
+ * broadcastable = false. Offline verification (no provider) must NOT claim
+ * Minima block contribution — `broadcastable` is left undefined.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWorkAdmission = verifyWorkAdmission;
+const core_1 = require("@totemsdk/core");
+const commitment_js_1 = require("./commitment.js");
+const challenge_js_1 = require("./challenge.js");
+const template_js_1 = require("./template.js");
+const types_js_1 = require("./types.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;
+}
+/** Big-endian 256-bit comparison: true if a < b. */
+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;
+}
+/**
+ * Verify a Machine Work Admission proof.
+ *
+ * The admission target is taken from the validated challenge — never from the
+ * proof. `proof.qualifiesAsMinimaBlock`, `proof.superLevel`, and
+ * `proof.isBlock` are treated as derived metadata and are NOT trusted; the
+ * Super level is recomputed from the re-derived txpowId and the template's
+ * block difficulty.
+ *
+ * @param action           The application action the proof claims to commit.
+ * @param challenge        The challenge the proof claims to satisfy.
+ * @param proof            The mined proof.
+ * @param templateProvider Optional live provider. When supplied, template
+ *                         freshness and broadcastability are checked and
+ *                         `broadcastable` is set. When omitted, verification
+ *                         runs in offline mode and does NOT claim Minima
+ *                         block contribution (`broadcastable` is undefined).
+ * @param options          Verification options.
+ */
+async function verifyWorkAdmission(action, challenge, proof, templateProvider, options) {
+    // 1. Structural checks
+    if (!proof || typeof proof !== 'object') {
+        return { valid: false, reason: 'proof is not an object' };
+    }
+    if (proof.version !== types_js_1.MACHINE_WORK_ADMISSION_VERSION) {
+        return { valid: false, reason: `unsupported proof version ${proof.version}` };
+    }
+    if (proof.challengeId !== challenge.challengeId) {
+        return { valid: false, reason: 'proof challengeId does not match challenge' };
+    }
+    if (proof.qualifiesForAdmission !== true) {
+        return { valid: false, reason: 'proof does not claim admission' };
+    }
+    // Target manipulation guard: the proof must have been mined against the
+    // challenge's exact target. A sender must not be able to mine against a
+    // trivially easy target and present it as satisfying a harder challenge.
+    if (proof.admissionTarget !== challenge.target) {
+        return { valid: false, reason: 'proof admissionTarget does not match challenge target' };
+    }
+    // 2. Challenge validity (expiry, recipient, domain)
+    const challengeCheck = (0, challenge_js_1.validateWorkChallenge)(challenge, {
+        recipient: action.recipient,
+        domain: action.domain,
+        now: options?.now,
+    });
+    if (!challengeCheck.valid) {
+        return { valid: false, reason: challengeCheck.reason };
+    }
+    // 3. Recompute the canonical commitment — must match the proof
+    const expectedCommitment = (0, commitment_js_1.computeActionCommitment)(action, challenge);
+    if (expectedCommitment !== proof.actionCommitment) {
+        return { valid: false, reason: 'action commitment mismatch' };
+    }
+    // 4. Re-derive the TxPoW ID from the mined header and check the target
+    const headerBytes = hexToBytes(proof.txpow);
+    const txpowId = (0, core_1.sha3_256)(headerBytes);
+    const txpowIdHex = toHex(txpowId);
+    if (txpowIdHex !== proof.txpowId) {
+        return { valid: false, reason: 'txpowId does not match mined header' };
+    }
+    const admissionTarget = hexToBytes(proof.admissionTarget);
+    if (!isLessThan(txpowId, admissionTarget)) {
+        return { valid: false, reason: 'txpowId does not beat admission target' };
+    }
+    // 5. Resolve a trusted template. Template fields — notably `blockDifficulty`,
+    //    which drives the Super-level claim — must come from a freshly-fetched
+    //    trusted template, never from the prover's copy (RFC-020 H4).
+    let trustedTemplate = options?.latestTemplate ?? null;
+    if (templateProvider) {
+        if (templateProvider.getLatestTemplate) {
+            trustedTemplate = await templateProvider.getLatestTemplate();
+        }
+        else if (options?.latestTemplate) {
+            trustedTemplate = options.latestTemplate;
+        }
+        else {
+            trustedTemplate = await templateProvider.getCurrentTemplate();
+        }
+    }
+    // 5a. Template freshness for admission (uses the proof's capture time).
+    const freshness = (0, template_js_1.templateFreshness)(proof.template, trustedTemplate, {
+        admissionWindowMs: options?.admissionWindowMs,
+        now: options?.now,
+    });
+    if (!freshness.admissionValid) {
+        return { valid: false, reason: 'proof template is stale for admission' };
+    }
+    // 5b. The prover's declared block difficulty must byte-match the trusted
+    //     template — otherwise a prover could set a max difficulty to fake a
+    //     Minima block.
+    if (trustedTemplate && trustedTemplate.blockDifficulty !== proof.template.blockDifficulty) {
+        return { valid: false, reason: 'proof template blockDifficulty does not match the trusted template' };
+    }
+    // 6. Level B: recompute the exact Minima Super level from the TRUSTED block
+    //    difficulty and the re-derived txpowId. Without a trusted template we
+    //    cannot claim Minima block contribution (isBlock = false).
+    const superLevel = trustedTemplate ? (0, template_js_1.computeSuperLevel)(txpowId, trustedTemplate.blockDifficulty) : -1;
+    const isBlock = trustedTemplate ? superLevel >= 0 : false;
+    // 7. Level C: broadcastability requires a live template provider, a current
+    //    template, and isBlock. Offline mode leaves broadcastable undefined.
+    let broadcastable;
+    if (templateProvider) {
+        broadcastable = isBlock && trustedTemplate !== null && freshness.broadcastable;
+    }
+    return { valid: true, superLevel, isBlock, broadcastable };
+}
+function toHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}

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

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calibrateHashRate = calibrateHashRate;
+exports.estimateMiningCost = estimateMiningCost;
+const core_1 = require("@totemsdk/core");
+/**
+ * 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.
+ */
+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++) {
+        (0, core_1.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
+ */
+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/cjs/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/cjs/constants.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAIN_NET_CHAIN_ID = exports.TX_POW_MIN_DIFFICULTY = exports.MAX_HASH = exports.ZERO_HASH = exports.CASCADE_LEVELS = void 0;
+exports.CASCADE_LEVELS = 32;
+exports.ZERO_HASH = new Uint8Array(32);
+exports.MAX_HASH = (() => {
+    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
+ */
+exports.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;
+})();
+exports.MAIN_NET_CHAIN_ID = new Uint8Array([0x00]);

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;