Architecture | Solvela

Solvela is a Rust workspace composed of five focused crates, an on-chain Anchor escrow program, a set of multi-language SDKs, and a Next.js dashboard. Every inbound HTTP request is handled by a single binary — the gateway — which delegates to the other crates for routing logic, payment verification, and shared wire types.

Workspace Crates

gateway

The only binary in the workspace (solvela). Axum HTTP server with routes, middleware, provider proxies, usage tracking, Redis caching, and Prometheus metrics.

x402

Pure protocol library — no Axum dependency. Solana verification, escrow integration, fee payer pool, nonce pool, and the chain-agnostic PaymentVerifier trait.

router

15-dimension rule-based request scorer, routing profiles (eco / auto / premium / free), and model registry that loads config/models.toml.

protocol

Shared wire-format types (solvela-protocol). Payment protocol types, OpenAI-compatible chat types, model info, and constants. Zero workspace dependencies.

There is also a fifth crate — cli (solvela-cli) — providing wallet, chat, models, health, stats, and doctor commands for operators and developers.

Crate Dependency Graph

protocol (wire types, zero deps)
    ↑
    ├── x402 (Solana verification, escrow)
    ├── router (scorer, profiles, model registry)
    │
    └── gateway (Axum HTTP server — the only binary)
            ├── routes/chat/ (completions, cost, payment, provider)
            ├── middleware/ (rate limit, x402, API key, CORS)
            ├── providers/ (OpenAI, Anthropic, Google, xAI, DeepSeek)
            └── a2a/ (Agent-to-Agent protocol adapter)

protocol sits at the bottom and carries no internal dependencies — every other crate builds on top of it without creating circular imports.

Note

x402 deliberately has no Axum dependency. This keeps the payment verification logic portable and independently testable outside of any web framework.

Supporting Components

Component	Location	Purpose
Anchor escrow program	`programs/escrow/`	Trustless USDC-SPL escrow with deposit, claim, and refund — not a workspace member
Python SDK	`sdks/python/`	`solvela-sdk` package on PyPI
TypeScript SDK	`sdks/typescript/`	`@solvela/sdk` npm package
Go SDK	`sdks/go/`	`github.com/solvela-ai/solvela/sdks/go` Go module
MCP server	`sdks/mcp/`	Model Context Protocol adapter
Dashboard	`dashboard/`	Next.js 16 + Tailwind + Recharts, 5 pages

Configuration Files

Defines every available model: provider, context window, pricing, routing tier assignment, and aliases. The router crate loads this at startup. To add a model, add an entry here — no code changes needed.

Controls server bind address, timeout values, rate limit defaults, caching TTLs, and feature flags.

Provider API base URLs, Facilitator endpoint, and Redis/PostgreSQL connection strings. Override via environment variables in production.

Key Architectural Rules

Gateway is the only binary

All other crates are libraries. Only gateway exposes a network interface. This keeps deployment simple — one process, one binary.

x402 has no Axum dependency

Payment verification is framework-agnostic. The PaymentVerifier trait is chain-agnostic by design — EVM support can be added without touching the gateway.

Provider adapters own format translation

Each provider adapter translates between the OpenAI-compatible wire format (from protocol) and the native provider format. Callers never see provider-specific types.

5% platform fee on all requests

The fee is applied uniformly at the gateway layer before proxying. It is included in the cost breakdown returned on 402 responses.

Private keys never leave the client

The gateway never handles wallet private keys. All signing happens client-side; the gateway only receives and verifies the resulting transaction signature.

Database writes are fire-and-forget

Usage logging to PostgreSQL is done with tokio::spawn — it does not block the response path. Both PostgreSQL and Redis are optional; the gateway degrades gracefully without them.

Warning

PostgreSQL and Redis are optional but strongly recommended in production. Without Redis, replay protection and response caching are disabled. Without PostgreSQL, usage logs and spend tracking are lost.

Provider Support

The providers/ module inside gateway contains an adapter for each upstream LLM provider:

Provider	Models
OpenAI	GPT-4o, o3, o4-mini, and more
Anthropic	Claude Sonnet, Claude Opus, Claude Haiku
Google	Gemini 2.0 Flash, Gemini 2.5 Pro
xAI	Grok-3, Grok-3-mini
DeepSeek	DeepSeek-V3, DeepSeek-R1

Tip

All providers accept the same OpenAI-compatible request format. Switching models or providers requires only changing the model field — no client code changes needed.