nano-pow 4.1.7 → 5.0.1

package/README.md

@@ -8,7 +8,8 @@ _Proof-of-work generation and validation with WebGPU/WebGL for Nano cryptocurren
 
 NanoPow uses WebGPU to generate proof-of-work nonces meeting the requirements
 of the Nano cryptocurrency. WebGPU is cutting edge technology, so for browsers
-which do not yet support it, a WebGL 2.0 implementation is used as a fallback.
+which do not yet support it, WebGL 2.0 and WASM implementations are available
+as fallbacks.
 
 All calculations take place client-side, so nonces can be generated offline and
 cached for the next transaction block. For more information about the
@@ -36,12 +37,6 @@ import { NanoPow } from 'nano-pow'
 import NanoPow from 'nano-pow'
 ```
 
-A specific API can be explicitly imported:
-
-```javascript
-import { NanoPowGpu, NanoPowGl } from 'nano-pow'
-```
-
 Use it directly on a webpage with a script module:
 
 ```html
@@ -75,16 +70,34 @@ const { valid } = await NanoPow.work_validate(work, hash)
 ### Options
 ```javascript
 const options = {
-	// default 0xFFFFFFF800000000 for send/change blocks
+	// default best available in order: webgpu => webgl => wasm => cpu
+	api: 'webgpu',
+	// default FFFFFFF800000000 for send/change blocks
 	difficulty: 'FFFFFFC000000000',
-	// default 8, valid range 1-32
-	effort: 16,
+	// default 4, valid range 1-32
+	effort: 2,
 	// default false
 	debug: true
 }
 const { work } = await NanoPow.work_generate(hash, options)
 ```
 
+#### What is "effort"?
+NanoPow's "effort" metric is an abstraction of various GPU and CPU capabilities.
+Different systems will have different optimal settings, but as a general rule of
+thumb:
+
+* WebGPU must strike a balance between the overhead of dispatching work to the
+GPU and the time it takes to compute the dispatch itself. Start with a low value
+like 2 or 4.
+* WegGL works by drawing to an invisible 2-D canvas that is `effort * 256`
+pixels long on each side. Since PoW speed in this case depends on resolution
+_and_ framerate, push for a value as high as the GPU can support. For example, a
+GPU that can draw 4096 x 4096 at 15 FPS should be set around 16 effort.
+* WASM does not use the GPU at all and instead depends on Web Workers for CPU
+multi-threading capabilities. Set effort equal to the number of physical cores
+in the CPU.
+
 ## Executables
 NanoPow can be installed globally and executed from the command line. This is
 useful for systems without a graphical interface.
@@ -137,11 +150,11 @@ detached process, and it can also be started manually to customize behavior by
 executing the server script directly.
 
 #### Environment Variables
-`NANO_POW_PORT`: override the default port 5040
+`NANO_POW_DEBUG`: enable additional logging saved to the HOME directory
 
-`NANO_POW_EFFORT` increase or decrease demand on the GPU
+`NANO_POW_EFFORT`: increase or decrease demand on the GPU
 
