Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install zola-ai-technical-skills-architecturegit clone https://github.com/Jeffreyxdev/zola-ai.gitcp -r zola-ai/ ~/.claude/skills/zola-ai-technical-skills-architecture/# Zola AI — Technical Skills & Architecture
> **Hackathon Judges**: This document covers Zola AI's core technical achievements, architecture decisions, and the cluster-switching system. Live demo: [use-zola.vercel.app/](https://use-zola.vercel.app/)
---
## Hackathon Focus: Telegram vs. Twitter
While Zola is designed as a multi-platform autonomous DeFi agent, **our primary focus for this hackathon was the Telegram integration**.
- **Telegram (`telegram_bot.py`)**: Fully implemented, rigorously tested, and serves as our primary interactive interface. Features secure deep-linking, a `/connect` flow that auto-deletes sensitive messages, and full agentic execution.
- **Twitter (`twitter_bot.py`)**: Fully functional in code. Uses a robust Tweepy v2 polling engine and shares the *exact same* Gemini agentic execution pipeline as Telegram. Currently untested live due to pending Twitter Developer API credits — the architecture guarantees identical behaviour to Telegram once credits are applied.
the core ai engine has 2 main agents one for security and the other for onchain executions what work hand in hand simultaneously
---
## 1. Agentic AI Integration (Gemini 2.0 Flash Lite)
We moved beyond simple intent parsing and built a true **Autonomous Agent** using `gemini-2.0-flash-lite`.
- **Native Tool Calling**: Gemini is given direct access to Python functions (`send_sol`, `jupiter_swap`, `get_balance`, `setup_dca`, `setup_monitor`). It autonomously decides when to call them, formats arguments, executes on-chain actions, and processes results before replying to the user — no manual routing required.
- **Context Injection**: `_run_agentic_loop` invisibly injects the user's active Solana cluster (`mainnet-beta` / `devnet`) and signing key status into every prompt. Gemini always has real-time context without ever asking the user for it.
- **Security-Hardened Prompt**: The system prompt contains immutable rules that block prompt injection, role reversal, and any attempt to extract private keys through conversation.
- **Agentic Loop**: Gemini runs up to 6 tool-call rounds per message. Each round dispatches tool calls in parallel, feeds results back into the conversation history, and continues until Gemini returns plain text.
---
## 2. Secure Non-Custodial Key Management
Handling private keys securely in a Python backend was a top priority.
- **AES-256 Encryption**: `wallet_store.py` uses `cryptography.fernet` (AES-128-CBC with HMAC-SHA256). When a user runs `/connect` in Telegram, the private key is immediately encrypted and stored as a BLOB in SQLite — never written to disk in plain text.
- **Key Validation**: Before storing, the key is validated against the user's Phantom-connected public key. If they don't match, the import is rejected with a clear error.
- **Zero AI Exposure**: `_get_keypair()` decrypts the key locally at the point of signing. The LLM never sees the private key — it only receives tool call results like `{"status": "success", "signature": "..."}`.
- **Auto-Cleanup**: The Telegram bot immediately deletes the user's `/connect` message from chat history, preventing shoulder-surfing or accidental exposure in shared screens.
- **Fallback Chain**: `_get_keypair(wallet)` first checks the per-user encrypted store, then falls back to the `WALLET_PRIVKEY` env var, then returns `None` — triggering a user-friendly message to run `/connect`.
---
## 3. Cluster Switching — Mainnet & Devnet
Zola supports live switching between Solana `mainnet-beta` and `devnet` without restarting. The active cluster is stored per-user in the database and respected by every component.
### Web App (Settings)
In the Zola dashboard, users can switch clusters from the **Settings panel**:
1. Open the dashboard at [https://use-zola.vercel.app/](https://use-zola.vercel.app/)
2. Connect your Phantom wallet
3. Click the **Settings**
4. Toggle between **Mainnet** and **Devnet**
5. The frontend calls `PUT /api/cluster` with the new value
6. The backend updates the user's DB row and live monitor instantly — no reconnect needed
```
Frontend toggle
↓
PUT /api/cluster { wallet, cluster: "devnet" }
↓
db.upsert_user(wallet, cluster="devnet")
solana_monitor.update_cluster(wallet, "devnet")
↓
All subsequent RPC calls, tx signing, and WebSocket feeds use devnet
```
### Telegram (`/cluster` command)
Users can also switch cluster directly in Telegram:
```
/cluster — shows current cluster + inline buttons
/cluster devnet — switches to devnet immediately
/cluster mainnet — switches to mainnet-beta immediately
```
The bot calls `PUT /api/cluster` on the backend, so the web app and Telegram always stay in sync — switching in one place updates the other.
### How Cluster Flows Through the Stack
```
User sets cluster (web or Telegram)
↓
DB: users.cluster = "devnet" | "mainnet-beta"
↓
_run_agentic_loop injects cluster into Gemini context
↓
_get_rpc_url(cluster) routes all RPC calls to correct endpoint
↓
_tool_send_sol / _tool_get_balance / _tool_setup_monitor all respect cluster
↓
solana_monitor.update_cluster() switches live WebSocket feed
↓
Frontend WebSocket feed updates in real-time
```
### Devnet for Testing
To test Zola end-to-end without real funds:
1. Switch to **Devnet** in Settings or via `/cluster devnet` in Telegram
2. Airdrop free devnet SOL:
```bash
solana airdrop 2 YOUR_WALLET_ADDRESS --url devnet
```
Or use [faucet.solana.com](https://faucet.solana.com)
3. Run `/connect` in Telegram to import your devnet wallet key
4. Send commands normally — all transactions go to devnet RPC
> Jupiter swaps only work on `mainnet-beta`. Devnet is best for SOL transfers, balance checks, DCA setup, and monitoring.
---
## 4. Persistent Cluster-Aware Blockchain Monitoring
`solana_monitor.py` bridges real-time on-chain events with Telegram and the web frontend.
- **WebSocket `logsSubscribe`**: The backend maintains persistent WebSocket connections to Solana RPCs for every registered wallet. Works on both mainnet and devnet endpoints.
- **Independent of Frontend**: Even if the user closes the React app, the backend monitor continues running, ensuring Telegram notifications fire 24/7 for inbound and outbound transfers.
- **Delta Polling Fallback**: A 30-second balance delta polling loop runs alongside WebSocket monitoring as a robust fallback — guaranteeing users are notified of balance changes that standard RPC logs occasionally miss (common with internal SPL transfers).
- **Live Cluster Switch**: `solana_monitor.update_cluster(wallet, cluster)` re-subscribes the wallet's WebSocket feed to the new RPC endpoint without dropping the connection.
---
## 5. Full-Stack Architecture
### Backend — FastAPI + Python
- Async Python server managing concurrent WebSocket streams, polling loops, and REST endpoints simultaneously
- `aiosqlite` for async SQLite — clean abstraction designed to swap to PostgreSQL with minimal changes
- Background tasks: hourly autonomous scan loop, 30-second monitor tick, DCA scheduler
- Endpoints: `POST /api/link-wallet`, `PUT /api/cluster`, `POST /api/link-telegram`, `GET /api/status/{wallet}`, `GET /api/activity/{wallet}`, `POST /api/bot/command`, `WS /ws/{wallet}`
### Frontend — React + Vite
- Terminal-inspired responsive UI
- Phantom / Solflare wallet connection via Wallet Adapter
- Telegram and Twitter deep-linking with one-time code polling
- Real-time WebSocket feed rendering on-chain activity as it happens
- Settings panel for cluster switching, wallet info, and connection management
### Key Files
| File | Role |
|---|---|
| `gemini_brain.py` | Agentic AI loop, tool dispatch, market analysis |
| `wallet_store.py` | AES-256 key encryption and SQLite storage |
| `connect_handlers.py` | Telegram `/connect` conversation flow |
| `solana_monitor.py` | WebSocket + delta polling monitor |
| `dca_engine.py` | Scheduled DCA job runner |
| `db.py` | Async SQLite abstraction |
| `main.py` | FastAPI app, lifespan, background tasks |
| `telegram_bot.py` | Full Telegram bot with command handlers |
| `twitter_bot.py` | Tweepy v2 polling bot (same pipeline as TG) |
---
## Environment Variables
```bash
# Gemini
GEMINI_API_KEY=
GEMINI_MODEL=gemini-2.0-flash-lite
# Solana RPC
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_RPC_URL_FALLBACKS= # comma-separated additional endpoints to try on failure
SOLANA_RPC_URL_DEV=https://api.devnet.solana.com
> Backend RPC calls will attempt the primary URL and then any fallbacks in
> order. This guards against 403s/timeouts when a single public node is
> rate‑limited.
# Wallet Security
WALLET_ENCRYPTION_KEY= # generate: python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
WALLET_PRIVKEY= # optional bot-level fallback, leave empty for per-user keys
# Telegram
TELEGRAM_BOT_TOKEN=
TELEGRAM_BOT_USERNAME=Zolaactive_bot
# Twitter (Tweepy v2)
TWITTER_API_KEY=
TWITTER_API_SECRET=
TWITTER_ACCESS_TOKEN=
TWITTER_ACCESS_SECRET=
TWITTER_BEARER_TOKEN=
# App
DB_PATH=zola.db
CLUSTER=mainnet-beta # default cluster for new users
```
---
## 🔗 Links
- **Live Demo**: [use-zola.vercel.app](https://use-zola.vercel.app/)
- **Telegram Bot**: [@Zolaactive_bot](https://t.me/Zolaactive_bot)
- **Twitter Bot**: [@use_zola](https://x.com/use_zola)
- **Built by**: Synq Studio — Jeffrey Agabaenwere & Samuel Opeyemi