@gala-chain/launchpad-mcp-server 1.7.2 → 1.7.4

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 1.7.4
+
+### Patch Changes
+
+- Fix demo script failures caused by missing tokenName field in poolDetails response.
+
+  **Root Causes:**
+  - GalaChainService response transformation broke property access after Phase 2 type safety changes
+  - fetchPoolDetails didn't include tokenName field that demo code expects
+
+  **Changes:**
+  - Add tokenName field to fetchPoolDetails return value for convenience
+  - Fix GalaChainService response transformation to preserve structure using type assertion patterns
+  - Maintain type safety throughout with proper TypeScript patterns
+
+  **Impact:**
+  - Resolves 9 failing demo scenarios with "Token name is required" validation errors
+  - All calculation methods (calculateBuyAmountLocal, calculateSellAmountLocal, calculateBuyAmount)
+    now work correctly
+  - Demo script runs without validation errors
+
+- Updated dependencies
+  - @gala-chain/launchpad-sdk@3.11.3
+
+## 1.7.3
+
+### Patch Changes
+
+- chore: Update SDK dependency to 3.11.2
+
 ## 1.7.1 - 2025-10-11
 
 ### Fixed
@@ -23,7 +53,10 @@
 
 ### Context
 
-v1.7.0 was published with incorrect tool counts due to not accounting for cache management tools added in v1.6.0. The registry validation expected 49 tools but 50 were actually registered, causing the MCP server to crash on startup with "Tool registry validation failed: Tool count mismatch: expected 49, got 50".
+v1.7.0 was published with incorrect tool counts due to not accounting for cache management tools
+added in v1.6.0. The registry validation expected 49 tools but 50 were actually registered, causing
+the MCP server to crash on startup with "Tool registry validation failed: Tool count mismatch:
+expected 49, got 50".
 
 ## 1.7.0 - 2025-10-11
 
@@ -44,7 +77,8 @@ v1.7.0 was published with incorrect tool counts due to not accounting for cache
 ### Changed
 
 - Updated SDK dependency from ^3.10.0 to ^3.11.0
-- Tool count increased from 49 to 50 tools (NOTE: v1.6.0 added 2 cache tools, bringing count from 47 to 49)
+- Tool count increased from 49 to 50 tools (NOTE: v1.6.0 added 2 cache tools, bringing count from 47
+  to 49)
 - Pool Management tools increased from 13 to 14 tools
 - Benefits from SDK v3.11.0 auto-pagination with 5x performance improvement
 
@@ -66,10 +100,12 @@ v1.7.0 was published with incorrect tool counts due to not accounting for cache
 
 ### Documentation
 
-- **Critical graduation calculation clarification** - Added comprehensive documentation to prevent misinterpretation of `calculateBuyAmountForGraduation` results
+- **Critical graduation calculation clarification** - Added comprehensive documentation to prevent
+  misinterpretation of `calculateBuyAmountForGraduation` results
   - Updated MCP README with "Understanding Graduation Calculations" section
   - Added amount field reference table showing what each calculation method returns
-  - Clarified that `amount` field represents **GALA cost** (e.g., "1594263.419" = 1.59 million GALA), NOT token quantity
+  - Clarified that `amount` field represents **GALA cost** (e.g., "1594263.419" = 1.59 million
+    GALA), NOT token quantity
   - Added real-world examples showing wrong vs correct interpretation
   - Updated CLAUDE.md with "Token Graduation Patterns" section and complete workflow examples
   - Emphasized that graduation amounts are typically hundreds of thousands to millions of GALA

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)