@gala-chain/launchpad-sdk 3.31.2 → 4.0.1-beta.0

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 4.0.0
+
+### BREAKING CHANGES
+
+- **`fetchLaunchpadTokenSpotPrice()` method DEPRECATED**
+  - **Deprecated**: v3.22.7
+  - **Status**: Still functional in v4.0.0, will be removed in v5.0.0
+  - **Replacement**: `fetchTokenPrice()` with smart routing (v3.22.7+)
+  - **Why**: Unified pricing interface for both launchpad and DEX tokens. Single method handles all price queries with automatic routing.
+  - **Impact**: Update your code to use `fetchTokenPrice()` before v5.0.0
+
+  **Migration Path:**
+  ```typescript
+  // ⚠️ DEPRECATED in v4.0.0 - Still works but will be removed in v5.0.0
+  const price = await sdk.fetchLaunchpadTokenSpotPrice('anime');
+
+  // ✅ RECOMMENDED (v4.0.0+)
+  const price = await sdk.fetchTokenPrice({ tokenName: 'anime' });
+
+  // Also supports tokenId format for DEX tokens
+  const priceById = await sdk.fetchTokenPrice({
+    tokenId: 'Token|Unit|BENE|none'
+  });
+  ```
+
+### New Features
+
+- **New Service Clients** - Low-level HTTP clients for direct blockchain interactions:
+  - `DexBackendClient` - Direct access to DEX Backend API for advanced swap operations and pool queries
+  - `GalaChainGatewayClient` - Direct access to GalaChain Gateway for token operations and DEX contract calls
+  - **Note**: These are internal clients used by higher-level SDK methods. Standard SDK methods continue to work without changes.
+
+### Deprecation Status
+
+- ✅ **Token format parsing** (v3.33.0 enforced) - Continues to enforce delimited formats only (`'GALA|Unit|none|none'`)
+- ✅ **`parseToken()` signature** (v3.33.0 enforced) - Continues strict validation
+
+### Migration Checklist
+
+- [ ] Replace `fetchLaunchpadTokenSpotPrice()` calls with `fetchTokenPrice()`
+- [ ] Test price queries for both launchpad and DEX tokens
+- [ ] Verify all trading operations use delimited token format
+- [ ] Run full test suite against v4.0.0
+
+### Expected Impact
+
+- **For launchpad tokens**: No functional change, just method name
+- **For DEX tokens**: New method works with all token types (previously would fail)
+- **Bundle size**: No change (both methods were similar complexity)
+- **Migration time**: Low (single method replacement across codebase)
+
+---
+
+## 3.33.0
+
+### BREAKING CHANGES
+
+- **Token format parsing now ONLY accepts delimited formats (pipe or dollar-delimited)**
+  - **Before (v3.32.x)**: Plain token strings like `'GALA'` and `'GUSDC'` were accepted and converted to delimited format
+  - **After (v3.33.0)**: All tokens MUST be in delimited format: `'GALA|Unit|none|none'` or `'GALA$Unit$none$none'`
+  - **Why**: Removed dangerous "escape hatch" that allowed ambiguous token identifiers. Enforces strict security-by-design.
+  - **Affected Methods**: `getSwapQuoteExactInput()`, `getSwapQuoteExactOutput()`, `executeSwap()`, `addSwapLiquidityByPrice()`, `addSwapLiquidityByTicks()`, `removeSwapLiquidity()`, `getSwapPoolInfo()`
+
+  **Migration Path:**
+  ```typescript
+  // ❌ NO LONGER WORKS (v3.33.0+)
+  await sdk.executeSwap('GALA', 'GUSDC', '100', ...);
+
+  // ✅ REQUIRED FORMAT (v3.33.0+)
+  await sdk.executeSwap('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100', ...);
+  ```
+
+- **`parseToken()` function signature changed**
+  - **Before**: `parseToken(token: string | TokenClassKey, allowPlainStrings: boolean = false)`
+  - **After**: `parseToken(token: string | TokenClassKey)`
+  - **Why**: The `allowPlainStrings` parameter created a security escape hatch. Removed entirely.
+  - **Migration**: Always provide delimited token format
+
+### Security Enhancements
+
+- ✅ **Strict token format enforcement** prevents injection attacks via token string manipulation
+- ✅ **Eliminated ambiguous parsing** - no more fallback to plain string conversion
+- ✅ **Deterministic security** - no escapehatches or opt-in flags that weaken validation
+- ✅ **Explicit token specification** - users must provide full TokenClassKey structure via delimiters
+
+### Documentation Updates
+
+- Added comprehensive [Token Format Migration guide](./README.md#token-format-migration-v330) to README
+- Updated all DEX trading examples to use delimited token format
+- Added breaking change notices to API.md and EXAMPLES.md
+- Updated JSDoc comments in token-parser.ts with v3.33.0 enforcement notes
+
 ## 3.29.0
 
 ### BREAKING CHANGES
@@ -507,7 +599,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
 
   Token symbols cached using pipe-delimited format with `token:` prefix to distinguish from
   tokenName entries:
-  - Example: `token:Token|Unit|GUSDC|eth:0x...`
+  - Example: `token:GUSDC|Unit|none|eth:0x...`
 
   ### Symbol Immutability
 
@@ -822,7 +914,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
   - Comprehensive unit tests (14 tests covering success/error/edge cases)
 
   **Features:**
-  - Flexible Token ID support: String format ('Token|Unit|GUSDC|eth:0x...') or object format
+  - Flexible Token ID support: String format ('GUSDC|Unit|none|eth:0x...') or object format
   - Comprehensive metadata: Returns symbol, name, decimals, image, verification status, network info
   - DEX API Integration: Queries /v1/tokens endpoint with URL-encoded token class keys
   - Proper error handling: Validates token existence and format
@@ -878,7 +970,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
   **Format 1: Standard (collection="Token")**
 
   ```
-  Token|Unit|GALA|none → GALA$Unit$none$none
+  Token|Unit|BENE|none → GALA$Unit$none$none
   Token|Unit|SILK|none → SILK$Unit$none$none
   ```
 
@@ -932,7 +1024,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
   ✅ String format: `Token|Unit|{TOKEN_NAME}|{additionalKey}`
 
   ```typescript
-  sdk.fetchPriceHistory({ tokenId: 'Token|Unit|GALA|none' });
+  sdk.fetchPriceHistory({ tokenId: 'Token|Unit|BENE|none' });
   sdk.fetchPriceHistory({ tokenId: 'Token|Unit|SILK|none' });
   ```
 
@@ -958,7 +1050,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
 
   ```
   Invalid tokenId format for price history. Expected format: "Token|Unit|{TOKEN_NAME}|{additionalKey}"
-  (e.g., "Token|Unit|GALA|none"). Received: "GALA|Unit|none|none".
+  (e.g., "Token|Unit|BENE|none"). Received: "GALA|Unit|none|none".
   The token name must be in the third field (type), not the first field (collection).
   ```
 
@@ -982,7 +1074,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
 
   The DEX Backend API uses a different token format than GalaChain:
   - API format: `tokenName$Unit$none$none` (e.g., `GALA$Unit$none$none`)
-  - SDK format: `collection|category|type|additionalKey` (e.g., `Token|Unit|GALA|none`)
+  - SDK format: `collection|category|type|additionalKey` (e.g., `Token|Unit|BENE|none`)
 
   ### Changes
 
@@ -1000,7 +1092,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
   ### Before
 
   ```typescript
-  // Input: Token|Unit|GALA|none
+  // Input: Token|Unit|BENE|none
   // Converted to: Token$Unit$GALA$none (WRONG - API expected GALA$Unit$none$none)
   // Result: Empty response, no historical data
   ```
@@ -1008,7 +1100,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
   ### After
 
   ```typescript
-  // Input: Token|Unit|GALA|none
+  // Input: Token|Unit|BENE|none
   // Converted to: GALA$Unit$none$none (CORRECT)
   // Result: Returns all 30,862 GALA price snapshots
   ```
@@ -1026,7 +1118,7 @@ Co-Authored-By: Claude <noreply@anthropic.com>
 
   ### SDK Changes (@gala-chain/launchpad-sdk)
   - **New**: Added `tokenFormatConverter` utility (`src/utils/tokenFormatConverter.ts`)
-    - Convert between pipe-delimited (`Token|Unit|GUSDC|eth:...`) and dollar-delimited token formats
+    - Convert between pipe-delimited (`GUSDC|Unit|none|eth:...`) and dollar-delimited token formats
     - Convert sort order from SDK format (uppercase) to API format (lowercase)
   - **Updated**: `environments.ts` - Added separate `dexBackendBaseUrl` configuration for DEX
     Backend service