@totemsdk/txpow 1.0.2 → 1.1.1

package/dist/admission/template.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * admission/template.ts — Minima block-candidate template handling.
  *
@@ -12,23 +11,9 @@
  * template provider. A real Minima node / Axia integration supplies live chain
  * state; tests supply fixtures.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.serializeSuperParents = serializeSuperParents;
-exports.buildEmptyBurnTxBytes = buildEmptyBurnTxBytes;
-exports.buildEmptyBurnWitnessBytes = buildEmptyBurnWitnessBytes;
-exports.buildEmptyTransactionBytes = buildEmptyTransactionBytes;
-exports.buildEmptyWitnessBytes = buildEmptyWitnessBytes;
-exports.buildEmptyBlockBody = buildEmptyBlockBody;
-exports.assembleTxPoWEnvelope = assembleTxPoWEnvelope;
-exports.buildBlockHeaderTail = buildBlockHeaderTail;
-exports.computeBlockCandidateId = computeBlockCandidateId;
-exports.isBlockWinner = isBlockWinner;
-exports.computeSuperLevel = computeSuperLevel;
-exports.templateFreshness = templateFreshness;
-exports.reconstructTxPoWEnvelope = reconstructTxPoWEnvelope;
-const core_1 = require("@totemsdk/core");
-const core_2 = require("@totemsdk/core");
-const constants_js_1 = require("../constants.js");
+import { sha3_256 } from '@totemsdk/core';
+import { writeMiniNumber, writeMiniData, writeHashToStream, concat, } from '@totemsdk/core';
+import { CASCADE_LEVELS } from '../constants.js';
 function hexToBytes(hex) {
     const h = hex.startsWith('0x') ? hex.slice(2) : hex;
     const out = new Uint8Array(h.length / 2);
@@ -46,9 +31,9 @@ function toHex(bytes) {
  * Consecutive equal hashes are coalesced into (count: MiniByte, hash) runs.
  * A fresh candidate with all-distinct parents serializes as 32 runs.
  */
-function serializeSuperParents(superParents) {
-    if (superParents.length !== constants_js_1.CASCADE_LEVELS) {
-        throw new Error(`superParents must have ${constants_js_1.CASCADE_LEVELS} entries, got ${superParents.length}`);
+export function serializeSuperParents(superParents) {
+    if (superParents.length !== CASCADE_LEVELS) {
+        throw new Error(`superParents must have ${CASCADE_LEVELS} entries, got ${superParents.length}`);
     }
     const parts = [];
     let runHash = superParents[0];
@@ -59,14 +44,14 @@ function serializeSuperParents(superParents) {
         }
         else {
             parts.push(new Uint8Array([runCount]));
-            parts.push((0, core_2.writeHashToStream)(hexToBytes(runHash)));
+            parts.push(writeHashToStream(hexToBytes(runHash)));
             runHash = superParents[i];
             runCount = 1;
         }
     }
     parts.push(new Uint8Array([runCount]));
-    parts.push((0, core_2.writeHashToStream)(hexToBytes(runHash)));
-    return (0, core_2.concat)(...parts);
+    parts.push(writeHashToStream(hexToBytes(runHash)));
+    return concat(...parts);
 }
 /**
  * Build the empty burn transaction bytes (TxBody.writeDataStream fields 5-6).
@@ -74,29 +59,29 @@ function serializeSuperParents(superParents) {
  * Equivalent to serializeTransaction({ linkHash: [0x00], inputs: [], outputs: [],
  * state: [] }): 0 inputs, 0 outputs, 0 state, linkHash = ZERO_TXPOWID (1 byte).
  */
-function buildEmptyBurnTxBytes() {
-    return (0, core_2.concat)((0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeHashToStream)(new Uint8Array([0x00])));
+export function buildEmptyBurnTxBytes() {
+    return concat(writeMiniNumber(0n, 0), writeMiniNumber(0n, 0), writeMiniNumber(0n, 0), writeHashToStream(new Uint8Array([0x00])));
 }
 /**
  * Build the empty burn witness bytes (TxBody.writeDataStream field 6).
  * 0 signatures, 0 coinproofs, 0 scriptproofs.
  */
-function buildEmptyBurnWitnessBytes() {
-    return (0, core_2.concat)((0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0));
+export function buildEmptyBurnWitnessBytes() {
+    return concat(writeMiniNumber(0n, 0), writeMiniNumber(0n, 0), writeMiniNumber(0n, 0));
 }
 /**
  * Build the empty transaction bytes (TxBody.writeDataStream field 3).
  * 0 inputs, 0 outputs, 0 state, linkHash = ZERO_TXPOWID (1 byte).
  */
-function buildEmptyTransactionBytes() {
-    return (0, core_2.concat)((0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeHashToStream)(new Uint8Array([0x00])));
+export function buildEmptyTransactionBytes() {
+    return concat(writeMiniNumber(0n, 0), writeMiniNumber(0n, 0), writeMiniNumber(0n, 0), writeHashToStream(new Uint8Array([0x00])));
 }
 /**
  * Build the empty witness bytes (TxBody.writeDataStream field 4).
  * 0 signatures, 0 coinproofs, 0 scriptproofs.
  */
-function buildEmptyWitnessBytes() {
-    return (0, core_2.concat)((0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0), (0, core_2.writeMiniNumber)(0n, 0));
+export function buildEmptyWitnessBytes() {
+    return concat(writeMiniNumber(0n, 0), writeMiniNumber(0n, 0), writeMiniNumber(0n, 0));
 }
 /**
  * Build the serialized TxBody for a fresh block candidate.
@@ -110,8 +95,8 @@ function buildEmptyWitnessBytes() {
  * @param txnDifficulty Transaction difficulty (32-byte hex). For a block
  *                      candidate this is typically the block difficulty.
  */
-function buildEmptyBlockBody(prng, txnDifficulty) {
-    return (0, core_2.concat)((0, core_2.writeHashToStream)(prng), (0, core_2.writeMiniData)(hexToBytes(txnDifficulty)), buildEmptyTransactionBytes(), buildEmptyWitnessBytes(), buildEmptyBurnTxBytes(), buildEmptyBurnWitnessBytes(), (0, core_2.writeMiniNumber)(0n, 0));
+export function buildEmptyBlockBody(prng, txnDifficulty) {
+    return concat(writeHashToStream(prng), writeMiniData(hexToBytes(txnDifficulty)), buildEmptyTransactionBytes(), buildEmptyWitnessBytes(), buildEmptyBurnTxBytes(), buildEmptyBurnWitnessBytes(), writeMiniNumber(0n, 0));
 }
 /**
  * Assemble the complete Minima TxPoW wire format:
@@ -123,8 +108,8 @@ function buildEmptyBlockBody(prng, txnDifficulty) {
  * @param headerBytes  Serialized TxHeader bytes (with the winning nonce).
  * @param bodyBytes    Serialized TxBody bytes.
  */
-function assembleTxPoWEnvelope(headerBytes, bodyBytes) {
-    return (0, core_2.concat)(headerBytes, new Uint8Array([0x01]), bodyBytes);
+export function assembleTxPoWEnvelope(headerBytes, bodyBytes) {
+    return concat(headerBytes, new Uint8Array([0x01]), bodyBytes);
 }
 /**
  * Build the TxHeader tail (everything after the nonce field) for a block
@@ -138,21 +123,21 @@ function assembleTxPoWEnvelope(headerBytes, bodyBytes) {
  * @param customHash   The action commitment (32-byte hex) to place in mCustomHash.
  * @param txBodyHash   SHA3-256 of the serialized TxBody (32-byte hex).
  */
-function buildBlockHeaderTail(template, customHash, txBodyHash) {
-    return (0, core_2.concat)((0, core_2.writeMiniData)(hexToBytes(template.chainId)), (0, core_2.writeMiniNumber)(template.timeMilli, 0), (0, core_2.writeMiniNumber)(template.blockNumber, 0), (0, core_2.writeMiniData)(hexToBytes(template.blockDifficulty)), serializeSuperParents(template.superParents), (0, core_2.writeHashToStream)(hexToBytes(template.mmrRoot)), (0, core_2.writeMiniNumber)(template.mmrTotal, 0), hexToBytes(template.magic), (0, core_2.writeHashToStream)(hexToBytes(customHash)), (0, core_2.writeHashToStream)(hexToBytes(txBodyHash)));
+export function buildBlockHeaderTail(template, customHash, txBodyHash) {
+    return concat(writeMiniData(hexToBytes(template.chainId)), writeMiniNumber(template.timeMilli, 0), writeMiniNumber(template.blockNumber, 0), writeMiniData(hexToBytes(template.blockDifficulty)), serializeSuperParents(template.superParents), writeHashToStream(hexToBytes(template.mmrRoot)), writeMiniNumber(template.mmrTotal, 0), hexToBytes(template.magic), writeHashToStream(hexToBytes(customHash)), writeHashToStream(hexToBytes(txBodyHash)));
 }
 /**
  * Compute the TxPoW ID for a mined block-candidate header.
  * txpowId = SHA3-256(serialized TxHeader).
  */
-function computeBlockCandidateId(headerBytes) {
-    return (0, core_1.sha3_256)(headerBytes);
+export function computeBlockCandidateId(headerBytes) {
+    return sha3_256(headerBytes);
 }
 /**
  * Check whether a txpowId beats the block target (i.e. is a genuine Minima block).
  * valid = txpowId < blockDifficulty (big-endian 256-bit comparison).
  */
-function isBlockWinner(txpowId, blockDifficulty) {
+export function isBlockWinner(txpowId, blockDifficulty) {
     const target = hexToBytes(blockDifficulty);
     for (let i = 0; i < 32; i++) {
         if (txpowId[i] < target[i])
@@ -201,7 +186,7 @@ function bytesToBigInt(bytes) {
  * @param txpowId        SHA3-256(header), 32 bytes.
  * @param blockDifficulty 32-byte hex block difficulty target.
  */
-function computeSuperLevel(txpowId, blockDifficulty) {
+export function computeSuperLevel(txpowId, blockDifficulty) {
     const diffBigInt = bytesToBigInt(hexToBytes(blockDifficulty));
     const idBigInt = bytesToBigInt(txpowId);
     // Not a block: quot = 0 → super = -1
@@ -210,8 +195,8 @@ function computeSuperLevel(txpowId, blockDifficulty) {
     const quot = diffBigInt / idBigInt;
     let superLevel = bigIntBitLength(quot) - 1;
     // Clamp to the maximum represented Super level, exactly as Minima does.
-    if (superLevel >= constants_js_1.CASCADE_LEVELS) {
-        superLevel = constants_js_1.CASCADE_LEVELS - 1;
+    if (superLevel >= CASCADE_LEVELS) {
+        superLevel = CASCADE_LEVELS - 1;
     }
     return superLevel;
 }
@@ -220,7 +205,7 @@ function computeSuperLevel(txpowId, blockDifficulty) {
  * was captured within the window, and "current" for L1 broadcast if it matches
  * the latest template id.
  */
-function templateFreshness(template, latest, options) {
+export function templateFreshness(template, latest, options) {
     const now = options?.now ?? Date.now();
     const windowMs = options?.admissionWindowMs ?? 5 * 60 * 1000;
     const age = now - template.capturedAt;
@@ -239,9 +224,9 @@ function templateFreshness(template, latest, options) {
  * @param headerBytes   The mined TxHeader bytes.
  * @param prng          The PRNG used when the proof was mined (32 bytes).
  */
-function reconstructTxPoWEnvelope(proofTemplate, headerBytes, prng) {
+export function reconstructTxPoWEnvelope(proofTemplate, headerBytes, prng) {
     const body = buildEmptyBlockBody(prng, proofTemplate.blockDifficulty);
-    const bodyHash = toHex((0, core_1.sha3_256)(body));
+    const bodyHash = toHex(sha3_256(body));
     const envelope = assembleTxPoWEnvelope(headerBytes, body);
     return { envelope, bodyHash };
 }

package/dist/admission/types.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * admission/types.ts — Machine Work Admission core types.
  *
@@ -16,9 +15,7 @@
  * 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;
+export const MACHINE_WORK_ADMISSION_VERSION = 1;
 /** Canonical protocol domain prefix for the commitment hash. */
-exports.MACHINE_WORK_DOMAIN = 'totem.machine-work-admission';
+export const MACHINE_WORK_DOMAIN = 'totem.machine-work-admission';

package/dist/admission/verify.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * admission/verify.ts — Machine Work Admission verification.
  *
@@ -20,13 +19,11 @@
  * 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");
+import { sha3_256 } from '@totemsdk/core';
+import { computeActionCommitment } from './commitment.js';
+import { validateWorkChallenge } from './challenge.js';
+import { computeSuperLevel, templateFreshness } from './template.js';
+import { MACHINE_WORK_ADMISSION_VERSION, } from './types.js';
 function hexToBytes(hex) {
     const h = hex.startsWith('0x') ? hex.slice(2) : hex;
     const out = new Uint8Array(h.length / 2);
@@ -64,12 +61,12 @@ function isLessThan(a, b) {
  *                         block contribution (`broadcastable` is undefined).
  * @param options          Verification options.
  */
-async function verifyWorkAdmission(action, challenge, proof, templateProvider, options) {
+export 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) {
+    if (proof.version !== MACHINE_WORK_ADMISSION_VERSION) {
         return { valid: false, reason: `unsupported proof version ${proof.version}` };
     }
     if (proof.challengeId !== challenge.challengeId) {
@@ -85,7 +82,7 @@ async function verifyWorkAdmission(action, challenge, proof, templateProvider, o
         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, {
+    const challengeCheck = validateWorkChallenge(challenge, {
         recipient: action.recipient,
         domain: action.domain,
         now: options?.now,
@@ -94,13 +91,13 @@ async function verifyWorkAdmission(action, challenge, proof, templateProvider, o
         return { valid: false, reason: challengeCheck.reason };
     }
     // 3. Recompute the canonical commitment — must match the proof
-    const expectedCommitment = (0, commitment_js_1.computeActionCommitment)(action, challenge);
+    const expectedCommitment = 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 txpowId = sha3_256(headerBytes);
     const txpowIdHex = toHex(txpowId);
     if (txpowIdHex !== proof.txpowId) {
         return { valid: false, reason: 'txpowId does not match mined header' };
@@ -125,7 +122,7 @@ async function verifyWorkAdmission(action, challenge, proof, templateProvider, o
         }
     }
     // 5a. Template freshness for admission (uses the proof's capture time).
-    const freshness = (0, template_js_1.templateFreshness)(proof.template, trustedTemplate, {
+    const freshness = templateFreshness(proof.template, trustedTemplate, {
         admissionWindowMs: options?.admissionWindowMs,
         now: options?.now,
     });
@@ -141,7 +138,7 @@ async function verifyWorkAdmission(action, challenge, proof, templateProvider, o
     // 6. Level B: recompute the exact Minima Super level from the TRUSTED block
     //    difficulty and the re-derived txpowId. Without a trusted template we
     //    cannot claim Minima block contribution (isBlock = false).
-    const superLevel = trustedTemplate ? (0, template_js_1.computeSuperLevel)(txpowId, trustedTemplate.blockDifficulty) : -1;
+    const superLevel = trustedTemplate ? computeSuperLevel(txpowId, trustedTemplate.blockDifficulty) : -1;
     const isBlock = trustedTemplate ? superLevel >= 0 : false;
     // 7. Level C: broadcastability requires a live template provider, a current
     //    template, and isBlock. Offline mode leaves broadcastable undefined.

package/dist/calibrate.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * calibrate.ts — Hash rate measurement and mining cost estimation.
  *
@@ -9,24 +8,21 @@
  * estimateMiningCost() converts a difficulty target + hash rate into an
  * expected time and confidence label.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.calibrateHashRate = calibrateHashRate;
-exports.estimateMiningCost = estimateMiningCost;
-const core_1 = require("@totemsdk/core");
+import { sha3_256 } from '@totemsdk/core';
 /**
  * Run 100K trial SHA3-256 hashes and return the measured hash rate (hashes/sec).
  *
  * Call once per session and cache the result — the cost is ~50ms on a
  * typical desktop and ~300ms on a mid-range mobile.
  */
-async function calibrateHashRate() {
+export async function calibrateHashRate() {
     const TRIAL_COUNT = 100000;
     const data = new Uint8Array(150).fill(0xab);
     const start = typeof performance !== 'undefined'
         ? performance.now()
         : Date.now();
     for (let i = 0; i < TRIAL_COUNT; i++) {
-        (0, core_1.sha3_256)(data);
+        sha3_256(data);
     }
     const elapsed = (typeof performance !== 'undefined' ? performance.now() : Date.now()) - start;
     return Math.round(TRIAL_COUNT / (elapsed / 1000));
@@ -43,7 +39,7 @@ async function calibrateHashRate() {
  *   normal 2 – 15 s
  *   slow   > 15 s
  */
-function estimateMiningCost(txnDifficulty, hashRatePerSec) {
+export function estimateMiningCost(txnDifficulty, hashRatePerSec) {
     if (hashRatePerSec <= 0) {
         throw new Error('hashRatePerSec must be positive');
     }

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)));
+}