@gala-chain/launchpad-mcp-server 1.21.6 → 1.22.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 1.22.0
+
+### Minor Changes
+
+- 0a49faf: **GalaSwap Liquidity Position Management (v3.25.0 SDK / v1.20.0 MCP)**
+
+  Comprehensive liquidity position management for concentrated liquidity provision on GalaSwap DEX.
+  Liquidity providers can now earn passive trading fees by providing liquidity within specific price
+  ranges.
+
+  ### 8 New SDK Methods (LaunchpadSDK)
+  1. **getSwapUserLiquidityPositions(ownerAddress, limit?, bookmark?)** - View all open positions
+     for a wallet with pagination support
+  2. **getSwapLiquidityPositionById(ownerAddress, positionId)** - Get specific position by UUID
+  3. **getSwapLiquidityPosition(ownerAddress, position)** - Get position by token pair and tick
+     range
+  4. **addSwapLiquidityByPrice(args)** - Create position using user-friendly price ranges (e.g.,
+     min: 0.95, max: 1.05)
+  5. **addSwapLiquidityByTicks(args)** - Create position using precise tick boundaries (advanced)
+  6. **getSwapEstimateRemoveLiquidity(args)** - Preview amounts and fees before executing removal
+  7. **removeSwapLiquidity(args)** - Close or reduce position with slippage protection
+  8. **collectSwapPositionFees(args)** - Harvest accumulated trading fees without closing position
+
+  ### 8 New MCP Tools
+
+  All SDK methods exposed as MCP tools with full type validation and privateKey override support:
+  - `gala_launchpad_get_user_liquidity_positions` - List positions with pagination
+  - `gala_launchpad_get_liquidity_position_by_id` - Get by position ID
+  - `gala_launchpad_get_liquidity_position` - Get by token pair
+  - `gala_launchpad_add_liquidity_by_price` - Create position (price-based)
+  - `gala_launchpad_add_liquidity_by_ticks` - Create position (tick-based)
+  - `gala_launchpad_estimate_remove_liquidity` - Estimate removal amounts
+  - `gala_launchpad_remove_liquidity` - Execute removal
+  - `gala_launchpad_collect_position_fees` - Collect accumulated fees
+
+  ### 4 New Slash Commands (Prompts)
+
+  Quick-access workflows for Claude Desktop users:
+  - `/galachain-launchpad:my-positions` - View all liquidity positions
+  - `/galachain-launchpad:add-liquidity` - Create new position (guided workflow)
+  - `/galachain-launchpad:remove-liquidity` - Close position (with estimates)
+  - `/galachain-launchpad:collect-fees` - Harvest accumulated fees
+
+  ### Key Features
+
+  **Fee Tiers**: Support for standard GalaSwap fee tiers (500 bps = 0.05%, 3000 bps = 0.30%, 10000
+  bps = 1.00%)
+
+  **Price Range Creation**: User-friendly price range interface (0.95 - 1.05) automatically converts
+  to precise tick boundaries
+
+  **Tick-Based Creation**: Advanced users can create positions using exact tick boundaries for
+  precise capital management
+
+  **Fee Collection**: Harvest passive trading fees without closing position
+
+  **Estimation**: Preview exact amounts and fees before executing any transaction
+
+  **Slippage Protection**: Built-in slippage tolerance for all operations
+
+  **Pagination**: Efficient position listing with bookmark support for large portfolios
+
+  ### Documentation & Examples
+  - **Demo Script**: `packages/sdk/examples/demo-liquidity-positions.ts` - Complete workflow
+    demonstration
+  - **SDK Docs**: `explain_sdk_usage` tool includes `liquidity-positions` topic with runnable
+    examples
+  - **Integration Guide**: CLAUDE.md includes comprehensive LP integration section
+
+  ### Test Coverage
+  - **54 SDK Unit Tests**: Complete test coverage for all 8 methods with edge cases
+  - **39 MCP Tool Tests**: Full validation of all 8 MCP tools and input schemas
+  - **1401 Total Tests**: Full regression test suite passing
+
+  ### Version Updates
+  - SDK: 3.24.2 → 3.25.0 (minor version bump)
+  - MCP Server: 1.19.2 → 1.20.0 (minor version bump)
+
+### Patch Changes
+
+- Updated dependencies [0a49faf]
+- Updated dependencies
+  - @gala-chain/launchpad-sdk@3.27.0
+
 ## 1.19.0
 
 ### Minor Changes

