IQ Labs

IQ Labs is a Solana application built around two primary workflows:

• uploading files into onchain session/storage accounts
• creating and publishing external data feeds onto Solana

This repository contains the web client, Django backend, supporting services, and Solana programs used by those workflows.

Overview

At the product level, the app is an upload dashboard with wallet-connected and managed-wallet modes, feed management tools, upload history, replay/download support, and a small set of account and inbox utilities around those flows.

At the system level, the repository is split into:

• a Django monolith for auth, orchestration, persistence, and Solana-facing API endpoints
• a React/Vite frontend for upload, feed, and account workflows
• a FastAPI datafeed sidecar for Jito and Polymarket market data
• a Rust replay service for long-running ingestion/reconstruction jobs
• Solana programs for feed account creation and value updates

flowchart LR
    FE["React/Vite frontend<br/>iqlabs.dev"]
    API["Django API<br/>src/"]
    DB["Postgres"]
    DF["FastAPI datafeed<br/>services/datafeed"]
    RS["Rust replay service<br/>services/replay-service"]
    CH["ClickHouse"]
    SC["Solana programs<br/>smart-contracts/"]
    SOL["Solana RPC"]
    PM["Polymarket / Jito"]

    FE --> API
    FE --> SOL
    API --> DB
    API --> DF
    API --> RS
    API --> SOL
    DF --> PM
    RS --> CH
    RS --> SOL
    API --> SC

Loading

Main Workflows

Uploads

The upload flow supports two modes:

• self-signed uploads, where the connected wallet signs the transaction bundle client-side
• managed uploads, where the backend signs and submits the transaction bundle using a managed wallet associated with the authenticated user

On the backend, uploads are processed by:

1. decoding the incoming file
2. chunking the file and computing a Merkle root
3. building the required Solana transactions for session creation, storage initialization, chunk writes, and finalize
4. submitting and confirming those transactions
5. storing upload status/history in the managed upload registry

Successful uploads produce a session PDA that can later be used for download or replay flows.

sequenceDiagram
    participant User
    participant FE as Frontend
    participant API as Django API
    participant MW as Managed Wallet Service
    participant SOL as Solana RPC
    participant DB as Upload Registry

    User->>FE: select file + choose mode
    alt self-signed
        FE->>SOL: create/sign/send tx bundle client-side
    else managed
        FE->>API: POST /uploads/file
        API->>MW: load managed wallet keypair
        API->>API: base64 decode + chunk + Merkle root
        API->>SOL: submit session/init/chunk/finalize txs
        API->>DB: record started/completed upload
        API-->>FE: session PDA + finalize signature
    end

Loading

Feeds

The feed flow covers both built-in and user-saved feeds.

Current backend support includes:

• Jito tip-floor feed preview and publishing
• Polymarket event resolution, snapshotting, saving, and publish flows
• PDA lookup and feed state inspection from the frontend

The services/datafeed sidecar is responsible for pulling and normalizing offchain data, while the Django backend handles feed listing, preview, save, and publish orchestration.

flowchart LR
    PM["Polymarket / Jito"]
    DF["FastAPI datafeed"]
    API["Django feed service"]
    DB["SavedFeed records"]
    WAL["Managed wallet"]
    SOL["Solana feed PDA"]
    FE["Frontend"]

    PM --> DF
    DF --> API
    FE --> API
    API <--> DB
    API --> WAL
    WAL --> SOL
    FE --> SOL

Loading

Replay / Download

Uploads can be revisited through:

• session peek/download endpoints in the Django app
• replay ingestion through the Rust replay service

The replay service exposes HTTP endpoints for queueing jobs and polling status, and is designed to run an external replay binary with bounded concurrency while tracking progress in memory.

flowchart LR
    FE["Frontend / client"]
    API["Django API"]
    TMP["/tmp/iqlabs-replay"]
    RS["Rust replay service"]
    BIN["JETSTREAMER_BINARY"]
    CH["ClickHouse"]

    FE --> API
    API --> TMP
    API --> RS
    RS --> BIN
    BIN --> CH

Loading

Repository Layout

src/

Django application code.

Key areas:

• auth endpoints and token flows
• managed wallet creation and balance lookup
• file upload orchestration
• managed upload registry and gallery stats
• feed preview/publish endpoints
• Polymarket-specific save/publish helpers
• inbox and session lookup/download endpoints
• replay ingestion endpoint

iqlabs.dev/

React 19 + Vite + TypeScript frontend.

Key areas:

• upload dashboard
• wallet-connected flows using Solana wallet adapters
• managed-wallet account views
• feed management UI
• upload history and session download UX

services/datafeed/

FastAPI sidecar for offchain market data.

Current responsibilities:

• fetching Jito tip-floor data
• resolving Polymarket event metadata
• reading Polymarket book state / BBO snapshots
• caching short-lived market data for backend consumption

services/replay-service/

Rust/Axum service for replay job execution.

Current responsibilities:

• enqueueing replay jobs
• limiting replay concurrency with a semaphore
• spawning the external replay process
• parsing progress output
• serving job status over HTTP

smart-contracts/

Solana programs written in Rust with Pinocchio.

Included crates:

• feed_mvp: the minimal feed program used by the current backend flow for canonical feed PDA creation and value writes
• receipt_feeds: a receipt-based feed design that verifies provider-signed updates and stores latest feed values onchain

Current Rough Edges

Recent audit notes:

• development config still allows known fallback secrets in Django/auth config, so local startup can succeed with placeholder values if env vars are omitted
• the example env files are sanitized, but they still need real replacements before any non-local deployment
• some landing-page integrations only work when optional external service URLs are configured
• the replay path depends on an external JETSTREAMER_BINARY, so the repo does not fully reproduce replay execution on its own

Stack

• Backend: Python 3.11, Django, Postgres
• Frontend: React 19, TypeScript, Vite, TanStack Query, Solana wallet adapters
• Services: FastAPI, Axum, Tokio
• Infra/Data: Docker Compose, ClickHouse
• Onchain: Rust, Pinocchio, Solana account/program primitives

Local Development

Requirements

• Python 3.11+
• Node.js 20+
• Rust/Cargo
• Docker + Docker Compose

Setup

1. Copy .env.example to .env
2. Copy iqlabs.dev/.env.example to iqlabs.dev/.env
3. Copy services/datafeed/.env.example to services/datafeed/.env
4. Copy services/replay-service/.env.example to services/replay-service/.env if you want to run replay locally
5. Start the dev stack:

docker compose -f docker-compose.dev.yml up --build

Default local services:

• Frontend: http://localhost:3000
• Django API: http://localhost:8080
• Datafeed: http://localhost:8090
• Postgres: localhost:5432
• ClickHouse: localhost:8123

Verification

Recent checks:

python src/manage.py check
cd iqlabs.dev && npm run build
cd iqlabs.dev && npm run lint
cd services/replay-service && cargo check
cd smart-contracts/feed_mvp && cargo check
cd smart-contracts/receipt_feeds && cargo check

The replay service expects an external JETSTREAMER_BINARY; runtime binaries and captured datasets are not included here.

Public Copy Notes

This copy omits internal-only material:

• secrets and local environment files were removed
• recovery scripts, wallet dumps, and internal operational artifacts were removed
• example environment files were added in place of private config

Core application code, service code, and Solana programs are still present.