From: Chris Duncan <chris@zoso.dev>
Date: Tue, 21 Jan 2025 18:14:49 +0000 (-0800)
Subject: Update README with new options object. Add example of async module loading in HTML... 
X-Git-Tag: v3.0.0~78
X-Git-Url: https://zoso.dev/?a=commitdiff_plain;h=84ffa266442b3795e4e5f209d12f5270f88ed5a1;p=nano-pow.git

Update README with new options object. Add example of async module loading in HTML. Reword global namespace pollution option to discourage it as a practice. Add sections for acknowledgements and licenses. Whitespace.
---

diff --git a/README.md b/README.md
index 9318dbe..9b3c143 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ _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 also included.
+which do not yet support it, a WebGL 2.0 implementation is used as a fallback.
 
 All calculations take place client-side, so nonces can be generated offline and
 cached for the next transaction block. For more information about the
@@ -40,21 +40,30 @@ A specific API can be explicitly imported:
 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:
+Use it directly on a webpage with a script module:
+
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/nano-pow@latest/dist/global.min.js"></script>
 <script type="module">
-  console.log(NanoPow)
+	(async () => {
+		const { NanoPow } = await import('https://cdn.jsdelivr.net/npm/nano-pow@latest')
+		const work = await NanoPow.search(some_hash)
+		console.log(work)
+	})()
 </script>
 ```
 
+The global namespace can be polluted by targeting `dist/global.min.js` although
+this is not recommended:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/nano-pow@latest/dist/global.min.js"></script>
+```
+
 ### Search
 ```javascript
 // `hash` is a 64-char hex string
 const hash = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
-// `threshold` is optional and defaults to "0xFFFFFFF8" for send/change blocks
-const work = await NanoPow.search(hash, threshold)
+const work = await NanoPow.search(hash)
 // Result is a 16-char hex string
 ```
 
@@ -64,11 +73,23 @@ const work = await NanoPow.search(hash, threshold)
 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)
+const isValid = await NanoPow.validate(work, hash)
 // Result is a boolean
 ```
 
+### Options
+```javascript
+const options = {
+	// default 0xFFFFFFF8 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)
+```
+
 ## Notes
 The `work` field in a Nano transaction block contains an 8-byte nonce that
 satisfies the following equation:
@@ -78,17 +99,21 @@ satisfies the following equation:
 * 𝘣𝘭𝘢𝘬𝘦2𝘣() is the cryptographic hash function BLAKE2b.
 * 𝘯𝘰𝘯𝘤𝘦, an 8-byte value, is generated for the transaction.
 * || is concatenation.
-* 𝘣𝘭𝘰𝘤𝘬𝘩𝘢𝘴𝘩, a 32-byte value, is either the public key of brand new accounts without transactions or the
-hash of the most recent block in the account chain for all other accounts.
+* 𝘣𝘭𝘰𝘤𝘬𝘩𝘢𝘴𝘩, a 32-byte value, is either the public key of brand new accounts
+without transactions or the hash of the most recent block in the account chain
+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.
+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.
+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.
 
 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
@@ -112,6 +137,13 @@ npm i
 npm run build
 ```
 
+## Acknowledgements
+[numtel/nano-webgl-pow](https://github.com/numtel/nano-webgl-pow) for his WebGL
+implementation
+
+## Licenses
+GPLv3 (or later) & MIT
+
 ## Donations
 If you find this package helpful, please consider tipping the developer.
 ```