hugin-utils 0.1.3 → 0.2.0

package/README.md

@@ -7,3 +7,129 @@ PoW utils for hugin node messages.
 ```js
 const { insertNonce, meetsTarget, findShare } = require('hugin-utils');
 ```
+
+## Reusable challenge engine (desktop + mobile)
+
+### Engine API
+
+```js
+const {
+  message_challenge,
+  create_pow_scheduler,
+  create_rate_policy
+} = require('hugin-utils/challenge')
+```
+
+`message_challenge({ get_job, backend, message_hash, required_shares, nonce_tag_bits, scheduler, rate_policy, freshness_policy, log })`
+
+- `get_job() -> Promise<job|null>`: provide the latest pool job `{ job_id, blob, target }`
+- `backend.find_share(...) -> Promise<share|null>`: platform-specific PoW backend
+- `scheduler`: shared instance to enforce total H/s budget across concurrent message sends
+- `rate_policy({ active_tasks, elapsed_ms }) -> { hashes_per_second, time_budget_ms, in_phase1 }`
+- `freshness_policy(job) -> boolean`: optional prevId freshness check
+
+### Desktop backend (Node worker)
+
+```js
+const { create_node_worker_backend } = require('hugin-utils/challenge/node_worker')
+const backend = create_node_worker_backend()
+```
+
+Note: the Node-worker backend uses `kryptokrona-utils` for `cn_turtle_lite_slow_hash_v2`. It is declared as an **optional peer dependency** (desktop already provides it).
+
+### Mobile backend (native batch scan)
+
+You selected a native batch-scan interface. Implement a native function with the shape:
+
+- `native_find_share(jobBlobHex, targetHex, startNonce, timeBudgetMs, tagBits, tagValue) -> { nonceHex, resultHex } | null`
+
+Then wrap it:
+
+```js
+const { create_native_batch_backend } = require('hugin-utils/challenge')
+const backend = create_native_batch_backend({ native_find_share })
+```
+
+#### React Native example
+
+Example using `NativeModules` (you can adapt this to TurboModules/JSI).
+
+```js
+import { NativeModules } from 'react-native'
+import {
+  message_challenge,
+  create_pow_scheduler,
+  create_rate_policy,
+  create_native_batch_backend
+} from 'hugin-utils/challenge'
+
+// Your native module must expose:
+// findShare(jobBlobHex, targetHex, startNonce, timeBudgetMs, tagBits, tagValue)
+const { HuginPow } = NativeModules
+
+const backend = create_native_batch_backend({
+  native_find_share: async (jobBlobHex, targetHex, startNonce, timeBudgetMs, tagBits, tagValue) => {
+    const res = await HuginPow.findShare(jobBlobHex, targetHex, startNonce, timeBudgetMs, tagBits, tagValue)
+    // Expect { nonceHex, resultHex } or null
+    return res
+  }
+})
+
+// Share across concurrent sends to enforce total H/s cap.
+const scheduler = create_pow_scheduler()
+const rate_policy = create_rate_policy({
+  total_hashes_per_second_cap: 1500,
+  phase1_hashes_per_second_cap: 950,
+  phase2_hashes_per_second_cap: 250
+})
+
+export async function challenge_message({ get_job, message_hash }) {
+  return await message_challenge({
+    get_job,          // () => Promise<{ job_id, blob, target }|null>
+    backend,
+    message_hash,     // string (the message id/hash you tag the nonce with)
+    required_shares: 1,
+    nonce_tag_bits: 4,
+    scheduler,
+    rate_policy
+  })
+}
+```
+
+#### Mobile (easiest) when you only have `cn_pico` hash()
+
+If your native side only exposes a single function like `cn_pico(blobHex) -> hashHex`, you can keep the nonce search loop in JS and just provide the hash function:
+
+```js
+import { NativeModules } from 'react-native'
+import {
+  message_challenge,
+  create_pow_scheduler,
+  create_rate_policy,
+  create_js_hashfn_backend
+} from 'hugin-utils/challenge'
+
+const { HuginPow } = NativeModules
+
+const backend = create_js_hashfn_backend({
+  // Must return a 64-char hex hash string
+  hash_fn: async (blobHex) => await HuginPow.cn_pico(blobHex)
+})
+
+const scheduler = create_pow_scheduler()
+const rate_policy = create_rate_policy()
+
+export async function challenge_message({ get_job, message_hash }) {
+  return await message_challenge({
+    get_job,
+    backend,
+    message_hash,
+    required_shares: 1,
+    nonce_tag_bits: 4,
+    scheduler,
+    rate_policy
+  })
+}
+```
+
+Performance note: this is simplest to integrate, but can be significantly slower if `cn_pico()` is called over the classic RN bridge. Prefer JSI/TurboModules for high call rates, or implement the native batch-scan `findShare()` API for best performance.

