nano-pow 4.0.6 → 4.0.8

package/README.md

@@ -17,8 +17,10 @@ https://docs.nano.org/integration-guides/work-generation/#work-calculation-detai
 
 ## Installation
 ```console
-npm i nano-pow
+$ npm i nano-pow
 ```
+NanoPow can also be installed globally to add the `nano-pow` command to your
+environment. To learn more, see [#Executables](#executables).
 
 ## Usage
 ### Import
@@ -46,17 +48,17 @@ Use it directly on a webpage with a script module:
 <script type="module">
 	(async () => {
 		const { NanoPow } = await import('https://cdn.jsdelivr.net/npm/nano-pow@latest')
-		const work = await NanoPow.search(some_hash)
+		const { work } = await NanoPow.work_generate(some_hash)
 		console.log(work)
 	})()
 </script>
 ```
 
-### Search
+### Generate
 ```javascript
 // `hash` is a 64-char hex string
 const hash = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
-const work = await NanoPow.search(hash)
+const { work } = await NanoPow.work_generate(hash)
 // Result is a 16-char hex string
 ```
 
@@ -66,29 +68,112 @@ const work = await NanoPow.search(hash)
 const work = 'fedcba0987654321'
 // `hash` is a 64-char hex string
 const hash = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
-const isValid = await NanoPow.validate(work, hash)
+const { valid } = await NanoPow.work_validate(work, hash)
 // Result is a boolean
 ```
 
 ### Options
 ```javascript
 const options = {
-	// default 0xFFFFFFF8 for send/change blocks
+	// default 0xFFFFFFF800000000 for send/change blocks
 	threshold: number,
 	// default 8, valid range 1-32
 	effort: number,
 	// default false
 	debug: true
 }
-const work = await NanoPow.search(hash, options)
+const { work } = await NanoPow.work_generate(hash, options)
 ```
 
-### Command Line
+## Executables
 NanoPow can be installed globally and executed from the command line. This is
 useful for systems without a graphical interface.
 ```console
 $ npm -g i nano-pow
-$ nano-pow --help  # view command documentation
+$ nano-pow --help    # view abbreviated CLI help
+$ man nano-pow       # view full manual
+```
+Ensure you have proper permissions on your
+[npm `prefix`](https://docs.npmjs.com/cli/v11/commands/npm-prefix) directory and
+have configured your `PATH` accordingly.
+
+For example, this adds a user-specific directory for local binaries to `PATH`
+upon login and configures `npm prefix` to use it for global installations:
+```console
+$ echo 'PATH="$HOME/.local/bin:$PATH"' >> .bashrc
+$ npm config set prefix="$HOME/.local"
+```
+### Command Line
+NanoPow provides a shell command&mdash;`nano-pow`&mdash;to accomodate systems
+without a graphical user interface. It launches a headless Chrome browser using
+`puppeteer` to access the required WebGPU or WebGL APIs. Use the `--global` flag
+when installing to add the executable script to your system.
+```console
+$ npm i -g nano-pow
+```
+Some examples are provided below, and for full documentation, read the manual
+with `man nano-pow`.
+
+```console
+$ # Generate a work value using default settings and debugging output enabled.
+$ nano-pow --debug 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+```
+```console
+$ # Generate work using customized behavior with options.
+$ nano-pow --effort 32 --threshold FFFFFFC000000000 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+```
+```console
+$ # Validate an existing work nonce against a blockhash.
+nano-pow --validate fedcba9876543210 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+```
+```console
+$ # Process blockhashes in batches to reduce the initial startup overhead.
+$ nano-pow 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef [...]
+$ # OR
+nano-pow $(cat /path/to/hashes/file)
+$ # OR
+$ cat /path/to/hashes/file | nano-pow
+```
+
+### Server
+NanoPow also provides a basic work server similar to the one included in the
+official Nano node software. The installed command will launch the server in a
+detached process, and you can also start it yourself to customize behavior by
+executing the server script directly.
+
+`PORT` can be passed as an environment variable and defaults to 3000 if not
+specified.
+
+`NANO_POW_EFFORT` can also be passed as an environment variable to increase
+or decrease the demand on the GPU and defaults to 8 if not specified.
+
+```console
+$ # Launch the server and detach from the current session
+$ PORT=8080 nano-pow --server
+$ # View process ID for "NanoPow Server"
+$ cat ~/.nano-pow/server.pid
+$ # Display list of server logs
+$ ls ~/.nano-pow/logs/
+$ # Find process ID manually
+$ ps aux | grep NanoPow
+```
+Work is generated or validated by sending an HTTP `POST` request to the
+configured hostname or IP address of the machine. Some basic help is available
+via `GET` request.
+```console
+$ # Generate a work value
+$ curl -d '{
+	"action": "work_generate",
+	"hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+}' localhost:3000
+```
+```console
+$ # Validate a work value
+$ curl -d '{
+	"action": "work_validate",
+	"work": "e45835c3b291c3d1",
+	"hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+}' localhost:3000
 ```
 
 ## Notes
@@ -106,21 +191,16 @@ for all other accounts.
 * 𝘵𝘩𝘳𝘦𝘴𝘩𝘰𝘭𝘥 is 0xFFFFFFF800000000 for send/change blocks and 0xFFFFFE0000000000
 for receive/open/epoch blocks.
 
-The threshold is implemented in code as only the first 32 bits due to WGSL only
-supporting u32 integer types, but the result is the same. For example, if
-checking whether a two-digit number xx > 55, and it is known that the first
-digit is 6, it is also automatically known that xx is greater than 55. The
-default threshold used is the send/change difficulty. Any other threshold can be
-specified in practice.
-
 The BLAKE2b implementation has been optimized to the extreme for this package
-due to the very narrow use case to which it is applied. The compute shader is
-consequently immense, but the goal is to squeeze every last bit of speed and
-performance out of it.
+due to the very narrow use case to which it is applied. The compute shader used
+by the WebGPU implementation is consequently immense, but the goal is to squeeze
+every last bit of speed and performance out of it.
 
 ## Tests
-`test.html` in the source repository contains some basic tests to compare the
-speed of this tool. Feel free to check out how your system fares.
+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.
 
 ## Building
 1. Clone source
@@ -128,11 +208,10 @@ speed of this tool. Feel free to check out how your system fares.
 1. Install dev dependencies
 1. Compile, minify, and bundle
 
-```bash
-git clone https://zoso.dev/nano-pow.git
-cd nano-pow
-npm i
-npm run build
+```console
+$ git clone https://zoso.dev/nano-pow.git
+$ cd nano-pow
+$ npm i
 ```
 
 ## Reporting Bugs

package/dist/bin/cli.js

@@ -1,161 +1,136 @@
 #!/usr/bin/env node
 //! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
 //! SPDX-License-Identifier: GPL-3.0-or-later
-import * as crypto from "node:crypto";
-import * as fs from "node:fs/promises";
 import * as readline from "node:readline/promises";
-import * as puppeteer from "puppeteer";
-import { cliHelp } from "../../docs/index.js";
+process.title = "NanoPow CLI";
+process.env.NANO_POW_DEBUG = "";
+process.env.NANO_POW_EFFORT = "";
+process.env.NANO_POW_PORT = "3000";
+function log(...args2) {
+  if (process.env.NANO_POW_DEBUG) console.log(new Date(Date.now()).toLocaleString(), "NanoPow", args2);
+}
 const hashes = [];
 const stdinErrors = [];
 if (!process.stdin.isTTY) {
   const stdin = readline.createInterface({
     input: process.stdin
   });
+  let i = 0;
   for await (const line of stdin) {
+    i++;
     if (/^[0-9A-Fa-f]{64}$/.test(line)) {
       hashes.push(line);
     } else {
-      stdinErrors.push(`Skipping invalid stdin input: ${line}`);
+      stdinErrors.push(`Skipping invalid stdin input line ${i}`);
     }
   }
 }
 const args = process.argv.slice(2);
 if (hashes.length === 0 && args.length === 0 || args.some((v) => v === "--help" || v === "-h")) {
-  console.log(cliHelp);
-  process.exit();
+  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.
+
+  -h, --help                  show this dialog
+      --debug                 enable additional logging output
+
+	-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
+  -v, --validate=<value>      check an existing work value instead of searching for one
+
+If validating a nonce, it must be a 16-character hexadecimal value.
+Effort must be a decimal number between 1-32.
+Difficulty must be a hexadecimal string between 1-FFFFFFFFFFFFFFFF.
+
+Report bugs: <bug-nano-pow@zoso.dev>
+Full documentation: <https://www.npmjs.com/package/nano-pow>
+`
+  );
+  process.exit(0);
 }
 const inArgs = [];
 while (/^[0-9A-Fa-f]{64}$/.test(args[args.length - 1] ?? "")) {
   inArgs.unshift(args.pop());
 }
 hashes.push(...inArgs);
