Merge pull request #247 from simonfrvr/feature/developer-sandbox-environment

Feature/developer sandbox environment

Author: elizabetheonoja-art

.env.example

@@ -201,3 +201,15 @@ PII_SCRUBBING_SALT=your-secure-random-salt-for-pii-hashing-min-32-bytes
 INACTIVE_RETENTION_YEARS=3
 PII_SCRUBBING_ENABLED=true
 PII_SCRUBBING_CRON_SCHEDULE=0 2 * * 0  # Weekly on Sunday at 2 AM
+
+# Sandbox Environment Configuration
+SANDBOX_ENABLED=false
+SANDBOX_MODE=testnet  # testnet or mainnet
+SANDBOX_DB_SCHEMA_PREFIX=sandbox_
+SANDBOX_STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
+SANDBOX_STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
+SANDBOX_SOROBAN_RPC_URL=https://soroban-rpc.testnet.stellar.gateway.fm
+SANDBOX_SOROBAN_CONTRACT_ID=CAOUX2FZ65IDC4F2X7LJJ2SVF23A35CCTZB7KVVN475JCLKTTU4CEY6L
+SANDBOX_MOCK_PAYMENTS_ENABLED=true
+SANDBOX_FAILURE_SIMULATION_ENABLED=true
+SANDBOX_ZERO_VALUE_TOKENS_ENABLED=true

CONSOLIDATED_TREASURY_PR.md

