@darksol/terminal 0.1.1 → 0.2.1

package/package.json

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

package/skill/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: darksol-terminal
+description: "DARKSOL Terminal — unified CLI for trading, wallets, execution scripts, AI-powered market analysis, secure agent signing, and all DARKSOL services. Use when: (1) swapping/sniping tokens on Base/Ethereum/L2s, (2) managing encrypted wallets, (3) running automated trading scripts, (4) DCA strategies, (5) market intel lookups, (6) on-chain oracle/casino/cards, (7) natural language trading via LLM, (8) signing transactions securely for x402/contracts without exposing private keys."
+---
+
+# DARKSOL Terminal
+
+**All DARKSOL services. One terminal. Zero trust required. 🌑**
+
+## Install
+
+```bash
+npm install -g @darksol/terminal
+```
+
+## Quick Reference
+
+### Wallet Management
+```bash
+darksol wallet create <name>           # Create new wallet (AES-256-GCM encrypted)
+darksol wallet import <name>           # Import from private key
+darksol wallet list                    # List all wallets
+darksol wallet balance [name]          # Check ETH + USDC balance
+darksol wallet use <name>              # Set active wallet
+darksol wallet export [name]           # Export details (password required for PK)
+```
+
+### Trading
+```bash
+darksol trade swap -i ETH -o USDC -a 0.1      # Swap via Uniswap V3
+darksol trade snipe <token> -a 0.05            # Fast buy with gas boost
+darksol trade snipe <token> -a 0.05 -g 2.0     # Snipe with 2x gas priority
+darksol trade watch                             # Monitor new pairs
+```
+
+### DCA (Dollar-Cost Averaging)
+```bash
+darksol dca create                     # Interactive DCA order creation
+darksol dca list                       # List active DCA orders
+darksol dca run                        # Execute pending orders
+darksol dca cancel <id>                # Cancel an order
+```
+
+### AI Trading Assistant
+```bash
+darksol ai chat                        # Interactive AI trading chat
+darksol ai ask "buy 0.5 ETH of AERO"  # Parse natural language trade intent
+darksol ai strategy VIRTUAL -b 500     # DCA strategy recommendation
+darksol ai analyze AERO                # AI-powered token analysis
+```
+
+### Execution Scripts
+```bash
+darksol script templates               # List available templates
+darksol script create                  # Create from template (buy, sell, limit-buy, stop-loss, etc.)
+darksol script list                    # List saved scripts
+darksol script run <name>              # Execute (requires wallet password)
+darksol script run <name> -p "pw" -y   # Non-interactive (for automation/cron)
+darksol script show <name>             # View code + params
+darksol script edit <name>             # Edit params/wallet/chain
+darksol script clone <name> <new>      # Clone a script
+darksol script delete <name>           # Delete a script
+```
+
+Script templates: `buy-token`, `sell-token`, `limit-buy`, `stop-loss`, `multi-buy`, `transfer`, `empty` (custom)
+
+### Market Intel
+```bash
+darksol market top                     # Top movers on Base
+darksol market top -c ethereum         # Top movers on Ethereum
+darksol market token VIRTUAL           # Full token detail
+darksol market compare ETH AERO VIRTUAL # Side-by-side comparison
+```
+
+### Secure Agent Signer (for OpenClaw / AI agents)
+```bash
+darksol agent start <wallet>           # Start signing proxy
+darksol agent start <wallet> --max-value 0.5 --daily-limit 2.0
+darksol agent docs                     # Full security documentation
+```
+
+The agent signer creates a local HTTP server at `127.0.0.1:18790` that signs transactions without exposing the private key. AI agents authenticate with a one-time bearer token.
+
+**Endpoints:**
+- `GET /address` — wallet address
+- `GET /balance` — ETH balance
+- `POST /send` — sign + broadcast transaction
+- `POST /sign-message` — sign EIP-191 message (x402)
+- `POST /sign-typed-data` — sign EIP-712 typed data (x402)
+- `GET /policy` — spending limits
+- `GET /audit` — operation log
+
+### Oracle
+```bash
+darksol oracle flip                    # Coin flip
+darksol oracle dice 20                 # Roll d20
+darksol oracle number 1 100            # Random 1-100
+darksol oracle shuffle a b c d         # Shuffle list
+```
+
+### Casino
+```bash
+darksol casino bet coin-flip heads     # Place a bet
+darksol casino tables                  # View games
+darksol casino stats                   # House stats
+darksol casino receipt <id>            # Verify on-chain
+```
+
+### Prepaid Cards
+```bash
+darksol cards catalog                  # Available providers
+darksol cards order -p swype -a 50     # Order a card
+darksol cards status <id>              # Check order
+```
+
+### Builder Index
+```bash
+darksol builders leaderboard           # ERC-8021 builder rankings
+darksol builders lookup <code>         # Builder profile
+darksol builders feed                  # Recent transactions
+```
+
+### Facilitator
+```bash
+darksol facilitator health             # Status
+darksol facilitator verify <payment>   # Verify off-chain
+darksol facilitator settle <payment>   # Settle on-chain (free)
+```
+
+### API Keys
+```bash
+darksol keys list                      # Show all services + status
+darksol keys add openai                # Add OpenAI key
+darksol keys add coingecko             # Add CoinGecko Pro key
+darksol keys add alchemy               # Add Alchemy RPC key
+darksol keys remove <service>          # Remove a key
+```
+
+Supported: `openai`, `anthropic`, `openrouter`, `ollama`, `coingecko`, `dexscreener`, `alchemy`, `infura`, `quicknode`, `oneinch`, `paraswap`
+
+### Configuration
+```bash
+darksol config show                    # View all settings
+darksol config set chain base          # Set active chain
+darksol config set slippage 1.0        # Set slippage %
+darksol config rpc base https://...    # Custom RPC endpoint
+```
+
+### Reference
+```bash
+darksol tips                           # Trading + scripting tips
+darksol tips --trading                 # Trading tips only
+darksol networks                       # Chain reference table
+darksol quickstart                     # Getting started guide
+darksol lookup 0x...                   # Look up address on-chain
+```
+
+## Supported Chains
+- **Base** (default) — chain ID 8453
+- **Ethereum** — chain ID 1
+- **Polygon** — chain ID 137
+- **Arbitrum** — chain ID 42161
+- **Optimism** — chain ID 10
+
+## Agent Integration Notes
+
+- All commands work non-interactively with flags (`-p`, `-y`, `--key`, etc.)
+- Set `darksol config set output json` for programmatic JSON responses
+- Scripts can be executed via cron: `darksol script run my-dca -p "pass" -y`
+- The agent signer is the recommended way to give AI agents wallet access
+- Helper functions available at `@darksol/terminal/src/utils/helpers.js`
+
+## Security
+- Private keys encrypted with AES-256-GCM + scrypt KDF
+- Agent signer: PK never exposed, loopback-only, bearer auth, spending limits
+- Dangerous contract calls (transferOwnership, selfdestruct) blocked by default
+- Full audit logging on all signing operations

