@btx-tools/challenges-sdk 0.0.1

package/dist/index.js

@@ -0,0 +1,702 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+
+// src/types.ts
+var BtxError = class extends Error {
+  constructor(message, method) {
+    super(message);
+    this.method = method;
+    this.name = "BtxError";
+  }
+  method;
+};
+var BtxRpcError = class extends BtxError {
+  constructor(code, message, method) {
+    super(message, method);
+    this.code = code;
+    this.name = "BtxRpcError";
+  }
+  code;
+};
+var BtxHttpError = class extends BtxError {
+  constructor(status, body, method) {
+    super(`HTTP ${status}: ${body.slice(0, 200)}`, method);
+    this.status = status;
+    this.body = body;
+    this.name = "BtxHttpError";
+  }
+  status;
+  body;
+};
+var BtxParseError = class extends BtxError {
+  constructor(cause, body, method) {
+    const causeMsg = cause instanceof Error ? cause.message : String(cause);
+    super(`Failed to parse RPC response: ${causeMsg}`, method);
+    this.cause = cause;
+    this.body = body;
+    this.name = "BtxParseError";
+  }
+  cause;
+  body;
+};
+var BtxTimeoutError = class extends BtxError {
+  constructor(timeoutMs, method) {
+    super(`RPC request timed out after ${timeoutMs}ms`, method);
+    this.timeoutMs = timeoutMs;
+    this.name = "BtxTimeoutError";
+  }
+  timeoutMs;
+};
+var BtxNetworkError = class extends BtxError {
+  constructor(cause, method) {
+    const causeMsg = cause instanceof Error ? cause.message : String(cause);
+    super(`RPC network error: ${causeMsg}`, method);
+    this.cause = cause;
+    this.name = "BtxNetworkError";
+  }
+  cause;
+};
+
+// src/client.ts
+function base64Utf8(input) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "utf8").toString("base64");
+  }
+  const bytes = new TextEncoder().encode(input);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function redactSensitive(body) {
+  return body.replace(/authorization\s*:\s*basic\s+[A-Za-z0-9+/=]+/gi, "authorization: basic [REDACTED]").replace(/"password"\s*:\s*"[^"]*"/gi, '"password":"[REDACTED]"').replace(/"rpcpassword"\s*:\s*"[^"]*"/gi, '"rpcpassword":"[REDACTED]"').replace(/\b(rpc(?:user|password|auth))\s*=\s*\S+/gi, "$1=[REDACTED]");
+}
+function nextRequestId() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+var BtxChallengeClient = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  /** Low-level: raw JSON-RPC call. Exposed for forward compatibility. */
+  async call(method, params = []) {
+    const id = nextRequestId();
+    const auth = "Basic " + base64Utf8(`${this.opts.rpcAuth.user}:${this.opts.rpcAuth.pass}`);
+    const body = JSON.stringify({ jsonrpc: "1.0", id, method, params });
+    const ctrl = new AbortController();
+    const timeoutMs = this.opts.timeoutMs ?? 3e4;
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetch(this.opts.rpcUrl, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: auth
+        },
+        body,
+        signal: ctrl.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new BtxTimeoutError(timeoutMs, method);
+      }
+      throw new BtxNetworkError(err, method);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) {
+      const rawBody2 = await res.text().catch(() => "");
+      throw new BtxHttpError(res.status, redactSensitive(rawBody2), method);
+    }
+    const rawBody = await res.text();
+    let data;
+    try {
+      data = JSON.parse(rawBody);
+    } catch (err) {
+      throw new BtxParseError(err, redactSensitive(rawBody), method);
+    }
+    if (data.error) {
+      throw new BtxRpcError(data.error.code, data.error.message, method);
+    }
+    return data.result;
+  }
+  /** Issue a fresh challenge bound to (purpose, resource, subject). */
+  async issue(params) {
+    const ordered = [
+      ["purpose", params.purpose],
+      ["resource", params.resource],
+      ["subject", params.subject],
+      ["target_solve_time_s", params.target_solve_time_s],
+      ["expires_in_s", params.expires_in_s],
+      ["validation_overhead_s", params.validation_overhead_s],
+      ["propagation_overhead_s", params.propagation_overhead_s],
+      ["difficulty_policy", params.difficulty_policy],
+      ["difficulty_window_blocks", params.difficulty_window_blocks],
+      ["min_solve_time_s", params.min_solve_time_s],
+      ["max_solve_time_s", params.max_solve_time_s],
+      ["solver_parallelism", params.solver_parallelism],
+      ["solver_duty_cycle_pct", params.solver_duty_cycle_pct]
+    ];
+    let lastSet = 2;
+    for (let i = ordered.length - 1; i > 2; i--) {
+      if (ordered[i][1] !== void 0) {
+        lastSet = i;
+        break;
+      }
+    }
+    const args = ordered.slice(0, lastSet + 1).map(([, v]) => v);
+    return this.call("getmatmulservicechallenge", args);
+  }
+  /**
+   * Verify a proof statelessly. Does NOT consume the challenge.
+   * Use this for diagnostic / monitoring paths.
+   * For admission control, use {@link redeem} instead — verification alone
+   * does not prevent replay.
+   */
+  async verify(challenge, nonce64_hex, digest_hex, lookup_local_status = true) {
+    return this.call("verifymatmulserviceproof", [
+      challenge,
+      nonce64_hex,
+      digest_hex,
+      lookup_local_status
+    ]);
+  }
+  /**
+   * Verify-and-consume atomically. THIS is the admission control entry point.
+   * On success, the challenge is marked redeemed and cannot be replayed.
+   */
+  async redeem(challenge, nonce64_hex, digest_hex) {
+    return this.call("redeemmatmulserviceproof", [
+      challenge,
+      nonce64_hex,
+      digest_hex
+    ]);
+  }
+  /** Batch verify. Spec range 1–256 (audit M2). No consumption. */
+  async verifyBatch(entries) {
+    this.assertBatchSize(entries);
+    return this.call("verifymatmulserviceproofs", [entries]);
+  }
+  /** Batch verify + consume. Sequential per-entry. Spec range 1–256 (audit M2). */
+  async redeemBatch(entries) {
+    this.assertBatchSize(entries);
+    return this.call("redeemmatmulserviceproofs", [entries]);
+  }
+  /**
+   * Server-side local solver. Useful when generating fixtures or pre-computing
+   * for tests. For production browser-side solving, ship the WASM solver —
+   * RPC-based solving puts compute load on YOUR node, defeating the point.
+   */
+  async solve(challenge) {
+    return this.call("solvematmulservicechallenge", [challenge]);
+  }
+  assertBatchSize(entries) {
+    if (entries.length < 1 || entries.length > 256) {
+      throw new RangeError(
+        `Batch size must be between 1 and 256 (per BTX RPC spec), got ${entries.length}`
+      );
+    }
+  }
+};
+function headerInputForNonce(ctx, nonce64) {
+  return {
+    version: ctx.version,
+    previousblockhash: ctx.previousblockhash,
+    merkleroot: ctx.merkleroot,
+    time: ctx.time,
+    bits: ctx.bits,
+    nonce64,
+    matmul_dim: ctx.matmul_dim,
+    seed_a: ctx.seed_a,
+    seed_b: ctx.seed_b
+  };
+}
+function serializeMatMulHeader(input) {
+  const buf = new Uint8Array(4 + 32 + 32 + 4 + 4 + 8 + 2 + 32 + 32);
+  let off = 0;
+  writeUint32LE(buf, off, input.version >>> 0);
+  off += 4;
+  buf.set(parseUint256HexToLE(input.previousblockhash, "previousblockhash"), off);
+  off += 32;
+  buf.set(parseUint256HexToLE(input.merkleroot, "merkleroot"), off);
+  off += 32;
+  writeUint32LE(buf, off, input.time >>> 0);
+  off += 4;
+  writeUint32LE(buf, off, parseBitsHex(input.bits));
+  off += 4;
+  writeUint64LE(buf, off, input.nonce64);
+  off += 8;
+  writeUint16LE(buf, off, input.matmul_dim & 65535);
+  off += 2;
+  buf.set(parseUint256HexToLE(input.seed_a, "seed_a"), off);
+  off += 32;
+  buf.set(parseUint256HexToLE(input.seed_b, "seed_b"), off);
+  off += 32;
+  return buf;
+}
+function computeMatMulHeaderHash(input) {
+  return sha256(serializeMatMulHeader(input));
+}
+function deriveSigma(input) {
+  const headerHash = computeMatMulHeaderHash(input);
+  const sigmaRaw = sha256(headerHash);
+  const sigmaBE = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) sigmaBE[i] = sigmaRaw[31 - i];
+  return sigmaBE;
+}
+function parseUint256HexToLE(hex, field) {
+  const beBytes = parseHexFixed(hex, 32, field);
+  const leBytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) leBytes[i] = beBytes[31 - i];
+  return leBytes;
+}
+function parseHexFixed(hex, byteLen, field) {
+  const h = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+  if (h.length !== byteLen * 2) {
+    throw new Error(
+      `header.${field}: expected ${byteLen * 2} hex chars (${byteLen} bytes), got ${h.length}`
+    );
+  }
+  const out = new Uint8Array(byteLen);
+  for (let i = 0; i < byteLen; i++) {
+    const byte = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) {
+      throw new Error(`header.${field}: invalid hex at byte ${i}`);
+    }
+    out[i] = byte;
+  }
+  return out;
+}
+function parseBitsHex(bits) {
+  const h = bits.startsWith("0x") || bits.startsWith("0X") ? bits.slice(2) : bits;
+  if (h.length !== 8) {
+    throw new Error(`header.bits: expected 8 hex chars, got ${h.length}`);
+  }
+  const n = parseInt(h, 16);
+  if (Number.isNaN(n)) {
+    throw new Error(`header.bits: invalid hex`);
+  }
+  return n >>> 0;
+}
+function writeUint16LE(buf, offset, value) {
+  buf[offset] = value & 255;
+  buf[offset + 1] = value >>> 8 & 255;
+}
+function writeUint32LE(buf, offset, value) {
+  buf[offset] = value & 255;
+  buf[offset + 1] = value >>> 8 & 255;
+  buf[offset + 2] = value >>> 16 & 255;
+  buf[offset + 3] = value >>> 24 & 255;
+}
+function writeUint64LE(buf, offset, value) {
+  const lo = Number(value & 0xffffffffn);
+  const hi = Number(value >> 32n & 0xffffffffn);
+  writeUint32LE(buf, offset, lo);
+  writeUint32LE(buf, offset + 4, hi);
+}
+
+// src/matmul/constants.ts
+var M31_MODULUS = 2147483647;
+var NOISE_TAG_EL = "matmul_noise_EL_v1";
+var NOISE_TAG_ER = "matmul_noise_ER_v1";
+var NOISE_TAG_FL = "matmul_noise_FL_v1";
+var NOISE_TAG_FR = "matmul_noise_FR_v1";
+var TRANSCRIPT_COMPRESS_TAG = "matmul-compress-v1";
+
+// src/matmul/field.ts
+var MODULUS_BIG = BigInt(M31_MODULUS);
+function reduce64(x) {
+  let v = (x & MODULUS_BIG) + (x >> 31n);
+  v = (v & MODULUS_BIG) + (v >> 31n);
+  let result = Number(v);
+  if (result >= M31_MODULUS) result -= M31_MODULUS;
+  return result;
+}
+function add(a, b) {
+  const s = a + b;
+  return s >= M31_MODULUS ? s - M31_MODULUS : s;
+}
+function fromOracle(seed, index) {
+  if (seed.length !== 32) {
+    throw new Error(`field.fromOracle: seed must be 32 bytes, got ${seed.length}`);
+  }
+  const indexLe = new Uint8Array(4);
+  writeUint32LE2(indexLe, 0, index >>> 0);
+  for (let retry = 0; retry < 256; retry++) {
+    const hasher = sha256.create();
+    hasher.update(seed);
+    hasher.update(indexLe);
+    if (retry > 0) {
+      const retryLe = new Uint8Array(4);
+      writeUint32LE2(retryLe, 0, retry);
+      hasher.update(retryLe);
+    }
+    const hash2 = hasher.digest();
+    const candidate = readUint32LE(hash2, 0) & M31_MODULUS;
+    if (candidate < M31_MODULUS) return candidate;
+  }
+  const fallback = sha256.create();
+  fallback.update(seed);
+  fallback.update(indexLe);
+  fallback.update(new TextEncoder().encode("oracle-fallback"));
+  const hash = fallback.digest();
+  return readUint32LE(hash, 0) % M31_MODULUS;
+}
+function dot(a, b, len) {
+  let acc = 0n;
+  let pending = 0;
+  for (let i = 0; i < len; i++) {
+    acc += BigInt(a[i]) * BigInt(b[i]);
+    if (++pending === 4) {
+      acc = (acc & MODULUS_BIG) + (acc >> 31n);
+      acc = (acc & MODULUS_BIG) + (acc >> 31n);
+      pending = 0;
+    }
+  }
+  return reduce64(acc);
+}
+function writeUint32LE2(buf, offset, value) {
+  buf[offset] = value & 255;
+  buf[offset + 1] = value >>> 8 & 255;
+  buf[offset + 2] = value >>> 16 & 255;
+  buf[offset + 3] = value >>> 24 & 255;
+}
+function readUint32LE(buf, offset) {
+  return (buf[offset] | buf[offset + 1] << 8 | buf[offset + 2] << 16 | buf[offset + 3] << 24) >>> 0;
+}
+
+// src/matmul/matrix.ts
+function zeros(rows, cols) {
+  return { rows, cols, data: new Uint32Array(rows * cols) };
+}
+function fromSeedRect(seed, rows, cols) {
+  const m = zeros(rows, cols);
+  const total = rows * cols;
+  for (let i = 0; i < total; i++) {
+    m.data[i] = fromOracle(seed, i);
+  }
+  return m;
+}
+function matAdd(a, b) {
+  if (a.rows !== b.rows || a.cols !== b.cols) {
+    throw new Error(
+      `matAdd: dim mismatch a=${a.rows}x${a.cols} b=${b.rows}x${b.cols}`
+    );
+  }
+  const out = zeros(a.rows, a.cols);
+  for (let i = 0; i < a.data.length; i++) {
+    out.data[i] = add(a.data[i], b.data[i]);
+  }
+  return out;
+}
+function matMul(a, b) {
+  if (a.cols !== b.rows) {
+    throw new Error(
+      `matMul: inner-dim mismatch a.cols=${a.cols} b.rows=${b.rows}`
+    );
+  }
+  const out = zeros(a.rows, b.cols);
+  const rowBuf = new Uint32Array(a.cols);
+  const colBuf = new Uint32Array(a.cols);
+  for (let i = 0; i < a.rows; i++) {
+    for (let k = 0; k < a.cols; k++) rowBuf[k] = a.data[i * a.cols + k];
+    for (let j = 0; j < b.cols; j++) {
+      for (let k = 0; k < a.cols; k++) colBuf[k] = b.data[k * b.cols + j];
+      out.data[i * b.cols + j] = dot(rowBuf, colBuf, a.cols);
+    }
+  }
+  return out;
+}
+function deriveNoiseSeed(domainTag, sigmaBE) {
+  if (sigmaBE.length !== 32) {
+    throw new Error(`deriveNoiseSeed: sigma must be 32 bytes, got ${sigmaBE.length}`);
+  }
+  if (domainTag.length !== 18) {
+    throw new Error(`deriveNoiseSeed: domain tag must be 18 chars, got ${domainTag.length}`);
+  }
+  const hasher = sha256.create();
+  hasher.update(new TextEncoder().encode(domainTag));
+  hasher.update(sigmaBE);
+  return hasher.digest();
+}
+function generate(sigmaBE, n, r) {
+  const seedEL = deriveNoiseSeed(NOISE_TAG_EL, sigmaBE);
+  const seedER = deriveNoiseSeed(NOISE_TAG_ER, sigmaBE);
+  const seedFL = deriveNoiseSeed(NOISE_TAG_FL, sigmaBE);
+  const seedFR = deriveNoiseSeed(NOISE_TAG_FR, sigmaBE);
+  return {
+    E_L: fromSeedRect(seedEL, n, r),
+    E_R: fromSeedRect(seedER, r, n),
+    F_L: fromSeedRect(seedFL, n, r),
+    F_R: fromSeedRect(seedFR, r, n)
+  };
+}
+function deriveCompressionSeed(sigmaBE) {
+  const hasher = sha256.create();
+  hasher.update(new TextEncoder().encode(TRANSCRIPT_COMPRESS_TAG));
+  hasher.update(sigmaBE);
+  return hasher.digest();
+}
+function deriveCompressionVector(sigmaBE, b) {
+  if (b <= 0) throw new Error("block size b must be positive");
+  const seed = deriveCompressionSeed(sigmaBE);
+  const len = b * b;
+  const vec = new Uint32Array(len);
+  for (let k = 0; k < len; k++) vec[k] = fromOracle(seed, k);
+  return vec;
+}
+function compressBlock(block, v) {
+  if (block.length !== v.length) {
+    throw new Error(
+      `compressBlock: dim mismatch block.length=${block.length} v.length=${v.length}`
+    );
+  }
+  return dot(block, v, block.length);
+}
+var TranscriptHasher = class {
+  hasher = sha256.create();
+  compressVec;
+  b;
+  le4 = new Uint8Array(4);
+  constructor(sigmaBE, b) {
+    this.b = b;
+    this.compressVec = deriveCompressionVector(sigmaBE, b);
+  }
+  /**
+   * Append the LE32-encoded compressed `c_block` to the transcript.
+   * Ignores `i`/`j`/`ell` for hashing (btxd's `(void)i;(void)j;(void)ell;`
+   * proves they don't participate in the digest), but accepts them so the
+   * call-site reads identically to the C++.
+   */
+  addIntermediate(_i, _j, _ell, cBlock) {
+    if (cBlock.length !== this.b * this.b) {
+      throw new Error(
+        `addIntermediate: c_block must be ${this.b * this.b} elements, got ${cBlock.length}`
+      );
+    }
+    const compressed = compressBlock(cBlock, this.compressVec);
+    this.le4[0] = compressed & 255;
+    this.le4[1] = compressed >>> 8 & 255;
+    this.le4[2] = compressed >>> 16 & 255;
+    this.le4[3] = compressed >>> 24 & 255;
+    this.hasher.update(this.le4);
+  }
+  /** SHA-256d: inner = SHA256(transcript); return SHA256(inner). */
+  finalize() {
+    const inner = this.hasher.digest();
+    return sha256(inner);
+  }
+};
+function canonicalMatMul(aPrime, bPrime, b, sigmaBE) {
+  if (aPrime.rows !== aPrime.cols || bPrime.rows !== bPrime.cols || aPrime.rows !== bPrime.rows) {
+    throw new Error("canonicalMatMul requires square matrices of equal size");
+  }
+  if (b === 0 || aPrime.rows % b !== 0) {
+    throw new Error("canonicalMatMul: invalid transcript block size");
+  }
+  const n = aPrime.rows;
+  const N = n / b;
+  const cPrime = zeros(n, n);
+  const hasher = new TranscriptHasher(sigmaBE, b);
+  const aBlock = new Uint32Array(b * b);
+  const bBlock = new Uint32Array(b * b);
+  const cBlock = new Uint32Array(b * b);
+  for (let i = 0; i < N; i++) {
+    for (let j = 0; j < N; j++) {
+      cBlock.fill(0);
+      for (let ell = 0; ell < N; ell++) {
+        readBlock(aPrime, i, ell, b, aBlock);
+        readBlock(bPrime, ell, j, b, bBlock);
+        multiplyAndAccumulateBlock(aBlock, bBlock, cBlock, b);
+        hasher.addIntermediate(i, j, ell, cBlock);
+      }
+      writeBlock(cPrime, i, j, b, cBlock);
+    }
+  }
+  return { cPrime, transcriptHash: hasher.finalize() };
+}
+function readBlock(m, bi, bj, b, out) {
+  const rowStart = bi * b;
+  const colStart = bj * b;
+  const stride = m.cols;
+  for (let r = 0; r < b; r++) {
+    const src = (rowStart + r) * stride + colStart;
+    const dst = r * b;
+    for (let c = 0; c < b; c++) {
+      out[dst + c] = m.data[src + c];
+    }
+  }
+}
+function writeBlock(m, bi, bj, b, block) {
+  const rowStart = bi * b;
+  const colStart = bj * b;
+  const stride = m.cols;
+  for (let r = 0; r < b; r++) {
+    const dst = (rowStart + r) * stride + colStart;
+    const src = r * b;
+    for (let c = 0; c < b; c++) {
+      m.data[dst + c] = block[src + c];
+    }
+  }
+}
+function multiplyAndAccumulateBlock(a, b_buf, c, b) {
+  const colBuf = new Uint32Array(b);
+  for (let j = 0; j < b; j++) {
+    for (let k = 0; k < b; k++) colBuf[k] = b_buf[k * b + j];
+    for (let i = 0; i < b; i++) {
+      const rowStart = i * b;
+      let acc = 0n;
+      let pending = 0;
+      for (let k = 0; k < b; k++) {
+        acc += BigInt(a[rowStart + k]) * BigInt(colBuf[k]);
+        if (++pending === 4) {
+          acc = (acc & MOD_BIG) + (acc >> 31n);
+          acc = (acc & MOD_BIG) + (acc >> 31n);
+          pending = 0;
+        }
+      }
+      acc = (acc & MOD_BIG) + (acc >> 31n);
+      acc = (acc & MOD_BIG) + (acc >> 31n);
+      let folded = Number(acc);
+      if (folded >= MOD_NUM) folded -= MOD_NUM;
+      c[rowStart + j] = add(c[rowStart + j], folded);
+    }
+  }
+}
+var MOD_NUM = 2147483647;
+var MOD_BIG = 0x7fffffffn;
+
+// src/matmul/pow.ts
+var MAX_U64 = (1n << 64n) - 1n;
+function solveJs(challenge, options = {}) {
+  const payload = challenge.challenge;
+  const ctx = payload.header_context;
+  const { n, b, r } = payload.matmul;
+  const maxTries = options.maxTries ?? 1e6;
+  const nonceStart = options.nonceStart ?? BigInt(ctx.nonce64_start ?? 0);
+  const attemptInterval = options.attemptInterval ?? 1;
+  if (n <= 0 || b <= 0 || r <= 0) {
+    throw new Error(`solveJs: invalid matmul params (n=${n}, b=${b}, r=${r})`);
+  }
+  if (n % b !== 0) {
+    throw new Error(`solveJs: n=${n} not divisible by b=${b}`);
+  }
+  const seedA = parseHex32(payload.matmul.seed_a, "seed_a");
+  const seedB = parseHex32(payload.matmul.seed_b, "seed_b");
+  const targetBE = parseHex32(payload.target, "target");
+  const targetValue = bytesBEToBigInt(targetBE);
+  const A = fromSeedRect(seedA, n, n);
+  const B = fromSeedRect(seedB, n, n);
+  let nonce = nonceStart & MAX_U64;
+  for (let attempt = 0; attempt < maxTries; attempt++) {
+    if (options.onAttempt && attempt % attemptInterval === 0) {
+      options.onAttempt(attempt, nonce);
+    }
+    const headerInput = headerInputForNonce(ctx, nonce);
+    const sigmaBE = deriveSigma(headerInput);
+    const noise = generate(sigmaBE, n, r);
+    const E = matMul(noise.E_L, noise.E_R);
+    const F = matMul(noise.F_L, noise.F_R);
+    const aPrime = matAdd(A, E);
+    const bPrime = matAdd(B, F);
+    const result = canonicalMatMul(aPrime, bPrime, b, sigmaBE);
+    const digestValue = bytesLEToBigInt(result.transcriptHash);
+    if (digestValue <= targetValue) {
+      const nonce64_hex = nonce.toString(16).padStart(16, "0");
+      const digest_hex = bytesLEToHexBE(result.transcriptHash);
+      return {
+        nonce64_hex,
+        digest_hex,
+        // Same shape btxd's solve RPC returns: {challenge, nonce64_hex, digest_hex}.
+        // See `solvematmulservicechallenge` in btxd src/rpc/mining.cpp.
+        proof: { challenge, nonce64_hex, digest_hex }
+      };
+    }
+    if (nonce === MAX_U64) return null;
+    nonce = nonce + 1n & MAX_U64;
+  }
+  return null;
+}
+function parseHex32(hex, field) {
+  const h = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+  if (h.length !== 64) {
+    throw new Error(`solveJs.${field}: expected 64 hex chars, got ${h.length}`);
+  }
+  const out = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    const byte = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) {
+      throw new Error(`solveJs.${field}: invalid hex at byte ${i}`);
+    }
+    out[i] = byte;
+  }
+  return out;
+}
+function bytesBEToBigInt(bytes) {
+  let v = 0n;
+  for (let i = 0; i < bytes.length; i++) {
+    v = v << 8n | BigInt(bytes[i]);
+  }
+  return v;
+}
+function bytesLEToBigInt(bytes) {
+  let v = 0n;
+  for (let i = bytes.length - 1; i >= 0; i--) {
+    v = v << 8n | BigInt(bytes[i]);
+  }
+  return v;
+}
+function bytesLEToHexBE(bytes) {
+  const chars = [];
+  for (let i = bytes.length - 1; i >= 0; i--) {
+    chars.push(bytes[i].toString(16).padStart(2, "0"));
+  }
+  return chars.join("");
+}
+
+// src/solver.ts
+var Solver = class {
+  static async solve(challenge, opts = {}) {
+    const mode = opts.mode ?? (opts.rpcClient ? "rpc" : "pure-js");
+    switch (mode) {
+      case "rpc":
+        return solveViaRpc(challenge, opts);
+      case "pure-js":
+        return solveViaPureJs(challenge, opts);
+      case "auto":
+        if (opts.rpcClient) return solveViaRpc(challenge, opts);
+        return solveViaPureJs(challenge, opts);
+      default: {
+        const _exhaustive = mode;
+        throw new Error(`Solver.solve: unknown mode "${_exhaustive}"`);
+      }
+    }
+  }
+};
+async function solveViaRpc(challenge, opts) {
+  if (!opts.rpcClient) {
+    throw new Error(
+      'Solver.solve: mode="rpc" requires opts.rpcClient. Construct a BtxChallengeClient and pass it via opts.rpcClient.'
+    );
+  }
+  return opts.rpcClient.solve(challenge);
+}
+async function solveViaPureJs(challenge, opts) {
+  const result = solveJs(challenge, opts.pureJs);
+  if (result === null) {
+    const tries = opts.pureJs?.maxTries ?? 1e6;
+    throw new Error(
+      `Solver.solve: pure-JS solver exhausted maxTries=${tries} without finding a proof. Increase maxTries or lower challenge difficulty (target_solve_time_s).`
+    );
+  }
+  return result;
+}
+
+export { BtxChallengeClient, BtxError, BtxHttpError, BtxNetworkError, BtxParseError, BtxRpcError, BtxTimeoutError, Solver };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map