payment-kit 1.24.3 → 1.25.0

package/api/src/libs/exchange-rate/token-data-provider.ts

@@ -0,0 +1,142 @@
+import axios from 'axios';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import BigNumber from 'bignumber.js';
+
+import logger from '../logger';
+import { getTokenInfo } from './token-address-mapping';
+import type { ExchangeRateData, IExchangeRateProvider, ProviderConfig } from './types';
+import { SymbolNotSupportedError } from './types';
+
+/**
+ * Token Data Provider (ArcBlock)
+ *
+ * Fetches token prices from token-data.arcblock.io using contract addresses
+ * Uses Ethereum mainnet (chainId: 1) contract addresses
+ */
+export class TokenDataProvider implements IExchangeRateProvider {
+  public readonly name = 'token-data';
+
+  private baseUrl: string;
+  private timeout: number;
+  private zeroAddress = '0x0000000000000000000000000000000000000000';
+
+  constructor(config: ProviderConfig = {}) {
+    this.baseUrl = config.base_url || 'https://token-data.arcblock.io';
+    this.timeout = config.timeout || 10000; // 10 seconds default
+  }
+
+  async fetch(symbol: string): Promise<ExchangeRateData> {
+    try {
+      // Get token address from mapping
+      const tokenInfo = getTokenInfo(symbol);
+      if (!tokenInfo) {
+        // Symbol not in mapping - this is a data issue, not a service issue
+        throw new SymbolNotSupportedError(symbol, this.name);
+      }
+
+      const addressLower = (tokenInfo.address || '').toLowerCase();
+      const useSymbolEndpoint = !addressLower || addressLower === this.zeroAddress || !addressLower.startsWith('0x');
+      const url = useSymbolEndpoint
+        ? `${this.baseUrl}/api/token-price-by-symbol`
+        : `${this.baseUrl}/api/token-price-by-address`;
+
+      logger.debug('Fetching exchange rate from token-data', {
+        symbol,
+        address: tokenInfo.address,
+        endpoint: useSymbolEndpoint ? 'token-price-by-symbol' : 'token-price-by-address',
+      });
+
+      const response = await axios.get(url, {
+        params: useSymbolEndpoint
+          ? {
+              symbols: tokenInfo.symbol,
+            }
+          : {
+              addresses: addressLower,
+            },
+        timeout: this.timeout,
+        headers: {
+          'User-Agent': 'PaymentKit/1.0',
+        },
+      });
+
+      if (!response.data || typeof response.data !== 'object') {
+        logger.error('Invalid response format from token-data', { response: response.data });
+        throw new Error('Invalid response format from token-data');
+      }
+
+      const responseData = response.data;
+
+      // API returns: { data: [...], total, page, size }
+      if (!responseData.data || !Array.isArray(responseData.data) || responseData.data.length === 0) {
+        logger.error('No token data in response', {
+          symbol,
+          address: addressLower,
+          endpoint: useSymbolEndpoint ? 'token-price-by-symbol' : 'token-price-by-address',
+        });
+        throw new Error(`No token data found for ${symbol}`);
+      }
+
+      const tokenData = responseData.data[0];
+
+      // Extract USD price from tokenData.price.USD
+      const usdPrice = tokenData.price?.USD;
+      if (!usdPrice || typeof usdPrice !== 'number') {
+        logger.error('No valid USD price in token data', {
+          symbol,
+          priceObject: tokenData.price,
+        });
+        throw new Error(`No valid USD price found for ${symbol}`);
+      }
+
+      // Validate price is positive
+      const rate = new BigNumber(usdPrice);
+      if (rate.lte(0) || !rate.isFinite()) {
+        throw new Error(`Invalid price value: ${usdPrice}`);
+      }
+
+      // Get timestamp - use updatedAt from token data
+      const timestampMs = tokenData.updatedAt ? new Date(tokenData.updatedAt).getTime() : Date.now();
+
+      return {
+        rate: rate.toString(),
+        timestamp_ms: timestampMs,
+        metadata: {
+          source: 'token-data',
+          address: tokenInfo.address,
+          symbol: tokenData.symbol,
+          name: tokenData.name,
+          percent_change_24h: tokenData.percent_change_24h?.USD,
+        },
+      };
+    } catch (error: any) {
+      // Log the error
+      logger.error('Failed to fetch exchange rate from token-data', {
+        symbol,
+        error: error.message,
+        response: error.response?.data,
+      });
+
+      // Determine error type and throw appropriate error
+      // Re-throw SymbolNotSupportedError as-is (don't wrap it)
+      if (error instanceof SymbolNotSupportedError) {
+        throw error;
+      }
+      if (error.response) {
+        if (error.response.status === 404) {
+          throw new SymbolNotSupportedError(symbol, this.name);
+        } else if (error.response.status >= 500) {
+          throw new Error(`token-data server error: ${error.response.status}`);
+        } else {
+          throw new Error(`token-data request failed: ${error.response.status}`);
+        }
+      } else if (error.code === 'ECONNABORTED') {
+        throw new Error(`token-data request timeout after ${this.timeout}ms`);
+      } else if (error.code === 'ENOTFOUND' || error.code === 'ECONNREFUSED') {
+        throw new Error(`Cannot connect to token-data: ${error.message}`);
+      } else {
+        throw new Error(`token-data fetch error: ${error.message}`);
+      }
+    }
+  }
+}