@@ -0,0 +1,185 @@
+# PR: Multi-Currency "Consolidated Treasury" View
+
+**Issue #220** ✅
+
+## Summary
+
+This PR implements a comprehensive multi-currency consolidated treasury view that enables large organizations to view their entire protocol treasury in a single, stable currency regardless of underlying crypto assets (XLM, USDC, EURC).
+
+## 🎯 Problem Solved
+
+Large organizations accepting payments in multiple cryptocurrencies across different plans need:
+- **Single-Currency View**: Net worth in their preferred base currency (USD, EUR, etc.)
+- **Real-time Valuation**: Accurate pricing within 5-minute windows
+- **Risk Analysis**: Exposure breakdown by volatile tokens
+- **Performance Tracking**: 24-hour delta showing treasury changes
+
+## 🚀 Features Implemented
+
+### Core API Endpoints
+- `GET /api/v1/merchants/:id/treasury/consolidated` - Main consolidated view
+- `GET /api/v1/merchants/:id/treasury/history` - Historical treasury data
+
+### Key Capabilities
+✅ **Multi-Currency Conversion**: XLM, USDC, EURC → base currency  
+✅ **Real-time Price Feeds**: 5-minute freshness window via PriceCache  
+✅ **24-Hour Delta**: Price fluctuation vs revenue growth analysis  
+✅ **Asset Breakdown**: Detailed exposure analysis with percentages  
+✅ **Historical Tracking**: Treasury snapshots for trend analysis  
+
+## 🏗️ Architecture
+
+### Database Schema
+- **`merchants`** - Base currency preferences and merchant data
+- **`merchant_balances`** - Multi-asset holdings (XLM, USDC, EURC)
+- **`price_cache`** - Real-time price data from multiple sources
+- **`treasury_snapshots`** - Historical treasury values
+
+### Services Layer
+- **`PriceCacheService`** - Price conversion and caching logic
+- **`MerchantService`** - Balance management and historical data
+- **`TreasuryService`** - Consolidation and delta calculations
+
+### Response Structure
+```json
+{
+  "success": true,
+  "data": {
+    "merchantId": "uuid",
+    "baseCurrency": "USD",
+    "totalValueLocked": "93802.500000",
+    "totalValueLockedUsd": "93802.500000", 
+    "delta24h": {
+      "absolute": "1250.500000",
+      "percentage": "1.3524"
+    },
+    "assetBreakdown": [
+      {
+        "assetCode": "USDC",
+        "balance": "50000.00000000",
+        "valueInBaseCurrency": "50000.000000",
+        "percentageOfTotal": 53.31,
+        "currentPrice": "1.00000000",
+        "priceChange24h": 0
+      }
+      // ... more assets
+    ],
+    "lastUpdated": "2026-04-28T14:30:00.000Z"
+  }
+}
+```
+
+## ✅ Acceptance Criteria Verification
+
+### AC1: Single-Currency View ✅
+- Merchants can view net protocol worth in their base currency
+- Supports USD, EUR, and other major currencies
+- Shows total value in both base currency and USD
+
+### AC2: Real-time Price Accuracy ✅  
+- 5-minute price freshness window enforced
+- Multiple price sources (Stellar, Coinbase, Binance)
+- USD-bridged conversion for unsupported pairs
+
+### AC3: Asset Exposure Breakdown ✅
+- Detailed breakdown by asset with percentages
+- Individual asset prices and 24h changes
+- Clear view of volatile token exposure
+
+## 🧪 Testing
+
+### Sample Data
+- 2 sample merchants with different base currencies
+- Multi-asset balances (XLM, USDC, EURC)
+- Current and historical price data
+
+### Test Coverage
+- Comprehensive test script (`test_treasury_endpoint.js`)
+- Database migrations and seed data
+- Error handling and edge cases
+
+## 📊 Files Added/Modified
+
+### New Files
+- `services/priceCacheService.js` - Price conversion service
+- `services/merchantService.js` - Merchant management service  
+- `services/treasuryService.js` - Consolidation logic service
+- `services/loggerService.js` - Logging utility
+- `routes/merchants.js` - Updated with treasury endpoints
+- `migrations/2024042800000*_create_*_table.js` - Database schema
+- `seeds/001_sample_merchants.js` - Sample data
+- `test_treasury_endpoint.js` - Test script
+
+### Modified Files
+- `index.js` - Added merchant routes and fixed route ordering
+
+## 🔒 Security & Compliance
+
+- **Authentication**: All treasury endpoints require JWT authentication
+- **Audit Trail**: All treasury views logged for compliance
+- **Rate Limiting**: Standard rate limiting applied
+- **Error Handling**: Comprehensive error responses
+- **Input Validation**: Proper sanitization throughout
+
+## 🚀 Performance
+
+- **Database Indexing**: Optimized queries on merchant_id, asset_code, timestamps
+- **Price Caching**: Efficient lookup with freshness checks
+- **Connection Pooling**: High concurrency support
+- **Batch Operations**: Historical data processing
+
+## 📋 Setup Instructions
+
+1. Run migrations: `npm run migrate`
+2. Seed data: `npm run seed`  
+3. Start server: `npm run dev`
+4. Test: `node test_treasury_endpoint.js`
+
+## 🎯 Business Impact
+
+**For Corporate Treasurers:**
+- Unified view of crypto-denominated revenue streams
+- Real-time risk assessment and exposure management
+- Performance tracking for treasury optimization
+
+**Technical Benefits:**
+- Scalable architecture supporting additional assets
+- Real-time price feeds from multiple exchanges
+- Comprehensive audit trail for compliance
+
+## 🔧 Integration Notes
+
+- **Authentication**: Uses existing `authenticateToken` middleware
+- **Database**: Integrates with existing Knex.js setup
+- **Error Handling**: Follows existing error response patterns
+- **Logging**: Uses custom logger service for consistency
+
+---
+
+**Status**: ✅ Ready for Review  
+**Testing**: ✅ Complete with sample data  
+**Documentation**: ✅ Comprehensive README included  
+
+This implementation fully addresses Issue #220 and provides enterprise-grade treasury management capabilities for organizations managing multi-cryptocurrency payment streams.
+
+### 📝 Next Steps for Reviewers
+
+1. Review database migrations for proper schema design
+2. Test API endpoints with provided test script
+3. Verify authentication and authorization logic
+4. Check error handling and edge cases
+5. Validate price conversion accuracy
+
+### 🧪 Quick Test Commands
+
+```bash
+# Setup database
+npm run migrate
+npm run seed
+
+# Start server
+npm run dev
+
+# Test endpoints (in separate terminal)
+node test_treasury_endpoint.js
+```