@totemsdk/txpow 1.0.0 → 1.0.1

package/dist/admission/types.d.ts

@@ -0,0 +1,224 @@
+/**
+ * admission/types.ts — Machine Work Admission core types.
+ *
+ * Machine Work Admission lets a receiver require a sender to perform bounded
+ * computational work before scarce machine resources are allocated. The work
+ * searches the nonce space of a real current Minima block candidate, so the
+ * same hashes that admit the machine action also search for Minima L1 blocks.
+ *
+ * The three distinct concepts:
+ *   - WorkChallenge  — the receiver-controlled admission requirement
+ *   - MachineWorkAction — the domain-separated application action commitment
+ *   - MachineWorkAdmissionProof — the mined result
+ *
+ * The TxPoW package knows only "there is an application action represented by
+ * canonical bytes". It does NOT know about negotiation, compute, storage, or
+ * any particular Edge resource. Domain-specific packages supply the action.
+ */
+/** Current Machine Work Admission protocol version. */
+export declare const MACHINE_WORK_ADMISSION_VERSION = 1;
+/** Canonical protocol domain prefix for the commitment hash. */
+export declare const MACHINE_WORK_DOMAIN = "totem.machine-work-admission";
+/**
+ * The receiver controls the admission requirement.
+ *
+ * A challenge must be unique enough to prevent useful pre-mining, must expire,
+ * must bind to the intended receiver, and must bind to an application domain.
+ * `target` is an absolute cryptographic target: verification is `hash < target`.
+ */
+export interface WorkChallenge {
+    /** Protocol version. */
+    version: number;
+    /** Unique challenge identifier (receiver-generated, prevents pre-mining). */
+    challengeId: string;
+    /** The intended receiver this challenge is bound to. */
+    recipient: string;
+    /** Application domain (e.g. "totem.negotiation.proposal"). Open-ended. */
+    domain: string;
+    /** Absolute 32-byte cryptographic target (big-endian 256-bit). */
+    target: string;
+    /** Receiver-generated random nonce to prevent pre-mining. */
+    nonce: string;
+    /** Epoch milliseconds when the challenge was issued. */
+    issuedAt: number;
+    /** Epoch milliseconds after which the challenge is invalid. */
+    expiresAt: number;
+    /** Optional network identifier (e.g. "mainnet", "testnet"). */
+    network?: string;
+}
+/**
+ * The application action, represented in a generic domain-separated form.
+ *
+ * Only a commitment to this action enters the TxPoW header — never the
+ * application payload itself. The application remains off-chain.
+ */
+export interface MachineWorkAction {
+    /** Protocol version. */
+    version: number;
+    /** Application domain (e.g. "totem.compute.reserve"). Open-ended. */
+    domain: string;
+    /** The sender performing the work. */
+    sender: string;
+    /** The intended recipient. */
+    recipient: string;
+    /** Unique action identifier. */
+    actionId: string;
+    /** SHA3-256 hex commitment to the application payload (off-chain). */
+    payloadHash: string;
+    /** Optional domain-specific context (canonicalized into the commitment). */
+    context?: Record<string, string>;
+}
+/**
+ * A Minima block-candidate work template.
+ *
+ * This is the chain state a candidate is mined against. It is structurally
+ * capable of becoming a legitimate Minima block: block number, block
+ * difficulty, super-parents, MMR root/total, magic, and time are all taken
+ * from the current chain tip (see TxPoWGenerator.generateTxPoW in Minima).
+ */
+export interface MinimaWorkTemplate {
+    /** Chain ID (MAIN_NET = 0x00). */
+    chainId: string;
+    /** Block number = current tip + 1. */
+    blockNumber: bigint;
+    /** Current block difficulty target (32-byte hex). */
+    blockDifficulty: string;
+    /** Super-parent hashes at each cascade level (RLE-serialized). */
+    superParents: string[];
+    /** Current MMR root (32-byte hex). */
+    mmrRoot: string;
+    /** Current MMR total (sum of all coins). */
+    mmrTotal: bigint;
+    /** Serialized Magic struct (hex). */
+    magic: string;
+    /** Candidate timestamp in epoch milliseconds. */
+    timeMilli: bigint;
+    /** Template identifier (e.g. tip txpowId) for staleness checks. */
+    templateId: string;
+    /** Epoch milliseconds when the template was captured. */
+    capturedAt: number;
+}
+/**
+ * Provider abstraction for the current Minima block-candidate template.
+ *
+ * The TxPoW package remains transport/node-client agnostic: callers inject a
+ * provider that fetches the current template from a Minima node, Axia, or a
+ * test fixture.
+ *
+ * `MinimaWorkRelay` is the preferred long-term relay boundary. The legacy
+ * `broadcastBlockCandidate` callback is retained as a compatibility/fallback
+ * path only — new consumers should use `relay` via `MinimaWorkRelay` and not
+ * build around the lossy `candidate: unknown` shape.
+ */
+export interface MinimaWorkTemplateProvider {
+    /** Fetch the current block-candidate template. */
+    getCurrentTemplate(): Promise<MinimaWorkTemplate>;
+    /** Optional: fetch the latest template for freshness checks. Falls back to getCurrentTemplate. */
+    getLatestTemplate?(): Promise<MinimaWorkTemplate>;
+    /** Optional: validate a template before mining against it. */
+    validateTemplate?(template: MinimaWorkTemplate): Promise<boolean>;
+    /**
+     * @deprecated Prefer `MinimaWorkRelay.submitBlock` (complete envelope).
+     * Retained for compatibility; only invoked for genuine Minima blocks
+     * (Super-0 … Super-31) when no relay is configured.
+     */
+    broadcastBlockCandidate?(candidate: MachineWorkAdmissionProof): Promise<void>;
+}
+/**
+ * Relay boundary for a complete Minima TxPoW envelope.
+ *
+ * Keeps Minima networking outside core mining logic. A future
+ * @totemsdk/minima-rpc or chain-provider adapter may implement this port.
+ * Duplicate relay attempts must be safe/idempotent at the integration boundary.
+ */
+export interface MinimaWorkRelay {
+    /** Submit a complete Minima TxPoW envelope for block relay. */
+    submitBlock(envelope: Uint8Array): Promise<void>;
+}
+/**
+ * The mined Machine Work Admission proof.
+ *
+ * Reuses the existing TxPoW types where possible:
+ *   - `txpow`          — serialized TxHeader bytes (SHA3-256 of these is `txpowId`)
+ *   - `txpowEnvelope`  — the COMPLETE Minima TxPoW wire format
+ *                        (header | 0x01 hasBody | body), required for network
+ *                        submission of a genuine Minima block
+ *   - `txpowId`        — SHA3-256(header)
+ *
+ * `qualifiesAsMinimaBlock`, `isBlock`, and `superLevel` are DERIVED METADATA
+ * recorded at mining time. They are never trusted by verification —
+ * verification recomputes all of them from the re-derived txpowId and the
+ * template's block difficulty.
+ */
+export interface MachineWorkAdmissionProof {
+    /** Protocol version. */
+    version: number;
+    /** Hex commitment placed in the TxPoW header's customHash field. */
+    actionCommitment: string;
+    /** The challenge this proof was mined against. */
+    challengeId: string;
+    /** The admission target (32-byte hex) the proof satisfies. */
+    admissionTarget: string;
+    /** Serialized TxHeader bytes (SHA3-256 of these is the TxPoW ID). */
+    txpow: string;
+    /** Complete Minima TxPoW envelope (header | 0x01 | body) for block relay. */
+    txpowEnvelope: string;
+    /** SHA3-256(header) — the canonical TxPoW ID. */
+    txpowId: string;
+    /** The winning nonce. */
+    nonce: string;
+    /** Epoch milliseconds when the proof was mined. */
+    minedAt: number;
+    /** Always true for a valid admission proof. */
+    qualifiesForAdmission: true;
+    /**
+     * DERIVED METADATA: true when the mined hash also beats the block difficulty
+     * encoded by the candidate template (i.e. a genuine Minima block). Never
+     * trusted by verification — it is recomputed from the re-derived txpowId.
+     */
+    qualifiesAsMinimaBlock: boolean;
+    /**
+     * DERIVED METADATA: Minima Super level (-1 = not a block, 0..31 = block
+     * strength). Never trusted by verification.
+     */
+    superLevel: number;
+    /** DERIVED METADATA: superLevel >= 0. Never trusted by verification. */
+    isBlock: boolean;
+    /** Template the proof was mined against (for staleness policy). */
+    template: MinimaWorkTemplate;
+}
+/**
+ * Result of verifying a Machine Work Admission proof.
+ *
+ * Three distinct claims, never to be confused:
+ *   A. `valid` — the hash satisfies the challenge target (admission proof).
+ *   B. `superLevel` / `isBlock` — the hash ALSO satisfies the block difficulty
+ *      encoded by the candidate template, yielding an exact Minima Super level.
+ *   C. `broadcastable` — the candidate still corresponds to sufficiently
+ *      current live Minima state AND can be submitted through the relay.
+ *
+ * A stale candidate may remain `valid = true` (and `superLevel >= 0`) while
+ * `broadcastable = false`.
+ *
+ * `superLevel === -1 ⇔ isBlock === false`, and
+ * `superLevel >= 0 ⇔ isBlock === true`. Verification recomputes these — it
+ * never trusts sender-supplied `isBlock`/`superLevel` metadata.
+ */
+export interface WorkAdmissionVerification {
+    /** Level A: the hash satisfies the challenge target. */
+    valid: boolean;
+    reason?: string;
+    /**
+     * Level B: exact Minima Super level of the candidate hash.
+     * -1 = not a Minima block; 0..31 = Super-0 … Super-31 block strength.
+     */
+    superLevel?: number;
+    /** Level B: superLevel >= 0 (a genuine Minima block). */
+    isBlock?: boolean;
+    /**
+     * Level C: isBlock AND the template is current AND a live template provider
+     * was supplied. Undefined in offline mode (no provider) — offline
+     * verification must NOT claim Minima block contribution.
+     */
+    broadcastable?: boolean;
+}

