| # SolVox — Voice-First Private AI Wallet for Solana |
|
|
| <div align="center"> |
|
|
|  |
|  |
|  |
|  |
|
|
| **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> |
|
|
