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

package/README.md

@@ -2,9 +2,12 @@
 
 A comprehensive TypeScript SDK for the Gala Launchpad Backend API, providing type-safe authentication, trading, and real-time features for DeFi applications.
 
+> **⚠️ BREAKING CHANGE (v3.33.0+)**: Token format parsing now **ONLY accepts delimited formats** (`GALA|Unit|none|none` or `GALA$Unit$none$none`). Plain token strings (`'GALA'`, `'GUSDC'`) are **permanently rejected** for security. See [Migration Guide](#token-format-migration-v330) below.
+
 [![npm version](https://badge.fury.io/js/@gala-chain%2Flaunchpad-sdk.svg)](https://badge.fury.io/js/@gala-chain%2Flaunchpad-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+[![Documentation Coverage](https://img.shields.io/badge/Documentation%20Coverage-100%25-success)](./docs/API-REFERENCE.md)
 
 ## Features
 
@@ -63,7 +66,7 @@ console.log(pools.hasNext); // Computed convenience properties
 - **Token Trading**: Buy and sell tokens with slippage protection via GalaChain
 - **DEX Pool Discovery**: Discover and explore GalaSwap liquidity pools with filtering, sorting, and pagination
 - **DEX Trading**: Real-time token swaps on GalaSwap DEX with quote generation and slippage protection
-- **Liquidity Management**: Manage liquidity positions on GalaSwap (add, remove, collect fees)
+- **Liquidity Management**: Manage liquidity positions on GalaSwap (add, remove, collect fees) with filtering and organization utilities
 - **Token Transfers**: Transfer GALA and launchpad tokens between wallets with EIP-712 signatures
 - **User Operations**: Portfolio management, token balances, and account management
 - **Comment System**: Post and retrieve comments on token pools
@@ -292,6 +295,245 @@ const result = await sdk.buy({
 - ✅ Missing wallet throws `ValidationError` with code `WALLET_REQUIRED`
 - ⚠️ Only methods that sign transactions require a wallet
 
+## Environment Configuration
+
+The SDK supports multiple environments (STAGE and PROD). All demo scripts and examples use a **centralized environment configuration pattern** via `.env` file.
+
+### Quick Setup
+
+Create/edit `.env` in the repository root:
+
+```bash
+# .env
+ENVIRONMENT=STAGE          # Switch between STAGE and PROD
+WALLET_PRIVATE_KEY=0x...   # Your wallet private key (optional)
+```
+
+All demo scripts automatically read from this `.env` file:
+
+```bash
+npm run demo:read-only    # Uses ENVIRONMENT from .env
+npm run demo:dex          # Uses ENVIRONMENT from .env
+npm run demo:liquidity    # Uses ENVIRONMENT from .env
+```
+
+### Environment Values
+
+| Value | Accepts | Use Case |
+|-------|---------|----------|
+| `STAGE` | `STAGE`, `STAGING` | Development/staging |
+| `PROD` | `PROD`, `PRODUCTION` | Production |
+| Default | (if not set) | Defaults to `STAGE` with warning |
+
+### SDK Initialization
+
+When using demo scripts or examples, the environment is automatically loaded:
+
+```typescript
+import { getEnvironment } from './examples/utils/get-environment';
+
+const environment = getEnvironment();  // Reads from .env
+const sdk = new LaunchpadSDK({
+  env: environment,
+  wallet: undefined  // Optional
+});
+```
+
+### Validation
+
+Prevent hardcoded environment values:
+
+```bash
+npm run validate:env  # Validates no hardcoded 'STAGE' or 'PROD'
+```
+
+### Full Documentation
+
+See [docs/ENVIRONMENT_CONFIGURATION.md](./docs/ENVIRONMENT_CONFIGURATION.md) for:
+- Architecture and implementation details
+- Pattern for adding new scripts
+- Troubleshooting guide
+- Migration guide for existing scripts
+
+## Token Format Migration (v3.33.0)
+
+### Breaking Change: Strict Token Format Enforcement
+
+**v3.33.0 removes support for plain token strings** and requires all tokens to use **delimited format**.
+
+#### Old Behavior (v3.32.x and below) - DEPRECATED
+
+Plain token strings were accepted:
+```typescript
+// ❌ NO LONGER WORKS (v3.33.0+)
+await sdk.addSwapLiquidityByPrice({
+  token0: 'GALA',      // Plain string
+  token1: 'GUSDC',     // Plain string
+  fee: 3000,
+  minPrice: '0.95',
+  maxPrice: '1.05',
+  amount0Desired: '100',
+  amount1Desired: '100'
+});
+```
+
+#### New Behavior (v3.33.0+) - REQUIRED
+
+All tokens must use **pipe-delimited** (`|`) or **dollar-delimited** (`$`) format:
+
+```typescript
+// ✅ REQUIRED FORMAT (v3.33.0+)
+await sdk.addSwapLiquidityByPrice({
+  token0: 'GALA|Unit|none|none',      // Delimited format
+  token1: 'GUSDC|Unit|none|none',     // Delimited format
+  fee: 3000,
+  minPrice: '0.95',
+  maxPrice: '1.05',
+  amount0Desired: '100',
+  amount1Desired: '100'
+});
+```
+
+#### Format Options
+
+**Pipe-Delimited (Recommended):**
+```typescript
+'GALA|Unit|none|none'
+'GUSDC|Unit|none|none'
+'MYTOKEN|Unit|none|none'
+```
+
+**Dollar-Delimited (Alternative):**
+```typescript
+'GALA$Unit$none$none'
+'GUSDC$Unit$none$none'
+'MYTOKEN$Unit$none$none'
+```
+
+#### Migration Checklist
+
+- [ ] Search codebase for plain token strings: `'GALA'`, `'GUSDC'`, etc.
+- [ ] Replace with delimited format: `'GALA|Unit|none|none'`, `'GUSDC|Unit|none|none'`
+- [ ] Update all SDK method calls that pass token parameters
+- [ ] Test thoroughly - TypeScript strict mode will catch most issues
+- [ ] Update internal token handling code
+
+#### Affected Methods
+
+The following methods now require delimited token format:
+- `getSwapQuoteExactInput(token0, token1, amount)`
+- `getSwapQuoteExactOutput(token0, token1, amount)`
+- `executeSwap(token0, token1, ...)`
+- `addSwapLiquidityByPrice({token0, token1, ...})`
+- `addSwapLiquidityByTicks({token0, token1, ...})`
+- `removeSwapLiquidity({token0, token1, ...})`
+- `getSwapPoolInfo(token0, token1)`
+
+#### Security Rationale
+
+This breaking change enforces **strict token format validation** to:
+- ✅ **Prevent injection attacks** via token string manipulation
+- ✅ **Ensure deterministic parsing** with no ambiguous fallbacks
+- ✅ **Eliminate security gaps** from loose string handling
+- ✅ **Force explicit token specification** with full TokenClassKey structure
+
+Plain string support created a dangerous "escape hatch" where ambiguous token identifiers could be accepted. v3.33.0 eliminates this by requiring all tokens be properly delimited.
+
+## Upgrading to v4.0.0
+
+### Breaking Changes: Removed Deprecated Methods
+
+**v4.0.0 removes one deprecated method** that was superseded in v3.22.7. This is a clean removal with **minimal migration effort** - most users will not be affected.
+
+#### Removed Method: `fetchLaunchpadTokenSpotPrice()`
+
+This method was deprecated in v3.22.7 in favor of the more flexible `fetchTokenPrice()` method.
+
+**Old Code (v3.35.x and below) - NO LONGER WORKS:**
+```typescript
+// ❌ REMOVED in v4.0.0
+const price = await sdk.fetchLaunchpadTokenSpotPrice('anime');
+console.log(`Price: ${price} USD`);
+```
+
+**New Code (v4.0.0+) - REQUIRED:**
+```typescript
+// ✅ REQUIRED - Works for both launchpad and DEX tokens
+const price = await sdk.fetchTokenPrice('anime');
+console.log(`Price: ${price} USD`);
+```
+
+#### Why This Change?
+
+The new `fetchTokenPrice()` method:
+- ✅ **Unified pricing** - Works for both launchpad tokens and DEX-graduated tokens
+- ✅ **Automatic routing** - Detects token type and fetches from correct backend
+- ✅ **Better performance** - Single method instead of specialized variants
+- ✅ **Cleaner API** - Less method duplication in SDK
+
+#### Migration Checklist
+
+- [ ] Search codebase for `fetchLaunchpadTokenSpotPrice(`
+- [ ] Replace all occurrences with `fetchTokenPrice(`
+- [ ] Test with both launchpad tokens (e.g., `'anime'`) and DEX tokens
+- [ ] Verify price results haven't changed (same calculation logic)
+
+#### Impact Assessment
+
+**Affected Users:**
+- ⚠️ **Only if you explicitly called** `fetchLaunchpadTokenSpotPrice()`
+- ✅ **Not affected if you** used `fetchTokenPrice()` or `fetchTokenSpotPrice()` methods
+- ✅ **Not affected if you** never queried token prices
+
+**Migration Effort:**
+- ⏱️ **5 minutes** - Simple find/replace across codebase
+- ⚙️ **Zero logic changes** - Functionality remains identical
+- 🎯 **Low risk** - Price calculation algorithm unchanged
+
+### New Features: Service Clients Documentation
+
+v4.0.0 adds internal service client documentation for advanced users who need direct access to underlying blockchain services.
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key'
+});
+
+// Advanced: Direct access to DEX Backend API
+// Use case: Custom swap parameters or debugging
+const quote = await sdk.dexBackendClient.querySwapQuote({
+  orderedTokens: [...],
+  zeroForOne: false,
+  inputAmount: '10',
+  // ... additional parameters
+});
+
+// Advanced: Direct access to GalaChain Gateway
+// Use case: Custom transaction building
+const result = await sdk.galaChainGatewayClient.callContract({
+  address: 'contract-address',
+  method: 'transfer',
+  // ... parameters
+});
+```
+
+**⚠️ Important:** Service clients are internal implementation details. For standard operations, always use public SDK methods:
+- ✅ Use `sdk.buy()` instead of `sdk.galaChainGatewayClient`
+- ✅ Use `sdk.executeSwap()` instead of `sdk.dexBackendClient`
+- ✅ These public methods provide better error handling and validation
+
+For detailed service client documentation, see [docs/API-REFERENCE.md#service-clients](./docs/API-REFERENCE.md#service-clients).
+
+### Migration Summary
+
+**For Most Users:** Nothing to do! v4.0.0 is backward compatible except for the removal of `fetchLaunchpadTokenSpotPrice()`.
+
+**If You Used `fetchLaunchpadTokenSpotPrice()`:** Replace with `fetchTokenPrice()` - identical functionality, better flexibility.
+
+**If You Need Service Client Access:** They're now documented and available for advanced use cases, but use public SDK methods when possible.
+
 ## DEX Pool Discovery & Analysis
 
 ### Overview
@@ -932,6 +1174,62 @@ console.log(`Status: ${tokenTransfer.status}`);
 - **GalaChain Integration**: Direct transfers via GalaChain gateway
 - **Error Handling**: Detailed error types for different failure scenarios
 
+## Lock/Unlock Operations
+
+Lock and unlock tokens on GalaChain for staking, escrow, and vesting mechanisms:
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// Lock tokens - caller becomes lock authority by default
+const lockResult = await sdk.lockToken({
+  tokenName: 'tinyevil',
+  amount: '1000' // Token amount in smallest unit
+});
+
+console.log(`Locked tokens, tx: ${lockResult.transactionId}`);
+
+// Lock with custom authority and expiration
+const escrowLock = await sdk.lockToken({
+  tokenName: 'tinyevil',
+  amount: '5000',
+  lockAuthority: 'eth|0xEscrowContract...', // Third party can unlock
+  expires: Date.now() + 7 * 24 * 60 * 60 * 1000, // Auto-release in 1 week
+  name: 'escrow-deal-123' // Named lock for matching
+});
+
+// Unlock tokens - must be called by lock authority
+const unlockResult = await sdk.unlockToken({
+  tokenName: 'tinyevil',
+  amount: '1000'
+});
+
+console.log(`Unlocked tokens, tx: ${unlockResult.transactionId}`);
+
+// Unlock specific named lock
+await sdk.unlockToken({
+  tokenName: 'tinyevil',
+  amount: '5000',
+  name: 'escrow-deal-123' // Must match lock name
+});
+```
+
+### Lock Features
+- **Lock Authority**: Specify who can unlock (defaults to caller)
+- **Expiration**: Optional auto-release timestamp
+- **Named Locks**: Identify locks by name for targeted unlocks
+- **EIP-712 Signatures**: Secure blockchain transactions
+- **Idempotency**: Optional unique keys prevent duplicate operations
+
+### Use Cases
+- **Staking**: Lock tokens for reward programs
+- **Escrow**: Third-party holds tokens until conditions met
+- **Vesting**: Time-locked token releases with expiration
+
 ## Multi-Wallet Support
 
 The SDK supports **per-operation wallet overrides** for testing multi-wallet workflows without creating new SDK instances. This is ideal for:
@@ -1126,7 +1424,7 @@ fetchPoolDetails(tokenName): Promise<PoolDetailsData>
 
 fetchTokenDetails(tokenId): Promise<TokenDetails>
 // Returns: { symbol, decimals, name, image, verified, network, chainId, contractAddress, tradingEnabled, ... }
-// Supports flexible tokenId: string ('Token|Unit|GUSDC|eth:0x...') or object format
+// Supports flexible tokenId: string ('GUSDC|Unit|none|eth:0x...') or object format
 
 fetchVolumeData(options): Promise<GraphDataResult>
 // Returns: { dataPoints }
@@ -1847,7 +2145,7 @@ getSwapPoolInfo(tokenA, tokenB): Promise<PoolInfo>
 ```
 
 **Key Features:**
-- ✅ **Multi-format token support**: Use simple symbols ('GALA', 'GUSDC') or structured format ('GALA|Unit|none|none')
+- ✅ **Strict token format enforcement** (v3.33.0+): All tokens require delimited format (`'GALA|Unit|none|none'` or `'GALA$Unit$none$none'`)
 - ✅ **Quote pattern**: Always get quote before executing swap for accurate slippage calculations
 - ✅ **Unified WebSocket**: Real-time transaction monitoring via shared LaunchpadSDK WebSocket connection
 - ✅ **Environment alignment**: Automatic STAGE/PROD configuration matching
@@ -2071,6 +2369,54 @@ const testSDK = createTestLaunchpadSDK({
 });
 ```
 
+### **Position Filter Utilities**
+
+Helpers for organizing and filtering liquidity positions by various criteria:
+
+```typescript
+import {
+  filterByLiquidity,           // Remove positions with zero liquidity
+  filterByMinLiquidity,        // Keep positions >= threshold
+  filterByTokenPair,           // Match specific token pair
+  filterByToken,               // Find positions containing a token
+  filterByFeeTier,             // Filter by fee tier (500, 3000, 10000)
+  filterByPoolKey,             // Match specific pool (token pair + fee)
+  sortByLiquidity,             // Sort positions by liquidity amount
+  groupByTokenPair,            // Group by "TOKEN0/TOKEN1"
+  groupByFeeTier,              // Group by fee tier
+  groupByPoolKey,              // Group by "TOKEN0|TOKEN1|FEETIER"
+} from '@gala-chain/launchpad-sdk';
+
+// Example: Find active GALA/GUSDC positions and sort by size
+const allPositions = await sdk.getAllSwapUserLiquidityPositions(address);
+const active = filterByLiquidity(allPositions);                    // Remove zero-liquidity
+const galaPositions = filterByTokenPair(active, 'GALA', 'GUSDC');  // GALA/GUSDC only
+const sorted = sortByLiquidity(galaPositions, 'desc');             // Largest first
+
+// Group positions by token pair for portfolio analysis
+const grouped = groupByTokenPair(active);
+grouped.forEach((positions, pair) => {
+  console.log(`${pair}: ${positions.length} positions`);
+});
+
+// Find positions with significant liquidity
+const large = filterByMinLiquidity(active, '1000');
+
+// Organize by pool (pair + fee tier) for advanced analysis
+const byPool = groupByPoolKey(active);
+byPool.forEach((positions, poolKey) => {
+  console.log(`Pool ${poolKey}: ${positions.length} LPs`);
+});
+```
+
+**Use Cases:**
+- Organize positions by token pair or pool
+- Filter for active positions (non-zero liquidity)
+- Find positions above minimum liquidity threshold
+- Analyze portfolio distribution by token or fee tier
+- Identify opportunities for fee collection
+- Locate positions in specific pools
+
 ## Testing
 
 ```bash
@@ -2092,7 +2438,7 @@ npm run lint
 - [SDK Method Reference](./SDK-METHOD-GRAPH.md) - Complete flat API reference
 - [Clean Result Types Migration Guide](./docs/CLEAN_RESULT_TYPES_MIGRATION.md) - Migration guide for clean result types
 - [Service Architecture Migration Guide](./docs/SERVICE_ARCHITECTURE_MIGRATION.md) - Guide for v3.1.0 service-based architecture
-- [API Documentation](../../API.md) - Detailed API documentation
+- [API Reference](./docs/API-REFERENCE.md) - Complete reference for all 72 SDK methods with examples
 - [Examples](./examples/) - Code examples and demos
 
 ### GSwap Liquidity Operations
@@ -2103,24 +2449,202 @@ npm run lint
 
 ### Demo Scripts
 
-**Liquidity Operations:**
+The SDK includes 36 comprehensive demo scripts organized into logical categories for easy discovery and learning.
+
+#### Organized Directory Structure
+
+```
+examples/
+├── core/                    # SDK fundamentals and authentication patterns
+├── liquidity/               # GalaSwap liquidity position management (9 demos)
+├── bonding-curve/           # Token bonding curve trading operations
+├── dex/                     # DEX trading and pool discovery (6 demos)
+├── fees/                    # Fee generation and collection workflows (5 demos)
+├── monitoring/              # Real-time event watching (2 demos)
+├── utilities/               # Balance checks, cache, token supply (5 demos)
+└── debug/                   # Development and troubleshooting tools
+```
+
+#### Quick Start Examples
+
+**Core SDK Operations:**
+```bash
+# Complete SDK feature demonstration
+npm run demo
+
+# Read-only operations (no wallet required)
+npm run demo:read-only
+
+# Authenticated operations (wallet required)
+npm run demo:authenticated
+
+# Multi-wallet private key override pattern
+npm run demo:privatekey-override
+```
+
+#### Liquidity Position Management (9 Demos)
+
+Comprehensive liquidity provision workflows for GalaSwap DEX:
+
+```bash
+# Interactive CLI for position management
+npm run demo:liquidity
+
+# Run all 9 liquidity demos sequentially
+npm run demo:liquidity:all
+
+# Individual demos
+npm run demo:liquidity:detailed        # Detailed position lifecycle
+npm run demo:liquidity:ticks           # Advanced tick-based positions
+npm run demo:liquidity:portfolio       # Multi-position portfolio management
+npm run demo:liquidity:apr             # APR calculation for LP positions
+npm run demo:liquidity:errors          # Error handling patterns
+npm run demo:liquidity:fetch-all       # Fetch all positions with pagination
+npm run demo:liquidity:positions-with-prices  # Position pricing enrichment
+
+# Complete roundtrip workflow (legacy, use orchestrator instead)
+npm run demo:dex:roundtrip
+```
+
+**Orchestrator Pattern:**
+The liquidity orchestrator (`npm run demo:liquidity:all`) runs all demos with intelligent error handling:
+- Skip individual demos: `--skip=detailed,ticks`
+- Run specific demos only: `--only=portfolio,apr`
+- See all available demos: `npm run demo:liquidity:all --help`
+
+#### Bonding Curve Trading (Launchpad Tokens)
+
+Pre-graduation token trading on bonding curve pools:
+
+```bash
+# Basic buy/sell operations with slippage protection
+npm run demo:trades
+```
+
+**Bonding Curve Focus:**
+8 additional bonding curve demos are available through the orchestrator (in development):
+- Pool discovery and filtering
+- Price calculation methods
+- Graduation simulation
+- Multi-token analysis
+- Fee structure exploration
+- Slippage testing scenarios
+
+#### DEX Trading Operations (6 Demos)
+
+Graduated token trading on GalaSwap DEX with full liquidity pool support:
+
 ```bash
-# View all liquidity positions
-npm run demo:liquidity view
+# DEX swap workflow (quote → execute → confirm)
+npm run demo:dex
 
-# Add liquidity to GALA/GUSDC pool
-npm run demo:liquidity add
+# Pool discovery and metrics
+npm run demo:dex:pools
 
-# Collect fees from a position
-npm run demo:liquidity collect <position-id>
+# Pool pricing and TVL analysis
+npm run demo:dex:pricing
 
-# Remove liquidity (100% or partial percentage)
-npm run demo:liquidity remove <position-id> [percentage]
+# Quote comparison (exact input vs exact output)
+npm run demo:dex:quotes
 
-# Show detailed transaction responses (multiple swaps)
-npm run demo:liquidity:detailed
+# Complete swap roundtrip (buy → sell → verify)
+npm run demo:roundtrip:swap
 ```
 
+#### Fee Generation and Collection (5 Demos)
+
+Liquidity provider fee workflows with multi-wallet testing:
+
+```bash
+# Basic fee generation and collection
+npm run demo:fees
+
+# High-volume trading fee accumulation
+npm run demo:fees:high-volume
+
+# Complete fee lifecycle test suite
+npm run demo:fees:test
+
+# Trade and collect fees in single workflow
+npm run demo:fees:trade-collect
+```
+
+**Note:** `demo-multi-wallet-fee-generation.ts` is available but not exposed in npm scripts (advanced usage).
+
+#### Real-Time Monitoring (2 Demos)
+
+WebSocket-based event watchers for pool and token creation:
+
+```bash
+# Watch for new DEX pool creation
+npm run demo:watch
+
+# Watch for new launchpad token launches
+npm run demo:watch:tokens
+```
+
+#### Utility Operations (5 Demos)
+
+Balance queries, caching, and token supply information:
+
+```bash
+# Metadata cache warming and performance testing
+npm run demo:cache
+
+# Token supply metrics from GalaChain
+npm run demo:token-supply
+```
+
+**Additional utilities:**
+- `balances.ts` - Multi-token balance queries
+- `balance.ts` - Single token balance check
+- `price-history.ts` - Historical price data (Node.js only)
+
+#### Debug and Development Tools
+
+Advanced troubleshooting and environment testing:
+
+```bash
+# Environment alignment verification
+tsx examples/debug/test-env-alignment.ts
+
+# Slot0 data debugging
+tsx examples/debug/debug-getslot0-test.ts
+
+# DEX simulation with monkey patching
+tsx examples/debug/demo-dex-monkey-patch-simulation.ts
+```
+
+#### Demo Statistics
+
+- **Total Demos:** 36 working examples
+- **npm Scripts:** 25 convenient shortcuts
+- **Categories:** 8 organized directories
+- **Coverage:** All major SDK features demonstrated
+
+#### Recommended Learning Path
+
+1. **Start Here:** `npm run demo` - Complete SDK overview
+2. **Liquidity Basics:** `npm run demo:liquidity` - Interactive CLI
+3. **DEX Trading:** `npm run demo:dex` - Swap workflow
+4. **Fee Management:** `npm run demo:fees` - LP fee collection
+5. **Advanced:** Explore individual demos by category
+
+#### Migration Notes
+
+**Removed Scripts (v3.32.0+):**
+- `demo:liquidity:simple` - Merged into `demo:liquidity`
+- `demo:liquidity:workflow` - Replaced by orchestrator pattern
+- `demo:dex:swap` - Renamed to `demo:dex` for consistency
+
+**New in v3.32.0+:**
+- Organized directory structure with 8 categories
+- Bonding curve orchestrator (in development)
+- Fee demo npm scripts now exposed
+- Symmetry: Both bonding-curve and dex have pool discovery demos
+
+For detailed migration guide, see [docs/DEMO_MIGRATION_GUIDE.md](./docs/DEMO_MIGRATION_GUIDE.md).
+
 ## Architecture
 
 The SDK uses a **service-based architecture** with backend-aligned services: