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

package/EXAMPLES.md

@@ -0,0 +1,923 @@
+# Gala Launchpad SDK - Usage Examples
+
+Practical code examples for common SDK operations organized by category. For complete API documentation, see [API Reference](./docs/API-REFERENCE.md).
+
+> **⚠️ BREAKING CHANGE (v3.33.0+)**: All DEX trading examples now require delimited token formats (`'GALA|Unit|none|none'` instead of `'GALA'`). See [README.md migration guide](./README.md#token-format-migration-v330) for details.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Recommended Learning Path](#recommended-learning-path)
+- [Core Operations](#core-operations)
+- [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)
+- [Error Handling](#error-handling)
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @gala-chain/launchpad-sdk
+```
+
+### Basic Setup
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Read-only mode (no wallet required)
+const sdk = createLaunchpadSDK({ environment: 'production' });
+
+// Full-access mode (with wallet for trading)
+const sdkWithWallet = createLaunchpadSDK({
+  environment: 'production',
+  privateKey: process.env.WALLET_PRIVATE_KEY
+});
+```
+
+### Run Your First Demo
+
+```bash
+# Complete SDK feature demonstration
+npm run demo
+
+# Interactive liquidity position manager
+npm run demo:liquidity
+
+# DEX swap workflow
+npm run demo:dex
+```
+
+---
+
+## Recommended Learning Path
+
+Follow this progression to master the SDK:
+
+### 1. Start with Core Operations
+
+```bash
+# Complete SDK overview (10 minutes)
+npm run demo
+
+# Read-only operations (no wallet needed)
+npm run demo:read-only
+
+# Authenticated operations (wallet required)
+npm run demo:authenticated
+```
+
+**Learn:** SDK initialization, configuration, read-only vs full-access modes
+
+### 2. Explore Liquidity Management
+
+```bash
+# Interactive CLI for liquidity positions
+npm run demo:liquidity
+
+# Run all 9 liquidity demos sequentially
+npm run demo:liquidity:all
+
+# Detailed position lifecycle
+npm run demo:liquidity:detailed
+```
+
+**Learn:** Add liquidity, collect fees, remove positions, APR calculations
+
+### 3. Master DEX Trading
+
+```bash
+# DEX swap workflow (quote → execute → confirm)
+npm run demo:dex
+
+# Pool discovery and metrics
+npm run demo:dex:pools
+
+# Quote comparison (exact input vs exact output)
+npm run demo:dex:quotes
+```
+
+**Learn:** Token swaps, quote generation, slippage protection, pool discovery
+
+### 4. Understand Fee Management
+
+```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
+npm run demo:fees:test
+```
+
+**Learn:** LP fee generation, collection strategies, multi-wallet workflows
+
+### 5. Try Real-Time Features
+
+```bash
+# Watch for new DEX pool creation
+npm run demo:watch
+
+# Watch for new launchpad token launches
+npm run demo:watch:tokens
+```
+
+**Learn:** WebSocket event monitoring, pool/token discovery
+
+### 6. Explore Advanced Topics
+
+```bash
+# Metadata cache performance
+npm run demo:cache
+
+# Token supply metrics from GalaChain
+npm run demo:token-supply
+
+# Advanced tick-based positions
+npm run demo:liquidity:ticks
+```
+
+**Learn:** Performance optimization, token supply queries, advanced LP strategies
+
+---
+
+## Core Operations
+
+### Initialize SDK
+
+**Read-Only Mode** (no wallet required):
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  environment: 'production'
+});
+
+// Query operations work without wallet
+const pools = await sdk.fetchDexPools({ search: 'GALA' });
+const prices = await sdk.fetchTokenSpotPrice('GALA');
+```
+
+**Full-Access Mode** (with wallet for trading):
+
+```typescript
+const sdk = createLaunchpadSDK({
+  environment: 'production',
+  privateKey: process.env.WALLET_PRIVATE_KEY
+});
+
+// Now you can execute trades
+const result = await sdk.executeSwap('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100', ...);
+```
+
+**Dynamic Wallet Configuration:**
+
+```typescript
+// Start in read-only mode
+const sdk = createLaunchpadSDK({ environment: 'production' });
+
+// Later, upgrade to full-access
+sdk.setWallet('your-private-key');
+
+// Now signing operations work
+const result = await sdk.buy({ tokenName: 'anime', amount: '100', ... });
+```
+
+**Demos:**
+- `npm run demo` - Complete SDK showcase
+- `npm run demo:read-only` - Wallet-free operations
+- `npm run demo:authenticated` - Wallet-required operations
+
+---
+
+## Liquidity Position Management
+
+Provide liquidity to GalaSwap DEX pools and earn trading fees.
+
+### View All Liquidity Positions
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  environment: 'production',
+  privateKey: process.env.WALLET_PRIVATE_KEY
+});
+
+// Get all positions with automatic pagination (recommended)
+const positions = await sdk.getAllSwapUserLiquidityPositions('eth|0x...');
+
+console.log(`Total positions: ${positions.length}`);
+
+// Analyze position performance
+let totalLiquidity = 0;
+let totalFees = 0;
+
+positions.forEach(pos => {
+  totalLiquidity += parseFloat(pos.liquidity || '0');
+
+  const fee0 = parseFloat(pos.feeAmount0 || '0');
+  const fee1 = parseFloat(pos.feeAmount1 || '0');
+  totalFees += fee0 + fee1;
+
+  console.log(`
+    Pool: ${pos.token0}/${pos.token1}
+    Liquidity: ${pos.liquidity}
+    Fees: ${pos.feeAmount0} ${pos.token0} + ${pos.feeAmount1} ${pos.token1}
+  `);
+});
+
+console.log(`\nTotal Liquidity: ${totalLiquidity}`);
+console.log(`Total Fees Earned: ${totalFees}`);
+```
+
+### Create Liquidity Position (Price Range)
+
+```typescript
+// Create position with user-friendly price range (v3.33.0+ requires delimited token format)
+const result = await sdk.addSwapLiquidityByPrice({
+  token0: 'GALA|Unit|none|none',
+  token1: 'GUSDC|Unit|none|none',
+  fee: 3000,              // 0.30% fee tier
+  minPrice: '0.95',       // Active range: 0.95 - 1.05
+  maxPrice: '1.05',
+  amount0Desired: '1000', // Provide 1000 GALA
+  amount1Desired: '1000', // Provide 1000 GUSDC
+  amount0Min: '900',      // Slippage protection (optional)
+  amount1Min: '900'
+});
+
+console.log(`Position created: ${result.positionId}`);
+console.log(`Liquidity provided: ${result.liquidity}`);
+console.log(`Amount0 used: ${result.amount0Used} GALA`);
+console.log(`Amount1 used: ${result.amount1Used} GUSDC`);
+
+// Wait for confirmation
+await result.wait();
+console.log('✓ Position confirmed on blockchain');
+```
+
+### Collect Fees Periodically
+
+```typescript
+// Harvest accumulated fees without closing position
+const result = await sdk.collectSwapPositionFees({
+  ownerAddress: 'eth|0x...',
+  positionId: 'position-id-uuid'
+});
+
+console.log(`Collected fees:`);
+console.log(`  ${result.amount0Collected} GALA`);
+console.log(`  ${result.amount1Collected} GUSDC`);
+
+// Position remains active and continues earning fees
+```
+
+### Remove Liquidity & Close Position
+
+```typescript
+// Step 1: Preview what you'll receive
+const estimate = await sdk.getSwapEstimateRemoveLiquidity(
+  'GALA',
+  'GUSDC',
+  3000,
+  position.liquidity,
+  position.tickLower,
+  position.tickUpper
+);
+
+console.log(`Will receive:`);
+console.log(`  ${estimate.amount0} ${estimate.token0Symbol}`);
+console.log(`  ${estimate.amount1} ${estimate.token1Symbol}`);
+
+// Step 2: Remove full liquidity
+const result = await sdk.removeSwapLiquidity({
+  ownerAddress: 'eth|0x...',
+  positionId: position.positionId,
+  liquidity: position.liquidity,  // Full amount to close
+  amount0Min: estimate.amount0,   // Use estimated amounts
+  amount1Min: estimate.amount1,
+  deadline: Math.floor(Date.now() / 1000) + 3600  // 1 hour deadline
+});
+
+console.log(`Position closed!`);
+console.log(`Withdrawn: ${result.amount0Withdrawn} GALA + ${result.amount1Withdrawn} GUSDC`);
+```
+
+**Liquidity Demos (9 total):**
+- `npm run demo:liquidity` - Interactive CLI
+- `npm run demo:liquidity:all` - Run all 9 demos (orchestrator)
+- `npm run demo:liquidity:detailed` - Complete lifecycle
+- `npm run demo:liquidity:ticks` - Advanced tick positions
+- `npm run demo:liquidity:portfolio` - Multi-position management
+- `npm run demo:liquidity:apr` - APR calculations
+- `npm run demo:liquidity:errors` - Error handling
+- `npm run demo:liquidity:fetch-all` - Pagination example
+- `npm run demo:liquidity:positions-with-prices` - Price enrichment
+
+**Orchestrator Usage:**
+
+```bash
+# Run all liquidity demos
+npm run demo:liquidity:all
+
+# Skip specific demos
+npm run demo:liquidity:all -- --skip=detailed,ticks
+
+# Run only specific demos
+npm run demo:liquidity:all -- --only=portfolio,apr
+```
+
+---
+
+## Bonding Curve Trading
+
+Trade tokens that are still in bonding curve pools (pre-graduation).
+
+### Buy Tokens on Bonding Curve
+
+```typescript
+const sdk = createLaunchpadSDK({
+  environment: 'production',
+  privateKey: process.env.WALLET_PRIVATE_KEY
+});
+
+// Calculate purchase amounts
+const quote = await sdk.calculateBuyAmount({
+  tokenName: 'anime',
+  amount: '100',
+  type: 'native'
+});
+
+console.log(`For 100 GALA:`);
+console.log(`  Receive: ${quote.amount} tokens`);
+console.log(`  Fee: ${quote.reverseBondingCurveFee} GALA`);
+console.log(`  Total cost: ${quote.totalCost} GALA`);
+
+// Execute purchase
+const result = await sdk.buy({
+  tokenName: 'anime',
+  amount: '100',
+  type: 'native',
+  expectedAmount: quote.amount,
+  slippageToleranceFactor: 0.01
+});
+
+console.log(`✓ Purchase completed: ${result.transactionId}`);
+```
+
+### Sell Tokens on Bonding Curve
+
+```typescript
+// Calculate sale amounts
+const quote = await sdk.calculateSellAmount({
+  tokenName: 'anime',
+  amount: '10000',
+  type: 'exact'
+});
+
+console.log(`Selling 10,000 tokens:`);
+console.log(`  Receive: ${quote.amount} GALA`);
+console.log(`  Fee: ${quote.reverseBondingCurveFee} GALA`);
+
+// Execute sale
+const result = await sdk.sell({
+  tokenName: 'anime',
+  amount: '10000',
+  type: 'exact',
+  expectedAmount: quote.amount,
+  slippageToleranceFactor: 0.01
+});
+
+console.log(`✓ Sale completed: ${result.transactionId}`);
+```
+
+**Bonding Curve Demos:**
+- `npm run demo:trades` - Basic buy/sell operations
+
+**Coming Soon (Bonding Curve Orchestrator):**
+8 additional bonding curve demos planned:
+- Pool discovery and filtering
+- Price calculation methods
+- Graduation simulation
+- Multi-token analysis
+- Fee structure exploration
+- Slippage testing scenarios
+- Liquidity depth analysis
+- Graduation timing optimization
+
+---
+
+## DEX Trading
+
+Trade graduated tokens on the GalaSwap DEX.
+
+### Get Swap Quote
+
+```typescript
+const sdk = createLaunchpadSDK({ environment: 'production' });
+
+// Quote for exact input (how many GUSDC for 100 GALA?)
+// v3.33.0+ requires delimited token format
+const quoteInput = await sdk.getSwapQuoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100');
+
+console.log(`Spend 100 GALA → Receive ~${quoteInput.estimatedOutput} GUSDC`);
+console.log(`Price impact: ${(quoteInput.priceImpact * 100).toFixed(2)}%`);
+console.log(`Suggested fee tier: ${quoteInput.feeTier} bps`);
+
+// Quote for exact output (how much GALA to get 100 GUSDC?)
+const quoteOutput = await sdk.getSwapQuoteExactOutput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100');
+
+console.log(`Need ${quoteOutput.inputAmount} GALA → Get 100 GUSDC`);
+console.log(`Price impact: ${(quoteOutput.priceImpact * 100).toFixed(2)}%`);
+```
+
+### Execute Swap
+
+```typescript
+const sdk = createLaunchpadSDK({
+  environment: 'production',
+  privateKey: process.env.WALLET_PRIVATE_KEY
+});
+
+// Step 1: Get quote (v3.33.0+ requires delimited token format)
+const quote = await sdk.getSwapQuoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100');
+
+// Step 2: Execute swap with 1% slippage protection
+const result = await sdk.executeSwap(
+  'GALA|Unit|none|none',
+  'GUSDC|Unit|none|none',
+  '100',
+  quote.estimatedOutput,
+  quote.feeTier,
+  0.01  // 1% slippage
+);
+
+console.log(`Swap initiated: ${result.transactionId}`);
+console.log(`Expected output: ~${quote.estimatedOutput} GUSDC`);
+
+// Step 3: Wait for confirmation
+await result.wait();
+
+console.log(`✓ Swap completed!`);
+console.log(`Received: ${result.outputAmount} GUSDC`);
+```
+
+### Discover DEX Pools
+
+```typescript
+// Find high-TVL pools
+const pools = await sdk.fetchDexPools({
+  search: 'GALA',
+  sortBy: 'tvl',
+  sortOrder: 'desc',
+  limit: 10
+});
+
+pools.pools.forEach(pool => {
+  console.log(`${pool.poolPair}: $${pool.tvl.toLocaleString()} TVL`);
+  console.log(`  24h Volume: $${pool.volume1d.toLocaleString()}`);
+  console.log(`  APR: ${pool.apr1d.toFixed(2)}%`);
+});
+```
+
+**DEX Demos (6 total):**
+- `npm run demo:dex` - Swap workflow (quote → execute → confirm)
+- `npm run demo:dex:pools` - Pool discovery and metrics
+- `npm run demo:dex:pricing` - Pool pricing and TVL analysis
+- `npm run demo:dex:quotes` - Quote comparison
+- `npm run demo:dex:roundtrip` - Complete liquidity workflow
+- `npm run demo:roundtrip:swap` - Buy → Sell → Verify
+
+**Symmetry Note:** Both `bonding-curve/` and `dex/` categories have pool discovery demos for consistent learning patterns.
+
+---
+
+## 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.
+
+### Basic Fee Generation
+
+```typescript
+const sdk = createLaunchpadSDK({
+  environment: 'production',
+  privateKey: process.env.WALLET_PRIVATE_KEY
+});
+
+// Step 1: Create liquidity position (v3.33.0+ requires delimited token format)
+const position = await sdk.addSwapLiquidityByPrice({
+  token0: 'GALA|Unit|none|none',
+  token1: 'GUSDC|Unit|none|none',
+  fee: 3000,
+  minPrice: '0.95',
+  maxPrice: '1.05',
+  amount0Desired: '1000',
+  amount1Desired: '1000'
+});
+
+await position.wait();
+console.log(`Position created: ${position.positionId}`);
+
+// Step 2: Execute swaps to generate fees
+for (let i = 0; i < 10; i++) {
+  const swap = await sdk.executeSwap('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '10', ...);
+  await swap.wait();
+  console.log(`Swap ${i + 1} completed`);
+}
+
+// Step 3: Check accumulated fees
+const positionData = await sdk.getSwapLiquidityPositionById(
+  'eth|0x...',
+  position.positionId
+);
+
+console.log(`Fees accumulated:`);
+console.log(`  ${positionData.feeAmount0} GALA`);
+console.log(`  ${positionData.feeAmount1} GUSDC`);
+
+// Step 4: Collect fees
+const collected = await sdk.collectSwapPositionFees({
+  ownerAddress: 'eth|0x...',
+  positionId: position.positionId
+});
+
+console.log(`✓ Collected: ${collected.amount0Collected} + ${collected.amount1Collected}`);
+```
+
+### High-Volume Fee Testing
+
+```typescript
+// Simulate high trading volume to test fee accumulation
+const highVolumeSwaps = 100;
+const swapAmount = '50'; // 50 GALA per swap
+
+console.log(`Generating ${highVolumeSwaps} swaps...`);
+
+for (let i = 0; i < highVolumeSwaps; i++) {
+  const quote = await sdk.getSwapQuoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', swapAmount);
+  const swap = await sdk.executeSwap('GALA|Unit|none|none', 'GUSDC|Unit|none|none', swapAmount, quote.estimatedOutput, quote.feeTier, 0.01);
+  await swap.wait();
+
+  if ((i + 1) % 10 === 0) {
+    console.log(`${i + 1}/${highVolumeSwaps} swaps completed`);
+  }
+}
+
+console.log(`✓ High-volume testing complete`);
+```
+
+**Fee Demos (5 total):**
+- `npm run demo:fees` - Basic fee generation and collection
+- `npm run demo:fees:high-volume` - High-volume trading simulation
+- `npm run demo:fees:test` - Complete fee lifecycle test suite
+- `npm run demo:fees:trade-collect` - Single workflow (trade + collect)
+
+**Advanced (not exposed as npm script):**
+- `tsx examples/fees/demo-multi-wallet-fee-generation.ts` - Multi-wallet fee workflows
+
+---
+
+## Real-Time Monitoring
+
+Monitor pool and token creation events using WebSocket event watchers.
+
+### Watch for DEX Pool Creation
+
+```typescript
+const sdk = createLaunchpadSDK({ environment: 'production' });
+
+// Monitor for 60 seconds
+const unsubscribe = sdk.onDexPoolCreation(
+  (pool) => {
+    console.log(`🆕 New pool: ${pool.poolPair}`);
+    console.log(`   TVL: $${pool.tvl.toFixed(2)}`);
+    console.log(`   24h Volume: $${pool.volume1d.toFixed(2)}`);
+    console.log(`   Fee tier: ${pool.fee}%`);
+  },
+  {
+    minTVL: 1000,                    // Only pools with $1k+ TVL
+    tokens: ['GALA', 'GUSDC'],       // Only these token pairs
+    intervalMs: 30000                // Poll every 30 seconds
+  }
+);
+
+// Stop watching after 60 seconds
+setTimeout(() => {
+  unsubscribe();
+  console.log('Stopped watching for new pools');
+}, 60000);
+```
+
+### Watch for Launchpad Token Creation
+
+```typescript
+// Monitor for new token launches
+const unsubscribe = sdk.onLaunchpadTokenCreation(
+  (token) => {
+    console.log(`🚀 New token: ${token.tokenName}`);
+    console.log(`   Symbol: ${token.symbol}`);
+    console.log(`   Creator: ${token.creatorAddress}`);
+    console.log(`   Created: ${new Date(token.createdAt).toISOString()}`);
+  },
+  {
+    creatorAddress: 'eth|0x...',  // Optional: watch specific creator
+    intervalMs: 30000              // Poll every 30 seconds
+  }
+);
+
+// Stop watching after 2 minutes
+setTimeout(() => {
+  unsubscribe();
+  console.log('Stopped watching for new tokens');
+}, 120000);
+```
+
+**Monitoring Demos (2 total):**
+- `npm run demo:watch` - Watch for new DEX pool creation
+- `npm run demo:watch:tokens` - Watch for new launchpad token launches
+
+---
+
+## Utilities
+
+### Portfolio & Balances
+
+```typescript
+const sdk = createLaunchpadSDK({ environment: 'production' });
+
+// GALA balance
+const galaBalance = await sdk.fetchGalaBalance('eth|0x...');
+console.log(`GALA: ${galaBalance.balance}`);
+
+// Token balance on DEX
+const assets = await sdk.getSwapUserAssets('eth|0x...');
+
+console.log('DEX Assets:');
+assets.forEach(asset => {
+  console.log(`  ${asset.symbol}: ${asset.balance}`);
+});
+
+// Tokens you hold
+const held = await sdk.fetchTokensHeld({
+  address: 'eth|0x...',
+  search: 'dragon'  // Optional: filter by search
+});
+
+console.log('Tokens held:');
+held.forEach(token => {
+  console.log(`  ${token.symbol}: ${token.balance}`);
+});
+```
+
+### Token Supply Metrics
+
+```typescript
+// Query GALA supply information
+const supplies = await sdk.fetchTokenClassesWithSupply([
+  {
+    collection: 'GALA',
+    category: 'Unit',
+    type: 'none',
+    additionalKey: 'none'
+  }
+]);
+
+const gala = supplies[0];
+console.log(`Token: ${gala.symbol} (${gala.name})`);
+console.log(`Total Supply: ${gala.totalSupply}`);
+console.log(`Max Supply: ${gala.maxSupply}`);
+console.log(`Total Burned: ${gala.totalBurned}`);
+console.log(`Decimals: ${gala.decimals}`);
+
+// Calculate health metrics
+const totalSupply = parseFloat(gala.totalSupply);
+const maxSupply = parseFloat(gala.maxSupply);
+const burned = parseFloat(gala.totalBurned);
+
+const circulationPercent = (totalSupply / maxSupply) * 100;
+const burnPercent = (burned / totalSupply) * 100;
+
+console.log(`\nCirculation: ${circulationPercent.toFixed(2)}% of max supply`);
+console.log(`Burned: ${burnPercent.toFixed(2)}% of total supply`);
+```
+
+### Metadata Cache Performance
+
+```typescript
+// Warm cache by fetching pools
+console.log('Warming cache...');
+await sdk.fetchPools({ type: 'popular', limit: 50 });
+
+// Check cache statistics
+const stats = sdk.getCacheInfo();
+console.log(`Cache warmed with ${stats.totalTokens} tokens`);
+console.log(`Memory: ${(stats.cacheSize / 1024).toFixed(2)} KB`);
+
+// Perform instant calculations using cached metadata
+const tokens = ['anime', 'dragnrkti', 'rocketri'];
+
+console.log('\nCalculating spot prices (instant, no network calls):');
+console.time('Batch Calculations');
+
+for (const token of tokens) {
+  const poolDetails = await sdk.fetchPoolDetailsForCalculation(token);
+
+  const buy100 = await sdk.calculateBuyAmountLocal({
+    tokenName: token,
+    amount: '100',
+    type: 'native',
+    currentSupply: poolDetails.currentSupply
+  });
+
+  console.log(`${token}: 100 GALA → ${buy100.amount} tokens`);
+}
+
+console.timeEnd('Batch Calculations');
+// Output: Batch Calculations: ~50ms (vs ~2000ms without cache)
+```
+
+**Utility Demos (5 total):**
+- `npm run demo:cache` - Metadata cache warming and performance
+- `npm run demo:token-supply` - Token supply metrics from GalaChain
+
+**Additional (not exposed as npm scripts):**
+- `tsx examples/utilities/balances.ts` - Multi-token balance queries
+- `tsx examples/utilities/balance.ts` - Single token balance check
+- `tsx examples/utilities/price-history.ts` - Historical price data (Node.js only)
+
+---
+
+## Error Handling
+
+Common error patterns and solutions.
+
+### Network Errors
+
+```typescript
+try {
+  const quote = await sdk.getSwapQuoteExactInput('GALA', 'INVALID', '100');
+} catch (error) {
+  if (error.message.includes('Pool not found')) {
+    console.log('Token pair not available on DEX');
+  } else if (error.message.includes('Invalid token')) {
+    console.log('Check token symbol format');
+  } else if (error.message.includes('timeout')) {
+    console.log('Network request timeout - try again');
+  } else {
+    console.log(`Error: ${error.message}`);
+  }
+}
+```
+
+### Wallet Requirements
+
+```typescript
+import { ValidationError } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({ environment: 'production' });
+// No wallet configured
+
+try {
+  await sdk.buy({ tokenName: 'anime', amount: '100', ... });
+} catch (error) {
+  if (error instanceof ValidationError && error.code === 'WALLET_REQUIRED') {
+    console.log('This operation requires a wallet');
+    console.log('Configure wallet: sdk.setWallet(privateKey)');
+  }
+}
+```
+
+### Slippage Protection
+
+```typescript
+try {
+  const quote = await sdk.getSwapQuoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '10000');
+  const result = await sdk.executeSwap(
+    'GALA',
+    'GUSDC',
+    '10000',
+    quote.estimatedOutput,
+    quote.feeTier,
+    0.01  // 1% slippage tolerance
+  );
+} catch (error) {
+  if (error.message.includes('slippage')) {
+    console.log('Price moved beyond slippage tolerance');
+    console.log('Increase slippage or retry with fresh quote');
+  }
+}
+```
+
+**Error Handling Demo:**
+- `npm run demo:liquidity:errors` - Comprehensive error scenarios
+
+---
+
+## More Examples
+
+See the `examples/` directory for complete working demos organized by category:
+
+```
+examples/
+├── core/           # 4 demos - SDK fundamentals
+├── liquidity/      # 9 demos - LP position management
+├── bonding-curve/  # 1 demo + 8 planned - Pre-graduation trading
+├── dex/            # 6 demos - DEX trading
+├── fees/           # 5 demos - Fee workflows
+├── monitoring/     # 2 demos - Real-time events
+├── utilities/      # 5 demos - Helper operations
+└── debug/          # 3 tools - Development utilities
+```
+
+**Total:** 36 demos covering all major SDK features
+
+For migration from old demo structure, see [docs/DEMO_MIGRATION_GUIDE.md](./docs/DEMO_MIGRATION_GUIDE.md).