apow-cli 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apow-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Mine AGENT tokens on Base L2 with AI-powered proof of work",
   "keywords": [
     "apow",

package/skill.md

@@ -53,6 +53,8 @@ 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), NOT claude-code/codex.
+#    Session-based providers are too slow for the 20-second mint challenge window.
 cat > .env << 'EOF'
 PRIVATE_KEY=0x<from step 1>
 RPC_URL=https://mainnet.base.org
@@ -237,15 +239,17 @@ CHAIN=base
 
 ### LLM Provider Recommendations
 
+> **For AI agents:** Always use an API-based provider (OpenAI, Anthropic, or Gemini). 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.
+
 | Provider | Model | Cost per call | Notes |
 |---|---|---|---|
-| OpenAI | `gpt-4o-mini` | ~$0.001 | Cheapest cloud option |
-| OpenAI | `gpt-4o` | ~$0.005 | Default; good reliability |
+| OpenAI | `gpt-4o-mini` | ~$0.001 | **Recommended for agents.** Cheapest, fastest, reliable |
+| Gemini | `gemini-2.5-flash` | ~$0.001 | Fast, good accuracy |
 | Anthropic | `claude-sonnet-4-5-20250929` | ~$0.005 | High accuracy on constrained generation |
+| OpenAI | `gpt-4o` | ~$0.005 | Higher quality, slightly slower |
 | Ollama | `llama3.1` | Free (local) | Requires local GPU; variable accuracy |
-| Gemini | `gemini-2.5-flash` | ~$0.001 | Fast, good accuracy |
-| Claude Code | `default` | Subscription | Use your existing Claude Code session — no API key needed |
-| Codex | `default` | Subscription | Use your existing Codex session — no API key needed |
+| Claude Code | `default` | Subscription | **Not recommended for minting** — CLI startup too slow for 20s window |
+| Codex | `default` | Subscription | **Not recommended for minting** — CLI startup too slow for 20s window |
 
 ### RPC Recommendations
 
@@ -272,7 +276,7 @@ npx apow-cli mint
 5. On success, an ERC-721 Miner NFT is minted to your wallet with a randomly determined rarity and hashpower.
 6. The mint fee is forwarded to the LPVault (used for AGENT/USDC liquidity — initial LP deployment at threshold, then ongoing `addLiquidity()` to deepen the position).
 
-**Challenge expiry:** 20 seconds from `getChallenge` to `mint`. The LLM must solve quickly.
+**Challenge expiry:** 20 seconds from `getChallenge` to `mint`. The LLM must solve quickly. Use an API-based provider (openai/anthropic/gemini) — session-based providers (claude-code/codex) are too slow and will fail.
 
 ### Mint Price
 
@@ -479,7 +483,7 @@ LLM_PROVIDER=codex
 - The CLI must be available in your PATH
 - Your subscription must be active
 
-**Trade-off:** Session-based solving may be slightly slower than direct API calls due to CLI startup overhead, but eliminates the need for separate API keys and billing. The 15-second timeout ensures challenges are still submitted within the contract's 20-second window.
+**Warning:** Session-based providers (`claude-code`, `codex`) spawn a CLI subprocess for each SMHL challenge. The startup overhead frequently exceeds the 20-second mint challenge window, causing mints to fail with `Expired`. **For minting, always use an API-based provider** (openai, anthropic, or gemini). Session providers may work for the mining loop (which has no time limit per challenge) but are unreliable and not recommended for autonomous operation.
 
 ### Custom RPC Endpoints
 
@@ -522,7 +526,7 @@ Use the corresponding testnet contract addresses.
 | `LLM_API_KEY is required for openai.` | Missing API key for cloud provider | Set `LLM_API_KEY` (or provider-specific key like `OPENAI_API_KEY`) in `.env`, or switch to `ollama` |
 | `Insufficient fee` | Not enough ETH sent with mint | Check `getMintPrice()` and ensure wallet has enough ETH |
 | `Sold out` | All 10,000 Miner NFTs minted | No more rigs available; buy one on secondary market |
-| `Expired` | SMHL challenge expired (>20s) | Your LLM is too slow; use a faster model or provider |
+| `Expired` | SMHL challenge expired (>20s) | Switch to an API-based provider (openai/gemini/anthropic). Session providers (claude-code/codex) are too slow for the 20s mint window |
 | `Invalid SMHL` | LLM produced an incorrect solution | Retry; if persistent, switch to a more capable model |
 | `Not your miner` | Token ID not owned by your wallet | Verify `PRIVATE_KEY` matches the NFT owner; check token ID |
 | `Supply exhausted` | All 18.9M mineable AGENT has been minted | Mining is complete; no more rewards available |
