feat: harden wallet backups and mining flow

Author: Agentoshi

README.md

@@ -83,16 +83,16 @@ If you want to control each step manually, the older `setup -> fund -> mint -> m
 | `apow start` | Guided happy path: setup -> fund -> mint -> mine |
 | `apow setup` | Agent-first setup wizard: Easy Mode (x402 everywhere) or Advanced Mode |
 | `apow fund` | Fund your wallet: bridge from Solana/Ethereum or send on Base, auto-split ETH+USDC |
-| `apow wallet new` | Generate a new mining wallet |
+| `apow wallet new` | Generate a new mining wallet, plus optional encrypted JSON keystore backup |
 | `apow wallet show` | Show configured wallet address |
-| `apow wallet export` | Export your wallet's private key |
+| `apow wallet export` | Export your wallet's private key and optional backups |
 | `apow wallet fund <addr> [eth]` | Send ETH to another address (default: mint price + gas) |
 | `apow mint` | Mint a MiningAgent NFT (one per wallet) |
 | `apow mine [tokenId]` | Mine $AGENT with your NFT (auto-detects best rig) |
 | `apow stats [tokenId]` | View mining stats, earnings, difficulty |
 | `apow dashboard start` | Launch multi-wallet mining dashboard |
 | `apow dashboard add <addr>` | Add a wallet to the dashboard |
-| `apow dashboard scan [dir]` | Auto-detect wallet files in a directory |
+| `apow dashboard scan [dir]` | Auto-detect `wallet-0x*.txt` and `wallet-0x*.json` files in a directory |
 
 ## Configuration
 
@@ -107,6 +107,7 @@ ALLOW_LOCAL_FALLBACK_WITH_X402=false  # Easy Mode default: do not burn local CPU
 # LLM_PROVIDER=clawrouter     # clawrouter (auto with x402) | openai | gemini | deepseek | qwen | anthropic | ollama (for minting)
 # LLM_MODEL=blockrun/eco      # Auto-detected per provider; override only if needed
 # LLM_API_KEY=sk-...          # Not needed with clawrouter/ollama; required for openai/gemini/etc.
+# KEYSTORE_PASSWORD=...       # Optional: create encrypted wallet JSON backups during wallet new/export
 # Bridging (only for `apow fund`)
 # SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
 # ETHEREUM_RPC_URL=https://cloudflare-eth.com
@@ -219,7 +220,7 @@ Monitor your entire mining fleet from a single web UI. Zero external dependencie
 
 ```bash
 # Quick start: scan wallet files and launch
-apow dashboard scan .          # detect wallet-0x*.txt files in current directory
+apow dashboard scan .          # detect wallet-0x*.txt / .json files in current directory
 apow dashboard start           # open dashboard at http://localhost:3847
 ```
 
@@ -230,7 +231,7 @@ apow dashboard start           # open dashboard at http://localhost:3847
 | `apow dashboard start` | Launch dashboard web UI (default port 3847) |
 | `apow dashboard add <addr>` | Add a wallet address to monitor |
 | `apow dashboard remove <addr>` | Remove a wallet from monitoring |
-| `apow dashboard scan [dir]` | Auto-detect wallets from `wallet-0x*.txt` files |
+| `apow dashboard scan [dir]` | Auto-detect wallets from `wallet-0x*.txt` and `wallet-0x*.json` files |
 | `apow dashboard wallets` | List all monitored wallets |
 
 ### Fleet Configuration
@@ -245,7 +246,7 @@ Wallets are stored in `~/.apow/wallets.json` (plain JSON array of addresses). Fo
 ]
 ```
 
