@sip-protocol/api 0.1.0 → 0.1.1

package/src/monitoring/sentry.ts

@@ -0,0 +1,179 @@
+/**
+ * Sentry Error Monitoring
+ *
+ * Integrates Sentry for production error tracking:
+ * - Captures unhandled exceptions
+ * - Captures unhandled promise rejections
+ * - Provides stack traces with source maps
+ * - Enriches errors with request context
+ */
+
+import * as Sentry from '@sentry/node'
+import type { Express, ErrorRequestHandler } from 'express'
+import { env } from '../config'
+
+let isInitialized = false
+
+/**
+ * Initialize Sentry error monitoring
+ *
+ * Only initializes if SENTRY_DSN is provided
+ */
+export function initSentry(): void {
+  if (isInitialized) return
+
+  if (!env.SENTRY_DSN) {
+    if (env.isProduction) {
+      console.warn('[Sentry] SENTRY_DSN not set - error monitoring disabled')
+    }
+    return
+  }
+
+  Sentry.init({
+    dsn: env.SENTRY_DSN,
+    environment: env.NODE_ENV,
+    release: `sip-api@${process.env.npm_package_version || '0.1.0'}`,
+
+    // Performance monitoring
+    tracesSampleRate: env.isProduction ? 0.1 : 1.0,
+
+    // Filter out noisy errors
+    ignoreErrors: [
+      // Expected client errors
+      'Request validation failed',
+      'Unauthorized',
+      // Network issues
+      'ECONNRESET',
+      'EPIPE',
+    ],
+
+    // Add extra context
+    beforeSend(event) {
+      // Don't send events in test environment
+      if (env.NODE_ENV === 'test') {
+        return null
+      }
+
+      // Add request ID tag for correlation
+      const requestId = event.request?.headers?.['x-request-id']
+      if (requestId && typeof requestId === 'string') {
+        event.tags = { ...event.tags, requestId }
+      }
+
+      // Sanitize sensitive data
+      if (event.request?.headers) {
+        delete event.request.headers['authorization']
+        delete event.request.headers['x-api-key']
+        delete event.request.headers['cookie']
+      }
+
+      return event
+    },
+
+    // Capture breadcrumbs for debugging
+    beforeBreadcrumb(breadcrumb) {
+      // Filter out health check noise
+      if (breadcrumb.category === 'http' && breadcrumb.data?.url?.includes('/health')) {
+        return null
+      }
+      return breadcrumb
+    },
+  })
+
+  isInitialized = true
+  console.log('[Sentry] Initialized for environment:', env.NODE_ENV)
+}
+
+/**
+ * Check if Sentry is initialized
+ */
+export function isSentryEnabled(): boolean {
+  return isInitialized && !!env.SENTRY_DSN
+}
+
+/**
+ * Capture an exception with optional context
+ */
+export function captureException(
+  error: Error,
+  context?: Record<string, unknown>
+): string | undefined {
+  if (!isSentryEnabled()) return undefined
+
+  return Sentry.captureException(error, {
+    extra: context,
+  })
+}
+
+/**
+ * Capture a message with severity level
+ */
+export function captureMessage(
+  message: string,
+  level: Sentry.SeverityLevel = 'info'
+): string | undefined {
+  if (!isSentryEnabled()) return undefined
+
+  return Sentry.captureMessage(message, level)
+}
+
+/**
+ * Set user context for error tracking
+ */
+export function setUser(user: { id: string; [key: string]: unknown } | null): void {
+  if (!isSentryEnabled()) return
+
+  Sentry.setUser(user)
+}
+
+/**
+ * Add context tags
+ */
+export function setTags(tags: Record<string, string>): void {
+  if (!isSentryEnabled()) return
+
+  Sentry.setTags(tags)
+}
+
+/**
+ * Setup Express error handler for Sentry
+ * Call after all routes are registered
+ */
+export function setupSentryErrorHandler(app: Express): void {
+  if (!isSentryEnabled()) return
+
+  Sentry.setupExpressErrorHandler(app)
+}
+
+/**
+ * Create a no-op request handler middleware
+ * Sentry v10 uses auto-instrumentation, but we keep this for compatibility
+ */
+export function sentryRequestHandler(
+  _req: unknown,
+  _res: unknown,
+  next: () => void
+): void {
+  next()
+}
+
+/**
+ * Create a no-op error handler for compatibility
+ * Actual error handling is done via setupSentryErrorHandler
+ */
+export const sentryErrorHandler: ErrorRequestHandler = (err, _req, _res, next) => {
+  // Sentry v10 captures errors automatically via setupExpressErrorHandler
+  // This middleware is kept for API compatibility
+  next(err)
+}
+
+/**
+ * Flush pending events (call before shutdown)
+ */
+export async function flushSentry(timeout = 2000): Promise<boolean> {
+  if (!isSentryEnabled()) return true
+
+  return Sentry.close(timeout)
+}
+
+export { Sentry }

