@gala-chain/launchpad-mcp-server 2.0.1 → 2.0.2-beta.2

package/dist/tools/utils/explainSdkUsage.js

@@ -6,17 +6,89 @@
  * Acts as a development reference showing how MCP tools map to SDK methods.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.explainSdkUsageTool = void 0;
+exports.explainSdkUsageTool = exports.COMPOSITE_TOPICS = exports.TOPIC_METHOD_MAPPING = void 0;
 const error_handler_js_1 = require("../../utils/error-handler.js");
 const response_formatter_js_1 = require("../../utils/response-formatter.js");
+/**
+ * Topic-to-method mapping for documentation validation
+ * Defines which SDK methods are covered by each documentation topic
+ */
+exports.TOPIC_METHOD_MAPPING = {
+    // Trading Workflows
+    'buy-tokens': ['calculateBuyAmount', 'buy'],
+    'sell-tokens': ['calculateSellAmount', 'sell'],
+    'pool-graduation': ['calculateBuyAmountForGraduation', 'graduateToken'],
+    // Pool Discovery
+    'fetch-pools': [
+        'fetchPools', 'fetchAllPools', 'fetchPoolDetails', 'fetchPoolDetailsForCalculation',
+        'fetchVolumeData', 'fetchTokenPrice', 'fetchLaunchpadTokenSpotPrice',
+        'fetchTokenDistribution', 'fetchTokenBadges', 'resolveVaultAddress', 'resolveTokenClassKey'
+    ],
+    'balances': ['fetchGalaBalance', 'fetchTokenBalance', 'fetchTokensHeld', 'fetchTokensCreated'],
+    // Token Creation & Management
+    'token-creation': ['isTokenNameAvailable', 'isTokenSymbolAvailable', 'fetchLaunchTokenFee', 'uploadTokenImage', 'launchToken'],
+    'token-details': ['fetchTokenDetails'],
+    'token-distribution': ['fetchTokenDistribution'],
+    // Portfolio Management
+    'multi-wallet': [], // Composite workflow topic
+    'transfers': ['transferGala', 'transferToken'],
+    'locks': ['lockToken', 'unlockToken'],
+    // DEX Trading
+    'dex-trading': ['getSwapQuoteExactInput', 'getSwapQuoteExactOutput', 'executeSwap', 'getSwapUserAssets', 'getAllSwapUserAssets', 'getSwapPoolInfo'],
+    'error-handling': [], // Cross-cutting concern
+    // Developer Tools
+    'installation': [], // Setup topic
+    'local-calculations': ['calculateBuyAmountLocal', 'calculateSellAmountLocal', 'calculateBuyAmountExternal', 'calculateSellAmountExternal', 'calculateInitialBuyAmount'],
+    // Market Data
+    'price-history': ['fetchPriceHistory', 'fetchAllPriceHistory'],
+    'spot-prices-smart-routing': ['fetchTokenPrice', 'getSwapPoolPrice'],
+    // User Profile & Social
+    'profile-management': ['fetchProfile', 'updateProfile', 'uploadProfileImage'],
+    'social-features': ['fetchComments', 'postComment'],
+    // Liquidity Management
+    'liquidity-positions': ['getSwapUserLiquidityPositions', 'getAllSwapUserLiquidityPositions', 'getSwapLiquidityPosition', 'getSwapLiquidityPositionById', 'addSwapLiquidityByPrice', 'addSwapLiquidityByTicks', 'getSwapEstimateRemoveLiquidity', 'removeSwapLiquidity', 'collectSwapPositionFees'],
+    // Advanced Analysis & Social
+    'advanced-dex-analysis': ['fetchCompositePoolData', 'calculateDexPoolQuoteExactAmountLocal', 'calculateDexPoolQuoteExactAmountExternal', 'calculateDexPoolQuoteExactAmount'],
+    'trading-analytics': ['fetchTrades'],
+    'utilities-and-helpers': ['fetchGalaPrice', 'fetchTokenClassesWithSupply', 'calculateInitialBuyAmount', 'getBundlerTransactionResult', 'retrieveGalaFromFaucet', 'getSwapPoolPrice', 'fetchSwapPositionDirect', 'getAllSwapUserAssets', 'cleanup'],
+    // DEX Leaderboards & Metrics
+    'fetch-all-dex-seasons': ['fetchAllDexSeasons', 'fetchCurrentDexSeason'],
+    'fetch-dex-leaderboard-by-season-id': ['fetchDexLeaderboardBySeasonId', 'fetchCurrentDexLeaderboard'],
+    'fetch-dex-aggregated-volume-summary': ['fetchDexAggregatedVolumeSummary'],
+    'fetch-dex-pools': ['fetchDexPools', 'fetchAllDexPools'],
+};
+/**
+ * Composite topics that don't map 1:1 to SDK methods
+ * These are workflow-based topics that group multiple methods
+ */
+exports.COMPOSITE_TOPICS = new Set([
+    'buy-tokens', 'sell-tokens', 'pool-graduation', 'fetch-pools', 'balances',
+    'token-creation', 'multi-wallet', 'transfers', 'locks', 'dex-trading', 'error-handling',
+    'installation', 'local-calculations', 'price-history', 'token-details',
+    'spot-prices-smart-routing', 'profile-management', 'token-distribution',
+    'liquidity-positions', 'advanced-dex-analysis', 'social-features',
+    'trading-analytics', 'utilities-and-helpers', 'fetch-all-dex-seasons',
+    'fetch-dex-leaderboard-by-season-id', 'fetch-dex-aggregated-volume-summary',
+    'fetch-dex-pools',
+]);
 /**
  * SDK code examples organized by topic
  */
 const SDK_EXAMPLES = {
-    // Trading workflows
+    // ============================================================================
+    // TRADING WORKFLOWS: Bonding Curve Trading
+    // ============================================================================
+    // - buy-tokens: Purchase tokens from bonding curve pools
+    // - sell-tokens: Sell tokens back to bonding curve pools
+    // - pool-graduation: Transition pools to full DEX trading
+    // ============================================================================
     'buy-tokens': `
 ## Buying Tokens with SDK
 
+**Covers Methods:**
+- \`calculateBuyAmount()\`
+- \`buy()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -59,6 +131,10 @@ async function buyTokens() {
     'sell-tokens': `
 ## Selling Tokens with SDK
 
+**Covers Methods:**
+- \`calculateSellAmount()\`
+- \`sell()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -98,6 +174,10 @@ async function sellTokens() {
     'pool-graduation': `
 ## Pool Graduation with SDK
 
+**Covers Methods:**
+- \`calculateBuyAmountForGraduation()\`
+- \`graduateToken()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -136,9 +216,28 @@ async function graduatePool() {
 - \`gala_launchpad_calculate_buy_amount_for_graduation\`
 - \`gala_launchpad_graduate_token\`
 `,
+    // ============================================================================
+    // POOL DISCOVERY: Launchpad Pool Queries
+    // ============================================================================
+    // - fetch-pools: Query bonding curve pools with pagination and filtering
+    // - balances: Check GALA and token balances in wallet
+    // ============================================================================
     'fetch-pools': `
 ## Fetching Pool Data with Advanced Methods
 
+**Covers Methods:**
+- \`fetchPools()\`
+- \`fetchAllPools()\`
+- \`fetchPoolDetails()\`
+- \`fetchPoolDetailsForCalculation()\`
+- \`fetchVolumeData()\`
+- \`fetchTokenPrice()\`
+- \`fetchLaunchpadTokenSpotPrice()\`
+- \`fetchTokenDistribution()\`
+- \`fetchTokenBadges()\`
+- \`resolveVaultAddress()\`
+- \`resolveTokenClassKey()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -297,6 +396,13 @@ async function analyzeToken(tokenName) {
     'balances': `
 ## Checking Balances with SDK
 
+**Covers Methods:**
+- \`fetchGalaBalance()\`
+- \`fetchTokenBalance()\`
+- \`fetchTokensHeld()\`
+- \`fetchTokensCreated()\`
+- \`fetchProfile()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -360,9 +466,23 @@ async function checkBalances() {
 - \`gala_launchpad_fetch_tokens_created\`
 - \`gala_launchpad_fetch_profile\`
 `,
+    // ============================================================================
+    // TOKEN CREATION & MANAGEMENT: Launch New Tokens
+    // ============================================================================
+    // - token-creation: Create new tokens and manage token metadata
+    // - token-details: Fetch comprehensive token information
+    // - token-distribution: Analyze token holder distribution
+    // ============================================================================
     'token-creation': `
 ## Creating Tokens with SDK
 
+**Covers Methods:**
+- \`isTokenNameAvailable()\`
+- \`isTokenSymbolAvailable()\`
+- \`fetchLaunchTokenFee()\`
+- \`uploadTokenImage()\`
+- \`launchToken()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -417,9 +537,19 @@ async function launchToken() {
 - \`gala_launchpad_launch_token\`
 - \`gala_launchpad_get_url_by_token_name\`
 `,
+    // ============================================================================
+    // PORTFOLIO MANAGEMENT: Multi-Wallet & Transfers
+    // ============================================================================
+    // - multi-wallet: Manage multiple wallets and sessions
+    // - transfers: Send GALA and tokens to other addresses
+    // ============================================================================
     'multi-wallet': `
 ## Multi-Wallet Support with SDK
 
+**Covers Methods:**
+- \`createWallet()\` (utility function)
+- \`buy()\`, \`sell()\`, \`postComment()\` with privateKey override
+
 \`\`\`typescript
 import { createLaunchpadSDK, createWallet } from '@gala-chain/launchpad-sdk';
 
@@ -481,6 +611,10 @@ async function multiWalletExample() {
     'transfers': `
 ## Token Transfers with SDK
 
+**Covers Methods:**
+- \`transferGala()\`
+- \`transferToken()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -521,9 +655,188 @@ async function transferTokens() {
 - \`gala_launchpad_transfer_gala\`
 - \`gala_launchpad_transfer_token\`
 `,
+    'locks': `
+## Token Locking and Unlocking with SDK
+
+**Covers Methods:**
+- \`lockToken()\`
+- \`unlockToken()\`
+
+Lock and unlock tokens on GalaChain for staking, escrow, vesting, or governance.
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function tokenLocking() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key'
+  });
+
+  // ============================================================================
+  // LOCK TOKENS - Basic usage
+  // ============================================================================
+
+  // Lock 1000 tokens with default options (caller is lock authority)
+  const lockResult = await sdk.lockToken({
+    tokenName: 'anime',
+    amount: '1000'
+  });
+
+  console.log('Lock transaction ID:', lockResult.transactionId);
+  console.log('Lock status:', lockResult.status);
+
+  // ============================================================================
+  // LOCK TOKENS - Advanced options
+  // ============================================================================
+
+  // Lock with custom lock authority (another address can unlock)
+  const escrowLock = await sdk.lockToken({
+    tokenName: 'anime',
+    amount: '500',
+    lockAuthority: 'eth|0x1234...',  // Escrow agent address
+    name: 'escrow-payment-001',       // Identifier for matching during unlock
+    expires: Date.now() + 30 * 24 * 60 * 60 * 1000  // Auto-release in 30 days
+  });
+
+  console.log('Escrow lock created');
+
+  // Lock for time-based vesting
+  const vestingLock = await sdk.lockToken({
+    tokenName: 'anime',
+    amount: '10000',
+    name: 'vesting-q1-2025',
+    expires: new Date('2025-04-01').getTime()  // Auto-unlock on April 1st
+  });
+
+  console.log('Vesting lock created with expiry');
+
+  // ============================================================================
+  // UNLOCK TOKENS - Release locked tokens
+  // ============================================================================
+
+  // Unlock tokens (must be called by lock authority)
+  const unlockResult = await sdk.unlockToken({
+    tokenName: 'anime',
+    amount: '500'
+  });
+
+  console.log('Unlock transaction ID:', unlockResult.transactionId);
+  console.log('Unlock status:', unlockResult.status);
+
+  // Unlock with matching name (for specific lock identification)
+  const namedUnlock = await sdk.unlockToken({
+    tokenName: 'anime',
+    amount: '1000',
+    name: 'escrow-payment-001'  // Match the lock name used during lock
+  });
+
+  console.log('Named unlock completed');
+
+  // ============================================================================
+  // STAKING WORKFLOW EXAMPLE
+  // ============================================================================
+
+  async function stakingWorkflow() {
+    // Step 1: Lock tokens for staking period
+    const stake = await sdk.lockToken({
+      tokenName: 'anime',
+      amount: '5000',
+      name: 'staking-period-1',
+      expires: Date.now() + 90 * 24 * 60 * 60 * 1000  // 90-day staking period
+    });
+
+    console.log('Staked 5000 tokens for 90 days');
+
+    // Step 2: After staking period expires, unlock
+    // (This would happen after the expires timestamp)
+    const unstake = await sdk.unlockToken({
+      tokenName: 'anime',
+      amount: '5000',
+      name: 'staking-period-1'
+    });
+
+    console.log('Unstaked tokens after staking period');
+    return { stake, unstake };
+  }
+
+  // ============================================================================
+  // ESCROW WORKFLOW EXAMPLE
+  // ============================================================================
+
+  async function escrowWorkflow(buyerAddress: string, sellerAddress: string) {
+    // Step 1: Buyer locks payment in escrow (seller is lock authority)
+    const escrow = await sdk.lockToken({
+      tokenName: 'anime',
+      amount: '1000',
+      lockAuthority: sellerAddress,  // Seller can release upon delivery
+      name: 'order-12345'
+    });
+
+    console.log('Escrow created: seller can release payment upon delivery');
+
+    // Step 2: Seller releases escrow after delivery (seller calls unlock)
+    // This would be executed by the seller's SDK instance
+    // const release = await sellerSdk.unlockToken({
+    //   tokenName: 'anime',
+    //   amount: '1000',
+    //   name: 'order-12345'
+    // });
+
+    return escrow;
+  }
+}
+\`\`\`
+
+**Key Features:**
+- **Lock Authority**: Specify who can unlock (defaults to caller)
+- **Expiration**: Optional auto-release timestamp for time-based vesting
+- **Named Locks**: Use \`name\` to identify specific locks for targeted unlocks
+- **EIP-712 Signatures**: Secure blockchain transactions
+- **Error Handling**: \`LockError\` class with specific error types
+
+**Lock Parameters:**
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| \`tokenName\` | Yes | Token to lock (e.g., 'anime') |
+| \`amount\` | Yes | Amount of tokens to lock |
+| \`lockAuthority\` | No | Address that can unlock (defaults to caller) |
+| \`expires\` | No | Timestamp in ms for auto-unlock |
+| \`name\` | No | Identifier for matching during unlock |
+
+**Unlock Parameters:**
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| \`tokenName\` | Yes | Token to unlock (e.g., 'anime') |
+| \`amount\` | Yes | Amount of tokens to unlock |
+| \`name\` | No | Lock name to match (if used during lock) |
+
+**Use Cases:**
+- **Staking**: Lock tokens for rewards/governance
+- **Escrow**: Third-party controlled releases
+- **Vesting**: Time-based token releases
+- **Governance**: Lock tokens for voting power
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_lock_token\`
+- \`gala_launchpad_unlock_token\`
+`,
+    // ============================================================================
+    // DEX TRADING: GalaSwap Integration
+    // ============================================================================
+    // - dex-trading: Execute trades, get quotes, manage assets on GalaSwap
+    // - error-handling: Handle transaction errors gracefully
+    // ============================================================================
     'dex-trading': `
 ## DEX Trading with SDK - GalaSwap Integration
 
+**Covers Methods:**
+- \`getSwapQuoteExactInput()\`
+- \`getSwapQuoteExactOutput()\`
+- \`executeSwap()\`
+- \`getSwapUserAssets()\`
+- \`getAllSwapUserAssets()\`
+- \`getSwapPoolInfo()\`
+
 Trade graduated tokens on the GalaSwap DEX with real-time WebSocket monitoring:
 
 \`\`\`typescript
@@ -577,6 +890,17 @@ async function dexTradingExample() {
     console.log('  ' + asset.symbol + ': ' + asset.balance);
   });
 
+  // ============================================================================
+  // PORTFOLIO: Get ALL assets (auto-paginated)
+  // ============================================================================
+
+  const allAssets = await sdk.getAllSwapUserAssets(sdk.getEthereumAddress());
+  console.log('Complete asset portfolio:');
+  console.log('Total assets: ' + allAssets.length);
+  allAssets.forEach(asset => {
+    console.log('  ' + asset.symbol + ': ' + asset.balance);
+  });
+
   // ============================================================================
   // POOL INFO: Check liquidity before trading
   // ============================================================================
@@ -595,17 +919,22 @@ async function dexTradingExample() {
 - **Token Formats**: Supports simple names ('GALA') or full IDs ('GALA|Unit|none|none')
 - **Slippage Protection**: Always use quote values for execution
 - **Fee Tiers**: 500 (0.05%), 3000 (0.30%), 10000 (1.00%)
+- **Auto-Pagination**: Use \`getAllSwapUserAssets()\` for complete portfolio
 
 **MCP Tool Equivalents:**
 - \`gala_launchpad_get_swap_quote_exact_input\`
 - \`gala_launchpad_get_swap_quote_exact_output\`
 - \`gala_launchpad_execute_swap\`
 - \`gala_launchpad_get_swap_user_assets\`
+- \`gala_launchpad_get_all_swap_user_assets\`
 - \`gala_launchpad_get_swap_pool_info\`
 `,
     'error-handling': `
 ## Error Handling with SDK
 
+**Covers Methods:**
+- Error types from SDK (ValidationError, NetworkError, TransactionError, TokenNotFoundError, etc.)
+
 \`\`\`typescript
 import {
   createLaunchpadSDK,
@@ -664,9 +993,19 @@ async function errorHandlingExample() {
 - \`ConfigurationError\` - SDK misconfiguration
 - \`WebSocketError\` - Real-time connection issues
 `,
+    // ============================================================================
+    // DEVELOPER TOOLS & SETUP: Installation & Utilities
+    // ============================================================================
+    // - installation: Install and import the SDK
+    // - local-calculations: Offline bonding curve calculations
+    // - utilities-and-helpers: Helper functions and utilities
+    // ============================================================================
     'installation': `
 ## Installing and Importing SDK
 
+**Covers Methods:**
+- SDK installation, imports, and configuration
+
 ### NPM Installation
 
 \`\`\`bash
@@ -736,6 +1075,12 @@ const sdk = createLaunchpadSDK({
     'local-calculations': `
 ## Local Bonding Curve Calculations with SDK
 
+**Covers Methods:**
+- \`calculateBuyAmountLocal()\`
+- \`calculateSellAmountLocal()\`
+- \`calculateBuyAmountExternal()\`
+- \`calculateSellAmountExternal()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -844,9 +1189,19 @@ async function localCalculationsExample() {
 - \`gala_launchpad_calculate_sell_amount_local\`
 - \`gala_launchpad_calculate_sell_amount_external\`
 `,
+    // ============================================================================
+    // MARKET DATA: Prices & Historical Data
+    // ============================================================================
+    // - price-history: Fetch historical price data for tokens
+    // - spot-prices-smart-routing: Get current token prices
+    // ============================================================================
     'price-history': `
 ## Historical Price Analysis with SDK
 
+**Covers Methods:**
+- \`fetchPriceHistory()\`
+- \`fetchAllPriceHistory()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -857,7 +1212,7 @@ async function analyzePriceHistory() {
 
   // Paginated price history
   const history = await sdk.fetchPriceHistory({
-    tokenId: 'Token|Unit|GUSDC|eth:0x...',
+    tokenId: 'GUSDC|Unit|none|eth:0x...',
     from: new Date('2025-01-01'),
     to: new Date('2025-01-31'),
     sortOrder: 'DESC',
@@ -909,7 +1264,7 @@ async function analyzePriceHistory() {
 - Backtesting strategies
 
 **Token ID Formats:**
-- String: \`Token|Unit|GUSDC|eth:0x...\`
+- String: \`GUSDC|Unit|none|eth:0x...\`
 - Object: \`{ collection, category, type, additionalKey }\`
 
 **MCP Tool Equivalents:**
@@ -919,6 +1274,9 @@ async function analyzePriceHistory() {
     'token-details': `
 ## Token Details and Metadata with SDK
 
+**Covers Methods:**
+- \`fetchTokenDetails()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -928,7 +1286,7 @@ async function analyzeTokenDetails() {
   });
 
   // Fetch token metadata
-  const details = await sdk.fetchTokenDetails('Token|Unit|GUSDC|eth:0x...');
+  const details = await sdk.fetchTokenDetails('GUSDC|Unit|none|eth:0x...');
 
   console.log('Token Information:');
   console.log(\`  Name: \${details.name}\`);
@@ -959,7 +1317,7 @@ async function analyzeTokenDetails() {
   }
 
   // Batch token comparison
-  const tokens = ['GALA|Unit|none|none', 'Token|Unit|GUSDC|eth:0x...'];
+  const tokens = ['GALA|Unit|none|none', 'GUSDC|Unit|none|eth:0x...'];
   const details_list = await Promise.all(
     tokens.map(id => sdk.fetchTokenDetails(id).catch(() => null))
   );
@@ -987,7 +1345,7 @@ async function analyzeTokenDetails() {
 - Network compatibility checking
 
 **Token ID Formats:**
-- String: \`Token|Unit|GUSDC|eth:0x...\`
+- String: \`GUSDC|Unit|none|eth:0x...\`
 - Object: \`{ collection, category, type, additionalKey }\`
 
 **MCP Tool Equivalent:** \`gala_launchpad_fetch_token_details\`
@@ -995,6 +1353,11 @@ async function analyzeTokenDetails() {
     'spot-prices-smart-routing': `
 ## Smart Spot Price Routing with DEX Fallback
 
+**Covers Methods:**
+- \`fetchTokenPrice()\` (smart routing)
+- \`fetchLaunchpadTokenSpotPrice()\`
+- \`isTokenGraduated()\`
+
 The SDK intelligently routes pricing requests between DEX and Launchpad backends based on token graduation status - no need to know which backend a token uses!
 
 \`\`\`typescript
@@ -1134,9 +1497,20 @@ async function safePriceQuery(tokenId: string) {
 - \`gala_launchpad_fetch_launchpad_token_spot_price\` - Launchpad-only
 - \`gala_launchpad_is_token_graduated\` - Check graduation status
 `,
+    // ============================================================================
+    // USER PROFILE & SOCIAL: Community Features
+    // ============================================================================
+    // - profile-management: Update user profile and images
+    // - social-features: Community comments and interactions
+    // ============================================================================
     'profile-management': `
 ## User Profile Management with SDK
 
+**Covers Methods:**
+- \`fetchProfile()\`
+- \`updateProfile()\`
+- \`uploadProfileImage()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -1240,6 +1614,9 @@ async function manageUserProfiles() {
     'token-distribution': `
 ## Token Holder Distribution with SDK
 
+**Covers Methods:**
+- \`fetchTokenDistribution()\`
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
@@ -1322,14 +1699,30 @@ function calculateGini(holders: Array<{balance: string}>) {
 
 **MCP Tool Equivalent:** \`gala_launchpad_fetch_token_distribution\`
 `,
+    // ============================================================================
+    // LIQUIDITY MANAGEMENT: GalaSwap LP Positions
+    // ============================================================================
+    // - liquidity-positions: Manage concentrated liquidity positions
+    // ============================================================================
     'liquidity-positions': `
 ## GSwap Liquidity Position Management
 
+**Covers Methods:**
+- \`getSwapUserLiquidityPositions()\`
+- \`getAllSwapUserLiquidityPositions()\`
+- \`getSwapLiquidityPosition()\`
+- \`getSwapLiquidityPositionById()\`
+- \`addSwapLiquidityByPrice()\`
+- \`addSwapLiquidityByTicks()\`
+- \`getSwapEstimateRemoveLiquidity()\`
+- \`removeSwapLiquidity()\`
+- \`collectSwapPositionFees()\`
+
 Provide liquidity on GalaSwap DEX and earn passive trading fees from swaps.
 
 **Overview:** Concentrated liquidity allows capital deployment within specific price ranges. Liquidity providers earn fees when trades occur within their price range, making it an attractive passive income strategy.
 
-**8 Core SDK Methods:**
+**9 Core SDK Methods:**
 
 1. **getSwapUserLiquidityPositions(ownerAddress, limit?, bookmark?)** - View all open positions for wallet
    - Returns: Array of positions with token pairs, amounts, accumulated fees
@@ -1370,7 +1763,489 @@ Provide liquidity on GalaSwap DEX and earn passive trading fees from swaps.
 - /galachain-launchpad:remove-liquidity - Close position
 - /galachain-launchpad:collect-fees - Harvest fees
 
+**Auto-Pagination Method:**
+
+Use \`getAllSwapUserLiquidityPositions()\` to fetch all positions without manual pagination:
+
+\`\`\`typescript
+// Fetch ALL positions automatically (handles pagination internally)
+const allPositions = await sdk.getAllSwapUserLiquidityPositions(ownerAddress);
+
+console.log(\`Total positions: \${allPositions.length}\`);
+allPositions.forEach(position => {
+  const fees = position.fees0 + position.fees1; // Total accumulated fees
+  console.log(\`Position: \${position.token0}-\${position.token1}\`);
+  console.log(\`Accumulated fees: \${fees}\`);
+});
+\`\`\`
+
 **Demo Script:** See packages/sdk/examples/demo-liquidity-positions.ts for complete workflows
+`,
+    // ============================================================================
+    // ADVANCED ANALYSIS & SOCIAL: Complex Features
+    // ============================================================================
+    // - advanced-dex-analysis: Composite DEX analysis and pricing
+    // - social-features: Community interactions
+    // - trading-analytics: Trade history and metrics
+    // ============================================================================
+    'advanced-dex-analysis': `
+## Advanced DEX Pool Analysis with SDK
+
+**Covers Methods:**
+- \`fetchCompositePoolData()\`
+- \`calculateDexPoolQuoteExactAmountLocal()\`
+- \`calculateDexPoolQuoteExactAmountExternal()\`
+- \`calculateDexPoolQuoteExactAmount()\`
+
+This workflow demonstrates analyzing graduated tokens using composite data and price calculations.
+
+**Use Cases:**
+- Arbitrage opportunity detection
+- Price impact analysis before large trades
+- Comparing bonding curve vs DEX pricing
+- Smart routing for best execution
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function advancedDexAnalysis() {
+  const sdk = createLaunchpadSDK({ environment: 'production' });
+
+  // Step 1: Get composite pool data (bonding curve + DEX if graduated)
+  const composite = await sdk.fetchCompositePoolData('anime');
+
+  if (composite.isGraduated) {
+    console.log('Token graduated to DEX!');
+    console.log('DEX Pool TVL:', composite.dexPool.tvl);
+    console.log('DEX 24h Volume:', composite.dexPool.volume1d);
+  }
+
+  // Step 2: Compare local vs external price calculations
+  const localQuote = await sdk.calculateDexPoolQuoteExactAmountLocal(
+    'GALA|Unit|none|none',
+    'anime|Unit|none|eth:0x...',
+    '100'
+  );
+
+  const externalQuote = await sdk.calculateDexPoolQuoteExactAmountExternal(
+    'GALA|Unit|none|none',
+    'anime|Unit|none|eth:0x...',
+    '100'
+  );
+
+  console.log('Local calculation:', localQuote.outputAmount);
+  console.log('External API:', externalQuote.outputAmount);
+  console.log('Price difference:',
+    Math.abs(parseFloat(localQuote.outputAmount) - parseFloat(externalQuote.outputAmount))
+  );
+
+  // Step 3: Use smart routing for best price
+  const bestQuote = await sdk.calculateDexPoolQuoteExactAmount(
+    'GALA|Unit|none|none',
+    'anime|Unit|none|eth:0x...',
+    '100'
+  );
+
+  console.log('Best route:', bestQuote.route); // 'local' or 'external'
+  console.log('Best price:', bestQuote.outputAmount);
+}
+\`\`\`
+
+**MCP Tools:**
+- \`gala_launchpad_fetch_composite_pool_data\`
+- \`gala_launchpad_calculate_dex_pool_quote_exact_amount_local\`
+- \`gala_launchpad_calculate_dex_pool_quote_exact_amount_external\`
+- \`gala_launchpad_calculate_dex_pool_quote_exact_amount\`
+`,
+    'social-features': `
+## Community Comments and Social Features
+
+**Covers Methods:**
+- \`fetchComments()\`
+- \`postComment()\`
+
+Interact with token communities through comments.
+
+**Use Cases:**
+- Display community sentiment
+- Post analysis or updates
+- Moderate discussions
+- Track engagement
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function socialFeatures() {
+  // Read-only: Fetch comments
+  const sdkReadOnly = createLaunchpadSDK({ environment: 'production' });
+
+  const comments = await sdkReadOnly.fetchComments({
+    tokenName: 'anime',
+    limit: 50,
+    page: 1
+  });
+
+  console.log(\`Found \${comments.total} comments\`);
+  comments.comments.forEach(comment => {
+    console.log(\`\${comment.author}: \${comment.content}\`);
+    console.log(\`  Posted: \${comment.createdAt}\`);
+  });
+
+  // Write: Post a comment (requires wallet)
+  const sdkWithWallet = createLaunchpadSDK({
+    environment: 'production',
+    wallet: process.env.WALLET_PRIVATE_KEY
+  });
+
+  await sdkWithWallet.postComment({
+    tokenName: 'anime',
+    content: 'Great project! Just bought 1000 tokens.'
+  });
+
+  console.log('Comment posted successfully!');
+}
+\`\`\`
+
+**MCP Tools:**
+- \`gala_launchpad_fetch_comments\`
+- \`gala_launchpad_post_comment\`
+`,
+    'trading-analytics': `
+## Trading History and Analytics
+
+**Covers Methods:**
+- \`fetchTrades()\`
+
+Analyze individual trades for technical analysis and bot development.
+
+**Use Cases:**
+- Track recent trading activity
+- Calculate average trade size
+- Identify whale transactions
+- Build trading bots with historical data
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function tradingAnalytics() {
+  const sdk = createLaunchpadSDK({ environment: 'production' });
+
+  // Fetch recent trades
+  const trades = await sdk.fetchTrades('anime', {
+    limit: 100,
+    page: 1
+  });
+
+  console.log(\`Analyzing \${trades.total} trades\`);
+
+  // Calculate analytics
+  const totalVolume = trades.trades.reduce((sum, t) => sum + parseFloat(t.galaAmount), 0);
+  const averageTradeSize = totalVolume / trades.trades.length;
+  const whaleTrades = trades.trades.filter(t => parseFloat(t.galaAmount) > 1000);
+
+  console.log(\`Total volume: \${totalVolume} GALA\`);
+  console.log(\`Average trade size: \${averageTradeSize} GALA\`);
+  console.log(\`Whale trades (>1000 GALA): \${whaleTrades.length}\`);
+
+  // Most recent trades
+  trades.trades.slice(0, 10).forEach(trade => {
+    console.log(\`\${trade.type}: \${trade.galaAmount} GALA at \${trade.timestamp}\`);
+  });
+}
+\`\`\`
+
+**Related Topics:**
+- See \`fetch-pools\` for volume data analysis
+- See \`dex-trading\` for executing trades
+
+**MCP Tools:**
+- \`gala_launchpad_fetch_trades\`
+`,
+    'utilities-and-helpers': `
+## Utility Methods and Helpers
+
+**Covers Methods:**
+- \`fetchGalaPrice()\`
+- \`fetchTokenClassesWithSupply()\`
+- \`calculateInitialBuyAmount()\`
+- \`getBundlerTransactionResult()\`
+- \`retrieveGalaFromFaucet()\`
+- \`getSwapPoolPrice()\`
+- \`fetchSwapPositionDirect()\`
+- \`getAllSwapUserAssets()\`
+- \`cleanup()\`
+
+Essential helper methods for development, debugging, and special use cases.
+
+### Price & Supply Queries
+
+\`\`\`typescript
+// Get current GALA price in USD
+const galaPrice = await sdk.fetchGalaPrice();
+console.log(\`GALA: $\${galaPrice}\`);
+
+// Get token supply metrics from GalaChain
+const supplies = await sdk.fetchTokenClassesWithSupply();
+supplies.forEach(token => {
+  console.log(\`\${token.tokenClass}: \${token.totalSupply}\`);
+});
+\`\`\`
+
+### Transaction Monitoring
+
+\`\`\`typescript
+// Check transaction status
+const status = await sdk.getBundlerTransactionResult('tx-id-123');
+console.log('Status:', status.status); // 'pending' | 'success' | 'failed'
+\`\`\`
+
+### Testing Utilities
+
+\`\`\`typescript
+// Retrieve test GALA from faucet (development only)
+await sdk.retrieveGalaFromFaucet();
+console.log('Test GALA received!');
+\`\`\`
+
+### Advanced Swap Queries
+
+\`\`\`typescript
+// Get pool price without full quote
+const price = await sdk.getSwapPoolPrice('GALA|Unit|none|none', 'GUSDC|Unit|none|none');
+console.log(\`Pool price: \${price}\`);
+
+// Auto-paginated asset fetch
+const allAssets = await sdk.getAllSwapUserAssets('eth|0x...', { limit: 100 });
+console.log(\`Total assets: \${allAssets.length}\`);
+
+// Direct position lookup (if you have compound key)
+const position = await sdk.fetchSwapPositionDirect({
+  owner: 'eth|0x...',
+  token0: 'GALA|Unit|none|none',
+  token1: 'GUSDC|Unit|none|none',
+  feeTier: 3000
+});
+\`\`\`
+
+### Launch Calculations
+
+\`\`\`typescript
+// Calculate initial buy amount for token launch
+const buyAmount = await sdk.calculateInitialBuyAmount('100');
+console.log(\`Initial buy: \${buyAmount} tokens\`);
+\`\`\`
+
+### SDK Cleanup
+
+\`\`\`typescript
+// Proper cleanup when done (closes connections)
+await sdk.cleanup();
+\`\`\`
+
+**MCP Tools:**
+- \`gala_launchpad_fetch_gala_price\`
+- \`gala_launchpad_fetch_token_classes_with_supply\`
+- \`gala_launchpad_calculate_initial_buy_amount\`
+- \`gala_launchpad_get_bundler_transaction_result\`
+- \`gala_launchpad_retrieve_gala_from_faucet\`
+- \`gala_launchpad_get_swap_pool_price\`
+- \`gala_launchpad_fetch_swap_position_direct\`
+- \`gala_launchpad_get_all_swap_user_assets\`
+`,
+    // ============================================================================
+    // DEX LEADERBOARDS & METRICS: Competitive Features
+    // ============================================================================
+    // - fetch-all-dex-seasons: Query DEX leaderboard seasons
+    // - fetch-dex-leaderboard-by-season-id: View season rankings
+    // - fetch-dex-aggregated-volume-summary: Platform volume trends
+    // - fetch-dex-pools: Discover and analyze liquidity pools
+    // ============================================================================
+    'fetch-all-dex-seasons': `
+## DEX Leaderboard Seasons Management
+
+**Covers Methods:**
+- \`fetchAllDexSeasons()\`
+- \`fetchCurrentDexSeason()\`
+
+Discover and manage DEX leaderboard seasons for competitive trading events.
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function manageDexSeasons() {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Fetch all available seasons
+  const seasons = await sdk.fetchAllDexSeasons();
+
+  // Display season information
+  seasons.forEach(season => {
+    console.log(\`Season: \${season.name} (ID: \${season.id})\`);
+    console.log(\`Duration: \${season.start} to \${season.end}\`);
+  });
+
+  // Get current season
+  const activeSeason = await sdk.fetchCurrentDexSeason();
+  if (activeSeason) {
+    console.log(\`Active: \${activeSeason.name}\`);
+  } else {
+    console.log('No active season (between seasons)');
+  }
+
+  // Verify season is active
+  const now = new Date();
+  const isActive = activeSeason && now >= activeSeason.start && now <= activeSeason.end;
+  console.log(\`Season active: \${isActive}\`);
+}
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_all_dex_seasons\`
+- \`gala_launchpad_fetch_current_dex_season\`
+`,
+    'fetch-dex-leaderboard-by-season-id': `
+## DEX Leaderboard Rankings by Season
+
+**Covers Methods:**
+- \`fetchDexLeaderboardBySeasonId()\`
+- \`fetchCurrentDexLeaderboard()\`
+
+Query leaderboard rankings for competitive DEX trading seasons.
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function viewLeaderboards() {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Option 1: Fetch leaderboard for specific season
+  const leaderboard = await sdk.fetchDexLeaderboardBySeasonId(4);
+
+  // Display top 10 ranked players
+  console.log(\`Season \${leaderboard.seasonId} - Top 10 Players:\`);
+  leaderboard.entries.slice(0, 10).forEach(entry => {
+    console.log(\`  \${entry.rank}. \${entry.wallet}\`);
+    console.log(\`     XP: \${entry.totalXp} (Liquidity: \${entry.liquidityXp}, Trading: \${entry.tradingXp})\`);
+  });
+
+  // Analyze mastery titles
+  const topPlayer = leaderboard.entries[0];
+  topPlayer.masteryTitles.forEach(title => {
+    console.log(\`  🏆 \${title.name} (Type: \${title.type}, Tier: \${title.order})\`);
+  });
+
+  // Option 2: Get current leaderboard (convenience method)
+  const currentBoard = await sdk.fetchCurrentDexLeaderboard();
+
+  if (currentBoard) {
+    console.log(\`Season \${currentBoard.seasonId} is active\`);
+    console.log(\`Total participants: \${currentBoard.entries.length}\`);
+
+    // Top 3 performers
+    const topThree = currentBoard.entries.slice(0, 3);
+    topThree.forEach(entry => {
+      console.log(\`  #\${entry.rank}: \${entry.totalXp} XP\`);
+    });
+  }
+}
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_dex_leaderboard_by_season_id\`
+- \`gala_launchpad_fetch_current_dex_leaderboard\`
+`,
+    'fetch-dex-aggregated-volume-summary': `
+## DEX Aggregated Volume Summary and Trends
+
+**Covers Methods:**
+- \`fetchDexAggregatedVolumeSummary()\`
+
+Analyze DEX trading volume trends across different time periods.
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function analyzeVolumeTrends() {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Get volume summary with trend metrics
+  const summary = await sdk.fetchDexAggregatedVolumeSummary();
+
+  // Display volumes
+  console.log(\`1-Day Volume: $\${summary.volume1d.toLocaleString()}\`);
+  console.log(\`7-Day Volume: $\${summary.volume7d.toLocaleString()}\`);
+  console.log(\`30-Day Volume: $\${summary.volume30d.toLocaleString()}\`);
+
+  // Analyze trends
+  const trend1d = summary.volume1dDelta > 0 ? '📈 UP' : '📉 DOWN';
+  const trend7d = summary.volume7dDelta > 0 ? '📈 UP' : '📉 DOWN';
+  const trend30d = summary.volume30dDelta > 0 ? '📈 UP' : '📉 DOWN';
+
+  console.log(\`1-Day Trend: \${trend1d} (\${(summary.volume1dDelta * 100).toFixed(2)}%)\`);
+  console.log(\`7-Day Trend: \${trend7d} (\${(summary.volume7dDelta * 100).toFixed(2)}%)\`);
+  console.log(\`30-Day Trend: \${trend30d} (\${(summary.volume30dDelta * 100).toFixed(2)}%)\`);
+
+  // Growth analysis
+  if (summary.volume30dDelta > 0.1) {
+    console.log('Strong growth - Platform adoption increasing');
+  } else if (summary.volume30dDelta < -0.1) {
+    console.log('Declining volume - Platform may be slowing');
+  }
+}
+\`\`\`
+
+**MCP Tool Equivalent:** \`gala_launchpad_fetch_dex_aggregated_volume_summary\`
+`,
+    'fetch-dex-pools': `
+## Fetch DEX Pools with Pagination
+
+**Covers Methods:**
+- \`fetchDexPools()\`
+- \`fetchAllDexPools()\`
+
+Discover and query liquidity pools on GalaSwap with advanced filtering and pagination.
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function queryDexPools() {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Option 1: Fetch pools with pagination
+  const pools = await sdk.fetchDexPools({
+    search: 'GALA',
+    sortBy: 'tvl',      // Sort by: tvl, volume30d, volume1d
+    limit: 20,
+    page: 1
+  });
+
+  console.log(\`Found \${pools.total} pools, page \${pools.page} of \${pools.totalPages}\`);
+  pools.pools.forEach(pool => {
+    console.log(\`\${pool.tokenName}: TVL \${pool.tvl}, 24h Volume: \${pool.volume1d}\`);
+  });
+
+  // Option 2: Fetch ALL pools automatically (handles pagination)
+  const allPools = await sdk.fetchAllDexPools({
+    sortBy: 'tvl'
+  });
+
+  console.log(\`Total pools: \${allPools.pools.length}\`);
+
+  // Analyze pool metrics
+  const avgTvl = allPools.pools.reduce((sum, p) => sum + parseFloat(p.tvl), 0) / allPools.pools.length;
+  console.log(\`Average TVL: $\${avgTvl.toFixed(2)}\`);
+}
+\`\`\`
+
+**Key Features:**
+- **Sorting**: TVL (total value locked), volume30d (30-day volume), volume1d (24-hour volume)
+- **Pool Metrics**: Token prices, fee tiers, liquidity, 24h/30d volume, APR
+- **Auto-Pagination**: \`fetchAllDexPools()\` handles pagination automatically
+- **Search**: Filter by token name or pair
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_dex_pools\`
+- \`gala_launchpad_fetch_all_dex_pools\`
 `,
 };
 /**
@@ -1378,7 +2253,7 @@ Provide liquidity on GalaSwap DEX and earn passive trading fees from swaps.
  */
 exports.explainSdkUsageTool = {
     name: 'gala_launchpad_explain_sdk_usage',
-    description: 'Get detailed SDK code examples for: buy-tokens, sell-tokens, pool-graduation, fetch-pools, balances, dex-trading, liquidity-positions, price-history, token-details, token-distribution, token-creation, profile-management, multi-wallet, transfers, error-handling, installation, local-calculations, mcp-to-sdk-mapping',
+    description: 'Get detailed SDK code examples for all 78 SDK methods organized into 28 composite workflow topics covering: buy-tokens, sell-tokens, pool-graduation, fetch-pools, balances, dex-trading, liquidity-positions, advanced-dex-analysis, price-history, token-details, token-distribution, token-creation, profile-management, multi-wallet, transfers, locks, social-features, trading-analytics, utilities-and-helpers, error-handling, installation, local-calculations, spot-prices-smart-routing, and more',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1392,6 +2267,7 @@ exports.explainSdkUsageTool = {
                     'balances',
                     'dex-trading',
                     'liquidity-positions',
+                    'advanced-dex-analysis',
                     'price-history',
                     'token-details',
                     'token-distribution',
@@ -1399,10 +2275,20 @@ exports.explainSdkUsageTool = {
                     'profile-management',
                     'multi-wallet',
                     'transfers',
+                    'locks',
+                    'social-features',
+                    'trading-analytics',
+                    'utilities-and-helpers',
                     'error-handling',
                     'installation',
                     'local-calculations',
+                    'spot-prices-smart-routing',
                     'mcp-to-sdk-mapping',
+                    'fetch-all-dex-seasons',
+                    'fetch-current-dex-season',
+                    'fetch-dex-leaderboard-by-season-id',
+                    'fetch-current-dex-leaderboard',
+                    'fetch-dex-aggregated-volume-summary',
                 ],
                 description: 'The SDK usage topic to explain',
             },
@@ -1417,7 +2303,7 @@ exports.explainSdkUsageTool = {
         return (0, response_formatter_js_1.formatSuccess)({
             topic: args.topic,
             explanation: example,
-            sdkVersion: '3.19.0',
+            sdkVersion: '4.0.0',
             packageName: '@gala-chain/launchpad-sdk',
             documentation: 'https://www.npmjs.com/package/@gala-chain/launchpad-sdk',
         });