-Fleet types: `array` (JSON array of addresses), `solkek` (master/miners JSON), `rigdirs` (scan `rig*/wallet-0x*.txt`), `walletfiles` (scan `wallet-0x*.txt`).
+Fleet types: `array` (JSON array of addresses), `solkek` (master/miners JSON), `rigdirs` (scan `rig*/wallet-0x*.txt` / `.json`), `walletfiles` (scan `wallet-0x*.txt` / `.json`).
 
 ## Protocol
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "apow-cli",
-  "version": "0.11.5",
+  "version": "0.11.6",
   "description": "Mine AGENT tokens on Base L2 with Agentic Proof of Work",
   "keywords": [
     "apow",

skill.md

@@ -134,15 +134,15 @@ Or generate one directly (useful for agents, no prompts):
 npx apow-cli wallet new
 ```
 
-This outputs a private key (0x + 64 hex chars) and Base address, and saves a `wallet-<address>.txt` file to the current directory. The private key goes in your `.env` as `PRIVATE_KEY`.
+This outputs a private key (0x + 64 hex chars) and Base address, saves a plaintext `wallet-<address>.txt` import helper to the current directory, and can also create an encrypted `wallet-<address>.json` keystore under `~/.apow/keystores/` when a password is available. The private key goes in your `.env` as `PRIVATE_KEY`.
 
 **Exporting an existing wallet:** If you've already set up a wallet and need to retrieve the key:
 
 ```bash
 npx apow-cli wallet export
 ```
 
-This prompts for confirmation, then displays your address and private key. It also offers to save a `wallet-<address>.txt` file if one doesn't already exist.
+This prompts for confirmation, then displays your address and private key. It can save a plaintext `wallet-<address>.txt` import helper and/or an encrypted JSON keystore backup.
 
 **Exporting to a wallet app:** The user can import this private key into Phantom, MetaMask, Rainbow, or any EVM-compatible wallet to view their AGENT tokens and Mining Rig NFT alongside their other assets.
 
@@ -263,6 +263,7 @@ CHAIN=base
 | Variable | Required | Default | Description |
 |---|---|---|---|
 | `PRIVATE_KEY` | Yes | - | Wallet private key (0x + 64 hex chars) |
+| `KEYSTORE_PASSWORD` | No | unset | If set, `wallet new`/`wallet export` also create an encrypted JSON keystore backup under `~/.apow/keystores/` |
 | `MINING_AGENT_ADDRESS` | Yes | - | Deployed MiningAgent contract address |
 | `AGENT_COIN_ADDRESS` | Yes | - | Deployed AgentCoin contract address |
 | `LLM_PROVIDER` | For minting | `clawrouter` if `USE_X402=true`, else `openai` | LLM provider for minting: `clawrouter` (recommended, zero credentials), `openai`, `gemini`, `deepseek`, `qwen`, `anthropic`, `ollama`, `claude-code`, `codex`. Not needed for mining. |
@@ -650,7 +651,7 @@ This section addresses the security model of apow-cli head-on. Every claim below
 
 ### 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).
+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 the CLI can create both a plaintext `wallet-<address>.txt` import helper and a password-protected JSON keystore (`Web3 Secret Storage v3`) with file permissions `0o600`.
 
 ### Private Key Is NEVER Transmitted
 
@@ -698,7 +699,7 @@ The SMHL solver sends only generic word-generation prompts to the LLM (e.g., "Wr
 
 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`).
+3. **Prefer encrypted keystore backups** in `~/.apow/keystores/wallet-<address>.json`. The plaintext `wallet-<address>.txt` helper is convenient for importing into wallet UIs, but it is less secure.
 4. **Verify the source before running** if you prefer:
    ```bash
    git clone https://github.com/Agentoshi/apow-cli
@@ -769,7 +770,7 @@ The `apow dashboard` command group provides a real-time web UI for monitoring yo
 | `apow dashboard start` | Launch the dashboard web UI at `http://localhost:3847`. Auto-opens browser. Press Ctrl+C to stop. |
 | `apow dashboard add <address>` | Add a wallet address to monitor. Validates 0x + 40 hex chars. |
 | `apow dashboard remove <address>` | Remove a wallet address from monitoring. |
