@gala-chain/launchpad-mcp-server 1.23.1 → 1.24.0

package/src/tools/dex/liquidity-positions.ts

@@ -0,0 +1,547 @@
+/**
+ * DEX Liquidity Position Management Tools
+ *
+ * Tools for managing liquidity positions on GalaSwap DEX, including:
+ * - Querying user positions and position details
+ * - Estimating liquidity removal
+ * - Adding liquidity by price or tick range
+ * - Removing liquidity and collecting fees
+ */
+
+import type { MCPTool } from '../../types/mcp.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+import {
+  DECIMAL_AMOUNT_SCHEMA,
+  ADDRESS_SCHEMA,
+} from '../../schemas/common-schemas.js';
+
+// Token symbol for DEX trading
+const TOKEN_SYMBOL_SCHEMA = {
+  type: 'string',
+  minLength: 1,
+  maxLength: 20,
+  description: 'Token symbol (e.g., "GALA", "GUSDC")',
+};
+
+// Fee tier for GalaSwap (in basis points)
+const FEE_TIER_SCHEMA = {
+  type: 'number',
+  enum: [500, 3000, 10000],
+  description: 'Fee tier in basis points: 500 (0.05%), 3000 (0.30%), 10000 (1.00%)',
+};
+
+// 1. Get User Liquidity Positions
+export const getUserLiquidityPositionsTool: MCPTool = {
+  name: 'gala_launchpad_get_user_liquidity_positions',
+  description:
+    'Get all open liquidity positions for a wallet address with optional pagination',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      ownerAddress: {
+        ...ADDRESS_SCHEMA,
+        description: 'Wallet address to query positions for (e.g., "0x1234..." or "eth|1234...")',
+      },
+      limit: {
+        type: 'number',
+        minimum: 1,
+        maximum: 100,
+        description: 'Maximum number of positions to return (optional)',
+      },
+      bookmark: {
+        type: 'string',
+        description: 'Pagination bookmark from previous response (optional)',
+      },
+    },
+    required: ['ownerAddress'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const positions = await sdk.getSwapUserLiquidityPositions(
+      args.ownerAddress,
+      args.limit,
+      args.bookmark
+    );
+
+    return formatSuccess({
+      ownerAddress: args.ownerAddress,
+      positionCount: (positions && Array.isArray(positions)) ? positions.length : 0,
+      positions: (positions && Array.isArray(positions))
+        ? positions.map((pos: any) => ({
+            positionId: pos.positionId,
+            token0: pos.token0,
+            token1: pos.token1,
+            feeTier: pos.feeTier,
+            liquidity: pos.liquidity,
+            amount0: pos.amount0,
+            amount1: pos.amount1,
+            feeAmount0: pos.feeAmount0,
+            feeAmount1: pos.feeAmount1,
+            tickLower: pos.tickLower,
+            tickUpper: pos.tickUpper,
+          }))
+        : [],
+      message:
+        (positions && Array.isArray(positions))
+          ? `${positions.length} open positions found`
+          : 'No open positions found',
+    });
+  }),
+};
+
+// 2. Get Liquidity Position by ID
+export const getLiquidityPositionByIdTool: MCPTool = {
+  name: 'gala_launchpad_get_liquidity_position_by_id',
+  description: 'Get specific liquidity position details by position ID',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      ownerAddress: {
+        ...ADDRESS_SCHEMA,
+        description: 'Wallet address that owns the position',
+      },
+      positionId: {
+        type: 'string',
+        minLength: 1,
+        description: 'Unique position identifier',
+      },
+    },
+    required: ['ownerAddress', 'positionId'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const position = await sdk.getSwapLiquidityPositionById(args.ownerAddress, args.positionId);
+
+    if (!position) {
+      return formatSuccess({
+        found: false,
+        message: `Position ${args.positionId} not found`,
+      });
+    }
+
+    return formatSuccess({
+      found: true,
+      positionId: position.positionId,
+      ownerAddress: position.ownerAddress,
+      token0: position.token0,
+      token1: position.token1,
+      feeTier: position.feeTier,
+      liquidity: position.liquidity,
+      amount0: position.amount0,
+      amount1: position.amount1,
+      feeAmount0: position.feeAmount0,
+      feeAmount1: position.feeAmount1,
+      tickLower: position.tickLower,
+      tickUpper: position.tickUpper,
+      createdAt: position.createdAt ? new Date(position.createdAt).toISOString() : undefined,
+      updatedAt: position.updatedAt ? new Date(position.updatedAt).toISOString() : undefined,
+      message: `Position ${args.positionId}: ${position.liquidity} liquidity in ${position.token0}/${position.token1}`,
+    });
+  }),
+};
+
+// 3. Get Liquidity Position by Token Pair
+export const getLiquidityPositionTool: MCPTool = {
+  name: 'gala_launchpad_get_liquidity_position',
+  description:
+    'Get liquidity position for a specific token pair and price range (tick boundaries)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      ownerAddress: {
+        ...ADDRESS_SCHEMA,
+        description: 'Wallet address that owns the position',
+      },
+      token0: TOKEN_SYMBOL_SCHEMA,
+      token1: TOKEN_SYMBOL_SCHEMA,
+      fee: FEE_TIER_SCHEMA,
+      tickLower: {
+        type: 'number',
+        description: 'Lower tick boundary of the position',
+      },
+      tickUpper: {
+        type: 'number',
+        description: 'Upper tick boundary of the position',
+      },
+    },
+    required: ['ownerAddress', 'token0', 'token1', 'fee', 'tickLower', 'tickUpper'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const position = await sdk.getSwapLiquidityPosition(args.ownerAddress, {
+      token0: args.token0,
+      token1: args.token1,
+      fee: args.fee,
+      tickLower: args.tickLower,
+      tickUpper: args.tickUpper,
+    });
+
+    if (!position) {
+      return formatSuccess({
+        found: false,
+        message: `No position found for ${args.token0}/${args.token1} at ticks ${args.tickLower}-${args.tickUpper}`,
+      });
+    }
+
+    return formatSuccess({
+      found: true,
+      positionId: position.positionId,
+      token0: position.token0,
+      token1: position.token1,
+      feeTier: position.feeTier,
+      liquidity: position.liquidity,
+      amount0: position.amount0,
+      amount1: position.amount1,
+      feeAmount0: position.feeAmount0,
+      feeAmount1: position.feeAmount1,
+      tickLower: position.tickLower,
+      tickUpper: position.tickUpper,
+      message: `Found position: ${position.liquidity} liquidity with ${position.feeAmount0} ${args.token0} and ${position.feeAmount1} ${args.token1} in fees`,
+    });
+  }),
+};
+
+// 4. Estimate Liquidity Removal
+export const estimateRemoveLiquidityTool: MCPTool = {
+  name: 'gala_launchpad_estimate_remove_liquidity',
+  description:
+    'Estimate tokens and fees received when removing liquidity at current market prices',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      token0: TOKEN_SYMBOL_SCHEMA,
+      token1: TOKEN_SYMBOL_SCHEMA,
+      fee: FEE_TIER_SCHEMA,
+      liquidity: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Liquidity amount to estimate removal for',
+      },
+      tickLower: {
+        type: 'number',
+        description: 'Lower tick boundary of the position',
+      },
+      tickUpper: {
+        type: 'number',
+        description: 'Upper tick boundary of the position',
+      },
+    },
+    required: ['token0', 'token1', 'fee', 'liquidity', 'tickLower', 'tickUpper'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const estimate = await sdk.getSwapEstimateRemoveLiquidity({
+      token0: args.token0,
+      token1: args.token1,
+      fee: args.fee,
+      liquidity: args.liquidity,
+      tickLower: args.tickLower,
+      tickUpper: args.tickUpper,
+    });
+
+    return formatSuccess({
+      liquidity: estimate.liquidity,
+      amount0: estimate.amount0,
+      amount1: estimate.amount1,
+      fee0: estimate.fee0,
+      fee1: estimate.fee1,
+      token0Symbol: estimate.token0Symbol,
+      token1Symbol: estimate.token1Symbol,
+      tickLower: estimate.tickLower,
+      tickUpper: estimate.tickUpper,
+      currentPrice: estimate.currentPrice,
+      message: `Removing ${args.liquidity} liquidity would return ${estimate.amount0} ${args.token0} + ${estimate.amount1} ${args.token1}, plus ${estimate.fee0} ${args.token0} and ${estimate.fee1} ${args.token1} in fees`,
+    });
+  }),
+};
+
+// 5. Add Liquidity by Price Range
+export const addLiquidityByPriceTool: MCPTool = {
+  name: 'gala_launchpad_add_liquidity_by_price',
+  description:
+    'Add liquidity to a pool by specifying min/max price boundaries (SDK calculates tick boundaries)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      token0: TOKEN_SYMBOL_SCHEMA,
+      token1: TOKEN_SYMBOL_SCHEMA,
+      fee: FEE_TIER_SCHEMA,
+      minPrice: {
+        type: 'string',
+        description: 'Minimum price boundary (e.g., "0.90")',
+      },
+      maxPrice: {
+        type: 'string',
+        description: 'Maximum price boundary (e.g., "1.10")',
+      },
+      amount0Desired: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Desired amount of token0 to provide',
+      },
+      amount1Desired: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Desired amount of token1 to provide',
+      },
+      amount0Min: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Minimum acceptable amount0 (optional, defaults to 0)',
+      },
+      amount1Min: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Minimum acceptable amount1 (optional, defaults to 0)',
+      },
+    },
+    required: [
+      'token0',
+      'token1',
+      'fee',
+      'minPrice',
+      'maxPrice',
+      'amount0Desired',
+      'amount1Desired',
+    ],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    // Validate wallet before execution
+    try {
+      sdk.getAddress();
+    } catch {
+      throw new Error('Wallet not configured - required for adding liquidity');
+    }
+
+    const result = await sdk.addSwapLiquidityByPrice({
+      token0: args.token0,
+      token1: args.token1,
+      fee: args.fee,
+      minPrice: args.minPrice,
+      maxPrice: args.maxPrice,
+      amount0Desired: args.amount0Desired,
+      amount1Desired: args.amount1Desired,
+      amount0Min: args.amount0Min || '0',
+      amount1Min: args.amount1Min || '0',
+    });
+
+    return formatSuccess({
+      transactionId: result.transactionId || result.id,
+      status: result.status,
+      token0: args.token0,
+      token1: args.token1,
+      priceRange: `${args.minPrice} - ${args.maxPrice}`,
+      amount0: result.amount0 || args.amount0Desired,
+      amount1: result.amount1 || args.amount1Desired,
+      liquidity: result.liquidity,
+      positionId: result.positionId,
+      message: `Liquidity added! Position: ${result.positionId || result.transactionId}`,
+    });
+  }),
+};
+
+// 6. Add Liquidity by Tick Range
+export const addLiquidityByTicksTool: MCPTool = {
+  name: 'gala_launchpad_add_liquidity_by_ticks',
+  description:
+    'Add liquidity to a pool by specifying exact tick boundaries (advanced usage)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      token0: TOKEN_SYMBOL_SCHEMA,
+      token1: TOKEN_SYMBOL_SCHEMA,
+      feeTier: FEE_TIER_SCHEMA,
+      tickLower: {
+        type: 'number',
+        description: 'Lower tick boundary (must be multiple of tickSpacing)',
+      },
+      tickUpper: {
+        type: 'number',
+        description: 'Upper tick boundary (must be multiple of tickSpacing)',
+      },
+      amount0Desired: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Desired amount of token0 to provide',
+      },
+      amount1Desired: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Desired amount of token1 to provide',
+      },
+      amount0Min: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Minimum acceptable amount0 (optional, defaults to 0)',
+      },
+      amount1Min: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Minimum acceptable amount1 (optional, defaults to 0)',
+      },
+    },
+    required: [
+      'token0',
+      'token1',
+      'feeTier',
+      'tickLower',
+      'tickUpper',
+      'amount0Desired',
+      'amount1Desired',
+    ],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    // Validate wallet before execution
+    try {
+      sdk.getAddress();
+    } catch {
+      throw new Error('Wallet not configured - required for adding liquidity');
+    }
+
+    const result = await sdk.addSwapLiquidityByTicks({
+      token0: args.token0,
+      token1: args.token1,
+      feeTier: args.feeTier,
+      tickLower: args.tickLower,
+      tickUpper: args.tickUpper,
+      amount0Desired: args.amount0Desired,
+      amount1Desired: args.amount1Desired,
+      amount0Min: args.amount0Min || '0',
+      amount1Min: args.amount1Min || '0',
+    });
+
+    return formatSuccess({
+      transactionId: result.transactionId || result.id,
+      status: result.status,
+      token0: args.token0,
+      token1: args.token1,
+      tickRange: `${args.tickLower} - ${args.tickUpper}`,
+      amount0: result.amount0 || args.amount0Desired,
+      amount1: result.amount1 || args.amount1Desired,
+      liquidity: result.liquidity,
+      positionId: result.positionId,
+      message: `Liquidity added! Position: ${result.positionId || result.transactionId}`,
+    });
+  }),
+};
+
+// 7. Remove Liquidity
+export const removeLiquidityTool: MCPTool = {
+  name: 'gala_launchpad_remove_liquidity',
+  description:
+    'Remove liquidity from an open position and withdraw underlying tokens',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      ownerAddress: {
+        ...ADDRESS_SCHEMA,
+        description: 'Wallet address that owns the position',
+      },
+      positionId: {
+        type: 'string',
+        minLength: 1,
+        description: 'Position identifier to remove liquidity from',
+      },
+      liquidity: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Amount of liquidity to remove (full liquidity to close position)',
+      },
+      amount0Min: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Minimum acceptable amount of token0 to receive',
+      },
+      amount1Min: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Minimum acceptable amount of token1 to receive',
+      },
+      deadline: {
+        type: 'number',
+        description: 'Transaction deadline (unix timestamp, optional)',
+      },
+    },
+    required: ['ownerAddress', 'positionId', 'liquidity', 'amount0Min', 'amount1Min'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    // Validate wallet before execution
+    try {
+      sdk.getAddress();
+    } catch {
+      throw new Error('Wallet not configured - required for removing liquidity');
+    }
+
+    const deadline = args.deadline || Math.floor(Date.now() / 1000) + 60 * 20; // 20 minute default
+
+    const result = await sdk.removeSwapLiquidity({
+      ownerAddress: args.ownerAddress,
+      positionId: args.positionId,
+      liquidity: args.liquidity,
+      amount0Min: args.amount0Min,
+      amount1Min: args.amount1Min,
+      deadline,
+    });
+
+    return formatSuccess({
+      transactionId: result.transactionId || result.id,
+      status: result.status,
+      positionId: args.positionId,
+      liquidity: args.liquidity,
+      amount0: result.amount0,
+      amount1: result.amount1,
+      message: `Liquidity removed! Received ${result.amount0} token0 and ${result.amount1} token1`,
+    });
+  }),
+};
+
+// 8. Collect Position Fees
+export const collectPositionFeesTool: MCPTool = {
+  name: 'gala_launchpad_collect_position_fees',
+  description:
+    'Collect accumulated trading fees from a liquidity position without modifying the position',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      ownerAddress: {
+        ...ADDRESS_SCHEMA,
+        description: 'Wallet address that owns the position',
+      },
+      positionId: {
+        type: 'string',
+        minLength: 1,
+        description: 'Position identifier to collect fees from',
+      },
+      amount0Max: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Maximum amount of token0 fees to collect (optional)',
+      },
+      amount1Max: {
+        ...DECIMAL_AMOUNT_SCHEMA,
+        description: 'Maximum amount of token1 fees to collect (optional)',
+      },
+    },
+    required: ['ownerAddress', 'positionId'],
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    // Validate wallet before execution
+    try {
+      sdk.getAddress();
+    } catch {
+      throw new Error('Wallet not configured - required for collecting fees');
+    }
+
+    const result = await sdk.collectSwapPositionFees({
+      ownerAddress: args.ownerAddress,
+      positionId: args.positionId,
+      amount0Max: args.amount0Max,
+      amount1Max: args.amount1Max,
+    });
+
+    return formatSuccess({
+      transactionId: result.transactionId || result.id,
+      status: result.status,
+      positionId: args.positionId,
+      amount0Collected: result.amount0,
+      amount1Collected: result.amount1,
+      message: `Fees collected! ${result.amount0} token0 and ${result.amount1} token1 harvested`,
+    });
+  }),
+};
+
+// Export all liquidity position tools
+export const liquidityPositionTools: MCPTool[] = [
+  getUserLiquidityPositionsTool,
+  getLiquidityPositionByIdTool,
+  getLiquidityPositionTool,
+  estimateRemoveLiquidityTool,
+  addLiquidityByPriceTool,
+  addLiquidityByTicksTool,
+  removeLiquidityTool,
+  collectPositionFeesTool,
+];

