@gala-chain/launchpad-sdk 3.31.2 → 4.0.1-beta.0

package/dist/src/services/DexPoolService.d.ts

@@ -0,0 +1,137 @@
+/**
+ * DEX Pool Discovery Service
+ *
+ * Service for querying and exploring GalaSwap DEX liquidity pools
+ * with pagination, filtering, sorting, and quote-based pricing enrichment.
+ *
+ * @packageDocumentation
+ */
+import { BaseService } from './BaseService';
+import type { HttpClient } from '../utils/http';
+import type { DexPoolsResult, FetchDexPoolsOptions } from '../types/dex-pool.dto';
+import type { GSwapService } from './GSwapService';
+/**
+ * Service for fetching and exploring DEX pools on GalaSwap
+ *
+ * Handles pagination, filtering, sorting, and optional quote-based pricing enrichment
+ * of liquidity pools across all graduated tokens and base tokens.
+ *
+ * @category GSwap
+ * @since 3.28.0
+ */
+export declare class DexPoolService extends BaseService {
+    /** Base URL for DEX backend API */
+    private readonly dexBackendBaseUrl;
+    /** GSwap service for quote-based pricing enrichment */
+    private gswapService;
+    /** Concurrency level for parallel pricing requests */
+    private pricingConcurrency;
+    /**
+     * Create a new DexPoolService instance
+     *
+     * @param http HttpClient for making API requests
+     * @param dexBackendBaseUrl Base URL for DEX backend API
+     * @param gswapService Optional GSwap service for pricing enrichment
+     * @param pricingConcurrency Concurrency level for parallel pricing requests (default: 5)
+     * @param debugMode Enable debug logging
+     */
+    constructor(http: HttpClient, dexBackendBaseUrl: string, gswapService?: GSwapService | undefined, pricingConcurrency?: number, debugMode?: boolean);
+    /**
+     * Set GSwap service for pricing enrichment
+     *
+     * @param service GSwap service instance
+     */
+    setGSwapService(service: GSwapService): void;
+    /**
+     * Set concurrency level for pricing requests
+     *
+     * @param concurrency Number of concurrent pricing requests
+     */
+    setPricingConcurrency(concurrency: number): void;
+    /**
+     * Enrich pools with quote-based pricing
+     *
+     * Uses parallel requests with concurrency control to price each pool's tokens
+     * against GUSDC (as stable reference) via `getSwapQuoteExactInput()`.
+     *
+     * Failed pricing requests are caught and logged - pools without prices are still
+     * included with all other metrics intact (graceful degradation).
+     *
+     * @param pools Pools to enrich with pricing
+     * @returns Promise resolving to pools with token0Price and token1Price populated
+     *
+     * @private
+     */
+    private enrichPoolsWithPricing;
+    /**
+     * Fetch DEX pools with pagination and filtering
+     *
+     * Queries the DEX backend for available liquidity pools with support for:
+     * - Pagination (max 20 per page)
+     * - Sorting by TVL, 30-day volume, or 1-day volume
+     * - Search filtering by token symbols
+     * - Optional quote-based pricing enrichment via `withPrices` option
+     *
+     * @param options Fetch options (all optional)
+     * @returns Promise resolving to paginated pool results
+     *
+     * @throws {Error} If HTTP request fails
+     * @throws {ValidationError} If sort options are invalid
+     *
+     * @example
+     * ```typescript
+     * // Fetch top 10 pools by volume with pricing
+     * const result = await dexPoolService.fetchDexPools({
+     *   sortBy: 'volume1d',
+     *   sortOrder: 'desc',
+     *   limit: 10,
+     *   page: 1,
+     *   withPrices: true
+     * });
+     *
+     * console.log(`Found ${result.total} total pools`);
+     * result.pools.forEach(pool => {
+     *   console.log(`${pool.poolName}: ${pool.token0Price} / ${pool.token1Price}`);
+     * });
+     * ```
+     *
+     * @since 3.28.0
+     */
+    fetchDexPools(options?: FetchDexPoolsOptions): Promise<DexPoolsResult>;
+    /**
+     * Fetch ALL DEX pools with automatic pagination
+     *
+     * Convenience method that automatically handles pagination to retrieve
+     * all available DEX pools. Uses maximum page size (20) for efficiency.
+     *
+     * This is useful when you need complete pool data regardless of result size.
+     * For large result sets with pricing, note that the operation may take significant time
+     * since all pools must be priced. Consider using fetchDexPools() with explicit pagination
+     * and batching if you need to process pricing incrementally.
+     *
+     * @param options Fetch options (no pagination fields)
+     * @returns Promise resolving to all pools with flattened pagination
+     *
+     * @example
+     * ```typescript
+     * // Fetch all pools sorted by TVL with pricing
+     * const allPools = await dexPoolService.fetchAllDexPools({
+     *   sortBy: 'tvl',
+     *   sortOrder: 'desc',
+     *   withPrices: true  // Enable pricing for all pools
+     * });
+     *
+     * console.log(`Total pools: ${allPools.total}`);
+     * console.log(`Priced pools: ${allPools.pools.filter(p => p.token0Price).length}`);
+     *
+     * // Find top GALA pools with prices
+     * const galaPools = allPools.pools
+     *   .filter(p => p.poolName.includes('GALA') && p.token0Price)
+     *   .slice(0, 10);
+     * ```
+     *
+     * @since 3.28.0
+     */
+    fetchAllDexPools(options?: Omit<FetchDexPoolsOptions, 'page' | 'limit'>): Promise<DexPoolsResult>;
+}
+//# sourceMappingURL=DexPoolService.d.ts.map