-| `apow dashboard scan [dir]` | Auto-detect wallets from `wallet-0x*.txt` files in the given directory (default: CWD). Also scans `rig*/` subdirectories. |
+| `apow dashboard scan [dir]` | Auto-detect wallets from `wallet-0x*.txt` and `wallet-0x*.json` files in the given directory (default: CWD). Also scans `rig*/` subdirectories. |
 | `apow dashboard wallets` | List all currently monitored wallet addresses. |
 
 ### How It Works
@@ -779,7 +780,7 @@ The `apow dashboard` command group provides a real-time web UI for monitoring yo
 - **Data fetching:** Chunked RPC multicalls (max 30 per batch) with a 25-second TTL cache. Queries ETH balance, AGENT balance, rig ownership, rarity, hashpower, mine count, and earnings for every wallet.
 - **NFT art:** Renders on-chain SVG art for each Mining Rig with rarity-based color coding.
 - **Auto-seed:** On first run, seeds `wallets.json` with the address from your `.env` if configured.
-- **Auto-detect:** `dashboard start` automatically scans CWD for `wallet-0x*.txt` files before launching.
+- **Auto-detect:** `dashboard start` automatically scans CWD for `wallet-0x*.txt` and `wallet-0x*.json` files before launching.
 
 ### Fleet Configuration (`~/.apow/fleets.json`)
 
