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

package/API.md

@@ -2,17 +2,21 @@
 
 Complete API documentation for the Gala Launchpad SDK (v3.23.0+).
 
+> **⚠️ BREAKING CHANGE (v3.33.0+)**: Token format parsing now **ONLY accepts delimited formats**. Plain token strings (`'GALA'`, `'GUSDC'`) are **permanently rejected** for security. Use delimited format: `'GALA|Unit|none|none'` or `'GALA$Unit$none$none'`. See README.md for [migration guide](./README.md#token-format-migration-v330).
+
 ## Table of Contents
 
 - [SDK Initialization](#sdk-initialization)
 - [Bonding Curve Trading (Launchpad Tokens)](#bonding-curve-trading)
 - [DEX Trading (Graduated Tokens)](#dex-trading-galaswap)
+- [GalaSwap Liquidity Position Management](#galaswap-liquidity-position-management)
 - [Pool Information](#pool-information)
 - [Token Management](#token-management)
 - [Portfolio & Balances](#portfolio--balances)
 - [Price History & Analytics](#price-history--analytics)
 - [Real-Time Features](#real-time-features)
 - [Type Definitions](#type-definitions)
+- [Error Handling](#error-handling)
 
 ---
 
@@ -244,8 +248,8 @@ Get a quote for swapping a known input amount on GalaSwap DEX.
 
 **Parameters:**
 ```typescript
-fromToken: string;  // Source token ("GALA", "GUSDC", or pipe-delimited format)
-toToken: string;    // Destination token ("GALA", "GUSDC", or pipe-delimited format)
+fromToken: string;  // Source token in delimited format (e.g., "GALA|Unit|none|none" or "GALA$Unit$none$none") - v3.33.0+ REQUIRED
+toToken: string;    // Destination token in delimited format (e.g., "GUSDC|Unit|none|none" or "GUSDC$Unit$none$none") - v3.33.0+ REQUIRED
 amount: string;     // Input amount (how much fromToken to spend)
 ```
 
@@ -262,8 +266,8 @@ amount: string;     // Input amount (how much fromToken to spend)
 
 **Example:**
 ```typescript
-// How many GUSDC for 100 GALA?
-const quote = await sdk.getSwapQuoteExactInput('GALA', 'GUSDC', '100');
+// How many GUSDC for 100 GALA? (v3.33.0+ requires delimited token format)
+const quote = await sdk.getSwapQuoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100');
 console.log(`Spend: 100 GALA`);
 console.log(`Receive: ~${quote.estimatedOutput} GUSDC`);
 console.log(`Price impact: ${(quote.priceImpact * 100).toFixed(2)}%`);
@@ -406,6 +410,418 @@ console.log(`Fee tiers: ${pool.feeTiers.map(t => t / 100 + '%').join(', ')}`);
 
 ---
 
+## GalaSwap Liquidity Position Management
+
+Provide liquidity to DEX pools and earn trading fees. Liquidity positions enable passive income through fee accumulation while helping maintain DEX liquidity.
+
+### `getAllSwapUserLiquidityPositions(ownerAddress)`
+
+Get **all** open liquidity positions for a wallet with automatic pagination (recommended).
+
+**Parameters:**
+```typescript
+ownerAddress: string;  // Wallet address (e.g., "0x1234..." or "eth|1234...")
+```
+
+**Returns:**
+```typescript
+Array<{
+  positionId: string;      // Unique position identifier
+  token0: string;          // First token symbol
+  token1: string;          // Second token symbol
+  feeTier: number;         // Fee tier in basis points
+  liquidity: string;       // Liquidity amount
+  amount0: string;         // Token0 amount in position
+  amount1: string;         // Token1 amount in position
+  feeAmount0: string;      // Accumulated fees (Token0)
+  feeAmount1: string;      // Accumulated fees (Token1)
+  tickLower: number;       // Lower tick boundary
+  tickUpper: number;       // Upper tick boundary
+}>
+```
+
+**Example:**
+```typescript
+// Fetch all positions with automatic pagination
+const allPositions = await sdk.getAllSwapUserLiquidityPositions('eth|0x...');
+
+console.log(`Total positions: ${allPositions.length}`);
+
+// Analyze positions
+allPositions.forEach(pos => {
+  console.log(`${pos.token0}/${pos.token1}: ${pos.liquidity} liquidity`);
+  console.log(`Fees earned: ${pos.feeAmount0} ${pos.token0}, ${pos.feeAmount1} ${pos.token1}`);
+});
+
+// Find best-performing position (highest accumulated fees)
+const bestPosition = allPositions.reduce((best, current) => {
+  const currentFees = parseFloat(current.feeAmount0) + parseFloat(current.feeAmount1);
+  const bestFees = parseFloat(best.feeAmount0) + parseFloat(best.feeAmount1);
+  return currentFees > bestFees ? current : best;
+});
+console.log(`Best position: ${bestPosition.token0}/${bestPosition.token1}`);
+```
+
+### `getSwapUserLiquidityPositions(ownerAddress, limit?, bookmark?)`
+
+Get open liquidity positions with manual pagination control (paginated version).
+
+**Parameters:**
+```typescript
+ownerAddress: string;     // Wallet address
+limit?: number;           // Results per page (default: 10, max: 20)
+bookmark?: string;        // Pagination bookmark from previous response
+```
+
+**Returns:** Same array structure as getAllSwapUserLiquidityPositions, plus pagination metadata:
+```typescript
+{
+  positions: Array<...>;  // Array of position objects
+  bookmark?: string;      // Bookmark for next page (if more results exist)
+  hasMore: boolean;       // True if more pages available
+  total: number;          // Total positions
+}
+```
+
+**Example:**
+```typescript
+// Paginated retrieval for streaming/processing
+let allPositions = [];
+let bookmark;
+let hasMore = true;
+
+while (hasMore) {
+  const page = await sdk.getSwapUserLiquidityPositions('eth|0x...', 10, bookmark);
+  allPositions = allPositions.concat(page.positions);
+  hasMore = !!page.bookmark;
+  bookmark = page.bookmark;
+  console.log(`Fetched page: ${page.positions.length} positions`);
+}
+
+console.log(`Total fetched: ${allPositions.length}`);
+```
+
+### `getSwapLiquidityPositionById(ownerAddress, positionId)`
+
+Get a specific liquidity position by its ID.
+
+**Parameters:**
+```typescript
+ownerAddress: string;     // Wallet address
+positionId: string;       // Position UUID
+```
+
+**Returns:** Single position object (same structure as above)
+
+**Example:**
+```typescript
+const position = await sdk.getSwapLiquidityPositionById('eth|0x...', 'position-uuid');
+
+console.log(`Position: ${position.token0}/${position.token1}`);
+console.log(`Liquidity: ${position.liquidity}`);
+console.log(`Accumulated fees: ${position.feeAmount0} + ${position.feeAmount1}`);
+```
+
+### `getSwapLiquidityPosition(ownerAddress, token0, token1, fee, tickLower, tickUpper)`
+
+Get a liquidity position by token pair and price range.
+
+**Parameters:**
+```typescript
+ownerAddress: string;  // Wallet address
+token0: string;        // First token
+token1: string;        // Second token
+fee: number;           // Fee tier (500, 3000, or 10000)
+tickLower: number;     // Lower tick boundary
+tickUpper: number;     // Upper tick boundary
+```
+
+**Returns:** Single position object
+
+**Example:**
+```typescript
+const position = await sdk.getSwapLiquidityPosition(
+  'eth|0x...',
+  'GALA',
+  'GUSDC',
+  3000,
+  -1000,
+  1000
+);
+
+console.log(`Active: ${position.liquidity > 0}`);
+```
+
+### `getSwapEstimateRemoveLiquidity(token0, token1, fee, liquidity, tickLower, tickUpper)`
+
+Estimate tokens and fees you'll receive when removing liquidity.
+
+**Parameters:**
+```typescript
+token0: string;        // First token
+token1: string;        // Second token
+fee: number;           // Fee tier
+liquidity: string;     // Liquidity amount to remove
+tickLower: number;     // Lower tick
+tickUpper: number;     // Upper tick
+```
+
+**Returns:**
+```typescript
+{
+  amount0: string;       // Token0 amount to receive
+  amount1: string;       // Token1 amount to receive
+  fee0: string;          // Collected fees (Token0)
+  fee1: string;          // Collected fees (Token1)
+  feeAmount0: string;    // Same as fee0
+  feeAmount1: string;    // Same as fee1
+  token0Symbol: string;  // Token0 symbol
+  token1Symbol: string;  // Token1 symbol
+}
+```
+
+**Example:**
+```typescript
+// Preview removal before executing
+const estimate = await sdk.getSwapEstimateRemoveLiquidity(
+  'GALA',
+  'GUSDC',
+  3000,
+  position.liquidity,
+  position.tickLower,
+  position.tickUpper
+);
+
+console.log(`Will receive: ${estimate.amount0} GALA, ${estimate.amount1} GUSDC`);
+console.log(`Collected fees: ${estimate.feeAmount0} GALA, ${estimate.feeAmount1} GUSDC`);
+```
+
+### `addSwapLiquidityByPrice(token0, token1, fee, minPrice, maxPrice, amount0Desired, amount1Desired, amount0Min?, amount1Min?)`
+
+Add liquidity by specifying a price range (user-friendly approach).
+
+**Parameters:**
+```typescript
+token0: string;          // First token
+token1: string;          // Second token
+fee: number;             // Fee tier (500, 3000, or 10000)
+minPrice: string;        // Minimum price (e.g., "0.95")
+maxPrice: string;        // Maximum price (e.g., "1.05")
+amount0Desired: string;  // Desired Token0 amount to provide
+amount1Desired: string;  // Desired Token1 amount to provide
+amount0Min?: string;     // Minimum Token0 (slippage protection, default: "0")
+amount1Min?: string;     // Minimum Token1 (slippage protection, default: "0")
+```
+
+**Returns:**
+```typescript
+{
+  transactionId: string;
+  status: 'PENDING' | 'COMPLETED' | 'FAILED';
+  positionId: string;    // New position ID
+  liquidity: string;     // Liquidity amount provided
+  amount0Used: string;   // Actual Token0 used
+  amount1Used: string;   // Actual Token1 used
+  wait(): Promise<TransactionResult>;
+}
+```
+
+**Example:**
+```typescript
+// Create position with 0.95-1.05 price range
+const result = await sdk.addSwapLiquidityByPrice({
+  token0: 'GALA',
+  token1: 'GUSDC',
+  fee: 3000,          // 0.30% fee tier
+  minPrice: '0.95',   // Active when price between 0.95-1.05
+  maxPrice: '1.05',
+  amount0Desired: '100',   // Provide 100 GALA
+  amount1Desired: '100',   // Provide 100 GUSDC
+  amount0Min: '95',        // Accept at least 95 GALA
+  amount1Min: '95'         // Accept at least 95 GUSDC
+});
+
+console.log(`Position created: ${result.positionId}`);
+console.log(`Liquidity provided: ${result.liquidity}`);
+
+// Wait for confirmation
+await result.wait();
+```
+
+### `addSwapLiquidityByTicks(token0, token1, feeTier, tickLower, tickUpper, amount0Desired, amount1Desired, amount0Min?, amount1Min?)`
+
+Add liquidity by specifying exact tick boundaries (advanced users).
+
+**Parameters:**
+```typescript
+token0: string;          // First token
+token1: string;          // Second token
+feeTier: number;         // Fee tier (500, 3000, or 10000)
+tickLower: number;       // Lower tick (must align with tickSpacing)
+tickUpper: number;       // Upper tick (must align with tickSpacing)
+amount0Desired: string;  // Desired Token0 amount
+amount1Desired: string;  // Desired Token1 amount
+amount0Min?: string;     // Minimum Token0 (default: "0")
+amount1Min?: string;     // Minimum Token1 (default: "0")
+```
+
+**Returns:** Same as addSwapLiquidityByPrice
+
+**Example:**
+```typescript
+// Create position with exact tick boundaries (advanced)
+// Note: ticks must be multiples of tickSpacing (varies by fee tier)
+const result = await sdk.addSwapLiquidityByTicks({
+  token0: 'GALA',
+  token1: 'GUSDC',
+  feeTier: 3000,
+  tickLower: -1000,   // Exact tick
+  tickUpper: 1000,    // Exact tick
+  amount0Desired: '100',
+  amount1Desired: '100'
+});
+
+console.log(`Position ID: ${result.positionId}`);
+```
+
+### `removeSwapLiquidity(ownerAddress, positionId, liquidity, amount0Min, amount1Min, deadline?)`
+
+Remove liquidity from a position and withdraw underlying tokens.
+
+**Parameters:**
+```typescript
+ownerAddress: string;  // Wallet address
+positionId: string;    // Position ID to remove from
+liquidity: string;     // Liquidity amount to remove (use full amount to close)
+amount0Min: string;    // Minimum Token0 to receive (slippage protection)
+amount1Min: string;    // Minimum Token1 to receive (slippage protection)
+deadline?: number;     // Deadline timestamp (unix seconds, optional)
+```
+
+**Returns:**
+```typescript
+{
+  transactionId: string;
+  status: 'PENDING' | 'COMPLETED' | 'FAILED';
+  amount0Withdrawn: string;  // Token0 received
+  amount1Withdrawn: string;  // Token1 received
+  fee0Collected: string;     // Fees collected (Token0)
+  fee1Collected: string;     // Fees collected (Token1)
+  wait(): Promise<TransactionResult>;
+}
+```
+
+**Example:**
+```typescript
+// Preview removal before executing
+const estimate = await sdk.getSwapEstimateRemoveLiquidity(
+  position.token0,
+  position.token1,
+  position.feeTier,
+  position.liquidity,
+  position.tickLower,
+  position.tickUpper
+);
+
+// Remove full liquidity and close position
+const result = await sdk.removeSwapLiquidity({
+  ownerAddress: 'eth|0x...',
+  positionId: position.positionId,
+  liquidity: position.liquidity,
+  amount0Min: estimate.amount0,  // Use estimate values
+  amount1Min: estimate.amount1,
+  deadline: Math.floor(Date.now() / 1000) + 3600  // 1 hour from now
+});
+
+console.log(`Withdrawn: ${result.amount0Withdrawn} + ${result.amount1Withdrawn}`);
+console.log(`Fees collected: ${result.fee0Collected} + ${result.fee1Collected}`);
+```
+
+### `collectSwapPositionFees(ownerAddress, positionId, amount0Max?, amount1Max?)`
+
+Collect accumulated trading fees without closing the position.
+
+**Parameters:**
+```typescript
+ownerAddress: string;    // Wallet address
+positionId: string;      // Position ID
+amount0Max?: string;     // Maximum Token0 fees (optional)
+amount1Max?: string;     // Maximum Token1 fees (optional)
+```
+
+**Returns:**
+```typescript
+{
+  transactionId: string;
+  status: 'PENDING' | 'COMPLETED' | 'FAILED';
+  amount0Collected: string;  // Token0 fees collected
+  amount1Collected: string;  // Token1 fees collected
+  wait(): Promise<TransactionResult>;
+}
+```
+
+**Example:**
+```typescript
+// Collect fees periodically without removing liquidity
+const result = await sdk.collectSwapPositionFees({
+  ownerAddress: 'eth|0x...',
+  positionId: position.positionId
+});
+
+console.log(`Collected: ${result.amount0Collected} + ${result.amount1Collected}`);
+
+// Position remains active and continues earning fees
+```
+
+### Complete Liquidity Management Workflow
+
+```typescript
+// 1. View all positions
+const positions = await sdk.getAllSwapUserLiquidityPositions('eth|0x...');
+console.log(`You have ${positions.length} active positions`);
+
+// 2. Create new position
+const newPos = await sdk.addSwapLiquidityByPrice({
+  token0: 'GALA',
+  token1: 'GUSDC',
+  fee: 3000,
+  minPrice: '0.95',
+  maxPrice: '1.05',
+  amount0Desired: '1000',
+  amount1Desired: '1000'
+});
+
+await newPos.wait();
+console.log(`Position created: ${newPos.positionId}`);
+
+// 3. Monitor fees (periodically)
+setTimeout(async () => {
+  const position = await sdk.getSwapLiquidityPositionById('eth|0x...', newPos.positionId);
+  console.log(`Fees earned: ${position.feeAmount0} + ${position.feeAmount1}`);
+}, 3600000);  // Every hour
+
+// 4. Collect fees when ready
+const fees = await sdk.collectSwapPositionFees({
+  ownerAddress: 'eth|0x...',
+  positionId: newPos.positionId
+});
+
+console.log(`Harvested: ${fees.amount0Collected} + ${fees.amount1Collected}`);
+
+// 5. Close position when desired
+const removed = await sdk.removeSwapLiquidity({
+  ownerAddress: 'eth|0x...',
+  positionId: newPos.positionId,
+  liquidity: newPos.liquidity,
+  amount0Min: '0',
+  amount1Min: '0'
+});
+
+console.log(`Closed position, received: ${removed.amount0Withdrawn} + ${removed.amount1Withdrawn}`);
+```
+
+---
+
 ## Pool Information
 
 ### `fetchPoolDetails(tokenName)`
@@ -548,6 +964,81 @@ symbol: string;  // 1-8 uppercase characters
 }
 ```
 
+### `fetchTokenClassesWithSupply(tokenClasses)`
+
+Fetch authoritative supply information for one or more token classes from GalaChain.
+
+Queries the GalaChain network for definitive token supply data including total supply, maximum supply, burned amounts, and mint-related metrics. This method provides blockchain-verified token information.
+
+**Parameters:**
+```typescript
+tokenClasses: TokenClassKey[];  // Array of token class identifiers
+```
+
+**Returns:**
+```typescript
+Promise<Array<{
+  // Token Identification
+  collection: string;      // Token collection (e.g., 'Token')
+  category: string;        // Token category (e.g., 'Unit')
+  type: string;           // Token type (e.g., 'GALA', 'GUSDC')
+  additionalKey: string;  // Additional key/network (e.g., 'eth:0x...', 'none')
+
+  // Token Metadata
+  symbol: string;         // Token symbol
+  name: string;          // Token display name
+  decimals: number;      // Decimal precision
+
+  // Supply Information
+  totalSupply: string;             // Current total supply in circulation
+  maxSupply: string;               // Maximum possible supply
+  totalBurned: string;             // Total amount burned
+  knownMintSupply: string;         // Known mint supply
+  knownMintAllowanceSupply: string; // Known mint allowance
+}>>
+```
+
+**Example:**
+```typescript
+// Query single token
+const supplies = await sdk.fetchTokenClassesWithSupply([
+  {
+    collection: 'GALA',
+    category: 'Unit',
+    type: 'none',
+    additionalKey: 'none'
+  }
+]);
+
+console.log(`GALA Total Supply: ${supplies[0].totalSupply}`);
+console.log(`GALA Max Supply: ${supplies[0].maxSupply}`);
+console.log(`GALA Burned: ${supplies[0].totalBurned}`);
+
+// Query multiple tokens in one call
+const multiSupplies = await sdk.fetchTokenClassesWithSupply([
+  { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' },
+  { collection: 'GUSDC', category: 'Unit', type: 'none', additionalKey: 'none' }
+]);
+
+// Analyze supply metrics
+for (const token of multiSupplies) {
+  const circulationPercent = (parseFloat(token.totalSupply) / parseFloat(token.maxSupply)) * 100;
+  const burnPercent = (parseFloat(token.totalBurned) / parseFloat(token.totalSupply)) * 100;
+
+  console.log(`${token.symbol}:`);
+  console.log(`  Circulation: ${circulationPercent.toFixed(2)}% of max`);
+  console.log(`  Burned: ${burnPercent.toFixed(2)}% of total`);
+}
+```
+
+**Use Cases:**
+- Token supply tracking and dashboards
+- Burn rate analysis and monitoring
+- Mint allowance verification
+- Token health metrics and reporting
+- Supply distribution analysis
+- Compliance and audit reporting
+
 ---
 
 ## Portfolio & Balances
@@ -797,7 +1288,7 @@ tokenId: string | {
 
 **Example:**
 ```typescript
-const details = await sdk.fetchTokenDetails('Token|Unit|GUSDC|eth:0x...');
+const details = await sdk.fetchTokenDetails('GUSDC|Unit|none|eth:0x...');
 
 if (details.verified && details.tradingEnabled) {
   console.log(`${details.symbol}: ${details.name}`);
@@ -877,6 +1368,35 @@ interface TokenClassKey {
 }
 ```
 
+### TokenClassWithSupply
+```typescript
+interface TokenClassWithSupply {
+  // Token Identification
+  collection: string;      // Token collection (e.g., "Token")
+  category: string;        // Token category (e.g., "Unit")
+  type: string;           // Token type (e.g., "GALA", "GUSDC")
+  additionalKey: string;  // Network/chain info (e.g., "eth:0x...", "none")
+
+  // Token Metadata
+  symbol: string;         // Token symbol
+  name: string;          // Token display name
+  decimals: number;      // Decimal precision
+
+  // Supply Information
+  totalSupply: string;             // Current total supply in circulation
+  maxSupply: string;               // Maximum possible supply
+  totalBurned: string;             // Total amount burned
+  knownMintSupply: string;         // Known mint supply
+  knownMintAllowanceSupply: string; // Known mint allowance supply
+
+  // Optional Fields
+  authorities?: Array<{   // Optional token authorities
+    address?: string;     // Authority address
+    role?: string;       // Authority role/type
+  }>;
+}
+```
+
 ### TransactionResult
 ```typescript
 interface TransactionResult {