apow-cli 0.3.4 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # APoW CLI
 
-Mining client for the [APoW (Agentic Proof of Work)](https://github.com/Agentoshi/apow-core) protocol on Base. Solve SMHL challenges with any LLM to mine $AGENT tokens.
+Mining client for the [APoW (Agentic Proof of Work)](https://github.com/Agentoshi/apow-core) protocol on Base. Prove your agent identity once by minting an ERC-8004 Mining Rig, then compete on hash power to mine $AGENT tokens.
 
 **Your agent does all the work — you just fund a wallet.**
 
@@ -36,22 +36,23 @@ npx apow-cli wallet new
 # → Captures address + private key from stdout
 
 # 2. Write .env (no interactive prompts)
+#    LLM config is only needed for minting — mining uses optimized SMHL solving
 cat > .env << 'EOF'
 PRIVATE_KEY=0x<from step 1>
 RPC_URL=https://mainnet.base.org  # UNRELIABLE — get a free Alchemy URL (see above)
-LLM_PROVIDER=openai
-LLM_MODEL=gpt-4o-mini
-LLM_API_KEY=<your key>
+LLM_PROVIDER=openai               # Required for minting only
+LLM_MODEL=gpt-4o-mini             # Required for minting only
+LLM_API_KEY=<your key>            # Required for minting only
 EOF
 
 # 3. Fund the wallet (bridge from Solana or send ETH on Base)
 npx apow-cli fund --solana            # bridge SOL → ETH on Base
 # Or ask your user to send ≥0.005 ETH on Base directly
 
-# 4. Mint a mining rig NFT (solves SMHL challenge via LLM)
+# 4. Mint a mining rig NFT (proves agent identity via LLM — one-time)
 npx apow-cli mint
 
-# 5. Start mining (runs forever, auto-detects best rig)
+# 5. Start mining (runs forever, no LLM needed, multi-threaded)
 npx apow-cli mine
 ```
 
@@ -108,9 +109,9 @@ Create a `.env` file or use `apow setup`:
 ```bash
 PRIVATE_KEY=0x...              # Your wallet private key
 RPC_URL=https://mainnet.base.org  # UNRELIABLE — strongly recommend a free Alchemy URL instead (see above)
-LLM_PROVIDER=openai            # openai | anthropic | gemini | ollama | claude-code | codex
-LLM_MODEL=gpt-4o-mini
-LLM_API_KEY=sk-...
+LLM_PROVIDER=openai            # openai | anthropic | gemini | ollama | claude-code | codex (for minting)
+LLM_MODEL=gpt-4o-mini         # Required for minting only — mining uses optimized SMHL solving
+LLM_API_KEY=sk-...             # Required for minting only
 # Solana bridging (only for `apow fund --solana`)
 # SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
 # SQUID_INTEGRATOR_ID=          # free, get at squidrouter.com (deposit address flow only)
@@ -121,7 +122,9 @@ LLM_API_KEY=sk-...
 
 See [.env.example](.env.example) for all options.
 
-## LLM Providers
+## LLM Providers (for Minting)
+
+An LLM is required to mint your Mining Rig NFT (one-time identity verification). Once minted, mining uses optimized algorithmic SMHL solving — no LLM needed.
 
 | Provider | Model | Cost/call | Notes |
 |----------|-------|-----------|-------|
@@ -132,6 +135,13 @@ See [.env.example](.env.example) for all options.
 | Claude Code | `default` | Subscription | No API key needed |
 | Codex | `default` | Subscription | No API key needed |
 
+## Speed Mining (v0.4.0+)
+
+Mining in v0.4.0 uses two key optimizations:
+
+- **Algorithmic SMHL**: Mining SMHL challenges are solved algorithmically in microseconds (no LLM call). Your agent identity was already proven when you minted your ERC-8004 Mining Rig.
+- **Multi-threaded nonce grinding**: Hash computation is parallelized across all CPU cores via `worker_threads`. Set `MINER_THREADS` in `.env` to override the default (all cores).
+
 ## Protocol
 
 The APoW protocol contracts and documentation live in [apow-core](https://github.com/Agentoshi/apow-core).

package/dist/config.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.config = void 0;
 exports.requirePrivateKey = requirePrivateKey;
@@ -7,6 +10,7 @@ exports.isExpensiveModel = isExpensiveModel;
 exports.writeEnvFile = writeEnvFile;
 const dotenv_1 = require("dotenv");
 const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = require("node:path");
 const chains_1 = require("viem/chains");
 (0, dotenv_1.config)();
@@ -83,6 +87,7 @@ exports.config = {
     chainName,
     miningAgentAddress: parseAddress("MINING_AGENT_ADDRESS", DEFAULT_MINING_AGENT_ADDRESS),
     agentCoinAddress: parseAddress("AGENT_COIN_ADDRESS", DEFAULT_AGENT_COIN_ADDRESS),
+    minerThreads: parseInt(process.env.MINER_THREADS ?? String(node_os_1.default.cpus().length), 10),
 };
 function requirePrivateKey() {
     if (!exports.config.privateKey) {

package/dist/grinder.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Multi-threaded nonce grinding via worker_threads.
+ * Spawns N workers that search different nonce ranges in parallel.
+ * First worker to find a valid nonce wins; all others are terminated.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.grindNonceParallel = grindNonceParallel;
+const node_worker_threads_1 = require("node:worker_threads");
+const node_os_1 = __importDefault(require("node:os"));
+const viem_1 = require("viem");
+// ── Worker thread logic ──────────────────────────────────────────────
+if (!node_worker_threads_1.isMainThread && node_worker_threads_1.parentPort) {
+    const params = node_worker_threads_1.workerData;
+    const target = BigInt(params.targetHex);
+    let nonce = BigInt(params.startNonce);
+    let attempts = 0n;
+    const reportInterval = 50000n;
+    while (true) {
+        const digest = BigInt((0, viem_1.keccak256)((0, viem_1.encodePacked)(["bytes32", "address", "uint256"], [params.challengeNumber, params.minerAddress, nonce])));
+        attempts += 1n;
+        if (digest < target) {
+            node_worker_threads_1.parentPort.postMessage({
+                type: "found",
+                nonce: nonce.toString(),
+                attempts: attempts.toString(),
+            });
+            break;
+        }
+        if (attempts % reportInterval === 0n) {
+            node_worker_threads_1.parentPort.postMessage({
+                type: "progress",
+                attempts: attempts.toString(),
+            });
+        }
+        nonce += 1n;
+    }
+}
+// ── Main thread: spawn workers, collect results ──────────────────────
+async function grindNonceParallel(params) {
+    const threadCount = params.threads ?? node_os_1.default.cpus().length;
+    const start = process.hrtime();
+    const workers = [];
+    const workerAttempts = new Map();
+    let totalAttempts = 0n;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        function cleanup() {
+            for (const w of workers) {
+                w.terminate().catch(() => { });
+            }
+        }
+        function elapsed() {
+            const [s, ns] = process.hrtime(start);
+            return s + ns / 1_000_000_000;
+        }
+        for (let i = 0; i < threadCount; i++) {
+            // Each worker starts at a random offset to avoid overlap
+            const startNonce = BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER));
+            const worker = new node_worker_threads_1.Worker(__filename, {
+                workerData: {
+                    challengeNumber: params.challengeNumber,
+                    targetHex: params.target.toString(),
+                    minerAddress: params.minerAddress,
+                    startNonce: startNonce.toString(),
+                },
+            });
+            workerAttempts.set(i, 0n);
+            worker.on("message", (msg) => {
+                if (msg.type === "found" && !settled) {
+                    settled = true;
+                    // Sum all worker attempts
+                    const workerFinalAttempts = BigInt(msg.attempts ?? "0");
+                    workerAttempts.set(i, workerFinalAttempts);
+                    totalAttempts = 0n;
+                    for (const a of workerAttempts.values())
+                        totalAttempts += a;
+                    const e = elapsed();
+                    cleanup();
+                    resolve({
+                        nonce: BigInt(msg.nonce),
+                        attempts: totalAttempts,
+                        hashrate: e > 0 ? Number(totalAttempts) / e : Number(totalAttempts),
+                        elapsed: e,
+                    });
+                }
+                else if (msg.type === "progress") {
+                    const workerProgressAttempts = BigInt(msg.attempts ?? "0");
+                    workerAttempts.set(i, workerProgressAttempts);
+                    totalAttempts = 0n;
+                    for (const a of workerAttempts.values())
+                        totalAttempts += a;
+                    if (params.onProgress) {
+                        const e = elapsed();
+                        const hashrate = e > 0 ? Number(totalAttempts) / e : Number(totalAttempts);
+                        params.onProgress(totalAttempts, hashrate);
+                    }
+                }
+            });
+            worker.on("error", (err) => {
+                if (!settled) {
+                    settled = true;
+                    cleanup();
+                    reject(err);
+                }
+            });
+            workers.push(worker);
+        }
+    });
+}

package/dist/index.js

@@ -192,8 +192,10 @@ async function setupWizard() {
         ui.hint("Continuing anyway — you can fix RPC_URL in .env later");
     }
     console.log("");
-    // Step 3: LLM
-    console.log(`  ${ui.bold("Step 3/3: LLM Provider")}`);
+    // Step 3: LLM (for minting)
+    console.log(`  ${ui.bold("Step 3/3: LLM Provider (for minting)")}`);
+    console.log(`  ${ui.dim("An LLM solves the SMHL challenge when minting your Mining Rig.")}`);
+    console.log(`  ${ui.dim("Mining uses optimized solving — no LLM needed after minting.")}`);
     const providerInput = await ui.prompt("Provider (openai/anthropic/gemini/ollama/deepseek/qwen/claude-code/codex)", "openai");
     const provider = (["openai", "anthropic", "gemini", "ollama", "deepseek", "qwen", "claude-code", "codex"].includes(providerInput) ? providerInput : "openai");
     values.LLM_PROVIDER = provider;
@@ -265,7 +267,7 @@ async function main() {
     });
     program
         .name("apow")
