sarpoy-api

May be out of date

This page lists Poetry as the package manager, but the project README and sarpoy-api/ actually use uv (uv sync, uv run). The "Modules" table also marks services and workers as "To be implemented" while the README reports the backend as implemented. Treat module-status flags as historical.

The backend service exposes REST + realtime endpoints for bot management, chat, leaderboards, and Solana settlement. This document spells out the technical decisions, modules, and near-term tasks required to evolve the current prototype into a production-ready service.

Stack

• FastAPI for HTTP + WebSocket endpoints.
• TortoiseORM with Aerich migrations on Postgres 15.
• Pydantic v2 schemas (shared with UI via generated TypeScript types).
• Redis for caching, rate limiting, and background jobs (RQ or Dramatiq).
• AnchorPy + solders for Solana RPC + program interactions.
• Poetry manages dependencies; Ruff + Black provide linting/formatting.

Modules

Module	Description	Status
sarpoy_api/api/api_v1	Versioned routers (bots, chats, auth, leaderboard, health)	Stubbed with in-memory data
sarpoy_api/core	Settings (pydantic-settings), logging, security, Solana clients	Implemented
sarpoy_api/db	Tortoise models + Aerich migrations (users, bots, sessions, tx)	Models defined, migrations pending
sarpoy_api/services	Business logic (bot creation, pricing, Solana orchestration)	To be implemented
sarpoy_api/workers	Background tasks for tx confirmation, payouts, webhooks	To be implemented

Data Model (Tortoise)

Table	Purpose	Key Fields
users	Wallet-based identities	address, network, username
bots	Puzzle bots + metadata	objective, initial_pot, current_pot, treasury_pda
chat_sessions	Solver <> bot conversations	current_cost, status, last_tx_sig
messages	Individual chat turns	is_user, cost, tx_sig, payload
bot_solutions	Winning submissions	solver_id, reward_amount, proof
network_transactions	Trace on/off-chain moves	tx_sig, direction, status, type

Each table gains audit timestamps (created_at, updated_at). Use composite indexes on (bot_id, created_at) and (solver_id, status) for query efficiency.

API Surface (v1)

Endpoint	Method	Description
/api/v1/auth/nonce	POST	Issue nonce for wallet signature
/api/v1/auth/session	POST	Verify signature and mint JWT/session
/api/v1/bots	GET/POST	List bots with filters / create new bot
/api/v1/bots/{id}	GET/PATCH	Fetch or update metadata (creator only)
/api/v1/chats/{bot_id}	GET	Fetch or initialize chat session
/api/v1/chats/{session_id}/messages	POST	Submit chat message + payment proof
/api/v1/leaderboard/{type}	GET	Aggregated creator/solver rankings
/api/v1/health	GET	DB + Solana RPC diagnostics
/ws/chats/{session_id}	WS	Real-time chat stream + payment updates

Generate OpenAPI from FastAPI and export to /docs/api.openapi.json for UI consumption.

Solana Integration

1. Program IDs: Track Devnet + Mainnet IDs via settings: SOLANA_PROGRAM_ID, SOLANA_RPC_URL, SOLANA_COMMITMENT.
2. Instructions: create_bot, record_message_fee, settle_reward, close_bot. Each instruction returns events with seeds for off-chain correlation.
3. Client abstraction: Wrap AnchorPy provider initialization in sarpoy_api/core/solana.py (or sarpoy_api/solana/client.py) and expose typed helpers for each instruction. Services call helpers and persist tx metadata.
4. Confirmation strategy: Start with RPC polling (get_signature_status), then upgrade to WebSocket subscription + backoff queue.
5. Error handling: Map Solana error codes to FastAPI HTTP errors with user-friendly messages.

Configuration (.env)

DATABASE_URL=postgres://user:pass@localhost:5432/sarpoy
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_PROGRAM_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
REDIS_URL=redis://localhost:6379/0
JWT_SECRET=change-me
ENV=development

Load via pydantic-settings. Guard secrets by using Doppler/Vault in production.

Testing Strategy

• Unit tests: Pytest for services, repositories, and helper utils (mock Solana client).
• Integration tests: Spin up Postgres + Redis via Docker Compose, run API tests hitting real DB.
• Localnet tests: Launch solana-test-validator, deploy Anchor program, and run end-to-end flows.
• Contract tests: Dredd/Newman runner ensures OpenAPI contract stays in sync with UI expectations.

Next Actions

1. Scaffold FastAPI project layout (sarpoy_api/api, sarpoy_api/core, sarpoy_api/services).
2. Port SQLAlchemy models to Tortoise + generate first Aerich migration.
3. Implement wallet auth endpoints and tests.
4. Build Solana client abstraction + mock for tests.
5. Ship bot CRUD and chat session endpoints with placeholder Solana validations.