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

package/API.md

@@ -1003,9 +1003,9 @@ Promise<Array<{
 // Query single token
 const supplies = await sdk.fetchTokenClassesWithSupply([
   {
-    collection: 'Token',
+    collection: 'GALA',
     category: 'Unit',
-    type: 'GALA',
+    type: 'none',
     additionalKey: 'none'
   }
 ]);
@@ -1016,8 +1016,8 @@ console.log(`GALA Burned: ${supplies[0].totalBurned}`);
 
 // Query multiple tokens in one call
 const multiSupplies = await sdk.fetchTokenClassesWithSupply([
-  { collection: 'Token', category: 'Unit', type: 'GALA', additionalKey: 'none' },
-  { collection: 'Token', category: 'Unit', type: 'GUSDC', additionalKey: 'eth:0x...' }
+  { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' },
+  { collection: 'GUSDC', category: 'Unit', type: 'none', additionalKey: 'none' }
 ]);
 
 // Analyze supply metrics
@@ -1288,7 +1288,7 @@ tokenId: string | {
 
 **Example:**
 ```typescript
-const details = await sdk.fetchTokenDetails('Token|Unit|GUSDC|eth:0x...');
+const details = await sdk.fetchTokenDetails('GUSDC|Unit|none|eth:0x...');
 
 if (details.verified && details.tradingEnabled) {
   console.log(`${details.symbol}: ${details.name}`);

package/CHANGELOG.md

@@ -4,24 +4,24 @@
 
 ### BREAKING CHANGES
 
-- **`fetchLaunchpadTokenSpotPrice()` method REMOVED**
+- **`fetchLaunchpadTokenSpotPrice()` method DEPRECATED**
   - **Deprecated**: v3.22.7
-  - **Removed**: v4.0.0
+  - **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**: Direct replacement required in all code using this method
+  - **Impact**: Update your code to use `fetchTokenPrice()` before v5.0.0
 
   **Migration Path:**
   ```typescript
-  // ❌ REMOVED in v4.0.0 - NO LONGER WORKS
+  // ⚠️ DEPRECATED in v4.0.0 - Still works but will be removed in v5.0.0
   const price = await sdk.fetchLaunchpadTokenSpotPrice('anime');
 
-  // ✅ USE INSTEAD (v4.0.0+)
+  // ✅ 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|GALA|none'
+    tokenId: 'Token|Unit|BENE|none'
   });
   ```
 
@@ -599,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
 
@@ -914,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
@@ -970,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
   ```
 
@@ -1024,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' });
   ```
 
@@ -1050,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).
   ```
 
@@ -1074,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
 
@@ -1092,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
   ```
@@ -1100,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
   ```
@@ -1118,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

package/EXAMPLES.md

@@ -12,6 +12,7 @@ Practical code examples for common SDK operations organized by category. For com
 - [Liquidity Position Management](#liquidity-position-management)
 - [Bonding Curve Trading](#bonding-curve-trading)
 - [DEX Trading](#dex-trading)
+- [DEX Leaderboard & Volume Analytics](#dex-leaderboard--volume-analytics)
 - [Fee Generation & Collection](#fee-generation--collection)
 - [Real-Time Monitoring](#real-time-monitoring)
 - [Utilities](#utilities)
@@ -503,6 +504,83 @@ pools.pools.forEach(pool => {
 
 ---
 
+## DEX Leaderboard & Volume Analytics
+
+Competitive DEX leaderboard system with achievement tracking and platform-wide volume metrics.
+
+### Fetch All Seasons
+
+```typescript
+const sdk = createLaunchpadSDK({ environment: 'production' });
+
+// Get all available competitive seasons
+const seasons = await sdk.fetchAllDexSeasons();
+
+console.log(`Total seasons: ${seasons.length}`);
+seasons.forEach(season => {
+  const days = Math.ceil((new Date(season.end).getTime() - new Date(season.start).getTime()) / (1000 * 60 * 60 * 24));
+  console.log(`${season.name} (ID: ${season.id}): ${days} days`);
+});
+```
+
+### Get Current Season & Leaderboard
+
+```typescript
+// Get current active season
+const currentSeason = await sdk.fetchCurrentDexSeason();
+console.log(`Active: ${currentSeason.name}`);
+
+// Get current season leaderboard (top 10)
+const leaderboard = await sdk.fetchCurrentDexLeaderboard({ limit: 10 });
+
+console.log(`🏆 Top Traders (${currentSeason.name}):`);
+leaderboard.rankings.forEach(entry => {
+  const titles = entry.masteryTitles.map(t => t.name).join(', ');
+  console.log(`${entry.rank}. ${entry.wallet.slice(0, 12)}...`);
+  console.log(`   XP: ${entry.totalXp} | Distribution: ${entry.distributionPercent}%`);
+  console.log(`   Trading: ${entry.tradingXp} | Liquidity: ${entry.liquidityXp}`);
+  if (titles) console.log(`   Achievements: ${titles}`);
+});
+```
+
+### Query Historic Season Leaderboard
+
+```typescript
+// Get leaderboard from a specific season (e.g., Season 1, ID=4)
+const historicLeaderboard = await sdk.fetchDexLeaderboardBySeasonId(4, { limit: 5 });
+
+console.log(`Season 1 Final Rankings:`);
+historicLeaderboard.rankings.forEach(entry => {
+  console.log(`${entry.rank}. ${entry.wallet}: ${entry.totalXp} XP`);
+});
+```
+
+### Platform Volume Metrics
+
+```typescript
+// Get platform-wide DEX volume summary
+const volume = await sdk.fetchDexAggregatedVolumeSummary();
+
+console.log(`📊 DEX Platform Volume:`);
+console.log(`  24h:  $${volume.volume1d.toFixed(2)} (${(volume.volume1dDelta * 100).toFixed(1)}%)`);
+console.log(`  7d:   $${volume.volume7d.toFixed(2)} (${(volume.volume7dDelta * 100).toFixed(1)}%)`);
+console.log(`  30d:  $${volume.volume30d.toFixed(2)} (${(volume.volume30dDelta * 100).toFixed(1)}%)`);
+
+// Trend analysis
+if (volume.volume1dDelta > volume.volume7dDelta) {
+  console.log(`📈 Accelerating: 24h growth stronger than 7d avg`);
+} else if (volume.volume1dDelta < -0.1) {
+  console.log(`📉 Warning: Significant 24h decline (${(volume.volume1dDelta * 100).toFixed(1)}%)`);
+}
+```
+
+**DEX Leaderboard & Volume Demos (3 total):**
+- `npm run demo:dex:leaderboard` - Seasonal leaderboard queries and XP rankings
+- `npm run demo:dex:volume-summary` - Platform volume metrics and trend analysis
+- `npm run demo:dex:all` - Orchestrator managing all DEX demos (pools, pricing, swap, leaderboard, volume)
+
+---
+
 ## Fee Generation & Collection
 
 Liquidity provider fee workflows with multi-wallet testing.
@@ -686,9 +764,9 @@ held.forEach(token => {
 // Query GALA supply information
 const supplies = await sdk.fetchTokenClassesWithSupply([
   {
-    collection: 'Token',
+    collection: 'GALA',
     category: 'Unit',
-    type: 'GALA',
+    type: 'none',
     additionalKey: 'none'
   }
 ]);

package/README.md

@@ -7,6 +7,7 @@ A comprehensive TypeScript SDK for the Gala Launchpad Backend API, providing typ
 [![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
 
@@ -294,6 +295,66 @@ 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
@@ -1113,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:
@@ -1307,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 }