package/api/src/libs/exchange-rate/types.ts

@@ -0,0 +1,114 @@
+/**
+ * Exchange Rate Provider Interface
+ *
+ * All exchange rate providers must implement this interface.
+ * Rates are expressed as "USD per token" (e.g., 1 ABT = 0.1 USD means rate = 0.1)
+ */
+
+export interface IExchangeRateProvider {
+  readonly name: string;
+
+  /**
+   * Fetch the current exchange rate for a given token symbol
+   * @param symbol - Token symbol (e.g., 'ABT', 'ETH')
+   * @returns Exchange rate data
+   * @throws Error if fetching fails or data is invalid
+   */
+  fetch(symbol: string): Promise<ExchangeRateData>;
+}
+
+export interface ExchangeRateData {
+  /**
+   * Exchange rate in USD per token
+   * Example: 1 ABT = 0.1 USD => rate = "0.1"
+   */
+  rate: string;
+
+  /**
+   * Timestamp of the rate in milliseconds
+   */
+  timestamp_ms: number;
+
+  /**
+   * Optional metadata
+   */
+  metadata?: Record<string, any>;
+}
+
+export interface ExchangeRateResult extends ExchangeRateData {
+  /**
+   * Consensus method used to compute the final rate
+   */
+  consensus_method?: string;
+
+  /**
+   * Provider snapshots participating in consensus
+   */
+  providers?: ExchangeRateProviderSnapshot[];
+
+  /**
+   * Provider ID from database
+   */
+  provider_id: string;
+
+  /**
+   * Provider name
+   */
+  provider_name: string;
+
+  /**
+   * Human-readable provider display string
+   * - Single source: "CoinGecko"
+   * - Multiple sources: "CoinGecko (2 sources)"
+   */
+  provider_display?: string;
+
+  /**
+   * Whether the rate is from a degraded provider
+   */
+  degraded: boolean;
+
+  /**
+   * Reason for degradation (if degraded)
+   */
+  degraded_reason?: string;
+
+  /**
+   * Timestamp when we fetched the data (milliseconds)
+   * Different from timestamp_ms which is the provider's data timestamp
+   */
+  fetched_at?: number;
+}
+
+export interface ExchangeRateProviderSnapshot {
+  provider_id: string;
+  provider_name: string;
+  rate: string;
+  timestamp_ms: number;
+  degraded: boolean;
+  degraded_reason?: string;
+}
+
+export interface ProviderConfig {
+  base_url?: string;
+  api_key?: string;
+  timeout?: number;
+  [key: string]: any;
+}
+
+/**
+ * Error thrown when a symbol is not supported by the provider
+ * This error should NOT be recorded as a provider failure
+ * because it's a data issue, not a service issue
+ */
+export class SymbolNotSupportedError extends Error {
+  public readonly symbol: string;
+  public readonly provider: string;
+
+  constructor(symbol: string, provider: string, message?: string) {
+    super(message || `Symbol ${symbol} is not supported by ${provider}`);
+    this.name = 'SymbolNotSupportedError';
+    this.symbol = symbol;
+    this.provider = provider;
+  }
+}

