Skip to content

VALIDATION_QUICKSTART.md

Latest commit

 

History

History
198 lines (154 loc) · 5.32 KB

VALIDATION_QUICKSTART.md

File metadata and controls

198 lines (154 loc) · 5.32 KB
Raw

Referral Earnings Validation - Quick Start Guide

🚀 Quick Start

Step 1: Test with Sample Data (Recommended First)

npm run validate-referral

This will show you:

  • How earnings compare between old ($0.25 flat) and new (1%) models
  • Break-even point ($25)
  • Sample calculations for various transaction amounts

Expected Output:

Transaction | Old Model | New Model | Difference | Better For
------------|-----------|-----------|------------|------------
$1.00       | $0.2500   | $0.0100   | -0.2400    | Old ($0.25)
$25.00      | $0.2500   | $0.2500   | +0.0000    | Equal
$100.00     | $0.2500   | $1.0000   | +0.7500    | New (1%)
$1000.00    | $0.2500   | $10.0000  | +9.7500    | New (1%)

📊 Break-even point: $25.00

Step 2: Validate Against Your Database (If You Have Data)

npm run validate-referral:live

This will:

  • Analyze your recent earnings transactions
  • Show total earnings comparison
  • Generate a CSV report in output/ directory
  • Validate points balance integrity

Step 3: Review the Results

Look for:

  • ✅ All calculations match expected (1% of volume)
  • ✅ No invalid balances reported
  • ✅ CSV report generated successfully
  • ⚠️ Any warnings or errors

📊 What to Expect

Key Findings

Break-Even Point: $25

  • Transactions < $25: Old model pays more
  • Transactions = $25: Both models equal
  • Transactions > $25: New model pays more

Impact on Different Transaction Sizes:

Volume Old Earnings New Earnings Change
$10 $0.25 $0.10 -60%
$25 $0.25 $0.25 0%
$50 $0.25 $0.50 +100%
$100 $0.25 $1.00 +300%
$500 $0.25 $5.00 +1900%
$1,000 $0.25 $10.00 +3900%

Expected Distribution

If your average transaction is around $50-$100:

  • ~20-30% of transactions will earn less (small transactions)
  • ~70-80% of transactions will earn more (medium-large transactions)
  • Overall earnings will likely increase significantly

🔍 Interpreting Results

Good Signs ✅

  • Calculations are accurate (earnings = volume × 0.01)
  • No invalid balances
  • CSV report generated
  • Most transactions show higher earnings

Warning Signs ⚠️

  • Invalid balances (totalEarned < currentBalance)
  • Calculation mismatches
  • Database connection errors
  • Unexpected earnings amounts

📝 Next Steps

If Validation Passes ✅

  1. Review the CSV report for any anomalies
  2. Check the transaction distribution
  3. Verify break-even point makes sense for your use case
  4. Test in staging environment
  5. Deploy to production
  6. Monitor first few live transactions

If Issues Found ⚠️

  1. Review error messages carefully
  2. Check the specific transactions with issues
  3. Verify sellAmountUsd calculation in TransactionManager
  4. Ensure exchange rate is correct (NGN/USD not USD/NGN)
  5. Test with known transaction amounts
  6. Fix issues before deploying

🛠️ Troubleshooting

"No earnings transactions found"

  • Normal if database is empty
  • Expected in development environment
  • Run sample mode instead: npm run validate-referral

"Cannot connect to database"

  • Check MongoDB is running
  • Verify MONGODB_URI in .env
  • Try: MONGODB_URI=mongodb://localhost:27017/chainpaye npm run validate-referral:live

"Invalid balance" warnings

  • Data integrity issue
  • totalEarned should always be ≥ currentBalance
  • Investigate and fix before deploying

📈 Understanding the Math

Old Model (Flat Fee)

Earnings = $0.25 (always)

New Model (1% of Volume)

Earnings = Transaction Volume (USD) × 0.01

Examples:
- $10 transaction → $10 × 0.01 = $0.10
- $50 transaction → $50 × 0.01 = $0.50
- $100 transaction → $100 × 0.01 = $1.00
- $1,000 transaction → $1,000 × 0.01 = $10.00

Break-Even Calculation

Old Earnings = New Earnings
$0.25 = Volume × 0.01
Volume = $0.25 / 0.01
Volume = $25

Therefore, $25 is the break-even point

🎯 Success Criteria

Before deploying, ensure:

  • Sample validation runs successfully
  • All calculations are accurate (1% of volume)
  • No invalid balances in database
  • Break-even point is $25
  • CSV report looks correct
  • EarningsService tests pass
  • Integration tests pass
  • Staging environment tested

📞 Need Help?

If you encounter issues:

  1. Check scripts/VALIDATION_README.md for detailed documentation
  2. Review error messages in console output
  3. Check CSV report in output/ directory
  4. Verify database connection
  5. Test with sample data first

🚦 Quick Commands Reference

# Test with sample data (no DB needed)
npm run validate-referral

# Compare old vs new models
npm run validate-referral:compare

# Validate against live database
npm run validate-referral:live

# Validate specific number of transactions
npm run validate-referral:live -- --limit=100

# With custom MongoDB URI
MONGODB_URI=mongodb://localhost:27017/chainpaye npm run validate-referral:live

✨ What's Next?

After successful validation:

  1. ✅ Run tests: npm test services/EarningsService.test.ts
  2. ✅ Check diagnostics: Review any TypeScript errors
  3. ✅ Test in staging: Deploy to staging environment
  4. ✅ Monitor closely: Watch first few live transactions
  5. ✅ Update documentation: Inform users of new model
  6. ✅ Celebrate: You've successfully updated the referral system! 🎉