-        .description("Mine AGENT tokens on Base L2 with AI-powered proof of work")
+        .description("Mine AGENT tokens on Base L2 with Agentic Proof of Work")
         .version(version);
     program
         .command("setup")

package/dist/miner.js

@@ -44,6 +44,7 @@ const config_1 = require("./config");
 const detect_1 = require("./detect");
 const errors_1 = require("./errors");
 const explorer_1 = require("./explorer");
+const grinder_1 = require("./grinder");
 const smhl_1 = require("./smhl");
 const ui = __importStar(require("./ui"));
 const wallet_1 = require("./wallet");
@@ -234,19 +235,26 @@ async function startMining(tokenId) {
             }));
             const [challengeNumber, target, rawSmhl] = miningChallenge;
             const smhl = (0, smhl_1.normalizeSmhlChallenge)(rawSmhl);
-            // Solve SMHL with spinner
-            const smhlSpinner = ui.spinner("Solving SMHL challenge...");
+            // Solve SMHL algorithmically (sub-millisecond)
             const smhlStart = process.hrtime();
-            const smhlSolution = await (0, smhl_1.solveSmhlChallenge)(smhl, (attempt) => {
-                smhlSpinner.update(`Solving SMHL challenge... attempt ${attempt}/5`);
-            });
+            const smhlSolution = (0, smhl_1.solveSmhlAlgorithmic)(smhl);
+            const smhlIssues = (0, smhl_1.validateSmhlSolution)(smhlSolution, smhl);
+            if (smhlIssues.length > 0) {
+                throw new Error(`SMHL generation failed: ${smhlIssues.join(", ")}`);
+            }
             const smhlElapsed = elapsedSeconds(smhlStart);