-let fn = "work_generate";
-let work = "";
-let isJson = false;
-const options = {};
+if (hashes.length === 0) {
+  console.error("Invalid block hash input");
+  process.exit(1);
+}
+let isBatch = false;
+const body = {
+  action: "work_generate"
+};
 for (let i = 0; i < args.length; i++) {
   switch (args[i]) {
     case "--validate":
     case "-v": {
       if (args[i + 1] == null) throw new Error("Missing argument for work validation");
       if (!/^[0-9A-Fa-f]{16}$/.test(args[i + 1])) throw new Error("Invalid work to validate");
-      fn = "work_validate";
-      work = `'${args[i + 1]}', `;
+      body.action = "work_validate";
+      body.work = args[i + 1];
       break;
     }
-    case "--threshold":
-    case "-t": {
-      if (args[i + 1] == null) throw new Error("Missing argument for threshold");
-      if (!/^[0-9A-Fa-f]{0,8}$/.test(args[i + 1])) throw new Error("Invalid threshold");
-      options["threshold"] = parseInt(args[i + 1], 16);
+    case "--difficulty":
+    case "-d": {
+      if (args[i + 1] == null) throw new Error("Missing argument for difficulty");
+      if (!/^[0-9A-Fa-f][0-9A-Fa-f]{0,15}$/.test(args[i + 1])) throw new Error("Invalid difficulty");
+      body.difficulty = args[i + 1];
       break;
     }
     case "--effort":
     case "-e": {
       if (args[i + 1] == null) throw new Error("Missing argument for effort");
       if (!/^[0-9]{0,2}$/.test(args[i + 1])) throw new Error("Invalid effort");
-      options["effort"] = parseInt(args[i + 1], 10);
+      process.env.NANO_POW_EFFORT = args[i + 1];
       break;
     }
-    case "--debug":
-    case "-d": {
-      options["debug"] = true;
+    case "--debug": {
+      process.env.NANO_POW_DEBUG = "true";
       break;
     }
-    case "--json":
-    case "-j": {
-      isJson = true;
+    case "--batch":
+    case "-b": {
+      isBatch = true;
       break;
     }
   }
 }
-if (options["debug"]) {
-  console.log(`NanoPowCli.${fn}()`);
-  console.log(`${fn} options`, JSON.stringify(options));
-  for (const stdinErr of stdinErrors) {
-    console.warn(stdinErr);
-  }
-}
-if (hashes.length === 0) {
-  console.error("Invalid block hash input");
-  process.exit(1);
+log("CLI args:", ...args);
+for (const stdinErr of stdinErrors) {
+  log(stdinErr);
 }
-(async () => {
-  const NanoPow = await fs.readFile(new URL("../main.min.js", import.meta.url), "utf-8");
-  const browser = await puppeteer.launch({
-    headless: true,
-    args: [
-      "--headless=new",
-      "--use-angle=vulkan",
-      "--enable-features=Vulkan",
-      "--disable-vulkan-surface",
-      "--enable-unsafe-webgpu"
-    ]
-  });
-  const page = await browser.newPage();
-  const path = new URL(import.meta.url).pathname;
-  const dir = path.slice(0, path.lastIndexOf("/"));
-  await fs.writeFile(`${dir}/cli.html`, "");
-  await page.goto(import.meta.resolve("./cli.html"));
-  await page.waitForFunction(async () => {
-    return await navigator.gpu.requestAdapter();
-  });
-  const inject = `
-		${NanoPow}
-		window.results = []
-		const hashes = ["${hashes.join('","')}"]
-		for (const hash of hashes) {
-			try {
-				const result = await NanoPow.${fn}(${work}hash, ${JSON.stringify(options)})
-				window.results.push(result)
-				console.log(\`cli \${JSON.stringify(result, null, 4)}\`)
-			} catch (err) {
-				console.error(\`cli \${err}\`)
-			}
-		}
-		console.log('cli exit')
-	`;
-  const hash = await crypto.subtle.digest("SHA-256", Buffer.from(inject, "utf-8"));
-  const src = `sha256-${Buffer.from(hash).toString("base64")}`;
-  let start = performance.now();
-  page.on("console", async (msg) => {
-    const output = msg.text().split(/^cli /);
-    if (output[0] === "") {
-      if (output[1] === "exit") {
-        if (isJson) {
-          const results = await page.evaluate(() => {
-            return window.results;
-          });
-          console.log(JSON.stringify(results, null, 4));
-        }
-        const end = performance.now();
-        if (options["debug"]) console.log(end - start, "ms total |", (end - start) / hashes.length, "ms avg");
-        await browser.close();
-      } else if (!isJson) {
-        try {
-          console.log(JSON.parse(output[1]));
-        } catch (err) {
-          console.log(output[1]);
-        }
-      }
-    } else if (options["debug"]) {
-      try {
-        console.log(JSON.parse(msg.text()));
-      } catch (err) {
-        console.log(msg.text());
-      }
+log("Starting NanoPow CLI");
+await import("./server.js");
+const results = [];
+const start = performance.now();
+const aborter = new AbortController();
+for (const hash of hashes) {
+  try {
+    body.hash = hash;
+    const kill = setTimeout(aborter.abort, 5e3);
+    const response = await fetch(`http://localhost:${process.env.NANO_POW_PORT}`, {
+      method: "POST",
+      body: JSON.stringify(body),
+      signal: aborter.signal
+    });
+    clearTimeout(kill);
+    const result = await response.json();
+    if (isBatch) {
+      results.push(result);
+    } else {
+      console.log(result);
     }
-  });
-  start = performance.now();
-  await page.setContent(`
-		<!DOCTYPE html>
-			<head>
-				<meta http-equiv="Content-Security-Policy" content="default-src 'none'; base-uri 'none'; form-action 'none'; script-src '${src}';">
-				<script type="module">${inject}</script>
-			</head>
-		</html>
-	`);
-  await fs.unlink(`${dir}/cli.html`);
-  if (options["debug"]) console.log("Puppeteer initialized");
-})();
+  } catch (err) {
+    log(err);
+  }
+}
+const end = performance.now();
+if (isBatch) console.log(results);
+log(end - start, "ms total |", (end - start) / hashes.length, "ms avg");
+process.exit(0);

package/dist/bin/nano-pow.sh

@@ -10,7 +10,7 @@ NANO_POW_LOGS="$NANO_POW_HOME"/logs;
 mkdir -p "$NANO_POW_LOGS";
 if [ "$1" = '--server' ]; then
 	shift;
-	node "$SCRIPT_DIR"/server.js "$@" > "$NANO_POW_LOGS"/nano-pow-server-$(date +%s).log 2>&1 & echo "$!" > "$NANO_POW_HOME"/server.pid;
+	node "$SCRIPT_DIR"/server.js > "$NANO_POW_LOGS"/nano-pow-server-$(date +%s).log 2>&1 & echo "$!" > "$NANO_POW_HOME"/server.pid;
 else
 	node "$SCRIPT_DIR"/cli.js "$@";
 fi;

package/dist/bin/server.js

@@ -1,181 +1,165 @@
 #!/usr/bin/env node
 //! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
 //! SPDX-License-Identifier: GPL-3.0-or-later
-import * as crypto from "node:crypto";
-import * as dns from "node:dns/promises";
-import * as fs from "node:fs/promises";
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { launch } from "puppeteer";
+import { lookup } from "node:dns/promises";
 import * as http from "node:http";
-import * as os from "node:os";
-import * as puppeteer from "puppeteer";
-import { serverHelp } from "../../docs/index.js";
-const PORT = process.env.PORT || 3e3;
-function log(...args) {
-  console.log(new Date(Date.now()).toLocaleString(), "NanoPow", args);
-}
-log("Starting server");
-const NanoPow = await fs.readFile(new URL("../main.min.js", import.meta.url), "utf-8");
+import { hostname } from "node:os";
+import { join } from "node:path";
+process.title = "NanoPow Server";
+const MAX_REQUEST_SIZE = 1024;
+const MAX_BODY_SIZE = 158;
+const DEBUG = !!(process.env.NANO_POW_DEBUG || false);
+const EFFORT = +(process.env.NANO_POW_EFFORT || 8);
+const PORT = +(process.env.NANO_POW_PORT || 3e3);
 let browser;
 let page;
-async function work_generate(res, json) {
-  if (!/^[0-9A-Fa-f]{64}$/.test(json.hash ?? "")) {
-    res.writeHead(400, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "Invalid hash. Must be a 64-character hex string." }));
-    return;
-  }
-  if (json.difficulty && !/^[1-9A-Fa-f][0-9A-Fa-f]{0,15}$/.test(json.difficulty)) {
-    res.writeHead(400, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "Invalid difficulty. Must be a hexadecimal string between 1-FFFFFFFFFFFFFFFF." }));
-    return;
-  }
+function log(...args) {
+  if (DEBUG) console.log(new Date(Date.now()).toLocaleString(), "NanoPow", args);
+}
+async function respond(res, data) {
+  let statusCode = 500;
+  let headers = { "Content-Type": "application/json" };
+  let response = "work_validate failed";
   try {
-    const result = await page.evaluate(async (args) => {
-      const options = {
-        debug: true
-      };
-      if (args.difficulty) options.threshold = BigInt(`0x${args.difficulty}`);
-      return await window.NanoPow.work_generate(args.hash, options);
-    }, json);
-    res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify(result));
+    const datastring = Buffer.concat(data).toString().replace(/\s+/g, "");
+    if (Buffer.byteLength(datastring) > MAX_BODY_SIZE) {
+      throw new Error("Invalid data.");
+    }
+    const { action, hash: hash2, work, difficulty } = JSON.parse(datastring);
+    if (action !== "work_generate" && action !== "work_validate") {
+      throw new Error("Invalid action. Must be work_generate or work_validate.");
+    }
+    if (!/^[0-9A-Fa-f]{64}$/.test(hash2 ?? "")) {
+      throw new Error("Invalid hash. Must be a 64-character hex string.");
+    }
+    if (difficulty && !/^[1-9A-Fa-f][0-9A-Fa-f]{0,15}$/.test(difficulty)) {
+      throw new Error("Invalid difficulty. Must be a hexadecimal string between 1-FFFFFFFFFFFFFFFF.");
+    }
+    if (action === "work_validate" && !/^[0-9A-Fa-f]{16}$/.test(work ?? "")) {
+      throw new Error("Invalid work. Must be a 16-character hex string.");
+    }
+    const options = {
+      debug: DEBUG,
+      effort: EFFORT,
+      threshold: difficulty
+    };
+    const args = [];
+    if (work) args.push(work);
+    args.push(hash2);
+    args.push(options);
+    response = JSON.stringify(await page.evaluate(async (action2, args2) => {
+      if (window.NanoPow == null) throw new Error("NanoPow not found");
+      return await window.NanoPow[action2](...args2);
+    }, action, args));
+    statusCode = 200;
   } catch (err) {
-    log("work_generate error:", err);
-    res.writeHead(500, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "work_generate failed" }));
+    log(err);
+    statusCode = 400;
+  } finally {
+    res.writeHead(statusCode, headers).end(response);
   }
 }
