✅ [Fixed] No off-chain event indexer — every page load re-derives state from raw RPC calls

[Ejirowebfi]

Severity: Critical (as filed) · Area: API / Infra (api/_lib/indexer/, api/cron/index-tokens.ts) · Status: ✅ Resolved — re-verified against the tree on 2026-08-19

Description

Original defect. .kiro/specs/contract-event-indexing/ was an empty directory: the team had named the gap but not scoped or built it. The frontend's entire data layer ran on live synchronous RPC calls with a short-TTL in-memory cache as the only persistence, which truncated the explorer at the RPC's 100-event page cap, made pagination latency-bound, and meant any RPC outage took down all reads at once.

Why this is now closed. The spec is filled in and the indexer is built:

• api/_lib/indexer/ implements the layer behind a TokenStore seam (types.ts), with backfill / steady-state paging / reconciliation (ingest.ts), Soroban RPC reads (sorobanChain.ts), and both a Postgres (postgresStore.ts) and in-memory (memoryStore.ts) store.
• api/cron/index-tokens.ts is the scheduled ingest entrypoint, authenticated with CRON_SECRET and failing closed in production when unconfigured.
• api/tokens/index.ts and api/tokens/[address].ts serve the paginated query surface the issue asked for; api/health/indexer.ts exposes ingest lag.
• docs/indexer.md documents the design and — importantly for this issue's acceptance criteria — states the fallback contract explicitly: the indexer is never a source of truth, every value it serves is re-derivable from the chain, and a broken or stale indexer degrades to direct RPC rather than failing reads. Rollback is a feature flag.

Two residual gaps were found during the 2026-08 audit and are tracked separately, because each is a distinct defect rather than unfinished scope on this issue:

• 🔴 The event indexer cron job is never actually scheduled #1090 — the cron job exists but is never actually scheduled: no crons entry in either vercel.json, so ingest never runs in production.
• 🟡 The indexer stores no events, so token history is permanently retention-limited #1111 — the indexer stores token records but no events, so per-token history remains permanently limited to the RPC retention window.

Tasks

• Scope the empty contract-event-indexing spec.
• Define and build the frontend-facing query API (/api/tokens, /api/tokens/:address).
• Ship a first version covering the all-tokens explorer view without the 100-event truncation.
• Add indexer-lag visibility (/api/health/indexer).
• Close this issue — remaining work is tracked in 🔴 The event indexer cron job is never actually scheduled #1090 and 🟡 The indexer stores no events, so token history is permanently retention-limited #1111.

Acceptance Criteria

• A design document fills the previously-empty spec (docs/indexer.md plus .kiro/specs/contract-event-indexing/).
• The all-tokens view is served completely, without the page-cap truncation.
• The frontend has a documented fallback path to direct RPC when the indexer is unreachable.

---

Re-verified on 2026-08-19 during the 30-issue codebase audit tracked in ISSUES.md, which excludes this issue as already fixed.

[giftexceed]

I'd like to work on this issue.

I'm a backend and blockchain developer with experience designing scalable data pipelines, REST APIs, caching layers, and event-driven systems. I've worked with TypeScript, Node.js, PostgreSQL, and blockchain integrations, focusing on performance, reliability, and maintainability.

For this issue, I will define a clear architecture for the off-chain event indexer, document the API and synchronization strategy, implement an initial indexer for the token explorer, and provide a reliable frontend fallback to direct RPC calls. I'll also document monitoring for indexer lag to ensure data freshness and operational visibility while keeping the solution scalable and easy to extend.

[Dennis-Ritchie1]

hello maintainers i would like to work on this issues
have gone the issues and understand it how to solved it

[grantfox-oss]

🦊 GrantFox — @Dennis-Ritchie1 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.