package/src/tools/index.ts

@@ -0,0 +1,94 @@
+/**
+ * Tool Registry
+ *
+ * Enhanced tool registry with auto-validation and metadata.
+ * Uses tool-registry system for robust tool management.
+ *
+ * @see src/utils/tool-registry.ts
+ */
+
+import { poolTools } from './pools/index.js';
+import { tradingTools } from './trading/index.js';
+import { dexTools } from './dex/index.js';
+import { balanceTools } from './balance/index.js';
+import { creationTools } from './creation/index.js';
+import { socialTools } from './social/index.js';
+import { transferTools } from './transfers/index.js';
+import { utilityTools } from './utils/index.js';
+import { createToolRegistry, logToolRegistry } from '../utils/tool-registry.js';
+
+/**
+ * Tool categories with metadata
+ */
+const toolCategories = [
+  {
+    name: 'pools',
+    description: 'Pool management, pricing, and token availability checks',
+    tools: poolTools,
+  },
+  {
+    name: 'trading',
+    description: 'Token trading operations (buy, sell, calculate amounts)',
+    tools: tradingTools,
+  },
+  {
+    name: 'dex',
+    description: 'DEX/GalaSwap trading for graduated tokens (NEW in v3.23.0)',
+    tools: dexTools,
+  },
+  {
+    name: 'balance',
+    description: 'Balance queries and portfolio management',
+    tools: balanceTools,
+  },
+  {
+    name: 'creation',
+    description: 'Token creation and launch operations',
+    tools: creationTools,
+  },
+  {
+    name: 'social',
+    description: 'Comments and social interactions',
+    tools: socialTools,
+  },
+  {
+    name: 'transfers',
+    description: 'Token and GALA transfer operations',
+    tools: transferTools,
+  },
+  {
+    name: 'utils',
+    description: 'Utility tools (wallet, config, SDK documentation)',
+    tools: utilityTools,
+  },
+];
+
+/**
+ * Enhanced tool registry with validation (72 tools total):
+ * - Pools: 17 tools
+ * - Trading: 13 tools
+ * - DEX/GalaSwap: 13 tools (5 swap + 8 liquidity)
+ * - Balance: 6 tools
+ * - Creation: 4 tools
+ * - Social: 2 tools
+ * - Transfers: 2 tools
+ * - Utilities: 15 tools (config, version, environment switching, wallet mgmt, etc.)
+ */
+export const registry = createToolRegistry(toolCategories, 72);
+
+/**
+ * Complete tool array (for backward compatibility)
+ */
+export const tools = registry.tools;
+
+// Log registry statistics in debug mode
+if (process.env.DEBUG === 'true') {
+  logToolRegistry(registry);
+}
+
+// Throw error if registry is invalid
+if (!registry.isValid) {
+  throw new Error(
+    `Tool registry validation failed:\n${registry.errors.join('\n')}`
+  );
+}