-async function work_validate(res, json) {
-  if (!/^[0-9A-Fa-f]{64}$/.test(json.hash ?? "")) {
-    res.writeHead(400, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "Invalid hash. Must be a 64-character hex string." }));
-    return;
-  }
-  if (json.difficulty && !/^[1-9A-Fa-f][0-9A-Fa-f]{0,15}$/.test(json.difficulty)) {
-    res.writeHead(400, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "Invalid difficulty. Must be a hexadecimal string between 1-FFFFFFFFFFFFFFFF." }));
-    return;
-  }
-  if (!/^[0-9A-Fa-f]{16}$/.test(json.work ?? "")) {
-    res.writeHead(400, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "Invalid work. Must be a 16-character hex string." }));
-    return;
+const server = http.createServer((req, res) => {
+  let data = [];
+  let reqSize = 0;
+  if (req.method === "POST") {
+    req.on("data", (chunk) => {
+      reqSize += chunk.byteLength;
+      if (reqSize > MAX_REQUEST_SIZE) {
+        res.writeHead(413, { "Content-Type": "text/plain" });
+        res.end("Content Too Large");
+        req.socket.destroy();
+        return;
+      }
+      data.push(chunk);
+    });
+    req.on("end", async () => {
+      if (!req.socket.destroyed) {
+        await respond(res, data);
+      }
+    });
+  } else {
+    res.writeHead(200, { "Content-Type": "text/plain" });
+    res.end(
+      `Usage: Send POST request to server URL to generate or validate Nano proof-of-work
+
+Generate work for a BLOCKHASH with an optional DIFFICULTY:
+  curl -d '{ action: "work_generate", hash: BLOCKHASH, difficulty?: DIFFICULTY }'
+
+Validate WORK previously calculated for a BLOCKHASH with an optional DIFFICULTY:
+  curl -d '{ action: "work_validate", work: WORK, hash: BLOCKHASH, difficulty?: DIFFICULTY }'
+
+BLOCKHASH is a 64-character hexadecimal string.
+WORK is 16-character hexadecimal string.
+DIFFICULTY is a 16-character hexadecimal string (default: FFFFFFF800000000)
+
+Report bugs: <bug-nano-pow@zoso.dev>
+Full documentation: <https://www.npmjs.com/package/nano-pow>
+`
+    );
   }
+});
+server.on("error", (e) => {
+  log("Server error", e);
   try {
-    const result = await page.evaluate(async (args) => {
-      const options = {
-        debug: true
-      };
-      if (args.difficulty) options.threshold = BigInt(`0x${args.difficulty}`);
-      return await window.NanoPow.work_validate(args.work, args.hash, options);
-    }, json);
-    res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify(result));
+    shutdown();
   } catch (err) {
-    log("work_validate error:", err);
-    res.writeHead(500, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "work_validate failed" }));
+    log("Failed to shut down", err);
+    process.exit(1);
   }
