Add Soroban event indexer for SmartDrop contract events

[prodbycorne]

Overview

The SmartDrop Soroban contract emits events for every airdrop operation (creation, claim, expiry). This service needs to index those events so the API can answer queries like "what is the claim status for address X" without making live RPC calls on every request.

Events to Index

Based on the Soroban contract (see smartdrop-contracts):

Contract Event	Data
airdrop_created	airdrop_id, creator, token, total_amount, expiry_ledger
recipient_added	airdrop_id, recipient, amount
token_claimed	airdrop_id, recipient, amount, ledger
airdrop_expired	airdrop_id, unclaimed_amount

Architecture

Soroban RPC (getEvents) → EventPoller → EventParser → PostgreSQL → REST API

• Poll soroban_rpc.getEvents for the contract address every 5 seconds
• Persist the last indexed ledger in DB to survive restarts
• Store raw XDR + decoded event in contract_events table
• Expose indexed data via new API endpoints

New Endpoints

GET /api/v1/airdrops/:id/status
GET /api/v1/airdrops/:id/recipients
GET /api/v1/recipients/:address/claims
GET /api/v1/indexer/status   (lag, last_ledger, events_count)

Acceptance Criteria

• src/indexer/eventPoller.js polls Soroban RPC
• Last indexed ledger persisted and resumed on restart
• All 4 event types decoded and stored
• API endpoints return indexed data
• Indexer lag exposed in /api/v1/indexer/status
• Unit test: event parser decodes XDR correctly
• Handles RPC errors and continues polling

[Tobi-8]

Hey maintainer, i have looked through your description, and i have had experience in this type of issue.
kindly assign

[Temi-suwa18]

I will approach this by implementing an event indexer that listens to SmartDrop Soroban contract events for airdrop creation, claims, and expiries. The indexer will process and persist these events into a queryable database, maintaining the latest claim status for each address. I'll ensure events are handled in order and idempotently to avoid duplicate records or inconsistent state. Finally, I'll expose the indexed data through the API so claim status queries can be served efficiently without requiring live RPC calls.

[grantfox-oss]

🦊 GrantFox — @Temi-suwa18 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #14)
2. Your PR will be reviewed by the SmartDropLabs maintainers

Good luck! Track your progress on GrantFox.