package/src/routes/commitment.ts

@@ -45,7 +45,7 @@ router.post(
     const { value, blindingFactor } = req.body as CreateCommitmentRequest
 
     const valueBigInt = BigInt(value)
-    const blindingBytes = blindingFactor ? hexToBytes(blindingFactor) : undefined
+    const blindingBytes = blindingFactor ? hexToBytes(blindingFactor.replace(/^0x/, '')) : undefined
 
     const result = commit(valueBigInt, blindingBytes)
 

package/src/routes/health.ts

@@ -1,5 +1,9 @@
 import { Router, Request, Response } from 'express'
 import type { HealthResponse, ApiResponse } from '../types/api'
+import { isServerShuttingDown } from '../shutdown'
+import { swapStore } from '../stores'
+import { isProofProviderReady, getProofInitError } from './proof'
+import { getRedisStatus } from '../middleware/rate-limit'
 
 const router: Router = Router()
 
@@ -38,17 +42,45 @@ const startTime = Date.now()
  *                       type: number
  */
 router.get('/', (req: Request, res: Response) => {
+  const shuttingDown = isServerShuttingDown()
+  const status = shuttingDown ? 'shutting_down' : 'healthy'
+  const statusCode = shuttingDown ? 503 : 200
+
+  const cacheMetrics = swapStore.getMetrics()
+
+  const proofReady = isProofProviderReady()
+  const proofError = getProofInitError()
+  const redisStatus = getRedisStatus()
+
   const response: ApiResponse<HealthResponse> = {
-    success: true,
+    success: !shuttingDown,
     data: {
-      status: 'healthy',
+      status: status as 'healthy',
       version: process.env.npm_package_version || '0.1.0',
       timestamp: new Date().toISOString(),
       uptime: Math.floor((Date.now() - startTime) / 1000),
+      services: {
+        proofProvider: {
+          ready: proofReady,
+          error: proofError?.message || null,
+        },
+        rateLimiter: {
+          store: redisStatus.storeType,
+          redisConfigured: redisStatus.configured,
+          redisConnected: redisStatus.connected,
+        },
+      },
+      cache: {
+        swaps: {
+          size: cacheMetrics.size,
+          maxSize: cacheMetrics.maxSize,
+          utilizationPercent: cacheMetrics.utilizationPercent,
+        },
+      },
     },
   }
 
-  res.json(response)
+  res.status(statusCode).json(response)
 })
 
 export default router

package/src/routes/index.ts

@@ -4,6 +4,7 @@ import stealthRouter from './stealth'
 import commitmentRouter from './commitment'
 import proofRouter from './proof'
 import swapRouter from './swap'
+import webhookRouter from './webhook'
 
 const router: Router = Router()
 
@@ -14,5 +15,6 @@ router.use('/commitment', commitmentRouter)
 router.use('/proof', proofRouter)
 router.use('/quote', swapRouter)  // POST /quote
 router.use('/swap', swapRouter)   // POST /swap and GET /swap/:id/status
+router.use('/webhooks', webhookRouter) // Webhook registration CRUD + Helius ingest
 
 export default router

package/src/routes/metrics.ts

@@ -0,0 +1,27 @@
+/**
+ * Prometheus Metrics Endpoint
+ *
+ * GET /metrics - Prometheus-compatible metrics
+ */
+
+import { Router, Request, Response } from 'express'
+import { register } from '../monitoring'
+
+const router: Router = Router()
+
+/**
+ * GET /metrics
+ * Prometheus metrics endpoint
+ *
+ * Returns metrics in Prometheus text format for scraping
+ */
+router.get('/', async (req: Request, res: Response) => {
+  try {
+    res.set('Content-Type', register.contentType)
+    res.end(await register.metrics())
+  } catch (err) {
+    res.status(500).end()
+  }
+})
+
+export default router

package/src/routes/proof.ts

@@ -2,6 +2,7 @@ import { Router, Request, Response } from 'express'
 import { MockProofProvider } from '@sip-protocol/sdk'
 import { hexToBytes } from '@noble/hashes/utils'
 import { validateRequest, schemas } from '../middleware'
+import { logger } from '../logger'
 import type { GenerateFundingProofRequest, FundingProofResponse, ApiResponse } from '../types/api'
 
 const router: Router = Router()
@@ -10,6 +11,58 @@ const router: Router = Router()
 // In production, use NoirProofProvider from '@sip-protocol/sdk/proofs/noir'
 const proofProvider = new MockProofProvider()
 
+/**
+ * Proof provider initialization state
+ * Implements fail-fast pattern with retry for transient failures
+ */
+let proofProviderReady = false
+let proofInitError: Error | null = null
+
+const MAX_INIT_RETRIES = 3
+const RETRY_DELAY_MS = 2000
+
+async function initializeProofProvider(): Promise<void> {
+  for (let attempt = 1; attempt <= MAX_INIT_RETRIES; attempt++) {
+    try {
+      await proofProvider.initialize()
+      proofProviderReady = true
+      proofInitError = null
+      logger.info({ attempt }, 'Proof provider initialized successfully')
+      return
+    } catch (err) {
+      proofInitError = err instanceof Error ? err : new Error(String(err))
+      logger.warn({ attempt, maxRetries: MAX_INIT_RETRIES, error: proofInitError.message },
+        'Proof provider initialization failed, retrying...')
+
+      if (attempt < MAX_INIT_RETRIES) {
+        await new Promise(resolve => setTimeout(resolve, RETRY_DELAY_MS * attempt))
+      }
+    }
+  }
+
+  // All retries exhausted - log fatal but don't crash (graceful degradation)
+  // The readiness guard will reject proof requests until fixed
+  logger.error({ error: proofInitError?.message },
+    'Proof provider initialization failed after all retries')
+}
+
+// Start initialization immediately (non-blocking)
+initializeProofProvider()
+
+/**
+ * Check if proof provider is ready
+ */
+export function isProofProviderReady(): boolean {
+  return proofProviderReady
+}
+
+/**
+ * Get proof provider initialization error (if any)
+ */
+export function getProofInitError(): Error | null {
+  return proofInitError
+}
+
 /**
  * POST /proof/funding
  * Generate a funding proof (proves balance >= minimum without revealing exact balance)
@@ -52,11 +105,25 @@ router.post(
   '/funding',
   validateRequest({ body: schemas.generateFundingProof }),
   async (req: Request, res: Response) => {
+    // Readiness guard - reject requests if proof provider not initialized
+    if (!proofProviderReady) {
+      const errorMsg = proofInitError?.message || 'Proof provider is initializing'
+      logger.warn({ error: errorMsg }, 'Proof request rejected - provider not ready')
+      return res.status(503).json({
+        success: false,
+        error: {
+          code: 'PROOF_PROVIDER_NOT_READY',
+          message: 'Proof generation service is not ready',
+          details: { reason: errorMsg },
+        },
+      })
+    }
+
     const { balance, minRequired, balanceBlinding } = req.body as GenerateFundingProofRequest
 
     const balanceBigInt = BigInt(balance)
     const minRequiredBigInt = BigInt(minRequired)
-    const balanceBlindingBytes = hexToBytes(balanceBlinding)
+    const balanceBlindingBytes = hexToBytes(balanceBlinding.replace(/^0x/, ''))
 
     const result = await proofProvider.generateFundingProof({
       balance: balanceBigInt,

package/src/routes/swap.ts

@@ -1,6 +1,9 @@
 import { Router, Request, Response } from 'express'
-import { SIP, PrivacyLevel } from '@sip-protocol/sdk'
-import { validateRequest, schemas } from '../middleware'
+import { SIP, PrivacyLevel, getAsset, isKnownToken } from '@sip-protocol/sdk'
+import { validateRequest, schemas, calculateMinAmount, percentToBps } from '../middleware'
+import { swapStore } from '../stores'
+import { env } from '../config'
+import { logger } from '../logger'
 import type {
   GetQuoteRequest,
   ExecuteSwapRequest,
@@ -15,19 +18,15 @@ const router: Router = Router()
 // Initialize SIP client
 const sip = new SIP({ network: 'testnet' })
 
-import type { HexString } from '@sip-protocol/types'
+/**
+ * Check if mock mode is allowed
+ * In production, mock mode should be explicitly disabled
+ */
+const MOCK_MODE_ENABLED = env.NODE_ENV !== 'production'
 
-// In-memory swap tracking (in production, use a database)
-const swaps = new Map<string, {
-  id: string
-  status: 'pending' | 'processing' | 'completed' | 'failed'
-  transactionHash?: HexString
-  inputAmount: string
-  outputAmount?: string
-  createdAt: string
-  updatedAt: string
-  error?: string
-}>()
+if (!MOCK_MODE_ENABLED) {
+  logger.warn('Production mode: Mock quotes and swaps are DISABLED')
+}
 
 /**
  * POST /quote
@@ -82,36 +81,78 @@ router.post(
       slippageTolerance
     } = req.body as GetQuoteRequest
 
-    // Create intent
+    // PRODUCTION MODE: Fail if quote aggregator not configured
+    if (!MOCK_MODE_ENABLED) {
+      return res.status(503).json({
+        success: false,
+        error: {
+          code: 'QUOTE_SERVICE_UNAVAILABLE',
+          message: 'Real quote aggregator not configured. This API is not ready for production use.',
+          details: {
+            hint: 'Configure QUOTE_AGGREGATOR_URL or use development mode',
+          },
+        },
+      })
+    }
+
+    // Validate tokens are known (fail fast on unknown tokens)
+    if (!isKnownToken(inputToken, inputChain)) {
+      return res.status(400).json({
+        success: false,
+        error: {
+          code: 'UNKNOWN_TOKEN',
+          message: `Unknown input token: ${inputToken} on ${inputChain}`,
+        },
+      } satisfies ApiResponse<never>)
+    }
+    if (!isKnownToken(outputToken, outputChain)) {
+      return res.status(400).json({
+        success: false,
+        error: {
+          code: 'UNKNOWN_TOKEN',
+          message: `Unknown output token: ${outputToken} on ${outputChain}`,
+        },
+      } satisfies ApiResponse<never>)
+    }
+
+    // Get asset info with correct decimals from registry
+    const inputAsset = getAsset(inputToken, inputChain)
+    const outputAsset = getAsset(outputToken, outputChain)
+
+    // Parse and validate amount (already validated by schema, safe to parse)
+    const inputAmountBigInt = BigInt(inputAmount)
+    const slippagePercent = slippageTolerance ?? 1
+    const slippageBps = percentToBps(slippagePercent)
+
+    // Create intent with safe slippage calculation
     const intent = await sip.createIntent({
       input: {
-        asset: {
-          chain: inputChain,
-          address: null, // Native token
-          symbol: inputToken,
-          decimals: 9,
-        },
-        amount: BigInt(inputAmount),
+        asset: inputAsset,
+        amount: inputAmountBigInt,
       },
       output: {
-        asset: {
-          chain: outputChain,
-          address: null, // Native token
-          symbol: outputToken,
-          decimals: 9,
-        },
-        minAmount: BigInt(inputAmount) * 95n / 100n, // 5% slippage
-        maxSlippage: (slippageTolerance || 1) / 100,
+        asset: outputAsset,
+        minAmount: calculateMinAmount(inputAmountBigInt, slippageBps),
+        maxSlippage: slippagePercent / 100,
       },
       privacy: PrivacyLevel.TRANSPARENT, // Default to transparent for quote
     })
 
-    // Get quotes (using mock data for now)
-    // In production, this would query real DEX aggregators
+    // DEV MODE: Return mock quote with warning
+    // In production, this block would never execute (see check above)
+    logger.warn({
+      inputChain,
+      inputToken,
+      outputChain,
+      outputToken,
+      inputAmount,
+    }, 'Returning MOCK quote - not for production use')
+
     const mockQuote: QuoteResponse = {
       quoteId: `quote-${Date.now()}`,
       inputAmount,
-      outputAmount: (BigInt(inputAmount) * 95n / 100n).toString(), // Mock 5% fee
+      // Mock: 5% fee (clearly fake rate)
+      outputAmount: (BigInt(inputAmount) * 95n / 100n).toString(),
       rate: '0.95',
       estimatedTime: 30,
       fees: {
@@ -130,9 +171,12 @@ router.post(
       },
     }
 
-    const response: ApiResponse<QuoteResponse> = {
+    const response: ApiResponse<QuoteResponse & { _warning?: string }> = {
       success: true,
-      data: mockQuote,
+      data: {
+        ...mockQuote,
+        _warning: 'MOCK_DATA: This quote uses simulated pricing. Do not use for real transactions.',
+      },
     }
 
     res.json(response)
@@ -176,33 +220,56 @@ router.post(
   '/swap',
   validateRequest({ body: schemas.executeSwap }),
   async (req: Request, res: Response) => {
-    const { intentId, quoteId, privacy, viewingKey } = req.body as ExecuteSwapRequest
+    const { intentId, quoteId, inputAmount } = req.body as ExecuteSwapRequest & { inputAmount?: string }
+
+    // PRODUCTION MODE: Fail if swap executor not configured
+    if (!MOCK_MODE_ENABLED) {
+      return res.status(503).json({
+        success: false,
+        error: {
+          code: 'SWAP_SERVICE_UNAVAILABLE',
+          message: 'Real swap executor not configured. This API is not ready for production use.',
+          details: {
+            hint: 'Configure SWAP_EXECUTOR_URL or use development mode',
+          },
+        },
+      })
+    }
 
     // Generate swap ID
     const swapId = `swap-${Date.now()}`
 
-    // Store swap status
+    // Track actual input amount from request (not hardcoded)
+    // In dev mode, allow a default for testing but warn about it
+    const actualInputAmount = inputAmount || '0'
+    if (!inputAmount) {
+      logger.warn({ swapId, quoteId, intentId }, 'Swap created without inputAmount - using 0')
+    }
+
+    // Store swap in LRU cache with TTL
     const swap = {
       id: swapId,
       status: 'pending' as const,
-      inputAmount: '1000000000', // Mock value
+      inputAmount: actualInputAmount,
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     }
-    swaps.set(swapId, swap)
+    swapStore.set(swapId, swap)
 
-    // In production, this would:
-    // 1. Sign the transaction
-    // 2. Submit to the network
-    // 3. Track the transaction
-    // For now, we just return a mock response
+    logger.warn({
+      swapId,
+      quoteId,
+      intentId,
+      inputAmount: actualInputAmount,
+    }, 'Creating MOCK swap - not for production use')
 
-    const response: ApiResponse<SwapResponse> = {
+    const response: ApiResponse<SwapResponse & { _warning?: string }> = {
       success: true,
       data: {
         swapId,
         status: 'pending',
         timestamp: new Date().toISOString(),
+        _warning: 'MOCK_DATA: This swap is simulated. No real transaction will be executed.',
       },
     }
 
@@ -237,15 +304,17 @@ router.get(
   validateRequest({ params: schemas.swapStatus }),
   async (req: Request, res: Response) => {
     const { id } = req.params
+    // Express 5 types params as string | string[] - ensure we have a string
+    const swapId = Array.isArray(id) ? id[0] : id
 
-    const swap = swaps.get(id)
+    const swap = swapStore.get(swapId)
 
     if (!swap) {
       return res.status(404).json({
         success: false,
         error: {
           code: 'SWAP_NOT_FOUND',
-          message: `Swap ${id} not found`,
+          message: `Swap ${swapId} not found`,
         },
       })
     }