feat(#104): Performance optimization and caching

.github/PR_DRAFT_104.md

@@ -0,0 +1,118 @@
+# 🚀 Pull Request
+
+## 📋 Description
+Implements **#104 – Develop Advanced Performance Optimization and Caching**: intelligent caching, query optimization, performance monitoring, and regression testing in both the Soroban contract and the NestJS indexer.
+
+**Contract:** Performance cache module stores a bridge summary (health score + top chains by volume) with 1-hour TTL; admin can invalidate cache; bounded chain iteration for gas; new events for cache compute/invalidate.
+
+**Indexer:** In-memory cache (60s TTL) for dashboard analytics; dashboard aggregates use SQL SUM/COUNT/AVG instead of full-table loads; `GET /health` and `GET /metrics` for load balancers and monitoring; MetricsService tracks cache hit rate and latency; dashboard tests include cache behavior and a 2s latency regression test.
+
+## 🔗 Related Issue(s)
+- Closes #104
+
+## 🎯 Type of Change
+- [x] ✨ New feature (non-breaking change that adds functionality)
+- [x] ⚡ Performance improvements
+
+## 📝 Changes Made
+- **Contract**
+  - Added `performance.rs`: `PerformanceManager` with `get_cached_summary`, `compute_and_cache_summary`, `get_or_compute_summary`, `invalidate_cache(admin)`; `CachedBridgeSummary` type; storage keys `PERF_CACHE`, `PERF_TS`; events `PerfMetricsComputedEvent`, `PerfCacheInvalidatedEvent`.
+  - Added `get_top_chains_by_volume_bounded` in `analytics.rs` (max 50 chains) for gas-bound cache; kept existing `get_top_chains_by_volume` for backward compatibility.
+  - Wired performance module in `lib.rs`; public API: `get_cached_bridge_summary`, `compute_and_cache_bridge_summary`, `invalidate_performance_cache`.
+  - Added `contracts/teachlink/tests/test_performance.rs` (registration + type tests).
+- **Indexer**
+  - `CacheModule` (60s TTL, global) in `AppModule`; `DashboardService` caches `getCurrentAnalytics()` with key `dashboard:analytics`; `invalidateDashboardCache()` for manual invalidation.
+  - Dashboard query optimization: escrow/reward totals via `SUM`/`COUNT`/`AVG` in SQL (no full-table `find()` + reduce).
+  - New `PerformanceModule`: `MetricsService` (request count, cache hits/misses, last dashboard ms, uptime), `PerformanceController` with `GET /health` and `GET /metrics`.
+  - Dashboard spec: `CACHE_MANAGER` and `MetricsService` mocks; cache-hit test; performance regression test (getCurrentAnalytics < 2s); fixed `generatedBy`/`save` types in `dashboard.service.ts`.
+  - `IMPLEMENTATION.md`: new “Performance optimization and caching” section.
+
+## 🧪 Testing
+
+### ✅ Pre-Merge Checklist (Required)
+- [ ] 🧪 **Unit Tests**: Contract tests include `test_performance.rs`; indexer: `npx jest --testPathPattern="dashboard"` passes (7 tests).
+- [ ] 🔨 **Debug Build**: `cargo build` (may require MSVC on Windows; CI runs on Linux).
+- [ ] 🎯 **WASM Build**: `cargo build -p teachlink-contract --target wasm32-unknown-unknown` or `.\scripts\check-wasm.ps1` on Windows.
+- [ ] 📝 **Code Formatting**: `cargo fmt --all -- --check`
+- [ ] 🔍 **Clippy Lints**: `cargo clippy`
+
+### 📋 Test Results
+```
+# Indexer dashboard tests
+npx jest --testPathPattern="dashboard" --passWithNoTests
+ PASS  src/reporting/dashboard.service.spec.ts
+  DashboardService
+    √ should be defined
+    getCurrentAnalytics
+      √ should return dashboard analytics with zeroed metrics when no data
+      √ should include success rate and health score fields
+      √ should return cached result when cache hit
+      √ performance: getCurrentAnalytics completes within 2s (regression)
+    saveSnapshot
+      √ should create and save a dashboard snapshot
+    getSnapshots
+      √ should return snapshots for period
+ Test Suites: 1 passed, 1 total
+ Tests: 7 passed, 7 total
+```
+
+## 🔍 Review Checklist
+
+### 📝 Code Quality
+- [x] My code follows the project's style guidelines
+- [x] I have performed a self-review of my own code
+- [x] I have commented my code, particularly in hard-to-understand areas
+- [x] My changes generate no new warnings or errors
+
+### 🧪 Testing Requirements
+- [x] I have added/updated tests that prove my fix is effective or that my feature works
+- [x] New and existing unit tests pass locally with my changes
+
+### 📚 Documentation
+- [x] I have updated the documentation accordingly (IMPLEMENTATION.md)
+
+### 🔒 Security
+- [x] I have not committed any secrets, keys, or sensitive data
+- [x] My changes do not introduce known vulnerabilities
+
+### 🏗️ Contract-Specific (if applicable)
+- [x] Storage changes are backward compatible (new keys only)
+- [x] Event emissions are appropriate and documented
+- [x] Gas/resource usage has been considered (bounded iteration, cache reduces repeated reads)
+
+## 💥 Breaking Changes
+- [ ] This PR introduces breaking changes
+- **N/A**: New APIs only; existing behavior unchanged.
+
+## 📊 Performance Impact
+- **CPU/Memory**: Indexer: lower DB load for repeated dashboard requests (cache); fewer rows loaded (aggregates only). Contract: cached summary reduces repeated heavy reads when callers use `get_cached_bridge_summary`.
+- **Gas costs**: Contract: bounded `get_top_chains_by_volume_bounded` caps iteration; cache avoids recompute within TTL.
+- **Network**: No change.
+
+## 🔒 Security Considerations
+- **Risks**: None identified; cache is in-memory (indexer) and instance storage (contract); invalidation is admin-only on contract.
+- **Mitigations**: N/A.
+
+## 🚀 Deployment Notes
+- [ ] Requires contract redeployment (new contract code with performance module)
+- [ ] Requires data migration: No
+- [ ] Requires configuration changes: No (indexer cache is default 60s TTL)
+- [ ] No deployment changes needed for indexer beyond deploy of new code
+
+## 📋 Reviewer Checklist
+- [ ] 📝 Code review completed
+- [ ] 🧪 Tests verified
+- [ ] 📚 Documentation reviewed
+- [ ] 🔒 Security considerations reviewed
+- [ ] 🏗️ Architecture/design reviewed
+- [ ] ✅ Approved for merge
+
+---
+
+**🎯 Ready for Review**: 
+- [ ] Yes, all required checks pass and I'm ready for review
+- [ ] No, I need to fix some issues first
+
+---
+
+*Thank you for contributing to TeachLink! 🚀*

README.md

@@ -409,6 +409,18 @@ fn hello_returns_input() {
 - `curl not found` while funding
   - Install curl or fund the account manually using the friendbot URL
 
+### Windows: linker or "export ordinal too large"
+
+On Windows, `cargo test` may fail with **`link.exe` not found** (MSVC) or **`export ordinal too large: 79994`** (MinGW). The contract has many exports, which can exceed MinGW’s DLL limit.
+
+- **Verify the contract (WASM only, no tests):**
+  ```powershell
+  .\scripts\check-wasm.ps1
+  ```
+  Or: `cargo build -p teachlink-contract --target wasm32-unknown-unknown`
+- **Run full tests:** Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with "Desktop development with C++", then use the default (MSVC) toolchain and run `cargo test -p teachlink-contract`.
+- **Otherwise:** Rely on CI (GitHub Actions) for `cargo test`; the WASM build is what gets deployed.
+
 ## License
 
 This project is licensed under the MIT License. See `LICENSE` for details.

contracts/teachlink/src/analytics.rs

@@ -279,7 +279,51 @@ impl AnalyticsManager {
         ((success_score * 40) + (validator_score * 30) + (confirmation_score * 30)) / 100
     }
 
-    /// Get top chains by volume
+    /// Max chains to iterate when building top-by-volume (gas bound).
+    const MAX_CHAINS_ITER: u32 = 50;
+
+    /// Get top chains by volume with bounded iteration (for performance cache).
+    pub fn get_top_chains_by_volume_bounded(env: &Env, limit: u32) -> Vec<(u32, i128)> {
+        let chain_metrics: Map<u32, ChainMetrics> = env
+            .storage()
+            .instance()
+            .get(&CHAIN_METRICS)
+            .unwrap_or_else(|| Map::new(env));
+
+        let mut chains: Vec<(u32, i128)> = Vec::new(env);
+        let mut count = 0u32;
+        for (chain_id, metrics) in chain_metrics.iter() {
+            if count >= Self::MAX_CHAINS_ITER {
+                break;
+            }
+            count += 1;
+            let total_volume = metrics.volume_in + metrics.volume_out;
+            chains.push_back((chain_id, total_volume));
+        }
+
+        let len = chains.len();
+        for i in 0..len {
+            for j in 0..(len - i - 1) {
+                let (_, vol_a) = chains.get(j).unwrap();
+                let (_, vol_b) = chains.get(j + 1).unwrap();
+                if vol_a < vol_b {
+                    let temp = chains.get(j).unwrap();
+                    chains.set(j, chains.get(j + 1).unwrap());
+                    chains.set(j + 1, temp);
+                }
+            }
+        }
+
+        let mut result = Vec::new(env);
+        for i in 0..limit.min(chains.len()) {
+            if let Some(chain) = chains.get(i) {
+                result.push_back(chain);
+            }
+        }
+        result
+    }
+
+    /// Get top chains by volume (unbounded; use get_top_chains_by_volume_bounded for caching).
     pub fn get_top_chains_by_volume(env: &Env, limit: u32) -> Vec<(u32, i128)> {
         let chain_metrics: Map<u32, ChainMetrics> = env
             .storage()