Skip to content

feat: add Stellar event indexing service - #222

Merged
jobbykings merged 3 commits into
Epondia:mainfrom
fathiaoyinloye:feature/stellar-event-indexer
Jul 29, 2026
Merged

feat: add Stellar event indexing service#222
jobbykings merged 3 commits into
Epondia:mainfrom
fathiaoyinloye:feature/stellar-event-indexer

Conversation

@fathiaoyinloye

Copy link
Copy Markdown
Contributor

Closes #129

Description

Implement a backend event indexing service that polls Stellar/Soroban contract events and synchronizes them into PostgreSQL, making blockchain activity queryable through the backend API instead of requiring direct contract queries from the frontend.

What changed

  • Added a Stellar/Soroban event indexer service.
  • Added support for polling registered contracts for new events.
  • Processes events in ledger sequence order.
  • Added checkpoint tracking to resume indexing after restarts.
  • Added deduplication using:
    • contract_id
    • ledger
    • event_index
  • Added support for indexing:
    • CredentialIssued
    • CredentialRevoked
    • CourseCreated
    • EnrollmentCreated
    • AchievementMinted
    • PaymentReceived
    • ProfileUpdated
  • Added the indexed_events database model and migration with JSONB event payload storage.
  • Added domain table synchronization for relevant event types.
  • Added configurable polling with a default interval of 5 seconds.
  • Added indexer health information including:
    • Running status
    • Last indexed ledger
    • Events processed
    • Current ledger lag
  • Added graceful shutdown handling to finish the current batch and persist the checkpoint.
  • Added error handling for malformed events so individual failures do not stop the indexer.
  • Added admin controls to start and stop the indexer.
  • Verified contract event emission consistency in event_logger.rs.
  • Documented the event indexer environment variables in SETUP_GUIDE.md.

Verification

  • Events are indexed into PostgreSQL after contract execution.
  • Indexing resumes from the last processed ledger after restart.
  • Reprocessing the same ledger range does not create duplicate records.
  • Malformed events are logged and skipped without stopping the indexer.
  • Health endpoint exposes event indexer status and ledger lag.
  • Indexer polling interval is configurable.
  • Graceful shutdown saves the latest checkpoint.
  • Database connections are reused safely without exhausting the connection pool.
  • Tests cover event processing, checkpoint recovery, deduplication, malformed events, and indexer lifecycle behavior.

Configuration

The following environment variables are supported:

EVENT_INDEXER_ENABLED=true
EVENT_INDEXER_POLL_INTERVAL=5000

fathiaoyinloye and others added 3 commits July 20, 2026 22:23
…ndexerStatus import

- Replace all SorobanRpc.* references with rpc.* in eventIndexer.ts
  (SorobanRpc was removed in @stellar/stellar-sdk v13; project uses v14)
- Fix health.ts: import IndexerStatus from models/IndexedEvent where it
  is defined, not from services/eventIndexer which never re-exported it
@jobbykings
jobbykings merged commit 5c66d50 into Epondia:main Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Infrastructure] Implement contract event indexing service to sync on-chain events to database

2 participants