@@ -541,7 +545,91 @@ Use the corresponding testnet contract addresses.
 
 ---
 
-## 12. Contract Addresses
+## 12. Security & Trust
+
+This section addresses the security model of apow-cli head-on. Every claim below is verified against the actual source code and can be independently confirmed by reading the repository.
+
+### Private Key Generation -- Local Only
+
+Keys are generated via `viem/accounts` `generatePrivateKey()`, which uses Node.js `crypto.randomBytes(32)` -- a cryptographically secure random number generator. Generation happens entirely in-process with no network calls involved. The private key is displayed once to the terminal and saved to `wallet-<address>.txt` with file permissions `0o600` (owner-read-write only).
+
+### Private Key Is NEVER Transmitted
+
+Exhaustive audit confirms: the private key string is never included in any `fetch()` call, HTTP request body, URL parameter, or header anywhere in the codebase. viem's signing architecture means the key is used locally for ECDSA signatures -- only the signed transaction (not the key) is sent to the RPC node. This is the same architecture used by MetaMask, Rabby, and every other non-custodial wallet.
+
+### Zero Telemetry
+
+The CLI contains no analytics, no error reporting, and no phone-home behavior of any kind:
+
+- No analytics SDKs (no Mixpanel, no PostHog, no Google Analytics)
+- No error reporting services (no Sentry, no Bugsnag)
+- No tracking pixels, no usage metrics, no telemetry endpoints
+
+The CLI makes exactly two types of network calls:
+
+1. **Blockchain RPC** (to user-configured RPC URL, default: `mainnet.base.org`) -- standard `eth_call`, `eth_sendRawTransaction`, etc.
+2. **LLM API** (to user-configured provider) -- sends only word-puzzle prompts for SMHL solving, never wallet data
+
+Nothing else. No other outbound connections.
+
+### LLM Calls Are Data-Isolated
+
+The SMHL solver sends only generic word-generation prompts to the LLM (e.g., "Write exactly 5 lowercase English words..."). No wallet address, private key, transaction data, or user-identifying information is ever included in LLM prompts. The string `privateKey` does not appear anywhere in `smhl.ts`.
+
+### Open Source & Auditable
+
+- Full source code: [github.com/Agentoshi/apow-cli](https://github.com/Agentoshi/apow-cli)
+- MIT licensed
+- Every line is auditable -- there are no obfuscated modules, no binary blobs, no minified dependencies performing network calls
+- Smart contracts are separately auditable: [github.com/Agentoshi/apow-core](https://github.com/Agentoshi/apow-core)
+
+### npm Package Integrity
+
+- Published as `apow-cli` on npm
+- Package contents match the GitHub source -- verify with `npm pack --dry-run` or compare against the repo
+- No `postinstall` scripts that execute arbitrary code
+- The `package.json` `scripts` section contains only standard build/dev commands
+
+### Best Practices for Users
+
+1. **Use a fresh wallet.** Generate one with `npx apow-cli wallet new`. Do not import your main wallet or any wallet holding significant funds.
+2. **Fund with only what you need.** ~0.005 ETH covers minting + several mining cycles.
+3. **Wallet backups are created automatically** at `wallet-<address>.txt` with restricted file permissions (`0o600`).
+4. **Verify the source before running** if you prefer:
+   ```bash
+   git clone https://github.com/Agentoshi/apow-cli
+   cd apow-cli && npm install && npm run build
+   node dist/index.js setup
+   ```
+5. **Review dependencies.** The dependency tree is minimal and standard: `viem` (Ethereum library), `commander` (CLI framework), `dotenv` (env loading), `chalk`/`ora` (terminal UI), and an LLM client. No exotic or suspicious packages.
+
+### How to Verify These Claims Yourself
+
+Every statement above can be independently verified:
+
+```bash
+# Clone the source
+git clone https://github.com/Agentoshi/apow-cli && cd apow-cli
+
+# Search for any outbound network calls -- you'll find only RPC and LLM calls
+grep -r "fetch\|axios\|http\|request" src/
+
+# Confirm private key is never in any network payload
+grep -r "privateKey" src/  # only appears in local wallet operations, never in fetch/request calls
+
+# Check for telemetry/analytics packages
+grep -r "mixpanel\|posthog\|sentry\|bugsnag\|analytics\|telemetry" src/ package.json
+
+# Verify wallet file permissions
+grep -r "0o600\|0600" src/  # wallet files are created with owner-only permissions
+
+# Check postinstall scripts
+cat package.json | grep -A5 "scripts"  # no postinstall hook
+```
+
+---
+
+## 13. Contract Addresses
 
 | Contract | Address |
 |---|---|