-}
-(async () => {
-  browser = await puppeteer.launch({
-    headless: true,
-    args: [
-      "--headless=new",
-      "--use-angle=vulkan",
-      "--enable-features=Vulkan",
-      "--disable-vulkan-surface",
-      "--enable-unsafe-webgpu"
-    ]
-  });
-  page = await browser.newPage();
-  page.on("console", (msg) => {
-    log(msg.text());
-  });
-  const path = new URL(import.meta.url).pathname;
-  const dir = path.slice(0, path.lastIndexOf("/"));
-  await fs.writeFile(`${dir}/server.html`, "");
-  await page.goto(import.meta.resolve("./server.html"));
-  await page.waitForFunction(async () => {
-    return await navigator.gpu.requestAdapter();
-  });
-  const inject = `${NanoPow};window.NanoPow=NanoPow;`;
-  const hash = await crypto.subtle.digest("SHA-256", Buffer.from(inject, "utf-8"));
-  const src = `sha256-${Buffer.from(hash).toString("base64")}`;
-  await page.setContent(`
-		<!DOCTYPE html>
-			<head>
-				<meta http-equiv="Content-Security-Policy" content="default-src 'none'; base-uri 'none'; form-action 'none'; script-src '${src}';">
-				<script type="module">${inject}</script>
-			</head>
-		</html>
-	`);
-  await fs.unlink(`${dir}/server.html`);
-  log("Puppeteer initialized");
-  const server = http.createServer(async (req, res) => {
-    let data = [];
-    if (req.method === "POST") {
-      req.on("data", (chunk) => {
-        data.push(chunk);
-      });
-      req.on("end", async () => {
-        let json;
-        try {
-          json = JSON.parse(Buffer.concat(data).toString());
-        } catch (err) {
-          log("JSON.parse error:", err);
-          log("Failed JSON:", json);
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Invalid data." }));
-          return;
-        }
-        switch (json.action) {
-          case "work_generate": {
-            await work_generate(res, json);
-            break;
-          }
-          case "work_validate": {
-            await work_validate(res, json);
-            break;
-          }
-          default: {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: `Invalid data.` }));
-            return;
-          }
-        }
-      });
-    } else {
-      res.writeHead(200, { "Content-Type": "text/plain" });
-      res.end(serverHelp);
-    }
+});
+function shutdown() {
+  log("Shutdown signal received");
+  const kill = setTimeout(() => {
+    log("Server unresponsive, forcefully stopped");
+    process.exit(1);
+  }, 1e4);
+  server.close(() => {
+    clearTimeout(kill);
+    log("Server stopped");
+    process.exit(0);
   });
-  server.on("error", (e) => {
-    log("Server error", e);
-    try {
-      shutdown();
-    } catch (err) {
-      log("Failed to shut down", err);
-      process.exit(1);
-    }
-  });
-  server.listen(PORT, async () => {
-    process.title = "NanoPow Server";
-    const ip = await dns.lookup(os.hostname(), { family: 4 });
-    log(`Server process ${process.pid} running at ${ip.address}:${PORT}/`);
-  });
-  function shutdown() {
-    log("Shutdown signal received");
-    const kill = setTimeout(() => {
-      log("Server unresponsive, forcefully stopped");
-      process.exit(1);
-    }, 1e4);
-    server.close(async () => {
-      await page?.close();
-      await browser?.close();
-      clearTimeout(kill);
-      log("Server stopped");
-      process.exit(0);
-    });
-  }
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-})();
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+log("Starting NanoPow work server");
+const NanoPow = await readFile(new URL("../main.min.js", import.meta.url), "utf-8");
+browser = await launch({
+  headless: true,
+  args: [
+    "--headless=new",
+    "--use-angle=vulkan",
+    "--enable-features=Vulkan",
+    "--disable-vulkan-surface",
+    "--enable-unsafe-webgpu"
+  ]
+});
+page = await browser.newPage();
+page.on("console", (msg) => log(msg.text()));
+const path = new URL(import.meta.url).pathname;
+const dir = path.slice(0, path.lastIndexOf("/"));
+const filename = join(dir, `${process.pid}.html`);
+await writeFile(filename, "");
+await page.goto(import.meta.resolve(filename));
+await page.waitForFunction(async () => {
+  return await navigator["gpu"].requestAdapter();
+});
+const src = `${NanoPow};window.NanoPow=NanoPow;`;
+const hash = await crypto.subtle.digest("SHA-256", Buffer.from(src));
+const enc = `sha256-${Buffer.from(hash).toString("base64")}`;
+await page.setContent(`
+	<!DOCTYPE html>
+		<head>
+			<meta http-equiv="Content-Security-Policy" content="default-src 'none'; base-uri 'none'; form-action 'none'; script-src '${enc}';">
+			<script type="module">${src}</script>
+		</head>
+	</html>
+`);
+await unlink(filename);
+log("Puppeteer initialized");
+server.listen(PORT, async () => {
+  const ip = await lookup(hostname(), { family: 4 });
+  log(`Server process ${process.pid} running at ${ip.address}:${PORT}/`);
+});