package/src/tools/pools/fetchAllPools.ts

@@ -0,0 +1,47 @@
+/**
+ * Fetch All Pools Tool
+ *
+ * Convenience tool that fetches all available pools with automatic pagination.
+ * Equivalent to calling fetchPools with limit: 0.
+ */
+
+import type { MCPTool } from '../../types/mcp.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+
+export const fetchAllPoolsTool: MCPTool = {
+  name: 'gala_launchpad_fetch_all_pools',
+  description: 'Fetch all available pools with automatic pagination. No page/limit parameters needed - returns ALL pools matching filters.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      search: {
+        type: 'string',
+        minLength: 1,
+        maxLength: 100,
+        description: 'Optional search query (fuzzy match filter)',
+      },
+      tokenName: {
+        type: 'string',
+        minLength: 3,
+        maxLength: 20,
+        pattern: '^[a-zA-Z0-9]{3,20}$',
+        description: 'Optional token name (exact match filter)',
+      },
+      type: {
+        type: 'string',
+        enum: ['recent', 'popular'],
+        description: 'Type of pools to fetch (default: recent)',
+      },
+    },
+  },
+  handler: withErrorHandling(async (sdk, args) => {
+    const result = await sdk.fetchAllPools({
+      ...(args.search && { search: args.search }),
+      ...(args.tokenName && { tokenName: args.tokenName }),
+      ...(args.type && { type: args.type }),
+    });
+
+    return formatSuccess(result);
+  }),
+};