@gala-chain/launchpad-sdk 3.31.2 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/API.md +524 -4
  2. package/CHANGELOG.md +92 -0
  3. package/EXAMPLES.md +845 -0
  4. package/README.md +421 -14
  5. package/dist/LaunchpadSDK.d.ts +435 -18
  6. package/dist/LaunchpadSDK.d.ts.map +1 -1
  7. package/dist/api/LaunchpadAPI.d.ts.map +1 -1
  8. package/dist/constants/version.generated.d.ts +1 -1
  9. package/dist/constants/version.generated.d.ts.map +1 -1
  10. package/dist/index.cjs.js +1 -1
  11. package/dist/index.d.ts +10 -3
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.esm.js +1 -1
  14. package/dist/index.js +1 -1
  15. package/dist/services/CommentService.d.ts.map +1 -1
  16. package/dist/services/DexBackendClient.d.ts +46 -0
  17. package/dist/services/DexBackendClient.d.ts.map +1 -0
  18. package/dist/services/DexPoolService.d.ts +54 -12
  19. package/dist/services/DexPoolService.d.ts.map +1 -1
  20. package/dist/services/DexQuoteService.d.ts +288 -0
  21. package/dist/services/DexQuoteService.d.ts.map +1 -0
  22. package/dist/services/GSwapService.d.ts +468 -38
  23. package/dist/services/GSwapService.d.ts.map +1 -1
  24. package/dist/services/GalaChainGatewayClient.d.ts +89 -0
  25. package/dist/services/GalaChainGatewayClient.d.ts.map +1 -0
  26. package/dist/services/GalaChainService.d.ts +26 -0
  27. package/dist/services/GalaChainService.d.ts.map +1 -1
  28. package/dist/services/PoolStateManager.d.ts +176 -0
  29. package/dist/services/PoolStateManager.d.ts.map +1 -0
  30. package/dist/services/SignatureService.d.ts +13 -35
  31. package/dist/services/SignatureService.d.ts.map +1 -1
  32. package/dist/services/WebSocketService.d.ts +98 -0
  33. package/dist/services/WebSocketService.d.ts.map +1 -1
  34. package/dist/services/__mocks__/logger.mock.d.ts +17 -0
  35. package/dist/services/__mocks__/logger.mock.d.ts.map +1 -0
  36. package/dist/types/common.d.ts +2 -0
  37. package/dist/types/common.d.ts.map +1 -1
  38. package/dist/types/composite-pool.dto.d.ts +103 -0
  39. package/dist/types/composite-pool.dto.d.ts.map +1 -0
  40. package/dist/types/dex-pool.dto.d.ts +56 -5
  41. package/dist/types/dex-pool.dto.d.ts.map +1 -1
  42. package/dist/types/dto.d.ts +6 -6
  43. package/dist/types/dto.d.ts.map +1 -1
  44. package/dist/types/eip712-types.d.ts +140 -0
  45. package/dist/types/eip712-types.d.ts.map +1 -0
  46. package/dist/types/galachain-api.types.d.ts +206 -0
  47. package/dist/types/galachain-api.types.d.ts.map +1 -0
  48. package/dist/types/gswap-responses.types.d.ts +366 -0
  49. package/dist/types/gswap-responses.types.d.ts.map +1 -0
  50. package/dist/types/gswap.dto.d.ts +58 -3
  51. package/dist/types/gswap.dto.d.ts.map +1 -1
  52. package/dist/types/launchpad.dto.d.ts +57 -0
  53. package/dist/types/launchpad.dto.d.ts.map +1 -1
  54. package/dist/types/pool-state-delta.dto.d.ts +246 -0
  55. package/dist/types/pool-state-delta.dto.d.ts.map +1 -0
  56. package/dist/types/pool-state-manager-config.dto.d.ts +103 -0
  57. package/dist/types/pool-state-manager-config.dto.d.ts.map +1 -0
  58. package/dist/utils/auto-pagination.d.ts +74 -0
  59. package/dist/utils/auto-pagination.d.ts.map +1 -1
  60. package/dist/utils/bignumber-helpers.d.ts +75 -3
  61. package/dist/utils/bignumber-helpers.d.ts.map +1 -1
  62. package/dist/utils/bignumber-pool-cache.d.ts +169 -0
  63. package/dist/utils/bignumber-pool-cache.d.ts.map +1 -0
  64. package/dist/utils/composite-pool-converter.d.ts +121 -0
  65. package/dist/utils/composite-pool-converter.d.ts.map +1 -0
  66. package/dist/utils/errors.d.ts +86 -0
  67. package/dist/utils/errors.d.ts.map +1 -1
  68. package/dist/utils/http.d.ts.map +1 -1
  69. package/dist/utils/load-env.d.ts +31 -0
  70. package/dist/utils/load-env.d.ts.map +1 -0
  71. package/dist/utils/pool-pair-parser.d.ts +55 -0
  72. package/dist/utils/pool-pair-parser.d.ts.map +1 -0
  73. package/dist/utils/pool-state-validator.d.ts +207 -0
  74. package/dist/utils/pool-state-validator.d.ts.map +1 -0
  75. package/dist/utils/position-filters.d.ts +253 -0
  76. package/dist/utils/position-filters.d.ts.map +1 -0
  77. package/dist/utils/swap-delta-calculator.d.ts +231 -0
  78. package/dist/utils/swap-delta-calculator.d.ts.map +1 -0
  79. package/dist/utils/tick-crossing-handler.d.ts +250 -0
  80. package/dist/utils/tick-crossing-handler.d.ts.map +1 -0
  81. package/dist/utils/token-format-converter.d.ts +10 -3
  82. package/dist/utils/token-format-converter.d.ts.map +1 -1
  83. package/dist/utils/token-parser.d.ts +235 -0
  84. package/dist/utils/token-parser.d.ts.map +1 -0
  85. package/dist/utils/transfer-validation.d.ts.map +1 -1
  86. package/package.json +36 -15