package/dist/admission/types.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * admission/types.ts — Machine Work Admission core types.
+ *
+ * Machine Work Admission lets a receiver require a sender to perform bounded
+ * computational work before scarce machine resources are allocated. The work
+ * searches the nonce space of a real current Minima block candidate, so the
+ * same hashes that admit the machine action also search for Minima L1 blocks.
+ *
+ * The three distinct concepts:
+ *   - WorkChallenge  — the receiver-controlled admission requirement
+ *   - MachineWorkAction — the domain-separated application action commitment
+ *   - MachineWorkAdmissionProof — the mined result
+ *
+ * The TxPoW package knows only "there is an application action represented by
+ * canonical bytes". It does NOT know about negotiation, compute, storage, or
+ * any particular Edge resource. Domain-specific packages supply the action.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MACHINE_WORK_DOMAIN = exports.MACHINE_WORK_ADMISSION_VERSION = void 0;
+/** Current Machine Work Admission protocol version. */
+exports.MACHINE_WORK_ADMISSION_VERSION = 1;
+/** Canonical protocol domain prefix for the commitment hash. */
+exports.MACHINE_WORK_DOMAIN = 'totem.machine-work-admission';

package/dist/admission/verify.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+import { type MachineWorkAction, type MachineWorkAdmissionProof, type MinimaWorkTemplate, type MinimaWorkTemplateProvider, type WorkChallenge, type WorkAdmissionVerification } from './types.js';
+export interface VerifyWorkAdmissionOptions {
+    /** Override the current time for deterministic testing. */
+    now?: number;
+    /** Staleness window (ms) within which a template is acceptable for admission. */
+    admissionWindowMs?: number;
+    /** The latest template, for broadcastability checks. */
+    latestTemplate?: MinimaWorkTemplate | null;
+}
+/**
+ * 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.
+ */
+export declare function verifyWorkAdmission(action: MachineWorkAction, challenge: WorkChallenge, proof: MachineWorkAdmissionProof, templateProvider?: MinimaWorkTemplateProvider, options?: VerifyWorkAdmissionOptions): Promise<WorkAdmissionVerification>;

