README.md

# SolVox — Voice-First Private AI Wallet for Solana

<div align="center">

![SolVox](https://img.shields.io/badge/SolVox-Voice_AI_Wallet-0052ff?style=for-the-badge&labelColor=0a0b0d)
![QVAC](https://img.shields.io/badge/QVAC_SDK-6_Modules-05b169?style=for-the-badge&labelColor=0a0b0d)
![Solana](https://img.shields.io/badge/Solana-Devnet_+_Mainnet-0052ff?style=for-the-badge&labelColor=0a0b0d)
![TypeScript](https://img.shields.io/badge/TypeScript-0_Errors-05b169?style=for-the-badge&labelColor=0a0b0d)

**A fully offline, voice-controlled Solana wallet where AI drives every operation.**

*No cloud. No API keys. No data leaves your device. QVAC is the brain, not a wrapper.*

</div>

---

## Hackathon: Colosseum Frontier — Tether QVAC Track

**Listing:** [superteam.fun/earn/listing/tether-frontier-hackathon-track](https://superteam.fun/earn/listing/tether-frontier-hackathon-track)

SolVox integrates **all 6 QVAC addon packages** as load-bearing components of a production wallet. The LLM is an autonomous agent that decides which wallet tools to call. Embeddings power contact resolution and transaction search. OCR chains into LLM for document-to-payment extraction. Every voice command fires all 6 modules in a single pipeline.

---

## Pages (10 screens)

| # | Page | Description | QVAC Modules Used |
|---|---|---|---|
| 1 | **Dashboard** | Dark hero band with floating product-UI cards, sparkline charts, asset rows with mono prices, QVAC engine status | embed (RAG) |
| 2 | **Voice AI** | Hold-to-speak with waveform visualizer, AI agent chat with pipeline trace, suggestion chips | All 6: STT → NMT → LLM → EMB → NMT → TTS |
| 3 | **Send** | Token pill selector, amount input with % buttons, AI risk assessment card, confirmation flow | LLM (risk), EMB (patterns) |
| 4 | **Scan & Pay** | Drag-drop image upload → OCR text extraction → LLM payment parsing → auto-fill transaction | OCR → LLM |
| 5 | **Contacts** | Semantic contact book — add contacts with notes, resolve by name/description via embeddings | EMB (cosine similarity) |
| 6 | **Transactions** | History with semantic AI search, asset-row pattern, status badges | EMB (RAG search) |
| 7 | **Security** | Transaction limits, toggle switches, address whitelist, AI anomaly detection log | LLM (anomaly analysis) |
| 8 | **Settings** | Network selector, QVAC model list with sizes, about section, danger zone | — |
| 9 | **Lock Screen** | PIN dot visualization, biometric support, encrypted vault | — |
| 10 | **Onboarding** | Step indicator, wallet create/import, PIN setup with AES-256-GCM | — |

---

## Deep QVAC Integration (40% of judging)

This is NOT a wrapper. QVAC drives the wallet:

### 1. Tool-Use Agent (`@qvac/llm-llamacpp`)
The LLM receives user commands and returns structured JSON with tool calls:
```
User: "Send 5 SOL to Alice"
→ LLM reasons: need to resolve contact first
→ Actions: [resolve_contact("Alice"), confirm_transaction(5, SOL, resolved_address)]
→ User confirms → ai:executeConfirmed → transaction sent + auto-indexed
```

### 2. Semantic Contact Book (`@qvac/embed-llamacpp`)
Contacts embedded with names + notes. "Send to my friend from the hackathon" resolves via cosine similarity — no exact match needed.

### 3. AI Risk Assessment (`@qvac/llm-llamacpp` + `@qvac/embed-llamacpp`)
Before every transaction, the LLM analyzes spending patterns from the embedded transaction history and generates a scored risk assessment with natural language reasoning.

### 4. Voice Pipeline (all 6 modules)
```
🎤 Audio → @qvac/transcription-whispercpp → text
        → @qvac/translation-nmtcpp → English (if non-English)
        → @qvac/llm-llamacpp → agent reasoning + tool calls
        → @qvac/embed-llamacpp → RAG context retrieval
        → @qvac/translation-nmtcpp → user's language
        → @qvac/tts-onnx → spoken response
```

### 5. Document-to-Payment (`@qvac/ocr-onnx` → `@qvac/llm-llamacpp`)
Upload invoice → OCR extracts text → LLM parses amount, recipient, token, memo → auto-fills transaction form.

### 6. Auto-Indexing RAG (`@qvac/embed-llamacpp`)
Every transaction auto-embeds on completion. The AI's knowledge grows with every interaction — entirely local.

---

## Security

- **OS keychain encryption** via Electron `safeStorage` + AES-256-GCM + PBKDF2 (600K iterations)
- **PIN + Touch ID** with 5-attempt lockout (15 min)
- **Transaction limits** — per-tx, daily volume, velocity, cooldown
- **Address whitelisting** — optional, restrict to approved addresses
- **AI anomaly detection** — LLM analyzes patterns, can block dangerous transactions
- **Process isolation** — `contextIsolation: true`, `sandbox: true`, `nodeIntegration: false`
- **CSP headers** block script injection, limit connections to Solana RPC only
- **Auto-lock** after 5 minutes idle
- **Zero key exposure** — private keys never cross IPC boundary

See [SECURITY.md](SECURITY.md) for full threat model.

---

## Design System

Coinbase-inspired institutional design:
- **Single accent color** — Coinbase Blue (#0052ff), used scarcely
- **White canvas** + hairline borders + dark hero bands
- **Pill geometry** — every CTA is rounded-pill (100px)
- **Inter** at weight 400 for display, **JetBrains Mono** for all numbers
- **96px section rhythm** — generous editorial pacing
- **Trading semantics** — green (#05b169) / red (#cf202f) for text only, never backgrounds

---

## Quick Start

```bash
git clone https://github.com/muthuk1/solvox.git
cd solvox
npm install
chmod +x scripts/download-models.sh && ./scripts/download-models.sh
npm run dev
```

### Models (~2.6 GB)
| Model | Package | Size |
|---|---|---|
| Llama 3.2 3B Instruct Q4_K_M | `@qvac/llm-llamacpp` | 2.0 GB |
| Nomic Embed Text v1.5 Q4_K_M | `@qvac/embed-llamacpp` | 260 MB |
| Whisper Base English | `@qvac/transcription-whispercpp` | 150 MB |
| Piper TTS Amy | `@qvac/tts-onnx` | 75 MB |
| OPUS MT EN↔ES | `@qvac/translation-nmtcpp` | 50 MB |
| PaddleOCR v4 | `@qvac/ocr-onnx` | 30 MB |

---

## Project Structure

```
solvox/
├── src/
│   ├── main/                         # Electron main process
│   │   ├── main.ts                   # Window, CSP, IPC handlers, agent execution
│   │   ├── preload.ts                # contextBridge — allowlisted IPC channels
│   │   ├── ai/qvacEngine.ts          # QVAC deep integration (33KB) — agent, RAG, risk, OCR pipeline
│   │   ├── wallet/walletService.ts   # Solana wallet (BIP39, SOL, USDT)
│   │   └── security/                 # KeyVault, SecurityManager, TransactionGuard
│   │
│   └── renderer/                     # React UI (Coinbase design)
│       ├── App.tsx                   # Router, toast system, auth flow
│       ├── types.ts                  # Preload bridge types (verified match)
│       ├── components/
│       │   ├── Sidebar.tsx           # 8-item nav, QVAC badge
│       │   ├── TopBar.tsx            # Address pill, mono balances
│       │   └── ui/index.tsx          # Toast, Num, AssetRow, Sparkline, PipelineTrace, StepIndicator
│       └── pages/
│           ├── Dashboard.tsx         # Dark hero, sparklines, AI status
│           ├── VoicePage.tsx         # Voice agent + chat + pipeline trace
│           ├── SendPage.tsx          # Send with AI risk assessment
│           ├── ScanPage.tsx          # OCR → LLM payment extraction (NEW)
│           ├── ContactsPage.tsx      # Semantic contact book (NEW)
│           ├── HistoryPage.tsx       # Transactions + RAG search
│           ├── SecurityPage.tsx      # Limits, toggles, whitelist, anomaly log
│           ├── SettingsPage.tsx      # Network, models, about
│           ├── LockScreen.tsx        # PIN dots, biometric
│           └── OnboardingScreen.tsx  # Create/import, PIN setup
│
├── models/                           # AI models (~2.6 GB, downloaded locally)
├── scripts/download-models.sh        # Model download script
├── SECURITY.md                       # Full threat model
└── package.json
```

**TypeScript: 0 errors** (verified with `tsc --noEmit`)

---

## Tech Stack

| Layer | Technology |
|---|---|
| App Shell | Electron 30 |
| Frontend | React 18 + TypeScript + TailwindCSS |
| Design | Coinbase design system (Inter + JetBrains Mono) |
| AI Runtime | QVAC SDK (all 6 addons) |
| GPU | Vulkan API (any GPU — no CUDA) |
| Blockchain | Solana (@solana/web3.js + @solana/spl-token) |
| Encryption | safeStorage + AES-256-GCM + PBKDF2 |
| Build | Vite 5 + electron-builder |

---

## License

MIT — see [LICENSE](LICENSE).

---

<div align="center">

**Built for Colosseum Frontier Hackathon — Tether QVAC Track**

*QVAC is the brain. Not the wrapper.*

</div>