feat: formal verification for rate/liquidation math, historical rate analytics, and cross-protocol ETL (#750)

- Add Kani/SMT-LIB formal verification for the interest rate model's
  boundary conditions (0%/100% utilization, kink continuity, monotonicity,
  overflow safety) in a new interest-rate-model-proofs crate.
- Add Kani/SMT-LIB formal verification for liquidation math in a new
  liquidation-math-proofs crate, backed by a new RiskManager::apply_liquidation
  in lending-risk (refactored onto checked safe-math arithmetic). The proofs
  surface a real finding: liquidation with a bonus can worsen health factor
  for deeply under-collateralized positions, and prove the precise ratio
  condition under which it does/doesn't.
- Fix pre-existing compile breakage blocking all formal-verification crates:
  stellarlend-safe-math's PrecisionLoss missing #[contracttype], I256::rem
  (no such method; use rem_euclid), and Kani dev-dependencies declared as
  `optional` (unsupported by current Cargo) pointing at a nonexistent
  crates.io version.
- Extend historical rate analytics: rolling rate volatility (std dev),
  weighted average rates by day/week/month, derived rate-change events, and
  a GET /api/rates/history?asset=&from=&to=&granularity= endpoint.
- Add a cross-protocol ETL pipeline (services/cross-protocol-etl) with a
  standardized metrics schema, a StellarLend adapter, a DefiLlama-backed
  adapter for Aave/Compound/Morpho/Spark, per-adapter failure isolation,
  data-quality checks, TVL-weighted market share, and comparison/leaderboard
  endpoints under /api/cross-protocol.

Closes #458
Closes #459
Closes #460
Closes #461

Author: codeX-james

api/src/__tests__/analytics.service.test.ts

@@ -0,0 +1,146 @@
+import {
+  getRateVolatility,
+  getWeightedAverageRates,
+  getRateChangeEvents,
+  getRateHistoryRange,
+} from '../services/analytics.service';
+import { StellarService } from '../services/stellar.service';
+import { redisCacheService } from '../services/redisCache.service';
+import { ValidationError } from '../utils/errors';
+
+describe('analytics.service — historical rate analytics', () => {
+  let getPoolRateAtSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    redisCacheService.clearAllForTests();
+    // Deterministic, monotonically increasing borrow APY per call so
+    // volatility/weighted-average/rate-change tests have real variance to
+    // observe (the default simulated implementation returns a constant
+    // rate per pool address, which would make every metric trivially zero).
+    let call = 0;
+    getPoolRateAtSpy = jest
+      .spyOn(StellarService.prototype, 'getPoolRateAt')
+      .mockImplementation(async () => {
+        call += 1;
+        const borrowApy = 0.05 + (call % 5) * 0.01;
+        return {
+          depositApy: borrowApy * 0.7,
+          borrowApy,
+          utilizationRate: 0.5,
+        };
+      });
+  });
+
+  afterEach(() => {
+    getPoolRateAtSpy.mockRestore();
+  });
+
+  describe('getRateVolatility', () => {
+    it('computes a rolling standard deviation with the requested window size', async () => {
+      const result = await getRateVolatility({ timeRange: '7d', poolAddress: 'pool_a' }, 5);
+      expect(result.length).toBeGreaterThan(0);
+      for (const point of result) {
+        expect(point.windowSize).toBe(5);
+        expect(point.borrowApyStdDev).toBeGreaterThanOrEqual(0);
+        expect(point.depositApyStdDev).toBeGreaterThanOrEqual(0);
+      }
+      // With varying rates, at least one window should show non-zero volatility.
+      expect(result.some((p) => p.borrowApyStdDev > 0)).toBe(true);
+    });
+
+    it('returns an empty array when there are fewer samples than the window size', async () => {
+      const result = await getRateVolatility({ timeRange: '7d', poolAddress: 'pool_b' }, 1000);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('getWeightedAverageRates', () => {
+    it('buckets rate points by the requested granularity', async () => {
+      const result = await getWeightedAverageRates(
+        { timeRange: '30d', poolAddress: 'pool_c' },
+        'weekly'
+      );
+      expect(result.length).toBeGreaterThan(0);
+      for (const bucket of result) {
+        expect(bucket.granularity).toBe('weekly');
+        expect(bucket.sampleCount).toBeGreaterThan(0);
+        expect(new Date(bucket.periodStart).getTime()).toBeLessThan(
+          new Date(bucket.periodEnd).getTime()
+        );
+      }
+    });
+
+    it('sorts buckets chronologically', async () => {
+      const result = await getWeightedAverageRates(
+        { timeRange: '30d', poolAddress: 'pool_d' },
+        'daily'
+      );
+      const starts = result.map((b) => new Date(b.periodStart).getTime());
+      const sorted = [...starts].sort((a, b) => a - b);
+      expect(starts).toEqual(sorted);
+    });
+  });
+
+  describe('getRateChangeEvents', () => {
+    it('flags borrow-rate moves at or above the threshold', async () => {
+      const events = await getRateChangeEvents({ timeRange: '7d', poolAddress: 'pool_e' }, 10);
+      expect(events.length).toBeGreaterThan(0);
+      for (const event of events) {
+        expect(Math.abs(event.deltaBps)).toBeGreaterThanOrEqual(10);
+        expect(['increase', 'decrease']).toContain(event.changeType);
+        expect(event.governanceActionId).toBeUndefined();
+      }
+    });
+
+    it('finds no events when the threshold is set impossibly high', async () => {
+      const events = await getRateChangeEvents(
+        { timeRange: '7d', poolAddress: 'pool_f' },
+        1_000_000
+      );
+      expect(events).toEqual([]);
+    });
+  });
+
+  describe('getRateHistoryRange', () => {
+    it('returns daily-bucketed points across an explicit date range', async () => {
+      const from = '2024-01-01T00:00:00.000Z';
+      const to = '2024-01-05T00:00:00.000Z';
+      const result = await getRateHistoryRange({ asset: 'pool_g', from, to, granularity: 'daily' });
+      expect(result.length).toBe(5); // Jan 1..5 inclusive at daily granularity
+      expect(result[0]!.poolAddress).toBe('pool_g');
+    });
+
+    it('rejects a `from` after `to`', async () => {
+      await expect(
+        getRateHistoryRange({
+          asset: 'pool_h',
+          from: '2024-01-05T00:00:00.000Z',
+          to: '2024-01-01T00:00:00.000Z',
+        })
+      ).rejects.toThrow(ValidationError);
+    });
+
+    it('rejects an invalid date string', async () => {
+      await expect(
+        getRateHistoryRange({ asset: 'pool_i', from: 'not-a-date', to: '2024-01-01T00:00:00.000Z' })
+      ).rejects.toThrow(ValidationError);
+    });
+
+    it('rejects a range that would exceed the maximum bucket count', async () => {
+      await expect(
+        getRateHistoryRange({
+          asset: 'pool_j',
+          from: '2000-01-01T00:00:00.000Z',
+          to: '2024-01-01T00:00:00.000Z',
+          granularity: 'hourly',
+        })
+      ).rejects.toThrow(ValidationError);
+    });
+
+    it('defaults to the last 7 days at daily granularity when no range is given', async () => {
+      const result = await getRateHistoryRange({ asset: 'pool_k' });
+      expect(result.length).toBeGreaterThan(0);
+      expect(result.length).toBeLessThanOrEqual(8);
+    });
+  });
+});

api/src/__tests__/crossProtocolEtl.service.test.ts

@@ -0,0 +1,165 @@
+import {
+  refreshCrossProtocolData,
+  getCrossProtocolComparison,
+  computeMarketShare,
+  getLeaderboard,
+} from '../services/cross-protocol-etl/etl.service';
+import { ProtocolAdapter, StandardizedProtocolMetrics } from '../services/cross-protocol-etl/types';
+import { redisCacheService } from '../services/redisCache.service';
+
+function metric(overrides: Partial<StandardizedProtocolMetrics> = {}): StandardizedProtocolMetrics {
+  return {
+    protocol: 'test-protocol',
+    displayName: 'Test Protocol',
+    chain: 'test-chain',
+    asset: 'USDC',
+    supplyApy: 0.03,
+    borrowApy: 0.05,
+    tvlUsd: 1_000_000,
+    utilizationRate: 0.6,
+    fetchedAt: new Date().toISOString(),
+    source: 'test',
+    ...overrides,
+  };
+}
+
+function fakeAdapter(protocolId: string, metrics: StandardizedProtocolMetrics[]): ProtocolAdapter {
+  return {
+    protocolId,
+    displayName: protocolId,
+    fetchMetrics: async () => metrics,
+  };
+}
+
+function failingAdapter(protocolId: string, error: Error): ProtocolAdapter {
+  return {
+    protocolId,
+    displayName: protocolId,
+    fetchMetrics: async () => {
+      throw error;
+    },
+  };
+}
+
+describe('cross-protocol-etl.service', () => {
+  beforeEach(() => {
+    redisCacheService.clearAllForTests();
+  });
+
+  describe('refreshCrossProtocolData', () => {
+    it('merges metrics from all adapters', async () => {
+      const adapters = [
+        fakeAdapter('a', [metric({ protocol: 'a', asset: 'USDC' })]),
+        fakeAdapter('b', [metric({ protocol: 'b', asset: 'USDT' })]),
+      ];
+      const result = await refreshCrossProtocolData(adapters);
+      expect(result.metrics).toHaveLength(2);
+      expect(result.failedSources).toEqual([]);
+      expect(result.metrics.map((m) => m.protocol).sort()).toEqual(['a', 'b']);
+    });
+
+    it('isolates a failing adapter without blocking the others', async () => {
+      const adapters = [
+        fakeAdapter('good', [metric({ protocol: 'good' })]),
+        failingAdapter('bad', new Error('upstream unreachable')),
+      ];
+      const result = await refreshCrossProtocolData(adapters);
+      expect(result.metrics).toHaveLength(1);
+      expect(result.metrics[0]!.protocol).toBe('good');
+      expect(result.failedSources).toEqual(['bad']);
+    });
+
+    it('filters out metrics that fail data quality checks', async () => {
+      const adapters = [
+        fakeAdapter('mixed', [
+          metric({ protocol: 'mixed', asset: 'GOOD' }),
+          metric({ protocol: 'mixed', asset: 'BAD_APY', supplyApy: 50 }), // 5000% APY — implausible
+          metric({ protocol: 'mixed', asset: 'BAD_UTIL', utilizationRate: 1.5 }),
+          metric({ protocol: 'mixed', asset: 'BAD_TVL', tvlUsd: -100 }),
+        ]),
+      ];
+      const result = await refreshCrossProtocolData(adapters);
+      expect(result.metrics).toHaveLength(1);
+      expect(result.metrics[0]!.asset).toBe('GOOD');
+      expect(result.qualityIssues).toHaveLength(3);
+      expect(result.qualityIssues.map((i) => i.asset).sort()).toEqual([
+        'BAD_APY',
+        'BAD_TVL',
+        'BAD_UTIL',
+      ]);
+    });
+  });
+
+  describe('getCrossProtocolComparison caching', () => {
+    it('caches the result so a second call does not re-invoke adapters', async () => {
+      let calls = 0;
+      const adapters = [
+        {
+          protocolId: 'counted',
+          displayName: 'counted',
+          fetchMetrics: async () => {
+            calls += 1;
+            return [metric({ protocol: 'counted' })];
+          },
+        },
+      ];
+      await getCrossProtocolComparison(adapters);
+      await getCrossProtocolComparison(adapters);
+      expect(calls).toBe(1);
+    });
+  });
+
+  describe('computeMarketShare', () => {
+    it('computes TVL-weighted share per protocol, sorted descending', () => {
+      const metrics = [
+        metric({ protocol: 'big', tvlUsd: 750 }),
+        metric({ protocol: 'small', tvlUsd: 250 }),
+      ];
+      const shares = computeMarketShare(metrics);
+      expect(shares).toEqual([
+        { protocol: 'big', tvlUsd: 750, marketSharePct: 75 },
+        { protocol: 'small', tvlUsd: 250, marketSharePct: 25 },
+      ]);
+    });
+
+    it('sums TVL across multiple pools of the same protocol', () => {
+      const metrics = [
+        metric({ protocol: 'multi', asset: 'USDC', tvlUsd: 400 }),
+        metric({ protocol: 'multi', asset: 'USDT', tvlUsd: 600 }),
+      ];
+      const shares = computeMarketShare(metrics);
+      expect(shares).toEqual([{ protocol: 'multi', tvlUsd: 1000, marketSharePct: 100 }]);
+    });
+
+    it('returns 0% shares (not NaN) when total TVL is zero', () => {
+      const shares = computeMarketShare([metric({ tvlUsd: 0 })]);
+      expect(shares[0]!.marketSharePct).toBe(0);
+    });
+  });
+
+  describe('getLeaderboard', () => {
+    it('ranks protocols by the requested metric, descending', async () => {
+      const adapters = [
+        fakeAdapter('x', [
+          metric({ protocol: 'low-apy', supplyApy: 0.01, tvlUsd: 100 }),
+          metric({ protocol: 'high-apy', supplyApy: 0.09, tvlUsd: 50 }),
+        ]),
+      ];
+      const board = await getLeaderboard('supplyApy', 10, adapters);
+      expect(board.map((e) => e.protocol)).toEqual(['high-apy', 'low-apy']);
+      expect(board[0]!.rank).toBe(1);
+      expect(board[0]!.metricValue).toBe(0.09);
+    });
+
+    it('respects the limit', async () => {
+      const adapters = [
+        fakeAdapter(
+          'many',
+          Array.from({ length: 5 }, (_, i) => metric({ protocol: `p${i}`, tvlUsd: i }))
+        ),
+      ];
+      const board = await getLeaderboard('tvlUsd', 2, adapters);
+      expect(board).toHaveLength(2);
+    });
+  });
+});

api/src/__tests__/defiLlamaAdapter.test.ts

@@ -0,0 +1,61 @@
+import axios from 'axios';
+import { DefiLlamaAdapter } from '../services/cross-protocol-etl/adapters/defiLlamaAdapter';
+
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+describe('DefiLlamaAdapter', () => {
+  it('normalizes tracked-project pools into StandardizedProtocolMetrics', async () => {
+    mockedAxios.get.mockResolvedValueOnce({
+      data: {
+        status: 'success',
+        data: [
+          { chain: 'Ethereum', project: 'aave-v3', symbol: 'USDC', tvlUsd: 500_000_000, apy: 3.2 },
+          {
+            chain: 'Ethereum',
+            project: 'compound-v3',
+            symbol: 'USDC',
+            tvlUsd: 200_000_000,
+            apy: 2.8,
+          },
+          // Untracked project must be filtered out.
+          { chain: 'Ethereum', project: 'some-random-farm', symbol: 'USDC', tvlUsd: 10, apy: 999 },
+        ],
+      },
+    });
+
+    const adapter = new DefiLlamaAdapter();
+    const metrics = await adapter.fetchMetrics();
+
+    expect(metrics).toHaveLength(2);
+    expect(metrics.map((m) => m.protocol).sort()).toEqual(['aave-v3', 'compound-v3']);
+
+    const aave = metrics.find((m) => m.protocol === 'aave-v3')!;
+    expect(aave.supplyApy).toBeCloseTo(0.032);
+    expect(aave.tvlUsd).toBe(500_000_000);
+    expect(aave.chain).toBe('Ethereum');
+    expect(aave.source).toBe('defillama');
+    // Honestly zeroed, not fabricated — see adapter doc comment.
+    expect(aave.borrowApy).toBe(0);
+    expect(aave.utilizationRate).toBe(0);
+  });
+
+  it('handles a null apy without throwing', async () => {
+    mockedAxios.get.mockResolvedValueOnce({
+      data: {
+        status: 'success',
+        data: [{ chain: 'Ethereum', project: 'spark', symbol: 'DAI', tvlUsd: 1000, apy: null }],
+      },
+    });
+
+    const adapter = new DefiLlamaAdapter();
+    const metrics = await adapter.fetchMetrics();
+    expect(metrics[0]!.supplyApy).toBe(0);
+  });
+
+  it('propagates upstream errors so the ETL orchestrator can isolate them', async () => {
+    mockedAxios.get.mockRejectedValueOnce(new Error('network error'));
+    const adapter = new DefiLlamaAdapter();
+    await expect(adapter.fetchMetrics()).rejects.toThrow('network error');
+  });
+});