@provable-games/ekubo-sdk 0.1.0 → 0.1.9

package/dist/index.d.ts

@@ -1,426 +1,5 @@
-/**
- * Ekubo pool key identifying a unique liquidity pool
- */
-interface PoolKey {
-    token0: string;
-    token1: string;
-    fee: string;
-    tick_spacing: number;
-    extension: string;
-}
-/**
- * A single hop in a swap route through one pool
- */
-interface RouteNode {
-    pool_key: PoolKey;
-    sqrt_ratio_limit: string;
-    skip_ahead: number;
-}
-/**
- * A split in a multi-route swap, representing one path through liquidity pools
- */
-interface SwapSplit {
-    amount_specified: string;
-    route: RouteNode[];
-}
-/**
- * A complete swap quote from the Ekubo API
- */
-interface SwapQuote {
-    /** Price impact as a decimal (e.g., 0.01 = 1%) */
-    impact: number;
-    /** Total amount to send or receive (always positive) */
-    total: bigint;
-    /** Individual route splits for multi-path swaps */
-    splits: SwapSplit[];
-}
-/**
- * Raw API response format (before transformation)
- */
-interface SwapQuoteApiResponse {
-    price_impact: number;
-    total_calculated: string | number;
-    splits: SwapSplit[];
-}
-/**
- * Error response from the Ekubo API
- */
-interface SwapQuoteErrorResponse {
-    error: string;
-}
-
-/**
- * Token information for registry and resolution
- */
-interface TokenInfo {
-    /** Token symbol (e.g., "ETH", "STRK") */
-    symbol: string;
-    /** Contract address (hex string) */
-    address: string;
-    /** Token decimals (default: 18) */
-    decimals?: number;
-    /** Human-readable name */
-    name?: string;
-}
-
-/**
- * Configuration for fetch operations with retry logic
- */
-interface FetchConfig {
-    /** Request timeout in milliseconds (default: 10000) */
-    timeout?: number;
-    /** Maximum number of retry attempts (default: 3) */
-    maxRetries?: number;
-    /** Base backoff delay in milliseconds (default: 1000) */
-    baseBackoff?: number;
-    /** Maximum backoff delay in milliseconds (default: 5000) */
-    maxBackoff?: number;
-    /** Custom fetch function (for SSR or custom implementations) */
-    fetch?: typeof globalThis.fetch;
-}
-/**
- * Configuration for quote polling
- */
-interface PollingConfig {
-    /** Polling interval in milliseconds (default: 5000) */
-    interval?: number;
-    /** Maximum consecutive errors before auto-stopping (default: 3) */
-    maxConsecutiveErrors?: number;
-}
-/**
- * Main configuration for EkuboClient
- */
-interface EkuboClientConfig {
-    /** Chain shorthand: 'mainnet' or 'sepolia' */
-    chain?: "mainnet" | "sepolia";
-    /** Custom chain ID (overrides chain setting) */
-    chainId?: string;
-    /** Custom quoter API URL (for swap quotes) */
-    quoterApiUrl?: string;
-    /** Custom API URL (for tokens, prices, stats, etc.) */
-    apiUrl?: string;
-    /** Custom router contract address */
-    routerAddress?: string;
-    /** Default slippage percentage as bigint (default: 5n = 5%) */
-    defaultSlippagePercent?: bigint;
-    /** Fetch configuration */
-    fetch?: FetchConfig;
-    /** Polling configuration */
-    polling?: PollingConfig;
-    /** Additional custom tokens to register */
-    customTokens?: TokenInfo[];
-}
-/**
- * Resolved configuration with all defaults applied
- */
-interface ResolvedConfig {
-    chainId: string;
-    quoterApiUrl: string;
-    apiUrl: string;
-    routerAddress: string;
-    defaultSlippagePercent: bigint;
-    fetch: Required<FetchConfig>;
-    polling: Required<PollingConfig>;
-}
-
-/**
- * A single Starknet call (compatible with starknet.js Call type)
- */
-interface SwapCall {
-    contractAddress: string;
-    entrypoint: string;
-    calldata: string[];
-}
-/**
- * Result of swap call generation
- */
-interface SwapCallsResult {
-    /** Transfer call to send tokens to router */
-    transferCall: SwapCall;
-    /** Swap execution calls */
-    swapCalls: SwapCall[];
-    /** Clear remaining tokens call */
-    clearCall: SwapCall;
-    /** All calls in execution order */
-    allCalls: SwapCall[];
-}
-/**
- * Parameters for fetching a swap quote
- */
-interface FetchQuoteParams {
-    /** Amount to swap (in smallest unit) */
-    amount: bigint;
-    /** Token to sell (address or symbol) */
-    tokenFrom: string;
-    /** Token to buy (address or symbol) */
-    tokenTo: string;
-    /** Optional abort signal for cancellation */
-    signal?: AbortSignal;
-}
-
-/**
- * Price history data point
- */
-interface PriceDataPoint {
-    timestamp: number;
-    price: number;
-}
-/**
- * Price history response
- */
-interface PriceHistoryResponse {
-    data: PriceDataPoint[];
-}
-/**
- * Parameters for getPriceHistory
- */
-interface GetPriceHistoryParams {
-    /** Token to get price for */
-    token: string;
-    /** Quote token (e.g., USDC) */
-    otherToken: string;
-    /** Chain ID (Ekubo format) */
-    chainId?: string;
-    /** Time interval in seconds */
-    interval?: number;
-    /** API base URL */
-    apiUrl?: string;
-    /** Fetch configuration */
-    fetchConfig?: FetchConfig;
-}
-/**
- * Fetch price history from Ekubo API
- */
-declare function getPriceHistory(params: GetPriceHistoryParams): Promise<PriceHistoryResponse>;
-
-/**
- * Token metadata from Ekubo API
- */
-interface ApiTokenInfo {
-    /** Token contract address */
-    address: string;
-    /** Token name */
-    name: string;
-    /** Token symbol */
-    symbol: string;
-    /** Token decimals */
-    decimals: number;
-    /** Logo URI (optional) */
-    logo_uri?: string;
-    /** Whether token is verified/trusted */
-    verified?: boolean;
-}
-/**
- * Parameters for fetching tokens
- */
-interface FetchTokensParams {
-    /** Chain ID (Ekubo format) */
-    chainId?: string;
-    /** API base URL */
-    apiUrl?: string;
-    /** Fetch configuration */
-    fetchConfig?: FetchConfig;
-}
-/**
- * Parameters for fetching a single token
- */
-interface FetchTokenParams extends FetchTokensParams {
-    /** Token contract address */
-    tokenAddress: string;
-}
-/**
- * Parameters for batch fetching tokens
- */
-interface FetchTokensBatchParams extends FetchTokensParams {
-    /** Token contract addresses */
-    tokenAddresses: string[];
-}
-/**
- * Fetch list of all tokens for a chain
- */
-declare function fetchTokens(params?: FetchTokensParams): Promise<ApiTokenInfo[]>;
-/**
- * Fetch metadata for a single token
- */
-declare function fetchToken(params: FetchTokenParams): Promise<ApiTokenInfo | null>;
-/**
- * Fetch metadata for multiple tokens at once
- */
-declare function fetchTokensBatch(params: FetchTokensBatchParams): Promise<ApiTokenInfo[]>;
-
-/**
- * Trading pair statistics
- */
-interface PairStats {
-    token0: string;
-    token1: string;
-    tvl_usd: number;
-    volume_24h_usd: number;
-    fees_24h_usd: number;
-    price: number;
-    price_change_24h: number;
-}
-/**
- * Overview statistics response
- */
-interface OverviewStats {
-    tvl_usd: number;
-    volume_24h_usd: number;
-    fees_24h_usd: number;
-}
-/**
- * Pool information
- */
-interface PoolInfo {
-    key_hash: string;
-    token0: string;
-    token1: string;
-    fee: string;
-    tick_spacing: number;
-    extension: string;
-    tvl_usd: number;
-    volume_24h_usd: number;
-}
-/**
- * TVL data point
- */
-interface TvlDataPoint {
-    timestamp: number;
-    tvl_usd: number;
-}
-/**
- * Volume data point
- */
-interface VolumeDataPoint {
-    timestamp: number;
-    volume_usd: number;
-}
-/**
- * Base parameters for stats API calls
- */
-interface StatsBaseParams {
-    /** Chain ID (Ekubo format) */
-    chainId?: string;
-    /** API base URL */
-    apiUrl?: string;
-    /** Fetch configuration */
-    fetchConfig?: FetchConfig;
-}
-/**
- * Parameters for pair-specific queries
- */
-interface PairStatsParams extends StatsBaseParams {
-    /** First token address */
-    tokenA: string;
-    /** Second token address */
-    tokenB: string;
-}
-/**
- * Fetch overview of top trading pairs
- */
-declare function fetchTopPairs(params?: StatsBaseParams): Promise<PairStats[]>;
-/**
- * Fetch protocol TVL overview
- */
-declare function fetchTvl(params?: StatsBaseParams): Promise<OverviewStats>;
-/**
- * Fetch protocol volume overview
- */
-declare function fetchVolume(params?: StatsBaseParams): Promise<OverviewStats>;
-/**
- * Fetch TVL for a specific trading pair
- */
-declare function fetchPairTvl(params: PairStatsParams): Promise<TvlDataPoint[]>;
-/**
- * Fetch volume for a specific trading pair
- */
-declare function fetchPairVolume(params: PairStatsParams): Promise<VolumeDataPoint[]>;
-/**
- * Fetch pools for a specific trading pair
- */
-declare function fetchPairPools(params: PairStatsParams): Promise<PoolInfo[]>;
-
-/**
- * Parameters for generating swap calls
- */
-interface GenerateSwapCallsParams {
-    /** Token being sold (address) */
-    sellToken: string;
-    /** Token being bought (address) */
-    buyToken: string;
-    /** Minimum amount of buyToken to receive */
-    minimumReceived: bigint;
-    /** Quote from Ekubo API */
-    quote: SwapQuote;
-    /** Chain ID (Ekubo format) */
-    chainId?: string;
-    /** Router contract address (overrides chainId lookup) */
-    routerAddress?: string;
-    /** Slippage percentage for transfer amount (default: 5n = 5%) */
-    slippagePercent?: bigint;
-}
-/**
- * Generate swap calls for Ekubo router
- *
- * This generates the calls needed to execute a swap:
- * 1. Transfer tokens to router
- * 2. Execute multihop_swap or multi_multihop_swap
- * 3. Clear minimum profits
- * 4. Clear remaining tokens
- */
-declare function generateSwapCalls(params: GenerateSwapCallsParams): SwapCallsResult;
-/**
- * Prepare swap calls with approval included
- * This is a convenience wrapper that adds the ERC20 approve call
- */
-declare function prepareSwapCalls(params: GenerateSwapCallsParams): SwapCallsResult & {
-    approveCall: SwapCall;
-};
-
-/**
- * Token registry for managing token information and symbol-to-address resolution
- */
-declare class TokenRegistry {
-    private symbolMap;
-    private addressMap;
-    constructor(tokens?: TokenInfo[]);
-    /**
-     * Register a token
-     */
-    register(token: TokenInfo): void;
-    /**
-     * Get token by symbol (case-insensitive)
-     */
-    getBySymbol(symbol: string): TokenInfo | undefined;
-    /**
-     * Get token by address (normalized)
-     */
-    getByAddress(address: string): TokenInfo | undefined;
-    /**
-     * Check if a token exists by symbol
-     */
-    hasSymbol(symbol: string): boolean;
-    /**
-     * Check if a token exists by address
-     */
-    hasAddress(address: string): boolean;
-    /**
-     * Get all registered tokens
-     */
-    getAll(): TokenInfo[];
-    /**
-     * Get all registered symbols
-     */
-    getSymbols(): string[];
-}
-/**
- * Get the default token registry (singleton)
- */
-declare function getDefaultRegistry(): TokenRegistry;
-/**
- * Create a new token registry with custom tokens
- */
-declare function createTokenRegistry(customTokens?: TokenInfo[]): TokenRegistry;
+import { T as TokenRegistry, a as TokenInfo, F as FetchConfig, S as SwapQuote, R as RouteNode } from './client-DPSUVYSv.js';
+export { A as ApiTokenInfo, D as DEFAULT_POLLING_CONFIG, E as EkuboClient, b as EkuboClientConfig, c as FetchQuoteParams, d as FetchTokenParams, e as FetchTokensBatchParams, f as FetchTokensParams, G as GenerateSwapCallsParams, g as GetPriceHistoryParams, O as OverviewStats, P as PairStats, h as PairStatsParams, i as PollingConfig, j as PoolInfo, k as PoolKey, l as PriceDataPoint, m as PriceHistoryResponse, Q as QuotePoller, n as QuotePollerCallbacks, o as QuotePollerParams, p as ResolvedConfig, q as StatsBaseParams, r as SwapCall, s as SwapCallsResult, t as SwapQuoteApiResponse, u as SwapQuoteErrorResponse, v as SwapSplit, w as TvlDataPoint, V as VolumeDataPoint, x as createEkuboClient, y as createQuotePoller, z as createTokenRegistry, B as fetchPairPools, C as fetchPairTvl, H as fetchPairVolume, I as fetchToken, J as fetchTokens, K as fetchTokensBatch, L as fetchTopPairs, M as fetchTvl, N as fetchVolume, U as generateSwapCalls, W as getDefaultRegistry, X as getPriceHistory, Y as prepareSwapCalls } from './client-DPSUVYSv.js';
 
 /**
  * Resolve a token identifier (symbol or address) to a normalized address
@@ -453,240 +32,6 @@ declare const MAINNET_TOKENS: TokenInfo[];
  */
 declare function getMainnetTokensMap(): Map<string, TokenInfo>;
 
