Agent leaderboard: rank agents by XP, quest completions, and district unlocks

[leocagli]

Context

The gamification system now awards XP (agent.xp events), tracks district unlocks, and badges. A leaderboard ties it together — showing which agents are most active and rewarding competition.

What to implement

Route: GET /api/leaderboard

Query params: limit (default 20, max 100), metric (xp | quests | districts, default xp)

Response:

{
  "metric": "xp",
  "updatedAt": 1234567890,
  "entries": [
    { "rank": 1, "agentId": "bot-1", "xp": 1250, "questsCompleted": 8, "districtsUnlocked": 3 },
    { "rank": 2, "agentId": "bot-2", "xp": 980, "questsCompleted": 5, "districtsUnlocked": 2 }
  ]
}

Data source

• XP: sum of all agent.xp events per agent
• Quests: count of quest.completed events per agent
• Districts: count of unlocked districts from district store

Caching

Leaderboard is expensive to compute — cache for 60 seconds (in-memory, same TTL pattern as other stores).

Acceptance criteria

• GET /api/leaderboard returns top-20 by XP by default
• metric=quests ranks by quest completions
• limit=5 returns only top 5
• Agents with no activity appear at the bottom (rank N), not missing
• Unit test: 3 agents with different XP → correct rank order

[aetheron06]

am interested in this opportunity and would like to apply. Please let me know the application process. Thank you.

[grantfox-oss]

🦊 GrantFox — @aetheron06 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 #313)
2. Your PR will be reviewed by the Bitcoindefi maintainers

Good luck! Track your progress on GrantFox.