@totemsdk/txpow 1.0.2 → 1.1.0

package/dist/cjs/admission/challenge.d.ts

@@ -0,0 +1,66 @@
+/**
+ * admission/challenge.ts — WorkChallenge creation and validation.
+ *
+ * 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. Verification NEVER trusts
+ * sender-reported hardware speed — it only checks `hash < target`.
+ *
+ * ── AUTHENTICATION BOUNDARY ────────────────────────────────────────────────
+ * `validateWorkChallenge()` validates structural/freshness/domain/recipient
+ * properties but does NOT prove that the claimed recipient actually issued the
+ * challenge. A WorkChallenge is a plain data object; anyone can construct one
+ * claiming any recipient. Proving the issuer requires authenticating the
+ * enclosing message (e.g. a signed machine-to-machine protocol message in the
+ * Edge negotiation layer). @totemsdk/txpow deliberately does NOT implement a
+ * parallel identity/signature system — that belongs to the application layer.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+import { type WorkChallenge } from './types.js';
+/** Default challenge lifetime: 5 minutes. */
+export declare const DEFAULT_CHALLENGE_TTL_MS: number;
+/** Maximum challenge lifetime: 24 hours. */
+export declare const MAX_CHALLENGE_TTL_MS: number;
+/**
+ * Create a WorkChallenge.
+ *
+ * @param recipient  The intended receiver the challenge binds to.
+ * @param domain     Application domain (open-ended, e.g. "totem.compute.reserve").
+ * @param target     Absolute 32-byte cryptographic target (hex).
+ * @param options    Optional overrides (challengeId, nonce, ttl, issuedAt, network).
+ */
+export declare function createWorkChallenge(recipient: string, domain: string, target: string, options?: {
+    challengeId?: string;
+    nonce?: string;
+    ttlMs?: number;
+    issuedAt?: number;
+    network?: string;
+}): WorkChallenge;
+/**
+ * Validate a WorkChallenge at verification time.
+ *
+ * Checks structural integrity, expiry, and that the challenge binds to the
+ * expected recipient/domain. Does NOT check the proof hash — that is the
+ * caller's job via verifyWorkAdmission.
+ */
+export declare function validateWorkChallenge(challenge: WorkChallenge, expected?: {
+    recipient?: string;
+    domain?: string;
+    now?: number;
+}): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Derive a stable challenge fingerprint (SHA3-256 of canonical challenge bytes).
+ * Useful for higher-level code that tracks already-consumed challenge IDs.
+ */
+export declare function challengeFingerprint(challenge: WorkChallenge): string;
+/**
+ * Canonical serialization of a WorkChallenge.
+ *
+ * Deterministic field ordering with length-prefixed strings so that no
+ * ambiguous concatenation is possible. Used for the commitment and for
+ * challenge fingerprints.
+ */
+export declare function canonicalChallenge(challenge: WorkChallenge): string;

