Pool Data Structures Reference

Complete reference for all DLMM pool data structures, interfaces, and type definitions returned by the Saros SDK

Complete reference documentation for all data structures returned by the DLMM SDK when working with pool data composition and analysis.

Core Pool Data Types

ComposedPoolData

The main data structure containing complete pool information:

interface ComposedPoolData {
  pool: PoolInfo;
  state: PoolState;
  liquidity: LiquidityDistribution;
  pricing: PricingData;
  timestamp: number;
}

Fields:

• pool: Static pool configuration and token information
• state: Current pool state including active bin and reserves
• liquidity: Liquidity distribution across bins with analytics
• pricing: Real-time pricing and quote information
• timestamp: Unix timestamp when data was composed

PoolInfo

Static pool configuration that rarely changes:

interface PoolInfo {
  address: string;
  tokenX: TokenInfo;
  tokenY: TokenInfo;
  binStep: number;
  baseFactor: number;
}

Fields:

• address: Pool’s public key as string
• tokenX: Information about the first token in the pair
• tokenY: Information about the second token in the pair
• binStep: Price step between bins (basis points)
• baseFactor: Base factor for bin calculations

TokenInfo

Token metadata and configuration:

interface TokenInfo {
  mint: string;
  symbol: string;
  decimals: number;
  name?: string;
  logoURI?: string;
  coingeckoId?: string;
}

Fields:

• mint: Token mint address as string
• symbol: Token symbol (e.g., “USDC”, “SOL”)
• decimals: Number of decimal places for the token
• name: Full token name (optional)
• logoURI: URL to token logo image (optional)
• coingeckoId: CoinGecko API identifier (optional)

PoolState

Current pool state with calculated values:

interface PoolState {
  activeId: number;
  currentPrice: number;
  reserveX: number;
  reserveY: number;
  totalLiquidity: number;
  protocolFeeX?: number;
  protocolFeeY?: number;
  lastUpdatedSlot?: number;
}

Fields:

• activeId: ID of the currently active bin
• currentPrice: Current exchange rate (tokenY/tokenX)
• reserveX: Amount of tokenX in the pool (human-readable)
• reserveY: Amount of tokenY in the pool (human-readable)
• totalLiquidity: Total liquidity supply across all bins
• protocolFeeX: Accumulated protocol fees in tokenX (optional)
• protocolFeeY: Accumulated protocol fees in tokenY (optional)
• lastUpdatedSlot: Solana slot when pool was last updated (optional)

Liquidity Distribution Types

LiquidityDistribution

Comprehensive liquidity analysis across all bins:

interface LiquidityDistribution {
  distribution: BinLiquidityData[];
  activeBins: number;
  concentrationRatio: number;
  totalValueLocked: number;
  liquidityRange: {
    min: number;
    max: number;
  };
  utilizationRate: number;
}

Fields:

• distribution: Array of individual bin data
• activeBins: Number of bins with liquidity > 0
• concentrationRatio: Ratio of liquidity in top 20% of bins
• totalValueLocked: Total USD value locked in the pool
• liquidityRange: Price range containing liquidity
• utilizationRate: Percentage of total bins with liquidity

BinLiquidityData

Individual bin information with calculated metrics:

interface BinLiquidityData {
  binId: number;
  price: number;
  liquidityAmount: number;
  reserveX: number;
  reserveY: number;
  feeX: number;
  feeY: number;
  utilization: number;
  isActive?: boolean;
  priceRange?: {
    lower: number;
    upper: number;
  };
}

Fields:

• binId: Unique identifier for this bin
• price: Price at this bin level (tokenY/tokenX)
• liquidityAmount: Total liquidity in this bin
• reserveX: Amount of tokenX in this bin (human-readable)
• reserveY: Amount of tokenY in this bin (human-readable)
• feeX: Accumulated fees in tokenX
• feeY: Accumulated fees in tokenY
• utilization: Bin utilization factor (0-1)
• isActive: Whether this is the currently active bin (optional)
• priceRange: Price boundaries for this bin (optional)

Pricing and Quote Types

PricingData

Real-time pricing information and market impact data:

interface PricingData {
  currentRate: number;
  priceImpact: number;
  tradingFees: number;
  spreadBps?: number;
  lastTradePrice?: number;
  volume24h?: number;
}

Fields:

• currentRate: Current exchange rate (tokenY/tokenX)
• priceImpact: Price impact for reference trade size (percentage)
• tradingFees: Current trading fee rate (percentage)
• spreadBps: Bid-ask spread in basis points (optional)
• lastTradePrice: Price of the last executed trade (optional)
• volume24h: 24-hour trading volume in USD (optional)

SwapQuoteData

Quote information for potential swaps:

interface SwapQuoteData {
  fromAmount: string;
  toAmount: string;
  priceImpact: number;
  fee: number;
  route: string[];
  estimatedGas: number;
  minAmountOut: string;
  slippage: number;
}

Fields:

• fromAmount: Input amount (human-readable string)
• toAmount: Expected output amount (human-readable string)
• priceImpact: Price impact of this trade (percentage)
• fee: Trading fee for this swap (in input token)
• route: Token symbols showing swap route
• estimatedGas: Estimated gas cost in lamports
• minAmountOut: Minimum output with slippage (human-readable string)
• slippage: Slippage tolerance used (percentage)

Position and User Data Types

UserPosition

Individual liquidity position data:

interface UserPosition {
  address: string;
  owner: string;
  pool: string;
  lowerBinId: number;
  upperBinId: number;
  liquidityX: number;
  liquidityY: number;
  feeEarnedX: number;
  feeEarnedY: number;
  createdAt: Date;
  lastUpdated: Date;
  isInRange: boolean;
}

Fields:

• address: Position account address
• owner: Owner’s wallet address
• pool: Pool address this position belongs to
• lowerBinId: Lower bound of position range
• upperBinId: Upper bound of position range
• liquidityX: Current liquidity in tokenX
• liquidityY: Current liquidity in tokenY
• feeEarnedX: Accumulated fees in tokenX
• feeEarnedY: Accumulated fees in tokenY
• createdAt: Position creation timestamp
• lastUpdated: Last position update timestamp
• isInRange: Whether position is within active trading range

PositionMetrics

Calculated performance metrics for a position:

interface PositionMetrics {
  position: UserPosition;
  value: {
    current: number;
    original: number;
    change: number;
    changePercent: number;
  };
  fees: {
    totalEarned: number;
    apy: number;
    dailyRate: number;
  };
  performance: {
    impermanentLoss: number;
    impermanentLossPercent: number;
    totalReturn: number;
    totalReturnPercent: number;
  };
  risk: {
    concentrationRisk: number;
    utilizationRate: number;
    volatilityExposure: number;
  };
}

Fields:

• position: Base position information
• value: Current vs original value analysis
• fees: Fee earnings and yield calculations
• performance: Return metrics including impermanent loss
• risk: Risk assessment metrics

Utility and Helper Types

CacheEntry

Data structure for caching pool information:

interface CacheEntry<T> {
  data: T;
  timestamp: number;
  ttl: number;
  hits: number;
}

Fields:

• data: The cached data of type T
• timestamp: When the data was cached (Unix timestamp)
• ttl: Time-to-live in milliseconds
• hits: Number of cache hits for this entry

ErrorResponse

Standard error response structure:

interface ErrorResponse {
  code: string;
  message: string;
  context?: {
    pool?: string;
    method?: string;
    params?: any;
  };
  timestamp: number;
}

Fields:

• code: Error code identifier
• message: Human-readable error message
• context: Additional error context (optional)
• timestamp: When the error occurred

BatchOperation

Structure for batch data operations:

interface BatchOperation<T> {
  operation: 'fetch' | 'update' | 'delete';
  target: string;
  data?: T;
  options?: {
    priority?: 'high' | 'medium' | 'low';
    timeout?: number;
    retries?: number;
  };
}

Fields:

• operation: Type of operation to perform
• target: Target identifier (e.g., pool address)
• data: Data for the operation (optional)
• options: Operation configuration (optional)

SDK Response Wrappers

ApiResponse

Standard wrapper for all SDK responses:

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: ErrorResponse;
  metadata: {
    timestamp: number;
    requestId: string;
    cached: boolean;
    executionTime: number;
  };
}

Fields:

• success: Whether the operation succeeded
• data: Response data when successful (optional)
• error: Error information when failed (optional)
• metadata: Request metadata and performance info

PaginatedResponse

Response structure for paginated data:

interface PaginatedResponse<T> {
  items: T[];
  pagination: {
    page: number;
    pageSize: number;
    totalItems: number;
    totalPages: number;
    hasNext: boolean;
    hasPrevious: boolean;
  };
}

Fields:

• items: Array of items for current page
• pagination: Pagination metadata and navigation info

Type Guards and Validators

Type Guard Functions

Use these functions to validate data types at runtime:

function isComposedPoolData(obj: any): obj is ComposedPoolData {
  return obj && 
         typeof obj.pool === 'object' &&
         typeof obj.state === 'object' &&
         typeof obj.liquidity === 'object' &&
         typeof obj.pricing === 'object' &&
         typeof obj.timestamp === 'number';
}

function isBinLiquidityData(obj: any): obj is BinLiquidityData {
  return obj &&
         typeof obj.binId === 'number' &&
         typeof obj.price === 'number' &&
         typeof obj.liquidityAmount === 'number';
}

function isUserPosition(obj: any): obj is UserPosition {
  return obj &&
         typeof obj.address === 'string' &&
         typeof obj.owner === 'string' &&
         typeof obj.lowerBinId === 'number' &&
         typeof obj.upperBinId === 'number';
}

Enum Types

PoolStatus

Pool operational status:

enum PoolStatus {
  ACTIVE = 'active',
  PAUSED = 'paused',
  CLOSED = 'closed',
  MIGRATING = 'migrating'
}

CacheCategory

Cache categorization for different TTL strategies:

enum CacheCategory {
  METADATA = 'metadata',
  STATE = 'state', 
  BINS = 'bins',
  QUOTES = 'quotes',
  POSITIONS = 'positions'
}

ErrorCode

Standard error codes:

enum ErrorCode {
  POOL_NOT_FOUND = 'POOL_NOT_FOUND',
  INVALID_POOL_ADDRESS = 'INVALID_POOL_ADDRESS',
  RPC_CONNECTION_FAILED = 'RPC_CONNECTION_FAILED',
  INSUFFICIENT_LIQUIDITY = 'INSUFFICIENT_LIQUIDITY',
  QUOTE_CALCULATION_FAILED = 'QUOTE_CALCULATION_FAILED',
  POSITION_NOT_FOUND = 'POSITION_NOT_FOUND',
  CACHE_MISS = 'CACHE_MISS',
  RATE_LIMITED = 'RATE_LIMITED'
}

Constants and Default Values

Default Configuration

Standard default values used throughout the SDK:

const DEFAULT_CONFIG = {
  CACHE_TTL: {
    METADATA: 300000,  // 5 minutes
    STATE: 30000,      // 30 seconds
    BINS: 60000,       // 1 minute
    QUOTES: 10000,     // 10 seconds
    POSITIONS: 120000  // 2 minutes
  },
  BATCH_SIZE: {
    POOLS: 10,
    BINS: 50,
    POSITIONS: 100
  },
  TIMEOUT: {
    RPC_CALL: 10000,   // 10 seconds
    BATCH_OPERATION: 30000, // 30 seconds
    QUOTE_CALCULATION: 5000  // 5 seconds
  },
  RETRY: {
    MAX_ATTEMPTS: 3,
    BACKOFF_MS: 1000
  }
} as const;

Numeric Constants

Mathematical constants used in calculations:

const NUMERIC_CONSTANTS = {
  BASIS_POINTS: 10000,
  SECONDS_PER_YEAR: 31536000,
  LAMPORTS_PER_SOL: 1000000000,
  BIN_ID_OFFSET: 8388608,
  MAX_BIN_STEP: 10000,
  MIN_BIN_STEP: 1
} as const;

This reference covers all data structures returned by the DLMM SDK. Use these type definitions to ensure type safety and proper data handling in your applications.