package/dist/src/services/DexPoolService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DexPoolService.d.ts","sourceRoot":"","sources":["../../../src/services/DexPoolService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EAErB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC7C,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C,uDAAuD;IACvD,OAAO,CAAC,YAAY,CAA2B;IAE/C,sDAAsD;IACtD,OAAO,CAAC,kBAAkB,CAAa;IAEvC;;;;;;;;OAQG;gBAED,IAAI,EAAE,UAAU,EAChB,iBAAiB,EAAE,MAAM,EACzB,YAAY,GAAE,YAAY,GAAG,SAAqB,EAClD,kBAAkB,GAAE,MAAU,EAC9B,SAAS,GAAE,OAAe;IAQ5B;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAI5C;;;;OAIG;IACH,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKhD;;;;;;;;;;;;;OAaG;YACW,sBAAsB;IAoHpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC;IAgFhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,gBAAgB,CACpB,OAAO,GAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAM,GACzD,OAAO,CAAC,cAAc,CAAC;CAuC3B"}

package/dist/src/services/DexQuoteService.d.ts

@@ -0,0 +1,288 @@
+/**
+ * DEX Quote Service
+ *
+ * Handles offline and online DEX quote calculations using composite pool data.
+ * Provides three calculation modes:
+ * - LOCAL: Client-side calculation (instant, no network)
+ * - EXTERNAL: GalaChain network calculation (real-time, slower)
+ * - HYBRID: Local with external validation (best of both)
+ *
+ * @packageDocumentation
+ */
+import { BaseService } from './BaseService';
+import type { HttpClient } from '../utils/http';
+import type { FetchCompositePoolDataOptions, CompositePoolDataResult, CalculateDexPoolQuoteOptions, DexPoolQuoteResult } from '../types/composite-pool.dto';
+/**
+ * Concurrency constant for parallel composite pool fetching
+ */
+export declare const COMPOSITE_POOL_FETCH_CONCURRENCY = 5;
+/**
+ * Service for DEX quote calculations with composite pool data
+ *
+ * Provides offline and online quote calculations using composite pool state from GalaChain.
+ * Handles dependency version conflicts between @gala-chain/api and @gala-chain/dex through
+ * strategic type assertions validated by BigNumber.js runtime conversions.
+ *
+ * ## Dependency Version Management
+ *
+ * **Version Conflicts:**
+ * - `@gala-chain/api`: Used for TokenBalance class (imported from this package)
+ * - `@gala-chain/dex`: Used for Pool, TickData, CompositePoolDto classes
+ * - **Issue**: SDK may depend on different versions of @gala-chain/api than @gala-chain/dex
+ * - **Solution**: Type assertions with runtime validation via BigNumber.js
+ *
+ * **Current Dependency Stack:**
+ * ```
+ * SDK
+ * ├── @gala-chain/api@X.Y.Z (TokenBalance)
+ * ├── @gala-chain/dex@A.B.C (Pool, TickData, CompositePoolDto)
+ * ├── @gala-chain/connect (GalaChain client)
+ * └── axios (HTTP requests)
+ *
+ * Potential Conflict: @gala-chain/dex depends on different @gala-chain/api version
+ * ```
+ *
+ * **Type Assertion Patterns:**
+ * 1. **TokenBalance Construction** - `new TokenBalance(data as any)`
+ *    - Reason: TokenBalance class definition may differ between versions
+ *    - Validation: Constructor throws on invalid data
+ *
+ * 2. **Property Assignment** - `(instance as any).propertyName = value`
+ *    - Reason: TickData constructor only accepts 2 params; properties set after
+ *    - Validation: All assignments use BigNumber.js conversion or primitives
+ *
+ * 3. **CompositePoolDto Construction** - Passing TokenBalance instances
+ *    - Reason: TokenBalance types may not match exactly between versions
+ *    - Validation: BigNumber.js validates all numeric conversions
+ *
+ * **Risk Mitigation:**
+ * - ✓ BigNumber.js throws immediately on invalid numbers (NaN, non-numeric strings)
+ * - ✓ Pool, TickData, TokenBalance constructors throw on structural errors
+ * - ✓ All numeric fields converted to BigNumber before use
+ * - ✓ String-to-number conversions validated at instantiation time
+ *
+ * @category GSwap
+ * @since 3.32.0
+ * @architecture Uses composition and dependency injection for testability
+ * @note Type assertions are isolated to conversion functions; business logic uses proper types
+ */
+export declare class DexQuoteService extends BaseService {
+    private readonly galaChainBaseUrl;
+    private readonly networkTimeout;
+    private compositePoolFetchConcurrency;
+    /**
+     * Initialize DEX Quote Service
+     *
+     * @param http HttpClient for GalaChain requests
+     * @param galaChainBaseUrl Base URL for GalaChain gateway
+     * @param debugMode Enable debug logging
+     * @param networkTimeout Network timeout in milliseconds (default: 30000ms)
+     * @example
+     * ```typescript
+     * // Use default 30-second timeout
+     * const service = new DexQuoteService(http, galaChainBaseUrl, false);
+     *
+     * // Use custom 60-second timeout for rate-limited APIs
+     * const service = new DexQuoteService(http, galaChainBaseUrl, false, 60000);
+     * ```
+     */
+    constructor(http: HttpClient, galaChainBaseUrl: string, debugMode?: boolean, networkTimeout?: number);
+    /**
+     * Validate input parameters for fetchCompositePoolData
+     *
+     * @private
+     * @param token0 First token in pipe-delimited format
+     * @param token1 Second token in pipe-delimited format
+     * @param fee Fee tier (500, 3000, or 10000)
+     * @throws DexQuoteError if validation fails
+     */
+    private validateFetchCompositePoolDataInput;
+    /**
+     * Validate input parameters for quote calculation methods
+     *
+     * @private
+     * @param amount Amount to validate (should be positive numeric string)
+     * @throws DexQuoteError if validation fails
+     */
+    private validateQuoteAmount;
+    /**
+     * Convert SDK TokenClassKey to DexTokenClassKey for @gala-chain/dex
+     *
+     * @private
+     * @param tokenKey SDK TokenClassKey
+     * @returns DexTokenClassKey for use with @gala-chain/dex
+     */
+    private convertTokenClassKey;
+    /**
+     * Set concurrency level for parallel composite pool fetching
+     *
+     * Controls how many composite pool data requests can be in-flight simultaneously.
+     * Higher values fetch pools faster but use more network connections. Lower values
+     * use fewer connections but take longer to fetch multiple pools.
+     *
+     * **Default**: 5 concurrent requests
+     * **Valid Range**: 1-20 (values outside this range are clamped)
+     *
+     * @param concurrency Number of concurrent requests (automatically clamped to 1-20)
+     *
+     * @example Default usage
+     * ```typescript
+     * // Fetch 3 pools with default concurrency (5)
+     * const pools = await Promise.all([
+     *   sdk.fetchCompositePoolData({ token0: 'GALA|Unit|none|none', token1: 'Token|Unit|BENE|client:123', fee: 3000 }),
+     *   sdk.fetchCompositePoolData({ token0: 'GALA|Unit|none|none', token1: 'Token|Unit|USDC|eth:0x...', fee: 500 }),
+     *   sdk.fetchCompositePoolData({ token0: 'Token|Unit|BENE|client:123', token1: 'Token|Unit|USDC|eth:0x...', fee: 3000 }),
+     * ]);
+     * ```
+     *
+     * @example Increase concurrency for faster bulk fetching
+     * ```typescript
+     * // Optimize for fetching many pools (trading bot scenario)
+     * service.setCompositePoolFetchConcurrency(15);
+     *
+     * const pools = await Promise.all(
+     *   tokenPairs.map(pair => sdk.fetchCompositePoolData(pair))
+     * );
+     * ```
+     *
+     * @example Decrease concurrency for rate-limited APIs
+     * ```typescript
+     * // Optimize for rate-limited GalaChain gateways
+     * service.setCompositePoolFetchConcurrency(2);
+     *
+     * // Fetch pools one-by-one (slow but respects rate limits)
+     * for (const pair of tokenPairs) {
+     *   const composite = await sdk.fetchCompositePoolData(pair);
+     *   processPool(composite);
+     * }
+     * ```
+     *
+     * @example Reset to default
+     * ```typescript
+     * // Reset concurrency back to default (5)
+     * service.setCompositePoolFetchConcurrency(5);
+     * ```
+     */
+    setCompositePoolFetchConcurrency(concurrency: number): void;
+    /**
+     * Fetch composite pool data from GalaChain
+     *
+     * Retrieves complete pool state including:
+     * - Pool liquidity and price data
+     * - Tick data for liquidity calculations
+     * - Token balances and decimals
+     *
+     * @param options Composite pool fetch options (token0/token1 in pipe-delimited format)
+     * @returns Complete composite pool data for offline quote calculations
+     * @throws DexPoolNotFoundError if pool does not exist
+     * @throws DexQuoteError on API or conversion errors
+     *
+     * @example
+     * ```typescript
+     * const compositePool = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000  // 0.30%
+     * });
+     * ```
+     */
+    fetchCompositePoolData(options: FetchCompositePoolDataOptions): Promise<CompositePoolDataResult>;
+    /**
+     * Calculate DEX pool quote using LOCAL client-side calculation
+     *
+     * Instant quotes without network calls. Uses quoteExactAmount from @gala-chain/dex
+     * with pre-fetched composite pool data.
+     *
+     * @param options Quote calculation options (must include compositePoolData)
+     * @returns Quote result with amounts and price data
+     * @throws DexQuoteError on calculation errors
+     *
+     * @example
+     * ```typescript
+     * // Step 1: Fetch composite data (one network call)
+     * const composite = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000
+     * });
+     *
+     * // Step 2: Calculate quote (instant, local)
+     * const quote = await sdk.calculateDexPoolQuoteExactAmountLocal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * });
+     * console.log(`Receive: ${quote.amount1} BENE`);
+     *
+     * // Step 3: More quotes reusing same composite data (instant!)
+     * const quote2 = await sdk.calculateDexPoolQuoteExactAmountLocal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '5000'
+     * });
+     * ```
+     */
+    calculateDexPoolQuoteExactAmountLocal(options: CalculateDexPoolQuoteOptions): Promise<DexPoolQuoteResult>;
+    /**
+     * Calculate DEX pool quote using EXTERNAL GalaChain network call
+     *
+     * Real-time quotes from chain. Slower than local but always fresh.
+     * Uses QuoteExactAmount chain method directly.
+     *
+     * @param options Quote calculation options (must include compositePoolData for token info)
+     * @returns Quote result from chain
+     * @throws DexQuoteError on network or calculation errors
+     *
+     * @example
+     * ```typescript
+     * // Fetch composite data to get token ClassKeys
+     * const composite = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000
+     * });
+     *
+     * // Get real-time quote from chain
+     * const quote = await sdk.calculateDexPoolQuoteExactAmountExternal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * });
+     * ```
+     */
+    calculateDexPoolQuoteExactAmountExternal(options: CalculateDexPoolQuoteOptions): Promise<DexPoolQuoteResult>;
+    /**
+     * Calculate DEX pool quote with automatic mode selection
+     *
+     * Main method that delegates to local or external based on mode parameter.
+     * Defaults to local (instant) calculation.
+     *
+     * @param options Quote calculation options
+     * @param mode 'local' (instant) or 'external' (real-time) - defaults to 'local'
+     * @returns Quote result
+     *
+     * @example
+     * ```typescript
+     * const quote = await sdk.calculateDexPoolQuoteExactAmount({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * });
+     * // Uses local calculation by default
+     *
+     * // Or explicitly specify external mode for real-time:
+     * const quote = await sdk.calculateDexPoolQuoteExactAmount({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * }, 'external');
+     * ```
+     */
+    calculateDexPoolQuoteExactAmount(options: CalculateDexPoolQuoteOptions, mode?: 'local' | 'external'): Promise<DexPoolQuoteResult>;
+}
+//# sourceMappingURL=DexQuoteService.d.ts.map