package/dist/cjs/admission/challenge.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * admission/challenge.ts — WorkChallenge creation and validation.
+ *
+ * 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. Verification NEVER trusts
+ * sender-reported hardware speed — it only checks `hash < target`.
+ *
+ * ── AUTHENTICATION BOUNDARY ────────────────────────────────────────────────
+ * `validateWorkChallenge()` validates structural/freshness/domain/recipient
+ * properties but does NOT prove that the claimed recipient actually issued the
+ * challenge. A WorkChallenge is a plain data object; anyone can construct one
+ * claiming any recipient. Proving the issuer requires authenticating the
+ * enclosing message (e.g. a signed machine-to-machine protocol message in the
+ * Edge negotiation layer). @totemsdk/txpow deliberately does NOT implement a
+ * parallel identity/signature system — that belongs to the application layer.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CHALLENGE_TTL_MS = exports.DEFAULT_CHALLENGE_TTL_MS = void 0;
+exports.createWorkChallenge = createWorkChallenge;
+exports.validateWorkChallenge = validateWorkChallenge;
+exports.challengeFingerprint = challengeFingerprint;
+exports.canonicalChallenge = canonicalChallenge;
+const core_1 = require("@totemsdk/core");
+const types_js_1 = require("./types.js");
+/** Default challenge lifetime: 5 minutes. */
+exports.DEFAULT_CHALLENGE_TTL_MS = 5 * 60 * 1000;
+/** Maximum challenge lifetime: 24 hours. */
+exports.MAX_CHALLENGE_TTL_MS = 24 * 60 * 60 * 1000;
+function toHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+function randomHex(bytes) {
+    const out = new Uint8Array(bytes);
+    if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
+        throw new Error('SECURITY: crypto.getRandomValues unavailable — cannot generate secure random challenge');
+    }
+    crypto.getRandomValues(out);
+    return toHex(out);
+}
+/**
+ * Create a WorkChallenge.
+ *
+ * @param recipient  The intended receiver the challenge binds to.
+ * @param domain     Application domain (open-ended, e.g. "totem.compute.reserve").
+ * @param target     Absolute 32-byte cryptographic target (hex).
+ * @param options    Optional overrides (challengeId, nonce, ttl, issuedAt, network).
+ */
+function createWorkChallenge(recipient, domain, target, options) {
+    if (!recipient)
+        throw new Error('WorkChallenge requires a recipient');
+    if (!domain)
+        throw new Error('WorkChallenge requires a domain');
+    if (!/^[0-9a-fA-F]{64}$/.test(target)) {
+        throw new Error('WorkChallenge target must be 32-byte hex (64 hex chars)');
+    }
+    const ttlMs = options?.ttlMs ?? exports.DEFAULT_CHALLENGE_TTL_MS;
+    if (ttlMs <= 0 || ttlMs > exports.MAX_CHALLENGE_TTL_MS) {
+        throw new Error(`WorkChallenge ttlMs must be in (0, ${exports.MAX_CHALLENGE_TTL_MS}]`);
+    }
+    const issuedAt = options?.issuedAt ?? Date.now();
+    const challengeId = options?.challengeId ?? randomHex(16);
+    const nonce = options?.nonce ?? randomHex(16);
+    return {
+        version: types_js_1.MACHINE_WORK_ADMISSION_VERSION,
+        challengeId,
+        recipient,
+        domain,
+        target,
+        nonce,
+        issuedAt,
+        expiresAt: issuedAt + ttlMs,
+        network: options?.network,
+    };
+}
+/**
+ * Validate a WorkChallenge at verification time.
+ *
+ * Checks structural integrity, expiry, and that the challenge binds to the
+ * expected recipient/domain. Does NOT check the proof hash — that is the
+ * caller's job via verifyWorkAdmission.
+ */
+function validateWorkChallenge(challenge, expected) {
+    if (!challenge || typeof challenge !== 'object') {
+        return { valid: false, reason: 'challenge is not an object' };
+    }
+    if (challenge.version !== types_js_1.MACHINE_WORK_ADMISSION_VERSION) {
+        return { valid: false, reason: `unsupported challenge version ${challenge.version}` };
+    }
+    if (!challenge.challengeId) {
+        return { valid: false, reason: 'challenge is missing challengeId' };
+    }
+    if (!challenge.recipient) {
+        return { valid: false, reason: 'challenge is missing recipient' };
+    }
+    if (!challenge.domain) {
+        return { valid: false, reason: 'challenge is missing domain' };
+    }
+    if (!/^[0-9a-fA-F]{64}$/.test(challenge.target)) {
+        return { valid: false, reason: 'challenge target must be 32-byte hex' };
+    }
+    if (typeof challenge.issuedAt !== 'number' || typeof challenge.expiresAt !== 'number') {
+        return { valid: false, reason: 'challenge issuedAt/expiresAt must be numbers' };
+    }
+    const now = expected?.now ?? Date.now();
+    if (now > challenge.expiresAt) {
+        return { valid: false, reason: 'challenge has expired' };
+    }
+    if (now < challenge.issuedAt - 60000) {
+        return { valid: false, reason: 'challenge issuedAt is in the future' };
+    }
+    if (expected?.recipient && challenge.recipient !== expected.recipient) {
+        return { valid: false, reason: 'challenge recipient mismatch' };
+    }
+    if (expected?.domain && challenge.domain !== expected.domain) {
+        return { valid: false, reason: 'challenge domain mismatch' };
+    }
+    return { valid: true };
+}
+/**
+ * Derive a stable challenge fingerprint (SHA3-256 of canonical challenge bytes).
+ * Useful for higher-level code that tracks already-consumed challenge IDs.
+ */
+function challengeFingerprint(challenge) {
+    const canonical = canonicalChallenge(challenge);
+    return toHex((0, core_1.sha3_256)(new TextEncoder().encode(canonical)));
+}
+/**
+ * Canonical serialization of a WorkChallenge.
+ *
+ * Deterministic field ordering with length-prefixed strings so that no
+ * ambiguous concatenation is possible. Used for the commitment and for
+ * challenge fingerprints.
+ */
+function canonicalChallenge(challenge) {
+    const parts = [];
+    const push = (s) => {
+        parts.push(String(s.length).padStart(8, '0'));
+        parts.push(s);
+    };
+    push('totem.work-challenge');
+    push(String(challenge.version));
+    push(challenge.challengeId);
+    push(challenge.recipient);
+    push(challenge.domain);
+    push(challenge.target);
+    push(challenge.nonce);
+    push(String(challenge.issuedAt));
+    push(String(challenge.expiresAt));
+    if (challenge.network !== undefined)
+        push(challenge.network);
+    return parts.join('');
+}

