@autonomaai/api-schemas 1.0.0

package/src/validators.ts

@@ -0,0 +1,723 @@
+/**
+ * Schema validation utilities for autonoma API schemas.
+ * 
+ * Provides runtime validation for API requests and responses using JSON Schema.
+ */
+
+import Ajv, { JSONSchemaType, ValidateFunction } from 'ajv';
+import addFormats from 'ajv-formats';
+
+// Initialize AJV with formats
+const ajv = new Ajv({ allErrors: true, verbose: true });
+addFormats(ajv);
+
+// =============================================================================
+// Schema Validation Results
+// =============================================================================
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  data?: any;
+}
+
+export interface ValidationError {
+  field: string;
+  message: string;
+  value?: any;
+  code: string;
+}
+
+// =============================================================================
+// Common Response Schemas
+// =============================================================================
+
+const successResponseSchema: JSONSchemaType<{
+  success: boolean;
+  message: string;
+  timestamp: string;
+  data?: any;
+}> = {
+  type: 'object',
+  properties: {
+    success: { type: 'boolean' },
+    message: { type: 'string' },
+    timestamp: { type: 'string', format: 'date-time' },
+    data: { type: 'object', nullable: true }
+  },
+  required: ['success', 'message', 'timestamp'],
+  additionalProperties: false
+};
+
+const errorResponseSchema: JSONSchemaType<{
+  success: boolean;
+  error: string;
+  detail?: string;
+  error_code?: string;
+  timestamp: string;
+}> = {
+  type: 'object',
+  properties: {
+    success: { type: 'boolean' },
+    error: { type: 'string' },
+    detail: { type: 'string', nullable: true },
+    error_code: { type: 'string', nullable: true },
+    timestamp: { type: 'string', format: 'date-time' }
+  },
+  required: ['success', 'error', 'timestamp'],
+  additionalProperties: false
+};
+
+// =============================================================================
+// Controller Schemas
+// =============================================================================
+
+const createControllerRequestSchema: JSONSchemaType<{
+  name: string;
+  strategy: string;
+  trading_pair: string;
+  config: Record<string, any>;
+  metadata?: Record<string, any>;
+}> = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', minLength: 1, maxLength: 100 },
+    strategy: { 
+      type: 'string',
+      enum: ['pure_market_making', 'avellaneda_market_making', 'twap', 'grid_trading', 'arbitrage']
+    },
+    trading_pair: { type: 'string', pattern: '^[A-Z0-9]+-[A-Z0-9]+$' },
+    config: { type: 'object' },
+    metadata: { type: 'object', nullable: true }
+  },
+  required: ['name', 'strategy', 'trading_pair', 'config'],
+  additionalProperties: false
+};
+
+const controllerSchema: JSONSchemaType<{
+  id: string;
+  name: string;
+  strategy: string;
+  trading_pair: string;
+  status: string;
+  config: Record<string, any>;
+  metadata?: Record<string, any>;
+  created_at: string;
+  updated_at: string;
+}> = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', pattern: '^[a-zA-Z0-9_-]+$' },
+    name: { type: 'string' },
+    strategy: { type: 'string' },
+    trading_pair: { type: 'string' },
+    status: {
+      type: 'string',
+      enum: ['active', 'inactive', 'error', 'starting', 'stopping']
+    },
+    config: { type: 'object' },
+    metadata: { type: 'object', nullable: true },
+    created_at: { type: 'string', format: 'date-time' },
+    updated_at: { type: 'string', format: 'date-time' }
+  },
+  required: ['id', 'name', 'strategy', 'trading_pair', 'status', 'config', 'created_at', 'updated_at'],
+  additionalProperties: false
+};
+
+// =============================================================================
+// Trading Signal Schemas (Unified)
+// =============================================================================
+
+const tradingSignalSchema: JSONSchemaType<{
+  type: string;
+  side: string;
+  amount: number;
+  price?: number;
+  order_type: string;
+  time_in_force?: string;
+  metadata?: Record<string, any>;
+}> = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      enum: ['place_order', 'cancel_order', 'modify_order', 'close_position']
+    },
+    side: {
+      type: 'string',
+      enum: ['buy', 'sell']
+    },
+    amount: { type: 'number', minimum: 0, exclusiveMinimum: 0 },
+    price: { type: 'number', minimum: 0, exclusiveMinimum: 0, nullable: true },
+    order_type: {
+      type: 'string',
+      enum: ['market', 'limit', 'stop_loss', 'take_profit']
+    },
+    time_in_force: {
+      type: 'string',
+      enum: ['GTC', 'IOC', 'FOK'],
+      nullable: true
+    },
+    metadata: { type: 'object', nullable: true }
+  },
+  required: ['type', 'side', 'amount', 'order_type'],
+  additionalProperties: false
+};
+
+const executeSignalRequestSchema: JSONSchemaType<{
+  controller_id: string;
+  signal: {
+    type: string;
+    side: string;
+    amount: number;
+    price?: number;
+    order_type: string;
+    time_in_force?: string;
+    metadata?: Record<string, any>;
+  };
+  execution_options?: {
+    dry_run?: boolean;
+    timeout_seconds?: number;
+  };
+}> = {
+  type: 'object',
+  properties: {
+    controller_id: { type: 'string', pattern: '^[a-zA-Z0-9_-]+$' },
+    signal: tradingSignalSchema,
+    execution_options: {
+      type: 'object',
+      properties: {
+        dry_run: { type: 'boolean', nullable: true },
+        timeout_seconds: { type: 'integer', minimum: 1, maximum: 300, nullable: true }
+      },
+      required: [],
+      additionalProperties: false,
+      nullable: true
+    }
+  },
+  required: ['controller_id', 'signal'],
+  additionalProperties: false
+};
+
+// =============================================================================
+// DeFi Yield Optimization Schemas
+// =============================================================================
+
+const yieldOpportunitySchema: JSONSchemaType<{
+  protocol: string;
+  pool: string;
+  apy: number;
+  tvl: number;
+  risk_score: number;
+  chain: string;
+  asset: string;
+  lockup_period?: number;
+  minimum_deposit?: number;
+  confidence_score: number;
+  last_updated: string;
+}> = {
+  type: 'object',
+  properties: {
+    protocol: { type: 'string', minLength: 1 },
+    pool: { type: 'string', minLength: 1 },
+    apy: { type: 'number', minimum: 0, maximum: 10000 }, // Max 10,000% APY for safety
+    tvl: { type: 'number', minimum: 0 },
+    risk_score: { type: 'number', minimum: 0, maximum: 100 },
+    chain: { 
+      type: 'string',
+      enum: ['ethereum', 'arbitrum', 'polygon', 'base', 'optimism', 'bsc', 'avalanche']
+    },
+    asset: { type: 'string', minLength: 1 },
+    lockup_period: { type: 'number', minimum: 0, nullable: true },
+    minimum_deposit: { type: 'number', minimum: 0, nullable: true },
+    confidence_score: { type: 'number', minimum: 0, maximum: 100 },
+    last_updated: { type: 'string', format: 'date-time' }
+  },
+  required: ['protocol', 'pool', 'apy', 'tvl', 'risk_score', 'chain', 'asset', 'confidence_score', 'last_updated'],
+  additionalProperties: false
+};
+
+const yieldSearchRequestSchema: JSONSchemaType<{
+  search_criteria: {
+    asset?: string;
+    chain?: string[];
+    min_apy?: number;
+    max_risk?: number;
+    min_tvl?: number;
+    protocols?: string[];
+    limit?: number;
+  };
+  risk_tolerance: 'conservative' | 'moderate' | 'aggressive';
+  time_horizon: 'short' | 'medium' | 'long';
+}> = {
+  type: 'object',
+  properties: {
+    search_criteria: {
+      type: 'object',
+      properties: {
+        asset: { type: 'string', nullable: true },
+        chain: { 
+          type: 'array', 
+          items: { type: 'string' },
+          nullable: true 
+        },
+        min_apy: { type: 'number', minimum: 0, nullable: true },
+        max_risk: { type: 'number', minimum: 0, maximum: 100, nullable: true },
+        min_tvl: { type: 'number', minimum: 0, nullable: true },
+        protocols: {
+          type: 'array',
+          items: { type: 'string' },
+          nullable: true
+        },
+        limit: { type: 'integer', minimum: 1, maximum: 100, nullable: true }
+      },
+      required: [],
+      additionalProperties: false
+    },
+    risk_tolerance: {
+      type: 'string',
+      enum: ['conservative', 'moderate', 'aggressive']
+    },
+    time_horizon: {
+      type: 'string',
+      enum: ['short', 'medium', 'long']
+    }
+  },
+  required: ['search_criteria', 'risk_tolerance', 'time_horizon'],
+  additionalProperties: false
+};
+
+const allocationOptimizationSchema: JSONSchemaType<{
+  strategy: 'max_sharpe' | 'risk_parity' | 'mean_variance';
+  allocations: Record<string, number>;
+  expected_return: number;
+  expected_risk: number;
+  sharpe_ratio: number;
+  constraints: {
+    max_protocol_allocation: number;
+    max_single_asset: number;
+    min_liquidity: number;
+    max_risk_score: number;
+    required_chains?: string[];
+  };
+  rebalancing_threshold: number;
+}> = {
+  type: 'object',
+  properties: {
+    strategy: {
+      type: 'string',
+      enum: ['max_sharpe', 'risk_parity', 'mean_variance']
+    },
+    allocations: {
+      type: 'object',
+      additionalProperties: { type: 'number', minimum: 0, maximum: 1 },
+      required: []
+    },
+    expected_return: { type: 'number' },
+    expected_risk: { type: 'number', minimum: 0 },
+    sharpe_ratio: { type: 'number' },
+    constraints: {
+      type: 'object',
+      properties: {
+        max_protocol_allocation: { type: 'number', minimum: 0, maximum: 1 },
+        max_single_asset: { type: 'number', minimum: 0, maximum: 1 },
+        min_liquidity: { type: 'number', minimum: 0 },
+        max_risk_score: { type: 'number', minimum: 0, maximum: 100 },
+        required_chains: {
+          type: 'array',
+          items: { type: 'string' },
+          nullable: true
+        }
+      },
+      required: ['max_protocol_allocation', 'max_single_asset', 'min_liquidity', 'max_risk_score'],
+      additionalProperties: false
+    },
+    rebalancing_threshold: { type: 'number', minimum: 0, maximum: 1 }
+  },
+  required: ['strategy', 'allocations', 'expected_return', 'expected_risk', 'sharpe_ratio', 'constraints', 'rebalancing_threshold'],
+  additionalProperties: false
+};
+
+const defiSignalSchema: JSONSchemaType<{
+  type: string;
+  protocol: string;
+  action: 'deposit' | 'withdraw' | 'compound' | 'rebalance';
+  amount: number;
+  asset: string;
+  target_apy?: number;
+  max_slippage?: number;
+  metadata?: Record<string, any>;
+}> = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      enum: ['defi_yield_action']
+    },
+    protocol: { type: 'string', minLength: 1 },
+    action: {
+      type: 'string',
+      enum: ['deposit', 'withdraw', 'compound', 'rebalance']
+    },
+    amount: { type: 'number', minimum: 0, exclusiveMinimum: 0 },
+    asset: { type: 'string', minLength: 1 },
+    target_apy: { type: 'number', minimum: 0, nullable: true },
+    max_slippage: { type: 'number', minimum: 0, maximum: 1, nullable: true },
+    metadata: { type: 'object', nullable: true }
+  },
+  required: ['type', 'protocol', 'action', 'amount', 'asset'],
+  additionalProperties: false
+};
+
+const portfolioRiskAssessmentSchema: JSONSchemaType<{
+  var_95: number;
+  var_99: number;
+  expected_shortfall: number;
+  portfolio_volatility: number;
+  correlation_risk: number;
+  concentration_risk: number;
+  liquidity_risk: number;
+  overall_risk_score: number;
+  recommendations: string[];
+}> = {
+  type: 'object',
+  properties: {
+    var_95: { type: 'number' },
+    var_99: { type: 'number' },
+    expected_shortfall: { type: 'number' },
+    portfolio_volatility: { type: 'number', minimum: 0 },
+    correlation_risk: { type: 'number', minimum: 0, maximum: 100 },
+    concentration_risk: { type: 'number', minimum: 0, maximum: 100 },
+    liquidity_risk: { type: 'number', minimum: 0, maximum: 100 },
+    overall_risk_score: { type: 'number', minimum: 0, maximum: 100 },
+    recommendations: {
+      type: 'array',
+      items: { type: 'string' }
+    }
+  },
+  required: ['var_95', 'var_99', 'expected_shortfall', 'portfolio_volatility', 'correlation_risk', 'concentration_risk', 'liquidity_risk', 'overall_risk_score', 'recommendations'],
+  additionalProperties: false
+};
+
+// =============================================================================
+// Updated Compiled Validators
+// =============================================================================
+
+const validators = {
+  // Existing validators
+  successResponse: ajv.compile(successResponseSchema),
+  errorResponse: ajv.compile(errorResponseSchema),
+  createControllerRequest: ajv.compile(createControllerRequestSchema),
+  controller: ajv.compile(controllerSchema),
+  tradingSignal: ajv.compile(tradingSignalSchema),
+  executeSignalRequest: ajv.compile(executeSignalRequestSchema),
+  
+  // New DeFi validators
+  yieldOpportunity: ajv.compile(yieldOpportunitySchema),
+  yieldSearchRequest: ajv.compile(yieldSearchRequestSchema),
+  allocationOptimization: ajv.compile(allocationOptimizationSchema),
+  defiSignal: ajv.compile(defiSignalSchema),
+  portfolioRiskAssessment: ajv.compile(portfolioRiskAssessmentSchema)
+};
+
+// =============================================================================
+// Validation Functions
+// =============================================================================
+
+function formatValidationErrors(validator: ValidateFunction): ValidationError[] {
+  if (!validator.errors) return [];
+  
+  return validator.errors.map((error: any) => ({
+    field: error.instancePath || error.schemaPath,
+    message: error.message || 'Validation error',
+    value: error.data,
+    code: error.keyword || 'VALIDATION_ERROR'
+  }));
+}
+
+/**
+ * Validate a success response
+ */
+export function validateSuccessResponse(data: any): ValidationResult {
+  const valid = validators.successResponse(data);
+  return {
+    valid,
+    errors: valid ? [] : formatValidationErrors(validators.successResponse),
+    data: valid ? data : null
+  };
+}
+
+/**
+ * Validate an error response
+ */
+export function validateErrorResponse(data: any): ValidationResult {
+  const valid = validators.errorResponse(data);
+  return {
+    valid,
+    errors: valid ? [] : formatValidationErrors(validators.errorResponse),
+    data: valid ? data : null
+  };
+}
+
+/**
+ * Validate create controller request
+ */
+export function validateCreateControllerRequest(data: any): ValidationResult {
+  const valid = validators.createControllerRequest(data);
+  return {
+    valid,
+    errors: valid ? [] : formatValidationErrors(validators.createControllerRequest),
+    data: valid ? data : null
+  };
+}
+
+/**
+ * Validate controller object
+ */
+export function validateController(data: any): ValidationResult {
+  const valid = validators.controller(data);
+  return {
+    valid,
+    errors: valid ? [] : formatValidationErrors(validators.controller),
+    data: valid ? data : null
+  };
+}
+
+/**
+ * Validate trading signal
+ */
+export function validateTradingSignal(data: any): ValidationResult {
+  const valid = validators.tradingSignal(data);
+  return {
+    valid,
+    errors: valid ? [] : formatValidationErrors(validators.tradingSignal),
+    data: valid ? data : null
+  };
+}
+
+/**
+ * Validate execute signal request (UNIFIED)
+ */
+export function validateExecuteSignalRequest(data: any): ValidationResult {
+  const valid = validators.executeSignalRequest(data);
+  return {
+    valid,
+    errors: valid ? [] : formatValidationErrors(validators.executeSignalRequest),
+    data: valid ? data : null
+  };
+}
+
+// =============================================================================
+// DeFi Yield Validation Functions
+// =============================================================================
+
+export function validateYieldOpportunity(data: any): ValidationResult {
+  const isValid = validators.yieldOpportunity(data);
+  return {
+    valid: isValid,
+    errors: isValid ? [] : formatValidationErrors(validators.yieldOpportunity),
+    data: isValid ? data : null
+  };
+}
+
+export function validateYieldSearchRequest(data: any): ValidationResult {
+  const isValid = validators.yieldSearchRequest(data);
+  return {
+    valid: isValid,
+    errors: isValid ? [] : formatValidationErrors(validators.yieldSearchRequest),
+    data: isValid ? data : null
+  };
+}
+
+export function validateAllocationOptimization(data: any): ValidationResult {
+  const isValid = validators.allocationOptimization(data);
+  return {
+    valid: isValid,
+    errors: isValid ? [] : formatValidationErrors(validators.allocationOptimization),
+    data: isValid ? data : null
+  };
+}
+
+export function validateDeFiSignal(data: any): ValidationResult {
+  const isValid = validators.defiSignal(data);
+  return {
+    valid: isValid,
+    errors: isValid ? [] : formatValidationErrors(validators.defiSignal),
+    data: isValid ? data : null
+  };
+}
+
+export function validatePortfolioRiskAssessment(data: any): ValidationResult {
+  const isValid = validators.portfolioRiskAssessment(data);
+  return {
+    valid: isValid,
+    errors: isValid ? [] : formatValidationErrors(validators.portfolioRiskAssessment),
+    data: isValid ? data : null
+  };
+}
+
+// =============================================================================
+// DeFi Response Helpers
+// =============================================================================
+
+export function createYieldOpportunityResponse(
+  opportunities: any[],
+  metadata?: any
+): any {
+  return validateSuccessResponse({
+    success: true,
+    message: 'Yield opportunities found successfully',
+    timestamp: new Date().toISOString(),
+    data: {
+      opportunities,
+      count: opportunities.length,
+      metadata: {
+        search_timestamp: new Date().toISOString(),
+        ...metadata
+      }
+    }
+  });
+}
+
+export function createAllocationOptimizationResponse(
+  optimization: any,
+  metadata?: any
+): any {
+  return validateSuccessResponse({
+    success: true,
+    message: 'Portfolio optimization completed successfully',
+    timestamp: new Date().toISOString(),
+    data: {
+      optimization,
+      metadata: {
+        optimization_timestamp: new Date().toISOString(),
+        ...metadata
+      }
+    }
+  });
+}
+
+export function createDeFiSignalResponse(
+  execution_result: any,
+  metadata?: any
+): any {
+  return validateSuccessResponse({
+    success: true,
+    message: 'DeFi signal executed successfully',
+    timestamp: new Date().toISOString(),
+    data: {
+      execution_result,
+      metadata: {
+        execution_timestamp: new Date().toISOString(),
+        ...metadata
+      }
+    }
+  });
+}
+
+// =============================================================================
+// Validation Middleware Helpers
+// =============================================================================
+
+/**
+ * Express middleware factory for request validation
+ */
+export function createValidationMiddleware(validator: (data: any) => ValidationResult) {
+  return (req: any, res: any, next: any) => {
+    const result = validator(req.body);
+    
+    if (!result.valid) {
+      return res.status(400).json({
+        success: false,
+        error: 'Validation failed',
+        detail: 'Request body does not match required schema',
+        validation_errors: result.errors,
+        timestamp: new Date().toISOString()
+      });
+    }
+    
+    next();
+  };
+}
+
+/**
+ * FastAPI dependency for request validation (Python equivalent helper)
+ */
+export function generatePythonValidator(schemaName: string): string {
+  return `
+def validate_${schemaName}(data: dict) -> ValidationResult:
+    """
+    Validate ${schemaName} data against unified schema.
+    
+    This should be replaced with actual Python Pydantic validation
+    based on the OpenAPI specification.
+    """
+    # TODO: Implement with Pydantic models generated from OpenAPI spec
+    return {"valid": True, "errors": []}
+`;
+}
+
+// =============================================================================
+// Schema Migration Helpers
+// =============================================================================
+
+/**
+ * Convert legacy execute signal format to unified format
+ */
+export function migrateLegacyExecuteSignal(legacyData: any): any {
+  // Handle old format: { signal_type, parameters }
+  if (legacyData.signal_type && legacyData.parameters) {
+    return {
+      controller_id: legacyData.controller_id,
+      signal: {
+        type: legacyData.signal_type,
+        ...legacyData.parameters
+      }
+    };
+  }
+  
+  // Handle old format with different signal structure
+  if (legacyData.signal && typeof legacyData.signal === 'object') {
+    const signal = legacyData.signal;
+    
+    // Ensure required fields are present and normalized
+    return {
+      controller_id: legacyData.controller_id,
+      signal: {
+        type: signal.type || 'place_order',
+        side: signal.side,
+        amount: signal.amount,
+        price: signal.price,
+        order_type: signal.order_type || 'limit',
+        time_in_force: signal.time_in_force || 'GTC',
+        metadata: signal.metadata
+      }
+    };
+  }
+  
+  // Already in correct format
+  return legacyData;
+}
+
+/**
+ * Convert unified format to legacy format for backward compatibility
+ */
+export function convertToLegacyFormat(unifiedData: any, format: 'signal_type' | 'nested'): any {
+  if (format === 'signal_type') {
+    return {
+      controller_id: unifiedData.controller_id,
+      signal_type: unifiedData.signal.type,
+      parameters: {
+        side: unifiedData.signal.side,
+        amount: unifiedData.signal.amount,
+        price: unifiedData.signal.price,
+        order_type: unifiedData.signal.order_type,
+        time_in_force: unifiedData.signal.time_in_force,
+        ...unifiedData.signal.metadata
+      }
+    };
+  }
+  
+  // Default: nested format (current unified format)
+  return unifiedData;
+}