@btx-tools/challenges-sdk 0.0.1 → 0.0.2

package/README.md

@@ -156,17 +156,27 @@ For RPC mode at advertised latency (~1–4 seconds), point it at a **dedicated b
 
 ## Performance
 
-Pure-JS solver bench at production matmul shape (n=512, b=16, r=8) on M-series Mac / Node 22 (2026-05-21):
+Pure-JS solver bench at production matmul shape (n=512, b=16, r=8) on M-series Mac arm64 (2026-05-22, 5-sample mean):
 
-| Statistic | Wall-clock per attempt |
-|---|---|
-| mean | **4.6 s** |
-| median | 4.6 s |
-| min / max | 4.6 / 4.7 s |
+| Engine | Mean / attempt | vs Node 22 |
+|---|---|---|
+| **Node 22.20 / V8** | **4.6 s** | 1.0× (baseline) |
+| Deno 2.7 / V8 | 4.2 s | 0.92× (slightly faster, within noise) |
+| Bun 1.3 / JavaScriptCore | 9.8 s | **2.1× slower** |
+| Firefox SpiderMonkey | untested | — |
+| Safari JavaScriptCore | untested | — |
+
+`mul` and the `dot` accumulator use `bigint` because the worst-case M31 product (`(2^31-1)^2 ≈ 2^62`) exceeds `Number`'s 2^53 precision. The `bigint`-bounded inner loop is the dominant cost. **Bun's JavaScriptCore engine is ~2× slower than V8 for `bigint`-heavy workloads** — if Bun is your runtime, factor that into your `target_solve_time_s` calibration.
+
+Expected end-to-end solve time depends on challenge difficulty. At btxd's lowest service-challenge difficulty (`target_solve_time_s = min_solve_time_s = 0.001`), per-attempt success ≈ 1.3·10⁻³, so expected ≈ 770 attempts:
 
-`mul` and the `dot` accumulator use `bigint` because the worst-case M31 product (`(2^31-1)^2 ≈ 2^62`) exceeds `Number`'s 2^53 precision. The `bigint`-bounded inner loop is the dominant cost.
+| Engine | Expected solve at floor difficulty |
+|---|---|
+| Node 22 / V8 | ~59 min |
+| Deno 2.7 / V8 | ~54 min |
+| Bun 1.3 / JSC | ~2.1 hr |
 
-Expected end-to-end solve time depends on challenge difficulty. At btxd's lowest service-challenge difficulty (`target_solve_time_s = min_solve_time_s = 0.001`), per-attempt success ≈ 1.3·10⁻³, so expected ≈ 770 attempts ≈ **1 hour** wall-clock. **Default difficulty is too slow for online browser use.** Workable today for:
+**Default difficulty is too slow for online browser use.** Workable today for:
 
 - Server-side gating where you control difficulty (calibrate via `target_solve_time_s` for your target user wait)
 - Backend cron / batch jobs
@@ -177,10 +187,42 @@ Day 2.6 will add a WASM port of the matmul kernel + the `field.mul`/`field.dot`
 Reproduce the bench:
 
 ```bash
-npx tsx packages/core/tests/perf/solver-bench.ts 10   # 10 attempts
+npx tsx packages/core/tests/perf/solver-bench.ts 10                              # Node
+deno run --allow-all --unstable-sloppy-imports tests/perf/solver-bench.ts 10     # Deno
+bun tests/perf/solver-bench.ts 10                                                # Bun
+```
+
+## Drop-in middleware
+
+For Express apps, install the companion package:
+
+```bash
+npm install @btx-tools/middleware-express
+```
+
+```typescript
+import express from 'express';
+import { BtxChallengeClient } from '@btx-tools/challenges-sdk';
+import { btxAdmission } from '@btx-tools/middleware-express';
+
+const client = new BtxChallengeClient({ rpcUrl: '...', rpcAuth: { ... } });
+const app = express();
+
+app.post(
+  '/v1/generate',
+  btxAdmission({
+    client,
+    purpose: 'ai_inference_gate',
+    resource: (req) => `model:${req.body.model}|route:${req.path}`,
+    subject: (req) => `tenant:${req.body.tenant_id}`,
+  }),
+  (req, res) => res.json({ ok: true, generated: '...' }),
+);
 ```
 
-> **Cross-engine note**: bench captured on **Node 22 / V8 / M-series Mac arm64** (2026-05-21). `bigint` performance varies significantly by JS engine — Bun, Deno, Firefox SpiderMonkey, Safari JavaScriptCore are untested. If you run the SDK in those environments, please file an issue with your `solver-bench.ts` output so we can track real-world numbers across engines.
+That's it — one line, your route is gated by a BTX service challenge. Full docs at [`@btx-tools/middleware-express`](https://www.npmjs.com/package/@btx-tools/middleware-express) or in the [package README](https://github.com/btx-tools/btx-challenges-sdk/tree/main/packages/middleware-express#readme).
+
+Fastify + Hono adapters queued as `@btx-tools/middleware-fastify` + `@btx-tools/middleware-hono`.
 
 ## Roadmap
 
@@ -189,11 +231,12 @@ npx tsx packages/core/tests/perf/solver-bench.ts 10   # 10 attempts
 | ✅ | Day 1: RPC client + types + audit Wave A/B/C fixes |
 | ✅ | Day 2: Solver class with mode dispatch (RPC mode ships) |
 | ✅ | Day 2.5: Pure-JS MatMul solver port, cross-validated against btxd goldens |
+| ✅ | Day 3 (partial): Express middleware → `@btx-tools/middleware-express@0.1.0` |
 | ⏳ | Day 2.6: WASM port of matmul kernel (perf) |
-| ⏳ | Day 3: Express / Fastify / Hono middleware (separate sub-packages) |
+| ⏳ | Day 3 (rest): Fastify + Hono adapters (separate sub-packages) |
 | ⏳ | Day 4: Browser demo + Node examples |
-| ⏳ | Day 5-6: `@btx/mcp-gateway` companion package |
-| ⏳ | Day 7-8: Docs + npm publish |
+| ⏳ | Day 5-6: `@btx-tools/mcp-gateway` companion package |
+| ⏳ | Day 7-8: Docs + announce |
 | ⏳ | Day 9: Findings + handoff |
 
 ## Testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btx-tools/challenges-sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "TypeScript SDK for BTX service challenges — chain-anchored proof-of-work admission control for APIs, agent gateways, and form submissions",
   "author": "visitor-code <visitor@friction.market>",
   "license": "MIT",