zeldhash-miner 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Zeldhash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,244 @@
+# zeldhash-miner (TypeScript SDK)
+
+TypeScript SDK for Zeldhash mining in the browser. This package wraps the Rust/WASM miner, exposes a simple API for mining vanity Bitcoin txids, and supports optional WebGPU acceleration.
+
+> Requires Node.js 20+ and an ES module-capable bundler (Vite, webpack 5, etc.).
+
+## Installation
+
+```bash
+npm install zeldhash-miner
+```
+
+If you are developing locally from the monorepo, run the full pipeline to regenerate WASM bindings, library bundle, and demo:
+
+```bash
+./scripts/build-all.sh
+```
+
+## Quick Start
+
+```ts
+import { ZeldMiner, ZeldMinerErrorCode } from "zeldhash-miner";
+
+const miner = new ZeldMiner({
+  network: "mainnet",
+  batchSize: 10_000,
+  useWebGPU: true, // automatically falls back to CPU if unavailable
+  workerThreads: 4,
+  satsPerVbyte: 12,
+});
+
+miner.on("progress", ({ hashRate, hashesProcessed }) => {
+  console.log("hash rate", hashRate, "hashes", hashesProcessed.toString());
+});
+
+miner.on("found", ({ psbt, nonce, txid }) => {
+  console.log("nonce found", nonce.toString());
+  console.log("txid", txid);
+  console.log("psbt", psbt);
+});
+
+miner.on("error", (err) => {
+  if (err.code === ZeldMinerErrorCode.INVALID_INPUT) {
+    console.error("bad inputs", err.details);
+  } else {
+    console.error(err);
+  }
+});
+
+await miner.mineTransaction({
+  inputs: [
+    {
+      txid: "1f81ad6116ac6045b5bc4941afc212456770ab389c05973c088f22063a2aff37",
+      vout: 0,
+      scriptPubKey: "0014ea9d20bfb938b2a0d778a5d8d8bc2aaff755c395",
+      amount: 100000,
+    },
+  ],
+  outputs: [
+    { address: "bc1qa2wjp0ae8ze2p4mc5hvd30p24lm4tsu479mw0r", amount: 90000, change: false },
+    { address: "bc1q...change", change: true }, // amount auto-calculated
+  ],
+  targetZeros: 6,
+  distribution: [600n, 300n, 100n], // optional ZELD distribution
+});
+```
+
+## API Reference
+
+### `new ZeldMiner(options)`
+
+Creates a new miner instance.
+
+**Options:**
+- `network`: `"mainnet" | "testnet" | "signet" | "regtest"`
+- `batchSize`: `number` — Base batch size per worker
+- `useWebGPU`: `boolean` — Attempt GPU backend (falls back to CPU)
+- `workerThreads`: `number` — Worker count for CPU or GPU tasks
+- `satsPerVbyte`: `number` — Fee rate for PSBT construction
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `mineTransaction(params): Promise<MineResult>` | Mines for a nonce and returns an unsigned PSBT |
+| `pause(): void` | Pause the current mining session |
+| `resume(): Promise<void>` | Resume after pause |
+| `stop(): void` | Abort and reject the mining promise |
+| `on(event, handler)` | Subscribe to miner events |
+| `off(event, handler)` | Unsubscribe from events |
+
+### Mining Parameters
+
+```ts
+interface MineParams {
+  inputs: TxInput[];          // UTXOs to spend
+  outputs: TxOutput[];        // Destinations (one must be change: true)
+  targetZeros: number;        // Leading zero hex digits (1–32)
+  startNonce?: bigint;        // Starting point (default 0n)
+  batchSize?: number;         // Override instance batch size
+  distribution?: bigint[];    // Optional ZELD distribution values
+  signal?: AbortSignal;       // Abort controller signal
+}
+
+interface TxInput {
+  txid: string;
+  vout: number;
+  scriptPubKey: string;
+  amount: number;
+}
+
+interface TxOutput {
+  address: string;
+  amount?: number;  // Required unless change: true
+  change: boolean;
+}
+```
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `progress` | `ProgressStats` | Periodic mining progress |
+| `found` | `MineResult` | Nonce found, PSBT ready |
+| `error` | `ZeldMinerError` | Mining error occurred |
+| `stopped` | `void` | Mining was stopped |
+
+```ts
+interface ProgressStats {
+  hashesProcessed: bigint;
+  hashRate: number;
+  elapsedMs?: number;
+  lastNonce?: bigint;
+  workerId?: number;
+}
+
+interface MineResult {
+  psbt: string;        // Base64-encoded unsigned PSBT
+  txid: string;        // Transaction ID with leading zeros
+  nonce: bigint;       // Winning nonce
+  attempts: bigint;    // Total hashes computed
+  duration: number;    // Elapsed milliseconds
+  hashRate: number;    // Hashes per second
+}
+```
+
+## ZELD Distribution Mode
+
+When `distribution` is provided, the OP_RETURN payload becomes:
+
+```
+OP_RETURN | push | "ZELD" | CBOR([distribution..., nonce])
+```
+
+The nonce is appended as the final CBOR element. Bitcoin nodes truncate the CBOR array to match the count of spendable outputs, so the nonce is automatically ignored by downstream wallets while still affecting the txid for mining.
+
+```ts
+await miner.mineTransaction({
+  // ...
+  distribution: [600n, 300n, 100n], // 3 outputs → 3 values
+});
+```
+
+## Error Handling
+
+```ts
+import { ZeldMinerError, ZeldMinerErrorCode } from "zeldhash-miner";
+
+try {
+  await miner.mineTransaction(params);
+} catch (err) {
+  if (err instanceof ZeldMinerError) {
+    switch (err.code) {
+      case ZeldMinerErrorCode.INSUFFICIENT_FUNDS:
+        console.error("Not enough sats");
+        break;
+      case ZeldMinerErrorCode.INVALID_ADDRESS:
+        console.error("Bad address:", err.message);
+        break;
+      case ZeldMinerErrorCode.MINING_ABORTED:
+        console.error("Stopped by user");
+        break;
+      default:
+        console.error(err);
+    }
+  }
+}
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `INVALID_ADDRESS` | Address parsing failed |
+| `UNSUPPORTED_ADDRESS_TYPE` | Only P2WPKH and P2TR supported |
+| `INSUFFICIENT_FUNDS` | Inputs don't cover outputs + fees |
+| `NO_CHANGE_OUTPUT` | No output marked as change |
+| `MULTIPLE_CHANGE_OUTPUTS` | More than one change output |
+| `INVALID_INPUT` | Bad parameter |
+| `WEBGPU_NOT_AVAILABLE` | WebGPU requested but unavailable |
+| `WORKER_ERROR` | Internal worker failure |
+| `MINING_ABORTED` | Mining was stopped |
+| `DUST_OUTPUT` | Output below dust limit (310 sats P2WPKH / 330 sats P2TR) |
+
+## Runtime Notes
+
+- The WASM artifacts live in `node_modules/zeldhash-miner/wasm`. Most modern bundlers copy them automatically because the SDK loads them via `new URL("./wasm/zeldhash_miner_wasm_bg.wasm", import.meta.url)`.
+- If your bundler does not copy assets automatically, copy the `wasm/` folder to your public/static assets.
+- WebGPU is optional. When `useWebGPU` is `true`, the miner auto-detects support and silently falls back to CPU.
+
+## Build & Test
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+```
+
+## Publishing
+
+The package is configured for the public npm registry with `"publishConfig.access": "public"`.
+
+```bash
+# From the monorepo root
+./scripts/build-all.sh
+cd facades/typescript && npm publish
+```
+
+Release flows are documented in [docs/RELEASING.md](../../docs/RELEASING.md).
+
+## License
+
+MIT
+
+### Framework Integration
+
+For detailed setup instructions for different frameworks (Vite, Next.js, CRA, etc.), see:
+
+📖 **[docs/INTEGRATION.md](../../docs/INTEGRATION.md)**

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+declare type CoordinatorEvent = "ready" | "progress" | "found" | "error" | "stopped";
+
+declare type CoordinatorEventMap = {
+    ready: void;
+    progress: ProgressEvent_2;
+    found: MineResult;
+    error: ZeldMinerError;
+    stopped: void;
+};
+
+declare type CoordinatorListener<K extends CoordinatorEvent> = (payload: CoordinatorEventMap[K]) => void;
+
+export declare const createMinerError: (code: ZeldMinerErrorCode, message: string, details?: ZeldMinerErrorDetails) => ZeldMinerError;
+
+export declare interface MineParams {
+    inputs: TxInput[];
+    outputs: TxOutput[];
+    targetZeros: number;
+    startNonce?: bigint;
+    batchSize?: number;
+    signal?: AbortSignal;
+    distribution?: bigint[];
+}
+
+export declare interface MineResult {
+    psbt: string;
+    txid: string;
+    nonce: bigint;
+    attempts: bigint;
+    duration: number;
+    hashRate: number;
+}
+
+export declare class MiningCoordinator {
+    private readonly mode;
+    private readonly batchSize;
+    private readonly workerCount;
+    private readonly listeners;
+    private readonly workers;
+    private readonly readyPromise;
+    private readonly abortHandler;
+    private stride;
+    private cleanupExternalAbort;
+    private running;
+    private paused;
+    private startedAt;
+    private txInputs?;
+    private txOutputs?;
+    private txNetwork?;
+    private satsPerVbyte?;
+    private template?;
+    private targetZeros?;
+    private startNonce;
+    private txDistribution?;
+    private externalAbort?;
+    private terminated;
+    constructor(options: MiningCoordinatorOptions);
+    on<K extends CoordinatorEvent>(event: K, handler: CoordinatorListener<K>): void;
+    off<K extends CoordinatorEvent>(event: K, handler: CoordinatorListener<K>): void;
+    private emit;
+    private spawnWorkers;
+    private handleWorkerMessage;
+    private emitProgress;
+    private computeNextNonce;
+    private stopWorkers;
+    private terminateWorkers;
+    start(params: StartParams): Promise<void>;
+    pause(): void;
+    resume(): Promise<void>;
+    stop(): void;
+}
+
+declare interface MiningCoordinatorOptions {
+    mode: WorkerMode;
+    batchSize: number;
+    workerThreads: number;
+}
+
+declare interface MiningTemplate {
+    prefix: Uint8Array;
+    suffix: Uint8Array;
+    useCborNonce?: boolean;
+}
+
+export declare type Network = "mainnet" | "testnet" | "signet" | "regtest";
+
+declare interface ProgressEvent_2 {
+    hashesProcessed: bigint;
+    hashRate: number;
+    elapsedMs?: number;
+    lastNonce?: bigint;
+    workerId?: string;
+}
+
+export declare type ProgressStats = ProgressEvent_2;
+
+declare interface StartParams {
+    inputs: TxInput[];
+    outputs: TxOutput[];
+    network: Network;
+    satsPerVbyte: number;
+    template: WorkerTemplate;
+    targetZeros: number;
+    startNonce?: bigint;
+    signal?: AbortSignal;
+    distribution?: bigint[];
+}
+
+export declare const toZeldMinerError: (err: unknown, fallbackCode?: ZeldMinerErrorCode, details?: ZeldMinerErrorDetails) => ZeldMinerError;
+
+export declare class TransactionBuilder {
+    private readonly network;
+    private readonly satsPerVbyte;
+    constructor(network: Network, satsPerVbyte: number);
+    private getWasm;
+    private assertNonceRange;
+    private cloneInputs;
+    private cloneOutputs;
+    private validateInputs;
+    private validateAddressResult;
+    private validateOutputs;
+    private validateDistribution;
+    buildMiningTemplate(params: {
+        inputs: TxInput[];
+        outputs: TxOutput[];
+        startNonce: bigint;
+        batchSize: number;
+        distribution?: bigint[];
+    }): Promise<MiningTemplate & {
+        nonceLength: number;
+    }>;
+    buildPsbt(params: {
+        inputs: TxInput[];
+        outputs: TxOutput[];
+        nonce: bigint;
+        distribution?: bigint[];
+    }): Promise<string>;
+}
+
+export declare interface TxInput {
+    txid: string;
+    vout: number;
+    scriptPubKey: string;
+    amount: number;
+}
+
+export declare interface TxOutput {
+    address: string;
+    amount?: number;
+    change: boolean;
+}
+
+declare type WorkerMode = "cpu" | "gpu";
+
+declare interface WorkerTemplate extends MiningTemplate {
+    nonceLength: number;
+    useCborNonce?: boolean;
+}
+
+export declare class ZeldMiner {
+    private readonly options;
+    private readonly builder;
+    private coordinator;
+    private readonly listeners;
+    private state;
+    private stopRequested;
+    constructor(options: ZeldMinerOptions);
+    on<K extends ZeldMinerEvent>(event: K, handler: (payload: ZeldMinerEventMap[K]) => void): void;
+    off<K extends ZeldMinerEvent>(event: K, handler: (payload: ZeldMinerEventMap[K]) => void): void;
+    private emit;
+    private validateOptions;
+    private selectBackend;
+    private clearCoordinatorHandlers;
+    mineTransaction(params: MineParams): Promise<MineResult>;
+    stop(): void;
+    pause(): void;
+    resume(): Promise<void>;
+}
+
+export declare class ZeldMinerError extends Error {
+    readonly code: ZeldMinerErrorCode;
+    readonly details?: ZeldMinerErrorDetails;
+    constructor(code: ZeldMinerErrorCode, message: string, details?: ZeldMinerErrorDetails);
+}
+
+export declare enum ZeldMinerErrorCode {
+    INVALID_ADDRESS = "INVALID_ADDRESS",
+    UNSUPPORTED_ADDRESS_TYPE = "UNSUPPORTED_ADDRESS_TYPE",
+    INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS",
+    NO_CHANGE_OUTPUT = "NO_CHANGE_OUTPUT",
+    MULTIPLE_CHANGE_OUTPUTS = "MULTIPLE_CHANGE_OUTPUTS",
+    INVALID_INPUT = "INVALID_INPUT",
+    WEBGPU_NOT_AVAILABLE = "WEBGPU_NOT_AVAILABLE",
+    WORKER_ERROR = "WORKER_ERROR",
+    MINING_ABORTED = "MINING_ABORTED",
+    DUST_OUTPUT = "DUST_OUTPUT"
+}
+
+declare type ZeldMinerErrorDetails = Record<string, unknown>;
+
+declare type ZeldMinerEvent = "progress" | "found" | "error" | "stopped";
+
+declare type ZeldMinerEventMap = {
+    progress: ProgressStats;
+    found: MineResult;
+    error: ZeldMinerError;
+    stopped: void;
+};
+
+export declare interface ZeldMinerOptions {
+    network: Network;
+    batchSize: number;
+    useWebGPU: boolean;
+    workerThreads: number;
+    satsPerVbyte: number;
+}
+
+export { }