@steerprotocol/sdk 1.27.0 → 1.28.0

package/src/base/PoolClient.ts

@@ -0,0 +1,678 @@
+import type { PublicClient, WalletClient } from 'viem';
+import { PoolData, SteerResponse } from '../types.js';
+import { SubgraphClient } from './SubgraphClient.js';
+import { 
+  Protocol, 
+  Chain
+} from '../const/chain.js';
+import { 
+  chainIdToName, 
+  getProtocolSubgraphURL
+} from '../const/index.js';
+import { isAlgebraProtocol } from '../const/protocol.js';
+import { getTopPoolsQuery, getTokenPoolsQueryByAddress, getPoolDetailsQuery } from '../utils/PoolQueryAdapter.js';
+
+/**
+ * GraphQL token data interface representing token information from subgraph responses
+ * @interface GraphQLTokenData
+ */
+export interface GraphQLTokenData {
+  /** Token symbol (e.g., "ETH", "USDC") */
+  symbol: string;
+  /** Token contract address */
+  id: string;
+  /** Number of decimal places for the token */
+  decimals: string;
+  /** Human-readable token name */
+  name: string;
+}
+
+/**
+ * GraphQL pool data interface representing pool information from subgraph responses
+ * @interface GraphQLPoolData
+ */
+export interface GraphQLPoolData {
+  /** Pool contract address */
+  id: string;
+  /** First token in the pool */
+  token0: GraphQLTokenData;
+  /** Second token in the pool */
+  token1: GraphQLTokenData;
+  /** 24-hour trading volume in USD */
+  volumeUSD: string;
+  /** Current tick of the pool */
+  tick: string;
+  /** Total liquidity in the pool */
+  liquidity: string;
+  /** Fee tier for the pool (optional) */
+  feeTier?: string;
+  /** 24-hour volume of token0 (optional) */
+  volumeToken0?: string;
+  /** 24-hour volume of token1 (optional) */
+  volumeToken1?: string;
+  /** Total value locked in ETH (optional) */
+  totalValueLockedETH?: string;
+  /** Alternative field name for volume USD (optional) */
+  volumeUsd?: string;
+  /** Alternative field name for TVL in ETH (optional) */
+  totalValueLockedEth?: string;
+}
+
+/**
+ * Filter criteria for querying pools
+ * @interface PoolFilter
+ */
+export interface PoolFilter {
+  /** Chain ID to filter pools by */
+  chainId?: number;
+  /** Protocol to filter pools by */
+  protocol?: Protocol;
+  /** Minimum volume in USD to filter pools */
+  minVolumeUSD?: number;
+  /** Token address to find pools containing this token */
+  tokenAddress?: string;
+  /** Maximum number of pools to return */
+  limit?: number;
+}
+
+// GraphQL response interfaces (currently unused but kept for future use)
+// interface GraphQLResponse<T> {
+//   data: T;
+//   errors?: Array<{ message: string }>;
+// }
+
+/**
+ * Response interface for top pools query
+ * @interface TopPoolsResponse
+ * @internal
+ */
+interface TopPoolsResponse {
+  /** Standard pools array */
+  pools: GraphQLPoolData[];
+  /** Limit pools array (used by some protocols) */
+  limitPools?: GraphQLPoolData[];
+  /** CL pools array (used by some protocols) */
+  clPools?: GraphQLPoolData[];
+}
+
+/**
+ * Response interface for pool details query
+ * @interface PoolDetailsResponse
+ * @internal
+ */
+interface PoolDetailsResponse {
+  /** Single pool data */
+  pool: GraphQLPoolData;
+  /** Single limit pool data (used by some protocols) */
+  limitPool?: GraphQLPoolData;
+  /** Single CL pool data (used by some protocols) */
+  clPool?: GraphQLPoolData;
+}
+
+/**
+ * Response interface for pools by token query
+ * @interface PoolsByTokenResponse
+ * @internal
+ */
+interface PoolsByTokenResponse {
+  /** Standard pools array */
+  pools?: GraphQLPoolData[];
+  /** Limit pools array (used by some protocols) */
+  limitPools?: GraphQLPoolData[];
+  /** Token pools array (used by some protocols) */
+  tokenPools?: GraphQLPoolData[];
+  /** CL pools array (used by some protocols) */
+  clPools?: GraphQLPoolData[];
+}
+
+/**
+ * Client for fetching pool data from various DEX protocol subgraphs
+ * 
+ * @example
+ * ```typescript
+ * import { createPublicClient, createWalletClient, http } from 'viem';
+ * import { mainnet } from 'viem/chains';
+ * import { PoolClient } from '@steerprotocol/sdk';
+ * 
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http()
+ * }) as PublicClient & WalletClient;
+ * 
+ * const poolClient = new PoolClient(client, 'your-subgraph-studio-key');
+ * 
+ * // Fetch top pools
+ * const topPools = await poolClient.getTopPools(100, Protocol.UniswapV3, 1);
+ * ```
+ * 
+ * @extends SubgraphClient
+ * @group Pool
+ */
+export class PoolClient extends SubgraphClient {
+  /** Public client for blockchain interactions */
+  protected readonly publicClient: PublicClient;
+  /** Default timeout for GraphQL queries in milliseconds */
+  private readonly defaultTimeout: number = 60000;
+  /** Counter for tracking API call metrics */
+  private apiCallCount: number = 0;
+  /** Subgraph Studio API key for rate limiting */
+  private readonly subgraphStudioKey: string;
+
+  /**
+   * Creates a new PoolClient instance
+   * 
+   * @param client - Combined public and wallet client for blockchain interactions
+   * @param subgraphStudioKey - Optional Subgraph Studio API key for higher rate limits
+   * 
+   * @example
+   * ```typescript
+   * const poolClient = new PoolClient(client, 'your-api-key');
+   * ```
+   */
+  constructor(
+    client: PublicClient & WalletClient,
+    subgraphStudioKey: string = ''
+  ) {
+    super(client);
+    this.publicClient = client;
+    this.subgraphStudioKey = subgraphStudioKey;
+  }
+
+  /**
+   * Resets the API call counter for metrics tracking
+   * 
+   * @example
+   * ```typescript
+   * poolClient.resetMetrics();
+   * ```
+   */
+  public resetMetrics(): void {
+    this.apiCallCount = 0;
+  }
+
+  /**
+   * Gets current metrics for monitoring API usage
+   * 
+   * @returns Object containing current metrics
+   * 
+   * @example
+   * ```typescript
+   * const metrics = poolClient.getMetrics();
+   * console.log(`API calls made: ${metrics.apiCallCount}`);
+   * ```
+   */
+  public getMetrics(): { apiCallCount: number } {
+    return {
+      apiCallCount: this.apiCallCount,
+    };
+  }
+
+  /**
+   * Fetches data from GraphQL endpoint with retry logic for rate limits
+   * 
+   * @param query - GraphQL query string
+   * @param variables - Variables for the GraphQL query
+   * @param protocol - Protocol to query
+   * @param chainId - Chain ID to query
+   * @returns Promise containing the response data
+   * 
+   * @throws {Error} When subgraph endpoint is not available
+   * @throws {Error} When rate limit is exceeded after max retries
+   * @throws {Error} When GraphQL query times out
+   * 
+   * @internal
+   */
+  private async fetchFromGraph<T>(
+    query: string,
+    variables: Record<string, unknown>,
+    protocol: Protocol,
+    chainId: number
+  ): Promise<SteerResponse<T>> {
+    try {
+      const chainName = chainIdToName(chainId);
+      const endpoint = getProtocolSubgraphURL(protocol, chainName as Chain, this.subgraphStudioKey);
+
+      if (!endpoint) {
+        throw new Error(`No subgraph endpoint available for protocol ${protocol} on chain ${chainName}`);
+      }
+
+      const MAX_RETRIES = 3;
+      const RETRY_DELAY_MS = 11000;
+
+      const fetchWithRetry = async (retries = 0): Promise<T> => {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ query, variables }),
+        });
+
+        const data = await response.json() as { data: T; error?: string; errors?: Array<{ message: string }> };
+
+        if (data.error && typeof data.error === "string" && data.error.includes("surpassed your query allowance")) {
+          if (retries < MAX_RETRIES) {
+            console.warn(`Rate limit hit for ${endpoint}, retrying in ${RETRY_DELAY_MS / 1000}s (attempt ${retries + 1})`);
+            await new Promise(res => setTimeout(res, RETRY_DELAY_MS));
+            return fetchWithRetry(retries + 1);
+          } else {
+            throw new Error(`Rate limit exceeded after ${MAX_RETRIES} retries: ${data.error}`);
+          }
+        }
+
+        if (data.error) {
+          throw new Error(`GraphQL endpoint error: ${data.error}`);
+        }
+
+        if (data.errors) {
+          throw new Error(`GraphQL errors: ${JSON.stringify(data.errors)}`);
+        }
+
+        return data.data;
+      };
+
+      this.apiCallCount++;
+      console.log("Total API calls:", this.apiCallCount);
+
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(
+          () => reject(new Error("GraphQL query timeout")),
+          this.defaultTimeout
+        );
+      });
+
+      const data = await Promise.race([fetchWithRetry(), timeoutPromise]);
+
+      return {
+        data: data as T,
+        status: 200,
+        success: true,
+      };
+    } catch (error) {
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred',
+      };
+    }
+  }
+
+  /**
+   * Fetches the top pools for a specific protocol by trading volume
+   * 
+   * @param count - Number of pools to fetch (default: 500)
+   * @param protocol - Protocol to fetch pools from
+   * @param chainId - Chain ID to fetch pools from
+   * @returns Promise containing an array of top pools
+   * 
+   * @example
+   * ```typescript
+   * // Get top 100 Uniswap V3 pools on Ethereum
+   * const topPools = await poolClient.getTopPools(100, Protocol.UniswapV3, 1);
+   * if (topPools.success) {
+   *   console.log(`Found ${topPools.data.length} pools`);
+   * }
+   * ```
+   * 
+   * @throws {Error} When failed to fetch pools from subgraph
+   */
+  public async getTopPools(
+    count: number = 500,
+    protocol: Protocol,
+    chainId: number
+  ): Promise<SteerResponse<GraphQLPoolData[]>> {
+    try {
+      const isAlgebraPool = isAlgebraProtocol(protocol);
+      const query = getTopPoolsQuery(protocol, isAlgebraPool);
+
+      console.log(`[Chain ${chainId}] [Protocol ${protocol}] 📊 Fetching top ${count} pools from the subgraph...`);
+
+      const response = await this.fetchFromGraph<TopPoolsResponse>(
+        query,
+        { limit: count },
+        protocol,
+        chainId
+      );
+
+      if (!response.success || !response.data) {
+        throw new Error(response.error || 'Failed to fetch pools');
+      }
+
+      const pools = response.data.pools || response.data.limitPools || response.data.clPools || [];
+      
+      console.log(`[Chain ${chainId}] [Protocol ${protocol}] ✅ Received ${pools.length} pools from the subgraph`);
+
+      // Filter out pools with invalid volumeUSD
+      const validPools = pools.filter(pool => {
+        const volumeUSD = parseFloat(pool.volumeUSD || pool.volumeUsd || "0");
+        return !isNaN(volumeUSD) && volumeUSD > 0;
+      });
+
+      console.log(`[Chain ${chainId}] [Protocol ${protocol}] ✅ Found ${validPools.length} valid pools with positive volumeUSD`);
+
+      return {
+        data: validPools,
+        status: 200,
+        success: true,
+      };
+    } catch (error) {
+      console.error(`[Chain ${chainId}] [Protocol ${protocol}] Error in getTopPools:`, error);
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred',
+      };
+    }
+  }
+
+  /**
+   * Fetches detailed information for a specific pool by its ID
+   * 
+   * @param poolId - Pool contract address to fetch
+   * @param protocol - Protocol the pool belongs to
+   * @param chainId - Chain ID where the pool exists
+   * @returns Promise containing pool details or null if not found
+   * 
+   * @example
+   * ```typescript
+   * // Get specific pool details
+   * const poolDetails = await poolClient.getPoolById(
+   *   '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
+   *   Protocol.UniswapV3,
+   *   1
+   * );
+   * if (poolDetails.success && poolDetails.data) {
+   *   console.log(`Pool: ${poolDetails.data.token0.symbol}/${poolDetails.data.token1.symbol}`);
+   * }
+   * ```
+   * 
+   * @throws {Error} When failed to fetch pool from subgraph
+   */
+  public async getPoolById(
+    poolId: string,
+    protocol: Protocol,
+    chainId: number
+  ): Promise<SteerResponse<GraphQLPoolData | null>> {
+    try {
+
+      const isAlgebraPool = isAlgebraProtocol(protocol);
+      const query = getPoolDetailsQuery(isAlgebraPool, protocol);
+
+    
+      const response = await this.fetchFromGraph<PoolDetailsResponse>(
+        query,
+        { pool: poolId },
+        protocol,
+        chainId
+      );
+
+      if (!response.success || !response.data) {
+        throw new Error(response.error || 'Failed to fetch pool');
+      }
+
+      const pool = response.data.pool || response.data.clPool || response.data.limitPool || null;
+
+
+      return {
+        data: pool,
+        status: 200,
+        success: true,
+      };
+    } catch (error) {
+      console.error(`Error fetching pool ${poolId}:`, error);
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred',
+      };
+    }
+  }
+
+  /**
+   * Fetches pools containing multiple tokens in batches for better performance
+   * 
+   * @param tokenAddresses - Array of token contract addresses
+   * @param protocol - Protocol to fetch pools from
+   * @param chainId - Chain ID to fetch pools from
+   * @param batchSize - Number of tokens to process in each batch (default: 10)
+   * @returns Promise containing all pools found for the tokens
+   * 
+   * @example
+   * ```typescript
+   * // Get pools for multiple tokens
+   * const tokenAddresses = [
+   *   '0xa0b86a33e6f8b07b71c3a39ef77a6b6e8f1b7b7e', // USDC
+   *   '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'  // WETH
+   * ];
+   * const pools = await poolClient.fetchPoolsForTokensBatch(
+   *   tokenAddresses,
+   *   Protocol.UniswapV3,
+   *   1,
+   *   5
+   * );
+   * ```
+   * 
+   * @throws {Error} When batch processing fails
+   */
+  public async fetchPoolsForTokensBatch(
+    tokenAddresses: string[],
+    protocol: Protocol,
+    chainId: number,
+    batchSize: number = 10
+  ): Promise<SteerResponse<GraphQLPoolData[]>> {
+    try {
+      if (tokenAddresses.length === 0) {
+        return {
+          data: [],
+          status: 200,
+          success: true,
+        };
+      }
+
+      console.log(`\n🔍 Batch Pool Fetch Summary:`);
+      console.log(`📥 Total tokens to process: ${tokenAddresses.length}`);
+
+      const isAlgebraPool = isAlgebraProtocol(protocol);
+      const normalizedAddresses = tokenAddresses.map(addr => addr.toLowerCase());
+
+      // Split into chunks
+      const chunkSize = batchSize;
+      const addressChunks = [];
+      for (let i = 0; i < normalizedAddresses.length; i += chunkSize) {
+        addressChunks.push(normalizedAddresses.slice(i, i + chunkSize));
+      }
+
+      console.log(`📦 Processing ${addressChunks.length} chunks of max ${chunkSize} tokens each`);
+
+      const allPools: GraphQLPoolData[] = [];
+
+      // Process chunks in parallel
+      const results = await Promise.all(
+        addressChunks.map(async (chunk, chunkIndex) => {
+          console.log(`\n🔄 Processing chunk ${chunkIndex + 1}/${addressChunks.length} with ${chunk.length} tokens`);
+
+          const chunkResults = await Promise.all(
+            chunk.map(async (token) => {
+              try {
+                const query = getTokenPoolsQueryByAddress(isAlgebraPool, protocol);
+                const queryStartTime = performance.now();
+                
+                const response = await this.fetchFromGraph<PoolsByTokenResponse>(
+                  query,
+                  { token },
+                  protocol,
+                  chainId
+                );
+
+                const queryTime = performance.now() - queryStartTime;
+                console.log(`⏱️ GraphQL query for token ${token.slice(0, 6)}... completed in ${queryTime.toFixed(2)}ms`);
+
+                if (!response.success || !response.data) {
+                  console.error(`❌ No pools found for token: ${token} on chainId: ${chainId}`);
+                  return [];
+                }
+
+                // Extract pools from different possible response structures
+                let pools: GraphQLPoolData[] = [];
+                if (response.data.pools) {
+                  pools = response.data.pools;
+                } else if (response.data.clPools) {
+                  pools = response.data.clPools;
+                } else if (response.data.limitPools) {
+                  pools = response.data.limitPools;
+                } else if (response.data.tokenPools) {
+                  pools = response.data.tokenPools;
+                }
+
+                if (pools.length === 0) {
+                  console.error(`❌ No pools found for token: ${token} on chainId: ${chainId}`);
+                  return [];
+                }
+
+                return pools;
+              } catch (error) {
+                console.error(`❌ Error fetching pools for token: ${token} on chainId: ${chainId}`, error);
+                return [];
+              }
+            })
+          );
+
+          return chunkResults.flat();
+        })
+      );
+
+      // Flatten all results
+      allPools.push(...results.flat());
+
+      return {
+        data: allPools,
+        status: 200,
+        success: true,
+      };
+    } catch (error) {
+      console.error("Error in fetchPoolsForTokensBatch:", error);
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred',
+      };
+    }
+  }
+
+  /**
+   * Fetches all pools containing a specific token
+   * 
+   * @param tokenAddress - Token contract address
+   * @param protocol - Protocol to fetch pools from
+   * @param chainId - Chain ID to fetch pools from
+   * @returns Promise containing pools that include the specified token
+   * 
+   * @example
+   * ```typescript
+   * // Get all USDC pools on Uniswap V3
+   * const usdcPools = await poolClient.fetchPoolsForToken(
+   *   '0xa0b86a33e6f8b07b71c3a39ef77a6b6e8f1b7b7e',
+   *   Protocol.UniswapV3,
+   *   1
+   * );
+   * if (usdcPools.success) {
+   *   console.log(`Found ${usdcPools.data.length} USDC pools`);
+   * }
+   * ```
+   * 
+   * @throws {Error} When failed to fetch pools for token
+   */
+  public async fetchPoolsForToken(
+    tokenAddress: string,
+    protocol: Protocol,
+    chainId: number
+  ): Promise<SteerResponse<GraphQLPoolData[]>> {
+    try {
+      const isAlgebraPool = isAlgebraProtocol(protocol);
+      const query = getTokenPoolsQueryByAddress(isAlgebraPool, protocol);
+
+      const response = await this.fetchFromGraph<PoolsByTokenResponse>(
+        query,
+        { token: tokenAddress.toLowerCase() },
+        protocol,
+        chainId
+      );
+
+      if (!response.success || !response.data) {
+        throw new Error(response.error || 'Failed to fetch pools for token');
+      }
+
+      // Extract pools from different possible response structures
+      let pools: GraphQLPoolData[] = [];
+      if (response.data.pools) {
+        pools = response.data.pools;
+      } else if (response.data.limitPools) {
+        pools = response.data.limitPools;
+      } else if (response.data.tokenPools) {
+        pools = response.data.tokenPools;
+      } else if (response.data.clPools) {
+        pools = response.data.clPools;
+      }
+
+      return {
+        data: pools,
+        status: 200,
+        success: true,
+      };
+    } catch (error) {
+      console.error(`Error fetching pools for token ${tokenAddress}:`, error);
+      return {
+        data: null,
+        status: 500,
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred',
+      };
+    }
+  }
+
+  /**
+   * Filters pools based on validity criteria such as tick range and liquidity
+   * 
+   * @param pools - Array of pools to filter
+   * @returns Array of valid pools that meet the criteria
+   * 
+   * @example
+   * ```typescript
+   * const validPools = poolClient.filterValidPools(allPools);
+   * console.log(`Filtered down to ${validPools.length} valid pools`);
+   * ```
+   */
+  public filterValidPools(pools: PoolData[]): PoolData[] {
+    return pools.filter(pool => {
+      // Check for required fields
+      if (!pool.id || !pool.tick || !pool.liquidity) {
+        return false;
+      }
+
+      // Parse values
+      const tick = parseInt(pool.tick);
+      const liquidity = parseFloat(pool.liquidity);
+
+      // Check for valid tick range and liquidity
+      const TICK_MIN = -887272;
+      const TICK_MAX = 887272;
+      const TICK_EDGE_THRESHOLD = 1;
+
+      if (
+        isNaN(tick) ||
+        isNaN(liquidity) ||
+        liquidity <= 0 ||
+        tick <= TICK_MIN + TICK_EDGE_THRESHOLD ||
+        tick >= TICK_MAX - TICK_EDGE_THRESHOLD
+      ) {
+        return false;
+      }
+
+      return true;
+    });
+  }
+}