package/dist/generated/version.d.ts

@@ -3,5 +3,5 @@
  * This file is generated by scripts/inject-version.ts during build
  * DO NOT EDIT MANUALLY
  */
-export declare const MCP_SERVER_VERSION = "1.21.6";
+export declare const MCP_SERVER_VERSION = "1.22.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/generated/version.js

@@ -6,5 +6,5 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MCP_SERVER_VERSION = void 0;
-exports.MCP_SERVER_VERSION = '1.21.6';
+exports.MCP_SERVER_VERSION = '1.22.0';
 //# sourceMappingURL=version.js.map

package/docs/AI-AGENT-PATTERNS.md

@@ -0,0 +1,555 @@
+# AI Agent Patterns for Gala Launchpad MCP Server
+
+This guide provides AI agents with common workflows, gotchas, and best practices when using the `galachain-launchpad` MCP server.
+
+## Table of Contents
+
+- [Common Workflows](#common-workflows)
+- [Critical Gotchas](#critical-gotchas)
+- [Constraint Reference](#constraint-reference)
+- [Error Troubleshooting](#error-troubleshooting)
+- [Best Practices](#best-practices)
+
+---
+
+## Common Workflows
+
+### 1. Token Launch Workflow
+
+**Complete token creation from scratch:**
+
+```typescript
+// Step 1: Verify token name is available
+gala_launchpad_check_token_name({
+  tokenName: 'mytoken'
+})
+// Response: { available: true, message: "Token name is available" }
+
+// Step 2: Verify token symbol is available
+gala_launchpad_check_token_symbol({
+  symbol: 'MTK'
+})
+// Response: { available: true, message: "Token symbol is available" }
+
+// Step 3: Upload token image (optional, can use URL instead)
+gala_launchpad_upload_token_image({
+  tokenName: 'mytoken',
+  imagePath: '/absolute/path/to/image.png'
+})
+// Response: { url: 'https://launchpad.galachain.com/uploads/mytoken.png' }
+
+// Step 4: Launch the token
+gala_launchpad_launch_token({
+  tokenName: 'mytoken',
+  tokenSymbol: 'MTK',
+  tokenDescription: 'My awesome token for the community',
+  tokenImage: 'https://launchpad.galachain.com/uploads/mytoken.png',
+  preBuyQuantity: '100', // Optional initial buy
+  websiteUrl: 'https://mytoken.com',
+  twitterUrl: 'https://twitter.com/mytoken'
+})
+// Response: { tokenName: 'mytoken', transactionId: '...' }
+
+// Step 5: Get the frontend URL
+gala_launchpad_get_url_by_token_name({
+  tokenName: 'mytoken'
+})
+// Response: { url: 'https://launchpad.galachain.com/token/mytoken' }
+```
+
+### 2. Trading Workflow (Buy Tokens)
+
+**Two-step process: Calculate → Execute**
+
+```typescript
+// Step 1: Calculate buy amount (REQUIRED FIRST STEP)
+const calcResult = gala_launchpad_calculate_buy_amount({
+  tokenName: 'woohoo',
+  amount: '10',        // Spending 10 GALA
+  type: 'native'       // 'native' = GALA amount
+})
+// Response: {
+//   amount: '16843.7579794843252',           // <- THIS is expectedAmount for buy()
+//   reverseBondingCurveFee: '0.059280156',   // <- THIS is maxAcceptableReverseBondingCurveFee
+//   transactionFee: '0.00141090',
+//   gasFee: '1'
+// }
+
+// Step 2: Execute buy with calculated expectedAmount AND reverseBondingCurveFee
+gala_launchpad_buy_tokens({
+  tokenName: 'woohoo',
+  amount: '10',                                           // Same as Step 1
+  type: 'native',                                         // Same as Step 1
+  expectedAmount: '16843.7579794843252',                  // <- Use result.amount from Step 1
+  maxAcceptableReverseBondingCurveFee: '0.059280156',    // <- Use result.reverseBondingCurveFee from Step 1
+  slippageToleranceFactor: 0.05                           // 5% slippage protection
+})
+// Response: { transactionId: '...', status: 'completed' }
+
+// Step 3: Verify trade completed
+gala_launchpad_fetch_trades({
+  tokenName: 'woohoo',
+  userAddress: 'eth|your-address',
+  limit: 1
+})
+```
+
+**⚠️ CRITICAL:**
+- `expectedAmount` must be `result.amount` from calculate function, NOT your input amount!
+- `maxAcceptableReverseBondingCurveFee` must be `result.reverseBondingCurveFee` from calculate function!
+
+### 3. Trading Workflow (Sell Tokens)
+
+**Same two-step pattern:**
+
+```typescript
+// Step 1: Calculate sell amount
+const calcResult = gala_launchpad_calculate_sell_amount({
+  tokenName: 'woohoo',
+  amount: '1000',      // Selling 1000 tokens
+  type: 'exact'        // 'exact' = exact token amount
+})
+// Response: {
+//   amount: '5.234567',                    // <- THIS is expectedAmount for sell()
+//   reverseBondingCurveFee: '2.617284',   // <- THIS is maxAcceptableReverseBondingCurveFee
+//   transactionFee: '0.00523457',
+//   gasFee: '1'
+// }
+
+// Step 2: Execute sell with calculated expectedAmount AND reverseBondingCurveFee
+gala_launchpad_sell_tokens({
+  tokenName: 'woohoo',
+  amount: '1000',
+  type: 'exact',
+  expectedAmount: '5.234567',                           // <- Use result.amount from Step 1
+  maxAcceptableReverseBondingCurveFee: '2.617284',     // <- Use result.reverseBondingCurveFee from Step 1
+  slippageToleranceFactor: 0.05
+})
+```
+
+### 4. Portfolio Management Workflow
+
+**Check balances and trading activity:**
+
+```typescript
+// Get GALA balance
+gala_launchpad_fetch_gala_balance({
+  address: 'eth|your-address'  // Optional, defaults to authenticated wallet
+})
+
+// Get specific token balance (optimized single-token lookup)
+gala_launchpad_fetch_token_balance({
+  tokenName: 'woohoo',
+  address: 'eth|your-address'
+})
+
+// Get all tokens held (with filtering)
+gala_launchpad_fetch_tokens_held({
+  address: 'eth|your-address',
+  tokenName: 'woohoo',  // Optional exact match filter
+  limit: 20             // Max 20 for user operations
+})
+
+// Get all tokens created by user
+gala_launchpad_fetch_tokens_created({
+  address: 'eth|your-address',
+  search: 'test',  // Optional fuzzy search filter
+  limit: 20
+})
+
+// Get trade history
+gala_launchpad_fetch_trades({
+  tokenName: 'woohoo',
+  userAddress: 'eth|your-address',
+  tradeType: 'BUY',  // Optional: 'BUY' or 'SELL'
+  limit: 20,         // Max 20 for trade operations
+  sortOrder: 'DESC'
+})
+```
+
+### 5. Pool Analysis Workflow
+
+**Discover and analyze token pools:**
+
+```typescript
+// Fetch recent/trending pools
+gala_launchpad_fetch_pools({
+  type: 'trending',  // 'recent', 'trending', or 'user'
+  limit: 100         // Max 100 for pool operations
+})
+
+// Get detailed pool state
+gala_launchpad_fetch_pool_details({
+  tokenName: 'woohoo'
+})
+
+// Get holder distribution
+gala_launchpad_fetch_token_distribution({
+  tokenName: 'woohoo'
+})
+
+// Get volume data for charting
+gala_launchpad_fetch_volume_data({
+  tokenName: 'woohoo',
+  resolution: '1h',  // '1m', '5m', '15m', '1h', '4h', '1d'
+  from: '2024-01-01T00:00:00Z',
+  to: '2024-01-31T23:59:59Z'
+})
+```
+
+---
+
+## Critical Gotchas
+
+### Gotcha #1: Missing reverseBondingCurveFee Parameter ⚠️🔥
+
+**Problem:** AI agents forget to pass `maxAcceptableReverseBondingCurveFee`, causing transaction failures.
+
+**Wrong:**
+```typescript
+// Step 1: Calculate
+const calc = gala_launchpad_calculate_sell_amount({ tokenName: 'anime', amount: '500', type: 'exact' })
+// calc = { amount: '0.7056532', reverseBondingCurveFee: '0.3528266', ... }
+
+// Step 2: Execute - MISSING reverseBondingCurveFee!
+gala_launchpad_sell_tokens({
+  tokenName: 'anime',
+  amount: '500',
+  type: 'exact',
+  expectedAmount: '0.7056532',  // ✅ Got this right
+  // ❌ MISSING: maxAcceptableReverseBondingCurveFee
+  slippageToleranceFactor: 0.05
+})
+// Result: Transaction fails with "FAILED" status
+```
+
+**Correct:**
+```typescript
+// Step 1: Calculate
+const calc = gala_launchpad_calculate_sell_amount({ tokenName: 'anime', amount: '500', type: 'exact' })
+// calc = { amount: '0.7056532', reverseBondingCurveFee: '0.3528266', ... }
+
+// Step 2: Execute - Include BOTH parameters from calculation
+gala_launchpad_sell_tokens({
+  tokenName: 'anime',
+  amount: '500',
+  type: 'exact',
+  expectedAmount: '0.7056532',                          // ✅ From result.amount
+  maxAcceptableReverseBondingCurveFee: '0.3528266',   // ✅ From result.reverseBondingCurveFee
+  slippageToleranceFactor: 0.05
+})
+// Result: Transaction succeeds!
+```
+
+**Fix:** Always extract BOTH `result.amount` AND `result.reverseBondingCurveFee` from calculate functions, then pass BOTH to buy/sell.
+
+**This applies to both buy AND sell operations!**
+
+### Gotcha #2: expectedAmount Parameter Confusion ⚠️
+
+**Problem:** AI agents use the input `amount` as `expectedAmount`, causing WebSocket timeouts.
+
+**Wrong:**
+```typescript
+gala_launchpad_buy_tokens({
+  amount: '10',
+  expectedAmount: '10'  // ❌ WRONG - This is your input, not the expected output!
+})
+```
+
+**Correct:**
+```typescript
+// Step 1: Calculate first
+const calc = gala_launchpad_calculate_buy_amount({ amount: '10', ... })
+// calc.amount = '16843.7579794843252'
+
+// Step 2: Use calc.amount as expectedAmount
+gala_launchpad_buy_tokens({
+  amount: '10',
+  expectedAmount: '16843.7579794843252'  // ✅ CORRECT - Use result.amount
+})
+```
+
+**Fix:** Always call `calculate*Amount()` first, then use `result.amount` as `expectedAmount`.
+
+### Gotcha #3: Limit Validation Errors
+
+**Problem:** AI agents hit "Limit must be between 1 and 20" errors when using `limit: 100`.
+
+**Root Cause:** Different operations have different maximum limits:
+- Trade operations: Max 20
+- User operations (tokens held/created): Max 20
+- Pool operations: Max 100
+- Comment operations: Max 50
+
+**Wrong:**
+```typescript
+gala_launchpad_fetch_trades({
+  limit: 100  // ❌ WRONG - Trades max is 20!
+})
+```
+
+**Correct:**
+```typescript
+gala_launchpad_fetch_trades({
+  limit: 20  // ✅ CORRECT - Respects constraint
+})
+
+gala_launchpad_fetch_pools({
+  limit: 100  // ✅ CORRECT - Pools allow 100
+})
+```
+
+**Fix:** Use the constraint reference table below for correct limits.
+
+### Gotcha #4: Type Parameter Ambiguity
+
+**Problem:** Confusion between `type: 'native'` and `type: 'exact'`.
+
+**When to use 'native' (GALA amount):**
+- "I want to spend 10 GALA" → `{ amount: '10', type: 'native' }`
+- "I want to receive 5 GALA" → `{ amount: '5', type: 'native' }`
+
+**When to use 'exact' (exact token amount):**
+- "I want to buy exactly 1000 tokens" → `{ amount: '1000', type: 'exact' }`
+- "I want to sell exactly 500 tokens" → `{ amount: '500', type: 'exact' }`
+
+**Most Common:** Use `'native'` when you know the GALA amount.
+
+### Gotcha #5: Token Filtering Confusion
+
+**Problem:** Not using the right filter for the task.
+
+**Use `tokenName` for exact lookups:**
+```typescript
+gala_launchpad_fetch_tokens_held({
+  tokenName: 'anime',  // Exact match
+  limit: 1             // Only need 1 result
+})
+```
+
+**Use `search` for discovery:**
+```typescript
+gala_launchpad_fetch_tokens_held({
+  search: 'dragon',  // Fuzzy search
+  limit: 10          // Get multiple matches
+})
+```
+
+**Don't mix both:** If you provide both, `tokenName` takes precedence.
+
+### Gotcha #6: Wallet Address Format
+
+**Problem:** Wrong wallet address format causes validation errors.
+
+**Backend Format (for API):**
+- ✅ `'eth|abc123...'` - Prefixed format
+- ❌ `'0xabc123...'` - Standard Ethereum format
+
+**Conversion Pattern:**
+```typescript
+// From standard to backend format
+const backendAddress = address.startsWith('0x')
+  ? `eth|${address.slice(2)}`
+  : address
+
+// From backend to standard format
+const standardAddress = address.startsWith('eth|')
+  ? `0x${address.slice(4)}`
+  : address
+```
+
+---
+
+## Constraint Reference
+
+### Pagination Limits by Operation Type
+
+| Operation Type | Max Limit | SDK Source |
+|---------------|-----------|------------|
+| **Trade Operations** | 20 | `TRADE_CONSTRAINTS.PAGINATION.MAX_LIMIT` |
+| `fetchTrades` | 20 | packages/sdk/src/types/trade.dto.ts:331 |
+| **User Operations** | 20 | `USER_CONSTRAINTS.PAGINATION.MAX_LIMIT` |
+| `fetchTokensHeld` | 20 | packages/sdk/src/types/user.dto.ts:297 |
+| `fetchTokensCreated` | 20 | packages/sdk/src/types/user.dto.ts:297 |
+| **Pool Operations** | 100 | `PAGINATION_CONSTRAINTS.MAX_LIMIT` |
+| `fetchPools` | 100 | packages/sdk/src/types/launchpad.dto.ts:587 |
+| **Comment Operations** | 50 | `COMMENT_CONSTRAINTS.PAGINATION.MAX_LIMIT` |
+| `fetchComments` | 50 | packages/sdk/src/types/comment.dto.ts:149 |
+
+### Common Validation Rules
+
+| Parameter | Pattern | Example |
+|-----------|---------|---------|
+| `tokenName` | `^[a-z0-9_-]{2,20}$` | `'mytoken'`, `'test_token'` |
+| `tokenSymbol` | `^[A-Z0-9]{2,10}$` | `'MTK'`, `'TEST123'` |
+| `address` | `^(0x[a-fA-F0-9]{40}\|eth\\|[a-fA-F0-9]{40})$` | `'eth\|abc123...'`, `'0xabc123...'` (auto-normalized) |
+| `amount` | `^[0-9.]+$` | `'10'`, `'100.5'` |
+| `slippageTolerance` | `0-1` (decimal) | `0.05` (5%), `0.01` (1%) |
+
+---
+
+## Error Troubleshooting
+
+### "Limit must be a number between 1 and 20"
+
+**Cause:** Using `limit: 100` on trade or user operations.
+
+**Solution:**
+```typescript
+// Wrong
+gala_launchpad_fetch_trades({ limit: 100 })
+
+// Correct
+gala_launchpad_fetch_trades({ limit: 20 })
+```
+
+### "WebSocket timeout on trade execution"
+
+**Cause:** Using wrong `expectedAmount` (likely using input amount instead of calculated result).
+
+**Solution:**
+```typescript
+// Wrong
+const calc = gala_launchpad_calculate_buy_amount({ amount: '10', ... })
+gala_launchpad_buy_tokens({ amount: '10', expectedAmount: '10' })
+
+// Correct
+const calc = gala_launchpad_calculate_buy_amount({ amount: '10', ... })
+gala_launchpad_buy_tokens({ amount: '10', expectedAmount: calc.amount })
+```
+
+### "Token name validation failed"
+
+**Cause:** Token name doesn't match pattern `^[a-z0-9_-]{2,20}$`.
+
+**Valid:** `'mytoken'`, `'test-token'`, `'token_123'`
+**Invalid:** `'MyToken'` (uppercase), `'a'` (too short), `'my token'` (space)
+
+**Solution:** Use lowercase alphanumeric with dashes/underscores, 2-20 characters.
+
+### "Token symbol validation failed"
+
+**Cause:** Token symbol doesn't match pattern `^[A-Z0-9]{2,10}$`.
+
+**Valid:** `'MTK'`, `'TEST123'`, `'ABC'`
+**Invalid:** `'mtk'` (lowercase), `'A'` (too short), `'MY-TOKEN'` (dash)
+
+**Solution:** Use uppercase alphanumeric only, 2-10 characters.
+
+### "At least one social URL required"
+
+**Cause:** Launching token without `websiteUrl`, `twitterUrl`, or `telegramUrl`.
+
+**Solution:** Provide at least one social link:
+```typescript
+gala_launchpad_launch_token({
+  // ... other params
+  websiteUrl: 'https://mytoken.com'  // At least one required
+})
+```
+
+---
+
+## Best Practices
+
+### 1. Always Calculate Before Trading
+
+Never skip the calculate step - it provides:
+- Accurate `expectedAmount` for slippage protection
+- Fee breakdown for transparency
+- Price impact analysis for informed decisions
+
+### 2. Use Appropriate Limits
+
+Match your `limit` to the operation type:
+- Trades/User operations: Use 20 or less
+- Pools: Can use up to 100
+- Comments: Can use up to 50
+
+### 3. Handle Slippage Appropriately
+
+Common slippage tolerance factors:
+- `0.01` (1%) - Low volatility, stable pools
+- `0.05` (5%) - Standard for most trades
+- `0.10` (10%) - High volatility, new tokens
+
+### 4. Use Token Filtering Efficiently
+
+**For single token lookups:**
+```typescript
+gala_launchpad_fetch_token_balance({
+  tokenName: 'anime',
+  address: 'eth|...'
+})
+// 99% payload reduction vs fetching all tokens
+```
+
+**For discovery:**
+```typescript
+gala_launchpad_fetch_tokens_held({
+  search: 'dragon',
+  limit: 10
+})
+```
+
+### 5. Verify Trades Complete
+
+After executing trades, always verify:
+```typescript
+gala_launchpad_fetch_trades({
+  tokenName: 'woohoo',
+  userAddress: 'eth|...',
+  limit: 1,
+  sortOrder: 'DESC'
+})
+```
+
+### 6. Check Availability Before Launch
+
+Always verify token name and symbol availability before launching:
+```typescript
+// Step 1: Check name
+gala_launchpad_check_token_name({ tokenName: 'mytoken' })
+
+// Step 2: Check symbol
+gala_launchpad_check_token_symbol({ symbol: 'MTK' })
+
+// Step 3: Launch if both available
+gala_launchpad_launch_token({ ... })
+```
+
+---
+
+## Quick Reference Card
+
+### Trading Flow
+1. `calculate_buy_amount()` or `calculate_sell_amount()`
+2. Extract `result.amount` from response
+3. Use `result.amount` as `expectedAmount` in buy/sell
+4. Verify with `fetch_trades()`
+
+### Limit Values
+- Trades: 20 max
+- User ops: 20 max
+- Pools: 100 max
+- Comments: 50 max
+
+### Type Parameter
+- `'native'` = GALA amount (most common)
+- `'token'` = Exact token amount
+
+### Token Filtering
+- `tokenName` = Exact match (faster)
+- `search` = Fuzzy match (discovery)
+
+### Address Format
+- API expects: `'eth|abc123...'`
+- Convert from: `'0xabc123...'`
+
+---
+
+**For more details, see:**
+- [MCP Server README](../README.md)
+- [SDK Documentation](../../sdk/README.md)
+- [Constraints Reference](./CONSTRAINTS-REFERENCE.md)