package/dist/cjs/admission/commitment.d.ts

@@ -0,0 +1,34 @@
+/**
+ * admission/commitment.ts — Canonical domain-separated action commitment.
+ *
+ * The commitment is a deterministic SHA3-256 over a length-prefixed canonical
+ * encoding of every security-relevant field. It changes if any of the
+ * following change:
+ *   - protocol domain / version
+ *   - action domain, sender, recipient, actionId, payloadHash, context
+ *   - challenge challengeId, nonce, target, expiresAt
+ *
+ * The resulting 32-byte commitment is placed in the TxPoW header's customHash
+ * field, so the mined nonce commits the work to sender, recipient, action,
+ * challenge, target, and freshness.
+ */
+import { type MachineWorkAction, type WorkChallenge } from './types.js';
+/**
+ * Canonical serialization of a MachineWorkAction.
+ *
+ * Length-prefixed fields in a fixed order; context keys are sorted so that
+ * equivalent input produces identical output.
+ */
+export declare function canonicalAction(action: MachineWorkAction): string;
+/**
+ * Compute the canonical action commitment.
+ *
+ * commitment = SHA3-256(
+ *   protocolDomain || protocolVersion ||
+ *   canonicalAction(action) || canonicalChallenge(challenge)
+ * )
+ *
+ * @param action    The application action.
+ * @param challenge The challenge the work is bound to.
+ */
+export declare function computeActionCommitment(action: MachineWorkAction, challenge: WorkChallenge): string;

package/dist/cjs/admission/commitment.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * admission/commitment.ts — Canonical domain-separated action commitment.
+ *
+ * The commitment is a deterministic SHA3-256 over a length-prefixed canonical
+ * encoding of every security-relevant field. It changes if any of the
+ * following change:
+ *   - protocol domain / version
+ *   - action domain, sender, recipient, actionId, payloadHash, context
+ *   - challenge challengeId, nonce, target, expiresAt
+ *
+ * The resulting 32-byte commitment is placed in the TxPoW header's customHash
+ * field, so the mined nonce commits the work to sender, recipient, action,
+ * challenge, target, and freshness.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalAction = canonicalAction;
+exports.computeActionCommitment = computeActionCommitment;
+const core_1 = require("@totemsdk/core");
+const types_js_1 = require("./types.js");
+const challenge_js_1 = require("./challenge.js");
+function toHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Canonical serialization of a MachineWorkAction.
+ *
+ * Length-prefixed fields in a fixed order; context keys are sorted so that
+ * equivalent input produces identical output.
+ */
+function canonicalAction(action) {
+    const parts = [];
+    const push = (s) => {
+        parts.push(String(s.length).padStart(8, '0'));
+        parts.push(s);
+    };
+    push('totem.machine-work-action');
+    push(String(action.version));
+    push(action.domain);
+    push(action.sender);
+    push(action.recipient);
+    push(action.actionId);
+    push(action.payloadHash);
+    if (action.context) {
+        const keys = Object.keys(action.context).sort();
+        for (const key of keys) {
+            push(key);
+            push(action.context[key]);
+        }
+    }
+    return parts.join('');
+}
+/**
+ * Compute the canonical action commitment.
+ *
+ * commitment = SHA3-256(
+ *   protocolDomain || protocolVersion ||
+ *   canonicalAction(action) || canonicalChallenge(challenge)
+ * )
+ *
+ * @param action    The application action.
+ * @param challenge The challenge the work is bound to.
+ */
+function computeActionCommitment(action, challenge) {
+    const input = types_js_1.MACHINE_WORK_DOMAIN +
+        '|' +
+        String(types_js_1.MACHINE_WORK_ADMISSION_VERSION) +
+        '|' +
+        canonicalAction(action) +
+        '|' +
+        (0, challenge_js_1.canonicalChallenge)(challenge);
+    return toHex((0, core_1.sha3_256)(new TextEncoder().encode(input)));
+}

