Stellar Alerts ⚡

Real-Time Stellar Payment Tracker, Soroban Event Ingestion & Non-Custodial Alert Engine

Stellar Alerts monitors registered Stellar public wallets in real time for incoming transactions on the Stellar network (Testnet / Mainnet). It records payment history in PostgreSQL and dispatches multi-channel alerts (Telegram, WhatsApp, Email, Webhooks) without ever requesting or storing secret keys.

---

🌟 Key Features

• ⚡ Zero-Delay Horizon SSE Ingestion: Listens directly to Stellar Horizon Server-Sent Events (SSE) payment streams (payment and create_account operations).
• 🔮 Soroban Smart Contract Support: Ingests Soroban contract events (getEvents) and includes an on-chain Rust Wasm Alert Registry contract (contracts/alert_registry).
• 🔒 100% Non-Custodial Security: Only public key addresses (G...) are stored. Secret keys are never touched or requested.
• 🔑 StrKey Checksum Validation: Enforces Base32 CRC16-XMODEM public key checksum validation at the API boundary and watcher loop.
• 📨 BullMQ Redis Alert Queue: Asynchronous message queue with exponential retries for off-chain alert dispatches.
• 🧮 Persisted Alert-Rule Evaluator: Evaluates a user's stored AlertRule records (per-wallet or account-wide, asset allow-lists, minimum amount thresholds, and AND/OR condition grouping) against each normalized payment event, enqueuing a notification job only when a rule matches and never twice for the same payment.
• 🩹 Hardened Cursor Recovery: Detects ingestion ledger gaps and Horizon provider outages, recovers with a bounded backfill instead of an unbounded replay, and exposes per-wallet ingestion health via GET /wallets/:id/ingestion-status.
• 🛡️ HMAC SHA256 Webhook Signer: Generates cryptographically verifiable X-Stellar-Alerts-Signature headers for webhook payloads.
• 🪄 1-Click Passwordless Auth: Secure Magic Link email authentication (/verify?token=...) with zero password overhead.
• 🦋 Wallet (DID) Sign-In: Sign in with your Stellar Freighter wallet via did:pkh:stellar challenges — single-use, expiring, and fully non-custodial (see /auth/did/*).
• 🔁 Idempotent Delivery: Webhook/Telegram/Email dispatches deduplicate via notificationDeliveryAttempt, preventing duplicate alerts on retries.
• 🗄️ Dead-Letter Queue & Inspector: Terminal delivery failures are persisted (DeadLetter), audited, and can be replayed idempotently or suppressed from the API and web UI (/dead-letters).
• 📊 Modular React Dashboard: Monitored wallets, summary statistics, and real-time payment history powered by Next.js and Tailwind CSS, organized into feature routes (/dashboard, /inspectors, /settings, /onboarding, /docs).
• 🧙 Resumable Onboarding Wizard: A three-step freelancer setup flow (wallet connection → Telegram linking → notification preferences) with a test-ping check before activation; progress persists to localStorage so a refresh resumes exactly where the user left off.
• 🧪 Automated Vitest Test Suite: Unit testing framework with 100% passing test coverage (npm run test:api).
• 🔄 GraphQL Subscriptions: Real-time event streaming via GraphQL with Apollo Server and Redis Pub/Sub for filtered transaction and contract events over WebSockets.
• 📡 gRPC Streaming Interface: Enterprise-grade streaming server with Proto3 definitions for ledger events, wallet alert subscriptions, and low-latency bidirectional notification feeds.
• 🖥️ Interactive TUI Dashboard: React Ink terminal interface for real-time monitoring of ingested transactions, queue depths, delivery latency, and worker status.
• 🤖 Headless Daemon Mode: Background alert processing with automated service generation for systemd (Linux) and launchd (macOS).

---

🏗️ Architecture Overview

Stellar Network (Horizon SSE + Soroban RPC) → Ingestion Worker → PostgreSQL → Fastify REST API → Next.js Web App
                                                    │
                                                    └──> BullMQ (Redis) → Telegram / WhatsApp / Email / Webhook Alerts

For complete technical specifications, database schemas, and data flow details, see ARCHITECTURE.md.

---

🚀 Quick Start for Reviewers & Developers

1. Installation & Monorepo Setup

git clone https://github.com/stellar-alerts-labs/stellar-alerts.git
cd stellar-alerts
npm install

2. Start Local Database & Redis Stack (Docker)

docker compose up -d
npm run db:push

3. Run Automated Tests & Typechecks

npm run test:api

4. Launch Monorepo Stack (Turborepo)

npx turbo dev

Or launch components individually:

npm run dev:api     # Fastify REST API on http://localhost:3001
npm run dev:worker  # Stellar Horizon & Soroban Ingestion Worker
npm run dev:web     # Next.js Dashboard on http://localhost:3000
npm run cli:tui     # Interactive terminal dashboard
npm run daemon:start # Start headless daemon mode

5. Test Live Stellar Payment Ingestion

Fund a fresh keypair on Stellar Testnet via Friendbot and verify automated ingestion into PostgreSQL:

npx tsx --env-file=apps/api/.env apps/api/scripts/seed-and-trigger-payment.ts

6. Streaming Interfaces & Daemon Mode

GraphQL Subscriptions

Access real-time event streaming via GraphQL at http://localhost:3001/graphql:

subscription {
  paymentStream(filter: { walletId: "your-wallet-id" }) {
    id
    fromAddress
    amount
    asset
    receivedAt
  }
}

gRPC Streaming

Connect to the gRPC server on port 50051 for enterprise-grade streaming:

# Using grpcurl
grpcurl -plaintext localhost:50051 stellar.LedgerService/StreamLedgerEvents

Interactive TUI Dashboard

Launch the terminal-based real-time monitoring dashboard:

npm run cli:tui

Headless Daemon Mode

Install and run as a system service:

Linux (systemd):

npm run daemon:install:systemd
sudo systemctl daemon-reload
sudo systemctl enable stellar-alerts
sudo systemctl start stellar-alerts

macOS (launchd):

npm run daemon:install:launchd
launchctl load ~/Library/LaunchAgents/com.stellaralerts.daemon.plist

---

🏆 Grant Qualification & Documentation

• Drips Wave Audit & Readiness Report: See drips_wave_readiness_audit.md for full reviewer scoring & roadmap.
• Grant Submission Qualification Matrix: See SUBMISSION.md.
• System Design & API Specs: See ARCHITECTURE.md.
• Contribution Guidelines: See CONTRIBUTING.md.
• Development Roadmap: See ROADMAP.md.
• Soroban Smart Contract: See contracts/alert_registry/README.md.

---

💬 Community & Support

Join our official Telegram community to ask questions, chat with maintainers, discuss Drips Wave sprint tasks, and stay updated on new releases:

👉 Join Stellar Alerts on Telegram

---

📄 License

Released under the MIT License.