nano-pow 4.0.6 → 4.0.7

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/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

@@ -9,6 +9,7 @@ import * as os from "node:os";
 import * as puppeteer from "puppeteer";
 import { serverHelp } from "../../docs/index.js";
 const PORT = process.env.PORT || 3e3;
+const EFFORT = +(process.env.NANO_POW_EFFORT || 8);
 function log(...args) {
   console.log(new Date(Date.now()).toLocaleString(), "NanoPow", args);
 }
@@ -28,13 +29,10 @@ async function work_generate(res, json) {
     return;
   }
   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);
+    const result = await page.evaluate(async (json2, options) => {
+      if (json2.difficulty) options.threshold = BigInt(`0x${json2.difficulty}`);
+      return await window.NanoPow.work_generate(json2.hash, options);
+    }, json, { debug: true, effort: EFFORT });
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify(result));
   } catch (err) {
@@ -60,13 +58,10 @@ async function work_validate(res, json) {
     return;
   }
   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);
+    const result = await page.evaluate(async (json2, options) => {
+      if (json2.difficulty) options.threshold = BigInt(`0x${json2.difficulty}`);
+      return await window.NanoPow.work_validate(json2.work, json2.hash, options);
+    }, json, { debug: true, effort: EFFORT });
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify(result));
   } catch (err) {

package/docs/index.js

@@ -8,14 +8,14 @@ Prints a 16-character hexadecimal work value to standard output. If using --vali
 
   -h, --help                  show this dialog
   -d, --debug                 enable additional logging output
-	-j, --json                  format output as JSON
+	-j, --json                  gather all results and output them at once 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.
+Threshold must be a hexadecimal string between 1-FFFFFFFFFFFFFFFF.
 
 Report bugs: <bug-nano-pow@zoso.dev>
 Full documentation: <https://www.npmjs.com/package/nano-pow>

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.7",
 	"description": "Proof-of-work generation and validation with WebGPU/WebGL for Nano cryptocurrency.",
 	"keywords": [
 		"nemo",