feat: Read-Only Ranking/Leaderboard System

[Goodnessukaigwe]

closes #75

Summary

Implements efficient read-only ranking functionality for the rewards system, enabling leaderboard views and user rank queries without state mutation.

Changes

Core Features Added

1. get_top_users(limit: u32) - Returns top N users by reward points in descending order
2. get_user_rank(user: Address) - Returns 1-indexed rank for a specific user
3. get_user_ranking_details(user: Address) - Returns (rank, points, total_users) tuple

Files Modified

Smart Contract:

• contracts/src/rewards/ranking.rs - NEW ranking module with optimized iteration
• contracts/src/rewards/storage_types.rs - Added AllUsers key to track ranked users
• contracts/src/rewards/storage.rs - Auto-track users when first earning rewards
• contracts/src/rewards/mod.rs - Exposed ranking module
• contracts/src/lib.rs - Added public ranking API functions

Tests:

• contracts/tests/ranking_test.rs - NEW comprehensive test suite (10 tests covering):
  • Empty leaderboard handling
  • Basic ranking and ordering
  • Limit enforcement
  • Rank calculation
  • Tie handling
  • Dynamic updates
  • Large user set safety
  • Read-only verification

Technical Details

Storage Optimization:

• Users tracked in persistent storage list (AllUsers key)
• Iteration capped at 1,000 users to prevent excessive gas usage
• Bubble sort for simplicity (O(n²) acceptable for limited sets)

Read-Only Guarantee:

• All ranking functions are pure queries (no &mut references)
• No storage writes during ranking calculations
• Consistent results across multiple calls

Safety Features:

• ✅ Hard limit on iteration (MAX_RANKING_USERS = 1,000)
• ✅ Graceful handling of empty user sets
• ✅ Overflow-safe arithmetic
• ✅ No panics in ranking logic

Test Results

running 10 tests
test test_get_top_users_empty ... ok
test test_get_user_rank_not_ranked ... ok
test test_ranking_read_only ... ok
test test_get_user_ranking_details ... ok
test test_get_top_users_basic ... ok
test test_get_user_rank_basic ... ok
test test_get_top_users_limit ... ok
test test_ranking_updates_on_new_deposits ... ok
test test_ranking_with_ties ... ok
test test_large_user_set_safety ... ok

test result: ok. 10 passed; 0 failed

All 41 tests pass (31 existing + 10 new ranking tests) with no regressions.

API Examples

// Get top 10 users
let top_users = contract.get_top_users(10);
for (user, points) in top_users {
    // Display leaderboard entry
}

// Get specific user's rank
let rank = contract.get_user_rank(user_addr); // 1-indexed, 0 if not ranked

// Get detailed ranking info
if let Some((rank, points, total)) = contract.get_user_ranking_details(user_addr) {
    // Show: "Rank #5 with 12,500 points (out of 250 users)"
}

Acceptance Criteria Met

• ✅ Leaderboard view works - get_top_users() returns sorted list
• ✅ No state mutation - All functions are read-only queries
• ✅ Handles large user sets safely - Capped at 1K users max

Performance Characteristics

• get_top_users(N): O(min(users, 1000)²) due to bubble sort
• get_user_rank(): O(min(users, 1000)²) due to sorting
• Space: O(users) for AllUsers list in persistent storage

Future Optimizations (Optional)

• Implement more efficient sorting (quicksort/mergesort)
• Add pagination for leaderboards > 1K users
• Cache sorted results with TTL
• Use binary search for rank lookups

---

[vercel]

@Goodnessukaigwe is attempting to deploy a commit to the devsol-01's projects Team on Vercel.

A member of the Team first needs to authorize it.