package/dist/cjs/admission/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * admission/index.ts — Machine Work Admission public surface.
+ *
+ * Machine Work Admission allows applications to require computational proof
+ * before allocating scarce resources. The work is performed against a Minima
+ * block candidate so that application anti-spam work simultaneously searches
+ * for valid Minima L1 blocks.
+ */
+export { createWorkChallenge, validateWorkChallenge, challengeFingerprint, canonicalChallenge, DEFAULT_CHALLENGE_TTL_MS, MAX_CHALLENGE_TTL_MS, } from './challenge.js';
+export { computeActionCommitment, canonicalAction, } from './commitment.js';
+export { mineWorkAdmission, type MineWorkAdmissionOptions, } from './mine.js';
+export { verifyWorkAdmission, type VerifyWorkAdmissionOptions, } from './verify.js';
+export { buildBlockHeaderTail, serializeSuperParents, isBlockWinner, computeSuperLevel, templateFreshness, computeBlockCandidateId, buildEmptyBlockBody, buildEmptyTransactionBytes, buildEmptyWitnessBytes, buildEmptyBurnTxBytes, buildEmptyBurnWitnessBytes, assembleTxPoWEnvelope, reconstructTxPoWEnvelope, } from './template.js';
+export { MACHINE_WORK_ADMISSION_VERSION, MACHINE_WORK_DOMAIN, type WorkChallenge, type MachineWorkAction, type MinimaWorkTemplate, type MinimaWorkTemplateProvider, type MinimaWorkRelay, type MachineWorkAdmissionProof, type WorkAdmissionVerification, } from './types.js';