-/**
- * Default polling configuration
- */
-declare const DEFAULT_POLLING_CONFIG: Required<PollingConfig>;
-/**
- * Quote poller callbacks
- */
-interface QuotePollerCallbacks {
-    /** Called when a new quote is received */
-    onQuote: (quote: SwapQuote) => void;
-    /** Called when an error occurs */
-    onError?: (error: Error) => void;
-    /** Called when polling stops (due to errors or manually) */
-    onStop?: (reason: "manual" | "errors") => void;
-}
-/**
- * Parameters for quote polling
- */
-interface QuotePollerParams {
-    /** Amount to swap */
-    amount: bigint;
-    /** Token to sell (address) */
-    tokenFrom: string;
-    /** Token to buy (address) */
-    tokenTo: string;
-    /** Chain ID (Ekubo format) */
-    chainId?: string;
-}
-/**
- * QuotePoller class for real-time quote updates
- */
-declare class QuotePoller {
-    private intervalId;
-    private abortController;
-    private consecutiveErrors;
-    private isRunning;
-    private readonly params;
-    private readonly callbacks;
-    private readonly config;
-    private readonly fetchConfig?;
-    constructor(params: QuotePollerParams, callbacks: QuotePollerCallbacks, config?: PollingConfig, fetchConfig?: FetchConfig);
-    /**
-     * Start polling for quotes
-     */
-    start(): void;
-    /**
-     * Stop polling
-     */
-    stop(): void;
-    /**
-     * Check if currently polling
-     */
-    get running(): boolean;
-    /**
-     * Update polling parameters (requires restart)
-     */
-    updateParams(params: Partial<QuotePollerParams>): void;
-    /**
-     * Fetch a quote
-     */
-    private fetchQuote;
-    /**
-     * Stop due to consecutive errors
-     */
-    private stopDueToErrors;
-}
-/**
- * Create a quote poller instance
- */
-declare function createQuotePoller(params: QuotePollerParams, callbacks: QuotePollerCallbacks, config?: PollingConfig, fetchConfig?: FetchConfig): QuotePoller;
-
-/**
- * Main Ekubo SDK client
- *
- * Provides a high-level interface for:
- * - Fetching swap quotes
- * - Generating swap calls
- * - Token symbol resolution
- * - Quote polling
- * - Protocol statistics (TVL, volume, pairs)
- * - Dynamic token list fetching
- */
-declare class EkuboClient {
-    private readonly config;
-    private readonly tokenRegistry;
-    constructor(config?: EkuboClientConfig);
-    /**
-     * Resolve configuration with defaults
-     */
-    private resolveConfig;
-    /**
-     * Get the current chain ID
-     */
-    get chainId(): string;
-    /**
-     * Get the router contract address
-     */
-    get routerAddress(): string;
-    /**
-     * Get the token registry
-     */
-    get tokens(): TokenRegistry;
-    /**
-     * Resolve a token identifier (symbol or address) to an address
-     */
-    resolveToken(tokenIdentifier: string): string;
-    /**
-     * Fetch a swap quote
-     *
-     * @param params - Quote parameters (supports symbols or addresses)
-     * @returns Swap quote
-     */
-    getQuote(params: FetchQuoteParams): Promise<SwapQuote>;
-    /**
-     * Fetch a token price in USDC
-     *
-     * @param tokenIdentifier - Token symbol or address
-     * @param amount - Amount of token
-     * @param signal - Optional abort signal
-     * @returns Price in USDC (as bigint)
-     */
-    getUsdcPrice(tokenIdentifier: string, amount: bigint, signal?: AbortSignal): Promise<bigint>;
-    /**
-     * Fetch price history
-     *
-     * @param token - Token symbol or address
-     * @param otherToken - Quote token symbol or address
-     * @param interval - Time interval in seconds (default: 7000)
-     * @returns Price history data
-     */
-    getPriceHistory(token: string, otherToken: string, interval?: number): Promise<PriceHistoryResponse>;
-    /**
-     * Generate swap calls from a quote
-     *
-     * @param params - Call generation parameters (supports symbols or addresses)
-     * @returns Swap calls result
-     */
-    generateSwapCalls(params: Omit<GenerateSwapCallsParams, "chainId" | "routerAddress">): SwapCallsResult;
-    /**
-     * Prepare swap calls with approval included
-     *
-     * @param params - Call generation parameters (supports symbols or addresses)
-     * @returns Swap calls result with approve call
-     */
-    prepareSwapCalls(params: Omit<GenerateSwapCallsParams, "chainId" | "routerAddress">): SwapCallsResult & {
-        approveCall: SwapCall;
-    };
-    /**
-     * Create a quote poller for real-time updates
-     *
-     * @param params - Quote parameters (supports symbols or addresses)
-     * @param callbacks - Poller callbacks
-     * @param config - Optional polling configuration
-     * @returns QuotePoller instance
-     */
-    createQuotePoller(params: Omit<FetchQuoteParams, "signal">, callbacks: QuotePollerCallbacks, config?: PollingConfig): QuotePoller;
-    /**
-     * Register a custom token in the local registry
-     */
-    registerToken(token: TokenInfo): void;
-    /**
-     * Fetch all tokens from the Ekubo API
-     *
-     * @returns Array of token metadata from the API
-     */
-    fetchTokens(): Promise<ApiTokenInfo[]>;
-    /**
-     * Fetch metadata for a single token from the API
-     *
-     * @param tokenAddress - Token contract address
-     * @returns Token metadata or null if not found
-     */
-    fetchToken(tokenAddress: string): Promise<ApiTokenInfo | null>;
-    /**
-     * Fetch metadata for multiple tokens at once
-     *
-     * @param tokenAddresses - Array of token addresses
-     * @returns Array of token metadata
-     */
-    fetchTokensBatch(tokenAddresses: string[]): Promise<ApiTokenInfo[]>;
-    /**
-     * Fetch tokens from API and register them in the local registry
-     *
-     * @returns Number of tokens registered
-     */
-    syncTokensFromApi(): Promise<number>;
-    /**
-     * Fetch top trading pairs by volume
-     *
-     * @returns Array of pair statistics
-     */
-    getTopPairs(): Promise<PairStats[]>;
-    /**
-     * Fetch protocol TVL overview
-     *
-     * @returns TVL statistics
-     */
-    getTvl(): Promise<OverviewStats>;
-    /**
-     * Fetch protocol volume overview
-     *
-     * @returns Volume statistics
-     */
-    getVolume(): Promise<OverviewStats>;
-    /**
-     * Fetch TVL history for a trading pair
-     *
-     * @param tokenA - First token (symbol or address)
-     * @param tokenB - Second token (symbol or address)
-     * @returns TVL data points
-     */
-    getPairTvl(tokenA: string, tokenB: string): Promise<TvlDataPoint[]>;
-    /**
-     * Fetch volume history for a trading pair
-     *
-     * @param tokenA - First token (symbol or address)
-     * @param tokenB - Second token (symbol or address)
-     * @returns Volume data points
-     */
-    getPairVolume(tokenA: string, tokenB: string): Promise<VolumeDataPoint[]>;
-    /**
-     * Fetch pools for a trading pair
-     *
-     * @param tokenA - First token (symbol or address)
-     * @param tokenB - Second token (symbol or address)
-     * @returns Pool information
-     */
-    getPairPools(tokenA: string, tokenB: string): Promise<PoolInfo[]>;
-}
-/**
- * Create an EkuboClient instance
- */
-declare function createEkuboClient(config?: EkuboClientConfig): EkuboClient;
-
 /**
  * Parameters for fetchSwapQuote
  */