package/challenge/backends/js_hashfn.js

@@ -0,0 +1,22 @@
+const { findShare } = require('../..')
+
+function create_js_hashfn_backend({ hash_fn }) {
+  if (typeof hash_fn !== 'function') throw new Error('hash_fn_missing')
+
+  return {
+    async find_share({ job, hashes_per_second, time_budget_ms, nonce_tag_bits, nonce_tag_value }) {
+      return await findShare({
+        job,
+        startNonce: Math.floor(Math.random() * 0xFFFFFFFF),
+        hashesPerSecond: parseInt(hashes_per_second, 10),
+        timeBudgetMs: parseInt(time_budget_ms, 10),
+        nonceTagBits: nonce_tag_bits,
+        nonceTagValue: nonce_tag_value,
+        hashFn: async (blobHex) => await hash_fn(blobHex)
+      })
+    }
+  }
+}
+
+module.exports = { create_js_hashfn_backend }
+

package/challenge/backends/native_batch.js

@@ -0,0 +1,25 @@
+function create_native_batch_backend({ native_find_share }) {
+  if (typeof native_find_share !== 'function') throw new Error('native_find_share_missing')
+
+  return {
+    async find_share({ job, hashes_per_second, time_budget_ms, nonce_tag_bits, nonce_tag_value }) {
+      const res = await native_find_share(
+        job.blob,
+        job.target,
+        0,
+        time_budget_ms,
+        nonce_tag_bits,
+        nonce_tag_value
+      )
+      if (!res) return null
+      return {
+        job_id: job.job_id,
+        nonce: res.nonceHex || res.nonce || res.nonce_hex,
+        result: res.resultHex || res.result || res.result_hex
+      }
+    }
+  }
+}
+
+module.exports = { create_native_batch_backend }
+

package/challenge/backends/node_worker.js

@@ -0,0 +1,103 @@
+const path = require('path')
+const { fork } = require('child_process')
+
+function create_node_worker_backend({
+  max_job_time_ms = 90000
+} = {}) {
+  let worker = null
+  let worker_ready = false
+  const requests = new Map()
+  let cleanup_set = false
+
+  function ensure_worker() {
+    if (worker && worker_ready) return
+    const worker_path = path.join(__dirname, '..', 'node_worker_process.cjs')
+    worker = fork(worker_path, [], { stdio: ['pipe', 'pipe', 'pipe', 'ipc'] })
+    worker_ready = true
+
+    if (!cleanup_set) {
+      cleanup_set = true
+      const cleanup = () => {
+        if (worker) {
+          try { worker.kill() } catch (e) {}
+          worker = null
+          worker_ready = false
+        }
+      }
+      process.once('exit', cleanup)
+      process.once('SIGINT', cleanup)
+      process.once('SIGTERM', cleanup)
+      process.once('beforeExit', cleanup)
+    }
+
+    worker.on('message', (msg) => {
+      if (!msg || !msg.req_id) return
+      const pending = requests.get(msg.req_id)
+      if (!pending) return
+      requests.delete(msg.req_id)
+      if (msg.type === 'result') {
+        pending.resolve(msg.result)
+        return
+      }
+      const error = msg.error || 'pow_worker_error'
+      pending.reject(new Error(error))
+    })
+
+    worker.on('exit', (code) => {
+      worker_ready = false
+      for (const [, pending] of requests) {
+        pending.reject(new Error(`pow_worker_exit_${code}`))
+      }
+      requests.clear()
+    })
+  }
+
+  function call_worker(type, payload, timeout_ms) {
+    ensure_worker()
+    return new Promise((resolve, reject) => {
+      const req_id = `${Date.now()}-${Math.random()}`
+      let timer = null
+      if (timeout_ms && timeout_ms > 0) {
+        const backlog = requests.size
+        const per_req_slack = Math.min(timeout_ms, 5000)
+        const effective_timeout_ms = timeout_ms + (backlog * per_req_slack) + 500
+        timer = setTimeout(() => {
+          requests.delete(req_id)
+          reject(new Error('pow_worker_timeout'))
+        }, effective_timeout_ms)
+      }
+      requests.set(req_id, {
+        resolve: (result) => {
+          if (timer) clearTimeout(timer)
+          resolve(result)
+        },
+        reject: (error) => {
+          if (timer) clearTimeout(timer)
+          reject(error)
+        }
+      })
+      worker.send({ type, req_id, payload })
+    })
+  }
+
+  return {
+    async find_share({ job, hashes_per_second, time_budget_ms, nonce_tag_bits, nonce_tag_value }) {
+      const tms = parseInt(time_budget_ms, 10)
+      const timeout_ms = tms > 0 ? tms + 1500 : max_job_time_ms + 1500
+      return await call_worker('find_share', {
+        job,
+        start_nonce: Math.floor(Math.random() * 0xFFFFFFFF),
+        options: {
+          hashes_per_second: parseInt(hashes_per_second, 10),
+          time_budget_ms: tms,
+          max_job_time_ms,
+          nonceTagBits: nonce_tag_bits,
+          nonceTagValue: nonce_tag_value
+        }
+      }, timeout_ms)
+    }
+  }
+}
+
+module.exports = { create_node_worker_backend }
+

