[DioChuks]

Summary

I traced the existing event indexer, key API routes, and cache patterns, then filled only the gaps and verified the affected behavior.

The existing implementation did not cover the issue scope: it had a global key leaderboard and a separate holder-balance leaderboard, but no LeaderboardUpdated indexer, per-key metric rankings, or wallet rank endpoint.

Implemented:

• Added the key_leaderboards model and migration in key-leaderboard.prisma and migration.sql.
• Added replay- and ordering-safe event indexing with malformed events sent to the DLQ in key-leaderboard-indexer.service.ts. The pipeline awaits indexing before advancing its cursor in indexer-pipeline.service.ts.
• Added per-key metric and wallet-rank endpoints, with deterministic tie ordering and a 60-second cache invalidated for that key on indexed events. Routes are in keys.routes.ts; service and controller are in key-event-leaderboard.service.ts and key-event-leaderboard.controller.ts. Keys without data return an empty items list.
• Documented the endpoints in api-endpoints.md and api-inventory.md.

Validation passed: focused tests (3 suites, 30 tests), pnpm build, targeted ESLint, and pnpm exec prisma validate. The migration is added but has not been applied to a database.

Closes #1136

Testing

• pnpm lint
• pnpm build
• pnpm exec prisma generate when schema or generated types changed

Checklist

• Linked issue or backlog item
• No secrets or live credentials added
• Docs updated if setup or env changed
• Change is scoped to one problem

[drips-wave]

@DioChuks Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits