nano-pow 1.0.0 → 1.2.0

package/README.md

@@ -4,6 +4,8 @@ SPDX-License-Identifier: GPL-3.0-or-later
 -->
 
 # nano-pow
+_Proof-of-work generation and validation with WebGPU/WebGL for Nano cryptocurrency._
+
 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 also included.
@@ -14,23 +16,58 @@ proof-of-work equation defined by Nano, see
 https://docs.nano.org/integration-guides/work-generation/#work-calculation-details
 
 ## Installation
-
 ```console
 npm i nano-pow
 ```
 
 ## Usage
+### Import
+The easiest way to use NanoPow is to import it directly. Based on the features
+available in the environment, NanoPow will try to use its most performant API.
+
+The following two import statements are equivalent, and both are provided to
+accomodate project style preferences:
+
+```javascript
+import { NanoPow } from 'nano-pow'
+// OR
+import NanoPow from 'nano-pow'
+```
+
+A specific API can be explicitly imported:
 
 ```javascript
 import { NanoPowGpu, NanoPowGl } from 'nano-pow'
+```
 
+Any of these options can also be imported into the global namespace by targeting
+`dist/global.min.js`. For example:
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/nano-pow@latest/dist/global.min.js"></script>
+<script type="module">
+  console.log(NanoPow)
+</script>
+```
+
+### Search
+```javascript
 // `hash` is a 64-char hex string
-// `threshold` is optional and defaults to "0xFFFFFFF8"
-const workGpu = await NanoPowGpu.search(hash, threshold)
-const workGl = await NanoPowGl.search(hash, threshold)
+const hash = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
+// `threshold` is optional and defaults to "0xFFFFFFF8" for send/change blocks
+const work = await NanoPow.search(hash, threshold)
+// Result is a 16-char hex string
 ```
 
-You may also embed it in the global namespace by targeting `dist/global.min.js`
+### Validate
+```javascript
+// `work` is a 16-char hex string
+const work = 'fedcba0987654321'
+// `hash` is a 64-char hex string
+const hash = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
+// `threshold` is optional and defaults to "0xFFFFFFF8" for send/change blocks
+const isValid = await NanoPow.validate(work, hash, threshold)
+// Result is a boolean
+```
 
 ## Notes
 The `work` field in a Nano transaction block contains an 8-byte nonce that
@@ -47,9 +84,8 @@ hash of the most recent block in the account chain for all other accounts.
 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 one
-wants to know whether a two-digit number xx > 55, and you know the first digit is
-6, you automatically know it is greather than 55.
+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. Also, NanoPow technically compares the nonce to see if it is only greater than, and not necessarily equal to, the threshold, but the difference is trivial for a range of 2⁶⁴-1 nonces.
@@ -59,18 +95,22 @@ 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.
 
-## Validating work
-Although the nonces generated by this package have been tested extensively, a
-validation function is not currently implemented. There are other tools
-available to perform this trivial task, but if there is demand for it, then it
-can be delivered in a future update.
-
 ## 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.
 
 ## Building
-* `npm run build`: compile TypeScript, then minify and bundle with esbuild
+1. Clone source
+1. Enter the directory
+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
+```
 
 ## Donations
 If you find this package helpful, please consider tipping the developer.