Backend: Build Smart Contract Event Indexer with Real-Time WebSocket Streams

[Smartdevs17]

Context

Applications need real-time visibility into on-chain events (payments, disputes, settlements) without polling RPC endpoints. AgenticPay lacks a dedicated event indexer with streaming capabilities.

Current Limitation/Problem

Frontend and SDK clients poll the backend for transaction status, creating unnecessary load. There is no unified event stream for contract state changes across Stellar and EVM.

Expected Outcome

A horizontally scalable event indexer that ingests contract events from both Stellar Soroban and EVM chains, normalizes them into a common schema, and pushes them to subscribed clients via WebSocket with automatic reconnection.

Acceptance Criteria

• Index all relevant events (PaymentSent, PaymentReceived, DisputeRaised, SettlementCompleted, etc.) from Stellar Soroban and EVM
• Push events to authenticated WebSocket clients within 2 seconds of on-chain confirmation
• Support event filtering by contract address, event type, and time range
• Handle chain reorganizations (at least 6 confirmations deep)
• Expose REST API for historical event replay
• Auto-prune events older than configurable retention period
• Maintain at-least-once delivery semantics with deduplication

Technical Scope

• backend/src/services/indexer/ - new indexer service
• backend/src/services/indexer/soroban-listener.ts - Stellar event polling
• backend/src/services/indexer/evm-listener.ts - EVM event polling (ethers.js)
• backend/src/websocket/event-stream.ts - WebSocket handler with Socket.IO or ws
• Prisma schema: IndexedEvent, WebSocketSubscription models
• Redis pub/sub for cross-instance event broadcasting
• BullMQ queue for event persistence and deduplication
• Edge cases: RPC rate limits, connection drops, missed blocks, reorgs

[my908-hue]

@my908-hue has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi maintainer i will really love to work on this project i will add the Index in all relevant events (PaymentSent, PaymentReceived, DisputeRaised, SettlementCompleted, etc.) from Stellar Soroban and EVM
Push events to authenticated WebSocket clients within 2 seconds of on-chain confirmation
Support event filtering by contract address, event type, and time range
Handle chain reorganizations (at least 6 confirmations deep)

ℹ️ Repo Maintainers: To accept this application, review their application or assign @my908-hue to this issue.

[drips-wave]

Congratulations, @my908-hue! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @my908-hue: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