@totemsdk/txpow 1.0.0 → 1.0.1

package/README.md

@@ -69,6 +69,94 @@ const estimatedMs     = estimateMiningCost(targetDifficulty, hashesPerSecond);
 console.log(`Expected mining time: ${estimatedMs}ms`);
 ```
 
+## Machine Work Admission
+
+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 blocks.
+
+A receiver issues a `WorkChallenge` (unique, expiring, bound to the receiver and an application domain). A sender commits its application action into the TxPoW header's `customHash` field and mines the nonce space of a real current Minima block candidate. If the hash beats the receiver's admission target, the machine action is admissible. If the same hash also beats the current Minima block target, the candidate is a genuine Minima block (Super-0 … Super-31) and is relayable.
+
+Ordinary admission proofs stay off-chain. Only actual Minima blocks are eligible for relay.
+
+```typescript
+import {
+  createWorkChallenge,
+  mineWorkAdmission,
+  verifyWorkAdmission,
+  type MinimaWorkTemplateProvider,
+  type MinimaWorkRelay,
+} from '@totemsdk/txpow';
+
+// Receiver: issue a challenge (target chosen by receiver policy)
+const challenge = createWorkChallenge(
+  'receiver-address',
+  'totem.compute.reserve',
+  admissionTargetHex,
+);
+
+// Sender: mine the admission proof against a real Minima block candidate
+// The relay boundary keeps Minima networking out of the core primitive.
+const relay: MinimaWorkRelay = {
+  submitBlock: async (envelope) => node.submitBlock(envelope),
+};
+const provider: MinimaWorkTemplateProvider = {
+  getCurrentTemplate: async () => node.fetchCurrentTemplate(),
+  getLatestTemplate: async () => node.fetchCurrentTemplate(),
+};
+
+// The challenge target is the single authoritative admission target.
+const proof = await mineWorkAdmission(action, challenge, provider, { relay });
+
+// Receiver: verify (never trusts sender-reported hardware speed)
+const result = await verifyWorkAdmission(action, challenge, proof, provider);
+if (result.valid) {
+  // allocate the scarce resource
+}
+```
+
+### Minima Super level
+
+A TxPoW is a Minima block when `txpowId < blockDifficulty`. Its strength is the exact Minima Super level:
+
+```text
+superLevel = floor(log2(blockDifficulty / txpowId))
+```
+
+with `MINIMA_CASCADE_LEVELS = 32`, clamped so the maximum represented value is 31.
+
+| `superLevel` | Meaning |
+|--------------|---------|
+| `-1` | not a Minima block |
+| `0` | ordinary/base Minima block (Super-0) |
+| `1` | stronger block (Super-1) |
+| … | |
+| `31` | maximum represented Super level |
+
+**Super-0 is an ordinary valid Minima block. Non-block TxPoWs have computed Super level -1.** Super level describes block strength — it is not a relay policy. Every valid current block (Super-0 … Super-31) is eligible for relay.
+
+### Three distinct claims
+
+Verification distinguishes three claims that must never be confused:
+
+| Claim | Meaning | Field |
+|-------|---------|-------|
+| **A. admission-valid** | the hash satisfies `challenge.target` | `valid` |
+| **B. Minima block** | the hash beats the block difficulty encoded by the candidate template | `superLevel` / `isBlock` |
+| **C. broadcastable** | a Minima block AND the template is still current AND a live template provider was supplied | `broadcastable` |
+
+A stale candidate may remain `valid = true` (and `superLevel >= 0`) while `broadcastable = false`. Offline verification (no `MinimaWorkTemplateProvider`) leaves `broadcastable` undefined — it does **not** claim Minima block contribution.
+
+`proof.superLevel`, `proof.isBlock`, and `proof.qualifiesAsMinimaBlock` are derived metadata recorded at mining time. Verification never trusts them — they are recomputed from the re-derived TxPoW ID and the template's block difficulty.
+
+### Distributed mining boundary
+
+Machine Work Admission is primarily local/off-chain: the requesting machine performs the work, which keeps it attributable to the machine requesting admission. Native Minima distributed mining (`MSG_TXBLOCKMINE`, where receiving peers reset the body PRNG to create independent search spaces) is a separate, optional, rate-limited, integration-controlled mechanism. It is NOT used per machine action — broadcasting every machine action through `MSG_TXBLOCKMINE` would turn machine anti-spam into Minima network spam. The body PRNG is independent candidate entropy; it never changes the `customHash` application commitment.
+
+### 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.
+
+The primitive is generic — it knows only "there is an application action represented by canonical bytes". Domain-specific packages supply the action commitment for negotiation, compute, storage, mailbox, sensor, or rendezvous domains. It does NOT prove identity, authority, payment, or resource availability; higher-level layers must still perform those checks.
+
 ## Upstream Java source
 
 This package is a TypeScript port of Minima's TxPoW envelope structures. Canonical upstream references:

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