package/dist/src/services/DexQuoteService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DexQuoteService.d.ts","sourceRoot":"","sources":["../../../src/services/DexQuoteService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAUhD,OAAO,KAAK,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,EAEnB,MAAM,6BAA6B,CAAC;AAGrC;;GAEG;AACH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,6BAA6B,CAA4C;IAEjF;;;;;;;;;;;;;;;OAeG;gBAED,IAAI,EAAE,UAAU,EAChB,gBAAgB,EAAE,MAAM,EACxB,SAAS,GAAE,OAAe,EAC1B,cAAc,GAAE,MAAc;IAOhC;;;;;;;;OAQG;IACH,OAAO,CAAC,mCAAmC;IAuC3C;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;;;;OAMG;IAEH,OAAO,CAAC,oBAAoB;IAU5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAO3D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,sBAAsB,CAC1B,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC;IAgEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACG,qCAAqC,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC;IA8D9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,wCAAwC,CAC5C,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC;IAwE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,gCAAgC,CACpC,OAAO,EAAE,4BAA4B,EACrC,IAAI,GAAE,OAAO,GAAG,UAAoB,GACnC,OAAO,CAAC,kBAAkB,CAAC;CAM/B"}

package/dist/{services → src/services}/DexService.d.ts

@@ -6,7 +6,7 @@
  * and calculate spot prices for launchpad tokens.
  */
 import { HttpClient } from '../utils/http';