package/challenge/core.js

@@ -0,0 +1,160 @@
+const { nonceTagFromMessageHash, extractPrevIdFromBlob } = require('..')
+
+class ChallengeScheduler {
+  constructor() {
+    this.active = 0
+  }
+  acquire() {
+    this.active++
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      this.active = Math.max(0, this.active - 1)
+    }
+  }
+  active_count() {
+    return this.active
+  }
+}
+
+function create_pow_scheduler() {
+  return new ChallengeScheduler()
+}
+
+function create_rate_policy({
+  total_hashes_per_second_cap = 1500,
+  phase1_hashes_per_second_cap = 950,
+  phase2_hashes_per_second_cap = 250,
+  phase1_ms = 2 * 60 * 1000,
+  slice_ms_phase1 = 10000,
+  slice_ms_phase2 = 10000
+} = {}) {
+  return ({ active_tasks, elapsed_ms }) => {
+    const in_phase1 = elapsed_ms < phase1_ms
+    const per_task_budget = Math.max(1, Math.floor(total_hashes_per_second_cap / Math.max(1, active_tasks)))
+    const hashes_per_second = Math.min(
+      per_task_budget,
+      in_phase1 ? phase1_hashes_per_second_cap : phase2_hashes_per_second_cap
+    )
+    const time_budget_ms = in_phase1 ? slice_ms_phase1 : slice_ms_phase2
+    return { hashes_per_second, time_budget_ms, in_phase1 }
+  }
+}
+
+function create_freshness_policy({ get_current_prev_ids }) {
+  return (job) => {
+    if (!job || !job.blob) return false
+    const prevId = extractPrevIdFromBlob(job.blob)
+    const { currentPrevId, previousPrevId } = get_current_prev_ids()
+    if (!prevId || !currentPrevId) return false
+    return prevId === currentPrevId || prevId === previousPrevId
+  }
+}
+
+async function message_challenge({
+  get_job,
+  backend,
+  message_hash,
+  required_shares = 1,
+  nonce_tag_bits = 4,
+  scheduler,
+  rate_policy,
+  freshness_policy,
+  log
+}) {
+  if (!backend || typeof backend.find_share !== 'function') throw new Error('pow_backend_missing')
+  if (typeof get_job !== 'function') throw new Error('pow_get_job_missing')
+  if (!scheduler) scheduler = create_pow_scheduler()
+  if (!rate_policy) rate_policy = create_rate_policy()
+
+  const release = scheduler.acquire()
+  try {
+    const start = Date.now()
+    const nonce_tag_value = nonceTagFromMessageHash(message_hash, nonce_tag_bits)
+
+    const shares = []
+    const share_nonces = new Set()
+    const push_share = (share) => {
+      if (!share) return
+      if (typeof share.nonce !== 'string' || typeof share.result !== 'string') return
+      const nonce = share.nonce.toLowerCase()
+      if (share_nonces.has(nonce)) return
+      share_nonces.add(nonce)
+      shares.push({ ...share, job_id: String(share.job_id), nonce, result: share.result.toLowerCase() })
+    }
+
+    let did_boost = false
+    while (shares.length < required_shares) {
+      const job = await get_job()
+      if (!job) {
+        await new Promise(r => setTimeout(r, 250))
+        continue
+      }
+
+      if (freshness_policy && !freshness_policy(job)) {
+        if (log) log('pow_stale_local', { jobId: job.job_id })
+        await new Promise(r => setTimeout(r, 250))
+        continue
+      }
+
+      const elapsed_ms = Date.now() - start
+      const active_tasks = scheduler.active_count()
+      const { hashes_per_second, time_budget_ms, in_phase1 } = rate_policy({ active_tasks, elapsed_ms })
+
+      // Optional early boost pass.
+      if (in_phase1 && !did_boost && backend.boost_find_share) {
+        did_boost = true
+        try {
+          const share = await backend.boost_find_share({
+            job,
+            hashes_per_second,
+            time_budget_ms: Math.min(4000, time_budget_ms),
+            nonce_tag_bits,
+            nonce_tag_value,
+            log
+          })
+          if (share) push_share(share)
+          if (shares.length >= required_shares) return { job, shares }
+        } catch (e) {}
+      }
+
+      let share = null
+      try {
+        share = await backend.find_share({
+          job,
+          hashes_per_second,
+          time_budget_ms,
+          nonce_tag_bits,
+          nonce_tag_value,
+          log
+        })
+      } catch (e) {
+        if (e && e.message === 'pow_worker_timeout') {
+          if (log) log('pow_worker_timeout_retry', { jobId: job.job_id, sliceMs: time_budget_ms, hps: hashes_per_second })
+          await new Promise(r => setTimeout(r, in_phase1 ? 100 : 300))
+          continue
+        }
+        throw e
+      }
+
+      if (share) {
+        push_share(share)
+        if (shares.length >= required_shares) return { job, shares }
+      }
+
+      await new Promise(r => setTimeout(r, in_phase1 ? 50 : 250))
+    }
+    return null
+  } finally {
+    release()
+  }
+}
+
+module.exports = {
+  create_pow_scheduler,
+  create_rate_policy,
+  create_freshness_policy,
+  message_challenge
+}
+

