add leaderboard rebuild job

.gitignore

@@ -18,6 +18,12 @@ frontend/.next/
 frontend/out/
 frontend/node_modules/
 
+# Backend stack build output (backend/, indexer/, oracle/)
+dist/
+backend/dist/
+indexer/dist/
+oracle/dist/
+
 # ── Environment & Secrets ──────────────────────────────────────────────────────
 .env
 .env.local

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to iPredict — Backend & Oracle (`implementation-drips`)
+
+We're building the real backend and oracle for iPredict. All of this work
+happens on the **`implementation-drips`** branch — not `main`.
+
+## Workflow
+
+1. **Find an issue.** Browse [open issues](../../issues). Filter by `area:` label
+   to find work in your wheelhouse:
+   - `area:backend` / `area:api` — REST API
+   - `area:indexer` — Soroban event indexer
+   - `area:db` — database schema, migrations, queries
+   - `area:oracle` — council aggregator, optimistic oracle, data adapters
+   - `area:contracts` — Soroban contract changes (oracle state machine, bonds)
+   - `area:cache` — Redis caching layer
+   - `area:infra` — Docker, compose, deployment
+   - `area:monitoring` — metrics, dashboards, alerts
+   - `area:testing` — tests
+   - `area:docs` — documentation
+   - Priority: `P0` (needed for launch), `P1`, `P2`.
+
+2. **Claim it.** Comment on the issue so others don't duplicate work.
+
+3. **Branch.** Always branch off `implementation-drips`:
+   ```bash
+   git checkout implementation-drips
+   git pull
+   git checkout -b feat/<short-name>     # or fix/, chore/, test/
+   ```
+
+4. **Build it.** Each issue has Context, What to build, Acceptance criteria, and
+   the target files/folder. Stay within the issue's scope — small, reviewable PRs.
+
+5. **Open a PR — base branch `implementation-drips`.**
+   - Link the issue (`Closes #123`).
+   - Make sure `npm run typecheck` and `npm test` pass in the package you touched.
+
+> There is **no CI/GitHub Actions** on this branch yet — checks are manual.
+> Please run typecheck/tests locally before requesting review.
+
+## Repo layout
+
+```
+backend/    REST API (Node + TypeScript, Fastify)
+indexer/    Soroban event indexer (Node + TypeScript)
+oracle/     Council aggregator, data adapters, submitter, monitor
+db/         Shared Postgres migrations + schema
+infra/      Docker compose (dev + production)
+contracts/  Soroban smart contracts (existing + new oracle code)
+frontend/   Next.js app (existing)
+docs/       Architecture & design docs
+```
+
+## Local setup
+
+```bash
+# 1. Start Postgres + Redis
+cd infra && docker compose -f docker-compose.dev.yml up -d
+
+# 2. Run a service (example: backend)
+cd ../backend
+cp .env.example .env
+npm install
+npm run dev
+```
+
+The design reference for everything is
+[`docs/ORACLE_AND_BACKEND.md`](docs/ORACLE_AND_BACKEND.md).

backend/.env.example

@@ -0,0 +1,29 @@
+# ── Backend API configuration ────────────────────────────────────────────────
+# Copy to .env and fill in real values.
+
+# HTTP
+PORT=4000
+HOST=0.0.0.0
+
+# PostgreSQL (shared with the indexer)
+DATABASE_URL=postgres://ipredict:ipredict@localhost:5432/ipredict
+
+# Redis cache
+REDIS_URL=redis://localhost:6379
+
+# Stellar / Soroban
+SOROBAN_RPC_URL=https://mainnet.sorobanrpc.com
+NETWORK_PASSPHRASE=Public Global Stellar Network ; September 2015
+
+# Contract IDs (from deploy-mainnet-output.json)
+MARKET_CONTRACT_ID=
+TOKEN_CONTRACT_ID=
+REFERRAL_CONTRACT_ID=
+LEADERBOARD_CONTRACT_ID=
+
+# Oracle provider auth (Phase 2) — comma-separated API keys
+ORACLE_API_KEYS=
+
+# Rate limiting defaults (requests per window-seconds)
+RATE_LIMIT_DEFAULT=30
+RATE_LIMIT_WINDOW_SECONDS=60

backend/README.md

@@ -0,0 +1,67 @@
+# iPredict Backend API
+
+REST API that serves market, bet, leaderboard, and stats data to the frontend —
+reading from an indexed PostgreSQL copy of on-chain state (written by the
+[`indexer/`](../indexer)) with a Redis cache in front, instead of hitting Soroban
+RPC directly on every request.
+
+> **Branch:** all work happens on `implementation-drips`. Open PRs against that
+> branch, **not** `main`.
+
+## Why this exists
+
+The frontend currently reads markets directly from Soroban RPC. That works for
+<100 markets but throttles and slows badly past ~500. This service is the
+scalable read path. See [`docs/ORACLE_AND_BACKEND.md`](../docs/ORACLE_AND_BACKEND.md)
+for the full design.
+
+## Stack
+
+- **Runtime:** Node.js 20+, TypeScript
+- **HTTP:** Fastify
+- **DB:** PostgreSQL 16 (shared with the indexer)
+- **Cache:** Redis 7
+- **Validation:** Zod
+- **Stellar:** `@stellar/stellar-sdk`
+
+## Layout
+
+```
+backend/
+  src/
+    api/         route handlers (markets, leaderboard, stats, oracle)
+    db/          query layer (shared schema lives in ../db migrations)
+    cache/       Redis client + cache helpers
+    config/      env loading & validation
+    lib/         shared utilities
+    server.ts    Fastify bootstrap
+    index.ts     entrypoint
+  test/
+  package.json
+  tsconfig.json
+  .env.example
+```
+
+## Getting started
+
+```bash
+cd backend
+cp .env.example .env        # fill in DATABASE_URL, REDIS_URL, contract IDs
+npm install
+npm run dev                 # starts the API on :4000
+```
+
+You need Postgres and Redis running locally (see
+[`infra/`](../infra) for a docker-compose that starts both).
+
+## Endpoints (target)
+
+See [`docs/ORACLE_AND_BACKEND.md`](../docs/ORACLE_AND_BACKEND.md#api-endpoints).
+Each endpoint is tracked as its own issue.
+
+## Contributing
+
+1. Pick an open issue labelled `area:backend` (or `area:api`).
+2. Comment to claim it.
+3. Branch off `implementation-drips`, implement, open a PR back to
+   `implementation-drips`.