-import { TokenSpotPrice, GalaChainTokenDetails } from '../types/launchpad.dto';
+import { TokenSpotPrice, GalaChainTokenDetails, DexSeason, LeaderboardResult, DexAggregatedVolumeSummary } from '../types/launchpad.dto';
 import { CalculateBuyAmountOptions, FetchTokenSpotPriceParams } from '../types/options.dto';
 import { AmountCalculationResult } from '../types/launchpad.dto';
 import { TokenMetadataCache } from './TokenMetadataCache';
@@ -99,22 +99,23 @@ export declare class DexService {
      *
      * @example String format
      * ```typescript
-     * const details = await dexService.fetchTokenDetails('Token|Unit|GUSDC|eth:0x...');
-     * console.log(details.symbol);    // 'GUSDC'
-     * console.log(details.decimals);  // 6
+     * const details = await dexService.fetchTokenDetails('Token|Unit|BENE|client:xxxx');
+     * console.log(details.symbol);    // 'BENE'
      *
-     * // Also works for native tokens
+     * // Also works for native OG coins
      * const gala = await dexService.fetchTokenDetails('GALA|Unit|none|none');
-     * console.log(gala.symbol);       // 'GALA' (not 'NONE'!)
+     * console.log(gala.symbol);       // 'GALA'
+     * const gusdc = await dexService.fetchTokenDetails('GUSDC|Unit|none|none');
+     * console.log(gusdc.symbol);      // 'GUSDC'
      * ```
      *
      * @example Object format
      * ```typescript
      * const details = await dexService.fetchTokenDetails({
-     *   collection: 'Token',
+     *   collection: 'GUSDC',
      *   category: 'Unit',
-     *   type: 'GUSDC',
-     *   additionalKey: 'eth:0x...'
+     *   type: 'none',
+     *   additionalKey: 'none'
      * });
      * ```
      *
@@ -122,5 +123,78 @@ export declare class DexService {
      * @throws NetworkError if API request fails or token not found
      */
     fetchTokenDetails(tokenId: TokenId): Promise<GalaChainTokenDetails>;
+    /**
+     * Fetch all available DEX leaderboard seasons
+     *
+     * Retrieves all competitive seasons with their time ranges.
+     * Use the returned season IDs with `fetchDexLeaderboardBySeasonId()` to get rankings.
+     *
+     * @returns Promise<DexSeason[]> Array of all seasons with time ranges
+     * @throws {NetworkError} If API request fails
+     *
+     * @category DEX Leaderboard
+     * @since 3.X.0
+     *
+     * @internal
+     */
+    fetchAllDexSeasons(): Promise<DexSeason[]>;
+    /**
+     * Find the currently active DEX leaderboard season
+     *
+     * Determines which season is active by comparing current time with season start/end.
+     * Returns null if no season is currently active (between seasons).
+     *
+     * @returns Promise<DexSeason | null> Current season or null if none active
+     * @throws {NetworkError} If API request fails
+     *
+     * @category DEX Leaderboard
+     * @since 3.X.0
+     *
+     * @internal
+     */
+    fetchCurrentDexSeason(): Promise<DexSeason | null>;
+    /**
+     * Fetch DEX leaderboard for a specific season
+     *
+     * Returns complete leaderboard rankings with XP metrics and achievement titles.
+     * Non-paginated response includes all entries (typically 100 participants).
+     *
+     * @param seasonId Season identifier number (must be positive integer)
+     * @returns Promise<LeaderboardResult> Complete leaderboard with rankings and metrics
+     * @throws {RequiredFieldError} If seasonId is invalid
+     * @throws {NetworkError} If API request fails
+     *
+     * @category DEX Leaderboard
+     * @since 3.X.0
+     *
+     * @internal
+     */
+    fetchDexLeaderboardBySeasonId(seasonId: number): Promise<LeaderboardResult>;
+    /**
+     * Fetch leaderboard for the currently active season
+     *
+     * Convenience method that automatically detects the current season
+     * and fetches its leaderboard. Returns null if no season is active.
+     *
+     * @returns Promise<LeaderboardResult | null> Current leaderboard or null if no active season
+     * @throws {NetworkError} If API request fails
+     *
+     * @category DEX Leaderboard
+     * @since 3.X.0
+     *
+     * @internal
+     */
+    fetchCurrentDexLeaderboard(): Promise<LeaderboardResult | null>;
+    /**
+     * Fetch DEX aggregated volume summary with trend metrics
+     *
+     * Returns platform-wide trading volume statistics across all DEX pools
+     * with 1-day, 7-day, and 30-day comparisons.
+     *
+     * @returns Promise<DexAggregatedVolumeSummary> Volume metrics and deltas
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.0
+     */
+    fetchDexAggregatedVolumeSummary(): Promise<DexAggregatedVolumeSummary>;
 }
 //# sourceMappingURL=DexService.d.ts.map

package/dist/src/services/DexService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DexService.d.ts","sourceRoot":"","sources":["../../../src/services/DexService.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,SAAS,EAET,iBAAiB,EAGjB,0BAA0B,EAE3B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC5F,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAUjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IALpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,cAAc,CAAC,EAAE,UAAU,YAAA,EAC3B,KAAK,CAAC,EAAE,kBAAkB,YAAA,EAC1B,gBAAgB,CAAC,EAAE,gBAAgB,YAAA,EACpD,SAAS,GAAE,OAAe;IAQ5B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,eAAe,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC;IAkCjF;;;;;;;;;;;OAWG;YACW,uBAAuB;IAwGrC;;;;;;;OAOG;IACG,4BAA4B,CAChC,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,uBAAuB,CAAC,EAE5F,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,GACrD,OAAO,CAAC,cAAc,CAAC;IA2E1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACG,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAkDzE;;;;;;;;;;;;;OAaG;IACG,kBAAkB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAmChD;;;;;;;;;;;;;OAaG;IACG,qBAAqB,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAkBxD;;;;;;;;;;;;;;;OAeG;IACG,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwDjF;;;;;;;;;;;;;OAaG;IACG,0BAA0B,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAWrE;;;;;;;;;OASG;IACG,+BAA+B,IAAI,OAAO,CAAC,0BAA0B,CAAC;CA+B7E"}

package/dist/src/services/FaucetService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FaucetService.d.ts","sourceRoot":"","sources":["../../../src/services/FaucetService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAI3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,mBAAmB,EAIpB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,IAAI,EAAE,UAAU,EAAE,SAAS,GAAE,OAAe;IAIxD;;;;;;;;;;;;;;;OAeG;IACG,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB/D;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;CAiBpC"}