@gala-chain/launchpad-mcp-server 1.22.4 → 1.23.0

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)