Merge pull request #1566 from AlienScroll78/feature/cvar-var-auto-pause

feat(risk): add configurable CVaR/VaR auto-pause with notifications

Author: ritik4ever

backend/src/queue/workers/portfolioCheckWorker.ts

@@ -76,6 +76,20 @@ export async function processPortfolioCheckJob(
 
     const stellarService = new StellarService();
     for (const p of portfolios) {
+      // Skip portfolios that have been auto-paused due to a CVaR/VaR breach
+      if (p.riskPausedUntil && new Date(p.riskPausedUntil) > new Date()) {
+        logger.info(
+          "[WORKER:portfolio-check] Skipping risk-paused portfolio",
+          {
+            jobId: job.id,
+            portfolioId: p.id,
+            riskPausedUntil: p.riskPausedUntil,
+            correlationId,
+          },
+        );
+        continue;
+      }
+
       const needed = await stellarService.checkRebalanceNeeded(p.id);
       if (!needed) continue;
 

backend/src/services/notificationTemplates.ts

@@ -27,6 +27,16 @@ export interface RiskChangeData {
   portfolioId: string
   oldLevel: string
   newLevel: string
+  /** Optional: breach details when auto-pause was triggered by a CVaR/VaR threshold. */
+  autoPause?: {
+    reason: 'VAR_BREACH' | 'CVAR_BREACH'
+    /** Measured value as a percentage string e.g. "14.23%" */
+    measuredValue: string
+    /** Threshold as a percentage string e.g. "12.00%" */
+    threshold: string
+    /** ISO string of when the pause expires */
+    pausedUntil: string
+  }
 }
 
 export type NotificationTemplateData =
@@ -65,9 +75,21 @@ const templates: {
     message: (d) => `${d.asset} has ${d.direction} by ${d.priceChange}%.`,
   },
   riskChange: {
-    title: () => 'Portfolio Risk Level Changed',
-    message: (d) =>
-      `Your portfolio risk level changed from ${d.oldLevel} to ${d.newLevel}.`,
+    title: (d) => d.autoPause ? 'Rebalancing Auto-Paused: Risk Threshold Breached' : 'Portfolio Risk Level Changed',
+    message: (d) => {
+      if (d.autoPause) {
+        const metricLabel = d.autoPause.reason === 'VAR_BREACH' ? 'VaR(95)' : 'CVaR(95)'
+        const pauseDate = new Date(d.autoPause.pausedUntil).toLocaleString('en-US', { timeZoneName: 'short' })
+        return (
+          `Scheduled rebalancing for portfolio ${d.portfolioId} has been automatically paused because the ` +
+          `${metricLabel} limit was exceeded (measured: ${d.autoPause.measuredValue}, threshold: ${d.autoPause.threshold}). ` +
+          `Rebalancing is suspended until ${pauseDate}. ` +
+          `Risk level: ${d.oldLevel} → ${d.newLevel}. ` +
+          `Review your portfolio and market conditions before resuming.`
+        )
+      }
+      return `Your portfolio risk level changed from ${d.oldLevel} to ${d.newLevel}.`
+    },
   },
 }
 

backend/src/services/riskManagements.ts

@@ -1,6 +1,9 @@
 import type { PricesMap, RiskHeatmap } from '../types/index.js'
 import { assetRegistryService } from './assetRegistryService.js'
 import { logger } from '../utils/logger.js'
+import { notificationService } from './notificationService.js'
+import { buildNotificationPayload } from './notificationTemplates.js'
+import { portfolioStorage } from './portfolioStorage.js'
 
 export interface StatisticalRiskMetrics {
     ewmaVolatility: number
@@ -45,6 +48,25 @@ export type RiskDecisionReasonCode =
     | 'STAT_MODEL_CVAR_BREACH'
     | 'STAT_MODEL_DRAWDOWN_BREACH'
 
+export interface AutoPauseThresholds {
+    /** VaR(95) level that triggers an auto-pause. Expressed as a decimal fraction (e.g. 0.12 = 12%). */
+    var95?: number
+    /** CVaR(95) level that triggers an auto-pause. Expressed as a decimal fraction (e.g. 0.16 = 16%). */
+    cvar95?: number
+    /** How many milliseconds to pause the portfolio for once a breach is detected. Default: 24 hours. */
+    pauseDurationMs?: number
+}
+
+export interface CVaRVaRCheckResult {
+    portfolioId: string
+    breached: boolean
+    breachType?: 'VAR_BREACH' | 'CVAR_BREACH'
+    measuredValue?: number
+    threshold?: number
+    paused: boolean
+    riskMetrics: ReturnType<RiskManagementService['analyzePortfolioRisk']>
+}
+
 type ReturnPoint = { value: number, timestamp: number }
 type PricePoint = { price: number, timestamp: number }
 
@@ -68,7 +90,16 @@ export class RiskManagementService {
     private readonly CIRCUIT_BREAKER_THRESHOLD = 0.20
     private readonly CIRCUIT_BREAKER_COOLDOWN = 300000 // 5 minutes
 
-    constructor() {
+    /** Configurable CVaR/VaR auto-pause thresholds (fall back to class defaults when not set). */
+    private readonly autoPauseVar95Threshold: number
+    private readonly autoPauseCvar95Threshold: number
+    private readonly autoPauseDurationMs: number
+
+    constructor(autoPauseThresholds: AutoPauseThresholds = {}) {
+        this.autoPauseVar95Threshold = autoPauseThresholds.var95 ?? this.VAR95_BLOCK_THRESHOLD
+        this.autoPauseCvar95Threshold = autoPauseThresholds.cvar95 ?? this.CVAR95_BLOCK_THRESHOLD
+        this.autoPauseDurationMs = autoPauseThresholds.pauseDurationMs ?? 24 * 60 * 60 * 1000 // 24 h
+
         const symbols = assetRegistryService.getSymbols(true)
         const assets = symbols.length > 0 ? symbols : ['XLM', 'BTC', 'ETH', 'USDC']
         assets.forEach(asset => {
@@ -334,6 +365,137 @@ export class RiskManagementService {
         }
     }
 
+    /**
+     * Evaluates CVaR(95) and VaR(95) against the configured auto-pause thresholds.
+     *
+     * When either metric exceeds its threshold:
+     *  - Marks the portfolio as paused until `now + autoPauseDurationMs` by setting
+     *    `riskPausedUntil` on the portfolio record.
+     *  - Sends a `riskChange` notification to `userId` explaining the auto-pause.
+     *
+     * When neither metric is breached the portfolio is left unchanged and no
+     * notification is sent.
+     *
+     * @param portfolioId  The portfolio to evaluate and potentially pause.
+     * @param allocations  Current target allocations (weights or percentages).
+     * @param prices       Latest price data used for risk calculation.
+     * @param userId       Stellar address of the portfolio owner – used for notifications.
+     * @returns            A `CVaRVaRCheckResult` describing the outcome.
+     */
+    async checkCVaRVaRThresholdsAndAutoPause(
+        portfolioId: string,
+        allocations: Record<string, number>,
+        prices: PricesMap,
+        userId: string
+    ): Promise<CVaRVaRCheckResult> {
+        const riskMetrics = this.analyzePortfolioRisk(allocations, prices)
+
+        // Only run the threshold check once we have enough data for reliable stats
+        if (riskMetrics.sampleSize < this.MIN_RETURNS_FOR_STATS) {
+            logger.debug('[RISK] Skipping CVaR/VaR auto-pause check – insufficient sample size', {
+                portfolioId,
+                sampleSize: riskMetrics.sampleSize,
+                minRequired: this.MIN_RETURNS_FOR_STATS
+            })
+            return { portfolioId, breached: false, paused: false, riskMetrics }
+        }
+
+        // Determine which metric (if any) is breached – VaR is checked first
+        let breachType: 'VAR_BREACH' | 'CVAR_BREACH' | undefined
+        let measuredValue: number | undefined
+        let threshold: number | undefined
+
+        if (riskMetrics.var95 > this.autoPauseVar95Threshold) {
+            breachType = 'VAR_BREACH'
+            measuredValue = riskMetrics.var95
+            threshold = this.autoPauseVar95Threshold
+        } else if (riskMetrics.cvar95 > this.autoPauseCvar95Threshold) {
+            breachType = 'CVAR_BREACH'
+            measuredValue = riskMetrics.cvar95
+            threshold = this.autoPauseCvar95Threshold
+        }
+
+        if (!breachType) {
+            // All clear – no action needed
+            return { portfolioId, breached: false, paused: false, riskMetrics }
+        }
+
+        // ── Breach detected ──────────────────────────────────────────────────────
+        const pausedUntil = new Date(Date.now() + this.autoPauseDurationMs).toISOString()
+
+        logger.warn('[RISK] CVaR/VaR threshold breached – auto-pausing portfolio', {
+            portfolioId,
+            breachType,
+            measuredValue,
+            threshold,
+            pausedUntil
+        })
+
+        // 1. Persist the pause flag on the portfolio
+        try {
+            const portfolio = await portfolioStorage.getPortfolio(portfolioId)
+            if (portfolio) {
+                await portfolioStorage.updatePortfolio(portfolioId, { riskPausedUntil: pausedUntil })
+            } else {
+                logger.warn('[RISK] Portfolio not found for auto-pause', { portfolioId })
+            }
+        } catch (err) {
+            logger.error('[RISK] Failed to persist auto-pause on portfolio', {
+                portfolioId,
+                error: err instanceof Error ? err.message : String(err)
+            })
+        }
+
+        // 2. Send a notification explaining the pause
+        try {
+            const metricLabel = breachType === 'VAR_BREACH' ? 'VaR(95)' : 'CVaR(95)'
+            const measuredPct = `${(measuredValue! * 100).toFixed(2)}%`
+            const thresholdPct = `${(threshold! * 100).toFixed(2)}%`
+
+            const payload = buildNotificationPayload(userId, {
+                eventType: 'riskChange',
+                data: {
+                    portfolioId,
+                    oldLevel: riskMetrics.overallRiskLevel,
+                    newLevel: 'critical',
+                    autoPause: {
+                        reason: breachType,
+                        measuredValue: measuredPct,
+                        threshold: thresholdPct,
+                        pausedUntil
+                    }
+                }
+            })
+
+            await notificationService.notify(payload)
+
+            logger.info('[RISK] Auto-pause notification sent', {
+                portfolioId,
+                userId,
+                metricLabel,
+                measuredValue: measuredPct,
+                threshold: thresholdPct
+            })
+        } catch (err) {
+            // Notification failure must never prevent the pause from being recorded
+            logger.error('[RISK] Failed to send auto-pause notification', {
+                portfolioId,
+                userId,
+                error: err instanceof Error ? err.message : String(err)
+            })
+        }
+
+        return {
+            portfolioId,
+            breached: true,
+            breachType,
+            measuredValue,
+            threshold,
+            paused: true,
+            riskMetrics
+        }
+    }
+
     getCircuitBreakerStatus(): Record<string, CircuitBreakerStatus> {
         const status: Record<string, CircuitBreakerStatus> = {}