package/dist/main.min.js

@@ -51,10 +51,6 @@ var NanoPowGl = class _NanoPowGl {
   static #cores = Math.max(1, Math.floor(navigator.hardwareConcurrency));
   static #WORKLOAD = 256 * this.#cores;
   static #canvas;
-  /** Drawing buffer size in pixels. */
-  static get size() {
-    return (this.#gl?.drawingBufferWidth ?? 0) * (this.#gl?.drawingBufferHeight ?? 0);
-  }
   static #gl;
   static #drawProgram;
   static #downsampleProgram;
@@ -187,14 +183,14 @@ var NanoPowGl = class _NanoPowGl {
       this.#gl.uniformBlockBinding(this.#drawProgram, this.#gl.getUniformBlockIndex(this.#drawProgram, "WORK"), 1);
       this.#gl.bindBuffer(this.#gl.UNIFORM_BUFFER, null);
       this.#query = this.#gl.createQuery();
-      this.#pixels = new Uint32Array(this.size * 4);
+      this.#pixels = new Uint32Array(this.#gl.drawingBufferWidth * this.#gl.drawingBufferHeight * 4);
     } catch (err) {
       throw new Error("WebGL initialization failed.", { cause: err });
     } finally {
       this.#busy = false;
     }
     this.#isInitialized = true;
-    console.log(`NanoPow WebGL initialized at ${this.#gl.drawingBufferWidth}x${this.#gl.drawingBufferHeight}. Maximum nonces checked per frame: ${this.size}`);
+    console.log(`NanoPow WebGL initialized. Maximum nonces checked per frame: ${this.#gl.drawingBufferWidth * this.#gl.drawingBufferHeight}`);
   }
   /**
   * On WebGL context loss, attempts to clear all program variables and then

package/dist/types.d.ts

@@ -1,7 +1,11 @@
 // SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-import '@webgpu/types'
+declare global {
+	interface Window {
+		NanoPow: typeof NanoPow
+	}
+}
 
 /**
 * Used by work server for inbound requests to `work_generate`.
@@ -11,6 +15,7 @@ import '@webgpu/types'
 * @param {string} [difficulty=FFFFFFF800000000] - Minimum threshold for a nonce to be valid
 */
 type WorkGenerateRequest = {
+	[key: string]: string | undefined
 	action: 'work_generate'
 	hash: string
 	difficulty?: string
@@ -24,6 +29,7 @@ type WorkGenerateRequest = {
 * @param {string} difficulty - BLAKE2b hash result which was compared to specified minimum threshold
 */
 type WorkGenerateResponse = {
+	[key: string]: string
 	hash: string
 	work: string
 	difficulty: string
@@ -38,6 +44,7 @@ type WorkGenerateResponse = {
 * @param {string} [difficulty=FFFFFFF800000000] - Minimum threshold for a nonce to be valid
 */
 type WorkValidateRequest = {
+	[key: string]: string | undefined
 	action: 'work_validate'
 	hash: string
 	work: string
@@ -55,6 +62,7 @@ type WorkValidateRequest = {
 * @param {string} valid_receive - 1 for true if nonce is valid for receive blocks, else 0 for false
 */
 type WorkValidateResponse = {
+	[key: string]: string | undefined
 	hash: string
 	work: string
 	difficulty: string
@@ -103,9 +111,8 @@ export type NanoPowOptions = {
 * Nano proof-of-work using WebGL 2.0.
 */
 export declare class NanoPowGl {
+	static [key: string]: (...args: any[]) => any
 	#private
-	/** Drawing buffer width in pixels. */
-	static get size (): number
 	/**
 	* Constructs canvas, gets WebGL context, initializes buffers, and compiles
 	* shaders.
@@ -153,6 +160,7 @@ export declare class NanoPowGl {
 */
 export declare class NanoPowGpu {
 	#private
+	static [key: string]: (...args: any[]) => any
 	static init (): Promise<void>
 	static setup (): void
 	static reset (): void

package/docs/nano-pow.1

@@ -12,12 +12,19 @@ nano-pow \- proof-of-work generation and validation for Nano cryptocurrency
 .SH DESCRIPTION
 Generate work for \fIBLOCKHASH\fR, or multiple work values for \fIBLOCKHASH\fR(es).
 .PP
+If the \fI--server\fR option is provided as the first argument, all other options are ignored and the NanoPow server is started.
+.PP
 \fIBLOCKHASH\fR is a 64-character hexadecimal string. Multiple blockhashes must be separated by whitespace or line breaks.
 .PP
-Prints a 16-character hexadecimal work value to standard output. If \fB--validate\fR is used, prints 'true' or 'false' to standard output.
+Prints a 16-character hexadecimal work value, the BLAKE2b result, and the originating hash to standard output as a Javascript object.
+.PP
+If \fB--validate\fR is used, the original work value is returned instead along with validation flags.
 
 .SH OPTIONS
 .TP
+\fB--server\fR
+Start work server (see SERVER below). Must be the first argument in order to be recognized.
+.TP
 \fB\-h\fR, \fB\-\-help\fR
 Show this help dialog and exit.
 .TP
@@ -25,20 +32,64 @@ Show this help dialog and exit.
 Enable additional logging output.
 .TP
 \fB\-j\fR, \fB\-\-json\fR
-Format output as JSON.
+Format final output of all hashes as a JSON array of stringified values instead of incrementally returning Javascript objects for each result.
 .TP
 \fB\-e\fR, \fB\-\-effort\fR=\fIEFFORT\fR
 Increase demand on GPU processing. Must be between 1 and 32 inclusive.
 .TP
 \fB\-t\fR, \fB\-\-threshold\fR=\fITHRESHOLD\fR
-Override the minimum threshold value. Higher values increase difficulty. Must be a hexadecimal string between 0 and FFFFFFFF inclusive.
+Override the minimum threshold value. Higher values increase difficulty. Must be a hexadecimal string between 1 and FFFFFFFFFFFFFFFF inclusive.
 .TP
 \fB\-v\fR, \fB\-\-validate\fR=\fIWORK\fR
-Check an existing work value instead of searching for one.
+Check an existing work value instead of searching for one. If you pass multiple blockhashes, the work value will be validated against each one.
+
+.SH SERVER
+Calling \fBnano-pow\fR with the \fI--server\fR option will start the NanoPow work server in a detached process.
+.PP
+It provides work generation and validation via HTTP requests in a similar, but not identical, fashion as the official Nano node.
+.PP
+More specifically, it does not support the \fIuse_peers\fR, \fImultiplier\fR, \fIaccount\fR, \fIversion\fR, \fIblock\fR, and \fIjson_block\fR options.
+.PP
+By default, the server listens on port 3000. To use a different port, set the \fBPORT\fR environment variable before starting the server.
+
+.PP
+.EX
+$ PORT=8080 nano-pow --server
+.EE
+
+.PP
+The server process ID (PID) is saved to \fB~/.nano-pow/server.pid\fR. Log files are stored in \fB~/.nano-pow/logs/\fR.
+.TP
+To stop the server, terminate it using its PID.
+.EX
+$ cat ~/.nano-pow/server.pid
+12345
+$ kill 12345
+.EE
+.TP
+Alternatively, use \fBpgrep\fR to find the PID by process name:
+.EX
+$ pgrep "NanoPow Server"
+12345
+$ kill $(pgrep "NanoPow Server")
+.EE
+
+.PP
+The server accepts HTTP \fBPOST\fR requests to the server's root path (\fB/\fR). Requests should be in JSON format and include an \fBaction\fR field to specify the desired operation.
+.PP
+The following actions are supported:
+.TP
+\fBwork_generate\fR
+Generate a work value for a given blockhash. Requires a \fBhash\fR field containing the 64-character hexadecimal blockhash.
+.TP
+\fBwork_validate\fR
+Validate an existing work value against a blockhash. Requires \fBwork\fR field containing the 16-character hexadecimal work value and a \fBhash\fR field containing the 64-character hexadecimal blockhash.
+.PP
+
 
-.SH EXAMPLES
+.SH EXAMPLES - CLI
 .PP
-Search for a work nonce for a blockhash using the default threshold 0xFFFFFFF8:
+Search for a work nonce for a blockhash using the default threshold 0xFFFFFFF800000000:
 .EX
 $ nano-pow \fB0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\fR
 .EE
@@ -46,7 +97,7 @@ $ nano-pow \fB0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\f
 .PP
 Search for a work nonce using a custom threshold and increased effort:
 .EX
-$ nano-pow \fB\-t fffffe00 \-e 32 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\fR
+$ nano-pow \fB\-t fffffe0000000000 \-e 32 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\fR
 .EE
 
 .PP
@@ -61,6 +112,26 @@ Validate an existing work nonce against a blockhash and show debugging output:
 $ nano-pow \fB\-d \-v fedcba9876543210 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\fR
 .EE
 
+.SH EXAMPLES - SERVER
+.PP
+Generate a work value:
+.EX
+$ curl -d '{
+    "action": "work_generate",
+    "hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+}' localhost:3000
+.EE
+
+.PP
+Validate a work value:
+.EX
+$ curl -d '{
+    "action": "work_validate",
+    "work": "e45835c3b291c3d1",
+    "hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+}' localhost:3000
+.EE
+
 .SH AUTHOR
 Written by Chris Duncan.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nano-pow",
-	"version": "4.0.6",
+	"version": "4.0.8",
 	"description": "Proof-of-work generation and validation with WebGPU/WebGL for Nano cryptocurrency.",
 	"keywords": [
 		"nemo",

package/docs/index.js

@@ -1,38 +0,0 @@
-//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
-//! SPDX-License-Identifier: GPL-3.0-or-later
-
-export const cliHelp = `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 a 16-character hexadecimal work value to standard output. If using --validate, prints 'true' or 'false' to standard output instead.
-
-  -h, --help                  show this dialog
-  -d, --debug                 enable additional logging output
-	-j, --json                  format output as JSON
-  -e, --effort=<value>        increase demand on GPU processing
-  -t, --threshold=<value>     override the minimum threshold value
-  -v, --validate=<value>      check an existing work value instead of searching for one
-
-If validating a nonce, it must be a 16-character hexadecimal value.
-Effort must be a decimal number between 1-32.
-Threshold must be a hexadecimal string between 0-FFFFFFFF.
-
-Report bugs: <bug-nano-pow@zoso.dev>
-Full documentation: <https://www.npmjs.com/package/nano-pow>
-`
-
-export const serverHelp = `Usage: Send POST request to server URL to generate or validate Nano proof-of-work
-
-Generate work for a BLOCKHASH with an optional DIFFICULTY:
-  curl -d '{ action: "work_generate", hash: BLOCKHASH, difficulty?: DIFFICULTY }'
-
-Validate WORK previously calculated for a BLOCKHASH with an optional DIFFICULTY:
-  curl -d '{ action: "work_validate", work: WORK, hash: BLOCKHASH, difficulty?: DIFFICULTY }'
-
-BLOCKHASH is a 64-character hexadecimal string.
-WORK is 16-character hexadecimal string.
-DIFFICULTY is a 16-character hexadecimal string (default: FFFFFFF800000000)
-
-Report bugs: <bug-nano-pow@zoso.dev>
-Full documentation: <https://www.npmjs.com/package/nano-pow>
-`