-            smhlSpinner.stop(`Solving SMHL challenge... done (${smhlElapsed.toFixed(1)}s)`);
-            // Grind nonce with spinner
+            console.log(`  ${ui.dim(`SMHL solved (${(smhlElapsed * 1000).toFixed(1)}ms)`)}`);
+            // Grind nonce with multi-threaded spinner
             const nonceSpinner = ui.spinner("Grinding nonce...");
-            const grind = await grindNonce(challengeNumber, target, account.address, (attempts, hashrate) => {
-                const khs = (hashrate / 1000).toFixed(0);
-                nonceSpinner.update(`Grinding nonce... ${khs}k H/s (${attempts.toLocaleString()} attempts)`);
+            const grind = await (0, grinder_1.grindNonceParallel)({
+                challengeNumber,
+                target,
+                minerAddress: account.address,
+                threads: config_1.config.minerThreads,
+                onProgress: (attempts, hashrate) => {
+                    const khs = (hashrate / 1000).toFixed(0);
+                    nonceSpinner.update(`Grinding nonce... ${khs}k H/s (${attempts.toLocaleString()} attempts)`);
+                },
             });
             const khs = (grind.hashrate / 1000).toFixed(0);
             nonceSpinner.stop(`Grinding nonce... done (${grind.elapsed.toFixed(1)}s, ${khs}k H/s)`);

package/dist/preflight.js

@@ -118,22 +118,24 @@ async function runPreflight(level) {
                 });
             }
         }
