Skip to content

SANITY_CHECK_IMPLEMENTATION.md

Latest commit

 

History

History
261 lines (194 loc) · 5.91 KB

SANITY_CHECK_IMPLEMENTATION.md

File metadata and controls

261 lines (194 loc) · 5.91 KB
Raw

🎉 Price Sanity Check System - Implementation Complete

Overview

A comprehensive price sanity check system has been successfully implemented to automatically compare Oracle prices with external sources and alert admins when deviations exceed 2%.

📦 Deliverables

Core Implementation (2 files)

  1. src/services/sanityCheckService.ts

    • Core sanity check service
    • Multiple external source integration (CoinGecko, ExchangeRate-API)
    • Deviation calculation and threshold checking
    • Webhook alert system
    • Non-blocking design

  2. src/routes/sanityCheck.ts

    • API endpoints for manual checks
    • Single currency check
    • All currencies check
    • Threshold information endpoint

Integration (1 file)

  1. src/services/marketRate/marketRateService.ts (Modified)

    • Integrated sanity check into price fetch flow
    • Automatic check before Stellar submission
    • Non-blocking error handling

  2. src/app.ts (Modified)

    • Added sanity check router

Testing (1 file)

  1. test/sanityCheck.test.ts
    • Integration tests for sanity check service
    • Deviation calculation tests
    • Multi-currency tests

Documentation (3 files)

  1. SANITY_CHECK.md - Comprehensive documentation
  2. SANITY_CHECK_QUICK_REF.md - Quick reference guide
  3. SANITY_CHECK_IMPLEMENTATION.md - This file

🏗️ Architecture

Flow Diagram

Price Fetch → Review Assessment → 🔍 SANITY CHECK → Stellar Submission
                                        │
                                        ├─ CoinGecko
                                        ├─ ExchangeRate-API
                                        │
                                        ├─ Calculate Deviation
                                        ├─ Compare with 2% Threshold
                                        │
                                        ├─ If > 2%:
                                        │   ├─ Log Warning
                                        │   └─ Send Webhook Alert
                                        │
                                        └─ Continue (Non-blocking)

✅ Features Implemented

Automatic Checks

  • ✅ Runs on every price fetch
  • ✅ Compares with external sources
  • ✅ Calculates percentage deviation
  • ✅ Logs warnings when threshold exceeded
  • ✅ Sends webhook alerts to admins

External Sources

  • ✅ CoinGecko direct pairs (XLM/NGN, XLM/KES, XLM/GHS)
  • ✅ ExchangeRate-API (XLM/USD × USD/Currency)
  • ✅ Automatic fallback between sources
  • ✅ Retry logic with exponential backoff

Alert System

  • ✅ Discord webhook integration
  • ✅ Slack webhook integration
  • ✅ Rate limiting to prevent spam
  • ✅ Detailed alert messages with metadata

Monitoring

  • ✅ Manual check endpoints
  • ✅ Single currency check
  • ✅ All currencies check
  • ✅ Threshold information endpoint

Reliability

  • ✅ Non-blocking design
  • ✅ Graceful error handling
  • ✅ Continues Oracle operation if checks fail
  • ✅ Comprehensive logging

📊 Configuration

Threshold

DEVIATION_THRESHOLD = 2.0; // 2%

Webhook Alerts

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
WEBHOOK_RATE_LIMIT_MINUTES=5

🚀 API Endpoints

Check Single Currency

GET /api/v1/sanity-check/check/:currency

Check All Currencies

GET /api/v1/sanity-check/check-all

Get Threshold

GET /api/v1/sanity-check/threshold

📈 Example Results

Passed Check

{
  "currency": "NGN",
  "oraclePrice": 150.5,
  "externalPrice": 148.2,
  "deviation": 2.3,
  "deviationPercent": 1.55,
  "passed": true,
  "source": "CoinGecko"
}

Failed Check (Alert Triggered)

{
  "currency": "NGN",
  "oraclePrice": 150.5,
  "externalPrice": 147.0,
  "deviation": 3.5,
  "deviationPercent": 2.38,
  "passed": false,
  "source": "CoinGecko"
}

🧪 Testing

Run tests:

npm run test:jest -- sanityCheck.test.ts

Manual testing:

# Check NGN
curl http://localhost:3000/api/v1/sanity-check/check/NGN

# Check all
curl http://localhost:3000/api/v1/sanity-check/check-all

📝 Logging Examples

Success

✅ Sanity check passed for NGN
{
  oraclePrice: 150.5,
  externalPrice: 148.2,
  deviationPercent: 1.55,
  source: "CoinGecko"
}

Warning

⚠️ SANITY CHECK FAILED: NGN price deviation exceeds 2%
{
  currency: "NGN",
  oraclePrice: 150.5,
  externalPrice: 147.0,
  deviationPercent: 2.38,
  threshold: 2.0,
  source: "CoinGecko"
}

🎯 Success Criteria Met

  • ✅ Automatic comparison with external sources
  • ✅ 2% deviation threshold implemented
  • ✅ Warning logs when threshold exceeded
  • ✅ Webhook alerts to admins
  • ✅ Non-blocking integration
  • ✅ Multiple external sources
  • ✅ Manual check endpoints
  • ✅ Comprehensive testing
  • ✅ Complete documentation

🔮 Future Enhancements

  • Configurable threshold per currency
  • Historical deviation tracking
  • Dashboard visualization
  • Multiple threshold levels
  • More external sources
  • Machine learning anomaly detection

📚 Documentation

🎉 Conclusion

The Price Sanity Check System is production-ready and provides:

  • Automatic monitoring of price accuracy
  • Real-time alerts when deviations occur
  • Non-blocking operation to ensure Oracle reliability
  • Multiple data sources for redundancy
  • Comprehensive logging for debugging

The implementation meets all requirements and is ready for immediate deployment.

Implementation Date: January 2025
Status: ✅ Complete
Threshold: 2% deviation
Integration: Automatic + Manual endpoints