@darksol/terminal 0.12.0 → 0.13.1

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

@@ -56,6 +56,21 @@ 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                       # AI-scored DEX 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
+
+# AI arbitrage intelligence
+darksol arb ai                                       # strategy briefing + recommendations
+darksol arb discover --chain base                    # AI pair discovery
+darksol arb tune --chain base                        # AI threshold optimization
+darksol arb learn --chain base                       # learn from history patterns
+
 # Set up your agent identity
 darksol soul
 
@@ -128,6 +143,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

package/package.json

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

package/src/cli.js

@@ -16,6 +16,8 @@ import { startWebShell } from './web/server.js';
 import { executeSwap } from './trading/swap.js';
 import { snipeToken, watchSnipe } from './trading/snipe.js';
 import { createDCA, listDCA, cancelDCA, runDCA } from './trading/dca.js';
+import { arbScan, arbMonitor, arbExecute, arbStats, arbConfig, arbAddEndpoint, arbAddPair, arbRemovePair, arbInfo } from './trading/arb.js';
+import { aiDiscoverPairs, aiTuneThresholds, aiStrategyBriefing, aiLearn } from './trading/arb-ai.js';
 import { executeLifiSwap, executeLifiBridge, checkBridgeStatus, showSupportedChains } from './services/lifi.js';
 import { topMovers, tokenDetail, compareTokens } from './services/market.js';
 import { oracleFlip, oracleDice, oracleNumber, oracleShuffle, oracleHealth } from './services/oracle.js';
@@ -333,6 +335,96 @@ export function cli(argv) {
     .description('Execute pending DCA orders')
     .action(() => runDCA());
 
+  // ═══════════════════════════════════════
+  // ARBITRAGE COMMANDS
+  // ═══════════════════════════════════════
+  const arb = program
+    .command('arb')
+    .description('Cross-DEX arbitrage - scan, monitor, execute');
+
+  arb
+    .command('scan')
+    .description('One-shot scan across DEXs for price differences')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .option('-p, --pair <pair>', 'Token pair to scan (e.g. WETH/USDC)')
+    .option('-m, --min-profit <usd>', 'Minimum profit threshold in USD', '0.50')
+    .option('-s, --trade-size <eth>', 'Trade size in ETH', '0.1')
+    .action((opts) => arbScan({
+      chain: opts.chain,
+      pair: opts.pair,
+      minProfit: parseFloat(opts.minProfit),
+      tradeSize: parseFloat(opts.tradeSize),
+    }));
+
+  arb
+    .command('monitor')
+    .description('Real-time block-by-block arb monitoring (WSS recommended)')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .option('-e, --execute', 'Auto-execute profitable arbs')
+    .option('-d, --dry-run', 'Dry-run mode (no real transactions)')
+    .option('-m, --min-profit <usd>', 'Minimum profit threshold in USD', '0.50')
+    .action((opts) => arbMonitor({
+      chain: opts.chain,
+      execute: opts.execute,
+      dryRun: opts.dryRun !== undefined ? opts.dryRun : undefined,
+      minProfit: opts.minProfit,
+    }));
+
+  arb
+    .command('stats')
+    .description('View arb history and performance stats')
+    .option('-d, --days <days>', 'Number of days to show', '7')
+    .action((opts) => arbStats({ days: opts.days }));
+
+  arb
+    .command('config')
+    .description('Interactive arb configuration (thresholds, dry-run, DEXes)')
+    .action(() => arbConfig());
+
+  arb
+    .command('add-endpoint <chain> <url>')
+    .description('Add a custom WSS or RPC endpoint for faster arb detection')
+    .action((chain, url) => arbAddEndpoint({ chain, url }));
+
+  arb
+    .command('add-pair <tokenA> <tokenB>')
+    .description('Add a token pair to the arb scan list')
+    .action((tokenA, tokenB) => arbAddPair({ tokenA, tokenB }));
+
+  arb
+    .command('remove-pair <tokenA> <tokenB>')
+    .description('Remove a token pair from the arb scan list')
+    .action((tokenA, tokenB) => arbRemovePair({ tokenA, tokenB }));
+
+  arb
+    .command('info')
+    .description('How arbitrage works, setup guide, and risk warnings')
+    .action(() => arbInfo());
+
+  arb
+    .command('ai')
+    .description('AI strategy briefing — assessment, recommendations, next actions')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .action((opts) => aiStrategyBriefing({ chain: opts.chain }));
+
+  arb
+    .command('discover')
+    .description('AI-powered pair discovery — find new opportunities, drop dead pairs')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .action((opts) => aiDiscoverPairs({ chain: opts.chain }));
+
+  arb
+    .command('tune')
+    .description('AI threshold tuning — optimize min profit, trade size, gas ceiling')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .action((opts) => aiTuneThresholds({ chain: opts.chain }));
+
+  arb
+    .command('learn')
+    .description('Run AI learning cycle — analyze history and update patterns')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .action((opts) => aiLearn({ chain: opts.chain }));
+
   const auto = program
     .command('auto')
     .description('Autonomous trader mode - goal-based automated execution');
@@ -1933,6 +2025,7 @@ function showCommandList() {
     ['watch', 'Live price monitoring + alerts'],
     ['gas', 'Gas prices & cost estimates'],
     ['trade', 'Swap tokens, snipe, trading'],
+    ['arb', 'Cross-DEX arbitrage scanner'],
     ['auto', 'Autonomous trader strategies'],
     ['bridge', 'Cross-chain bridge (LI.FI)'],
     ['dca', 'Dollar-cost averaging orders'],

package/src/config/store.js

@@ -57,6 +57,34 @@ const config = new Conf({
         strategies: [],
       },
     },
+    arb: {
+      type: 'object',
+      default: {
+        enabled: false,
+        minProfitUsd: 0.50,
+        maxTradeSize: 1.0,
+        gasCeiling: 0.01,
+        cooldownMs: 5000,
+        dryRun: true,
+        tokenAllowlist: [],
+        tokenDenylist: [],
+        endpoints: {
+          wss: {},
+          rpc: {},
+        },
+        dexes: {
+          base:     ['uniswapV3', 'aerodrome', 'sushiswap'],
+          ethereum: ['uniswapV3', 'sushiswap'],
+          arbitrum: ['uniswapV3', 'sushiswap', 'camelot'],
+          optimism: ['uniswapV3', 'velodrome'],
+          polygon:  ['uniswapV3', 'quickswap'],
+        },
+        pairs: [
+          { tokenA: 'WETH', tokenB: 'USDC' },
+          { tokenA: 'WETH', tokenB: 'USDT' },
+        ],
+      },
+    },
     services: {
       type: 'object',
       default: {

package/src/llm/intent.js

@@ -66,6 +66,8 @@ ACTIONS (use the most specific one):
 - "gas" — gas price check
 - "cards" — order a prepaid Visa/Mastercard with crypto (e.g. "order a $50 card", "get me a prepaid card")
 - "casino" — play a casino game (coinflip, dice, hilo, slots). All bets are $1 USDC. (e.g. "flip a coin", "bet on heads", "play slots", "roll dice over 3")
+- "arb_scan" — scan for cross-DEX arbitrage opportunities (e.g. "find arb opportunities", "scan for price differences", "check arb on base")
+- "arb_monitor" — start real-time arbitrage monitoring (e.g. "monitor arb", "watch for arb opportunities")
 - "unknown" — can't determine what the user wants
 
 CASINO GAMES: