agentlili 0.1.0

package/README.md

@@ -0,0 +1,533 @@
+# AI Agent Wallet — Solana Devnet
+
+An autonomous AI agent wallet for Solana that manages wallets, executes DeFi operations, and interacts with on-chain protocols — all through natural language. Supports multiple independent agents, each with their own isolated keypair, security policy, and decision-making context.
+
+Built with Vercel AI SDK, Solana Agent Kit v2, and Next.js 15.
+
+---
+
+## For Judges — Quick Navigation
+
+| Judging Criteria | What to Look At | Command / Link |
+|---|---|---|
+| **C1: Functional Demo** | Autonomous DeFi agent with 93 tools, SSE activity feed, one-click demos | `pnpm dev` → click any demo card, or `SKIP_LLM=1 pnpm headless-demo` |
+| **C2: Security & Key Mgmt** | FROST 2-of-3 threshold signing, PolicyParticipant, PDA vault, spending limits, HMAC audit chain | `pnpm frost-demo` (no API keys needed), Security tab in UI, [SECURITY.md](SECURITY.md) |
+| **C3: Documentation** | 1,800+ line deep dive, 22 Mermaid diagrams, machine-readable SKILLS.md | [DEEP_DIVE.md](DEEP_DIVE.md) (architecture + threat model), [SKILLS.md](SKILLS.md) |
+| **C4: Multi-Agent Scalability** | 12-agent stress test, fleet health dashboard, bulk provisioning | `pnpm stress-test` (12 agents, 76 ops, 0% errors) |
+
+### Key Differentiators
+- **1,106 passing tests** (zero-mock) — run `pnpm test` to verify
+- **18-tool MCP server** for Claude Desktop integration — `pnpm mcp`
+- **5-layer security**: FROST threshold → PolicyParticipant → PDA vault → Kora gasless → Jito MEV protection
+- **93 DeFi tools** via Solana Agent Kit v2 (vs typical 2–4)
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            WEB UI (Next.js)                              │
+│  Chat Interface │ Wallet Panel │ Portfolio │ Agent Monitor │ Analytics   │
+│  Activity Feed  │ Demo Launcher │ Strategy │ Backup        │ Lifecycle   │
+│  Security Tab: FROST Mgmt │ Audit Log Viewer │ Fleet Health │ Spending   │
+└───────────────────────────────────┬─────────────────────────────────────┘
+                                    │  HTTP + SSE
+┌───────────────────────────────────▼─────────────────────────────────────┐
+│                      SECURITY MIDDLEWARE (every route)                   │
+│  HMAC-SHA256 Request Signing  │  Per-IP Rate Limiter  │  Audit Logger   │
+│  Spending Limit Enforcement   │  Agent Lifecycle Gate │  Input Sanit.   │
+└───────────────────────────────────┬─────────────────────────────────────┘
+                                    │
+┌───────────────────────────────────▼─────────────────────────────────────┐
+│                              AGENT CORE                                  │
+│  LLM Provider (Claude / GPT-4)    Solana Agent Kit v2 (93 DeFi Tools)   │
+│  Multi-step Tool Chaining         Success Detection Pipeline             │
+│  Strategy Presets (3 risk levels) Per-Agent SSE Event Bus               │
+└───────────────────────────────────┬─────────────────────────────────────┘
+                                    │
+┌───────────────────────────────────▼─────────────────────────────────────┐
+│                           WALLET LAYER                                   │
+│  WalletManager: AES-256-GCM + scrypt KDF                                 │
+│  KeypairWallet: Ed25519 signing, devnet airdrop, SPL token support       │
+│  Isolated per-agent state: keypair, tx log, spending ledger, lifecycle   │
+└──────────────────┬────────────────────────────────┬─────────────────────┘
+                   │ direct SOL fees                │ gasless (Kora)
+                   │                                │
+                   │         ┌──────────────────────▼──────────────────┐
+                   │         │          KORA PAYMASTER (optional)      │
+                   │         │  Fee Payer Co-signing │ Token Fee Mode  │
+                   │         │  Sponsored (free) │ Margin │ Fixed      │
+                   │         └──────────────────────┬──────────────────┘
+                   │                                │
+┌──────────────────▼────────────────────────────────▼─────────────────────┐
+│                           SOLANA DEVNET                                  │
+│  Jupiter │ Orca │ Raydium │ Drift │ Lulo │ Meteora │ Pyth │ deBridge    │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start (Under 3 Minutes)
+
+> **No API key?** Skip to the [Headless Demo](#headless-demo-no-browser-required) below — runs the full wallet + FROST demo without any external keys.
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm (`npm i -g pnpm`)
+
+### Setup
+
+```bash
+# 1. Install dependencies
+pnpm install
+
+# 2. Copy environment config
+cp .env.example .env
+
+# 3. Generate a wallet encryption key
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# → paste the output as WALLET_ENCRYPTION_KEY in .env
+
+# 4. Add your LLM API key to .env (optional — headless demo works without it)
+# ANTHROPIC_API_KEY=sk-ant-api03-{your-key-here}
+
+# 5. Start the web app
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+### First 2 Minutes
+
+Once the app is running:
+
+1. Click **Create New Wallet** in the left sidebar — the agent wallet is created and auto-funded with devnet SOL
+2. In the empty chat area, click the green **DeFi Explorer** demo card
+3. Watch the **Activity Feed** (bottom of page) stream live tool calls and transaction signatures in real time
+4. Click any transaction signature → opens directly in **Solana Explorer** on devnet (every TX is a clickable link to the explorer)
+
+### Headless Demo (No Browser Required)
+
+```bash
+# Wallet + airdrop + on-chain verify — NO API key needed
+SKIP_LLM=1 pnpm headless-demo
+
+# FROST threshold signing demo — NO API key needed
+pnpm frost-demo
+
+# Full 7-phase demo with autonomous LLM execution (requires ANTHROPIC_API_KEY)
+pnpm headless-demo
+```
+
+### Gasless Transactions (Optional — Kora Paymaster)
+
+To enable gasless transactions where agents don't need SOL for fees:
+
+```bash
+# 1. Start the Kora paymaster server (requires Rust toolchain or Docker)
+cd ../kora_server && chmod +x setup.sh && ./setup.sh
+
+# 2. Add to .env
+KORA_ENDPOINT=http://localhost:8080
+KORA_FEE_MODE=sponsored
+```
+
+See [kora_server/README.md](../kora_server/README.md) for full setup details.
+
+### Multi-Agent Scalability Test
+
+```bash
+pnpm stress-test                 # 12 concurrent agents, 76 ops, 0% errors — empirical proof
+STRESS_AGENTS=20 pnpm stress-test  # Scale to 20 agents
+```
+
+### CLI Mode
+
+```bash
+pnpm cli
+```
+
+---
+
+## Features
+
+### Autonomous Agent Wallet (C1)
+
+- **Programmatic wallet creation** — `Keypair.generate()` with automatic devnet airdrop on creation
+- **AES-256-GCM encrypted key storage** — per-wallet scrypt salt, stored at rest on disk
+- **Automatic transaction signing** — no human approval required; agent signs and submits
+- **93 DeFi tools** via Solana Agent Kit v2 (TokenPlugin + DefiPlugin)
+- **Multi-step tool chaining** — up to 10 sequential tool calls per LLM request
+- **Natural language → on-chain execution** — "swap 0.1 SOL for USDC" → Jupiter swap tx
+- **Real-time SSE activity feed** — live streaming of every tool call, tx signature, and balance change as they happen
+- **One-click demo mode** — 3 pre-built autonomous DeFi scenarios; spawns wallet, funds it, and executes strategy while you watch
+- **Portfolio view** — aggregate SOL + SPL holdings across all agent wallets with USD values (Jupiter Price API)
+- **Transaction analytics dashboard** — success/failure rates, SOL spent, tool usage charts, hourly timeline
+- **Security tab** — dedicated sidebar panel with FROST wallet management, HMAC-chained audit log viewer with integrity verification, fleet health dashboard (grade distribution, agents needing attention), and per-wallet spending limits editor
+
+### Security & Key Management (C2)
+
+- **AES-256-GCM encryption** — all private keys encrypted at rest; GCM auth tag detects ciphertext tampering
+- **scrypt key derivation** — N=2^14 storage, N=2^17 backup; memory-hard against brute force
+- **HMAC-SHA256 request signing** — every write/delete request signed with a derived key; replays blocked via 5-minute window
+- **Per-IP sliding-window rate limiting** — 12 per-bucket presets; prevents API abuse and DoS
+- **Spending limits** — configurable max SOL per-transaction and per-day per agent; blocks over-budget tool calls
+- **HMAC-chained audit log** — append-only JSONL with each entry hashing the previous; tamper detection via `verifyAuditIntegrity()`
+- **Password-protected wallet backup** — export encrypted JSON, restore from file; scrypt N=2^17 for strong backup protection
+- **Agent lifecycle enforcement** — paused/terminated agents are blocked from executing at the API level (403 AGENT_NOT_ACTIVE)
+- **Input sanitization** — HTML/XSS stripped from labels, wallet IDs validated by strict hex regex, JSON parse errors handled gracefully
+- **FROST threshold signing (RFC 9591)** — 2-of-3 Ed25519 threshold signatures; no single key compromise can sign
+- **PolicyParticipant enforcement** — 5 independent checks (program allowlist, per-tx/daily limits, intent matching, suspicious patterns, cooldown)
+- **Proactive share refresh** — rotate key shares without changing on-chain address; forward secrecy
+- **PDA Vault (on-chain)** — Anchor program enforces spending limits and program allowlists at the Solana runtime level
+- **Jito MEV protection** — bundle submission bypasses public mempool to prevent sandwich attacks (mainnet-beta only; devnet transactions use standard RPC submission)
+- **Kora gasless transactions** — optional paymaster co-signing; agents transact without holding SOL for fees. Supports sponsored (free), margin, and fixed token fee modes. See `kora_server/` for local setup.
+
+### Documentation & Deep Dive (C3)
+
+- [DEEP_DIVE.md](./DEEP_DIVE.md) — 1,700+ line architecture deep dive with 22 Mermaid diagrams (17 sections):
+  - System overview, separation of concerns, multi-agent isolation, key management flow
+  - Transaction signing sequence, HMAC authentication flow, wallet backup pipeline
+  - Agent lifecycle state machine, real-time event architecture, threat model visualization
+  - Section 12: FROST threshold signing architecture | Section 13: Threat model progression
+  - Section 14: Why this is a spending account | Section 15: Prompt injection defense
+  - Section 16: Transaction lifecycle (CU simulation, commitment strategy, retry)
+  - **Section 17: Full system architecture — the 5-layer defense-in-depth synthesizing argument**
+- [SECURITY.md](./SECURITY.md) — Full STRIDE threat model, 12 mitigated threats (T1–T12), 5 accepted risks, cryptographic inventory table, attack surface map, production hardening roadmap
+- [BENCHMARK.md](./BENCHMARK.md) — Stress test results: 12 concurrent agents, 76 ops, **0% error rate**, 1.8s total, wallet isolation proof, memory profile, extrapolation to 100+ agents
+- [SKILLS.md](./SKILLS.md) — Complete agent capability catalog (93 tools across 11 categories) for judges/agents to read
+- [VIDEO_SCRIPT.md](./VIDEO_SCRIPT.md) — Structured 7-scene, 5-minute demo recording script
+- [DEMO.md](./DEMO.md) — Judge-friendly walkthrough of all demo scripts
+
+### Multi-Agent Scalability (C4)
+
+- **Independent wallet isolation** — each agent has its own keypair, RPC context, tx log, spending ledger, strategy config, and lifecycle state; cryptographically verified (see [BENCHMARK.md](./BENCHMARK.md))
+- **Agent monitoring dashboard** — live view of all agents: balance, status (idle/executing/error/paused/terminated), last action, daily spending bar, success rate
+- **Agent lifecycle management** — pause, resume, or terminate agents with proper cleanup; terminated is terminal; transition history persisted
+- **Agent-to-agent transfers** — one agent can send SOL or SPL tokens to another agent's wallet; lifecycle and spending checks enforced
+- **Strategy presets** — conservative / balanced / aggressive risk profiles; affects slippage, max position size, leverage rules, protocol selection
+- **Stress test** — `pnpm stress-test` spawns 12 concurrent agents, runs 7 phases (create, airdrop, balance, transfers, lifecycle, strategy, monitoring); **76 ops / 0 failures / 1.8s** on Solana devnet; see [BENCHMARK.md](./BENCHMARK.md) for full results
+
+### UI/UX Polish
+
+- **Dark/light theme toggle** — CSS variable system with localStorage persistence, FOUC-free SSR
+- **Loading skeletons** — shimmer placeholders for wallet panel, portfolio, agent monitor, analytics
+- **Toast notifications** — success/error/info toasts for every user action (wallet create, airdrop, strategy change, backup, transfer, lifecycle transition)
+- **Copy-to-clipboard** — animated clipboard → checkmark for wallet addresses, tx signatures, mint addresses
+- **Solana Explorer deep links** — every tx signature and wallet address links to Solana Explorer with correct cluster
+- **Mobile responsive layout** — tested on iOS (safe area insets, `h-dvh`, 16px input zoom prevention)
+
+---
+
+## MCP Server (Model Context Protocol)
+
+Expose all wallet and agent management tools to Claude Desktop, Cursor, or any MCP-compatible client.
+
+```bash
+# Start the MCP server
+WALLET_ENCRYPTION_KEY=<key> pnpm mcp
+```
+
+**Claude Desktop config** (`~/.claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "stng-defi": {
+      "command": "npx",
+      "args": ["tsx", "src/mcp/server.ts"],
+      "cwd": "/path/to/stng_defi_wallets",
+      "env": {
+        "WALLET_ENCRYPTION_KEY": "<your-key>",
+        "SOLANA_RPC_URL": "https://api.devnet.solana.com"
+      }
+    }
+  }
+}
+```
+
+**18 tools** across 5 categories: wallet operations, FROST threshold signing, agent lifecycle management, spending & security controls, and portfolio analytics.
+
+**5 guided prompts**: portfolio overview, security audit, agent creation, fleet health check, and wallet investigation.
+
+---
+
+## API Reference
+
+All write/delete endpoints verify HMAC-SHA256 signatures when `X-Signature` header is present. All endpoints are rate-limited per-IP.
+
+**Interactive docs:** `GET /api/openapi` returns the full OpenAPI 3.0 spec. Open `/api-docs` in the browser for Swagger UI (try any endpoint with one click).
+
+### Infrastructure
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/health` | RPC status, wallet count, LLM provider info |
+| GET | `/api/events` | SSE stream of agent events (`?walletId=` for per-wallet filter) |
+| GET | `/api/auth/signing-key` | Fetch derived HMAC signing key for request authentication |
+| GET | `/api/openapi` | OpenAPI 3.0 specification (JSON) — import into Postman/Insomnia |
+
+### Wallets
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/wallet` | List all wallets with labels |
+| POST | `/api/wallet` | Create wallet. Body: `{ "label": "name" }` — auto-airdrops devnet SOL |
+| GET | `/api/wallet/:id` | Wallet details: SOL balance, SPL token list |
+| DELETE | `/api/wallet/:id` | Delete wallet and all associated data |
+| POST | `/api/wallet/:id?action=airdrop` | Request devnet SOL. Body: `{ "amount": 1 }` |
+| GET | `/api/wallet/:id/history` | Paginated transaction history |
+| GET | `/api/wallet/:id/limits` | Get spending limits (maxPerTx, maxPerDay, dailySpent) |
+| PUT | `/api/wallet/:id/limits` | Update spending limits. Body: `{ "maxPerTx": 0.5, "maxPerDay": 2 }` |
+| GET | `/api/wallet/:id/strategy` | Get risk strategy (conservative/balanced/aggressive) |
+| PUT | `/api/wallet/:id/strategy` | Set strategy. Body: `{ "strategyId": "conservative" }` |
+| POST | `/api/wallet/:id/backup` | Export password-protected encrypted backup |
+| PUT | `/api/wallet/:id/backup` | Restore wallet from backup file + password |
+| POST | `/api/wallet/:id?action=rekey` | Re-encrypt wallet with fresh salt + IV (forward secrecy) |
+
+### Agents
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/agents` | List all agents with SOL balances |
+| POST | `/api/agents` | Spawn agent. Body: `{ "label": "Bot Name" }` — auto-airdrops |
+| POST | `/api/agents/bulk` | Batch-create up to 20 agents. Body: `{ "labels": ["Bot1", "Bot2"] }` — returns array of walletIds |
+| GET | `/api/agents/monitor` | Full monitoring data. Params: `?status=active&strategy=conservative&limit=10` |
+| POST | `/api/agents/transfer` | Agent-to-agent transfer. Body: `{ "fromAgent", "toAgent", "amount", "mint?" }` |
+| GET | `/api/agents/:id/lifecycle` | Get lifecycle state and transition history |
+| PUT | `/api/agents/:id/lifecycle` | Transition state. Body: `{ "state": "paused" \| "active" \| "terminated" }` |
+| POST | `/api/agents/:id/run` | Trigger one autonomous execution cycle — no human prompt needed |
+| GET | `/api/agents/health-summary` | Aggregate security health across all agents: avg score, grade distribution, attention list |
+
+### FROST Threshold Signing
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/frost` | List all FROST wallets (metadata only) |
+| POST | `/api/frost` | Create FROST wallet. Body: `{ "threshold": 2, "totalShares": 3, "labels": [...] }` |
+| GET | `/api/frost/:id` | Get FROST wallet details + security health |
+| DELETE | `/api/frost/:id` | Delete FROST wallet and all encrypted shares |
+| POST | `/api/frost/:id/sign` | Execute FROST signing ceremony. Body: `{ "message", "participantIds", "intent?" }` |
+| POST | `/api/frost/:id/refresh` | Refresh shares (proactive key rotation) — group key unchanged |
+
+### Kora Gasless Transactions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/kora/status` | Kora paymaster status: enabled/disabled, fee mode, payer address, supported tokens |
+| POST | `/api/kora/estimate` | Estimate transaction fee. Body: `{ "transaction": "<base64>", "feeToken?": "<mint>" }` |
+| POST | `/api/frost/:id/sign-kora` | FROST sign + Kora co-sign and submit. Body: `{ "transaction", "participantIds", "intent?", "feeToken?" }` |
+
+### Chat & Operations
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/chat` | Streaming chat (SSE). Body: `{ "messages": [...], "walletId": "abc" }` |
+| GET | `/api/demo` | List available demo scenarios |
+| POST | `/api/demo` | Launch demo. Body: `{ "scenarioId": "defi-explorer" }` |
+| GET | `/api/portfolio` | Aggregate portfolio: total USD value, per-wallet holdings, allocation |
+| GET | `/api/analytics` | Usage analytics. Params: `?walletId=&hours=24` |
+| GET | `/api/audit` | Audit log. Params: `?action=&walletId=&verify=true&limit=50&offset=0` |
+
+---
+
+## Multi-Agent Example
+
+```bash
+# Spawn two independent agents
+curl -X POST localhost:3000/api/agents \
+  -H 'Content-Type: application/json' \
+  -d '{"label": "Trading Bot"}'
+# → { "walletId": "abc123", "publicKey": "..." }
+
+curl -X POST localhost:3000/api/agents \
+  -H 'Content-Type: application/json' \
+  -d '{"label": "LP Manager"}'
+# → { "walletId": "def456", "publicKey": "..." }
+
+# Each agent operates independently with full isolation
+curl -X POST localhost:3000/api/chat \
+  -H 'Content-Type: application/json' \
+  -d '{"walletId": "abc123", "messages": [{"role":"user","content":"Check my balance and swap 0.05 SOL for USDC"}]}'
+
+curl -X POST localhost:3000/api/chat \
+  -H 'Content-Type: application/json' \
+  -d '{"walletId": "def456", "messages": [{"role":"user","content":"Stake 0.1 SOL via Jupiter"}]}'
+
+# Agent-to-agent transfer
+curl -X POST localhost:3000/api/agents/transfer \
+  -H 'Content-Type: application/json' \
+  -d '{"fromAgent": "abc123", "toAgent": "def456", "amount": 0.01}'
+
+# Pause a misbehaving agent
+curl -X PUT localhost:3000/api/agents/abc123/lifecycle \
+  -H 'Content-Type: application/json' \
+  -d '{"state": "paused"}'
+
+# Monitor all agents
+curl localhost:3000/api/agents/monitor
+```
+
+---
+
+## Demo Mode
+
+Three pre-built autonomous scenarios launch with one click (UI or API):
+
+| Scenario | Strategy | Description |
+|----------|----------|-------------|
+| `defi-explorer` | Balanced | Check balance, fetch SOL price, swap to USDC, summarize portfolio |
+| `multi-protocol` | Balanced | Diversify across staking, swaps, and liquidity provision |
+| `trading-bot` | Aggressive | Market analysis, conditional trades, position reporting |
+
+```bash
+# List scenarios
+curl localhost:3000/api/demo
+
+# Launch a scenario (creates wallet, airdrops, sets strategy, returns prompt)
+curl -X POST localhost:3000/api/demo \
+  -H 'Content-Type: application/json' \
+  -d '{"scenarioId": "trading-bot"}'
+```
+
+---
+
+## Running the Demos
+
+```bash
+# Basic demo: wallet creation + airdrop + transaction signing
+pnpm demo
+
+# DeFi demo: AI agent autonomously executes multi-step DeFi operations
+pnpm demo:defi
+
+# Multi-agent demo: 3 concurrent agents with timing + memory metrics
+pnpm demo:multi
+
+# Stress test: 12 concurrent agents across 7 phases, with isolation verification
+pnpm stress-test
+# Override agent count: STRESS_AGENTS=20 pnpm stress-test
+```
+
+See [DEMO.md](./DEMO.md) for a detailed judge-friendly walkthrough.
+
+---
+
+## Test Suite
+
+```bash
+# Unit + API tests (~4s)
+pnpm test
+
+# With V8 coverage report
+pnpm test --coverage
+
+# On-chain tests against local validator (requires solana-test-validator)
+pnpm validator:start && pnpm test:localnet
+
+# E2E tests with Playwright (16 specs — requires dev server)
+pnpm test:e2e
+
+# Integration tests against devnet (requires RUN_INTEGRATION=1)
+pnpm test:integration
+
+# Type check only
+pnpm typecheck
+
+# Production build
+pnpm build
+```
+
+**Test breakdown (1,000+ total across 4 layers, zero mocks):**
+
+| Layer | Tests | Files | What it covers |
+|-------|------:|------:|----------------|
+| Unit + API (Vitest) | 743 | 44 | Core library, API routes, tool count, stress-lite — **zero mocks** |
+| FROST (Vitest) | 140 | 11 | Key management, ceremony, signer, policy, nonce, vault, share refresh, SATI, refresh triggers, e2e |
+| Kora (Vitest) | 19 | 4 | Config, client, transaction prep, FROST+Kora adapter, gasless on-chain SOL transfers |
+| Localnet (Vitest) | 40 | 6 | Real SOL transfers, balance queries, airdrops, health, full 17-phase workflow, **12 LLM vulnerability tests** — against `solana-test-validator` |
+| E2E (Playwright) | 16 | 1 | Wallet creation → airdrop → chat → on-chain verification |
+| Integration (devnet) | 55+ | 1 | Airdrop, SOL transfer, multi-agent, DeFi tool invocation via Solana Agent Kit |
+
+Run localnet tests: `pnpm test:localnet` (requires `solana-test-validator`)
+Run integration tests (requires devnet RPC): `pnpm test:integration`
+
+**CI/CD:** GitHub Actions pipeline runs lint → test → typecheck → build → E2E on every push to main.
+
+Test categories:
+- Wallet encryption/decryption (AES-256-GCM, scrypt, round-trips, tamper detection)
+- Wallet CRUD and multi-agent isolation
+- Rate limiter logic, per-bucket presets, memory management
+- Spending limits enforcement, daily window, SOL extraction
+- HMAC request signing (sign, verify, replay protection, timing-safe compare)
+- Audit log integrity chain (HMAC, filtering, pagination)
+- Agent lifecycle state machine (transitions, terminal state, executable gate)
+- Agent-to-agent transfer validation, lifecycle + spending guards
+- Agent monitor aggregation, status derivation, sorting
+- Portfolio aggregation, Jupiter price integration, allocation calc
+- Analytics (time series, category breakdown, top tools, wallet activity)
+- Demo scenarios (data integrity, prompt quality, strategy assignments)
+- SSE event bus (client management, wallet filtering, reconnect, keep-alive)
+- Toast notifications, copy button, loading skeletons (jsdom)
+- Theme system, mobile responsive layout (jsdom)
+- Error boundaries: RPC down, empty wallet, rate limit, lifecycle block, missing env
+- E2E: full wallet → airdrop → chat → on-chain verification (Playwright)
+
+---
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for the full threat model. Key properties:
+
+| Property | Implementation |
+|----------|----------------|
+| Key storage | AES-256-GCM + scrypt (N=2^14, r=8, p=1) per-wallet salt |
+| Key export | Never — no API endpoint reads raw private key bytes |
+| Key re-encryption | `POST /api/wallet/:id?action=rekey` rotates salt+IV; old ciphertext becomes stale |
+| Backup | AES-256-GCM + scrypt (N=2^17) under user password |
+| API authentication | HMAC-SHA256 + 5-minute replay window |
+| Rate limiting | Per-IP sliding window, 12 per-bucket presets |
+| Spending controls | Configurable per-tx + per-day SOL caps, enforced server-side |
+| Audit trail | HMAC-SHA256 integrity chain, append-only JSONL |
+| FROST threshold signing | 2-of-3 RFC 9591 shares — no single point of compromise |
+| PolicyParticipant | Independent TX validation: program allowlist, spending limits, intent matching |
+| PDA Vault | Anchor program enforces on-chain spending limits and CPI allowlist |
+| Gasless transactions | Kora paymaster co-signs as fee payer; agents don't need SOL for gas |
+| Prompt injection defense | PolicyParticipant validates TX semantics, not natural language (see SECURITY.md §6) |
+| Agent isolation | Separate keypair, RPC context, ledger, lifecycle state per agent |
+| Path traversal | Wallet IDs validated as 8-char hex by strict regex before any file I/O |
+| XSS prevention | HTML stripped from all user-supplied labels |
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | Next.js 15 (App Router) |
+| AI | Vercel AI SDK 4 (`streamText`, `useChat`, `maxSteps: 10`) |
+| Solana | solana-agent-kit 2.0 — TokenPlugin (26 tools) + DefiPlugin (70 tools) |
+| Encryption | Node.js `crypto` — AES-256-GCM, scrypt KDF |
+| FROST | `@substrate-system/frost` v0.0.9 — RFC 9591 Ed25519 threshold signatures |
+| Gasless Txs | Kora paymaster (`@solana/kora` SDK) — fee payer co-signing, token fee abstraction |
+| On-chain | 2 Anchor programs — `agent_vault` (PDA policy) + `agent_sati` (on-chain identity) |
+| UI | React 19, Tailwind CSS 4, pure SVG charts |
+| Testing | Vitest (unit), Playwright (E2E), @vitest/coverage-v8 |
+| CI/CD | GitHub Actions — lint, test, typecheck, build, E2E |
+| Runtime | Node.js 22, pnpm 9 |
+
+---
+
+## Documentation
+
+| File | Contents |
+|------|----------|
+| [DEMO.md](./DEMO.md) | Judge-friendly demo walkthrough (start here) |
+| [DEEP_DIVE.md](./DEEP_DIVE.md) | 1,500+ line architecture deep dive with 22 Mermaid diagrams |
+| [SECURITY.md](./SECURITY.md) | STRIDE threat model, cryptographic inventory, attack surface map |
+| [BENCHMARK.md](./BENCHMARK.md) | Stress test: 12 agents, 76 ops, 0% errors, 1.8s, isolation proof |
+| [SKILLS.md](./SKILLS.md) | Complete agent capability catalog (93 tools, for agents to read) |
+| [VIDEO_SCRIPT.md](./VIDEO_SCRIPT.md) | 7-scene, 5-minute demo recording script |
+| `/api/openapi` | OpenAPI 3.0 JSON spec — import into Postman/Insomnia |
+| `/api-docs` | Interactive Swagger UI — try all 18 endpoints in the browser |