🔭 stellar-horizon-indexer

A fault-tolerant, processor-pipeline Node.js indexer that streams live Stellar ledger data into PostgreSQL and serves it via a high-performance Fastify REST API — the data backbone your dApp deserves.

---

Overview

Every serious Stellar dApp needs reliable, queryable on-chain data. stellar-horizon-indexer provides an opinionated but extensible foundation:

• Real-time ingestion via Horizon SSE streams with cursor checkpointing
• Processor pipeline — drop in a class implementing IProcessor to handle any operation type you care about
• REST API — Fastify serves indexed data with Redis caching out of the box
• Docker-first — one docker compose up gets you indexer + DB + cache

---

Technical Architecture

Stack Overview

Layer	Technology
Runtime	Node.js 20 + TypeScript
Stellar Client	@stellar/stellar-sdk (SSE streams)
Database	PostgreSQL 16
ORM	Prisma 5
API Server	Fastify v4
Caching	Redis 7 (ioredis)
Queue	BullMQ (retry & backoff)
Testing	Vitest + Testcontainers
Containers	Docker + Docker Compose

Ingestion Pipeline

Horizon SSE Stream
  └── LedgerIngester
        └── OperationRouter
              ├── PaymentProcessor      → payments table
              ├── DEXTradeProcessor     → trades table
              ├── ContractCallProcessor → contract_events table
              └── [Your Custom Processor]

Each processor implements:

interface IProcessor {
  canHandle(operation: HorizonOperation): boolean;
  process(operation: HorizonOperation, db: PrismaClient): Promise<void>;
}

---

🌊 Drips Wave Program

This repository is an active participant in the Drips Wave Program — a protocol that streams crypto rewards to open-source contributors who solve real issues.

How to Contribute & Earn Rewards

Step 1 — Connect to Drips Visit drips.network and connect your Ethereum wallet (MetaMask, Rainbow, or any WalletConnect-compatible wallet).

Step 2 — Locate This Repository Find stellar-horizon-indexer on the Drips project dashboard using the link in this repo's GitHub About panel.

Step 3 — Understand Issue Labels Every funded issue is tagged with a complexity tier:

Label	Complexity	Typical Reward Range
drips:trivial	Trivial	$10 – $50
drips:medium	Medium	$51 – $200
drips:high	High	$201 – $500+

Examples of each tier in this repo:

• Trivial: Add a missing field to a Prisma schema, write a missing unit test
• Medium: Implement a new IProcessor for a specific operation type
• High: Build a WebSocket subscription endpoint on the Fastify layer

Step 4 — Claim Your Issue Comment /claim on the issue thread. A maintainer will assign it within 24 hours. Unclaimed work will not be eligible for rewards.

Step 5 — Open a Pull Request Your PR must reference the issue (Closes #XX), pass all CI checks, and include tests for any new processor or API route.

Step 6 — Receive Your Reward On merge, the payout is triggered on Drips. No KYC, no waiting — funds stream directly to your wallet.

---

Project Structure

stellar-horizon-indexer/
├── src/
│   ├── ingestion/          # Horizon SSE stream client & cursor manager
│   ├── processors/         # IProcessor implementations (payment, DEX, etc.)
│   ├── api/
│   │   ├── routes/         # Fastify route handlers
│   │   └── middleware/     # Auth, rate limiting, error handling
│   ├── db/
│   │   ├── migrations/     # Prisma migration files
│   │   └── schema/         # Prisma schema definitions
│   └── utils/              # Logger, config loader, retry helpers
├── tests/
│   ├── unit/               # Isolated processor & util tests
│   └── integration/        # Testcontainers DB + API tests
├── scripts/                # DB seed, backfill, health check scripts
├── docker/                 # Dockerfile + docker-compose.yml
├── .github/
│   └── workflows/          # CI: typecheck, lint, test, Docker build
├── .env.example            # Environment variable reference
├── package.json
└── README.md

---

Getting Started

# Clone
git clone https://github.com/YOUR_ORG/stellar-horizon-indexer.git
cd stellar-horizon-indexer

# Copy environment config
cp .env.example .env
# Edit .env: set DATABASE_URL, REDIS_URL, HORIZON_URL, NETWORK_PASSPHRASE

# Start all services with Docker
docker compose up -d

# Run database migrations
npx prisma migrate deploy

# Start the indexer (development mode)
npm run dev

# API is now live at http://localhost:3000
# Example: GET http://localhost:3000/accounts/G.../operations

---

Contributing

See CONTRIBUTING.md. New processors must include an canHandle unit test and a full integration test with a seeded ledger fixture.

---

License

MIT © stellar-horizon-indexer contributors