package/dist/cjs/admission/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * admission/index.ts — Machine Work Admission public surface.
+ *
+ * Machine Work Admission allows applications to require computational proof
+ * before allocating scarce resources. The work is performed against a Minima
+ * block candidate so that application anti-spam work simultaneously searches
+ * for valid Minima L1 blocks.
+ */
+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.MAX_CHALLENGE_TTL_MS = exports.DEFAULT_CHALLENGE_TTL_MS = exports.canonicalChallenge = exports.challengeFingerprint = exports.validateWorkChallenge = exports.createWorkChallenge = void 0;
+var challenge_js_1 = require("./challenge.js");
+Object.defineProperty(exports, "createWorkChallenge", { enumerable: true, get: function () { return challenge_js_1.createWorkChallenge; } });
+Object.defineProperty(exports, "validateWorkChallenge", { enumerable: true, get: function () { return challenge_js_1.validateWorkChallenge; } });
+Object.defineProperty(exports, "challengeFingerprint", { enumerable: true, get: function () { return challenge_js_1.challengeFingerprint; } });
+Object.defineProperty(exports, "canonicalChallenge", { enumerable: true, get: function () { return challenge_js_1.canonicalChallenge; } });
+Object.defineProperty(exports, "DEFAULT_CHALLENGE_TTL_MS", { enumerable: true, get: function () { return challenge_js_1.DEFAULT_CHALLENGE_TTL_MS; } });
+Object.defineProperty(exports, "MAX_CHALLENGE_TTL_MS", { enumerable: true, get: function () { return challenge_js_1.MAX_CHALLENGE_TTL_MS; } });
+var commitment_js_1 = require("./commitment.js");
+Object.defineProperty(exports, "computeActionCommitment", { enumerable: true, get: function () { return commitment_js_1.computeActionCommitment; } });
+Object.defineProperty(exports, "canonicalAction", { enumerable: true, get: function () { return commitment_js_1.canonicalAction; } });
+var mine_js_1 = require("./mine.js");
+Object.defineProperty(exports, "mineWorkAdmission", { enumerable: true, get: function () { return mine_js_1.mineWorkAdmission; } });
+var verify_js_1 = require("./verify.js");
+Object.defineProperty(exports, "verifyWorkAdmission", { enumerable: true, get: function () { return verify_js_1.verifyWorkAdmission; } });
+var template_js_1 = require("./template.js");
+Object.defineProperty(exports, "buildBlockHeaderTail", { enumerable: true, get: function () { return template_js_1.buildBlockHeaderTail; } });
+Object.defineProperty(exports, "serializeSuperParents", { enumerable: true, get: function () { return template_js_1.serializeSuperParents; } });
+Object.defineProperty(exports, "isBlockWinner", { enumerable: true, get: function () { return template_js_1.isBlockWinner; } });
+Object.defineProperty(exports, "computeSuperLevel", { enumerable: true, get: function () { return template_js_1.computeSuperLevel; } });
+Object.defineProperty(exports, "templateFreshness", { enumerable: true, get: function () { return template_js_1.templateFreshness; } });
+Object.defineProperty(exports, "computeBlockCandidateId", { enumerable: true, get: function () { return template_js_1.computeBlockCandidateId; } });
+Object.defineProperty(exports, "buildEmptyBlockBody", { enumerable: true, get: function () { return template_js_1.buildEmptyBlockBody; } });
+Object.defineProperty(exports, "buildEmptyTransactionBytes", { enumerable: true, get: function () { return template_js_1.buildEmptyTransactionBytes; } });
+Object.defineProperty(exports, "buildEmptyWitnessBytes", { enumerable: true, get: function () { return template_js_1.buildEmptyWitnessBytes; } });
+Object.defineProperty(exports, "buildEmptyBurnTxBytes", { enumerable: true, get: function () { return template_js_1.buildEmptyBurnTxBytes; } });
+Object.defineProperty(exports, "buildEmptyBurnWitnessBytes", { enumerable: true, get: function () { return template_js_1.buildEmptyBurnWitnessBytes; } });
+Object.defineProperty(exports, "assembleTxPoWEnvelope", { enumerable: true, get: function () { return template_js_1.assembleTxPoWEnvelope; } });
+Object.defineProperty(exports, "reconstructTxPoWEnvelope", { enumerable: true, get: function () { return template_js_1.reconstructTxPoWEnvelope; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "MACHINE_WORK_ADMISSION_VERSION", { enumerable: true, get: function () { return types_js_1.MACHINE_WORK_ADMISSION_VERSION; } });
+Object.defineProperty(exports, "MACHINE_WORK_DOMAIN", { enumerable: true, get: function () { return types_js_1.MACHINE_WORK_DOMAIN; } });

package/dist/cjs/admission/mine.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+import { type MachineWorkAction, type MachineWorkAdmissionProof, type MinimaWorkRelay, type MinimaWorkTemplateProvider, type WorkChallenge } from './types.js';
+export interface MineWorkAdmissionOptions {
+    /** AbortSignal — rejects the Promise when aborted. */
+    signal?: AbortSignal;
+    /** Hard cap on total iterations (default: unlimited). */
+    maxIterations?: number;
+    /** Hash iterations per async yield (default: 10_000). */
+    chunkSize?: number;
+    /** Override the template timeMilli for deterministic testing. */
+    timeMilli?: bigint;
+    /** Force the pure-JS mining path (for testing). */
+    forceJs?: boolean;
+    /** Skip the Node.js worker_threads Worker (for testing). */
+    _skipWorker?: boolean;
+    /**
+     * Deterministic 32-byte PRNG for the TxBody (testing only). When omitted a
+     * cryptographically random PRNG is generated.
+     */
+    prng?: Uint8Array;
+    /**
+     * Preferred Minima block relay boundary. When supplied, a genuine current
+     * Minima block is submitted through the relay exactly once. Falls back to
+     * the deprecated provider.broadcastBlockCandidate only when no relay is set.
+     */
+    relay?: MinimaWorkRelay;
+}
+/**
+ * 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.
+ */
+export declare function mineWorkAdmission(action: MachineWorkAction, challenge: WorkChallenge, templateProvider: MinimaWorkTemplateProvider, options?: MineWorkAdmissionOptions): Promise<MachineWorkAdmissionProof>;

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