-`NANO_POW_DEBUG` enable additional logging saved to the HOME directory
+`NANO_POW_PORT`: override the default port 5040
 
 ```console
 $ # Launch the server and detach from the current session
@@ -196,7 +209,8 @@ every last bit of speed and performance out of it.
 A few basic tests are availabe in the source repository.
 * `test/index.html` in the source repository contains a web interface to change
 execution options and compare results.
-* `test/script.sh` starts the `nano-pow` server and sends some basic requests.
+* `test/script.sh` runs some basic benchmarks to check the CLI, and then it
+starts the `nano-pow` server and sends some validate and generate requests.
 
 ## Building
 1. Clone source

package/dist/bin/cli.js

@@ -5,69 +5,238 @@ import { spawn } from "node:child_process";
 import { getRandomValues } from "node:crypto";
 import { createInterface } from "node:readline/promises";
 
+// src/utils/api-support/wasm.ts
+//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
+//! SPDX-License-Identifier: GPL-3.0-or-later
+var wasm = { isSupported: false };
+Object.defineProperty(wasm, "isSupported", {
+  get: async function() {
+    let isWasmSupported = false;
+    try {
+      const wasmBuffer = new Uint8Array([
+        0,
+        97,
+        115,
+        109,
+        1,
+        0,
+        0,
+        0,
+        // WASM magic header and version
+        1,
+        4,
+        // Type section, 4 byte descriptor
+        1,
+        96,
+        0,
+        0,
+        // 1 type, type function, 0 params, 0 returns
+        3,
+        2,
+        // Function section, 2 byte descriptor
+        1,
+        0,
+        // 1 function, ID 0
+        10,
+        23,
+        // Code section, 23 bytes
+        1,
+        21,
+        // 1 function body, 21 bytes
+        0,
+        // 0 local variables
+        253,
+        12,
+        // v128.const
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        // assign i64x2 values
+        26,
+        11
+        // Drop result, end function
+      ]);
+      const module = await WebAssembly.compile(wasmBuffer);
+      const instance = await WebAssembly.instantiate(module);
+      isWasmSupported = instance instanceof WebAssembly.Instance;
+    } catch (err) {
+      console.warn("WASM is not supported in this environment.\n", err);
+      isWasmSupported = false;
+    } finally {
+      delete this.isSupported;
+      this.isSupported = isWasmSupported;
+      return this.isSupported;
+    }
+  }
+});
+
+// src/utils/api-support/webgl.ts
+//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
+//! SPDX-License-Identifier: GPL-3.0-or-later
+var webgl = { isSupported: false };
+Object.defineProperty(webgl, "isSupported", {
+  get: async function() {
+    let isWebglSupported = false;
+    try {
+      const gl = new OffscreenCanvas(0, 0)?.getContext?.("webgl2");
+      isWebglSupported = gl instanceof WebGL2RenderingContext;
+    } catch (err) {
+      console.warn("WebGL is not supported in this environment.\n", err);
+      isWebglSupported = false;
+    } finally {
+      delete this.isSupported;
+      this.isSupported = isWebglSupported;
+      return this.isSupported;
+    }
+  }
+});
+
+// src/utils/api-support/webgpu.ts
+//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
+//! SPDX-License-Identifier: GPL-3.0-or-later
+var webgpu = { isSupported: false };
+Object.defineProperty(webgpu, "isSupported", {
+  get: async function() {
+    let isWebgpuSupported = false;
+    try {
+      const adapter = await navigator?.gpu?.requestAdapter?.();
+      isWebgpuSupported = adapter instanceof GPUAdapter;
+    } catch (err) {
+      console.warn("WebGPU is not supported in this environment.\n", err);
+      isWebgpuSupported = false;
+    } finally {
+      delete this.isSupported;
+      this.isSupported = isWebgpuSupported;
+      return this.isSupported;
+    }
+  }
+});
+
+// src/utils/api-support/index.ts
+//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
+//! SPDX-License-Identifier: GPL-3.0-or-later
+
+// src/utils/bigint.ts
+//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
+//! SPDX-License-Identifier: GPL-3.0-or-later
+
+// src/utils/logger.ts
+//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
+//! SPDX-License-Identifier: GPL-3.0-or-later
+var Logger = class {
+  isEnabled = false;
+  groups = {};
+  groupStart(name) {
+    if (this.isEnabled) {
+      console.groupCollapsed(name);
+      this.groups[name] = true;
+    }
+  }
+  groupEnd(name) {
+    if (this.groups[name]) {
+      console.groupEnd();
+      delete this.groups[name];
+    }
+  }
+  log(...args2) {
+    if (this.isEnabled) {
+      const datetime = new Date(Date.now()).toLocaleString(Intl.DateTimeFormat().resolvedOptions().locale ?? "en-US", { hour12: false, dateStyle: "medium", timeStyle: "medium" });
+      for (let i = 0; i < args2.length; i++) {
+        if (typeof args2[i] === "string") {
+          args2[i] = args2[i].replace(datetime, "").trimStart();
+        }
+        if (args2[i] instanceof Error) {
+          if ("stack" in args2[i]) {
+            args2.splice(i + 1, 0, args2[i].stack);
+          } else if ("message" in args2[i]) {
+            args2.splice(i + 1, 0, args2[i].message);
+          }
+        }
+      }
+      const entry = `${datetime} ${globalThis.process?.title ?? "NanoPow"}[${globalThis.process?.pid ?? "browser"}]:`;
+      console.log(entry, ...args2);
+      globalThis.process?.send?.({ type: "console", data: `${entry} ${args2}` });
+    }
+  }
+};
+
+// src/utils/queue.ts
+//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
+//! SPDX-License-Identifier: GPL-3.0-or-later
+
 // src/utils/index.ts
-function average(times) {
-  if (times == null || times.length === 0) return {};
-  let count = times.length;
+//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
+//! SPDX-License-Identifier: GPL-3.0-or-later
+function stats(times) {
+  if (times == null || times.length === 0) return null;
+  const count = times.length;
+  const truncatedStart = Math.floor(count * 0.1);
+  const truncatedEnd = count - truncatedStart;
+  const truncatedCount = truncatedEnd - truncatedStart;
   let min = Number.MAX_SAFE_INTEGER;
-  let logarithms, max, median, rate, reciprocals, total, truncated, truncatedCount;
-  logarithms = max = median = rate = reciprocals = total = truncated = truncatedCount = 0;
+  let logarithms, max, median, reciprocals, total;
+  logarithms = max = median = reciprocals = total = 0;
+  let truncatedMin = Number.MAX_SAFE_INTEGER;
+  let truncatedLogarithms, truncatedMax, truncatedReciprocals, truncatedTotal;
+  truncatedLogarithms = truncatedMax = truncatedReciprocals = truncatedTotal = 0;
   times.sort((a, b) => a - b);
   for (let i = 0; i < count; i++) {
     const time = times[i];
     total += time;
-    reciprocals += 1 / time;
     logarithms += Math.log(time);
+    reciprocals += 1 / time;
     min = Math.min(min, time);
     max = Math.max(max, time);
-    if (i + 1 === Math.ceil(count / 2)) median = time;
-    if (count < 3 || i > 0.1 * count && i < 0.9 * (count - 1)) {
-      truncated += time;
-      truncatedCount++;
-    }
+    if (i === Math.floor((count - 1) / 2)) median = time;
+    if (i === Math.floor(count / 2) && count % 2 === 0) median = (median + time) / 2;
+  }
+  for (let i = truncatedStart; i < truncatedEnd; i++) {
+    const time = times[i];
+    truncatedTotal += time;
+    truncatedLogarithms += Math.log(time);
+    truncatedReciprocals += 1 / time;
+    truncatedMin = Math.min(truncatedMin, time);
+    truncatedMax = Math.max(truncatedMax, time);
   }
   return {
     count,
     total,
+    rate: 1e3 * count / total,
     min,
     max,
     median,
     arithmetic: total / count,
-    harmonic: count / reciprocals,
     geometric: Math.exp(logarithms / count),
-    truncated: truncated / truncatedCount,
-    rate: 1e3 * truncatedCount / (truncated || total)
+    harmonic: count / reciprocals,
+    truncatedCount,
+    truncatedTotal,
+    truncatedRate: 1e3 * truncatedCount / truncatedTotal,
+    truncatedMin,
+    truncatedMax,
+    truncatedArithmetic: truncatedTotal / truncatedCount,
+    truncatedGeometric: Math.exp(truncatedLogarithms / truncatedCount),
+    truncatedHarmonic: truncatedCount / truncatedReciprocals
   };
 }
-function isHex(input, min, max) {
-  if (typeof input !== "string") {
-    return false;
-  }
-  if (typeof min !== "undefined" && typeof min !== "number") {
-    throw new Error(`Invalid argument for parameter 'min'`);
-  }
-  if (typeof max !== "undefined" && typeof max !== "number") {
-    throw new Error(`Invalid argument for parameter 'max'`);
-  }
-  const range = min === void 0 && max === void 0 ? "+" : `{${min ?? "0"},${max ?? ""}}`;
-  const regexp = new RegExp(`^[0-9A-Fa-f]${range}$`, "m");
-  return regexp.test(input);
-}
-function isNotHex(input, min, max) {
-  return !isHex(input, min, max);
-}
-function log(...args2) {
-  if (process?.env?.NANO_POW_DEBUG) {
-    const entry = `${new Date(Date.now()).toLocaleString(Intl.DateTimeFormat().resolvedOptions().locale ?? "en-US", { hour12: false, dateStyle: "medium", timeStyle: "medium" })} NanoPow[${process.pid}]: ${args2}`;
-    console.log(entry);
-    process.send?.({ type: "console", message: entry });
-  }
-}
 
 // src/bin/cli.ts
 //! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
 //! SPDX-License-Identifier: GPL-3.0-or-later
 process.title = "NanoPow CLI";
+var logger = new Logger();
 delete process.env.NANO_POW_DEBUG;
 delete process.env.NANO_POW_EFFORT;
 delete process.env.NANO_POW_PORT;
@@ -80,7 +249,7 @@ if (!process.stdin.isTTY) {
   let i = 0;
   for await (const line of stdin) {
     i++;
-    if (isHex(line, 64)) {
+    if (/^[A-Fa-f\d]{64}$/.test(line)) {
       hashes.push(line);
     } else {
       stdinErrors.push(`Skipping invalid stdin input line ${i}`);
@@ -89,13 +258,13 @@ if (!process.stdin.isTTY) {
 }
 var args = process.argv.slice(2);
 if (hashes.length === 0 && args.length === 0 || args.some((v) => v === "--help" || v === "-h")) {
-  console.log(
-    `Usage: nano-pow [OPTION]... BLOCKHASH...
+  console.log(`Usage: nano-pow [OPTION]... BLOCKHASH...
 Generate work for BLOCKHASH, or multiple work values for BLOCKHASH(es)
 BLOCKHASH is a 64-character hexadecimal string. Multiple blockhashes must be separated by whitespace or line breaks.
 Prints the result as a Javascript object to standard output as soon as it is calculated.
 If using --batch, results are printed only after all BLOCKHASH(es) have be processed.
 If using --validate, results will also include validity properties.
+
   -b, --batch                 process all data before returning final results as array
   -d, --difficulty <value>    override the minimum difficulty value
   -e, --effort <value>        increase demand on GPU processing
@@ -104,6 +273,7 @@ If using --validate, results will also include validity properties.
   -h, --help                  show this dialog
       --debug                 enable additional logging output
       --benchmark <value>     generate work for specified number of random hashes
+      --score <value>         used with --benchmark to run specified number of times and calculate work-per-second
 
 If validating a nonce, it must be a 16-character hexadecimal value.
 Effort must be a decimal number between 1-32.
@@ -111,46 +281,31 @@ Difficulty must be a hexadecimal string between 0-FFFFFFFFFFFFFFFF.
 
 Report bugs: <bug-nano-pow@zoso.dev>
 Full documentation: <https://www.npmjs.com/package/nano-pow>
-`
-  );
+`);
   process.exit(0);
 }
 var inArgs = [];
-while (isHex(args[args.length - 1], 64)) {
-  inArgs.unshift(args.pop());
+var isParsingHash = true;
+while (isParsingHash) {
+  if (!/^[A-Fa-f\d]{16}$/.test(args[args.length - 1])) break;
+  try {
+    inArgs.unshift(args.pop());
+  } catch {
+    isParsingHash = false;
+  }
 }
 hashes.push(...inArgs);
 var isBatch = false;
 var isBenchmark = false;
+var runs = 1;
 var body = {
   action: "work_generate"
 };
 for (let i = 0; i < args.length; i++) {
   switch (args[i]) {
-    case "--validate":
-    case "-v": {
-      const v = args[i + 1];
-      if (v == null) throw new Error("Missing argument for work validation");
-      if (isNotHex(v, 16)) throw new Error("Invalid work to validate");
-      if (hashes.length !== 1) throw new Error("Validate accepts exactly one hash");
-      body.action = "work_validate";
-      body.work = v;
-      break;
-    }
-    case "--difficulty":
-    case "-d": {
-      const d = args[i + 1];
-      if (d == null) throw new Error("Missing argument for difficulty");
-      if (isNotHex(d, 1, 16)) throw new Error("Invalid difficulty");
-      body.difficulty = d;
-      break;
-    }
-    case "--effort":
-    case "-e": {
-      const e = args[i + 1];
-      if (e == null) throw new Error("Missing argument for effort");
-      if (parseInt(e) < 1 || parseInt(e) > 32) throw new Error("Invalid effort");
-      process.env.NANO_POW_EFFORT = e;
+    case "--batch":
+    case "-b": {
+      isBatch = true;
       break;
     }
     case "--benchmark": {
@@ -167,12 +322,42 @@ for (let i = 0; i < args.length; i++) {
       break;
     }
     case "--debug": {
+      logger.isEnabled = true;
       process.env.NANO_POW_DEBUG = "true";
       break;
     }
-    case "--batch":
-    case "-b": {
-      isBatch = true;
+    case "--difficulty":
+    case "-d": {
+      const d = args[i + 1];
+      if (d == null) throw new Error("Missing argument for difficulty");
+      if (!/^[A-Fa-f\d]{16}$/.test(d)) throw new Error("Invalid argument for difficulty");
+      body.difficulty = d;
+      break;
+    }
+    case "--effort":
+    case "-e": {
+      const e = args[i + 1];
+      if (e == null) throw new Error("Missing argument for effort");
+      if (parseInt(e) < 1 || parseInt(e) > 32) throw new Error("Invalid effort");
+      process.env.NANO_POW_EFFORT = e;
+      break;
+    }
+    case "--score": {
+      const s = args[i + 1];
+      if (s == null) throw new Error("Missing argument for score");
+      const count = +s;
+      if (count < 1) throw new Error("Invalid score runs count");
+      runs = count;
+      break;
+    }
+    case "--validate":
+    case "-v": {
+      const v = args[i + 1];
+      if (v == null) throw new Error("Missing argument for work validation");
+      if (!/^[A-Fa-f\d]{16}$/.test(v)) throw new Error("Invalid argument for work validation");
+      if (hashes.length !== 1) throw new Error("Validate accepts exactly one hash");
+      body.action = "work_validate";
+      body.work = v;
       break;
     }
   }
@@ -181,71 +366,121 @@ if (hashes.length === 0) {
   console.error("Invalid block hash input");
   process.exit(1);
 }
-log("CLI args:", ...args);
+logger.log("CLI args: ", ...args);
 for (const stdinErr of stdinErrors) {
-  log(stdinErr);
+  logger.log(stdinErr);
 }
-log("Starting NanoPow CLI");
+logger.log("launching server");
 var server = spawn(
   process.execPath,
   [new URL(import.meta.resolve("./server.js")).pathname],
   { stdio: ["pipe", "pipe", "pipe", "ipc"] }
 );
 server.once("error", (err) => {
-  log(err);
+  logger.log(err);
   process.exit(1);
 });
 server.on("message", async (msg) => {
-  if (msg.type === "console") {
-    log(msg.message);
-  }
-  if (msg.type === "listening") {
-    const port = +msg.message;
-    if (port > -1) {
-      log(`CLI server listening on port ${port}`);
-      try {
-        await execute(port);
-      } catch {
-        log(`Error executing ${body.action}`);
+  if (typeof msg === "object" && msg != null && "type" in msg && typeof msg.type === "string" && "data" in msg && typeof msg.data === "string") {
+    if (msg.type === "console") {
+      logger.log(msg.data);
+    }
+    if (msg.type === "listening") {
+      if (msg.data === "ipc") {
+        logger.log(`CLI connected to server over IPC`);
+        try {
+          if (isBenchmark) {
+            if (runs > 1) {
+              await score();
+            } else {
+              await benchmark();
+            }
+          } else {
+            await execute();
+          }
+        } catch {
+          logger.log(`Error executing ${body.action}`);
+        } finally {
+          server.kill();
+        }
+      } else {
+        logger.log("CLI server failed to connect over IPC");
       }
-    } else {
-      log("Server failed to provide port");
     }
+  } else {
+    logger.log("received invalid message from server", msg);
   }
 });
 server.on("close", (code) => {
-  log(`Server closed with exit code ${code}`);
+  logger.log(`Server closed with exit code ${code}`);
   process.exit(code);
 });
-async function execute(port) {
-  const results = [];
-  if (isBenchmark) console.log("Running benchmark...");
-  let start = 0;
+async function benchmark() {
+  console.log("Running benchmark...");
+  let start = 0, end = 0;
   const times = [];
   for (const hash of hashes) {
+    const kill = setTimeout(() => {
+      throw new Error("cli execution timed out");
+    }, 6e4);
+    body.hash = hash;
     try {
-      const aborter = new AbortController();
-      const kill = setTimeout(() => aborter.abort(), 6e4);
-      body.hash = hash;
       start = performance.now();
-      const response = await fetch(`http://localhost:${port}`, {
-        method: "POST",
-        body: JSON.stringify(body),
-        signal: aborter.signal
-      });
+      await request(body);
+      end = performance.now();
+      times.push(end - start);
+    } catch (err) {
+      logger.log(err);
+    } finally {
       clearTimeout(kill);
-      const result = await response.json();
-      if (isBatch || isBenchmark) {
-        results.push(result);
-        times.push(performance.now() - start);
-      } else {
-        console.log(result);
+    }
+  }
+  console.log(stats(times));
+  return stats(times);
+}
+async function execute() {
+  const results = [];
+  for (const hash of hashes) {
+    const kill = setTimeout(() => {
+      throw new Error("cli execution timed out");
+    }, 6e4);
+    body.hash = hash;
+    try {
+      const result = await request(body);
+      isBatch ? results.push(result) : console.log(result);
+    } catch (err) {
+      logger.log(err);
+    } finally {
+      clearTimeout(kill);
+    }
+  }
+  if (isBatch) console.log(results);
+}
+async function request(body2) {
+  return new Promise((resolve, reject) => {
+    const listener = async (msg) => {
+      if (typeof msg === "object" && msg != null && "type" in msg && typeof msg.type === "string" && "data" in msg && typeof msg.data === "string") {
+        if (msg.type === "ipc") {
+          resolve(JSON.parse(msg.data));
+          server.off("message", listener);
+        }
       }
+    };
+    server.on("message", listener);
+    server.send({ type: "ipc", data: JSON.stringify(body2) }, (cb) => cb ? reject(cb) : logger.log("cli ipc request to server"));
+  });
+}
+async function score() {
+  console.log("Calculating work per second...");
+  const rates = [];
+  for (let i = 0; i < runs; i++) {
+    try {
+      const result = await benchmark();
+      logger.log(result);
+      if (result != null) rates.push(result.truncatedRate);
     } catch (err) {
-      log(err);
+      logger.log(err);
     }
   }
-  if (isBatch && !isBenchmark) console.log(results);
-  if (process.env.NANO_POW_DEBUG || isBenchmark) console.log(average(times));
-  server.kill();
+  console.log(stats(rates)?.truncatedHarmonic, "wps");
 }

package/dist/bin/nano-pow.sh

@@ -10,11 +10,11 @@ NANO_POW_LOGS="$NANO_POW_HOME"/logs;
 mkdir -p "$NANO_POW_LOGS";
 if [ "$1" = '--server' ]; then
 	shift;
-	node "$SCRIPT_DIR"/server.js --max-http-header-size=1024 --max-old-space-size=256 >> "$NANO_POW_LOGS"/nano-pow-server-$(date -I).log 2>&1 & echo "$!" > "$NANO_POW_HOME"/server.pid;
-	sleep 0.1;
+	npm start >> "$NANO_POW_LOGS"/nano-pow-server-$(date -I).log 2>&1 &
+	sleep 1;
 	if [ "$(ps | grep $(cat $NANO_POW_HOME/server.pid))" = '' ]; then
 		cat $(ls -td "$NANO_POW_LOGS"/* | head -n1);
 	fi;
 else
-	node "$SCRIPT_DIR"/cli.js --max-old-space-size=256 "$@";
+	node --max-old-space-size=256 "$SCRIPT_DIR"/cli.js "$@";
 fi;