package/src/cli.js

@@ -15,6 +15,10 @@ import { facilitatorHealth, facilitatorVerify, facilitatorSettle } from './servi
 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';
+import { listSkills, installSkill, skillInfo, uninstallSkill } from './services/skills.js';
 
 export function cli(argv) {
   const program = new Command();
@@ -289,6 +293,126 @@ 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());
+
+  // ═══════════════════════════════════════
+  // SKILLS COMMANDS
+  // ═══════════════════════════════════════
+  const skills = program
+    .command('skills')
+    .description('DARKSOL skills directory — install agent skills');
+
+  skills
+    .command('list')
+    .description('List all available DARKSOL skills')
+    .action(() => listSkills());
+
+  skills
+    .command('install <name>')
+    .description('Install a skill to OpenClaw')
+    .action((name) => installSkill(name));
+
+  skills
+    .command('info <name>')
+    .description('Show skill details')
+    .action((name) => skillInfo(name));
+
+  skills
+    .command('uninstall <name>')
+    .description('Uninstall a skill')
+    .action((name) => uninstallSkill(name));
+
   // ═══════════════════════════════════════
   // TIPS & REFERENCE COMMANDS
   // ═══════════════════════════════════════
@@ -466,6 +590,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'],
@@ -473,6 +600,7 @@ export function cli(argv) {
         ['cards', 'Prepaid Visa/MC cards'],
         ['builders', 'ERC-8021 builder index'],
         ['facilitator', 'x402 payment facilitator'],
+        ['skills', 'Agent skill directory & install'],
         ['config', 'Terminal configuration'],
         ['tips', 'Trading & scripting tips'],
         ['networks', 'Chain reference & explorers'],

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 };