@@ -924,4 +269,4 @@ declare class InvalidChainError extends EkuboError {
  */
 declare function isNonRetryableError(error: unknown): boolean;
 
-export { API_URLS, AbortError, ApiError, type ApiTokenInfo, CHAIN_CONFIGS, CHAIN_IDS, type ChainConfig, DEFAULT_POLLING_CONFIG, EkuboClient, type EkuboClientConfig, EkuboError, type EncodedRoute, type FetchConfig, type FetchQuoteParams, type FetchSwapQuoteParams, type FetchTokenParams, type FetchTokensBatchParams, type FetchTokensParams, type GenerateSwapCallsParams, type GetPriceHistoryParams, InsufficientLiquidityError, InvalidChainError, MAINNET_TOKENS, type OverviewStats, type PairStats, type PairStatsParams, type PollingConfig, type PoolInfo, type PoolKey, type PriceDataPoint, type PriceHistoryResponse, QuotePoller, type QuotePollerCallbacks, type QuotePollerParams, ROUTER_ADDRESSES, RateLimitError, type ResolvedConfig, type RetryOptions, type RouteNode, STARKNET_CHAIN_IDS, STARKNET_TO_EKUBO_CHAIN, type StatsBaseParams, type SwapCall, type SwapCallsResult, type SwapQuote, type SwapQuoteApiResponse, type SwapQuoteErrorResponse, type SwapSplit, TimeoutError, type TokenInfo, TokenNotFoundError, TokenRegistry, type TvlDataPoint, USDC_ADDRESSES, type VolumeDataPoint, abs, addSlippage, calculateBackoff, canResolveToken, createEkuboClient, createQuotePoller, createTokenRegistry, encodeRoute, encodeRouteNode, fetchPairPools, fetchPairTvl, fetchPairVolume, fetchSwapQuote, fetchSwapQuoteInUsdc, fetchToken, fetchTokens, fetchTokensBatch, fetchTopPairs, fetchTvl, fetchVolume, generateSwapCalls, getChainConfig, getDefaultRegistry, getEkuboChainId, getMainnetTokensMap, getPriceHistory, isAddress, isNonRetryableError, normalizeAddress, parseTotalCalculated, prepareSwapCalls, resolveToken, resolveTokenInfo, sleep, splitU256, subtractSlippage, toHex, withRetry };
+export { API_URLS, AbortError, ApiError, CHAIN_CONFIGS, CHAIN_IDS, type ChainConfig, EkuboError, type EncodedRoute, FetchConfig, type FetchSwapQuoteParams, InsufficientLiquidityError, InvalidChainError, MAINNET_TOKENS, ROUTER_ADDRESSES, RateLimitError, type RetryOptions, RouteNode, STARKNET_CHAIN_IDS, STARKNET_TO_EKUBO_CHAIN, SwapQuote, TimeoutError, TokenInfo, TokenNotFoundError, TokenRegistry, USDC_ADDRESSES, abs, addSlippage, calculateBackoff, canResolveToken, encodeRoute, encodeRouteNode, fetchSwapQuote, fetchSwapQuoteInUsdc, getChainConfig, getEkuboChainId, getMainnetTokensMap, isAddress, isNonRetryableError, normalizeAddress, parseTotalCalculated, resolveToken, resolveTokenInfo, sleep, splitU256, subtractSlippage, toHex, withRetry };