stellar-alerts-labs/stellar-alerts

Real-time payment notification system and financial dashboard designed for African freelancers receiving digital dollars on the Stellar network. # 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, 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. - 🛡️ **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. - 📊 **Modular React Dashboard**: Monitored wallets, summary statistics, and real-time payment history powered by Next.js and Tailwind CSS. - 🧪 **Automated Vitest Test Suite**: Unit testing framework with 100% passing test coverage (`npm run test:api`). --- ## 🏗️ Architecture Overview ``` Stellar Network (Horizon SSE + Soroban RPC) → Ingestion Worker → PostgreSQL → Fastify REST API → Next.js Web App │ └──> BullMQ (Redis) → Telegram / Email / Webhook Alerts ``` For complete technical specifications, database schemas, and data flow details, see **ARCHITECTURE.md**. --- ## …