# SolVox — Voice-First Private AI Wallet for Solana
**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.*
---
## 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).
---
**Built for Colosseum Frontier Hackathon — Tether QVAC Track**
*QVAC is the brain. Not the wrapper.*