@@ -0,0 +1,207 @@
1
+ /**
2
+ * Pool State Validator
3
+ *
4
+ * Multi-tier validation system for detecting state drift and triggering refetches.
5
+ * Implements three validation levels:
6
+ * - Tier 1: Fast validation (<5ms) - Always run on every swap delta
7
+ * - Tier 2: Moderate validation (~10-15ms) - Run periodically with chain data comparison
8
+ * - Tier 3: Full validation (~50-100ms) - Compare cached state with fresh network fetch
9
+ *
10
+ * @packageDocumentation
11
+ */
12
+ import { Pool } from '@gala-chain/dex';
13
+ import BigNumber from 'bignumber.js';
14
+ import type { SwapEventData, PoolStateValidationResult } from '../types/pool-state-delta.dto';
15
+ import type { CompositePoolDataResult } from '../types/composite-pool.dto';
16
+ /**
17
+ * Configuration for pool state validation
18
+ *
19
+ * @category Pool State
20
+ */
21
+ export interface PoolStateValidationConfig {
22
+ /**
23
+ * Maximum acceptable drift percentage before triggering refetch
24
+ * @default 0.001 (0.1%)
25
+ */
26
+ maxDriftThreshold: number;
27
+ /**
28
+ * Maximum liquidity change percentage allowed in single swap
29
+ * @default 0.5 (50%)
30
+ */
31
+ maxLiquidityChangePct: number;
32
+ /**
33
+ * Maximum tick drift allowed between tick and calculated tick from sqrtPrice
34
+ * @default 1 (allow 1 tick rounding error)
35
+ */
36
+ maxTickDrift: number;
37
+ /**
38
+ * Maximum tick count difference percentage for full validation
39
+ * @default 0.1 (10%)
40
+ */
41
+ maxTickCountDriftPct: number;
42
+ /**
43
+ * Maximum price drift percentage for full validation
44
+ * @default 0.001 (0.1%)
45
+ */
46
+ maxPriceDriftPct: number;
47
+ /**
48
+ * Maximum liquidity drift percentage for full validation
49
+ * @default 0.01 (1.0%)
50
+ */
51
+ maxLiquidityDriftPct: number;
52
+ }
53
+ /**
54
+ * Three-tier pool state validation system
55
+ *
56
+ * Provides fast, moderate, and full validation strategies for detecting
57
+ * state drift in cached DEX pool data.
58
+ *
59
+ * @category Pool State
60
+ */
61
+ export declare class PoolStateValidator {
62
+ private static readonly logger;
63
+ /**
64
+ * Default validation configuration
65
+ */
66
+ static readonly DEFAULT_CONFIG: PoolStateValidationConfig;
67
+ /**
68
+ * Tier 1: Fast validation (<5ms)
69
+ *
70
+ * Quick sanity checks run on EVERY swap delta application.
71
+ * Detects obvious calculation errors immediately without expensive operations.
72
+ *
73
+ * Checks:
74
+ * 1. Price moved in correct direction based on swap direction
75
+ * 2. Liquidity didn't change drastically (>50% in one swap)
76
+ * 3. Fee growth never decreased (monotonically increasing)
77
+ * 4. Protocol fees only increased
78
+ *
79
+ * @param originalPool Original pool state before swap
80
+ * @param updatedPool Pool state after applying swap delta
81
+ * @param swapEvent The swap event that was applied
82
+ * @param config Optional validation configuration
83
+ * @returns true if all critical checks pass, false if errors detected
84
+ *
85
+ * @example
86
+ * ```typescript
87
+ * const isValid = PoolStateValidator.fastValidation(
88
+ * originalPool,
89
+ * updatedPool,
90
+ * swapEvent
91
+ * );
92
+ *
93
+ * if (!isValid) {
94
+ * console.error('Fast validation failed - immediate refetch recommended');
95
+ * }
96
+ * ```
97
+ */
98
+ static fastValidation(originalPool: Pool, updatedPool: Pool, swapEvent: SwapEventData, config?: PoolStateValidationConfig): boolean;
99
+ /**
100
+ * Tier 2: Moderate validation (~10-15ms)
101
+ *
102
+ * More expensive validation with actual value comparisons.
103
+ * Run periodically (e.g., every 10 swaps) or manually.
104
+ * Compares calculated state with actual chain data when available.
105
+ *
106
+ * Checks:
107
+ * 1. Compare calculated sqrtPrice with actual chain data (if provided)
108
+ * 2. Verify tick/price consistency
109
+ * 3. Ensure fee growth is monotonic
110
+ * 4. Validate liquidity is positive
111
+ *
112
+ * @param updatedPool Pool state from calculation
113
+ * @param swapEvent Original swap event (may contain actual chain data)
114
+ * @param config Optional validation configuration
115
+ * @returns Detailed validation result with drift detection
116
+ *
117
+ * @example
118
+ * ```typescript
119
+ * const result = PoolStateValidator.moderateValidation(
120
+ * updatedPool,
121
+ * swapEvent,
122
+ * { maxDriftThreshold: 0.001 }
123
+ * );
124
+ *
125
+ * if (result.shouldRefetch) {
126
+ * console.log(`Refetch recommended: ${result.refetchReason}`);
127
+ * console.log(`Drift: ${result.driftPercentage}%`);
128
+ * }
129
+ * ```
130
+ */
131
+ static moderateValidation(updatedPool: Pool, swapEvent: SwapEventData, config?: PoolStateValidationConfig): PoolStateValidationResult;
132
+ /**
133
+ * Tier 3: Full validation (~50-100ms)
134
+ *
135
+ * Complete validation by fetching fresh chain data and comparing.
136
+ * Only run when other validations suggest drift or on-demand.
137
+ * This is expensive (~50-100ms) so use sparingly.
138
+ *
139
+ * Compares:
140
+ * 1. Price drift between cached and fresh data
141
+ * 2. Liquidity drift between cached and fresh data
142
+ * 3. Tick data completeness (missing ticks in cache)
143
+ *
144
+ * @param poolKey Pool identifier for logging
145
+ * @param cachedPoolData Current cached pool state
146
+ * @param fetchFn Async function that fetches fresh pool data from chain
147
+ * @returns Detailed validation result with drift analysis
148
+ *
149
+ * @example
150
+ * ```typescript
151
+ * const result = await PoolStateValidator.fullValidation(
152
+ * 'GALA-BENE-3000',
153
+ * cachedPoolData,
154
+ * async () => await sdk.fetchCompositePoolData({
155
+ * token0: 'GALA|Unit|none|none',
156
+ * token1: 'Token|Unit|BENE|client:123',
157
+ * fee: 3000
158
+ * })
159
+ * );
160
+ *
161
+ * if (result.shouldRefetch) {
162
+ * // Use fresh data from fetchFn result
163
+ * console.log(`Validation errors: ${result.validationErrors}`);
164
+ * }
165
+ * ```
166
+ */
167
+ static fullValidation(poolKey: string, cachedPoolData: CompositePoolDataResult, fetchFn: () => Promise<CompositePoolDataResult>): Promise<PoolStateValidationResult>;
168
+ /**
169
+ * Calculate percentage difference between two values
170
+ *
171
+ * @param calculated Calculated/cached value
172
+ * @param actual Actual chain value
173
+ * @returns Percentage difference (0.5 = 0.5%)
174
+ *
175
+ * @example
176
+ * ```typescript
177
+ * const drift = PoolStateValidator.calculateDriftPercentage(
178
+ * new BigNumber('1000'),
179
+ * new BigNumber('1005')
180
+ * );
181
+ * console.log(`Drift: ${drift}%`); // "Drift: 0.5%"
182
+ * ```
183
+ */
184
+ static calculateDriftPercentage(calculated: BigNumber, actual: BigNumber): number;
185
+ /**
186
+ * Build a PoolStateValidationResult object
187
+ *
188
+ * @param isValid Whether validation passed
189
+ * @param driftPercentage Drift detected (as percentage)
190
+ * @param shouldRefetch Whether refetch is recommended
191
+ * @param errors Array of error messages
192
+ * @returns Structured validation result
193
+ *
194
+ * @example
195
+ * ```typescript
196
+ * const result = PoolStateValidator.buildValidationResult(
197
+ * false,
198
+ * 1.5,
199
+ * true,
200
+ * ['Price drift exceeded threshold']
201
+ * );
202
+ * console.log(result.refetchReason); // 'drift'
203
+ * ```
204
+ */
205
+ static buildValidationResult(isValid: boolean, driftPercentage: number, shouldRefetch: boolean, errors?: string[]): PoolStateValidationResult;
206
+ }
207
+ //# sourceMappingURL=pool-state-validator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pool-state-validator.d.ts","sourceRoot":"","sources":["../../src/utils/pool-state-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC,OAAO,SAAS,MAAM,cAAc,CAAC;AAErC,OAAO,KAAK,EACV,aAAa,EACb,yBAAyB,EAC1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAG3E;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAG3B;IAEH;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,yBAAyB,CAOvD;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,cAAc,CACnB,YAAY,EAAE,IAAI,EAClB,WAAW,EAAE,IAAI,EACjB,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,yBAA6D,GACpE,OAAO;IAmHV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,MAAM,CAAC,kBAAkB,CACvB,WAAW,EAAE,IAAI,EACjB,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,yBAA6D,GACpE,yBAAyB;IA4E5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;WACU,cAAc,CACzB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,uBAAuB,EACvC,OAAO,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,GAC9C,OAAO,CAAC,yBAAyB,CAAC;IA4ErC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,wBAAwB,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM;IAYjF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,qBAAqB,CAC1B,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,OAAO,EACtB,MAAM,GAAE,MAAM,EAAO,GACpB,yBAAyB;CAsC7B"}
@@ -0,0 +1,253 @@
1
+ /**
2
+ * Liquidity position filter utilities
3
+ *
4
+ * Helper functions for filtering and grouping liquidity positions by various criteria:
5
+ * - Liquidity amount and thresholds
6
+ * - Token pairs and individual tokens
7
+ * - Fee tiers
8
+ * - Pool identifiers (token0|token1|feeTier)
9
+ *
10
+ * All functions are pure and return new arrays/maps without mutating input.
11
+ *
12
+ * @example
13
+ * ```typescript
14
+ * import { filterByLiquidity, groupByTokenPair } from '@gala-chain/launchpad-sdk';
15
+ *
16
+ * const positions = await sdk.getAllSwapUserLiquidityPositions(address);
17
+ * const active = filterByLiquidity(positions); // Remove zero-liquidity positions
18
+ * const grouped = groupByTokenPair(active); // Organize by GALA/GUSDC, etc.
19
+ * ```
20
+ */
21
+ import BigNumber from 'bignumber.js';
22
+ import type { LiquidityPosition } from '../types/gswap.dto';
23
+ /**
24
+ * Sort order for position arrays
25
+ */
26
+ export type SortOrder = 'asc' | 'desc';
27
+ /**
28
+ * Predicate function for filtering positions
29
+ */
30
+ export type PositionFilter = (position: LiquidityPosition) => boolean;
31
+ /**
32
+ * Options for position filtering operations
33
+ */
34
+ export interface PositionFilterOptions {
35
+ /** Minimum liquidity threshold */
36
+ minLiquidity?: string;
37
+ /** Fee tier to filter by (500, 3000, or 10000) */
38
+ feeTier?: number;
39
+ /** Token symbol to filter by (either token0 or token1) */
40
+ token?: string;
41
+ }
42
+ /**
43
+ * Filter positions to only those with non-zero liquidity
44
+ *
45
+ * Removes positions with `liquidity === '0'`, typically indicating
46
+ * closed or inactive positions.
47
+ *
48
+ * @param positions Array of liquidity positions
49
+ * @returns Filtered array with only positions that have liquidity > 0
50
+ *
51
+ * @example
52
+ * ```typescript
53
+ * const allPositions = await sdk.getAllSwapUserLiquidityPositions(address);
54
+ * const activePositions = filterByLiquidity(allPositions);
55
+ * console.log(`Active positions: ${activePositions.length}`);
56
+ * ```
57
+ */
58
+ export declare function filterByLiquidity(positions: LiquidityPosition[]): LiquidityPosition[];
59
+ /**
60
+ * Filter positions by minimum liquidity threshold
61
+ *
62
+ * Keeps only positions with `liquidity >= minLiquidity`. Useful for
63
+ * finding significant positions or filtering out dust positions.
64
+ *
65
+ * @param positions Array of liquidity positions
66
+ * @param minLiquidity Minimum liquidity amount (as string for precision)
67
+ * @returns Filtered array with positions >= minLiquidity
68
+ *
69
+ * @example
70
+ * ```typescript
71
+ * const largePositions = filterByMinLiquidity(positions, '1000');
72
+ * // Only positions with liquidity >= 1000
73
+ *
74
+ * const hugePositions = filterByMinLiquidity(positions, '100000');
75
+ * // Find whale positions
76
+ * ```
77
+ */
78
+ export declare function filterByMinLiquidity(positions: LiquidityPosition[], minLiquidity: string | number | BigNumber): LiquidityPosition[];
79
+ /**
80
+ * Sort positions by liquidity amount
81
+ *
82
+ * @param positions Array of liquidity positions
83
+ * @param order Sort order: 'desc' (default, highest first) or 'asc' (lowest first)
84
+ * @returns Sorted array (creates new array, doesn't mutate input)
85
+ *
86
+ * @example
87
+ * ```typescript
88
+ * const sorted = sortByLiquidity(positions, 'desc');
89
+ * const topPosition = sorted[0]; // Largest liquidity position
90
+ *
91
+ * const lowest = sortByLiquidity(positions, 'asc');
92
+ * const smallest = lowest[0]; // Smallest liquidity position
93
+ * ```
94
+ */
95
+ export declare function sortByLiquidity(positions: LiquidityPosition[], order?: SortOrder): LiquidityPosition[];
96
+ /**
97
+ * Filter positions by exact token pair match
98
+ *
99
+ * Matches token0 and token1 in either order. Comparison is case-insensitive.
100
+ *
101
+ * @param positions Array of liquidity positions
102
+ * @param token0 First token symbol (e.g., "GALA")
103
+ * @param token1 Second token symbol (e.g., "GUSDC")
104
+ * @returns Positions matching the token pair
105
+ *
106
+ * @example
107
+ * ```typescript
108
+ * const galaPositions = filterByTokenPair(positions, 'GALA', 'GUSDC');
109
+ * // Returns positions for GALA/GUSDC pair (in either order)
110
+ *
111
+ * const reverseMatch = filterByTokenPair(positions, 'GUSDC', 'GALA');
112
+ * // Also returns GALA/GUSDC positions (same result as above)
113
+ * ```
114
+ */
115
+ export declare function filterByTokenPair(positions: LiquidityPosition[], token0: string, token1: string): LiquidityPosition[];
116
+ /**
117
+ * Filter positions by a single token (either side of the pair)
118
+ *
119
+ * Finds all positions where the token appears as either token0 or token1.
120
+ * Comparison is case-insensitive.
121
+ *
122
+ * @param positions Array of liquidity positions
123
+ * @param token Token symbol to search for (e.g., "GALA")
124
+ * @returns Positions containing the specified token
125
+ *
126
+ * @example
127
+ * ```typescript
128
+ * const galaPositions = filterByToken(positions, 'GALA');
129
+ * // Returns GALA/GUSDC, GALA/ETH, ETH/GALA, etc.
130
+ *
131
+ * const stablecoinPositions = filterByToken(positions, 'GUSDC');
132
+ * // Any position with GUSDC on either side
133
+ * ```
134
+ */
135
+ export declare function filterByToken(positions: LiquidityPosition[], token: string): LiquidityPosition[];
136
+ /**
137
+ * Filter positions by fee tier
138
+ *
139
+ * Finds positions using a specific fee tier (0.05%, 0.30%, or 1.00%).
140
+ *
141
+ * @param positions Array of liquidity positions
142
+ * @param feeTier Fee tier in basis points (500 = 0.05%, 3000 = 0.30%, 10000 = 1.00%)
143
+ * @returns Positions with the specified fee tier
144
+ *
145
+ * @example
146
+ * ```typescript
147
+ * const lowFee = filterByFeeTier(positions, 500); // 0.05% - Best for stablecoins
148
+ * const mid = filterByFeeTier(positions, 3000); // 0.30% - Standard
149
+ * const highFee = filterByFeeTier(positions, 10000); // 1.00% - Volatile pairs
150
+ * ```
151
+ */
152
+ export declare function filterByFeeTier(positions: LiquidityPosition[], feeTier: number): LiquidityPosition[];
153
+ /**
154
+ * Group positions by token pair
155
+ *
156
+ * Creates a Map keyed by "TOKEN0/TOKEN1" containing arrays of positions
157
+ * for that pair. The pair key format is always uppercase with "/" separator.
158
+ *
159
+ * @param positions Array of liquidity positions
160
+ * @returns Map<pair_string, positions[]> where pair_string is "TOKEN0/TOKEN1"
161
+ *
162
+ * @example
163
+ * ```typescript
164
+ * const grouped = groupByTokenPair(positions);
165
+ *
166
+ * // Access positions for specific pairs
167
+ * const galusdcPos = grouped.get('GALA/GUSDC');
168
+ * const galaethPos = grouped.get('GALA/ETH');
169
+ *
170
+ * // Iterate over all pairs
171
+ * grouped.forEach((positions, pair) => {
172
+ * console.log(`${pair}: ${positions.length} positions`);
173
+ * });
174
+ * ```
175
+ */
176
+ export declare function groupByTokenPair(positions: LiquidityPosition[]): Map<string, LiquidityPosition[]>;
177
+ /**
178
+ * Group positions by fee tier
179
+ *
180
+ * Creates a Map keyed by fee tier (500, 3000, 10000) containing arrays
181
+ * of positions using that fee tier.
182
+ *
183
+ * @param positions Array of liquidity positions
184
+ * @returns Map<feeTier, positions[]>
185
+ *
186
+ * @example
187
+ * ```typescript
188
+ * const byFee = groupByFeeTier(positions);
189
+ *
190
+ * const stablecoinPos = byFee.get(500); // 0.05% fee tier
191
+ * const standardPos = byFee.get(3000); // 0.30% fee tier
192
+ * const volatilePos = byFee.get(10000); // 1.00% fee tier
193
+ *
194
+ * // Fee tier statistics
195
+ * byFee.forEach((positions, feeTier) => {
196
+ * const feePercent = feeTier / 100;
197
+ * console.log(`${feePercent}%: ${positions.length} positions`);
198
+ * });
199
+ * ```
200
+ */
201
+ export declare function groupByFeeTier(positions: LiquidityPosition[]): Map<number, LiquidityPosition[]>;
202
+ /**
203
+ * Filter positions by complete pool identifier
204
+ *
205
+ * Matches positions that belong to a specific pool identified by
206
+ * token0, token1, and fee tier. Comparison is case-insensitive for tokens.
207
+ *
208
+ * @param positions Array of liquidity positions
209
+ * @param token0 First token symbol
210
+ * @param token1 Second token symbol
211
+ * @param feeTier Fee tier (500, 3000, or 10000)
212
+ * @returns Positions matching the specific pool
213
+ *
214
+ * @example
215
+ * ```typescript
216
+ * // Find all positions in the GALA/GUSDC 0.30% pool
217
+ * const poolPositions = filterByPoolKey(positions, 'GALA', 'GUSDC', 3000);
218
+ *
219
+ * // Calculate total liquidity in a specific pool
220
+ * const totalLiq = poolPositions
221
+ * .reduce((sum, pos) => sum + BigInt(pos.liquidity), 0n);
222
+ * ```
223
+ */
224
+ export declare function filterByPoolKey(positions: LiquidityPosition[], token0: string, token1: string, feeTier: number): LiquidityPosition[];
225
+ /**
226
+ * Group positions by pool identifier (token pair + fee tier)
227
+ *
228
+ * Creates a Map keyed by "token0|token1|feeTier" containing arrays of
229
+ * positions in that specific pool. Useful for analyzing pool-specific metrics.
230
+ *
231
+ * @param positions Array of liquidity positions
232
+ * @returns Map<pool_key, positions[]> where pool_key is "TOKEN0|TOKEN1|FEETIER"
233
+ *
234
+ * @example
235
+ * ```typescript
236
+ * const byPool = groupByPoolKey(positions);
237
+ *
238
+ * // Access positions in specific pool
239
+ * const galusdcStandard = byPool.get('GALA|GUSDC|3000');
240
+ *
241
+ * // Calculate pool statistics
242
+ * byPool.forEach((positions, poolKey) => {
243
+ * const [token0, token1, feeTier] = poolKey.split('|');
244
+ * const total = positions.reduce(
245
+ * (sum, pos) => sum.plus(pos.liquidity),
246
+ * new BigNumber(0)
247
+ * );
248
+ * console.log(`${poolKey}: ${positions.length} LPs, ${total} total liquidity`);
249
+ * });
250
+ * ```
251
+ */
252
+ export declare function groupByPoolKey(positions: LiquidityPosition[]): Map<string, LiquidityPosition[]>;
253
+ //# sourceMappingURL=position-filters.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"position-filters.d.ts","sourceRoot":"","sources":["../../src/utils/position-filters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,SAAS,MAAM,cAAc,CAAC;AACrC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;AAEvC;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAErF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,iBAAiB,EAAE,EAC9B,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GACxC,iBAAiB,EAAE,CAGrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAAE,EAC9B,KAAK,GAAE,SAAkB,GACxB,iBAAiB,EAAE,CAOrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,iBAAiB,EAAE,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,iBAAiB,EAAE,CASrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAGhG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAAE,EAC9B,OAAO,EAAE,MAAM,GACd,iBAAiB,EAAE,CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAYjG;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAW/F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAAE,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,iBAAiB,EAAE,CAUrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAY/F"}