{"_id":"@btx-tools/browser-miner","name":"@btx-tools/browser-miner","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@btx-tools/browser-miner","version":"0.1.0","description":"Pool-agnostic browser mining client for BTX matmul service-challenge shares (WebGPU → WASM → pure-JS)","author":{"name":"visitor-code","email":"visitor@friction.market"},"license":"MIT","type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"peerDependencies":{"@btx-tools/challenges-sdk":"^1.4.0"},"optionalDependencies":{"@btx-tools/matmul-wasm":"^0.1.0","@btx-tools/matmul-webgpu":"^0.1.0"},"devDependencies":{"@types/node":"^22.0.0","@webgpu/types":"^0.1.40","prettier":"^3.3.0","tsup":"^8.3.0","typescript":"^5.6.0","vitest":"^2.1.0","@btx-tools/challenges-sdk":"1.4.0"},"keywords":["btx","mining","webgpu","browser","service-challenge","proof-of-work"],"repository":{"type":"git","url":"git+https://github.com/btx-tools/btx-challenges-sdk.git","directory":"packages/browser-miner"},"homepage":"https://github.com/btx-tools/btx-challenges-sdk/tree/main/packages/browser-miner#readme","bugs":{"url":"https://github.com/btx-tools/btx-challenges-sdk/issues"},"publishConfig":{"access":"public"},"engines":{"node":">=20.19.0"},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","test:unit":"vitest run tests/unit","type-check":"tsc --noEmit","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\""},"_id":"@btx-tools/browser-miner@0.1.0","_integrity":"sha512-e217ESUIZw1a4569ysbIMFMfWPnZmgzLD+jlExXbGBUWCvGy3mKFLqMIZ5+KV3jieg9pW4cE3wePtuuzRawBug==","_resolved":"/private/var/folders/56/l_0r7hgn6nb30xq5clyrvh_m0000gn/T/55f204f8430904e286ca61741d74d90c/btx-tools-browser-miner-0.1.0.tgz","_from":"file:btx-tools-browser-miner-0.1.0.tgz","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-e217ESUIZw1a4569ysbIMFMfWPnZmgzLD+jlExXbGBUWCvGy3mKFLqMIZ5+KV3jieg9pW4cE3wePtuuzRawBug==","shasum":"c7ae93eba8c30478f27cbc5187ba95070c795d0b","tarball":"https://registry.npmjs.org/@btx-tools/browser-miner/-/browser-miner-0.1.0.tgz","fileCount":9,"unpackedSize":98544,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD6R+sWiYSWGesm0DgCoFsBt+ap9n1Fuk+3TiOSa2zQLQIhAMT/p32W7tEYjWXvzVGSnSkeukqSwlsZ5nhh5RfV4/G5"}]},"_npmUser":{"name":"visitor-code","email":"visitor@friction.market"},"directories":{},"maintainers":[{"name":"visitor-code","email":"visitor@friction.market"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/browser-miner_0.1.0_1779653809154_0.6890137989728795"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-24T20:16:49.001Z","0.1.0":"2026-05-24T20:16:49.306Z","modified":"2026-05-24T20:16:49.497Z"},"maintainers":[{"name":"visitor-code","email":"visitor@friction.market"}],"description":"Pool-agnostic browser mining client for BTX matmul service-challenge shares (WebGPU → WASM → pure-JS)","homepage":"https://github.com/btx-tools/btx-challenges-sdk/tree/main/packages/browser-miner#readme","keywords":["btx","mining","webgpu","browser","service-challenge","proof-of-work"],"repository":{"type":"git","url":"git+https://github.com/btx-tools/btx-challenges-sdk.git","directory":"packages/browser-miner"},"author":{"name":"visitor-code","email":"visitor@friction.market"},"bugs":{"url":"https://github.com/btx-tools/btx-challenges-sdk/issues"},"license":"MIT","readme":"# @btx-tools/browser-miner\n\nA **pool-agnostic browser mining client** for BTX matmul service-challenge shares.\nIt drives the SDK's solver cascade (**WebGPU → WASM → pure-JS**) over a small\nadapter interface, with vardiff, GPU duty-cycle throttling, and new-job preemption.\n\n> ## ⚠️ This is not a money-maker\n> A browser solves **far slower** than native hardware, and BTX's network hashrate\n> is large — so a browser miner earns **≈ $0** (`stats.estimatedEarnings` is always\n> 0). The value is **zero-install access, engagement, and decentralization** —\n> \"donate spare cycles,\" gamified access — **never** \"earn money in your browser.\"\n> Mining must be **consent-based**: opt-in, visible, pausable, throttled. Silent\n> background mining is malware (cryptojacking) — don't ship it.\n\n## Install\n\n```sh\nnpm i @btx-tools/browser-miner @btx-tools/challenges-sdk\n# optional, for the fast paths:\nnpm i @btx-tools/matmul-webgpu @btx-tools/matmul-wasm\n```\n\n## Usage\n\n```ts\nimport { BrowserMiner } from '@btx-tools/browser-miner';\n\nconst miner = new BrowserMiner({\n  adapter: myPool,            // your MiningPoolAdapter (see below)\n  workerId: 'browser-1',\n  dutyCycle: 0.5,             // use ~50% of the GPU; rest yielded to the page\n  onStats: (s) => render(s), // { backend, hashrate, sharesAccepted, ... estimatedEarnings: 0 }\n  onShare: (share, result) => log(share, result),\n});\n\nstartButton.onclick = () => miner.start(); // explicit consent\nstopButton.onclick = () => miner.stop();    // graceful; releases the GPU\n```\n\nThe miner auto-selects the best backend (`webgpu → wasm → pure-js`), builds **one\nsolver per job**, searches it in small chunks (the preemption + throttle point),\nsubmits hits, and preempts on a new `jobId`/`cleanJobs`.\n\n## The adapter (the only thing a pool implements)\n\nA \"job\" is a service-challenge envelope whose `target` is the **share-target**; a\n\"share\" is a nonce whose matmul digest ≤ that target — the exact shape the SDK\n`Solver` / `@btx-tools/matmul-webgpu` already consume.\n\n```ts\ninterface MiningPoolAdapter {\n  getJob(): Promise<MiningJob>;                          // { jobId, challenge, cleanJobs?, expiresAt? }\n  submitShare(s: ShareSubmission): Promise<ShareResult>; // { accepted, reason? }\n}\n```\n\nDrop in any transport: HTTP (`fetch` getJob/submitShare), WebSocket (stratum-lite),\nor a btxd `issue`/`redeem` adapter. A production pool should **rate-limit + verify\nshares cheaply (Freivalds, O(n²))** server-side and run vardiff — browsers are\nuntrusted. `examples/04-browser-miner` ships a self-contained in-page reference\nwork source (synth jobs + local verify, no btxd) so the client is demoable standalone.\n\n## Backends\n\n| Backend | When | Source |\n|---|---|---|\n| `webgpu` | `navigator.gpu` + `@btx-tools/matmul-webgpu` installed | reused solver per job; one device |\n| `wasm` | `@btx-tools/matmul-wasm` installed + initializes here | per-job `WasmSolver` |\n| `pure-js` | always (fallback) | SDK `Solver` `mode:'pure-js'` |\n\nSelection happens **once** at startup (`selectBackend`); inject your own via\n`new BrowserMiner({ backend })` for tests or an explicit choice.\n\n`targetForExpectedAttempts(n)` helps a work source pick an easy share-target\n(`target = 2²⁵⁶ / n`).\n\n## Testing\n\n```sh\npnpm test   # headless unit tests (mock adapter + pure-js) — loop, preemption,\n            # pause/resume, duty-cycle, stop cleanup, vardiff — run in CI\n\npnpm build  # then the real-GPU end-to-end gate under Deno:\ndeno run --unstable-webgpu --allow-read --config tests/gpu/deno.json tests/gpu/miner.deno.ts\n```\n\nThe GPU gate runs the full loop over the real WebGPU backend against a synth work\nsource and asserts shares are found, **byte-exact-verified (Solver 1-nonce)**,\naccepted, and counted, with duty-cycle throttling on.\n\n## License\n\nMIT.\n","readmeFilename":"README.md","_rev":"1-73b665ac8d174ef25784f832137207e6"}