@totemsdk/txpow 0.1.7 → 1.0.1

package/dist/admission/mine.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * admission/mine.ts — Machine Work Admission mining.
+ *
+ * Mines a real Minima block candidate whose customHash commits to the machine
+ * action. The mining loop reuses the existing TxPoW mining loop
+ * (`mineHeaderTail` from ../mine.js) — the same SHA3-256 nonce search that
+ * Minima uses for transaction/block mining.
+ *
+ * The admission target is ALWAYS `challenge.target` — the challenge is the
+ * single source of truth. There is no separate admission target argument.
+ *
+ * Two thresholds:
+ *   - admission target (receiver-chosen, easier): hash < challenge.target
+ *   - L1 block target (current Minima block difficulty): hash < blockTarget
+ *
+ * The loop stops as soon as the admission target is satisfied, unless the same
+ * search already discovered a block-target winner. Ordinary admission proofs
+ * stay off-chain; only genuine L1 winners are broadcast via the injected
+ * template provider.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mineWorkAdmission = mineWorkAdmission;
+const core_1 = require("@totemsdk/core");
+const mine_js_1 = require("../mine.js");
+const commitment_js_1 = require("./commitment.js");
+const template_js_1 = require("./template.js");
+const types_js_1 = require("./types.js");
+function toHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Mine a Machine Work Admission proof.
+ *
+ * The admission target is derived from `challenge.target` — the challenge is
+ * the single authoritative source. The miner searches the nonce space of a
+ * real Minima block candidate (from the injected template provider) whose
+ * customHash commits to the action.
+ *
+ * @param action           The application action.
+ * @param challenge        The receiver-issued challenge (target is authoritative).
+ * @param templateProvider Injected provider for the current Minima template.
+ * @param options          Mining options.
+ */
+async function mineWorkAdmission(action, challenge, templateProvider, options) {
+    const template = await templateProvider.getCurrentTemplate();
+    if (templateProvider.validateTemplate) {
+        const ok = await templateProvider.validateTemplate(template);
+        if (!ok)
+            throw new Error('Minima work template failed validation');
+    }
+    const actionCommitment = (0, commitment_js_1.computeActionCommitment)(action, challenge);
+    const admissionTarget = challenge.target;
+    const admissionTargetBytes = hexToBytes(admissionTarget);
+    const blockTargetBytes = hexToBytes(template.blockDifficulty);
+    // The admission target must be easier than or equal to the block target,
+    // otherwise the search would be chasing a block that can never admit.
+    if (!isLessThanOrEqual(blockTargetBytes, admissionTargetBytes)) {
+        throw new Error('challenge.target must be easier than or equal to the current block target');
+    }
+    // Build the complete block candidate: empty TxBody (same shape Minima's
+    // MINEPULSE automine uses) + header tail with the action commitment.
+    const prng = options?.prng ?? randomBytes(32);
+    const bodyBytes = (0, template_js_1.buildEmptyBlockBody)(prng, template.blockDifficulty);
+    const bodyHash = toHex((0, core_1.sha3_256)(bodyBytes));
+    const timeMilli = options?.timeMilli ?? template.timeMilli;
+    const headerTail = (0, template_js_1.buildBlockHeaderTail)(template, actionCommitment, bodyHash);
+    // Mine against the admission target. The same nonce search also checks the
+    // block target: if the winning hash beats the block target, it is a block.
+    const result = await (0, mine_js_1.mineHeaderTail)(headerTail, admissionTargetBytes, {
+        signal: options?.signal,
+        maxIterations: options?.maxIterations,
+        chunkSize: options?.chunkSize,
+        timeMilli,
+        forceJs: options?.forceJs,
+        _skipWorker: options?._skipWorker,
+    });
+    // Assemble the complete Minima TxPoW wire format (header | 0x01 | body).
+    const envelope = (0, template_js_1.assembleTxPoWEnvelope)(result.minedHeaderBytes, bodyBytes);
+    // Exact Minima-derived metadata.
+    const superLevel = (0, template_js_1.computeSuperLevel)(result.txpowId, template.blockDifficulty);
+    const isBlock = superLevel >= 0;
+    const proof = {
+        version: types_js_1.MACHINE_WORK_ADMISSION_VERSION,
+        actionCommitment,
+        challengeId: challenge.challengeId,
+        admissionTarget,
+        txpow: toHex(result.minedHeaderBytes),
+        txpowEnvelope: toHex(envelope),
+        txpowId: toHex(result.txpowId),
+        nonce: result.nonce.toString(),
+        minedAt: Date.now(),
+        qualifiesForAdmission: true,
+        qualifiesAsMinimaBlock: isBlock,
+        superLevel,
+        isBlock,
+        template,
+    };
+    // Broadcast genuine Minima blocks exactly once, and only if the template is
+    // still current. All Super levels (0..31) are eligible — Super level is
+    // block strength, NOT a relay policy. Ordinary admission proofs never broadcast.
+    if (isBlock) {
+        let latest;
+        if (templateProvider.getLatestTemplate) {
+            latest = await templateProvider.getLatestTemplate();
+        }
+        else {
+            latest = await templateProvider.getCurrentTemplate();
+        }
+        if (latest.templateId === template.templateId) {
+            if (options?.relay) {
+                await options.relay.submitBlock(envelope);
+            }
+            else if (templateProvider.broadcastBlockCandidate) {
+                await templateProvider.broadcastBlockCandidate(proof);
+            }
+        }
+    }
+    return proof;
+}
+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;
+}
+function randomBytes(length) {
+    const out = new Uint8Array(length);
+    if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
+        throw new Error('SECURITY: crypto.getRandomValues unavailable — cannot generate secure random PRNG');
+    }
+    crypto.getRandomValues(out);
+    return out;
+}
+/** Big-endian 256-bit comparison: true if a <= b. */
+function isLessThanOrEqual(a, b) {
+    for (let i = 0; i < 32; i++) {
+        if (a[i] < b[i])
+            return true;
+        if (a[i] > b[i])
+            return false;
+    }
+    return true;
+}

