@darksol/terminal 0.11.0 → 0.13.0

package/AUDIT-2026-03-14.md

@@ -0,0 +1,241 @@
+# @darksol/terminal — Full Audit Report
+**Version:** 0.12.0 | **Test run:** 130 pass / 0 fail | **Files reviewed:** 47
+**Date:** 2026-03-14
+
+---
+
+## 1. Architecture Overview
+
+**Entry point:** `bin/darksol.js` → `src/cli.js` (Commander.js, ESM, Node ≥18)
+
+```
+src/
+├── cli.js              ← 1500+ line monolith; all commands wired here
+├── agent/              ← LLM tool-calling loop (OpenAI/Anthropic function-calling)
+│   ├── index.js, loop.js, autonomous.js, strategy-evaluator.js, tools.js
+├── config/
+│   ├── store.js        ← conf-backed typed config
+│   └── keys.js         ← AES-256-GCM encrypted API key vault
+├── daemon/             ← generic service registry (start/stop/status/PID)
+├── llm/
+│   ├── engine.js       ← multi-provider (OpenAI/Anthropic/OpenRouter/Ollama)
+│   ├── intent.js       ← NL → structured intent parser
+│   └── models.js       ← model catalog + capability metadata
+├── memory/index.js     ← JSON append-log memory
+├── scripts/engine.js   ← user script CRUD + new Function() executor
+├── services/           ← 14 service modules (casino, oracle, cards, facilitator,
+│                         gas, lifi, market, mail, builders, telegram, watch,
+│                         whale, whale-monitor, skills, browser)
+├── soul/index.js       ← agent personality/tone
+├── trading/            ← swap.js, snipe.js, dca.js
+├── ui/                 ← chalk, ora, cli-table3 wrappers
+├── utils/              ← fetch.js, helpers.js, x402.js
+├── wallet/             ← keystore, manager, agent-signer, portfolio, history
+└── web/                ← embedded web terminal (http.createServer)
+```
+
+**Dep graph:** cli.js imports from virtually every layer. Services are leaf nodes. x402.js is depended on by poker, oracle, casino. whale-monitor.js has a side-effect import (calls registerService at load).
+
+---
+
+## 2. Code Quality
+
+### ✅ Positives
+- Consistent spinner → success/fail pattern across all services
+- Good JSDoc on public functions
+- Clean separation: config/store vs config/keys vs wallet/keystore
+- Dependency injection on poker.js and whale.js makes them genuinely testable
+- 130 tests passing, zero failures
+
+### ❌ Issues
+- **`warn` not imported in cards.js** — will crash with ReferenceError on invalid denomination/provider
+- **`formatCompact()` duplicated** in market.js (already exists in utils/helpers.js)
+- **`topMovers()` makes unused HTTP call** — fetches trending endpoint, discards result
+- **ERC-20 ABI fragments duplicated** across swap.js, portfolio.js, whale.js, scripts/engine.js
+- **Explorer API URLs duplicated** between wallet/history.js and services/whale.js
+- **ora + nanospinner both in deps** — redundant spinner libraries
+- **cli.js is 1500+ lines** — should split into command modules
+- **Error handling inconsistent** — most use spin.fail(), but watch.js and market.js use raw console.log
+
+---
+
+## 3. Security Review
+
+### 🔴 CRITICAL — x402 nonce uses Math.random()
+
+**File:** `src/utils/x402.js`
+
+EIP-3009 nonce is generated with Math.random() — NOT cryptographically secure. This nonce authorizes USDC transfers on mainnet. A compromised PRNG seed allows replay attacks.
+
+**Fix:** `import { randomBytes } from 'crypto'; const nonce = '0x' + randomBytes(32).toString('hex');`
+
+### 🟠 HIGH — Key vault uses machine-derived password
+
+**File:** `src/config/keys.js`
+
+API keys stored via wizard are encrypted with `darksol-vault-${hostname()}-${username}` — predictable, derivable by any process running as the same user. Users aren't warned.
+
+**Fix:** Document weak vs strong protection clearly. Better: OS keychain or prompted master password.
+
+### 🟠 HIGH — Script execution is not sandboxed
+
+**File:** `src/scripts/engine.js`
+
+`new Function()` executes in global scope with full Node.js access. The unlocked private key signer is passed into script context. This is correct for user scripts, but needs a bold warning before execution.
+
+### 🟡 MEDIUM — node-fetch `timeout` silently ignored
+
+**Files:** `src/utils/x402.js`, `src/services/browser.js`
+
+node-fetch v3 dropped the timeout option. Calls with `{ timeout: 2000 }` will block indefinitely on hung connections.
+
+**Fix:** Use `AbortSignal.timeout(2000)` or manual AbortController.
+
+### 🟡 MEDIUM — Etherscan API key not applied in history.js
+
+`wallet/history.js` builds URLs without auth, unlike `services/whale.js` which uses `getApiKey('etherscan')`. Rate limited to 5 req/s unauthenticated.
+
+### 🟢 LOW — ETH price hardcoded fallback $3000
+
+`gas.js` and `portfolio.js` silently fall back to $3000 if CoinGecko is unreachable. No warning shown.
+
+### 🟢 LOW — Web server binds 0.0.0.0
+
+`src/web/server.js` binds all interfaces. Anyone on LAN can interact with the web terminal. Should default to 127.0.0.1.
+
+---
+
+## 4. Bug Hunt
+
+### 🔴 BUG — `warn` not imported in cards.js
+Any call to `cardsOrder()` with invalid denomination/provider throws `ReferenceError: warn is not defined`. Quick fix: add `warn` to the import.
+
+### 🔴 BUG — DCA `runDCA()` never executes actual swaps
+`src/trading/dca.js` — the executor marks orders as complete without calling `executeSwap`. Users see "DCA execution complete" for orders that were never traded. No "simulation mode" warning.
+
+### 🟠 BUG — `watchSnipe` auto-snipe logic is absent
+`src/trading/snipe.js` — subscribes to newBlockHeaders and logs block numbers, but never calls `snipeToken()`. The feature is a skeleton.
+
+### 🟠 BUG — Race condition in autonomous strategy loop
+`src/agent/autonomous.js` — `setInterval(runStrategyCycle, interval)` can fire overlapping cycles if one takes longer than the interval, risking duplicate trades. Should use setTimeout with re-scheduling.
+
+### 🟡 BUG — Silent error swallowing in whale monitor
+`src/services/whale-monitor.js` — `pollTrackedWallets().catch(() => {})` swallows all errors silently. No visibility into whether monitoring is working or failing.
+
+### 🟡 BUG — topMovers() wasted HTTP call
+`src/services/market.js` — fetches trending endpoint, result is completely discarded.
+
+### 🟡 BUG — Snipe slippage BigInt conversion
+`src/trading/snipe.js` — potential precision issues in slippage math with BigInt conversions.
+
+---
+
+## 5. Test Coverage
+
+### ✅ Well-tested
+- CLI command structure (cli.test.js)
+- Config store (config.test.js)
+- Keystore encryption (keystore.test.js)
+- Agent loop + tools (agent-loop.test.js, agent-tools.test.js)
+- Autonomous strategy (autonomous.test.js)
+- DCA CRUD (dca.test.js)
+- Trading validation (trading.test.js)
+- Poker logic (poker.test.js)
+- Script engine (scripts.test.js)
+- LLM providers (llm-providers.test.js)
+- Telegram bot (telegram.test.js)
+- UI components (ui.test.js)
+- Daemon management (daemon.test.js)
+- Helpers (helpers.test.js)
+
+### ❌ Not tested
+- x402 payment flow (critical path, no tests)
+- Casino service (real payment flow, no tests)
+- Oracle service (no tests)
+- Cards service (no tests — has the warn bug)
+- LI.FI bridge integration (no tests)
+- Web server/terminal (no tests)
+- Wallet portfolio scanning (no tests)
+- Whale monitor polling (no tests)
+- Agent signer HTTP daemon (no tests)
+- Facilitator service (no tests)
+
+### Assessment
+130 tests at 0 failures is solid. But the most dangerous code paths (x402 payments, casino bets, agent signer) have zero coverage. The things that move money are untested.
+
+---
+
+## 6. Dependency Health
+
+**19 runtime deps** — reasonable for scope, but:
+- **ora + nanospinner** — duplicate spinners, pick one
+- **blessed + blessed-contrib** — only used in dashboard.js, heavyweight for optional UI
+- **node-fetch** — Node 18+ has native fetch; could eliminate this dep entirely
+- **agentmail** — external dependency for mail service, review update frequency
+- **ethers v6** — correct and current
+- **ws** — needed for WebSocket (snipe block watcher, web terminal)
+
+No known CVEs in current dep tree. Supply chain risk is low — all deps are well-maintained mainstream packages.
+
+---
+
+## 7. UX Issues
+
+- **DCA "complete" messages are lies** — users think trades executed when they didn't
+- **Snipe watcher gives false confidence** — shows "watching..." but never snipes
+- **Key vault setup doesn't warn about protection level** — users assume their keys are safe
+- **Web terminal on 0.0.0.0 with no auth** — anyone on LAN gets full CLI access
+- **`hasSoul()` OLLAMA_HOST validation** — rejects bare hostnames without telling user to add http://
+- **cli.js is massive** — `darksol --help` works but finding specific subcommand help requires digging
+
+---
+
+## 8. Performance
+
+- **Startup:** Importing all 14 services on CLI boot regardless of which command runs. Lazy imports would cut cold start significantly.
+- **whale-monitor processed Set:** Grows unbounded, trims at 1000→500 but could accumulate over days
+- **node-fetch timeouts broken** — hung connections block indefinitely (see security section)
+- **topMovers double fetch** — wasted HTTP request on every call
+
+---
+
+## 9. Missing Features / Incomplete Code
+
+- **DCA execution** — CRUD works, execution is a stub
+- **Snipe auto-buy** — block watcher works, token detection is absent
+- **Whale mirror trading** — detected but not acted on
+- **Desktop app** — Electron scaffold at desktop/, not packaged
+- **MCP integration** — referenced in memory but not in current source
+
+---
+
+## 10. Prioritized Recommendations
+
+### 🔴 Critical (fix before next release)
+1. **x402 nonce: replace Math.random() with crypto.randomBytes()** — replay attack vector on mainnet USDC
+2. **cards.js: add `warn` to import** — crashes on invalid input
+3. **DCA: add clear "SIMULATION ONLY" warning or wire up real swaps** — users think trades execute
+
+### 🟠 High (fix soon)
+4. **node-fetch timeout: use AbortController** — prevents indefinite hangs
+5. **Web server: default to 127.0.0.1** — close LAN exposure
+6. **Autonomous strategy: replace setInterval with setTimeout chain** — prevent duplicate trades
+7. **Add tests for x402, casino, agent-signer** — the money-moving code needs coverage
+
+### 🟡 Medium (next sprint)
+8. **Deduplicate ERC-20 ABI, Explorer URLs, formatCompact** — DRY cleanup
+9. **Remove unused topMovers trending fetch**
+10. **Etherscan API key in history.js**
+11. **Lazy-load service imports in cli.js**
+12. **Split cli.js into command modules**
+
+### 🟢 Nice-to-have
+13. Remove ora (keep nanospinner) or vice versa
+14. Drop node-fetch, use native fetch
+15. ETH price fallback warning
+16. Script execution safety warning UI
+17. Key vault protection level documentation
+
+---
+
+**Bottom line:** The architecture is solid and well-organized for its scope. 130 passing tests is strong. The critical issues are concentrated in the financial paths — x402 nonce security, DCA phantom execution, and untested payment flows. Fix those three and this is a genuinely impressive CLI platform.

