@darksol/terminal 0.1.0 → 0.2.0

package/README.md

@@ -184,6 +184,105 @@ JSON output mode for programmatic use:
 darksol config set output json
 ```
 
+## Helper Functions
+
+When writing custom execution scripts, you have access to powerful helper utilities:
+
+```javascript
+import {
+  // Providers & Chain
+  getProvider,           // Get ethers provider for any chain
+  CHAIN_IDS,             // { base: 8453, ethereum: 1, ... }
+  EXPLORERS,             // Block explorer URLs per chain
+  txUrl, addressUrl,     // Generate explorer links
+
+  // Tokens
+  getERC20,              // Get ERC20 contract instance
+  getFullTokenInfo,      // Name, symbol, decimals, totalSupply
+  getTokenBalance,       // Formatted balance for any token
+  ensureApproval,        // Check & approve token spending
+  TOKENS,                // All known token addresses per chain
+  getUSDC, getWETH,      // Quick chain-specific lookups
+
+  // Gas
+  estimateGasCost,       // Estimate gas in ETH
+  getBoostedGas,         // Priority gas settings for snipes
+
+  // Formatting
+  formatCompact,         // 1234567 → "1.23M"
+  formatUSD,             // Format as $1,234.56
+  formatETH,             // Format wei to ETH string
+  formatTokenAmount,     // Format with symbol
+  shortAddress,          // 0x1234...5678
+  formatDuration,        // Seconds → "2h 30m"
+
+  // Validation
+  isValidAddress,        // Check Ethereum address
+  isValidPrivateKey,     // Check private key format
+  isValidAmount,         // Check positive number
+  parseTokenAmount,      // String → bigint with decimals
+
+  // Async
+  sleep,                 // await sleep(1000)
+  retry,                 // Retry with exponential backoff
+  waitForTx,             // Wait for tx with timeout
+
+  // Price
+  quickPrice,            // DexScreener price lookup
+  hasLiquidity,          // Check minimum liquidity
+} from './utils/helpers.js';
+```
+
+### Example: Custom Script Using Helpers
+
+```javascript
+module.exports = async function({ signer, provider, ethers, config, params }) {
+  // Import helpers (available in script context)
+  const helpers = await import('@darksol/terminal/src/utils/helpers.js');
+
+  // Check if token has enough liquidity
+  const liquid = await helpers.hasLiquidity(params.token, 5000);
+  if (!liquid) throw new Error('Insufficient liquidity');
+
+  // Get price
+  const price = await helpers.quickPrice(params.token);
+  console.log(`Price: ${helpers.formatUSD(price.price)}`);
+
+  // Get boosted gas for priority
+  const gas = await helpers.getBoostedGas(provider, 1.5);
+
+  // Execute trade with retry
+  const result = await helpers.retry(async () => {
+    const tx = await signer.sendTransaction({ ...txParams, ...gas });
+    return helpers.waitForTx(tx, 60000);
+  }, 3, 2000);
+
+  return { txHash: result.hash, price: price.price };
+};
+```
+
+## Tips & Reference
+
+```bash
+# Trading tips (slippage, MEV protection, etc.)
+darksol tips --trading
+
+# Script writing tips
+darksol tips --scripts
+
+# Both
+darksol tips
+
+# Network reference (chains, IDs, explorers, USDC addresses)
+darksol networks
+
+# Getting started guide
+darksol quickstart
+
+# Look up any address (auto-detects token vs wallet)
+darksol lookup 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+```
+
 ## Development
 
 ```bash

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@darksol/terminal",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DARKSOL Terminal — unified CLI for all DARKSOL services. Market intel, trading, oracle, casino, and more.",
   "type": "module",
   "bin": {
-    "darksol": "./bin/darksol.js"
+    "darksol": "bin/darksol.js"
   },
   "main": "./src/cli.js",
   "scripts": {
@@ -12,7 +12,16 @@
     "dev": "node bin/darksol.js dashboard",
     "test": "node --test tests/*.test.js"
   },