package/dist/admission/template.d.ts

@@ -0,0 +1,138 @@
+/**
+ * admission/template.ts — Minima block-candidate template handling.
+ *
+ * Builds a TxHeader tail that is structurally capable of becoming a legitimate
+ * Minima block. The fields (block number, block difficulty, super-parents, MMR
+ * root/total, magic, time) come from the current chain tip via an injected
+ * MinimaWorkTemplateProvider — mirroring TxPoWGenerator.generateTxPoW in
+ * Minima. The action commitment is placed in the header's customHash field.
+ *
+ * The TxPoW package stays transport/node-client agnostic: callers inject the
+ * template provider. A real Minima node / Axia integration supplies live chain
+ * state; tests supply fixtures.
+ */
+import type { MinimaWorkTemplate } from './types.js';
+/**
+ * Serialize the super-parent RLE runs per TxHeader.writeDataStream.
+ *
+ * Consecutive equal hashes are coalesced into (count: MiniByte, hash) runs.
+ * A fresh candidate with all-distinct parents serializes as 32 runs.
+ */
+export declare function serializeSuperParents(superParents: string[]): Uint8Array;
+/**
+ * Build the empty burn transaction bytes (TxBody.writeDataStream fields 5-6).
+ *
+ * Equivalent to serializeTransaction({ linkHash: [0x00], inputs: [], outputs: [],
+ * state: [] }): 0 inputs, 0 outputs, 0 state, linkHash = ZERO_TXPOWID (1 byte).
+ */
+export declare function buildEmptyBurnTxBytes(): Uint8Array;
+/**
+ * Build the empty burn witness bytes (TxBody.writeDataStream field 6).
+ * 0 signatures, 0 coinproofs, 0 scriptproofs.
+ */
+export declare function buildEmptyBurnWitnessBytes(): Uint8Array;
+/**
+ * Build the empty transaction bytes (TxBody.writeDataStream field 3).
+ * 0 inputs, 0 outputs, 0 state, linkHash = ZERO_TXPOWID (1 byte).
+ */
+export declare function buildEmptyTransactionBytes(): Uint8Array;
+/**
+ * Build the empty witness bytes (TxBody.writeDataStream field 4).
+ * 0 signatures, 0 coinproofs, 0 scriptproofs.
+ */
+export declare function buildEmptyWitnessBytes(): Uint8Array;
+/**
+ * Build the serialized TxBody for a fresh block candidate.
+ *
+ * Mirrors TxBody.writeDataStream with an empty transaction and witness (the
+ * same shape Minima's MINEPULSE automine uses for block candidates):
+ *   mPRNG | mTxnDifficulty | mTransaction | mWitness |
+ *   mBurnTransaction | mBurnWitness | mTxPowIDList
+ *
+ * @param prng          32-byte PRNG (deterministic for tests; random otherwise).
+ * @param txnDifficulty Transaction difficulty (32-byte hex). For a block
+ *                      candidate this is typically the block difficulty.
+ */
+export declare function buildEmptyBlockBody(prng: Uint8Array, txnDifficulty: string): Uint8Array;
+/**
+ * Assemble the complete Minima TxPoW wire format:
+ *   TxHeader | 0x01 (hasBody) | TxBody
+ *
+ * This is the representation required for network submission of a genuine L1
+ * block candidate. A mined header alone is NOT sufficient.
+ *
+ * @param headerBytes  Serialized TxHeader bytes (with the winning nonce).
+ * @param bodyBytes    Serialized TxBody bytes.
+ */
+export declare function assembleTxPoWEnvelope(headerBytes: Uint8Array, bodyBytes: Uint8Array): Uint8Array;
+/**
+ * Build the TxHeader tail (everything after the nonce field) for a block
+ * candidate with the given customHash commitment.
+ *
+ * Field order (TxHeader.writeDataStream):
+ *   mNonce | mChainID | mTimeMilli | mBlockNumber | mBlockDifficulty |
+ *   super-parents RLE | mMMRRoot | mMMRTotal | mMagic | mCustomHash | mTxBodyHash
+ *
+ * @param template     The current Minima work template.
+ * @param customHash   The action commitment (32-byte hex) to place in mCustomHash.
+ * @param txBodyHash   SHA3-256 of the serialized TxBody (32-byte hex).
+ */
+export declare function buildBlockHeaderTail(template: MinimaWorkTemplate, customHash: string, txBodyHash: string): Uint8Array;
+/**
+ * Compute the TxPoW ID for a mined block-candidate header.
+ * txpowId = SHA3-256(serialized TxHeader).
+ */
+export declare function computeBlockCandidateId(headerBytes: Uint8Array): Uint8Array;
+/**
+ * Check whether a txpowId beats the block target (i.e. is a genuine Minima block).
+ * valid = txpowId < blockDifficulty (big-endian 256-bit comparison).
+ */
+export declare function isBlockWinner(txpowId: Uint8Array, blockDifficulty: string): boolean;
+/**
+ * Compute the Minima Super level for a TxPoW ID against a block difficulty,
+ * with Minima's exact integer semantics.
+ *
+ * From TxPoW.calculateTXPOWID() / getSuperLevel():
+ *   quot  = blockDifficulty / txpowId          (unsigned BigInteger division)
+ *   super = quot.bitLength() - 1               (floor(log2(quot)))
+ *   if super >= MINIMA_CASCADE_LEVELS (32) → clamp to 31
+ *
+ * When the TxPoW is NOT a block (txpowId >= blockDifficulty), quot = 0,
+ * bitLength(0) = 0, so super = -1.
+ *
+ * Result:
+ *   -1   — not a Minima block
+ *    0   — ordinary/base Minima block (Super-0)
+ *    1..31 — Super-1 … Super-31 (stronger blocks; 31 is the maximum represented)
+ *
+ * @param txpowId        SHA3-256(header), 32 bytes.
+ * @param blockDifficulty 32-byte hex block difficulty target.
+ */
+export declare function computeSuperLevel(txpowId: Uint8Array, blockDifficulty: string): number;
+/**
+ * Default staleness policy: a template is "current enough" for admission if it
+ * was captured within the window, and "current" for L1 broadcast if it matches
+ * the latest template id.
+ */
+export declare function templateFreshness(template: MinimaWorkTemplate, latest: MinimaWorkTemplate | null, options?: {
+    admissionWindowMs?: number;
+    now?: number;
+}): {
+    admissionValid: boolean;
+    broadcastable: boolean;
+};
+/**
+ * Reconstruct the complete Minima TxPoW envelope for a proof.
+ *
+ * Rebuilds the empty block TxBody deterministically, recomputes the body hash,
+ * and reassembles header | 0x01 | body. Used by verification to confirm the
+ * proof corresponds to a complete, Minima-serializable candidate.
+ *
+ * @param proofTemplate The template the proof was mined against.
+ * @param headerBytes   The mined TxHeader bytes.
+ * @param prng          The PRNG used when the proof was mined (32 bytes).
+ */
+export declare function reconstructTxPoWEnvelope(proofTemplate: MinimaWorkTemplate, headerBytes: Uint8Array, prng: Uint8Array): {
+    envelope: Uint8Array;
+    bodyHash: string;
+};

package/dist/admission/template.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * admission/template.ts — Minima block-candidate template handling.
+ *
+ * Builds a TxHeader tail that is structurally capable of becoming a legitimate
+ * Minima block. The fields (block number, block difficulty, super-parents, MMR
+ * root/total, magic, time) come from the current chain tip via an injected
+ * MinimaWorkTemplateProvider — mirroring TxPoWGenerator.generateTxPoW in
+ * Minima. The action commitment is placed in the header's customHash field.
+ *
+ * The TxPoW package stays transport/node-client agnostic: callers inject the
+ * template provider. A real Minima node / Axia integration supplies live chain
+ * state; tests supply fixtures.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeSuperParents = serializeSuperParents;
+exports.buildEmptyBurnTxBytes = buildEmptyBurnTxBytes;
+exports.buildEmptyBurnWitnessBytes = buildEmptyBurnWitnessBytes;
+exports.buildEmptyTransactionBytes = buildEmptyTransactionBytes;
+exports.buildEmptyWitnessBytes = buildEmptyWitnessBytes;
+exports.buildEmptyBlockBody = buildEmptyBlockBody;
+exports.assembleTxPoWEnvelope = assembleTxPoWEnvelope;
+exports.buildBlockHeaderTail = buildBlockHeaderTail;
+exports.computeBlockCandidateId = computeBlockCandidateId;
+exports.isBlockWinner = isBlockWinner;
+exports.computeSuperLevel = computeSuperLevel;
+exports.templateFreshness = templateFreshness;
+exports.reconstructTxPoWEnvelope = reconstructTxPoWEnvelope;
+const core_1 = require("@totemsdk/core");
+const core_2 = require("@totemsdk/core");
+const constants_js_1 = require("../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;
+}
+function toHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Serialize the super-parent RLE runs per TxHeader.writeDataStream.
+ *
+ * Consecutive equal hashes are coalesced into (count: MiniByte, hash) runs.
+ * A fresh candidate with all-distinct parents serializes as 32 runs.
+ */
+function serializeSuperParents(superParents) {
+    if (superParents.length !== constants_js_1.CASCADE_LEVELS) {
+        throw new Error(`superParents must have ${constants_js_1.CASCADE_LEVELS} entries, got ${superParents.length}`);
+    }
+    const parts = [];
+    let runHash = superParents[0];
+    let runCount = 1;
+    for (let i = 1; i < superParents.length; i++) {
+        if (superParents[i] === runHash) {
+            runCount++;
+        }
+        else {
+            parts.push(new Uint8Array([runCount]));
+            parts.push((0, core_2.writeHashToStream)(hexToBytes(runHash)));
+            runHash = superParents[i];
+            runCount = 1;
+        }
+    }
+    parts.push(new Uint8Array([runCount]));
+    parts.push((0, core_2.writeHashToStream)(hexToBytes(runHash)));
+    return (0, core_2.concat)(...parts);
+}
+/**
+ * Build the empty burn transaction bytes (TxBody.writeDataStream fields 5-6).
+ *
+ * Equivalent to serializeTransaction({ linkHash: [0x00], inputs: [], outputs: [],
+ * state: [] }): 0 inputs, 0 outputs, 0 state, 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 (TxBody.writeDataStream field 6).
+ * 0 signatures, 0 coinproofs, 0 scriptproofs.
+ */
+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));
+}
+/**
+ * Build the empty transaction bytes (TxBody.writeDataStream field 3).
+ * 0 inputs, 0 outputs, 0 state, linkHash = ZERO_TXPOWID (1 byte).
+ */
+function buildEmptyTransactionBytes() {
+    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 witness bytes (TxBody.writeDataStream field 4).
+ * 0 signatures, 0 coinproofs, 0 scriptproofs.
+ */
+function buildEmptyWitnessBytes() {
+    return (0, core_2.concat)((0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0));
+}
+/**
+ * Build the serialized TxBody for a fresh block candidate.
+ *
+ * Mirrors TxBody.writeDataStream with an empty transaction and witness (the
+ * same shape Minima's MINEPULSE automine uses for block candidates):
+ *   mPRNG | mTxnDifficulty | mTransaction | mWitness |
+ *   mBurnTransaction | mBurnWitness | mTxPowIDList
+ *
+ * @param prng          32-byte PRNG (deterministic for tests; random otherwise).
+ * @param txnDifficulty Transaction difficulty (32-byte hex). For a block
+ *                      candidate this is typically the block difficulty.
+ */
+function buildEmptyBlockBody(prng, txnDifficulty) {
+    return (0, core_2.concat)((0, core_2.writeHashToStream)(prng), (0, core_2.writeMiniData)(hexToBytes(txnDifficulty)), buildEmptyTransactionBytes(), buildEmptyWitnessBytes(), buildEmptyBurnTxBytes(), buildEmptyBurnWitnessBytes(), (0, core_2.writeMiniNumber)(0n, 0));
+}
+/**
+ * Assemble the complete Minima TxPoW wire format:
+ *   TxHeader | 0x01 (hasBody) | TxBody
+ *
+ * This is the representation required for network submission of a genuine L1
+ * block candidate. A mined header alone is NOT sufficient.
+ *
+ * @param headerBytes  Serialized TxHeader bytes (with the winning nonce).
+ * @param bodyBytes    Serialized TxBody bytes.
+ */
+function assembleTxPoWEnvelope(headerBytes, bodyBytes) {
+    return (0, core_2.concat)(headerBytes, new Uint8Array([0x01]), bodyBytes);
+}
+/**
+ * Build the TxHeader tail (everything after the nonce field) for a block
+ * candidate with the given customHash commitment.
+ *
+ * Field order (TxHeader.writeDataStream):
+ *   mNonce | mChainID | mTimeMilli | mBlockNumber | mBlockDifficulty |
+ *   super-parents RLE | mMMRRoot | mMMRTotal | mMagic | mCustomHash | mTxBodyHash
+ *
+ * @param template     The current Minima work template.
+ * @param customHash   The action commitment (32-byte hex) to place in mCustomHash.
+ * @param txBodyHash   SHA3-256 of the serialized TxBody (32-byte hex).
+ */
+function buildBlockHeaderTail(template, customHash, txBodyHash) {
+    return (0, core_2.concat)((0, core_2.writeMiniData)(hexToBytes(template.chainId)), (0, core_2.writeMiniNumber)(template.timeMilli, 0), (0, core_2.writeMiniNumber)(template.blockNumber, 0), (0, core_2.writeMiniData)(hexToBytes(template.blockDifficulty)), serializeSuperParents(template.superParents), (0, core_2.writeHashToStream)(hexToBytes(template.mmrRoot)), (0, core_2.writeMiniNumber)(template.mmrTotal, 0), hexToBytes(template.magic), (0, core_2.writeHashToStream)(hexToBytes(customHash)), (0, core_2.writeHashToStream)(hexToBytes(txBodyHash)));
+}
+/**
+ * Compute the TxPoW ID for a mined block-candidate header.
+ * txpowId = SHA3-256(serialized TxHeader).
+ */
+function computeBlockCandidateId(headerBytes) {
+    return (0, core_1.sha3_256)(headerBytes);
+}
+/**
+ * Check whether a txpowId beats the block target (i.e. is a genuine Minima block).
+ * valid = txpowId < blockDifficulty (big-endian 256-bit comparison).
+ */
+function isBlockWinner(txpowId, blockDifficulty) {
+    const target = hexToBytes(blockDifficulty);
+    for (let i = 0; i < 32; i++) {
+        if (txpowId[i] < target[i])
+            return true;
+        if (txpowId[i] > target[i])
+            return false;
+    }
+    return false;
+}
+/** Java BigInteger.bitLength() for non-negative values. bitLength(0) = 0. */
+function bigIntBitLength(x) {
+    if (x <= 0n)
+        return 0;
+    let bits = 0;
+    let v = x;
+    while (v > 0n) {
+        v >>= 1n;
+        bits++;
+    }
+    return bits;
+}
+function bytesToBigInt(bytes) {
+    let v = 0n;
+    for (let i = 0; i < bytes.length; i++) {
+        v = (v << 8n) | BigInt(bytes[i]);
+    }
+    return v;
+}
+/**
+ * Compute the Minima Super level for a TxPoW ID against a block difficulty,
+ * with Minima's exact integer semantics.
+ *
+ * From TxPoW.calculateTXPOWID() / getSuperLevel():
+ *   quot  = blockDifficulty / txpowId          (unsigned BigInteger division)
+ *   super = quot.bitLength() - 1               (floor(log2(quot)))
+ *   if super >= MINIMA_CASCADE_LEVELS (32) → clamp to 31
+ *
+ * When the TxPoW is NOT a block (txpowId >= blockDifficulty), quot = 0,
+ * bitLength(0) = 0, so super = -1.
+ *
+ * Result:
+ *   -1   — not a Minima block
+ *    0   — ordinary/base Minima block (Super-0)
+ *    1..31 — Super-1 … Super-31 (stronger blocks; 31 is the maximum represented)
+ *
+ * @param txpowId        SHA3-256(header), 32 bytes.
+ * @param blockDifficulty 32-byte hex block difficulty target.
+ */
+function computeSuperLevel(txpowId, blockDifficulty) {
+    const diffBigInt = bytesToBigInt(hexToBytes(blockDifficulty));
+    const idBigInt = bytesToBigInt(txpowId);
+    // Not a block: quot = 0 → super = -1
+    if (idBigInt >= diffBigInt)
+        return -1;
+    const quot = diffBigInt / idBigInt;
+    let superLevel = bigIntBitLength(quot) - 1;
+    // Clamp to the maximum represented Super level, exactly as Minima does.
+    if (superLevel >= constants_js_1.CASCADE_LEVELS) {
+        superLevel = constants_js_1.CASCADE_LEVELS - 1;
+    }
+    return superLevel;
+}
+/**
+ * Default staleness policy: a template is "current enough" for admission if it
+ * was captured within the window, and "current" for L1 broadcast if it matches
+ * the latest template id.
+ */
+function templateFreshness(template, latest, options) {
+    const now = options?.now ?? Date.now();
+    const windowMs = options?.admissionWindowMs ?? 5 * 60 * 1000;
+    const age = now - template.capturedAt;
+    const admissionValid = age >= 0 && age <= windowMs;
+    const broadcastable = latest !== null && template.templateId === latest.templateId;
+    return { admissionValid, broadcastable };
+}
+/**
+ * Reconstruct the complete Minima TxPoW envelope for a proof.
+ *
+ * Rebuilds the empty block TxBody deterministically, recomputes the body hash,
+ * and reassembles header | 0x01 | body. Used by verification to confirm the
+ * proof corresponds to a complete, Minima-serializable candidate.
+ *
+ * @param proofTemplate The template the proof was mined against.
+ * @param headerBytes   The mined TxHeader bytes.
+ * @param prng          The PRNG used when the proof was mined (32 bytes).
+ */
+function reconstructTxPoWEnvelope(proofTemplate, headerBytes, prng) {
+    const body = buildEmptyBlockBody(prng, proofTemplate.blockDifficulty);
+    const bodyHash = toHex((0, core_1.sha3_256)(body));
+    const envelope = assembleTxPoWEnvelope(headerBytes, body);
+    return { envelope, bodyHash };
+}