@sip-protocol/sdk 0.7.2 → 0.7.3

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

@@ -0,0 +1,249 @@
+/**
+ * Helius RPC Provider
+ *
+ * Leverages Helius DAS (Digital Asset Standard) API for efficient
+ * token balance queries and asset metadata.
+ *
+ * @see https://docs.helius.dev/solana-apis/digital-asset-standard-das-api
+ *
+ * @example
+ * ```typescript
+ * import { HeliusProvider } from '@sip-protocol/sdk'
+ *
+ * const helius = new HeliusProvider({
+ *   apiKey: process.env.HELIUS_API_KEY!,
+ *   cluster: 'devnet'
+ * })
+ *
+ * const assets = await helius.getAssetsByOwner('7xK9...')
+ * console.log(assets) // [{ mint: '...', amount: 1000000n, decimals: 6, symbol: 'USDC' }]
+ * ```
+ */
+
+import type { SolanaRPCProvider, TokenAsset, ProviderConfig } from './interface'
+
+/**
+ * Helius API response types
+ */
+interface HeliusDASAsset {
+  id: string
+  interface: string
+  content?: {
+    metadata?: {
+      name?: string
+      symbol?: string
+    }
+    links?: {
+      image?: string
+    }
+  }
+  token_info?: {
+    /** Balance as string to preserve precision for large values */
+    balance?: string | number
+    decimals?: number
+    symbol?: string
+    token_program?: string
+    mint_authority?: string
+    freeze_authority?: string
+  }
+  ownership?: {
+    owner: string
+  }
+}
+
+interface HeliusDASResponse {
+  jsonrpc: string
+  result?: {
+    items: HeliusDASAsset[]
+    total: number
+    limit: number
+    page: number
+    cursor?: string
+  }
+  error?: {
+    code: number
+    message: string
+  }
+  id: string
+}
+
+interface HeliusBalancesResponse {
+  tokens: Array<{
+    mint: string
+    amount: number
+    decimals: number
+    tokenAccount: string
+  }>
+  nativeBalance: number
+}
+
+/**
+ * Helius provider configuration
+ */
+export interface HeliusProviderConfig extends ProviderConfig {
+  /** Helius API key (required) */
+  apiKey: string
+  /** Solana cluster (default: mainnet-beta) */
+  cluster?: 'mainnet-beta' | 'devnet'
+}
+
+/**
+ * Helius RPC Provider implementation
+ *
+ * Uses Helius DAS API for efficient token queries.
+ * Recommended for production deployments.
+ */
+export class HeliusProvider implements SolanaRPCProvider {
+  readonly name = 'helius'
+  private apiKey: string
+  private cluster: 'mainnet-beta' | 'devnet'
+  private rpcUrl: string
+  private restUrl: string
+
+  constructor(config: HeliusProviderConfig) {
+    if (!config.apiKey) {
+      throw new Error('Helius API key is required. Get one at https://dev.helius.xyz')
+    }
+
+    this.apiKey = config.apiKey
+    this.cluster = config.cluster ?? 'mainnet-beta'
+
+    // RPC endpoint for DAS API
+    this.rpcUrl = this.cluster === 'devnet'
+      ? `https://devnet.helius-rpc.com/?api-key=${this.apiKey}`
+      : `https://mainnet.helius-rpc.com/?api-key=${this.apiKey}`
+
+    // REST endpoint for balances API
+    this.restUrl = this.cluster === 'devnet'
+      ? `https://api-devnet.helius.xyz/v0`
+      : `https://api.helius.xyz/v0`
+  }
+
+  /**
+   * Get all token assets owned by an address using DAS API
+   *
+   * Uses getAssetsByOwner for comprehensive asset information including
+   * NFTs and fungible tokens with metadata.
+   */
+  async getAssetsByOwner(owner: string): Promise<TokenAsset[]> {
+    const assets: TokenAsset[] = []
+    let page = 1
+    const limit = 1000
+    let hasMore = true
+
+    while (hasMore) {
+      const response = await fetch(this.rpcUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: `sip-${Date.now()}`,
+          method: 'getAssetsByOwner',
+          params: {
+            ownerAddress: owner,
+            page,
+            limit,
+            displayOptions: {
+              showFungible: true,
+              showNativeBalance: false,
+            },
+          },
+        }),
+      })
+
+      if (!response.ok) {
+        throw new Error(`Helius API error: ${response.status} ${response.statusText}`)
+      }
+
+      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})`)
+      }
+
+      if (data.result?.items) {
+        for (const item of data.result.items) {
+          // Skip NFTs (interface !== 'FungibleToken' and 'FungibleAsset')
+          if (item.interface !== 'FungibleToken' && item.interface !== 'FungibleAsset') {
+            continue
+          }
+
+          // Extract token info
+          const tokenInfo = item.token_info
+          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))
+
+          assets.push({
+            mint: item.id,
+            amount: balanceValue,
+            decimals: tokenInfo.decimals ?? 0,
+            symbol: tokenInfo.symbol ?? item.content?.metadata?.symbol,
+            name: item.content?.metadata?.name,
+            logoUri: item.content?.links?.image,
+          })
+        }
+      }
+
+      // Check if there are more pages
+      hasMore = data.result?.items?.length === limit
+      page++
+
+      // Safety limit to prevent infinite loops
+      if (page > 100) {
+        console.warn('[HeliusProvider] Reached page limit (100), stopping pagination')
+        break
+      }
+    }
+
+    return assets
+  }
+
+  /**
+   * Get token balance for a specific mint using Balances API
+   *
+   * 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}`
+
+      const response = await fetch(url)
+
+      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
+      }
+
+      const data = (await response.json()) as HeliusBalancesResponse
+
+      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
+    }
+  }
+
+  /**
+   * Check if provider supports real-time subscriptions
+   *
+   * Helius supports webhooks for real-time notifications,
+   * but that requires server-side setup. Client-side subscriptions
+   * are not directly supported.
+   */
+  supportsSubscriptions(): boolean {
+    // Helius has webhooks but not client-side subscriptions
+    // Return false for now, can be enhanced with webhook integration later
+    return false
+  }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Solana RPC Providers
+ *
+ * SIP is RPC-provider-agnostic — developers choose their preferred provider.
+ *
+ * @example
+ * ```typescript
+ * import { createProvider, scanForPayments } from '@sip-protocol/sdk'
+ *
+ * // Helius — efficient DAS queries (recommended for production)
+ * const helius = createProvider('helius', {
+ *   apiKey: process.env.HELIUS_API_KEY!
+ * })
+ *
+ * // Generic — standard RPC, no API key needed
+ * const generic = createProvider('generic', {
+ *   endpoint: 'https://api.devnet.solana.com'
+ * })
+ *
+ * // Same API, different backends
+ * const payments = await scanForPayments({
+ *   provider: helius,
+ *   viewingPrivateKey,
+ *   spendingPublicKey,
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Interface and factory
+export {
+  createProvider,
+  type SolanaRPCProvider,
+  type TokenAsset,
+  type ProviderConfig,
+  type ProviderType,
+  type GenericProviderConfig,
+} from './interface'
+
+// Provider implementations
+export { HeliusProvider, type HeliusProviderConfig } from './helius'
+export { GenericProvider } from './generic'
+
+// Webhook handler for real-time scanning
+export {
+  createWebhookHandler,
+  processWebhookTransaction,
+  type HeliusWebhookTransaction,
+  type HeliusEnhancedTransaction,
+  type HeliusWebhookPayload,
+  type WebhookHandlerConfig,
+  type WebhookProcessResult,
+} from './webhook'

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

@@ -0,0 +1,178 @@
+/**
+ * Solana RPC Provider Interface
+ *
+ * SIP is RPC-provider-agnostic — developers choose their preferred provider.
+ * Each provider has unique moats we leverage through this unified interface.
+ *
+ * @example
+ * ```typescript
+ * import { createProvider, scanForPayments } from '@sip-protocol/sdk'
+ *
+ * // Helius — efficient DAS queries (recommended for production)
+ * const helius = createProvider('helius', { apiKey: process.env.HELIUS_API_KEY })
+ *
+ * // Generic — standard RPC, no API key needed
+ * const generic = createProvider('generic', { connection })
+ *
+ * // Same API, different backends
+ * const payments = await scanForPayments({
+ *   provider: helius,
+ *   viewingPrivateKey,
+ *   spendingPublicKey,
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { HeliusProvider, type HeliusProviderConfig } from './helius'
+import { GenericProvider } from './generic'
+
+/**
+ * Token asset information returned by providers
+ */
+export interface TokenAsset {
+  /** SPL token mint address */
+  mint: string
+  /** Token amount in smallest units */
+  amount: bigint
+  /** Token decimals */
+  decimals: number
+  /** Token symbol (e.g., 'USDC') */
+  symbol?: string
+  /** Token name (e.g., 'USD Coin') */
+  name?: string
+  /** Token logo URI */
+  logoUri?: string
+}
+
+/**
+ * Configuration for RPC providers
+ */
+export interface ProviderConfig {
+  /** API key for premium providers (Helius, QuickNode) */
+  apiKey?: string
+  /** Custom RPC endpoint */
+  endpoint?: string
+  /** Solana cluster */
+  cluster?: 'mainnet-beta' | 'devnet' | 'testnet'
+}
+
+/**
+ * Unified interface for Solana RPC providers
+ *
+ * All provider adapters must implement this interface to ensure
+ * consistent behavior across different RPC backends.
+ */
+export interface SolanaRPCProvider {
+  /** Provider name for logging/debugging */
+  readonly name: string
+
+  /**
+   * Get all token assets owned by an address
+   *
+   * @param owner - Solana address (base58)
+   * @returns Array of token assets with balances
+   */
+  getAssetsByOwner(owner: string): Promise<TokenAsset[]>
+
+  /**
+   * Get token balance for a specific mint
+   *
+   * @param owner - Solana address (base58)
+   * @param mint - SPL token mint address (base58)
+   * @returns Token balance in smallest units, 0n if no balance
+   */
+  getTokenBalance(owner: string, mint: string): Promise<bigint>
+
+  /**
+   * Check if provider supports real-time subscriptions
+   *
+   * @returns true if subscribeToTransfers is available
+   */
+  supportsSubscriptions(): boolean
+
+  /**
+   * Subscribe to token transfers for an address (optional)
+   *
+   * Only available if supportsSubscriptions() returns true.
+   *
+   * @param address - Solana address to watch
+   * @param callback - Called when a transfer is detected
+   * @returns Unsubscribe function
+   */
+  subscribeToTransfers?(
+    address: string,
+    callback: (asset: TokenAsset) => void
+  ): Promise<() => void>
+}
+
+/**
+ * Provider type for factory function
+ */
+export type ProviderType = 'helius' | 'quicknode' | 'triton' | 'generic'
+
+/**
+ * Extended config for generic provider that accepts a Connection
+ */
+export interface GenericProviderConfig extends ProviderConfig {
+  /** Existing Solana Connection object */
+  connection?: unknown // Typed as unknown to avoid @solana/web3.js dependency in interface
+}
+
+/**
+ * Create an RPC provider instance
+ *
+ * @param type - Provider type ('helius', 'quicknode', 'triton', 'generic')
+ * @param config - Provider configuration
+ * @returns Configured provider instance
+ *
+ * @example
+ * ```typescript
+ * // Helius with API key
+ * const helius = createProvider('helius', {
+ *   apiKey: process.env.HELIUS_API_KEY,
+ *   cluster: 'devnet'
+ * })
+ *
+ * // Generic with existing connection
+ * const generic = createProvider('generic', { connection })
+ *
+ * // Generic with endpoint
+ * const devnet = createProvider('generic', {
+ *   endpoint: 'https://api.devnet.solana.com'
+ * })
+ * ```
+ */
+export function createProvider(
+  type: 'helius',
+  config: ProviderConfig & { apiKey: string }
+): SolanaRPCProvider
+export function createProvider(
+  type: 'generic',
+  config: GenericProviderConfig
+): SolanaRPCProvider
+export function createProvider(
+  type: ProviderType,
+  config: ProviderConfig | GenericProviderConfig
+): SolanaRPCProvider
+export function createProvider(
+  type: ProviderType,
+  config: ProviderConfig | GenericProviderConfig
+): SolanaRPCProvider {
+  switch (type) {
+    case 'helius':
+      return new HeliusProvider(config as HeliusProviderConfig)
+    case 'generic':
+      return new GenericProvider(config as GenericProviderConfig)
+    case 'quicknode':
+    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'}`
+      )
+    default:
+      throw new Error(`Unknown provider type: ${type}`)
+  }
+}