package/README.md

@@ -15,7 +15,7 @@ A unified CLI for market intel, trading, AI-powered analysis, on-chain oracle, c
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-gold.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
 
-- Current release: **0.11.0**
+- Current release: **0.12.0**
 - Changelog: `CHANGELOG.md`
 
 ## Install
@@ -56,6 +56,15 @@ darksol bridge send --from base --to arbitrum --token ETH -a 0.1
 darksol bridge status 0xTxHash...
 darksol bridge chains
 
+# Cross-DEX arbitrage
+darksol arb scan --chain base                       # one-shot price comparison
+darksol arb monitor --chain base --execute          # real-time block-by-block scanning
+darksol arb config                                   # set thresholds, dry-run, DEXes
+darksol arb add-endpoint base wss://your-quicknode   # faster with WSS endpoints
+darksol arb add-pair WETH AERO                       # add pairs to scan
+darksol arb stats --days 7                           # PnL history
+darksol arb info                                     # setup guide + risk warnings
+
 # Set up your agent identity
 darksol soul
 
@@ -128,6 +137,7 @@ Useful web-shell commands:
 ```bash
 help          # clickable command menu (arrow keys + Enter)
 trade         # interactive swap / snipe / bridge menu
+arb           # cross-DEX arbitrage scanner
 bridge        # cross-chain bridge (LI.FI)
 send          # interactive token transfer
 wallet        # interactive wallet picker and actions
@@ -150,6 +160,9 @@ ai <prompt>   # chat with trading assistant
 | `dca` | Dollar-cost averaging engine | Gas only |
 | `soul` | Agent identity & personality configuration | Free |
 | `memory` | Persistent cross-session memory store | Free |
+| `whale` | Whale Radar — track wallets, copy-trade, live feed | Free |
+| `dash` | Live TUI dashboard — portfolio, prices, gas, whale feed | Free |
+| `auto` | Autonomous Trader — goal-based automated execution | Provider dependent |
 | `agent task` | Autonomous ReAct agent loop with tool use | Provider dependent |
 | `ai` | LLM-powered trading assistant & intent execution | Provider dependent |
 | `agent` | Secure agent signer (PK-isolated proxy) | Free |
@@ -176,6 +189,98 @@ ai <prompt>   # chat with trading assistant
 
 ---
 
+## 🐋 Whale Radar
+
+Track any wallet across 5 chains. Get alerts on swaps, transfers, new tokens. Enable copy-trading to mirror a whale's moves automatically.
+
+```bash
+# Track a wallet
+darksol whale track 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --label "vitalik" --chain ethereum
+
+# List all tracked wallets
+darksol whale list
+
+# View recent activity
+darksol whale activity 0xd8dA... --limit 20
+
+# Enable copy-trading (mirrors swaps with your own limits)
+darksol whale mirror 0xd8dA... --max 50 --slippage 2 --dry-run
+
+# Open the live feed (blessed TUI)
+darksol whale feed
+
+# Stop tracking
+darksol whale stop 0xd8dA...
+```
+
+- **5-chain support:** Base, Ethereum, Arbitrum, Polygon, Optimism
+- **Swap decoding:** Uniswap V2 + V3 router signatures automatically parsed
+- **Copy-trading:** Mirror whale swaps with budget caps, slippage limits, dry-run mode
+- **Live feed:** Real-time blessed terminal UI with whale events streaming
+- **Daemon integration:** Runs as a background service, feeds alerts to Telegram bot
+- **Event system:** Subscribe to `whale:swap`, `whale:transfer`, `whale:newtoken`, `whale:mirror-executed`
+
+---
+
+## 📊 Live Dashboard
+
+Full-screen terminal dashboard. Portfolio, prices, gas, transactions, whale alerts — all updating in real-time.
+
+```bash
+# Launch the dashboard
+darksol dash
+
+# Custom refresh interval
+darksol dash --refresh 15
+
+# Compact mode (portfolio + prices only)
+darksol dash --compact
+```
+
+- **Portfolio summary** — total value, token balances, chain breakdown
+- **Price ticker** — sparkline micro-charts for tracked tokens
+- **Gas gauge** — current gas prices across all 5 chains
+- **Recent transactions** — last 10 txs from wallet history
+- **Whale feed** — live alerts when whale monitor is running
+- **Keyboard shortcuts:** `q` quit, `r` refresh, `tab` cycle focus, `w` toggle whales, `1-5` switch chains
+- **DARKSOL gold/dark theme** throughout
+
+---
+
+## 🤖 Autonomous Trader
+
+Set a goal in plain English. The AI builds a strategy, monitors the market, and executes trades within your budget and risk limits. Full audit trail on every decision.
+
+```bash
+# Start an autonomous strategy
+darksol auto start "accumulate ETH under 2400" --budget 500 --max-per-trade 50 --risk moderate
+
+# DCA into memecoins
+darksol auto start "DCA into BASE memecoins with >1M liquidity" --budget 200 --interval 15 --dry-run
+
+# Check status
+darksol auto status
+darksol auto status auto_1741...
+
+# View audit trail
+darksol auto log auto_1741... --limit 20
+
+# Stop a strategy
+darksol auto stop auto_1741...
+
+# List all strategies
+darksol auto list
+```
+
+- **Natural language goals** — parsed by LLM intent system into executable strategies
+- **Three risk levels:** conservative (5% stop-loss), moderate (10%), aggressive (20%)
+- **Kill switches:** budget exhaustion, max loss, error threshold — auto-stops immediately
+- **Dry-run mode** — test strategies without executing real trades
+- **Full audit log** — every decision, trade, and skip logged to `~/.darksol/autonomous/<id>/audit.json`
+- **Event system:** `auto:started`, `auto:trade`, `auto:skipped`, `auto:stopped`, `auto:budget-hit`, `auto:error`
+
+---
+
 ## 📱 Telegram Bot
 
 Turn your terminal into a Telegram AI agent. Same brain (LLM + soul + memory), different mouth.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksol/terminal",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "DARKSOL Terminal — unified CLI for all DARKSOL services. Market intel, trading, oracle, casino, and more.",
   "type": "module",
   "bin": {