@@ -800,8 +801,8 @@ For managing wallets across multiple machines or directories, create `~/.apow/fl
 |------|--------------|-------------|
 | `array` | JSON array of addresses | Simple list: `["0xABC...", "0xDEF..."]` |
 | `solkek` | JSON with `master.address` + `miners[].address` | Solkek fleet manager format |
-| `rigdirs` | Directory containing `rig*/wallet-0x*.txt` | Scan rig subdirectories for wallet files |
-| `walletfiles` | Directory containing `wallet-0x*.txt` | Scan flat directory for wallet files |
+| `rigdirs` | Directory containing `rig*/wallet-0x*.txt` or `.json` | Scan rig subdirectories for wallet files |
+| `walletfiles` | Directory containing `wallet-0x*.txt` or `.json` | Scan flat directory for wallet files |
 
 If `fleets.json` does not exist, the dashboard falls back to `wallets.json` as a single "Main" fleet.
 

src/config.ts

@@ -1,5 +1,6 @@
 import { config as loadEnv } from "dotenv";
-import { writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import { join } from "node:path";
 import type { Address, Chain, Hex } from "viem";
@@ -203,10 +204,34 @@ export function isExpensiveModel(model: string): boolean {
 }
 
 export async function writeEnvFile(values: Record<string, string>): Promise<void> {
-  const lines = Object.entries(values)
-    .map(([key, value]) => `${key}=${value}`)
-    .join("\n");
-  await writeFile(join(process.cwd(), ".env"), lines + "\n", "utf8");
+  const envPath = join(process.cwd(), ".env");
+  const preserved: string[] = [];
+
+  if (existsSync(envPath)) {
+    const existingContent = await readFile(envPath, "utf8").catch(() => "");
+    const seenKeys = new Set(Object.keys(values));
+    for (const line of existingContent.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) {
+        continue;
+      }
+      const eq = line.indexOf("=");
+      if (eq === -1) {
+        preserved.push(line);
+        continue;
+      }
+      const key = line.slice(0, eq).trim();
+      if (!seenKeys.has(key)) {
+        preserved.push(line);
+      }
+    }
+  }
+
+  const lines = [
+    ...preserved,
+    ...Object.entries(values).map(([key, value]) => `${key}=${value}`),
+  ].join("\n");
+  await writeFile(envPath, lines + "\n", "utf8");
   for (const [key, value] of Object.entries(values)) {
     process.env[key] = value;
   }

src/dashboard.ts

@@ -5,6 +5,7 @@ import { createPublicClient, formatEther, http as viemHttp, type Abi, type Addre
 import { base } from "viem/chains";
 import { getDashboardHtml } from "./dashboard-html";
 import { createX402Transport } from "./x402";
+import { detectWalletAddressFromFilename } from "./wallet-store";
 
 import AgentCoinAbiJson from "./abi/AgentCoin.json";
 import MiningAgentAbiJson from "./abi/MiningAgent.json";
@@ -96,9 +97,9 @@ function extractRigdirs(dir: string): Address[] {
     if (!entry.isDirectory() || !entry.name.startsWith("rig")) continue;
     const rigFiles = readdirSync(join(dir, entry.name));
     for (const file of rigFiles) {
-      const match = file.match(/^wallet-(0x[0-9a-fA-F]{40})\.txt$/);
-      if (match && isAddress(match[1])) {
-        addrs.push(match[1] as Address);
+      const address = detectWalletAddressFromFilename(file);
+      if (address && isAddress(address)) {
+        addrs.push(address as Address);
       }
     }
   }
@@ -109,9 +110,9 @@ function extractWalletfiles(dir: string): Address[] {
   const addrs: Address[] = [];
   const files = readdirSync(dir);
   for (const file of files) {
-    const match = file.match(/^wallet-(0x[0-9a-fA-F]{40})\.txt$/);
-    if (match && isAddress(match[1])) {
-      addrs.push(match[1] as Address);
+    const address = detectWalletAddressFromFilename(file);
+    if (address && isAddress(address)) {
+      addrs.push(address as Address);
     }
   }
   return addrs;

src/detect.ts

@@ -26,16 +26,17 @@ export async function detectMinersWithClient(client: PublicClient, owner: Addres
     return [];
   }
 
-  const miners: OwnedMiner[] = [];
-
-  for (let i = 0n; i < balance; i++) {
-    const tokenId = (await client.readContract({
+  const indexes = Array.from({ length: Number(balance) }, (_, i) => BigInt(i));
+  const tokenIds = await Promise.all(indexes.map((index) =>
+    client.readContract({
       address: config.miningAgentAddress,
       abi: miningAgentAbi,
       functionName: "tokenOfOwnerByIndex",
-      args: [owner, i],
-    })) as bigint;
+      args: [owner, index],
+    }) as Promise<bigint>,
+  ));
 
+  const miners = await Promise.all(tokenIds.map(async (tokenId) => {
     const [rarityRaw, hashpowerRaw] = await Promise.all([
       client.readContract({
         address: config.miningAgentAddress,
@@ -52,13 +53,13 @@ export async function detectMinersWithClient(client: PublicClient, owner: Addres
     ]);
 
     const rarity = Number(rarityRaw);
-    miners.push({
+    return {
       tokenId,
       rarity,
       rarityLabel: rarityLabels[rarity] ?? `Tier ${rarity}`,
       hashpower: Number(hashpowerRaw),
-    });
-  }
+    };
+  }));
 
   return miners;
 }

src/errors.ts

@@ -118,11 +118,11 @@ const patterns: Array<{
     }),
   },
   {
-    test: (m) => m.toLowerCase().includes("insufficient funds"),
+    test: (m) => m.includes("Not enough ETH for gas") || m.toLowerCase().includes("insufficient funds"),
     classify: () => ({
       category: "setup",
       userMessage: "Not enough ETH for gas",
-      recovery: "Send ETH to your wallet on Base",
+      recovery: "Send ETH to your wallet on Base, or run `apow fund` to top up gas before mining again",
     }),
   },
   {

src/fund.ts

@@ -593,6 +593,10 @@ export async function runFundFlow(options: FundOptions): Promise<void> {
     console.log(`  Next: ${ui.cyan("apow mint")}`);
     console.log("");
 
+    if (!ui.isInteractiveSession()) {
+      return;
+    }
+
     // Allow explicit re-run if user wants to add more
     const addMore = await ui.confirm("Add more funds?");
     if (!addMore) return;