From: Chris Duncan <chris@zoso.dev>
Date: Sun, 15 Jun 2025 05:59:28 +0000 (-0700)
Subject: Add section in README explaining effort.
X-Git-Tag: v5.0.0~25
X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=bbadebcde6e83ceacc6db5641bfd07deed12845a;p=nano-pow.git

Add section in README explaining effort.
---

diff --git a/README.md b/README.md
index eed61d0..4b293d7 100644
--- a/README.md
+++ b/README.md
@@ -72,7 +72,7 @@ const { valid } = await NanoPow.work_validate(work, hash)
 const options = {
 	// default best available in order: webgpu => webgl => wasm => cpu
 	api: 'webgpu',
-	// default 0xFFFFFFF800000000 for send/change blocks
+	// default FFFFFFF800000000 for send/change blocks
 	difficulty: 'FFFFFFC000000000',
 	// default 4, valid range 1-32
 	effort: 8,
@@ -82,6 +82,22 @@ const options = {
 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 to
+middling value like 4 or 8.
+* 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.
@@ -193,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