feat: Implement four issues - leaderboard, token verification, networ…

[OsejiFabian]

…k fees, and background jobs

• Issue feat: Create a dummy leaderboard endpoint for top volume traders #77: Add GET /api/v1/analytics/leaderboard endpoint for top volume traders
• Issue security: Create an endpoint to validate if a token is officially whitelisted #64: Add GET /api/v1/tokens/verify/:address endpoint for token verification
• Issue feat: Add endpoint to calculate estimated network gas fees #70: Add GET /api/v1/network/fees endpoint with 30-second caching
• Issue architecture: Scaffold a background cron job structure for database syncing #74: Add background cron job structure with node-cron for blockchain syncing
• Update README.md with comprehensive endpoint documentation
• Add required dependencies (node-cron, @types/node-cron) to package.json

Pull Request: feat: Create an API endpoint for historical impermanent loss calculation

Description

This PR implements a dedicated backend endpoint for calculating impermanent loss (IL) risk for liquidity providers. The endpoint accepts entry and current price ratios and algorithmically calculates the percentage of impermanent loss based on the constant product formula.

Changes Made

✅ New Features

• GET endpoint: /api/v1/analytics/impermanent-loss
• Mathematical implementation: Standard IL formula 2 * sqrt(price_ratio) / (1 + price_ratio) - 1
• Input validation: Ensures positive price ratios
• Standardized response: JSON wrapper with success flag and timestamp
• Swagger documentation: Complete API documentation with examples

✅ Files Modified

• src/analytics/analytics.service.ts: Added calculateImpermanentLoss() method
• src/analytics/analytics.controller.ts: Added getImpermanentLoss() endpoint
• src/analytics/analytics.module.ts: No changes needed (existing structure)

✅ Files Added

• test-impermanent-loss.js: Endpoint integration tests
• test-il-formula.js: Mathematical formula validation
• IMPERMANENT_LOSS_ENDPOINT.md: Comprehensive documentation

API Usage

Request

GET /api/v1/analytics/impermanent-loss?entryPriceRatio=1.0&currentPriceRatio=1.5

Response

{
  "success": true,
  "data": {
    "entryPriceRatio": 1.0,
    "currentPriceRatio": 1.5,
    "impermanentLossPercentage": -2.02
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Testing

Formula Verification

• ✅ No price change = 0% IL
• ✅ Price increase/decrease symmetry
• ✅ Input validation (zero/negative prices)
• ✅ Mathematical accuracy

Endpoint Testing

• ✅ Response structure validation
• ✅ Error handling
• ✅ Swagger documentation
• ✅ CORS compatibility

Benefits

1. Performance: Heavy mathematical processing moved to backend
2. Consistency: Standardized calculation across all clients
3. Scalability: Leverages API infrastructure for high-volume requests
4. Power User Value: Advanced liquidity providers can hedge positions
5. Developer Experience: Well-documented endpoint with examples

Security & Validation

• Input validation prevents mathematical errors
• Global exception handling for consistent error responses
• CORS configuration maintained
• Rate limiting through existing throttling guards

Documentation

Complete API documentation available at:

• Swagger UI: http://localhost:3000/api/docs
• Technical documentation: IMPERMANENT_LOSS_ENDPOINT.md

Testing Instructions

1. Start the development server: npm run start:dev
2. Test the formula validation: node test-il-formula.js
3. Test the endpoint: node test-impermanent-loss.js
4. View Swagger documentation: Navigate to /api/docs

Checklist

• Code follows existing project patterns
• Mathematical implementation is correct
• Input validation implemented
• Error handling in place
• Swagger documentation complete
• Test scripts provided
• Documentation created
• No breaking changes to existing endpoints

Issue Resolution

Resolves #88: "feat: Create an API endpoint for historical impermanent loss calculation"

This implementation provides advanced liquidity providers with the tools they need to calculate impermanent loss risk before depositing funds, moving heavy mathematical processing off the frontend and into the scalable API layer.
Closes #64
Closes #70
Closes #74
Closes #77

[drips-wave]

@OsejiFabian 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