package/dist/admission/verify.js

@@ -0,0 +1,144 @@
+"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. Template freshness for admission
+    const freshness = (0, template_js_1.templateFreshness)(proof.template, options?.latestTemplate ?? null, {
+        admissionWindowMs: options?.admissionWindowMs,
+        now: options?.now,
+    });
+    if (!freshness.admissionValid) {
+        return { valid: false, reason: 'proof template is stale for admission' };
+    }
+    // 6. Level B: independently recompute the exact Minima Super level. Never
+    //    trust proof.superLevel / proof.isBlock / proof.qualifiesAsMinimaBlock.
+    const superLevel = (0, template_js_1.computeSuperLevel)(txpowId, proof.template.blockDifficulty);
+    const isBlock = superLevel >= 0;
+    // 7. Level C: broadcastability requires a live template provider AND a
+    //    current template. Offline mode leaves broadcastable undefined.
+    let broadcastable;
+    if (templateProvider) {
+        let latest;
+        if (templateProvider.getLatestTemplate) {
+            latest = await templateProvider.getLatestTemplate();
+        }
+        else if (options?.latestTemplate) {
+            latest = options.latestTemplate;
+        }
+        else {
+            latest = await templateProvider.getCurrentTemplate();
+        }
+        broadcastable = isBlock && latest.templateId === proof.template.templateId;
+    }
+    return { valid: true, superLevel, isBlock, broadcastable };
+}
+function toHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}

package/dist/index.d.ts

@@ -20,8 +20,9 @@
 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, isLessThan, setBrowserWorkerUrl, type MineResult, type MineOptions, } from './mine.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, type TxPowParams } 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/index.js

@@ -19,7 +19,7 @@
  *   if (!check.valid) drop(check.reason);
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.estimateMiningCost = exports.calibrateHashRate = exports.verifyTxPoWParts = exports.verifyTxPoWWork = exports.verifyProofOfWork = exports.fetchTxPowTarget = exports.isWasmAvailable = exports.getBrowserWasmUrl = exports.setWasmUrl = exports.setBrowserWorkerUrl = exports.isLessThan = 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 = 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.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;
 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; } });
@@ -36,6 +36,8 @@ Object.defineProperty(exports, "serializeMagic", { enumerable: true, get: functi
 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");
@@ -51,3 +53,33 @@ Object.defineProperty(exports, "verifyTxPoWParts", { enumerable: true, get: func
 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/mine.d.ts

@@ -72,6 +72,17 @@ export interface MineOptions {
  * Used to check: txpowId < mTxnDifficulty.
  */
 export declare function isLessThan(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * 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.
+ */
+export declare function buildHeaderTail(txBodyHash: Uint8Array, timeMilli: bigint): Uint8Array;
 /**
  * Configure the URL of the browser.worker.js bundle so that `mineTxPoW()`
  * can spawn a Web Worker in browser contexts.
@@ -84,6 +95,19 @@ export declare function isLessThan(a: Uint8Array, b: Uint8Array): boolean;
  *   setBrowserWorkerUrl(browser.runtime.getURL('mine-worker.js'));
  */
 export declare function setBrowserWorkerUrl(url: string): void;
+/**
+ * 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.
+ */
+export declare function mineHeaderTail(headerTail: Uint8Array, target: Uint8Array, options?: MineOptions): Promise<MineResult>;
 /**
  * Run the mining loop in the current thread/task.
  * Called directly by the Node.js worker, and by the browser code path.

package/dist/mine.js

@@ -29,7 +29,9 @@
  */
 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");
@@ -70,6 +72,11 @@ function nextNonceBoundary(nonce) {
  * 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));
@@ -283,19 +290,24 @@ async function mineTxPoWViaNodeWorker(txBodyBytes, txnDifficulty, options) {
 // In-process mining loop
 // ─────────────────────────────────────────────────────────────────────────────
 /**
- * Run the mining loop in the current thread/task.
- * Called directly by the Node.js worker, and by the browser code path.
+ * 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 mineTxPoWInProcess(txBodyBytes, txnDifficulty, options) {
+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 timeMilli = options?.timeMilli ?? BigInt(Date.now());
     const forceJs = options?.forceJs ?? false;
-    const bodyHash = (0, core_1.sha3_256)(txBodyBytes);
-    const headerTail = buildHeaderTail(bodyHash, timeMilli);
     const useWasm = !forceJs && (await (0, mine_wasm_js_1.isWasmAvailable)());
     const startTime = Date.now();
     let totalIterations = 0n;
@@ -319,10 +331,10 @@ async function mineTxPoWInProcess(txBodyBytes, txnDifficulty, options) {
         let found;
         if (useWasm) {
             found = await (0, mine_wasm_js_1.mineChunkWasm)(headerBuf.slice(), // WASM gets its own copy to avoid aliasing
-            2, nonceValueLen, txnDifficulty, nonce, chunkEnd - nonce);
+            2, nonceValueLen, target, nonce, chunkEnd - nonce);
         }
         else {
-            found = mineChunkJs(headerBuf, nonceValueLen, txnDifficulty, nonce, chunkEnd);
+            found = mineChunkJs(headerBuf, nonceValueLen, target, nonce, chunkEnd);
         }
         // ── End mutually exclusive section ───────────────────────────────────────
         if (found !== null) {
@@ -349,6 +361,16 @@ async function mineTxPoWInProcess(txBodyBytes, txnDifficulty, options) {
         });
     }
 }
+/**
+ * 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
 // ─────────────────────────────────────────────────────────────────────────────