Stellar Alerts ⚡

Worker failure quarantine

Payment alert jobs use a bounded retry policy. Transient infrastructure and provider failures are retried up to WORKER_MAX_ATTEMPTS (default 5, maximum 20) with exponential backoff. Invalid or otherwise permanent jobs are quarantined immediately and are not retried.

Quarantined jobs are copied to the payment-alerts-dlq queue and persisted as DeadLetter records with the job ID, failure class, failure reason, attempts made, and configured attempt cap. The dead-letter API exposes this metadata for operator inspection and preserves the existing replay and suppression workflow. The default cap is backward-compatible with the previous five-attempt behavior; set WORKER_MAX_ATTEMPTS during rollout if a different cap is required.

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

Note: For a comprehensive setup guide including environment variables, wallet connection, and the freelancer alert quick start flow, please refer to docs/LOCAL_SETUP.md.

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. Validate Dependabot Configuration

Verify the automated dependency update configuration:

npm run validate:dependabot

---

🏆 Grant Qualification & Documentation

• Drips Wave Audit & Readiness Report: See drips_wave_readiness_audit.md for full reviewer scoring & roadmap.
• Local Setup & Freelancer Quick Start: See docs/LOCAL_SETUP.md.
• 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

---

🤖 Automated Dependency Management

Dependabot is configured to automatically update dependencies weekly with grouped PRs to reduce notification noise:

• JavaScript/npm workspace dependencies: All workspace packages (apps/*, packages/*) are monitored for updates
• Docker images: Base images in docker-compose.yml (postgres, redis, toxiproxy) are monitored
• GitHub Actions: Workflow dependencies (actions/checkout, setup-node, etc.) are monitored

All updates run weekly on Mondays and are grouped by ecosystem to minimize PR volume. The configuration can be validated with npm run validate:dependabot.

---

📄 License

Released under the MIT License.