-        // Check 5: LLM key set
-        if (config_1.config.llmProvider === "ollama") {
-            results.push({ label: `LLM provider: ollama (${config_1.config.ollamaUrl})`, passed: true });
-        }
-        else if (config_1.config.llmProvider === "claude-code" || config_1.config.llmProvider === "codex") {
-            results.push({ label: `LLM provider: ${config_1.config.llmProvider} (local CLI)`, passed: true });
-        }
-        else if (config_1.config.llmApiKey) {
-            results.push({ label: `LLM provider: ${config_1.config.llmProvider} (key set)`, passed: true });
-        }
-        else {
-            results.push({
-                label: `LLM API key not set for ${config_1.config.llmProvider}`,
-                passed: false,
-                fix: "Set LLM_API_KEY (or OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY) in .env, or run `apow setup`",
-            });
+        // Check 5: LLM key set (only required for minting, not mining)
+        if (level === "wallet") {
+            if (config_1.config.llmProvider === "ollama") {
+                results.push({ label: `LLM provider: ollama (${config_1.config.ollamaUrl})`, passed: true });
+            }
+            else if (config_1.config.llmProvider === "claude-code" || config_1.config.llmProvider === "codex") {
+                results.push({ label: `LLM provider: ${config_1.config.llmProvider} (local CLI)`, passed: true });
+            }
+            else if (config_1.config.llmApiKey) {
+                results.push({ label: `LLM provider: ${config_1.config.llmProvider} (key set)`, passed: true });
+            }
+            else {
+                results.push({
+                    label: `LLM API key not set for ${config_1.config.llmProvider}`,
+                    passed: false,
+                    fix: "Set LLM_API_KEY (or OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY) in .env, or run `apow setup`",
+                });
+            }
         }
     }
     // Check 6: Contracts exist on-chain (bytecode check)

package/dist/smhl.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeSmhlChallenge = normalizeSmhlChallenge;
 exports.buildSmhlPrompt = buildSmhlPrompt;
 exports.validateSmhlSolution = validateSmhlSolution;
+exports.solveSmhlAlgorithmic = solveSmhlAlgorithmic;
 exports.solveSmhlChallenge = solveSmhlChallenge;
 const node_child_process_1 = require("node:child_process");
 const openai_1 = __importDefault(require("openai"));
@@ -329,6 +330,34 @@ async function requestProviderSolution(prompt) {
             return requestOpenAiSolution(prompt);
     }
 }
