@sip-protocol/sdk 0.7.3 → 0.8.0

package/src/chains/solana/providers/helius.ts

@@ -21,6 +21,73 @@
  */
 
 import type { SolanaRPCProvider, TokenAsset, ProviderConfig } from './interface'
+import { ValidationError, NetworkError } from '../../../errors'
+import {
+  SOLANA_ADDRESS_MIN_LENGTH,
+  SOLANA_ADDRESS_MAX_LENGTH,
+  HELIUS_API_KEY_MIN_LENGTH,
+  HELIUS_DAS_PAGE_LIMIT,
+  HELIUS_MAX_PAGES,
+  sanitizeUrl,
+} from '../constants'
+
+/** Default fetch timeout in milliseconds */
+const DEFAULT_FETCH_TIMEOUT_MS = 30000
+
+/**
+ * Mask API key for safe logging/error messages
+ *
+ * Shows only first 4 and last 4 characters to prevent key exposure.
+ *
+ * @param apiKey - Helius API key to mask
+ * @returns Masked key (e.g., 'abcd...wxyz') or '***' if too short
+ * @internal
+ */
+function maskApiKey(apiKey: string): string {
+  if (apiKey.length <= HELIUS_API_KEY_MIN_LENGTH) return '***'
+  return `${apiKey.slice(0, 4)}...${apiKey.slice(-4)}`
+}
+
+/**
+ * Fetch with configurable timeout using AbortController
+ *
+ * Wraps fetch with a timeout to prevent hanging requests.
+ *
+ * @param url - URL to fetch
+ * @param options - Fetch options (method, headers, body, etc.)
+ * @param timeoutMs - Timeout in milliseconds (default: 30000)
+ * @returns Fetch response
+ * @throws NetworkError if request times out
+ * @internal
+ */
+async function fetchWithTimeout(
+  url: string,
+  options: RequestInit,
+  timeoutMs: number = DEFAULT_FETCH_TIMEOUT_MS
+): Promise<Response> {
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
+
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: controller.signal,
+    })
+    return response
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      // H-2 FIX: Sanitize URL to prevent credential exposure
+      throw new NetworkError(
+        `Request timeout after ${timeoutMs}ms`,
+        undefined,
+        { endpoint: sanitizeUrl(url) }
+      )
+    }
+    throw error
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
 
 /**
  * Helius API response types
@@ -79,9 +146,17 @@ interface HeliusBalancesResponse {
 
 /**
  * Helius provider configuration
+ *
+ * @security API keys should be treated as sensitive credentials.
  */
 export interface HeliusProviderConfig extends ProviderConfig {
-  /** Helius API key (required) */
+  /**
+   * Helius API key (required)
+   *
+   * @security Treat as sensitive credential. Use environment variables.
+   * Never commit to source control or log in error messages.
+   * The SDK masks this key in error messages automatically.
+   */
   apiKey: string
   /** Solana cluster (default: mainnet-beta) */
   cluster?: 'mainnet-beta' | 'devnet'
@@ -95,28 +170,41 @@ export interface HeliusProviderConfig extends ProviderConfig {
  */
 export class HeliusProvider implements SolanaRPCProvider {
   readonly name = 'helius'
-  private apiKey: string
-  private cluster: 'mainnet-beta' | 'devnet'
-  private rpcUrl: string
-  private restUrl: string
+  private readonly apiKey: string
+  private readonly cluster: 'mainnet-beta' | 'devnet'
+  private readonly rpcUrl: string
+  private readonly restUrl: string
 
   constructor(config: HeliusProviderConfig) {
+    // Validate API key
     if (!config.apiKey) {
-      throw new Error('Helius API key is required. Get one at https://dev.helius.xyz')
+      throw new ValidationError(
+        'Helius API key is required. Get one at https://dev.helius.xyz',
+        'apiKey'
+      )
+    }
+
+    // Validate API key format (basic check - Helius keys are UUIDs or alphanumeric)
+    if (typeof config.apiKey !== 'string' || config.apiKey.length < HELIUS_API_KEY_MIN_LENGTH) {
+      throw new ValidationError(
+        'Invalid Helius API key format',
+        'apiKey'
+      )
     }
 
     this.apiKey = config.apiKey
     this.cluster = config.cluster ?? 'mainnet-beta'
 
-    // RPC endpoint for DAS API
+    // RPC endpoint for DAS API (no API key in URL - use header instead)
+    // H-1 FIX: API key moved from URL query parameter to Authorization header
     this.rpcUrl = this.cluster === 'devnet'
-      ? `https://devnet.helius-rpc.com/?api-key=${this.apiKey}`
-      : `https://mainnet.helius-rpc.com/?api-key=${this.apiKey}`
+      ? 'https://devnet.helius-rpc.com'
+      : 'https://mainnet.helius-rpc.com'
 
     // REST endpoint for balances API
     this.restUrl = this.cluster === 'devnet'
-      ? `https://api-devnet.helius.xyz/v0`
-      : `https://api.helius.xyz/v0`
+      ? 'https://api-devnet.helius.xyz/v0'
+      : 'https://api.helius.xyz/v0'
   }
 
   /**
@@ -126,15 +214,28 @@ export class HeliusProvider implements SolanaRPCProvider {
    * NFTs and fungible tokens with metadata.
    */
   async getAssetsByOwner(owner: string): Promise<TokenAsset[]> {
+    // Validate owner address
+    if (!owner || typeof owner !== 'string') {
+      throw new ValidationError('owner address is required', 'owner')
+    }
+    // Basic Solana address validation (32-44 chars, base58)
+    if (owner.length < SOLANA_ADDRESS_MIN_LENGTH || owner.length > SOLANA_ADDRESS_MAX_LENGTH) {
+      throw new ValidationError('invalid Solana address format', 'owner')
+    }
+
     const assets: TokenAsset[] = []
     let page = 1
-    const limit = 1000
+    const limit = HELIUS_DAS_PAGE_LIMIT
     let hasMore = true
 
     while (hasMore) {
-      const response = await fetch(this.rpcUrl, {
+      const response = await fetchWithTimeout(this.rpcUrl, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: {
+          'Content-Type': 'application/json',
+          // H-1 FIX: Use Authorization header instead of URL query parameter
+          'Authorization': `Bearer ${this.apiKey}`,
+        },
         body: JSON.stringify({
           jsonrpc: '2.0',
           id: `sip-${Date.now()}`,
@@ -152,14 +253,23 @@ export class HeliusProvider implements SolanaRPCProvider {
       })
 
       if (!response.ok) {
-        throw new Error(`Helius API error: ${response.status} ${response.statusText}`)
+        // H-2 FIX: Never include API key in error messages, sanitize URLs
+        throw new NetworkError(
+          `Helius API error: ${response.status} ${response.statusText} (key: ${maskApiKey(this.apiKey)})`,
+          undefined,
+          { endpoint: sanitizeUrl(this.rpcUrl), statusCode: response.status }
+        )
       }
 
       const data = (await response.json()) as HeliusDASResponse
 
       // Handle JSON-RPC errors
       if (data.error) {
-        throw new Error(`Helius RPC error: ${data.error.message} (code: ${data.error.code})`)
+        throw new NetworkError(
+          `Helius RPC error: ${data.error.message} (code: ${data.error.code})`,
+          undefined,
+          { endpoint: sanitizeUrl(this.rpcUrl) }
+        )
       }
 
       if (data.result?.items) {
@@ -174,10 +284,14 @@ export class HeliusProvider implements SolanaRPCProvider {
           if (!tokenInfo?.balance) continue
 
           // Convert balance to BigInt, handling both string and number types
-          // String is preferred for large values to preserve precision
-          const balanceValue = typeof tokenInfo.balance === 'string'
-            ? BigInt(tokenInfo.balance)
-            : BigInt(Math.floor(tokenInfo.balance))
+          // Always use string parsing for BigInt to avoid precision loss
+          let balanceValue: bigint
+          if (typeof tokenInfo.balance === 'string') {
+            balanceValue = BigInt(tokenInfo.balance)
+          } else {
+            // For numbers, convert to string first to avoid precision loss
+            balanceValue = BigInt(Math.floor(tokenInfo.balance).toString())
+          }
 
           assets.push({
             mint: item.id,
@@ -195,8 +309,7 @@ export class HeliusProvider implements SolanaRPCProvider {
       page++
 
       // Safety limit to prevent infinite loops
-      if (page > 100) {
-        console.warn('[HeliusProvider] Reached page limit (100), stopping pagination')
+      if (page > HELIUS_MAX_PAGES) {
         break
       }
     }
@@ -210,16 +323,43 @@ export class HeliusProvider implements SolanaRPCProvider {
    * More efficient than getAssetsByOwner when you only need one token's balance.
    */
   async getTokenBalance(owner: string, mint: string): Promise<bigint> {
-    try {
-      const url = `${this.restUrl}/addresses/${owner}/balances?api-key=${this.apiKey}`
+    // Validate inputs
+    if (!owner || typeof owner !== 'string') {
+      throw new ValidationError('owner address is required', 'owner')
+    }
+    if (!mint || typeof mint !== 'string') {
+      throw new ValidationError('mint address is required', 'mint')
+    }
+    // Validate address format
+    if (owner.length < SOLANA_ADDRESS_MIN_LENGTH || owner.length > SOLANA_ADDRESS_MAX_LENGTH) {
+      throw new ValidationError('invalid owner address format', 'owner')
+    }
+    if (mint.length < SOLANA_ADDRESS_MIN_LENGTH || mint.length > SOLANA_ADDRESS_MAX_LENGTH) {
+      throw new ValidationError('invalid mint address format', 'mint')
+    }
 
-      const response = await fetch(url)
+    const url = `${this.restUrl}/addresses/${owner}/balances`
+
+    try {
+      const response = await fetchWithTimeout(url, {
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+        },
+      })
 
       if (!response.ok) {
-        // Fallback to DAS if balances API fails
-        const assets = await this.getAssetsByOwner(owner)
-        const asset = assets.find((a) => a.mint === mint)
-        return asset?.amount ?? 0n
+        // Only fallback for specific recoverable errors (404, 503)
+        // Don't fallback for auth errors (401, 403) or client errors (400)
+        if (response.status === 404 || response.status === 503) {
+          return this.getTokenBalanceFallback(owner, mint)
+        }
+        // For other errors, throw rather than silently fallback
+        // H-2 FIX: Sanitize URL to prevent credential exposure
+        throw new NetworkError(
+          `Helius Balances API error: ${response.status}`,
+          undefined,
+          { endpoint: sanitizeUrl(url), statusCode: response.status }
+        )
       }
 
       const data = (await response.json()) as HeliusBalancesResponse
@@ -227,13 +367,26 @@ export class HeliusProvider implements SolanaRPCProvider {
       const token = data.tokens?.find((t) => t.mint === mint)
       return token ? BigInt(token.amount) : 0n
     } catch (error) {
-      console.warn('[HeliusProvider] getTokenBalance error, falling back to DAS:', error)
-      const assets = await this.getAssetsByOwner(owner)
-      const asset = assets.find((a) => a.mint === mint)
-      return asset?.amount ?? 0n
+      // Only fallback for network/timeout errors, not all errors
+      if (error instanceof NetworkError && error.message.includes('timeout')) {
+        return this.getTokenBalanceFallback(owner, mint)
+      }
+      // Re-throw validation and other errors
+      throw error
     }
   }
 
+  /**
+   * Fallback method to DAS API for token balance
+   * Only called for specific recoverable errors
+   * @internal
+   */
+  private async getTokenBalanceFallback(owner: string, mint: string): Promise<bigint> {
+    const assets = await this.getAssetsByOwner(owner)
+    const asset = assets.find((a) => a.mint === mint)
+    return asset?.amount ?? 0n
+  }
+
   /**
    * Check if provider supports real-time subscriptions
    *

package/src/chains/solana/providers/index.ts

@@ -41,14 +41,45 @@ export {
 // Provider implementations
 export { HeliusProvider, type HeliusProviderConfig } from './helius'
 export { GenericProvider } from './generic'
+export { QuickNodeProvider, type QuickNodeProviderConfig } from './quicknode'
+export { TritonProvider, type TritonProviderConfig } from './triton'
 
 // Webhook handler for real-time scanning
 export {
   createWebhookHandler,
   processWebhookTransaction,
+  verifyWebhookSignature,
+  verifyAuthToken,
   type HeliusWebhookTransaction,
   type HeliusEnhancedTransaction,
   type HeliusWebhookPayload,
   type WebhookHandlerConfig,
   type WebhookProcessResult,
+  type WebhookRequest,
+  type WebhookHandler,
 } from './webhook'
+
+// Enhanced Transactions API for human-readable tx data
+export {
+  HeliusEnhanced,
+  createHeliusEnhanced,
+  type HeliusEnhancedConfig,
+} from './helius-enhanced'
+
+// Enhanced Transactions types
+export type {
+  EnhancedTransactionType,
+  NativeTransfer,
+  TokenTransfer,
+  NftTransfer,
+  SwapEvent,
+  EnhancedTransactionEvents,
+  EnhancedAccountData,
+  EnhancedTransaction,
+  ParseTransactionsOptions,
+  GetTransactionHistoryOptions,
+  PrivacyDisplayOptions,
+  SIPTransactionMetadata,
+  SIPEnhancedTransaction,
+  TransactionSummary,
+} from './helius-enhanced-types'

package/src/chains/solana/providers/interface.ts

@@ -27,6 +27,9 @@
 
 import { HeliusProvider, type HeliusProviderConfig } from './helius'
 import { GenericProvider } from './generic'
+import { QuickNodeProvider, type QuickNodeProviderConfig } from './quicknode'
+import { TritonProvider, type TritonProviderConfig } from './triton'
+import { ValidationError, ErrorCode } from '../../../errors'
 
 /**
  * Token asset information returned by providers
@@ -129,50 +132,90 @@ export interface GenericProviderConfig extends ProviderConfig {
  *
  * @example
  * ```typescript
- * // Helius with API key
+ * // Helius with DAS API (recommended for production)
  * const helius = createProvider('helius', {
  *   apiKey: process.env.HELIUS_API_KEY,
  *   cluster: 'devnet'
  * })
  *
- * // Generic with existing connection
- * const generic = createProvider('generic', { connection })
+ * // QuickNode with Yellowstone gRPC (real-time subscriptions)
+ * const quicknode = createProvider('quicknode', {
+ *   endpoint: process.env.QUICKNODE_ENDPOINT
+ * })
  *
- * // Generic with endpoint
- * const devnet = createProvider('generic', {
- *   endpoint: 'https://api.devnet.solana.com'
+ * // Triton with Dragon's Mouth gRPC (ultra-low latency)
+ * const triton = createProvider('triton', {
+ *   xToken: process.env.TRITON_TOKEN
  * })
+ *
+ * // Generic with existing connection
+ * const generic = createProvider('generic', { connection })
  * ```
  */
 export function createProvider(
   type: 'helius',
   config: ProviderConfig & { apiKey: string }
 ): SolanaRPCProvider
+export function createProvider(
+  type: 'quicknode',
+  config: QuickNodeProviderConfig
+): SolanaRPCProvider
+export function createProvider(
+  type: 'triton',
+  config: TritonProviderConfig
+): SolanaRPCProvider
 export function createProvider(
   type: 'generic',
   config: GenericProviderConfig
 ): SolanaRPCProvider
 export function createProvider(
   type: ProviderType,
-  config: ProviderConfig | GenericProviderConfig
+  config: ProviderConfig | GenericProviderConfig | QuickNodeProviderConfig | TritonProviderConfig
 ): SolanaRPCProvider
 export function createProvider(
   type: ProviderType,
-  config: ProviderConfig | GenericProviderConfig
+  config: ProviderConfig | GenericProviderConfig | QuickNodeProviderConfig | TritonProviderConfig
 ): SolanaRPCProvider {
+  // Validate config before type casting
+  if (!config || typeof config !== 'object') {
+    throw new ValidationError('Provider config is required', 'config')
+  }
+
   switch (type) {
-    case 'helius':
-      return new HeliusProvider(config as HeliusProviderConfig)
-    case 'generic':
-      return new GenericProvider(config as GenericProviderConfig)
+    case 'helius': {
+      // Validate required fields for HeliusProvider
+      const heliusConfig = config as HeliusProviderConfig
+      if (!heliusConfig.apiKey || typeof heliusConfig.apiKey !== 'string') {
+        throw new ValidationError(
+          'Helius provider requires an API key',
+          'apiKey'
+        )
+      }
+      if (heliusConfig.cluster && !['mainnet-beta', 'devnet'].includes(heliusConfig.cluster)) {
+        throw new ValidationError(
+          'Invalid cluster. Must be "mainnet-beta" or "devnet"',
+          'cluster'
+        )
+      }
+      return new HeliusProvider(heliusConfig)
+    }
     case 'quicknode':
+      return new QuickNodeProvider(config as QuickNodeProviderConfig)
     case 'triton':
-      throw new Error(
-        `Provider '${type}' is not yet implemented. ` +
-        `Use 'helius' or 'generic' for now. ` +
-        `See https://github.com/sip-protocol/sip-protocol/issues/${type === 'quicknode' ? '494' : '495'}`
-      )
+      return new TritonProvider(config as TritonProviderConfig)
+    case 'generic': {
+      // Validate GenericProvider config
+      const genericConfig = config as GenericProviderConfig
+      // Must have either connection, endpoint, or cluster
+      if (!genericConfig.connection && !genericConfig.endpoint && !genericConfig.cluster) {
+        throw new ValidationError(
+          'Generic provider requires either connection, endpoint, or cluster',
+          'config'
+        )
+      }
+      return new GenericProvider(genericConfig)
+    }
     default:
-      throw new Error(`Unknown provider type: ${type}`)
+      throw new ValidationError(`unknown provider type: ${type}`, 'type', undefined, ErrorCode.INVALID_INPUT)
   }
 }