Feature/indexer service

README.md

@@ -230,6 +230,25 @@ cd frontend && pnpm install && pnpm dev
 
 ---
 
+## Indexer Service
+
+StellarCred includes a lightweight indexer service (located in `services/indexer/`) that polls the Stellar Horizon API for `ProofRegistry` events (verifications and revocations) and provides a fast, queryable REST API.
+
+The indexer reads strictly public on-chain data (no identity fields), and operates idempotently. It powers the frontend's aggregate statistics and claim discovery features. 
+
+**API Endpoints:**
+- `GET /claims?wallet=G...` — Claims for a specific wallet
+- `GET /stats` — Aggregate counts per credential type
+- `GET /recent` — Recent verifications (paginated)
+
+To run the indexer alongside the application, simply start the stack via Docker:
+```bash
+docker compose up indexer
+```
+For standalone setup instructions, refer to the [Indexer README](services/indexer/README.md).
+
+---
+
 ## Deployments
 
 A public record of deployed contract IDs on testnet and mainnet, along with instructions to verify the bytecode integrity from source, is maintained in [DEPLOYMENTS.md](DEPLOYMENTS.md).

docker-compose.yml

@@ -1,36 +1,71 @@
+version: "3.9"
+
 services:
-  contracts:
+  # ── ProofRegistry event indexer ─────────────────────────────────────────
+  indexer:
     build:
-      context: .
-      dockerfile: docker/Dockerfile.dev
-    image: stellarcred-dev
-    working_dir: /workspace
+      context: ./services/indexer
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    environment:
+      # Set these in a .env file or pass via environment at runtime.
+      # See services/indexer/.env.example for all options.
+      STELLAR_NETWORK: ${STELLAR_NETWORK:-testnet}
+      HORIZON_URL: ${HORIZON_URL:-https://horizon-testnet.stellar.org}
+      RPC_URL: ${RPC_URL:-https://soroban-testnet.stellar.org}
+      PROOF_REGISTRY_CONTRACT_ID: ${PROOF_REGISTRY_CONTRACT_ID}
+      DB_DRIVER: ${DB_DRIVER:-sqlite}
+      SQLITE_PATH: /data/indexer.db
+      # Uncomment to use Postgres instead:
+      # DB_DRIVER: postgres
+      # DATABASE_URL: ${DATABASE_URL}
+      POLL_INTERVAL_SECONDS: ${POLL_INTERVAL_SECONDS:-6}
+      START_LEDGER: ${START_LEDGER:-0}
+      PORT: 3001
     volumes:
-      - .:/workspace
-    command: ["sh", "-c", "cargo test && cargo build"]
+      # Persist SQLite data across container restarts
+      - indexer_data:/data
+    ports:
+      # Expose the read-only API on host port 3001 (adjust as needed)
+      - "${INDEXER_PORT:-3001}:3001"
+    healthcheck:
+      test: ["CMD", "node", "-e",
+        "require('http').get('http://localhost:3001/health',r=>{process.exit(r.statusCode===200?0:1)})"]
+      interval: 15s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
 
+  # ── StellarCred frontend ─────────────────────────────────────────────────
   frontend:
     build:
-      context: .
-      dockerfile: docker/Dockerfile.dev
-    image: stellarcred-dev
-    working_dir: /workspace/frontend
-    volumes:
-      - ./frontend:/workspace/frontend
-      - frontend-node-modules:/workspace/frontend/node_modules
+      context: ./frontend
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    environment:
+      NEXT_PUBLIC_STELLAR_NETWORK: ${NEXT_PUBLIC_STELLAR_NETWORK:-testnet}
+      NEXT_PUBLIC_RPC_URL: ${NEXT_PUBLIC_RPC_URL:-https://soroban-testnet.stellar.org}
+      NEXT_PUBLIC_NETWORK_PASSPHRASE: ${NEXT_PUBLIC_NETWORK_PASSPHRASE:-Test SDF Network ; September 2015}
+      NEXT_PUBLIC_ISSUER_ADDRESS: ${NEXT_PUBLIC_ISSUER_ADDRESS:-}
+      NEXT_PUBLIC_STELLARCRED_BASE_URL: ${NEXT_PUBLIC_STELLARCRED_BASE_URL:-}
+      NEXT_PUBLIC_ISSUER_REGISTRY_ID: ${NEXT_PUBLIC_ISSUER_REGISTRY_ID:-}
+      NEXT_PUBLIC_CREDENTIAL_VERIFIER_ID: ${NEXT_PUBLIC_CREDENTIAL_VERIFIER_ID:-}
+      NEXT_PUBLIC_PROOF_REGISTRY_ID: ${NEXT_PUBLIC_PROOF_REGISTRY_ID:-}
+      NEXT_PUBLIC_GATED_POOL_ID: ${NEXT_PUBLIC_GATED_POOL_ID:-}
+      # Indexer URL accessible inside the Next.js server (same docker network)
+      NEXT_PUBLIC_INDEXER_URL: ${NEXT_PUBLIC_INDEXER_URL:-http://indexer:3001}
+      ISSUER_PRIVATE_KEY: ${ISSUER_PRIVATE_KEY:-}
+      PERSONA_API_KEY: ${PERSONA_API_KEY:-}
+      PERSONA_KYC_TEMPLATE_ID: ${PERSONA_KYC_TEMPLATE_ID:-}
+      PLAID_CLIENT_ID: ${PLAID_CLIENT_ID:-}
+      PLAID_SECRET: ${PLAID_SECRET:-}
+      PLAID_ACCESS_TOKEN: ${PLAID_ACCESS_TOKEN:-}
+      PLAID_ENV: ${PLAID_ENV:-sandbox}
     ports:
-      - "3000:3000"
-    command: ["sh", "-c", "pnpm install && pnpm dev -- -H 0.0.0.0"]
-
-  circuits:
-    build:
-      context: .
-      dockerfile: docker/Dockerfile.dev
-    image: stellarcred-dev
-    working_dir: /workspace/circuits
-    volumes:
-      - ./circuits:/workspace/circuits
-    command: ["nargo", "compile", "--workspace"]
+      - "${FRONTEND_PORT:-3000}:3000"
+    depends_on:
+      indexer:
+        condition: service_healthy
 
 volumes:
-  frontend-node-modules:
+  indexer_data:

services/indexer/.env.example

@@ -0,0 +1,13 @@
+DB_DRIVER=sqlite
+SQLITE_PATH=./data/indexer.db
+DATABASE_URL=postgres://indexer:indexer@localhost:5432/indexer
+
+RPC_URL=https://soroban-testnet.stellar.org
+NETWORK_PASSPHRASE=Test SDF Network ; September 2015
+PROOF_REGISTRY_CONTRACT_ID=
+
+POLL_INTERVAL_MS=5000
+EVENT_PAGE_LIMIT=100
+START_LEDGER=0
+
+PORT=4100

services/indexer/.eslintrc.json

@@ -0,0 +1,15 @@
+{
+  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "root": true,
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-explicit-any": "warn"
+  }
+}

services/indexer/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+data/
+.env
+*.db
+*.db-wal
+*.db-shm

services/indexer/Dockerfile

@@ -0,0 +1,19 @@
+FROM node:20-slim
+
+WORKDIR /app
+
+# Copy package files and install all dependencies (including dev for build)
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Copy source and TypeScript config
+COPY src ./src
+COPY tsconfig.json ./
+
+# Build TypeScript source
+RUN npm run build
+
+# Use the compiled entrypoint
+EXPOSE 3001
+
+CMD ["node", "dist/index.js"]

services/indexer/README.md

@@ -0,0 +1,54 @@
+# StellarCred Indexer Service
+
+A lightweight indexer service that ingests `ProofRegistry` events from the Stellar Horizon API into a queryable local database (SQLite for development, PostgreSQL for production) and exposes a read-only, public-data-only API.
+
+## Features
+
+- **Idempotent Ingestion**: Tracks the last fully processed ledger. Safe to restart; it resumes exactly where it left off.
+- **Public Data Only**: Indexes only public chain data: wallet address, credential type, issuer, expiry, ledger sequence, and revoked flag. No identity fields are stored.
+- **Zero-State Blockchain Synchronization**: Does not mutate chain state; simply provides a fast query layer on top of on-chain verification events.
+
+## API Endpoints
+
+All endpoints are read-only and return JSON. No authentication is required.
+
+- `GET /health`
+  Returns the health status and the `lastLedger` ingested.
+- `GET /claims?wallet=<address>`
+  Returns all claims (active and revoked) for a given wallet address.
+- `GET /stats`
+  Returns aggregate counts of active, revoked, and total verifications per credential type.
+- `GET /recent?limit=20&page=1`
+  Returns the most recent active verifications (paginated).
+
+## Running the Indexer
+
+The indexer is configured to run out-of-the-box via Docker Compose alongside the frontend.
+
+```bash
+# In the repository root
+docker compose up indexer
+```
+
+### Running Locally (Development)
+
+1. Navigate to the indexer directory:
+   ```bash
+   cd services/indexer
+   ```
+2. Install dependencies and build:
+   ```bash
+   npm install
+   npm run build
+   ```
+3. Set your environment variables (copy `.env.example` to `.env` and fill it out).
+4. Start the service:
+   ```bash
+   npm start
+   # Or for development: npm run dev
+   ```
+
+### Database Configuration
+
+- **SQLite (Default)**: Set `DB_DRIVER=sqlite` (default) and configure `SQLITE_PATH` (e.g. `./data/indexer.db`).
+- **PostgreSQL**: Set `DB_DRIVER=postgres` and provide the full connection string via `DATABASE_URL`.

services/indexer/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/src/**/*.test.ts'],
+};