🚨 stellar-defi-alerts

A self-hostable, plugin-driven alert engine for the Stellar DEX — monitor prices, liquidity pools, and account activity, and get notified via Telegram, webhook, or email the moment your conditions are met.

---

Overview

DeFi moves fast. stellar-defi-alerts keeps you informed without writing custom polling scripts for every project. Define your rules in JSON, plug in your notification channel, and let the engine handle the rest.

Monitor types (built-in):

• 📈 DEX Price Monitor — track any trading pair on the Stellar DEX
• 💧 Liquidity Pool Monitor — watch TVL, reserves, and fee yield
• 👤 Account Activity Monitor — fire on any payment, trade, or contract call for a watched address
• 📉 Spread Monitor — alert when bid/ask spread crosses a threshold

Delivery channels (built-in):

• 🔗 Webhook (POST to any URL)
• 💬 Telegram (Bot API)
• 📧 Email (SMTP / SendGrid)

---

Technical Architecture

Stack Overview

Layer	Technology
Runtime	Node.js 20 + TypeScript
Stellar Client	@stellar/stellar-sdk
Job Queue	BullMQ + Redis
Rules Engine	json-rules-engine
Database	PostgreSQL 16 + Prisma
API	Fastify v4
Admin UI	HTML + HTMX
Testing	Vitest + Testcontainers
Containers	Docker + Docker Compose

Data Flow

BullMQ Scheduler
  └── IMonitor.poll()           # fetch Horizon data snapshot
        └── RulesEngine.run()   # evaluate user-defined rules
              └── [rule match]
                    ├── WebhookChannel.send()
                    ├── TelegramChannel.send()
                    └── EmailChannel.send()
                          └── alert_history table (PostgreSQL)

Plugin Interfaces

interface IMonitor {
  id: string;
  poll(): Promise<Record<string, unknown>>;
}

interface IChannel {
  id: string;
  send(alert: AlertPayload): Promise<void>;
}

---

🌊 Drips Wave Program

This repository is a proud participant in the Drips Wave Program — earn on-chain rewards for solving real open-source issues.

How to Contribute & Earn Rewards

Step 1 — Connect to Drips Visit drips.network and connect your Ethereum wallet. Rewards are paid to this address after your PR merges.

Step 2 — Find This Project on Drips Search for stellar-defi-alerts on the Drips dashboard, or click the project link in this repo's GitHub About section.

Step 3 — Pick a Funded Issue by Complexity

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

Examples in this repo:

• Trivial: Write unit tests for the rules engine evaluation logic
• Medium: Implement the TelegramChannel delivery adapter
• High: Build the HTMX admin dashboard for no-code rule management

Step 4 — Claim the Issue Post /claim in the issue comments. The maintainer will assign it to you. One active claim per contributor at a time.

Step 5 — Open a PR Reference the issue (Closes #XX). New monitors and channels each need a unit test and an entry in the documentation table above.

Step 6 — Collect Your Reward Payout is triggered on merge. No invoices, no delays — Drips streams the reward trustlessly to your wallet.

---

Project Structure

stellar-defi-alerts/
├── src/
│   ├── monitors/           # IMonitor implementations (DEX, LP, Account)
│   ├── channels/           # IChannel adapters (Webhook, Telegram, Email)
│   ├── rules/              # Rules engine setup & rule CRUD service
│   ├── api/
│   │   ├── routes/         # Fastify: /rules, /channels, /alerts
│   │   └── middleware/     # Auth, validation, error handling
│   ├── db/
│   │   ├── migrations/     # Prisma migrations
│   │   └── schema/         # Prisma schema (rules, channels, alerts)
│   └── utils/              # Logger, config, retry helpers
├── tests/
│   ├── unit/               # Monitor & channel unit tests
│   └── integration/        # API + DB integration tests
├── config/                 # Default rule templates (JSON)
├── docker/                 # Dockerfile + docker-compose.yml
├── scripts/                # DB seed, example rule import
├── .github/
│   └── workflows/          # CI: typecheck, test, Docker build
├── .env.example
├── package.json
└── README.md

---

Getting Started

# Clone
git clone https://github.com/YOUR_ORG/stellar-defi-alerts.git
cd stellar-defi-alerts

# Copy environment config
cp .env.example .env
# Set DATABASE_URL, REDIS_URL, HORIZON_URL, TELEGRAM_BOT_TOKEN, SMTP_*

# Start all services
docker compose up -d

# Run migrations
npx prisma migrate deploy

# Seed example rules
npm run seed

# Start the alert engine
npm run dev

# Admin UI available at http://localhost:3000/admin

---

Contributing

See CONTRIBUTING.md. New IMonitor or IChannel implementations must include a mock-based unit test and pass CI before merge.

---

License

MIT © stellar-defi-alerts contributors