package/challenge/index.js

@@ -0,0 +1,6 @@
+module.exports = {
+  ...require('./core'),
+  ...require('./backends/native_batch'),
+  ...require('./backends/js_hashfn')
+}
+

package/challenge/node_worker.js

@@ -0,0 +1,2 @@
+module.exports = require('./backends/node_worker')
+

package/challenge/node_worker_process.cjs

@@ -0,0 +1,92 @@
+const { Crypto } = require('kryptokrona-utils')
+const { findShare, nonceMatchesTag } = require('..')
+
+const crypto = new Crypto()
+
+function logPow(event, data) {
+  process.send && process.send({ type: 'log', event, data })
+}
+
+async function pow_find_share(job, start_nonce, options = {}) {
+  const hashes_per_second = parseInt(options.hashes_per_second, 10)
+  const time_budget_ms = parseInt(options.time_budget_ms, 10)
+  const max_job_time_ms = parseInt(options.max_job_time_ms, 10)
+  const nonceTagBits = parseInt(options.nonceTagBits || '0', 10)
+  const nonceTagValue = parseInt(options.nonceTagValue || '0', 10)
+  const tag_enabled = Number.isFinite(nonceTagBits) && nonceTagBits > 0
+
+  let nonce = start_nonce >>> 0
+  const start = Date.now()
+  while (true) {
+    const elapsed = Date.now() - start
+    const remaining_ms = time_budget_ms - elapsed
+    if (remaining_ms <= 0) return null
+    if (max_job_time_ms > 0 && elapsed >= max_job_time_ms) return null
+
+    const slice_ms = Math.min(1000, remaining_ms)
+    const share = await findShare({
+      job,
+      startNonce: nonce,
+      hashesPerSecond: hashes_per_second,
+      timeBudgetMs: slice_ms,
+      nonceTagBits,
+      nonceTagValue,
+      hashFn: (blobHex) => crypto.cn_turtle_lite_slow_hash_v2(blobHex),
+      log: (event, data) => logPow(event, data)
+    })
+
+    if (share) {
+      const nextNonce = (parseInt(share.nonce, 16) + 1) >>> 0
+      if (!tag_enabled || nonceMatchesTag(share.nonce, nonceTagValue, nonceTagBits)) {
+        return share
+      }
+      nonce = nextNonce
+      continue
+    }
+
+    const slice_attempts = Math.max(1, Math.floor(hashes_per_second * (slice_ms / 1000)))
+    nonce = (nonce + slice_attempts) >>> 0
+  }
+}
+
+async function pow_calculate_shares(job, required_shares = 1, options = {}) {
+  if (!job || !job.blob || !job.target) {
+    throw new Error('Invalid job data')
+  }
+  const shares = []
+  let nonce = Math.floor(Math.random() * 0xFFFFFFFF)
+  const start = Date.now()
+  const max_job_time_ms = parseInt(options.max_job_time_ms, 10)
+  for (let i = 0; i < required_shares; i++) {
+    if (max_job_time_ms > 0 && (Date.now() - start) >= max_job_time_ms) break
+    const share = await pow_find_share(job, nonce, options)
+    if (share) {
+      shares.push(share)
+      nonce = parseInt(share.nonce, 16) + 1
+    }
+  }
+  return { job, shares }
+}
+
+process.on('message', async (msg) => {
+  if (!msg || !msg.type || !msg.req_id) return
+  const { type, req_id, payload } = msg
+  try {
+    if (type === 'find_share') {
+      const { job, start_nonce, options } = payload || {}
+      const result = await pow_find_share(job, start_nonce, options || {})
+      process.send && process.send({ type: 'result', req_id, result })
+      return
+    }
+    if (type === 'calculate_shares') {
+      const { job, required_shares, options } = payload || {}
+      const result = await pow_calculate_shares(job, required_shares, options || {})
+      process.send && process.send({ type: 'result', req_id, result })
+      return
+    }
+    process.send && process.send({ type: 'error', req_id, error: 'unknown_request' })
+  } catch (e) {
+    process.send && process.send({ type: 'error', req_id, error: e && e.message })
+  }
+})
+

