zola-ai

Zola AI — Technical Skills & Architecture

install

source · Clone the upstream repo

git clone https://github.com/Jeffreyxdev/zola-ai

manifest: SKILL.MD

source content

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/

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:

Open the dashboard at https://use-zola.vercel.app/
Connect your Phantom wallet
Click the Settings
Toggle between Mainnet and Devnet
The frontend calls
```
PUT /api/cluster
```
with the new value
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:

Switch to Devnet in Settings or via
```
/cluster devnet
```
in Telegram

Airdrop free devnet SOL:

solana airdrop 2 YOUR_WALLET_ADDRESS --url devnet

Or use faucet.solana.com

Run
```
/connect
```
in Telegram to import your devnet wallet key
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

# 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
Telegram Bot: @Zolaactive_bot
Twitter Bot: @use_zola
Built by: Synq Studio — Jeffrey Agabaenwere & Samuel Opeyemi

zola-ai

Zola AI — Technical Skills & Architecture

Hackathon Focus: Telegram vs. Twitter

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)

2. Secure Non-Custodial Key Management

3. Cluster Switching — Mainnet & Devnet

Web App (Settings)

Telegram (/cluster command)

How Cluster Flows Through the Stack

Devnet for Testing

4. Persistent Cluster-Aware Blockchain Monitoring

5. Full-Stack Architecture

Backend — FastAPI + Python

Frontend — React + Vite

Key Files

Environment Variables

🔗 Links

Telegram (
`/cluster`
command)