feat: Add Merkle distributor, PnL engine, CSV export & referral system

[Akanimoh12]

feat: Add Merkle Distributor, PnL Engine, CSV Export & Referral System

Summary

This PR implements four new features for the StellarYield platform, spanning smart contracts, backend services, and frontend components with comprehensive test coverage.

Closes #106, Closes #107, Closes #113, Closes #115

---

Changes

1. Merkle Tree Airdrop Distributor (Issue #106)

Smart Contract (contracts/merkle_distributor/)

• Soroban contract with SHA256 Merkle proof verification
• Bitmap-based claim tracking (u128 words) for gas-efficient duplicate prevention
• Epoch-based root updates allowing multiple airdrop rounds
• Admin-only set_merkle_root with automatic epoch increment
• Full error handling: AlreadyClaimed, InvalidProof, ZeroAmount, InsufficientBalance, etc.

Backend (backend/rewards/)

• MerkleTree class with sorted-pair SHA256 hashing (matches on-chain logic)
• generateTree utility for building trees from address/amount pairs
• Proof generation and verification utilities

Frontend (client/src/features/rewards/ClaimRewards.tsx)

• Wallet-connected claim interface with proof submission
• Real-time claim status feedback

Tests: 12 contract tests + 32 backend tests

2. PnL Tracking Engine (Issue #107)

Backend Services (server/src/services/pnl_engine/)

• Time-Weighted Return (TWR) calculator with sub-period compounding
• Daily snapshot generation from share price history
• calculatePnL aggregating deposits, withdrawals, and unrealized gains

Infrastructure

• sharePriceSnapshot cron job running daily at 00:00 UTC (server/src/jobs/)
• REST endpoint: GET /api/users/:address/pnl (server/src/routes/pnl.ts)
• Prisma models: SharePriceSnapshot, UserTransaction

Frontend (client/src/features/pnl/PnLChart.tsx)

• Recharts area chart with date-based PnL visualization
• Auto-fetch on wallet connection

Tests: 15 test cases covering calculations, edge cases, and error handling

3. CSV Export for Tax Reporting (Issue #113)

Backend Services (server/src/services/export/)

• In-memory CSV generation for small datasets
• Streaming CSV generator with batched processing (100 records per batch)
• Configurable report types: transaction_history, pnl_summary
• createExportFilename with timestamp-based naming

Infrastructure

• Rate-limited endpoint: GET /api/users/:address/export (5 requests per 15 minutes)
• Prisma model: ExportJob for tracking export history

Frontend (client/src/features/taxes/TaxExport.tsx)

• One-click CSV download with format selection
• Loading states and error handling

Tests: 14 test cases covering generation, streaming, and edge cases

4. Referral & Affiliate System (Issue #115)

Smart Contract (contracts/yield_vault/src/referrals.rs)

• On-chain referral registration with first-referrer-wins policy
• Self-referral prevention
• Configurable referral fee: default 500 bps (5%), max 1000 bps (10%)
• Automatic reward accrual on deposit_with_referral
• claim_referral_rewards with token transfer to referrer
• Admin-only fee configuration with automatic clamping to valid range

Frontend (client/src/features/referrals/ReferralDashboard.tsx)

• Referral link generation and sharing
• Referred TVL and reward tracking
• One-click reward claiming

Tests: 17 contract tests covering registration, deposits, reward accrual/claiming, fee management, admin controls, and edge cases

---

Files Changed

New Files (62)

• contracts/merkle_distributor/ - Complete Soroban merkle distributor contract
• contracts/yield_vault/src/referrals.rs - Referral system module
• backend/rewards/ - Merkle tree generator package
• server/src/services/pnl_engine/ - PnL calculation services
• server/src/services/export/ - CSV export services
• server/src/jobs/sharePriceSnapshot.ts - Daily cron job
• server/src/routes/{pnl,export}.ts - API endpoints
• server/src/__tests__/{pnlCalculator,csvExport}.test.ts - Server tests
• client/src/features/{rewards,pnl,taxes,referrals}/ - UI components
• Test snapshot JSON files for contract tests

Modified Files (7)

• contracts/Cargo.toml - Added merkle_distributor to workspace
• contracts/Cargo.lock - Updated dependencies
• contracts/yield_vault/src/lib.rs - Added referral module + wrapper functions + tests
• server/prisma/schema.prisma - Added 4 new models
• server/src/app.ts - Registered new routes
• server/src/index.ts - Added cron job startup
• client/src/App.tsx - Added routes and navigation

---

Testing

Package	Tests	Status
contracts/merkle_distributor	12	✅ Pass
contracts/yield_vault (referral)	17	✅ Pass
contracts/yield_vault (existing)	18	✅ Pass
server (PnL + CSV)	29	✅ Pass
backend/rewards (Merkle)	32	✅ Pass
Total	108	✅ All Pass

All code passes cargo clippy --all-targets -- -D warnings and cargo fmt --check.

---

Architecture Decisions

• Delegation pattern for referral contract: Plain impl functions in referrals.rs called by wrapper methods in the main #[contractimpl] block, avoiding multiple contractimpl conflicts (consistent with existing flashloan.rs pattern)
• Bitmap claim tracking: Uses u128 words for gas-efficient on-chain storage of claim status
• Streaming CSV: Batched processing (100 records) for memory-efficient large exports
• Rate limiting: Export endpoint limited to 5 requests per 15-minute window to prevent abuse

[vercel]

@Akanimoh12 is attempting to deploy a commit to the Edeh Victor's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

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