package/api/src/libs/exchange-rate/validator.ts

@@ -0,0 +1,319 @@
+/**
+ * Exchange Rate Validator
+ *
+ * Implements dual-layer validation for dynamic pricing:
+ * 1. System-level: Rate trustworthiness (multi-source deviation, volatility)
+ * 2. User-level: Slippage protection (preview vs submit price change)
+ *
+ * @see Intent: blocklets/core/ai/intent/20260112-dynamic-price.md
+ */
+
+import type { ExchangeRateResult } from './types';
+import logger from '../logger';
+
+// System-level thresholds (non-bypassable)
+const MULTI_SOURCE_DEVIATION_THRESHOLD = 0.1; // 10%
+const VOLATILITY_30S_THRESHOLD = 0.2; // 20%
+const VOLATILITY_WINDOW_MS = 30 * 1000; // 30 seconds
+
+// Default user-level slippage threshold
+export const DEFAULT_SLIPPAGE_PERCENT = 0.5; // 0.5%
+
+export type RateValidationErrorCode = 'PRICE_UNAVAILABLE' | 'PRICE_UNSTABLE';
+
+export interface RateValidationResult {
+  trustworthy: boolean;
+  error_code?: RateValidationErrorCode;
+  error_message?: string;
+  deviation_percent?: number;
+  volatility_percent?: number;
+}
+
+export interface SlippageValidationResult {
+  passed: boolean;
+  change_percent: number;
+  preview_rate: string;
+  submit_rate: string;
+  slippage_threshold: number;
+}
+
+interface RateHistoryEntry {
+  rate: string;
+  timestamp_ms: number;
+}
+
+// In-memory rate history for volatility calculation
+const rateHistoryMap: Map<string, RateHistoryEntry[]> = new Map();
+const RATE_HISTORY_MAX_SIZE = 100;
+
+/**
+ * Record a trusted rate for volatility tracking
+ * Only rates that pass system-level validation should be recorded
+ */
+export function recordTrustedRate(symbol: string, rate: string, timestampMs: number): void {
+  const key = symbol.toUpperCase();
+  const history = rateHistoryMap.get(key) || [];
+
+  history.push({ rate, timestamp_ms: timestampMs });
+
+  // Keep history bounded
+  while (history.length > RATE_HISTORY_MAX_SIZE) {
+    history.shift();
+  }
+
+  rateHistoryMap.set(key, history);
+}
+
+/**
+ * Get the previous trusted rate within the volatility window
+ * rate_prev: The most recent rate that passed system-level validation
+ */
+function getPreviousTrustedRate(symbol: string, currentTimestampMs: number): RateHistoryEntry | null {
+  const key = symbol.toUpperCase();
+  const history = rateHistoryMap.get(key) || [];
+
+  // Find the most recent rate within the 30s window
+  const windowStart = currentTimestampMs - VOLATILITY_WINDOW_MS;
+
+  for (let i = history.length - 1; i >= 0; i--) {
+    const entry = history[i];
+    if (entry && entry.timestamp_ms >= windowStart && entry.timestamp_ms < currentTimestampMs) {
+      return entry;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * System-level rate validation (non-bypassable)
+ *
+ * Validates:
+ * 1. Data source availability - at least one provider returned a rate
+ * 2. Multi-source deviation - if multiple sources, deviation ≤ 10%
+ * 3. 30s volatility - rate change within 30s window ≤ 20%
+ *
+ * @param rateResult - The exchange rate result from providers
+ * @param symbol - Token symbol for volatility tracking
+ * @returns Validation result with error details if failed
+ */
+export function validateRateTrustworthy(rateResult: ExchangeRateResult, symbol: string): RateValidationResult {
+  const providers = rateResult.providers || [];
+
+  // 1. Check data source availability
+  if (providers.length === 0) {
+    logger.warn('Rate validation failed: No providers available', { symbol });
+    return {
+      trustworthy: false,
+      error_code: 'PRICE_UNAVAILABLE',
+      error_message: 'All exchange rate providers are unavailable',
+    };
+  }
+
+  // 2. Check multi-source deviation (if multiple sources)
+  if (providers.length >= 2) {
+    const rates = providers.map((p) => parseFloat(p.rate)).filter((r) => Number.isFinite(r));
+    if (rates.length >= 2) {
+      const maxRate = Math.max(...rates);
+      const minRate = Math.min(...rates);
+      const median = parseFloat(rateResult.rate);
+
+      if (median > 0) {
+        const deviationPercent = (maxRate - minRate) / median;
+
+        if (deviationPercent > MULTI_SOURCE_DEVIATION_THRESHOLD) {
+          logger.warn('Rate validation failed: Multi-source deviation too high', {
+            symbol,
+            deviation: `${(deviationPercent * 100).toFixed(2)}%`,
+            threshold: `${MULTI_SOURCE_DEVIATION_THRESHOLD * 100}%`,
+            rates: providers.map((p) => ({ provider: p.provider_name, rate: p.rate })),
+          });
+
+          return {
+            trustworthy: false,
+            error_code: 'PRICE_UNSTABLE',
+            error_message: `Multi-source deviation ${(deviationPercent * 100).toFixed(2)}% exceeds 10% threshold`,
+            deviation_percent: deviationPercent * 100,
+          };
+        }
+      }
+    }
+  }
+
+  // 3. Check 30s volatility
+  const prevEntry = getPreviousTrustedRate(symbol, rateResult.timestamp_ms);
+  if (prevEntry) {
+    const currentRate = parseFloat(rateResult.rate);
+    const prevRate = parseFloat(prevEntry.rate);
+
+    if (prevRate > 0 && Number.isFinite(currentRate) && Number.isFinite(prevRate)) {
+      const volatilityPercent = Math.abs(currentRate - prevRate) / prevRate;
+
+      if (volatilityPercent > VOLATILITY_30S_THRESHOLD) {
+        logger.warn('Rate validation failed: 30s volatility too high', {
+          symbol,
+          volatility: `${(volatilityPercent * 100).toFixed(2)}%`,
+          threshold: `${VOLATILITY_30S_THRESHOLD * 100}%`,
+          currentRate: rateResult.rate,
+          prevRate: prevEntry.rate,
+          timeDiff: `${(rateResult.timestamp_ms - prevEntry.timestamp_ms) / 1000}s`,
+        });
+
+        return {
+          trustworthy: false,
+          error_code: 'PRICE_UNSTABLE',
+          error_message: `30s volatility ${(volatilityPercent * 100).toFixed(2)}% exceeds 20% threshold`,
+          volatility_percent: volatilityPercent * 100,
+        };
+      }
+    }
+  }
+
+  // Rate is trustworthy - record it for future volatility calculations
+  recordTrustedRate(symbol, rateResult.rate, rateResult.timestamp_ms);
+
+  logger.debug('Rate validation passed', {
+    symbol,
+    rate: rateResult.rate,
+    providers: providers.length,
+  });
+
+  return { trustworthy: true };
+}
+
+/**
+ * User-level slippage validation (bypassable with user confirmation)
+ *
+ * Validates that the price change between preview and submit is within
+ * the user's configured slippage tolerance.
+ *
+ * @param previewRate - Rate displayed during preview
+ * @param submitRate - Rate at submit time
+ * @param userSlippage - User's slippage tolerance (default 0.5%)
+ * @param priceConfirmed - Whether user has confirmed the price change
+ * @returns Validation result
+ */
+export function validateUserSlippage(
+  previewRate: string,
+  submitRate: string,
+  userSlippage: number = DEFAULT_SLIPPAGE_PERCENT,
+  priceConfirmed: boolean = false
+): SlippageValidationResult {
+  const previewNum = parseFloat(previewRate);
+  const submitNum = parseFloat(submitRate);
+
+  // Invalid rates - treat as passed (backend will handle separately)
+  if (!Number.isFinite(previewNum) || !Number.isFinite(submitNum) || previewNum <= 0) {
+    return {
+      passed: true,
+      change_percent: 0,
+      preview_rate: previewRate,
+      submit_rate: submitRate,
+      slippage_threshold: userSlippage,
+    };
+  }
+
+  const changePercent = (Math.abs(submitNum - previewNum) / previewNum) * 100;
+  const slippageThreshold = userSlippage; // Already in percent
+
+  // If user has confirmed, always pass
+  if (priceConfirmed) {
+    logger.info('Slippage check bypassed: User confirmed price change', {
+      change: `${changePercent.toFixed(4)}%`,
+      threshold: `${slippageThreshold}%`,
+    });
+    return {
+      passed: true,
+      change_percent: changePercent,
+      preview_rate: previewRate,
+      submit_rate: submitRate,
+      slippage_threshold: slippageThreshold,
+    };
+  }
+
+  const passed = changePercent <= slippageThreshold;
+
+  if (!passed) {
+    logger.info('Slippage check failed: Price change exceeds user threshold', {
+      change: `${changePercent.toFixed(4)}%`,
+      threshold: `${slippageThreshold}%`,
+      preview_rate: previewRate,
+      submit_rate: submitRate,
+    });
+  }
+
+  return {
+    passed,
+    change_percent: changePercent,
+    preview_rate: previewRate,
+    submit_rate: submitRate,
+    slippage_threshold: slippageThreshold,
+  };
+}
+
+/**
+ * Combined validation for Submit phase
+ *
+ * Executes both validations in order:
+ * 1. System-level (non-bypassable)
+ * 2. User-level (bypassable with confirmation)
+ */
+export interface SubmitValidationResult {
+  passed: boolean;
+  error_code?: 'PRICE_UNAVAILABLE' | 'PRICE_UNSTABLE' | 'PRICE_CHANGED';
+  error_message?: string;
+  system_validation: RateValidationResult;
+  slippage_validation?: SlippageValidationResult;
+}
+
+export function validateForSubmit(
+  rateResult: ExchangeRateResult,
+  symbol: string,
+  previewRate: string | undefined,
+  userSlippage: number = DEFAULT_SLIPPAGE_PERCENT,
+  priceConfirmed: boolean = false
+): SubmitValidationResult {
+  // 1. System-level validation (non-bypassable)
+  const systemResult = validateRateTrustworthy(rateResult, symbol);
+  if (!systemResult.trustworthy) {
+    return {
+      passed: false,
+      error_code: systemResult.error_code,
+      error_message: systemResult.error_message,
+      system_validation: systemResult,
+    };
+  }
+
+  // 2. User-level slippage validation (bypassable)
+  if (previewRate) {
+    const slippageResult = validateUserSlippage(previewRate, rateResult.rate, userSlippage, priceConfirmed);
+
+    if (!slippageResult.passed) {
+      return {
+        passed: false,
+        error_code: 'PRICE_CHANGED',
+        error_message: `Price changed ${slippageResult.change_percent.toFixed(2)}% (threshold: ${slippageResult.slippage_threshold}%)`,
+        system_validation: systemResult,
+        slippage_validation: slippageResult,
+      };
+    }
+
+    return {
+      passed: true,
+      system_validation: systemResult,
+      slippage_validation: slippageResult,
+    };
+  }
+
+  return {
+    passed: true,
+    system_validation: systemResult,
+  };
+}
+
+/**
+ * Clear rate history (for testing)
+ */
+export function clearRateHistory(): void {
+  rateHistoryMap.clear();
+}