@lagoon-protocol/lagoon-mcp 0.1.0

package/dist/utils/risk-scoring.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Risk Scoring Utility
+ *
+ * Multi-factor risk analysis algorithms for vault assessment.
+ * Provides comprehensive risk scoring across multiple dimensions.
+ */
+/**
+ * Risk score breakdown by category
+ */
+export interface RiskScoreBreakdown {
+    tvlRisk: number;
+    concentrationRisk: number;
+    volatilityRisk: number;
+    ageRisk: number;
+    curatorRisk: number;
+    feeRisk: number;
+    liquidityRisk: number;
+    aprConsistencyRisk: number;
+    yieldSustainabilityRisk: number;
+    settlementRisk: number;
+    integrationComplexityRisk: number;
+    capacityUtilizationRisk: number;
+    overallRisk: number;
+    riskLevel: 'Low' | 'Medium' | 'High' | 'Critical';
+}
+/**
+ * Risk thresholds for scoring
+ */
+export declare const RISK_THRESHOLDS: {
+    TVL_VERY_HIGH: number;
+    TVL_HIGH: number;
+    TVL_MEDIUM: number;
+    TVL_LOW: number;
+    CONCENTRATION_LOW: number;
+    CONCENTRATION_MEDIUM: number;
+    CONCENTRATION_HIGH: number;
+    VOLATILITY_LOW: number;
+    VOLATILITY_MEDIUM: number;
+    VOLATILITY_HIGH: number;
+    AGE_MATURE: number;
+    AGE_ESTABLISHED: number;
+    AGE_NEW: number;
+    OVERALL_LOW: number;
+    OVERALL_MEDIUM: number;
+    OVERALL_HIGH: number;
+};
+/**
+ * Calculate TVL-based risk score
+ * Higher TVL = lower risk (more liquidity and market validation)
+ *
+ * @param tvl - Total value locked in USD
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateTVLRisk(tvl: number): number;
+/**
+ * Calculate concentration risk score
+ * Measures vault's share of total protocol TVL
+ *
+ * @param vaultTVL - Vault's TVL in USD
+ * @param totalProtocolTVL - Total protocol TVL in USD
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateConcentrationRisk(vaultTVL: number, totalProtocolTVL: number): number;
+/**
+ * Calculate volatility risk score
+ * Based on price volatility over time
+ *
+ * @param pricePoints - Array of price per share values over time
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateVolatilityRisk(pricePoints: number[]): number;
+/**
+ * Calculate age-based risk score
+ * Newer vaults are riskier (less battle-tested)
+ *
+ * @param ageInDays - Vault age in days
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateAgeRisk(ageInDays: number): number;
+/**
+ * Calculate curator reputation risk score
+ * Based on curator's track record, professional signals, and vault management
+ *
+ * @param curatorVaultCount - Number of vaults managed by curator
+ * @param curatorSuccessRate - Success rate (0-1) of curator's vaults
+ * @param professionalSignals - Professional indicators: website, description, multiple curators
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateCuratorRisk(curatorVaultCount: number, curatorSuccessRate?: number, professionalSignals?: {
+    hasWebsite: boolean;
+    hasDescription: boolean;
+    multipleCurators: boolean;
+    curatorCount: number;
+}): number;
+/**
+ * Calculate fee risk score
+ * Based on management fees and performance fee impact
+ *
+ * @param managementFee - Annual management fee percentage (e.g., 2 for 2%)
+ * @param performanceFee - Performance fee percentage (e.g., 20 for 20%)
+ * @param performanceFeeActive - Whether performance fee is currently active (above HWM)
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateFeeRisk(managementFee: number, performanceFee: number, performanceFeeActive: boolean): number;
+/**
+ * Calculate liquidity risk score
+ * Based on safe assets vs pending redemptions coverage
+ *
+ * @param safeAssets - Assets available for immediate redemptions (USD)
+ * @param pendingRedemptions - Outstanding redemption requests (USD)
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateLiquidityRisk(safeAssets: number, pendingRedemptions: number): number;
+/**
+ * Calculate APR consistency risk score
+ * Analyzes volatility of returns across different time periods
+ *
+ * @param aprData - APR values across different time periods
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateAPRConsistencyRisk(aprData: {
+    weeklyApr?: number;
+    monthlyApr?: number;
+    yearlyApr?: number;
+    inceptionApr?: number;
+}): number;
+/**
+ * Calculate yield sustainability risk score
+ * Assesses composition of APR sources (native vs temporary incentives)
+ *
+ * @param yieldComposition - Breakdown of yield sources
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateYieldSustainabilityRisk(yieldComposition: {
+    totalApr: number;
+    nativeYieldsApr: number;
+    airdropsApr: number;
+    incentivesApr: number;
+}): number;
+/**
+ * Calculate settlement time risk score
+ * Quantifies redemption delay and operational efficiency
+ *
+ * @param settlementData - Settlement time and pending operations data
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateSettlementRisk(settlementData: {
+    averageSettlementDays: number;
+    pendingOperationsRatio: number;
+}): number;
+/**
+ * Calculate integration complexity risk score
+ * Assesses smart contract attack surface based on number of integrations
+ *
+ * @param integrationCount - Number of DeFi protocol integrations
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateIntegrationComplexityRisk(integrationCount: number): number;
+/**
+ * Calculate capacity utilization risk score
+ * Assesses deposit headroom and demand signals
+ *
+ * @param utilizationData - Capacity and utilization data
+ * @returns Risk score 0-1 (0 = lowest risk, 1 = highest risk)
+ */
+export declare function calculateCapacityUtilizationRisk(utilizationData: {
+    totalAssets: number;
+    maxCapacity: number | null;
+}): number;
+/**
+ * Calculate overall risk score with weighted factors
+ *
+ * @param breakdown - Individual risk factor scores
+ * @returns Overall risk score 0-1 and risk level
+ */
+export declare function calculateOverallRisk(breakdown: Omit<RiskScoreBreakdown, 'overallRisk' | 'riskLevel'>): {
+    overallRisk: number;
+    riskLevel: 'Low' | 'Medium' | 'High' | 'Critical';
+};
+/**
+ * Generate comprehensive risk analysis
+ *
+ * @param params - Risk analysis parameters
+ * @returns Complete risk score breakdown
+ */
+export declare function analyzeRisk(params: {
+    tvl: number;
+    totalProtocolTVL: number;
+    priceHistory: number[];
+    ageInDays: number;
+    curatorVaultCount: number;
+    curatorSuccessRate?: number;
+    curatorProfessionalSignals?: {
+        hasWebsite: boolean;
+        hasDescription: boolean;
+        multipleCurators: boolean;
+        curatorCount: number;
+    };
+    managementFee: number;
+    performanceFee: number;
+    performanceFeeActive: boolean;
+    safeAssets: number;
+    pendingRedemptions: number;
+    aprData?: {
+        weeklyApr?: number;
+        monthlyApr?: number;
+        yearlyApr?: number;
+        inceptionApr?: number;
+    };
+    yieldComposition?: {
+        totalApr: number;
+        nativeYieldsApr: number;
+        airdropsApr: number;
+        incentivesApr: number;
+    };
+    settlementData?: {
+        averageSettlementDays: number;
+        pendingOperationsRatio: number;
+    };
+    integrationCount?: number;
+    capacityData?: {
+        totalAssets: number;
+        maxCapacity: number | null;
+    };
+}): RiskScoreBreakdown;
+//# sourceMappingURL=risk-scoring.d.ts.map

package/dist/utils/risk-scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-scoring.d.ts","sourceRoot":"","sources":["../../src/utils/risk-scoring.ts"],"names":[],"mappings":"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"}