+/**
+ * Solve SMHL challenge algorithmically (no LLM needed).
+ * On-chain _verifySMHL only checks: totalLength ±5, charValue anywhere, wordCount ±2.
+ * Generates a valid solution in microseconds.
+ */
+function solveSmhlAlgorithmic(challenge) {
+    const requiredChar = String.fromCharCode(challenge.charValue);
+    const targetWords = challenge.wordCount;
+    const targetLen = challenge.totalLength;
+    const spaces = targetWords - 1;
+    const letterBudget = targetLen - spaces;
+    if (letterBudget <= 0 || targetWords <= 0) {
+        return requiredChar.repeat(targetLen);
+    }
+    const baseWordLen = Math.floor(letterBudget / targetWords);
+    const extraChars = letterBudget - baseWordLen * targetWords;
+    const words = [];
+    for (let i = 0; i < targetWords; i++) {
+        const len = Math.max(1, baseWordLen + (i < extraChars ? 1 : 0));
+        if (i === 0) {
+            words.push(requiredChar + "a".repeat(len - 1));
+        }
+        else {
+            words.push("a".repeat(len));
+        }
+    }
+    return words.join(" ");
+}
 async function solveSmhlChallenge(challenge, onAttempt) {
     let feedback;
     let lastIssues = "provider did not return a valid response";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apow-cli",
-  "version": "0.3.4",
-  "description": "Mine AGENT tokens on Base L2 with AI-powered proof of work",
+  "version": "0.4.0",
+  "description": "Mine AGENT tokens on Base L2 with Agentic Proof of Work",
   "keywords": [
     "apow",
     "agentcoin",

package/skill.md

@@ -65,15 +65,15 @@ npx apow-cli wallet new
 # Captures address + private key from output (also saved to wallet-<address>.txt)
 
 # 2. Write .env directly (no interactive prompts needed)
-#    IMPORTANT: Use an API-based provider (openai/anthropic/gemini/deepseek/qwen), NOT claude-code/codex.
-#    Session-based providers are too slow for the 20-second mint challenge window.
+#    LLM config is only needed for minting (one-time) — mining uses algorithmic SMHL.
+#    IMPORTANT: Use an API-based provider for minting (openai/anthropic/gemini/deepseek/qwen).
 #    IMPORTANT: The public Base RPC is unreliable — get a free Alchemy URL (see RPC Recommendations).
 cat > .env << 'EOF'
 PRIVATE_KEY=0x<from step 1>
 RPC_URL=https://mainnet.base.org
-LLM_PROVIDER=openai
-LLM_MODEL=gpt-4o-mini
-LLM_API_KEY=<your key>
+LLM_PROVIDER=openai               # Required for minting only
+LLM_MODEL=gpt-4o-mini             # Required for minting only
+LLM_API_KEY=<your key>            # Required for minting only
 MINING_AGENT_ADDRESS=0xB7caD3ca5F2BD8aEC2Eb67d6E8D448099B3bC03D
 AGENT_COIN_ADDRESS=0x12577CF0D8a07363224D6909c54C056A183e13b3
 EOF
@@ -92,19 +92,22 @@ npx apow-cli mine
 
 ## 1. What is APoW?
 
-Agent Proof-of-Work (APoW) is a mining protocol where AI agents solve constrained string-generation challenges called SMHL ("Show Me Human Language") to mine AGENT tokens on the Base L2 network. Mining requires owning a Miner NFT (ERC-721 with rarity-based hashpower) and access to an LLM that can solve the SMHL constraints. Rewards start at 3 AGENT per mine (scaled by hashpower) and decay by 10% every 500,000 total network mines, with a hard cap of 21,000,000 AGENT.
+Agent Proof-of-Work (APoW) is a mining protocol on Base L2 where AI agents prove their identity once by minting an ERC-8004 Mining Rig NFT (requires LLM to solve an SMHL challenge), then compete on hash power to mine AGENT tokens. Mining requires owning a Miner NFT (ERC-721 with rarity-based hashpower) — no LLM needed after minting. Rewards start at 3 AGENT per mine (scaled by hashpower) and decay by 10% every 500,000 total network mines, with a hard cap of 21,000,000 AGENT.
 
 ### SMHL Challenge Format
 
-Your LLM receives a prompt like: "Generate a sentence that is approximately N characters long, contains approximately W words, and includes the letter 'X'."
+SMHL ("Show Me Human Language") serves two different roles in APoW:
+
+**SMHL for Minting (identity verification):** When minting a Mining Rig, your LLM solves an SMHL challenge to prove agent capability. This is the "prove yourself" gate — your agent demonstrates it can solve constrained text generation. The LLM receives a prompt like: "Generate a sentence that is approximately N characters long, contains approximately W words, and includes the letter 'X'."
 
-On-chain verification checks:
+**SMHL for Mining (algorithmic):** During mining, SMHL solutions are generated algorithmically in microseconds — no LLM needed. Your agent identity was already established when you minted your ERC-8004 Mining Rig. Mining is a hash power competition, not a language puzzle.
+
+On-chain verification checks (both minting and mining):
 1. **Length** (in bytes): within ±5 of the target
 2. **Word count**: within ±2 of the target
 3. **Character presence**: the specified letter appears at least once
-4. **ASCII only** (client-side convention): all characters should be printable ASCII (bytes 32-126). Note: this is NOT enforced on-chain — the contract's `_verifySMHL` does not check for ASCII-only characters. The miner client validates this locally to improve reliability.
 
-The miner client validates locally before submitting. If validation fails, it retries (up to 3 attempts).
+The miner client validates locally before submitting.
 
 ---
 
@@ -114,7 +117,7 @@ The miner client validates locally before submitting. If validation fails, it re
 |---|---|
 | **Node.js** | v18 or higher |
 | **Base wallet** | A private key with ETH on Base (for gas + mint fee) |
-| **LLM access** | API key (OpenAI, Anthropic, Gemini, DeepSeek, Qwen), local Ollama, or Claude Code / Codex CLI |
+| **LLM access** | API key (OpenAI, Anthropic, Gemini, DeepSeek, Qwen), local Ollama, or Claude Code / Codex CLI — **required for minting only** |
 | **git** | Only if installing from source (not needed for npm) |
 
 ---
@@ -242,7 +245,7 @@ PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE
 MINING_AGENT_ADDRESS=0xB7caD3ca5F2BD8aEC2Eb67d6E8D448099B3bC03D
 AGENT_COIN_ADDRESS=0x12577CF0D8a07363224D6909c54C056A183e13b3
 
-# === LLM Configuration ===
+# === LLM Configuration (required for minting only — mining uses optimized solving) ===
 
 # Provider: "openai" | "anthropic" | "ollama" | "gemini" | "deepseek" | "qwen" | "claude-code" | "codex"
 LLM_PROVIDER=openai
@@ -270,17 +273,20 @@ CHAIN=base
 | `PRIVATE_KEY` | Yes | -- | Wallet private key (0x + 64 hex chars) |
 | `MINING_AGENT_ADDRESS` | Yes | -- | Deployed MiningAgent contract address |
 | `AGENT_COIN_ADDRESS` | Yes | -- | Deployed AgentCoin contract address |
-| `LLM_PROVIDER` | No | `openai` | LLM provider: `openai`, `anthropic`, `ollama`, `gemini`, `deepseek`, `qwen`, `claude-code`, or `codex` |
-| `LLM_API_KEY` | Conditional | -- | API key. Falls back to `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `DEEPSEEK_API_KEY` / `DASHSCOPE_API_KEY` per provider. Not needed for `ollama`, `claude-code`, or `codex` |
-| `LLM_MODEL` | No | `gpt-4o-mini` | Model identifier passed to the provider |
+| `LLM_PROVIDER` | For minting | `openai` | LLM provider for minting: `openai`, `anthropic`, `ollama`, `gemini`, `deepseek`, `qwen`, `claude-code`, or `codex`. Not needed for mining. |
+| `LLM_API_KEY` | For minting | -- | API key for minting. Falls back to `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `DEEPSEEK_API_KEY` / `DASHSCOPE_API_KEY` per provider. Not needed for `ollama`, `claude-code`, `codex`, or mining. |
+| `LLM_MODEL` | For minting | `gpt-4o-mini` | Model identifier passed to the provider (minting only) |
+| `MINER_THREADS` | No | All CPU cores | Number of threads for parallel nonce grinding |
 | `RPC_URL` | **Strongly recommended** | `https://mainnet.base.org` | Base JSON-RPC endpoint. **The default public RPC is unreliable — use Alchemy (free) or another dedicated provider.** |
 | `CHAIN` | No | `base` | Network selector; auto-detects `baseSepolia` if RPC URL contains "sepolia" |
 | `SOLANA_RPC_URL` | No | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint (only for `apow fund --solana`) |
 | `SQUID_INTEGRATOR_ID` | No | -- | Squid Router integrator ID for deposit address flow (free at [squidrouter.com](https://app.squidrouter.com/)) |
 
-### LLM Provider Recommendations
+### LLM Provider Recommendations (for Minting)
 
-> **For AI agents:** Always use an API-based provider (OpenAI, Anthropic, Gemini, DeepSeek, or Qwen). Session-based providers (`claude-code`, `codex`) spawn a CLI subprocess to solve challenges and are too slow to reliably complete the 20-second mint window. They may work for mining (which has no time limit) but will frequently fail during minting.
+> An LLM is only needed for **minting** your Mining Rig NFT (one-time identity verification). Mining uses optimized algorithmic SMHL solving — no LLM needed.
+>
+> **For AI agents:** Use an API-based provider (OpenAI, Anthropic, Gemini, DeepSeek, or Qwen) for minting. Session-based providers (`claude-code`, `codex`) spawn a CLI subprocess and are too slow to reliably complete the 20-second mint window.
 
 | Provider | Model | Cost per call | Notes |
 |---|---|---|---|
@@ -400,9 +406,9 @@ npx apow-cli mine <tokenId> # or specify a rig by token ID
 3. **Fetch challenge** -- reads `getMiningChallenge()` from the AgentCoin contract, which returns:
    - `challengeNumber` (bytes32) -- the current PoW challenge hash
    - `miningTarget` (uint256) -- the difficulty target
-   - `smhl` -- the SMHL string-generation challenge
-4. **Solve SMHL** -- sends the SMHL constraints to your LLM. The client retries up to 3 times with local validation before submission.
-5. **Grind nonce** -- brute-force searches for a `nonce` where `keccak256(challengeNumber, minerAddress, nonce) < miningTarget`.
+   - `smhl` -- the SMHL format challenge
+4. **Solve SMHL** -- generates a valid SMHL solution algorithmically (sub-millisecond, no LLM needed).
+5. **Grind nonce** -- multi-threaded brute-force search for a `nonce` where `keccak256(challengeNumber, minerAddress, nonce) < miningTarget`. Uses all CPU cores by default.
 6. **Submit proof** -- calls `mine(nonce, smhlSolution, tokenId)` on AgentCoin. The contract verifies both the hash and SMHL solution on-chain.
 7. **Collect reward** -- AGENT tokens are minted directly to your wallet.
 8. **Wait for next block** -- the protocol enforces one mine per block network-wide. The client waits for block advancement before the next cycle.
@@ -434,8 +440,8 @@ A Mythic miner (5.00x) earns 15.00 AGENT per mine in Era 0.
 ### Cost Per Mine
 
 - **Gas:** ~0.001 ETH per `mine()` transaction on Base
-- **LLM:** varies by provider ($0.001--$0.005 per SMHL solve)
-- **Total:** ~$0.005--$0.02 per mining cycle at typical gas prices
+- **LLM:** $0 (mining uses algorithmic SMHL — no LLM calls)
+- **Total:** ~$0.003--$0.005 per mining cycle (gas only)
 
 ### Error Handling