-  "keywords": ["darksol", "crypto", "trading", "cli", "x402", "base", "ethereum", "defi"],
+  "keywords": [
+    "darksol",
+    "crypto",
+    "trading",
+    "cli",
+    "x402",
+    "base",
+    "ethereum",
+    "defi"
+  ],
   "author": "DARKSOL <chris00claw@gmail.com>",
   "license": "MIT",
   "dependencies": {

package/src/cli.js

@@ -14,6 +14,10 @@ import { cardsCatalog, cardsOrder, cardsStatus } from './services/cards.js';
 import { facilitatorHealth, facilitatorVerify, facilitatorSettle } from './services/facilitator.js';
 import { buildersLeaderboard, buildersLookup, buildersFeed } from './services/builders.js';
 import { createScript, listScripts, runScript, showScript, editScript, deleteScript, cloneScript, listTemplates } from './scripts/engine.js';
+import { showTradingTips, showScriptTips, showNetworkReference, showQuickStart, showWalletSummary, showTokenInfo, showTxResult } from './utils/helpers.js';
+import { addKey, removeKey, listKeys } from './config/keys.js';
+import { parseIntent, startChat, adviseStrategy, analyzeToken } from './llm/intent.js';
+import { startAgentSigner, showAgentDocs } from './wallet/agent-signer.js';
 
 export function cli(argv) {
   const program = new Command();
@@ -288,6 +292,154 @@ export function cli(argv) {
     .description('Settle payment on-chain')
     .action((payment) => facilitatorSettle(payment));
 
+  // ═══════════════════════════════════════
+  // AI / LLM COMMANDS
+  // ═══════════════════════════════════════
+  const ai = program
+    .command('ai')
+    .description('AI-powered trading assistant & analysis');
+
+  ai
+    .command('chat')
+    .description('Start interactive AI trading chat')
+    .option('-p, --provider <name>', 'LLM provider (openai, anthropic, openrouter, ollama)')
+    .option('-m, --model <model>', 'Model name')
+    .action((opts) => startChat(opts));
+
+  ai
+    .command('ask <prompt...>')
+    .description('One-shot AI query')
+    .option('-p, --provider <name>', 'LLM provider')
+    .option('-m, --model <model>', 'Model name')
+    .action(async (promptParts, opts) => {
+      const prompt = promptParts.join(' ');
+      const result = await parseIntent(prompt, opts);
+      if (result.action !== 'error' && result.action !== 'unknown') {
+        showSection('PARSED INTENT');
+        kvDisplay(Object.entries(result)
+          .filter(([k]) => !['raw', 'model'].includes(k))
+          .map(([k, v]) => [k, Array.isArray(v) ? v.join(', ') : String(v)])
+        );
+        if (result.command) {
+          console.log('');
+          info(`Suggested command: ${theme.gold(result.command)}`);
+        }
+      }
+    });
+
+  ai
+    .command('strategy <token>')
+    .description('Get DCA strategy recommendation')
+    .requiredOption('-b, --budget <usd>', 'Total budget in USD')
+    .option('-t, --timeframe <period>', 'Investment timeframe', '30 days')
+    .option('-p, --provider <name>', 'LLM provider')
+    .action((token, opts) => adviseStrategy(token, opts.budget, opts.timeframe, opts));
+
+  ai
+    .command('analyze <token>')
+    .description('AI-powered token analysis')
+    .option('-p, --provider <name>', 'LLM provider')
+    .action((token, opts) => analyzeToken(token, opts));
+
+  // ═══════════════════════════════════════
+  // API KEYS COMMANDS
+  // ═══════════════════════════════════════
+  const keys = program
+    .command('keys')
+    .description('API key vault — store keys for LLMs, data providers, RPCs');
+
+  keys
+    .command('list')
+    .description('List all services and stored keys')
+    .action(() => listKeys());
+
+  keys
+    .command('add <service>')
+    .description('Add or update an API key')
+    .option('-k, --key <key>', 'API key (or enter interactively)')
+    .action((service, opts) => addKey(service, opts));
+
+  keys
+    .command('remove <service>')
+    .description('Remove a stored key')
+    .action((service) => removeKey(service));
+
+  // ═══════════════════════════════════════
+  // AGENT SIGNER COMMANDS
+  // ═══════════════════════════════════════
+  const agent = program
+    .command('agent')
+    .description('Secure agent signer — PK-isolated wallet for AI agents');
+
+  agent
+    .command('start [wallet]')
+    .description('Start the agent signing proxy')
+    .option('--port <port>', 'Server port', '18790')
+    .option('--max-value <eth>', 'Max ETH per transaction', '1.0')
+    .option('--daily-limit <eth>', 'Daily spending limit in ETH', '5.0')
+    .option('--allowlist <contracts>', 'Comma-separated contract allowlist')
+    .action((wallet, opts) => startAgentSigner(wallet, opts));
+
+  agent
+    .command('docs')
+    .description('Show agent signer security documentation')
+    .action(() => showAgentDocs());
+
+  // ═══════════════════════════════════════
+  // TIPS & REFERENCE COMMANDS
+  // ═══════════════════════════════════════
+  program
+    .command('tips')
+    .description('Show trading and script writing tips')
+    .option('-t, --trading', 'Trading tips only')
+    .option('-s, --scripts', 'Script writing tips only')
+    .action((opts) => {
+      showMiniBanner();
+      if (opts.scripts) {
+        showScriptTips();
+      } else if (opts.trading) {
+        showTradingTips();
+      } else {
+        showTradingTips();
+        showScriptTips();
+      }
+    });
+
+  program
+    .command('networks')
+    .description('Show supported networks and chain info')
+    .action(() => {
+      showMiniBanner();
+      showNetworkReference();
+    });
+
+  program
+    .command('quickstart')
+    .description('Show getting started guide')
+    .action(() => {
+      showMiniBanner();
+      showQuickStart();
+    });
+
+  program
+    .command('lookup <address>')
+    .description('Look up a token or wallet address on-chain')
+    .option('-c, --chain <chain>', 'Chain to query')
+    .action(async (address, opts) => {
+      showMiniBanner();
+      if (address.length === 42 && address.startsWith('0x')) {
+        // Could be token or wallet — try token first
+        try {
+          await showTokenInfo(address, opts.chain);
+        } catch {
+          await showWalletSummary(address, opts.chain);
+        }
+      } else {
+        const { error } = await import('./ui/components.js');
+        error('Provide a valid 0x address');
+      }
+    });
+
   // ═══════════════════════════════════════
   // SCRIPT COMMANDS
   // ═══════════════════════════════════════
@@ -410,6 +562,9 @@ export function cli(argv) {
         ['wallet', 'Create, import, manage wallets'],
         ['trade', 'Swap tokens, snipe, trading'],
         ['dca', 'Dollar-cost averaging orders'],
+        ['ai', 'AI trading assistant & analysis'],
+        ['agent', 'Secure agent signer (PK-isolated)'],
+        ['keys', 'API key vault (LLMs, data, RPCs)'],
         ['script', 'Execution scripts & strategies'],
         ['market', 'Market intel & token data'],
         ['oracle', 'On-chain random oracle'],
@@ -418,6 +573,10 @@ export function cli(argv) {
         ['builders', 'ERC-8021 builder index'],
         ['facilitator', 'x402 payment facilitator'],
         ['config', 'Terminal configuration'],
+        ['tips', 'Trading & scripting tips'],
+        ['networks', 'Chain reference & explorers'],
+        ['quickstart', 'Getting started guide'],
+        ['lookup', 'Look up any address on-chain'],
       ];
 
       commands.forEach(([cmd, desc]) => {

package/src/config/keys.js

@@ -0,0 +1,320 @@
+import { randomBytes, createCipheriv, createDecipheriv, scryptSync } from 'crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { theme } from '../ui/theme.js';
+import { kvDisplay, success, error, warn, info } from '../ui/components.js';
+import { showSection } from '../ui/banner.js';
+import inquirer from 'inquirer';
+
+const KEYS_DIR = join(homedir(), '.darksol', 'keys');
+const KEYS_FILE = join(KEYS_DIR, 'vault.json');
+const ALGORITHM = 'aes-256-gcm';
+const SCRYPT_N = 2 ** 16;  // lighter for keys (faster unlock)
+const SCRYPT_r = 8;
+const SCRYPT_p = 1;
+const SCRYPT_MAXMEM = 512 * 1024 * 1024;
+
+function ensureDir() {
+  if (!existsSync(KEYS_DIR)) mkdirSync(KEYS_DIR, { recursive: true });
+}
+
+function encrypt(value, password) {
+  const salt = randomBytes(32);
+  const iv = randomBytes(16);
+  const key = scryptSync(password, salt, 32, { N: SCRYPT_N, r: SCRYPT_r, p: SCRYPT_p, maxmem: SCRYPT_MAXMEM });
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  let encrypted = cipher.update(value, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+  return {
+    salt: salt.toString('hex'),
+    iv: iv.toString('hex'),
+    tag: cipher.getAuthTag().toString('hex'),
+    data: encrypted,
+  };
+}
+
+function decrypt(entry, password) {
+  const key = scryptSync(password, Buffer.from(entry.salt, 'hex'), 32, { N: SCRYPT_N, r: SCRYPT_r, p: SCRYPT_p, maxmem: SCRYPT_MAXMEM });
+  const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(entry.iv, 'hex'));
+  decipher.setAuthTag(Buffer.from(entry.tag, 'hex'));
+  let decrypted = decipher.update(entry.data, 'hex', 'utf8');
+  decrypted += decipher.final('utf8');
+  return decrypted;
+}
+
+function loadVault() {
+  ensureDir();
+  if (!existsSync(KEYS_FILE)) return { version: 1, keys: {} };
+  return JSON.parse(readFileSync(KEYS_FILE, 'utf8'));
+}
+
+function saveVault(vault) {
+  ensureDir();
+  writeFileSync(KEYS_FILE, JSON.stringify(vault, null, 2));
+}
+
+// ──────────────────────────────────────────────────
+// SUPPORTED API SERVICES
+// ──────────────────────────────────────────────────
+
+export const SERVICES = {
+  // LLM Providers
+  openai: {
+    name: 'OpenAI',
+    category: 'llm',
+    description: 'GPT-4o, GPT-5 — natural language trading, strategy advisor',
+    envVar: 'OPENAI_API_KEY',
+    docsUrl: 'https://platform.openai.com/api-keys',
+    validate: (key) => key.startsWith('sk-'),
+  },
+  anthropic: {
+    name: 'Anthropic',
+    category: 'llm',
+    description: 'Claude Opus, Sonnet — intent parsing, analysis',
+    envVar: 'ANTHROPIC_API_KEY',
+    docsUrl: 'https://console.anthropic.com/settings/keys',
+    validate: (key) => key.startsWith('sk-ant-'),
+  },
+  openrouter: {
+    name: 'OpenRouter',
+    category: 'llm',
+    description: 'Multi-model gateway — any LLM via one key',
+    envVar: 'OPENROUTER_API_KEY',
+    docsUrl: 'https://openrouter.ai/keys',
+    validate: (key) => key.startsWith('sk-or-'),
+  },
+  ollama: {
+    name: 'Ollama (Local)',
+    category: 'llm',
+    description: 'Local models — free, private, no API key needed',
+    envVar: 'OLLAMA_HOST',
+    docsUrl: 'https://ollama.ai',
+    validate: (key) => key.startsWith('http'),
+  },
+
+  // Data Providers
+  coingecko: {
+    name: 'CoinGecko Pro',
+    category: 'data',
+    description: 'Pro/Demo API — higher rate limits, more endpoints',
+    envVar: 'COINGECKO_API_KEY',
+    docsUrl: 'https://www.coingecko.com/en/api/pricing',
+    validate: (key) => key.length > 10,
+  },
+  dexscreener: {
+    name: 'DexScreener',
+    category: 'data',
+    description: 'Enhanced DEX data — paid tier for higher limits',
+    envVar: 'DEXSCREENER_API_KEY',
+    docsUrl: 'https://docs.dexscreener.com',
+    validate: (key) => key.length > 10,
+  },
+  defillama: {
+    name: 'DefiLlama',
+    category: 'data',
+    description: 'TVL, yield, protocol data — free, no key needed',
+    envVar: null,
+    docsUrl: 'https://defillama.com/docs/api',
+    validate: () => true,
+  },
+
+  // RPC Providers (OAuth/API key)
+  alchemy: {
+    name: 'Alchemy',
+    category: 'rpc',
+    description: 'Premium RPC — faster, more reliable, trace APIs',
+    envVar: 'ALCHEMY_API_KEY',
+    docsUrl: 'https://dashboard.alchemy.com',
+    validate: (key) => key.length > 10,
+  },
+  infura: {
+    name: 'Infura',
+    category: 'rpc',
+    description: 'RPC provider — Ethereum, Polygon, Arbitrum, Optimism',
+    envVar: 'INFURA_API_KEY',
+    docsUrl: 'https://app.infura.io',
+    validate: (key) => key.length > 10,
+  },
+  quicknode: {
+    name: 'QuickNode',
+    category: 'rpc',
+    description: 'High-performance RPC — WebSocket support, trace',
+    envVar: 'QUICKNODE_API_KEY',
+    docsUrl: 'https://dashboard.quicknode.com',
+    validate: (key) => key.length > 10,
+  },
+
+  // Trading & Auth
+  oneinch: {
+    name: '1inch',
+    category: 'trading',
+    description: 'DEX aggregator API — best swap routing',
+    envVar: 'ONEINCH_API_KEY',
+    docsUrl: 'https://portal.1inch.dev',
+    validate: (key) => key.length > 10,
+  },
+  paraswap: {
+    name: 'ParaSwap',
+    category: 'trading',
+    description: 'DEX aggregator — competitive routing',
+    envVar: 'PARASWAP_API_KEY',
+    docsUrl: 'https://developers.paraswap.network',
+    validate: (key) => key.length > 5,
+  },
+};
+
+// ──────────────────────────────────────────────────
+// KEY MANAGEMENT
+// ──────────────────────────────────────────────────
+
+/**
+ * Add or update an API key
+ */
+export async function addKey(service, opts = {}) {
+  const svc = SERVICES[service];
+  if (!svc) {
+    error(`Unknown service: ${service}. Run: darksol keys list`);
+    return;
+  }
+
+  let apiKey = opts.key;
+  if (!apiKey) {
+    const { key } = await inquirer.prompt([{
+      type: 'password',
+      name: 'key',
+      message: theme.gold(`${svc.name} API key:`),
+      mask: '●',
+      validate: (v) => {
+        if (!v) return 'Key required';
+        if (svc.validate && !svc.validate(v)) return `Invalid format for ${svc.name}`;
+        return true;
+      },
+    }]);
+    apiKey = key;
+  }
+
+  // Get vault password
+  let vaultPass = opts.password;
+  if (!vaultPass) {
+    const { password } = await inquirer.prompt([{
+      type: 'password',
+      name: 'password',
+      message: theme.gold('Vault password:'),
+      mask: '●',
+      validate: (v) => v.length >= 6 || 'Minimum 6 characters',
+    }]);
+    vaultPass = password;
+  }
+
+  const vault = loadVault();
+  vault.keys[service] = {
+    encrypted: encrypt(apiKey, vaultPass),
+    service: svc.name,
+    category: svc.category,
+    addedAt: new Date().toISOString(),
+  };
+  saveVault(vault);
+
+  success(`${svc.name} key stored securely`);
+  if (svc.envVar) {
+    info(`Also available via env: ${svc.envVar}`);
+  }
+}
+
+/**
+ * Get a decrypted API key
+ */
+export async function getKey(service, password) {
+  const vault = loadVault();
+  const entry = vault.keys[service];
+
+  if (!entry) {
+    // Fall back to environment variable
+    const svc = SERVICES[service];
+    if (svc?.envVar && process.env[svc.envVar]) {
+      return process.env[svc.envVar];
+    }
+    return null;
+  }
+
+  try {
+    return decrypt(entry.encrypted, password);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get a key without password (tries env var first, then cached session)
+ */
+export function getKeyFromEnv(service) {
+  const svc = SERVICES[service];
+  if (svc?.envVar && process.env[svc.envVar]) {
+    return process.env[svc.envVar];
+  }
+  return null;
+}
+
+/**
+ * Remove a key
+ */
+export async function removeKey(service) {
+  const vault = loadVault();
+  if (!vault.keys[service]) {
+    error(`No key stored for: ${service}`);
+    return;
+  }
+  const svc = SERVICES[service];
+  const { confirm } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'confirm',
+    message: theme.accent(`Remove ${svc?.name || service} key?`),
+    default: false,
+  }]);
+  if (!confirm) return;
+
+  delete vault.keys[service];
+  saveVault(vault);
+  success(`${svc?.name || service} key removed`);
+}
+
+/**
+ * List all services and stored keys
+ */
+export function listKeys() {
+  const vault = loadVault();
+
+  showSection('API KEY VAULT');
+
+  const categories = ['llm', 'data', 'rpc', 'trading'];
+  const catNames = { llm: '🧠 LLM PROVIDERS', data: '📊 DATA PROVIDERS', rpc: '🌐 RPC PROVIDERS', trading: '📈 TRADING' };
+
+  for (const cat of categories) {
+    console.log('');
+    console.log(theme.gold(`  ${catNames[cat]}`));
+
+    const services = Object.entries(SERVICES).filter(([, s]) => s.category === cat);
+    for (const [key, svc] of services) {
+      const stored = vault.keys[key];
+      const envKey = svc.envVar ? getKeyFromEnv(key) : null;
+      let status;
+
+      if (stored) {
+        status = theme.success('● Stored');
+      } else if (envKey) {
+        status = theme.info('● Env');
+      } else {
+        status = theme.dim('○ Not set');
+      }
+
+      console.log(`    ${status} ${theme.label(svc.name.padEnd(18))} ${theme.dim(svc.description)}`);
+    }
+  }
+
+  console.log('');
+  info('Add a key: darksol keys add <service>');
+  info('Services: ' + Object.keys(SERVICES).join(', '));
+}
+
+export { KEYS_DIR, KEYS_FILE };