API: for Leaderboard, all time Sales Volume per account, and Sort

[0xthrpw]

Summary

Add sales_volume column to leaderboard API and implement sorting by sales volume

Changes

• package-lock.json
• services/api/migrations/seq/0460_add_sales_volume_index.sql
• services/api/src/controllers/leaderboard.ts
• services/api/src/routes/__tests__/leaderboard.integration.test.ts
• services/api/src/routes/leaderboard.ts
• services/api/src/services/__tests__/leaderboard.test.ts
• services/api/src/services/leaderboard.ts
• services/api/src/types/leaderboard.ts

Objectives

• Add sales_volume calculation to leaderboard data aggregation
• Implement new sortBy parameter for sales_volume sorting
• Ensure backwards compatibility with existing sales_count sorting
• Maintain proper API response format and performance

Approach

Add sales_volume calculation to the existing leaderboard route by joining with sales data, implementing volume aggregation using PostgreSQL SUM operations, and extending the sortBy parameter to support sales_volume while maintaining backwards compatibility. The implementation will leverage the existing sales table to calculate total ETH volume per address and add this as a new field in the response.

Test Results

• Passed: 0
• Failed: 0
• Skipped: 0

Invariants

• [INV-001] sales_volume must be calculated as the sum of all sale prices (in ETH) for a given address
• [INV-002] Leaderboard API must support both sales_count and sales_volume sorting
• [INV-003] sales_volume must be returned as a numeric value (ETH, not wei)
• [INV-004] Default sorting behavior must remain unchanged for backwards compatibility
• [INV-005] sales_volume calculation must only include completed sales, not listings or offers

---

Automated by Gard | Task ID: 110e31d1-b6b6-44be-b09f-fee191737348