package/index.js

@@ -1,132 +1,239 @@
-const DEFAULT_NONCE_OFFSET = 39;
-
-function readVarint(buffer, offset) {
-  let value = 0;
-  let shift = 0;
-  let bytes = 0;
-  while (offset + bytes < buffer.length) {
-    const byte = buffer[offset + bytes];
-    value |= (byte & 0x7f) << shift;
-    bytes += 1;
-    if ((byte & 0x80) === 0) {
-      return { value, bytes };
-    }
-    shift += 7;
-    if (shift > 63) return null;
-  }
-  return null;
-}
-
-function getNonceOffsetFromBuffer(blobBuffer) {
-  try {
-    let offset = 0;
-    const major = readVarint(blobBuffer, offset);
-    if (!major) return DEFAULT_NONCE_OFFSET;
-    offset += major.bytes;
-    const minor = readVarint(blobBuffer, offset);
-    if (!minor) return DEFAULT_NONCE_OFFSET;
-    offset += minor.bytes;
-    const timestamp = readVarint(blobBuffer, offset);
-    if (!timestamp) return DEFAULT_NONCE_OFFSET;
-    offset += timestamp.bytes;
-    offset += 32;
-    return offset;
-  } catch (e) {
-    return DEFAULT_NONCE_OFFSET;
-  }
-}
-
-function getNonceOffset(blobHex) {
-  const blobBuffer = Buffer.from(blobHex, 'hex');
-  return getNonceOffsetFromBuffer(blobBuffer);
-}
-
-function insertNonce(blobHex, nonceHex) {
-  const blobBuffer = Buffer.from(blobHex, 'hex');
-  const nonceBuffer = Buffer.from(nonceHex, 'hex');
-  const offset = getNonceOffsetFromBuffer(blobBuffer);
-  nonceBuffer.copy(blobBuffer, offset);
-  return { blobHex: blobBuffer.toString('hex'), offset };
-}
-
-function nonceToHexLE(nonce) {
-  const buf = Buffer.alloc(4);
-  buf.writeUInt32LE(nonce >>> 0, 0);
-  return buf.toString('hex');
-}
-
-function parseTarget(targetHex) {
-  if (!targetHex) return null;
-  const targetBuffer = Buffer.from(targetHex, 'hex');
-  if (targetBuffer.length === 4) {
-    const raw = targetBuffer.readUInt32LE(0);
-    if (raw === 0) return null;
-    const numerator = 0xFFFFFFFFFFFFFFFFn;
-    const denom = 0xFFFFFFFFn / BigInt(raw);
-    if (denom === 0n) return null;
-    return numerator / denom;
-  }
-  if (targetBuffer.length === 8) {
-    return targetBuffer.readBigUInt64LE(0);
-  }
-  return null;
-}
-
-function meetsTarget(hashHex, targetHex) {
-  const target = parseTarget(targetHex);
-  if (target === null) return true;
-  const hash = Buffer.from(hashHex, 'hex');
-  if (hash.length < 32) return false;
-  const hashTail = hash.readBigUInt64LE(24);
-  return hashTail <= target;
-}
-
-async function findShare({
-  job,
-  startNonce,
-  hashFn,
-  log,
-  hashesPerSecond = 500,
-  timeBudgetMs = 1000,
-  yieldEvery = 200,
-  logEvery = 100
-}) {
-  const maxAttempts = Math.max(1, Math.floor((hashesPerSecond * timeBudgetMs) / 1000));
-  let nonce = startNonce;
-  const start = Date.now();
-
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    const nonceHex = nonceToHexLE(nonce);
-    const { blobHex, offset } = insertNonce(job.blob, nonceHex);
-    if (log) log('nonce_offset', { jobId: job.job_id, offset });
-    const result = await hashFn(blobHex);
-
-    if (meetsTarget(result, job.target)) {
-      if (log) log('pow_share_found', { jobId: job.job_id, nonce: nonceHex, attempt });
-      return { job_id: job.job_id, nonce: nonceHex, result };
-    }
-
-    nonce++;
-    if (attempt > 0 && attempt % logEvery === 0) {
-      if (log) log('pow_progress', { jobId: job.job_id, attempt, nonce: nonceHex });
-    }
-    if (attempt > 0 && attempt % yieldEvery === 0) {
-      await new Promise(resolve => setTimeout(resolve, 0));
-    }
-    if (Date.now() - start >= timeBudgetMs) {
-      if (log) log('pow_time_budget', { jobId: job.job_id, attempt, elapsedMs: Date.now() - start });
-      break;
-    }
-  }
-
-  if (log) log('pow_share_exhausted', { jobId: job.job_id, attempts: maxAttempts });
-  return null;
-}
-
-module.exports = {
-  readVarint,
-  getNonceOffset,
-  insertNonce,
-  meetsTarget,
-  findShare
-};
+const DEFAULT_NONCE_OFFSET = 39;
+
+function hexToBytes(hex) {
+  if (typeof hex !== 'string') throw new Error('hex_to_bytes_invalid')
+  if (hex.length % 2 !== 0) throw new Error('hex_to_bytes_len')
+  const out = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < out.length; i++) {
+    const byte = parseInt(hex.slice(i * 2, (i * 2) + 2), 16)
+    if (!Number.isFinite(byte)) throw new Error('hex_to_bytes_parse')
+    out[i] = byte
+  }
+  return out
+}
+
+function bytesToHex(bytes) {
+  let hex = ''
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, '0')
+  }
+  return hex
+}
+
+function readUInt32LE(bytes, offset) {
+  return (
+    (bytes[offset] |
+      (bytes[offset + 1] << 8) |
+      (bytes[offset + 2] << 16) |
+      (bytes[offset + 3] << 24)) >>> 0
+  )
+}
+
+function readBigUInt64LE(bytes, offset) {
+  const lo = BigInt(readUInt32LE(bytes, offset))
+  const hi = BigInt(readUInt32LE(bytes, offset + 4))
+  return (hi << 32n) | lo
+}
+
+function readVarint(buffer, offset) {
+  let value = 0;
+  let shift = 0;
+  let bytes = 0;
+  while (offset + bytes < buffer.length) {
+    const byte = buffer[offset + bytes];
+    value |= (byte & 0x7f) << shift;
+    bytes += 1;
+    if ((byte & 0x80) === 0) {
+      return { value, bytes };
+    }
+    shift += 7;
+    if (shift > 63) return null;
+  }
+  return null;
+}
+
+function getNonceOffsetFromBuffer(blobBuffer) {
+  try {
+    let offset = 0;
+    const major = readVarint(blobBuffer, offset);
+    if (!major) return DEFAULT_NONCE_OFFSET;
+    offset += major.bytes;
+    const minor = readVarint(blobBuffer, offset);
+    if (!minor) return DEFAULT_NONCE_OFFSET;
+    offset += minor.bytes;
+    const timestamp = readVarint(blobBuffer, offset);
+    if (!timestamp) return DEFAULT_NONCE_OFFSET;
+    offset += timestamp.bytes;
+    offset += 32;
+    return offset;
+  } catch (e) {
+    return DEFAULT_NONCE_OFFSET;
+  }
+}
+
+function getNonceOffset(blobHex) {
+  const blobBuffer = hexToBytes(blobHex);
+  return getNonceOffsetFromBuffer(blobBuffer);
+}
+
+function insertNonce(blobHex, nonceHex) {
+  const blobBuffer = hexToBytes(blobHex);
+  const nonceBuffer = hexToBytes(nonceHex);
+  const offset = getNonceOffsetFromBuffer(blobBuffer);
+  blobBuffer.set(nonceBuffer, offset);
+  return { blobHex: bytesToHex(blobBuffer), offset };
+}
+
+function extractPrevIdFromBlob(blobHex) {
+  try {
+    const blobBuffer = hexToBytes(blobHex);
+    let offset = 0;
+    const major = readVarint(blobBuffer, offset);
+    if (!major) return null;
+    offset += major.bytes;
+    const minor = readVarint(blobBuffer, offset);
+    if (!minor) return null;
+    offset += minor.bytes;
+    const timestamp = readVarint(blobBuffer, offset);
+    if (!timestamp) return null;
+    offset += timestamp.bytes;
+    if (offset + 32 > blobBuffer.length) return null;
+    return bytesToHex(blobBuffer.subarray(offset, offset + 32));
+  } catch (e) {
+    return null;
+  }
+}
+
+function nonceToHexLE(nonce) {
+  const n = nonce >>> 0
+  const out = new Uint8Array(4)
+  out[0] = n & 0xff
+  out[1] = (n >>> 8) & 0xff
+  out[2] = (n >>> 16) & 0xff
+  out[3] = (n >>> 24) & 0xff
+  return bytesToHex(out)
+}
+
+function parseTarget(targetHex) {
+  if (!targetHex) return null;
+  const targetBytes = hexToBytes(targetHex)
+  if (targetBytes.length === 4) {
+    const raw = readUInt32LE(targetBytes, 0);
+    if (raw === 0) return null;
+    const numerator = 0xFFFFFFFFFFFFFFFFn;
+    const denom = 0xFFFFFFFFn / BigInt(raw);
+    if (denom === 0n) return null;
+    return numerator / denom;
+  }
+  if (targetBytes.length === 8) {
+    return readBigUInt64LE(targetBytes, 0);
+  }
+  return null;
+}
+
+function meetsTarget(hashHex, targetHex) {
+  const target = parseTarget(targetHex);
+  if (target === null) return true;
+  const hashBytes = hexToBytes(hashHex);
+  if (hashBytes.length < 32) return false;
+  const hashTail = readBigUInt64LE(hashBytes, 24);
+  return hashTail <= target;
+}
+
+function minTargetHex(a, b) {
+  const aa = parseTarget(a);
+  const bb = parseTarget(b);
+  if (aa === null) return b;
+  if (bb === null) return a;
+  return aa <= bb ? a : b;
+}
+
+function nonceTagFromMessageHash(messageHash, bits) {
+  try {
+    const b = typeof bits === 'number' ? bits : 0;
+    if (b <= 0 || b > 16) return 0;
+    const mask = (1 << b) - 1;
+    // Isomorphic sha256 (works in Node + React Native).
+    const { sha256 } = require('js-sha256')
+    const digest0 = sha256.array(String(messageHash))[0]
+    return digest0 & mask;
+  } catch (e) {
+    return 0;
+  }
+}
+
+function nonceMatchesTag(nonceHex, tagValue, bits) {
+  if (typeof nonceHex !== 'string' || nonceHex.length !== 8) return false;
+  const b = typeof bits === 'number' ? bits : 0;
+  if (b <= 0) return true;
+  const mask = (1 << b) - 1;
+  // Tag is computed over the actual 32-bit nonce value inserted into the blob (little-endian).
+  const nonceBytes = hexToBytes(nonceHex)
+  const nonce = readUInt32LE(nonceBytes, 0)
+  return (nonce & mask) === (tagValue & mask);
+}
+
+async function findShare({
+  job,
+  startNonce,
+  hashFn,
+  log,
+  hashesPerSecond = 500,
+  timeBudgetMs = 1000,
+  yieldEvery = 200,
+  logEvery = 100,
+  nonceTagBits = 0,
+  nonceTagValue = 0
+}) {
+  const maxAttempts = Math.max(1, Math.floor((hashesPerSecond * timeBudgetMs) / 1000));
+  let nonce = startNonce;
+  const start = Date.now();
+  const b = typeof nonceTagBits === 'number' ? nonceTagBits : 0;
+  const mask = b > 0 ? ((1 << b) - 1) : 0;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (b > 0 && ((nonce >>> 0) & mask) !== (nonceTagValue & mask)) {
+      nonce++;
+      continue;
+    }
+    const nonceHex = nonceToHexLE(nonce);
+    const { blobHex, offset } = insertNonce(job.blob, nonceHex);
+    if (log) log('nonce_offset', { jobId: job.job_id, offset });
+    const result = await hashFn(blobHex);
+
+    if (meetsTarget(result, job.target)) {
+      if (log) log('pow_share_found', { jobId: job.job_id, nonce: nonceHex, attempt });
+      return { job_id: job.job_id, nonce: nonceHex, result };
+    }
+
+    nonce++;
+    if (attempt > 0 && attempt % logEvery === 0) {
+      if (log) log('pow_progress', { jobId: job.job_id, attempt, nonce: nonceHex });
+    }
+    if (attempt > 0 && attempt % yieldEvery === 0) {
+      await new Promise(resolve => setTimeout(resolve, 0));
+    }
+    if (Date.now() - start >= timeBudgetMs) {
+      if (log) log('pow_time_budget', { jobId: job.job_id, attempt, elapsedMs: Date.now() - start });
+      break;
+    }
+  }
+
+  if (log) log('pow_share_exhausted', { jobId: job.job_id, attempts: maxAttempts });
+  return null;
+}
+
+module.exports = {
+  readVarint,
+  getNonceOffset,
+  insertNonce,
+  meetsTarget,
+  minTargetHex,
+  extractPrevIdFromBlob,
+  nonceTagFromMessageHash,
+  nonceMatchesTag,
+  findShare,
+  // helpers for embedders/backends
+  hexToBytes,
+  bytesToHex
+};

package/package.json

@@ -1,8 +1,22 @@
 {
   "name": "hugin-utils",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "PoW utils for hugin node messages",
   "main": "index.js",
+  "scripts": {
+    "test": "node test/challenge.test.cjs"
+  },
+  "dependencies": {
+    "js-sha256": "^0.11.0"
+  },
+  "peerDependencies": {
+    "kryptokrona-utils": "^1.3.7"
+  },
+  "peerDependenciesMeta": {
+    "kryptokrona-utils": {
+      "optional": true
+    }
+  },
   "license": "MIT",
   "author": "n9lsjr"
 }

package/test/challenge.test.cjs

@@ -0,0 +1,67 @@
+const assert = require('assert')
+
+const {
+  getNonceOffset,
+  insertNonce,
+  meetsTarget,
+  nonceTagFromMessageHash,
+  nonceMatchesTag,
+  findShare
+} = require('..')
+
+async function test_insert_nonce_defaults() {
+  const blobHex = '00'.repeat(100)
+  const nonceHex = '01020304'
+  const { blobHex: outHex, offset } = insertNonce(blobHex, nonceHex)
+  assert.strictEqual(offset, getNonceOffset(blobHex))
+  assert.strictEqual(offset, 39)
+  const inserted = outHex.slice(offset * 2, (offset * 2) + 8)
+  assert.strictEqual(inserted, nonceHex)
+}
+
+function test_meets_target_64bit() {
+  const targetHex = '0000000000000000' // 0
+  const okHash = '00'.repeat(32)
+  const badHash = '00'.repeat(24) + '0100000000000000' // tail=1 (LE)
+  assert.strictEqual(meetsTarget(okHash, targetHex), true)
+  assert.strictEqual(meetsTarget(badHash, targetHex), false)
+}
+
+async function test_nonce_tag_roundtrip() {
+  const bits = 4
+  const messageHash = 'test-message-hash'
+  const tagValue = nonceTagFromMessageHash(messageHash, bits)
+
+  const job = {
+    job_id: '1',
+    blob: '00'.repeat(100),
+    target: 'ffffffff'
+  }
+
+  const share = await findShare({
+    job,
+    startNonce: 0,
+    nonceTagBits: bits,
+    nonceTagValue: tagValue,
+    hashesPerSecond: 10_000,
+    timeBudgetMs: 50,
+    hashFn: async () => '00'.repeat(32)
+  })
+
+  assert.ok(share, 'expected share')
+  assert.strictEqual(share.job_id, job.job_id)
+  assert.ok(nonceMatchesTag(share.nonce, tagValue, bits), 'share nonce must match nonce-tag')
+}
+
+async function run() {
+  await test_insert_nonce_defaults()
+  test_meets_target_64bit()
+  await test_nonce_tag_roundtrip()
+  console.log('ok')
+}
+
+run().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})
+