Merge branch 'main' into fix/gas-optimization

Author: Mystery-CLI

.env.example

@@ -20,3 +20,15 @@ ADMIN_KEYS=admin-key-123
 # ── Optional ─────────────────────────────────────────────────────────────────
 REDIS_URL=
 LOG_LEVEL=debug
+
+# ── Monitoring & Alerting ─────────────────────────────────────────────────────
+GRAFANA_ADMIN_PASSWORD=
+GRAFANA_URL=http://localhost:3002
+ALERT_WEBHOOK_URL=http://indexer:3000/monitoring/alerts
+INCIDENT_WEBHOOK_URL=http://indexer:3000/monitoring/alerts
+PAGERDUTY_ROUTING_KEY=
+ONCALL_EMAIL=oncall@stellarescrow.app
+SMTP_HOST=localhost:587
+SMTP_FROM=alerts@stellarescrow.app
+SMTP_USER=
+SMTP_PASSWORD=

.github/workflows/cost-report.yml

@@ -0,0 +1,52 @@
+name: Monthly Cost Report
+
+on:
+  schedule:
+    # 1st of every month at 08:00 UTC
+    - cron: '0 8 1 * *'
+  workflow_dispatch:
+    inputs:
+      month:
+        description: 'Month to report (YYYY-MM, default: current)'
+        required: false
+
+jobs:
+  cost-report:
+    name: Generate Cost Report
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Run cost report
+        run: |
+          MONTH="${{ github.event.inputs.month || '' }}"
+          if [[ -n "$MONTH" ]]; then
+            bash infra/cost/cost-report.sh "$MONTH" json
+          else
+            bash infra/cost/cost-report.sh --json
+          fi
+
+      - name: Upload report artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cost-report-${{ github.run_id }}
+          path: infra/cost/reports/
+          retention-days: 90
+
+      - name: Post summary to job
+        run: |
+          REPORT=$(ls infra/cost/reports/*.json | tail -1)
+          echo "## Cost Report" >> $GITHUB_STEP_SUMMARY
+          echo '```json' >> $GITHUB_STEP_SUMMARY
+          cat "$REPORT" | python3 -m json.tool >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY

.github/workflows/smart-contract-tests.yml

@@ -0,0 +1,54 @@
+name: Smart Contract Tests
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+concurrency:
+  group: smart-contract-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  contract-tests:
+    name: Contract Test Matrix
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@cargo-llvm-cov
+
+      - name: Edge cases
+        run: cargo test --manifest-path contract/Cargo.toml --test edge_cases
+
+      - name: Security scenarios
+        run: cargo test --manifest-path contract/Cargo.toml --test security
+
+      - name: Integration scenarios
+        run: cargo test --manifest-path contract/Cargo.toml --test integration
+
+      - name: Performance benchmarks
+        run: cargo test --manifest-path contract/Cargo.toml --test performance -- --nocapture
+
+      - name: Stress benchmarks
+        run: cargo test --manifest-path contract/Cargo.toml --test stress -- --nocapture
+
+      - name: Coverage report
+        run: cargo llvm-cov --manifest-path contract/Cargo.toml --workspace --lcov --output-path contract/coverage/lcov.info --html --output-dir contract/coverage/html
+
+      - name: Upload contract coverage
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: smart-contract-coverage-${{ github.run_number }}
+          path: contract/coverage/
+          retention-days: 30

PERFORMANCE.md

@@ -13,25 +13,54 @@ The script checks:
 1. **Slow queries** — `pg_stat_statements` top 10 by mean execution time
 2. **Index usage** — tables with low index-scan ratio (candidates for new indexes)
 3. **API latency** — live data from `/health/metrics`
-4. **Container resources** — CPU/memory via `docker stats`
-5. **Redis hit rate** — `keyspace_hits` vs `keyspace_misses`
+4. **APM bottlenecks** — live data from `/performance/bottlenecks` (slow queries + index usage + cache stats)
+5. **Container resources** — CPU/memory via `docker stats`
+6. **Redis hit rate** — `keyspace_hits` vs `keyspace_misses`
+
+### Live Bottleneck API
+
+`GET /performance/bottlenecks` returns a JSON report combining:
+- Top 10 slow queries from `pg_stat_statements`
+- Tables with low index-scan ratio
+- Current cache hit/miss stats
+
+```bash
+curl http://localhost:3000/performance/bottlenecks | jq .
+```
+
+### Slow Query Threshold
+
+Queries exceeding **100ms** are automatically logged to the `slow_query_log` table.
+Query the table to find recurring slow patterns:
+
+```sql
+SELECT query_hash, query_text, round(avg(duration_ms)::numeric, 1) AS avg_ms, count(*) AS hits
+FROM slow_query_log
+WHERE recorded_at > NOW() - INTERVAL '24 hours'
+GROUP BY query_hash, query_text
+ORDER BY avg_ms DESC
+LIMIT 20;
+```
 
 ---
 
 ## Caching Strategy
 
 ### Redis API Cache (`indexer/src/cache.rs`)
 
-| Endpoint pattern | TTL | Rationale |
-|-----------------|-----|-----------|
-| `GET /events*` | 10s | High-frequency reads; Stellar ledger closes every ~5s |
-| `GET /search*` | 30s | Search results change infrequently |
-| `GET /stats` | 60s | Aggregate — expensive to compute |
-| `POST /events/replay` | no cache | Mutating |
+| Endpoint pattern | TTL | Config key | Rationale |
+|-----------------|-----|-----------|-----------|
+| `GET /events*` | 10s | `events_ttl_secs` | High-frequency reads; Stellar ledger closes every ~5s |
+| `GET /search*` | 30s | `search_ttl_secs` | Search results change infrequently |
+| `GET /stats` | 60s | `stats_ttl_secs` | Aggregate — expensive to compute |
+| `GET /analytics/dashboard` | 60s | `analytics_ttl_secs` | Heavy aggregation query |
+| `POST /events/replay` | no cache | — | Mutating |
 
-**Activate:** set `redis_url` in `config.toml` or `REDIS_URL` env var.  
+**Activate:** set `redis_url` in `config.toml` or `STELLAR_ESCROW__CACHE__REDIS_URL` env var.  
 **Fallback:** if Redis is unavailable, all requests hit Postgres directly — no errors.
 
+All TTLs are configurable in `indexer/config.toml` under `[cache]`.
+
 ### Client-Side Cache (`frontend/performance.js`)
 
 `cachedFetch()` provides an in-memory TTL cache (default 30s) for API responses.  
@@ -50,6 +79,17 @@ Call `invalidateCache(url)` after any write operation to keep the UI consistent.
 
 ## Resource Allocation
 
+### Docker Resource Limits
+
+Applied in `docker-compose.yml` for all application services:
+
+| Service | CPU limit | Memory limit | CPU reservation | Memory reservation |
+|---------|-----------|-------------|-----------------|-------------------|
+| indexer | 1.0 | 512M | 0.25 | 128M |
+| api | 0.5 | 256M | 0.1 | 64M |
+
+Adjust limits based on observed usage from `docker stats` or the Grafana infrastructure dashboard.
+
 ### Database Connection Pool
 
 Configured in `indexer/config.toml`:
@@ -63,6 +103,8 @@ min_connections = 2    # keep warm connections ready
 **Rule of thumb:** `max_connections = (2 × CPU cores) + effective_spindle_count`  
 For a 4-core host: set `max_connections = 10–15`.
 
+Monitor pool saturation via `GET /performance/bottlenecks` → `index_usage` or the Grafana PostgreSQL connections panel.
+
 ### Nginx (`performance.nginx.conf`)
 
 - `worker_processes auto` — one worker per CPU core
@@ -94,14 +136,46 @@ Metrics are collected at three layers:
 | Layer | Mechanism | Endpoint |
 |-------|-----------|---------|
 | Infrastructure | `HealthMonitor` (Rust) | `GET /health/metrics` |
+| APM (request-level) | `PerformanceService` (Rust) | `GET /performance/dashboard` |
+| APM alerts | `PerformanceService` alert rules | `GET /performance/alerts` |
+| APM history | Hourly rollup (materialized view) | `GET /performance/history` |
+| Prometheus scrape | `MonitoringService` + APM metrics | `GET /metrics` |
 | Web Vitals | `observeWebVitals()` (JS) | beacons → `POST /api/metrics` |
 | CDN | `observeCdnPerformance()` (JS) | beacons → `POST /api/metrics` |
 | SSL | `monitorTlsConnection()` (JS) | beacons → `POST /api/metrics` |
 
+### APM Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /performance/dashboard` | Full APM snapshot: per-route stats, overall P95/P99, active alerts |
+| `GET /performance/alerts` | Active performance alerts only |
+| `GET /performance/history` | Hourly rollup from `perf_metrics_hourly` (last 24h) |
+| `POST /performance/record` | Ingest a sample `{ route, method, status, duration_ms }` |
+| `GET /metrics` | Prometheus text format (monitoring + APM metrics) |
+
+### Grafana Dashboards
+
+| Dashboard | UID | Description |
+|-----------|-----|-------------|
+| StellarEscrow Platform | `stellar-escrow-main` | Business metrics (trades, compliance, fraud) |
+| APM — Performance | `stellar-escrow-apm` | Latency (avg/P95/P99), error rate, throughput, DB query time |
+| Code Quality | `code-quality` | CI lint/security metrics |
+
+### Alert Rules
+
+| File | Group | Alerts |
+|------|-------|--------|
+| `alert_rules.yml` | `stellar_escrow_platform` | Error rate, disputes, fraud |
+| `alert_rules_security.yml` | `stellar_escrow_compliance` | AML, compliance blocks |
+| `alert_rules_performance.yml` | `stellar_escrow_performance` | Latency (avg/P95), error rate, DB queries, throughput |
+
 ### Key Metrics to Watch
 
 - **TTFB** < 200ms (good), < 800ms (acceptable)
 - **LCP** < 2.5s
+- **Avg response time** < 500ms (warning at 500ms, critical at 2000ms)
+- **P95 response time** < 1000ms (warning at 1000ms, critical at 5000ms)
 - **DB query mean** < 10ms for hot paths (`get_events`, `search_trades`)
 - **Redis hit rate** > 80% under normal load
 - **Indexer memory** < 256MB under normal load
@@ -111,8 +185,11 @@ Metrics are collected at three layers:
 ## Quick Wins Checklist
 
 - [ ] Enable Redis (`redis_url` in config) — eliminates repeat DB hits for read-heavy endpoints
-- [ ] Enable `pg_stat_statements` extension — required for slow query analysis
+- [ ] Enable `pg_stat_statements` extension — required for slow query analysis (migration `20260329000001_perf_optimization.sql` does this)
 - [ ] Set `max_connections` based on actual CPU count
 - [ ] Include `performance.nginx.conf` in nginx http block
-- [ ] Add `REDIS_URL` to docker-compose environment
+- [ ] Add `STELLAR_ESCROW__CACHE__REDIS_URL` to docker-compose environment
 - [ ] Run `perf-analyze.sh` weekly and track trends
+- [ ] Review `GET /performance/bottlenecks` after each deploy
+- [ ] Check `slow_query_log` table weekly for recurring slow patterns
+- [ ] Tune Docker resource limits based on `docker stats` observations

PR_DESCRIPTION.md

@@ -0,0 +1,26 @@
+## Summary
+
+- expands the Soroban smart contract suite with dedicated edge case, security, integration, performance, and stress coverage
+- repairs the contract core so the smart contract crate builds and all contract tests pass again
+- adds root test commands, contract testing docs, snapshot artifacts, and a GitHub Actions workflow for contract testing and coverage
+
+## What Changed
+
+- added shared contract test harnesses and new suites under `contract/tests/`
+- restored a working contract implementation in `contract/src/` for escrow, bridge, insurance, pause, compliance, migration, and analytics flows
+- enabled importing the contract crate in integration tests via `rlib`
+- documented the new contract test matrix and commands
+- added `.github/workflows/smart-contract-tests.yml`
+
+## Verification
+
+```bash
+cargo test --manifest-path contract/Cargo.toml
+```
+
+All contract unit, edge, security, integration, performance, and stress tests pass locally.
+
+## Notes
+
+- stress scenarios were tuned to stable CI-safe volumes so the Soroban test host does not hit budget exhaustion during the suite
+- contract snapshots were generated under `contract/test_snapshots/` during verification

README.md

@@ -56,3 +56,17 @@ cargo test  # Backend tests
 docker-compose up  # Indexer + DB
 ```
 
+## Smart Contract Testing
+
+The Soroban contract now has dedicated suites for edge cases, security scenarios, integration flows, stress tests, and performance benchmarks under `contract/tests/`.
+
+```bash
+npm run test:contract
+npm run test:contract:edge
+npm run test:contract:security
+npm run test:contract:integration
+npm run test:contract:performance
+npm run test:contract:stress
+npm run test:contract:coverage
+```
+

TESTING.md

@@ -15,6 +15,7 @@ This project uses a three-tier testing strategy:
 | Scalability | Jest + performance harness | `api/src/**/*.scalability.test.ts` | Throughput and latency trends across concurrency levels |
 | Monitoring | Jest + performance harness | `api/src/**/*.monitoring.test.ts` | Threshold alerts, error-rate visibility, and per-operation telemetry |
 | Security | Jest + scenario harness | `security/src/security.assessment.test.ts` | Penetration tests, vulnerability scans, compliance, monitoring |
+| Smart Contract | Soroban test harness | `contract/tests/*.rs`, `contract/tests/stress.rs` | Contract edge cases, security, integration, stress, benchmarks, coverage |
 | E2E | Cypress | `components/cypress/e2e/` | Full user flows |
 
 ## Running Tests
@@ -41,6 +42,15 @@ npm run test:docs --workspace=api
 npm run test:security
 npm run test:security --workspace=security
 
+# Smart contract suites
+npm run test:contract
+npm run test:contract:edge
+npm run test:contract:security
+npm run test:contract:integration
+npm run test:contract:performance
+npm run test:contract:stress
+npm run test:contract:coverage
+
 # E2E tests (requires app running on localhost:3000)
 npm run test:e2e
 
@@ -52,6 +62,7 @@ cd components && npm run test:watch
 
 All packages enforce **70% minimum** on branches, functions, lines, and statements.
 Coverage reports are written to `coverage/` in each package directory.
+For the contract crate, coverage artifacts are written to `contract/coverage/`.
 
 ## Unit Tests