skayn-trading-sdk/src/interfaces/IRiskManager.js

Professional Bitcoin trading strategy backtesting framework with institutional-grade architecture

/**
 * Risk Manager Interface
 * Defines contract for risk management systems
 */
class IRiskManager {
  /**
   * Initialize the risk manager
   * @param {Object} config - Risk management configuration
   */
  async initialize(config = {}) {
    throw new Error('IRiskManager.initialize() must be implemented');
  }

  /**
   * Evaluate if a trade should be executed based on risk parameters
   * @param {Object} signal - Trading signal from strategy
   * @param {Object} portfolioState - Current portfolio state
   * @param {Object} marketData - Current market data
   * @returns {Promise<Object>} Risk evaluation result
   */
  async evaluateRisk(signal, portfolioState, marketData) {
    throw new Error('IRiskManager.evaluateRisk() must be implemented');
  }

  /**
   * Calculate position size based on risk parameters
   * @param {Object} signal - Trading signal
   * @param {Object} portfolioState - Current portfolio state
   * @param {Object} marketData - Current market data
   * @returns {Promise<Object>} Position sizing result
   */
  async calculatePositionSize(signal, portfolioState, marketData) {
    throw new Error('IRiskManager.calculatePositionSize() must be implemented');
  }

  /**
   * Set stop loss and take profit levels
   * @param {Object} position - Position details
   * @param {Object} marketData - Current market data
   * @returns {Promise<Object>} Stop loss and take profit levels
   */
  async setStopLossAndTakeProfit(position, marketData) {
    throw new Error('IRiskManager.setStopLossAndTakeProfit() must be implemented');
  }

  /**
   * Check if position should be closed due to risk limits
   * @param {Object} position - Position to evaluate
   * @param {Object} marketData - Current market data
   * @returns {Promise<Object>} Position close recommendation
   */
  async shouldClosePosition(position, marketData) {
    throw new Error('IRiskManager.shouldClosePosition() must be implemented');
  }

  /**
   * Get current portfolio risk metrics
   * @param {Object} portfolioState - Current portfolio state
   * @param {Object} marketData - Current market data
   * @returns {Promise<Object>} Risk metrics
   */
  async getPortfolioRiskMetrics(portfolioState, marketData) {
    throw new Error('IRiskManager.getPortfolioRiskMetrics() must be implemented');
  }

  /**
   * Check if maximum exposure limits are reached
   * @param {Object} portfolioState - Current portfolio state
   * @param {Object} newPosition - Proposed new position
   * @returns {Promise<boolean>} Whether exposure limits allow new position
   */
  async checkExposureLimits(portfolioState, newPosition) {
    throw new Error('IRiskManager.checkExposureLimits() must be implemented');
  }

  /**
   * Get maximum allowed position size for an asset
   * @param {string} symbol - Trading symbol
   * @param {Object} portfolioState - Current portfolio state
   * @returns {Promise<number>} Maximum position size
   */
  async getMaxPositionSize(symbol, portfolioState) {
    throw new Error('IRiskManager.getMaxPositionSize() must be implemented');
  }

  /**
   * Update risk parameters dynamically
   * @param {Object} newParams - New risk parameters
   */
  async updateRiskParameters(newParams) {
    throw new Error('IRiskManager.updateRiskParameters() must be implemented');
  }

  /**
   * Get recent loss count for consecutive loss limits
   * @param {number} lookbackPeriods - Number of recent trades to check
   * @returns {Promise<number>} Number of recent losses
   */
  async getRecentLosses(lookbackPeriods = 5) {
    throw new Error('IRiskManager.getRecentLosses() must be implemented');
  }

  /**
   * Calculate Value at Risk (VaR) for portfolio
   * @param {Object} portfolioState - Current portfolio state
   * @param {number} confidenceLevel - Confidence level (e.g., 0.95 for 95%)
   * @param {number} timeHorizon - Time horizon in days
   * @returns {Promise<number>} VaR value
   */
  async calculateVaR(portfolioState, confidenceLevel = 0.95, timeHorizon = 1) {
    throw new Error('IRiskManager.calculateVaR() must be implemented');
  }

  /**
   * Get drawdown metrics
   * @param {Object} portfolioState - Current portfolio state
   * @returns {Promise<Object>} Drawdown metrics
   */
  async getDrawdownMetrics(portfolioState) {
    throw new Error('IRiskManager.getDrawdownMetrics() must be implemented');
  }

  /**
   * Check correlation limits for new position
   * @param {Object} newPosition - Proposed new position
   * @param {Object} portfolioState - Current portfolio state
   * @returns {Promise<boolean>} Whether correlation limits allow position
   */
  async checkCorrelationLimits(newPosition, portfolioState) {
    throw new Error('IRiskManager.checkCorrelationLimits() must be implemented');
  }

  /**
   * Emergency position sizing for high volatility periods
   * @param {Object} signal - Trading signal
   * @param {Object} marketData - Current market data
   * @returns {Promise<number>} Emergency position size multiplier
   */
  async getEmergencyPositionMultiplier(signal, marketData) {
    // Default implementation - can be overridden
    return marketData.volatility > 0.05 ? 0.5 : 1.0;
  }

  /**
   * Get risk manager metadata
   * @returns {Object} Risk manager information
   */
  getRiskManagerMetadata() {
    return {
      name: 'Unknown Risk Manager',
      version: '1.0.0',
      description: 'Base risk manager interface',
      supportedRiskMethods: [],
      maxDrawdown: 20,
      maxPositionSize: 10
    };
  }

  /**
   * Cleanup resources
   */
  async cleanup() {
    // Optional cleanup - override if needed
  }
}

module.exports = IRiskManager;