Skip to content

Architecture

Sarpoy pairs an off-chain experience (FastAPI backend + Nuxt frontend) with an on-chain Solana program that escrows prize pools and routes message fees. This document captures the component map, core data flows, and integration boundaries so every contributor understands how the pieces fit.

System Goals

  • Allow creators to deploy puzzle bots with on-chain treasuries and programmatic rules.
  • Let solvers converse with bots from any client while message fees and rewards are settled trustlessly.
  • Keep the architecture modular so API, UI, and Solana surfaces can evolve independently.

Component Map

Layer Service Key Responsibilities Status
Client sarpoy-ui (Nuxt 3) Wallet connect, chat UX, leaderboard, creator dashboards ✅ Implemented
API sarpoy-api (FastAPI) Auth, user/session management, bot lifecycle, chat accounting, leaderboard aggregation ✅ Implemented
Blockchain Solana Program (Anchor) Escrow deposits, enforce fee schedule, distribute rewards, emit events ✅ Compiles, pending devnet
Integrations Webhooks, RPC, analytics Notifies creators of solves, pushes telemetry to analytics 🔄 Future

Runtime View

  1. Wallet auth: UI obtains a signed nonce from FastAPI, verifies signature, and receives a short-lived JWT/session cookie.
  2. Bot creation: Creator configures metadata + Solana treasury deposit via UI. API stores metadata, invokes Solana program to lock funds, then marks bot live.
  3. Chat loop: Solvers pay the per-message fee on-chain, API validates payment proof, records the message, and proxies bot responses.
  4. Resolution: When a solver submits the winning answer, API checks business logic, sends a settlement instruction to Solana, and updates off-chain stats.
  5. Leaderboards & analytics: Aggregations run periodically and cache results for UI consumption.

Data Flows

  • Bot creation flow: sarpoy-ui → POST /api/v1/bots → FastAPI validates + writes SQLite + triggers Anchor instruction initialize_bot. Successful transaction ID stored with bot record.
  • Chat payment flow: sarpoy-ui instructs wallet to transfer lamports to program treasury. FastAPI polls Solana RPC, releases chat when confirmed, and records message.
  • Reward settlement flow: Solver submits solution, FastAPI confirms, submit_solution Anchor instruction fires, and off-chain bot_solutions row is persisted.
  • Telemetry flow: Structured events logged, can be exported to OpenTelemetry exporters.

Storage Plan

  • Development DB: SQLite with Aerich migrations. Configure via DATABASE_URL.
  • Production DB: PostgreSQL 15 with TortoiseORM migrations (Aerich).
  • Cache/Queue: Redis for rate limiting and background jobs (future).
  • Object storage: Future use for bot assets.

Solana Program (programs/sarpoy/src/lib.rs)

Instructions:
├── initialize_bot(bot_id, name, description, objective, initial_pot, base_cost, cost_multiplier)
├── send_message(bot_id)
├── submit_solution(bot_id, is_correct)
└── close_bot(bot_id)

Accounts:
├── Bot PDA (seeds: [b"bot", bot_id])
└── Treasury PDA (seeds: [b"treasury", bot_id])

Integration Surfaces

  • Solana RPC: Provided by https://api.devnet.solana.com in development, configurable via SOLANA_RPC_URL. For production adopt a dedicated provider (Helius, QuickNode).
  • Anchor IDL: Exposed to both FastAPI (SarpoyClient with inline IDL fallback) and UI.
  • REST API: FastAPI endpoints documented in sarpoy-api.md.

Non-Functional Requirements

  • Performance: P50 chat latency < 1s off-chain, with on-chain confirmation gating only when value transfers occur.
  • Security: Wallet signatures verified server-side, Solana program compiled, API uses rate limiting.
  • Observability: Structured logging, can be extended with OpenTelemetry.