@gala-chain/launchpad-sdk 8.1.0 → 9.0.0-rc.0

package/EXAMPLES.md

@@ -1,20 +1,20 @@
 # 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).
+Practical code examples for the launchpad SDK (9.0.0), 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.
+> **9.0 is launchpad-only.** The DEX (quotes, swaps, pools, liquidity, fees, market prices, leaderboards) is
+> `@gala-chain/gswap-sdk`; its runnable demos are in
+> [`packages/gswap-sdk/examples/demos`](../gswap-sdk/examples/demos/README.md). Gateway-generic pieces
+> (signers, wallet providers, React hooks, the bridge) are `@gala-chain/gala-core-sdk`'s. See
+> [MIGRATING-TO-9.0.md](./MIGRATING-TO-9.0.md) for where each removed export went.
 
 ## Table of Contents
 
-- [Token Format Decision Tree](#token-format-decision-tree) ⭐ **READ THIS FIRST**
+- [Token Format Decision Tree](#token-format-decision-tree)
 - [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)
 - [Streaming & Chat](#streaming--chat)
 - [Utilities](#utilities)
@@ -24,95 +24,74 @@ Practical code examples for common SDK operations organized by category. For com
 
 ## Token Format Decision Tree
 
-**The SDK uses TWO different token identifier formats. Using the wrong one causes errors.**
-
-### Which Format Should I Use?
+**Launchpad tokens are addressed by `tokenName`; standard GalaChain tokens by a token id (`collection|category|type|additionalKey`).**
 
 ```
 Q: What operation am I performing?
 │
-├── Buying/selling tokens on bonding curve (pre-graduation)?
+├── Buying/selling tokens on the bonding curve (pre-graduation)?
 │   └── Use tokenName: sdk.buy({ tokenName: 'anime', amount: '100', type: 'native' })
 │
-├── Swapping on DEX (GALA, GUSDC, graduated tokens)?
-│   └── Use tokenClassKey: sdk.dex.swaps.swap('GALA|Unit|none|none', 'GUSDC|Unit|none|eth:0xa0b...', fee, { exactIn: '100', amountOutMinimum: '...' }) — queued, then await result.confirm()
-│
-├── Managing liquidity positions on DEX?
-│   └── Use tokenClassKey: sdk.dex.positions.addLiquidityByPrice({ token0: 'GALA|Unit|none|none', ... })
-│
 ├── Transferring tokens?
 │   ├── Launchpad token? → sdk.transferToken({ tokenName: 'anime', ... })
 │   └── Standard GalaChain token? → sdk.transferToken({ tokenId: 'GALA|Unit|none|none', ... })
 │
-├── Checking prices?
-│   └── Either works: sdk.fetchTokenPrice({ tokenName: 'anime' })
-│                  OR sdk.fetchTokenPrice({ tokenId: 'GALA|Unit|none|none' })
+├── Checking a launchpad token's price?
+│   └── sdk.fetchTokenPrice({ tokenName: 'anime' })   (bonding curve, or the swap backend once graduated)
+│
+├── Need a launchpad token's class key?
+│   └── await sdk.resolveTokenClassKey('anime')  (never construct it by hand)
+│
+├── Trading a graduated token / any other token on the DEX, or a price by token id?
+│   └── @gala-chain/gswap-sdk: gSwap.swaps.swap(...), gSwap.market.getPrice(tokenId)
 │
 └── Graduating a token from bonding curve to DEX?
-    └── Use tokenName: sdk.graduateToken({ tokenName: 'anime' })
+    └── Use tokenName: sdk.graduateToken('anime')
 ```
 
 ### Format Reference
 
 | Format | Pattern | Example | Used For |
 |--------|---------|---------|----------|
-| **tokenName** | Simple lowercase, 3-20 chars | `'anime'` | Bonding curve ops |
-| **tokenClassKey** | `collection\|category\|type\|additionalKey` | `'GALA\|Unit\|none\|none'` | DEX ops, LP, standard tokens |
-
-### Common Well-Known Tokens
-
-```typescript
-// Standard tokens (always use tokenClassKey format)
-const GALA = 'GALA|Unit|none|none';
-const GUSDC = 'GUSDC|Unit|none|eth:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
-const WETH = 'GETH|Unit|none|eth:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2';
-```
+| **tokenName** | Simple lowercase, 3-20 chars | `'anime'` | Bonding curve ops, price |
+| **token id / class key** | `collection\|category\|type\|additionalKey` | `'GALA\|Unit\|none\|none'` | Transfers, balances, locks, standard tokens |
 
 ### Common Mistakes Table
 
 | ❌ Wrong | ✅ Correct | Why |
 |----------|------------|-----|
-| `sdk.dex.swaps.swap('anime', ...)` (a launchpad tokenName) | `sdk.dex.swaps.swap('GALA\|Unit\|none\|none', ...)` or a registered symbol like `'GALA'` | DEX resolves registered symbols or full tokenClassKeys via `sdk.dex.symbols.list()` — it does not accept a bonding-curve `tokenName` |
 | `sdk.buy({ tokenName: 'ANIME\|Unit\|...' })` | `sdk.buy({ tokenName: 'anime' })` | Bonding curve uses simple names |
-| `sdk.dex.quoting.quoteExactInput('anime', ...)` | Get tokenClassKey from pool, then use it | DEX needs resolved tokenClassKey |
-| Assuming `buy()` works for graduated tokens | Check `isGraduated`, use DEX if true | Graduated tokens are on DEX |
+| `sdk.fetchTokenPrice({ tokenId: 'GALA\|Unit\|none\|none' })` | `gSwap.market.getPrice('GALA\|Unit\|none\|none')` (gswap-sdk) | 9.0 prices launchpad tokens only; a `tokenId` is refused with a `ValidationError` |
+| Assuming `buy()` works for graduated tokens | Check `isGraduated`, trade on the DEX with gswap-sdk if true | Graduated tokens trade on the DEX |
 
 ### Detecting Graduation Status
 
 ```typescript
-// Check if a token has graduated from bonding curve to DEX
 const pool = await sdk.fetchPools({ tokenName: 'anime' });
 const isGraduated = pool.items[0]?.isGraduated ?? false;
 
 if (isGraduated) {
-  // Token is on DEX - get its tokenClassKey for DEX operations
-  // ⚠️ IMPORTANT: Always query for tokenClassKey - never construct it!
-  // The symbol in tokenClassKey may differ from tokenName
-  const tokenClassKey = pool.items[0]?.tokenClassKey;
-  console.log(`Use tokenClassKey for DEX: ${tokenClassKey}`);
+  // Token is on the DEX: trade it with @gala-chain/gswap-sdk using its class key.
+  // Always resolve the key, never construct it: the symbol may differ from the tokenName.
+  const tokenClassKey = await sdk.resolveTokenClassKey('anime');
+  console.log('Trade on the DEX with', tokenClassKey);
 } else {
-  // Token is still on bonding curve - use tokenName
-  console.log('Use tokenName for bonding curve: anime');
+  console.log('Still on the bonding curve: use sdk.buy / sdk.sell with tokenName "anime"');
 }
 ```
 
-### Full Method Reference
+### Method Reference
 
-| Method | tokenName | tokenClassKey | Notes |
-|--------|:---------:|:-------------:|-------|
+| Method | tokenName | token id | Notes |
+|--------|:---------:|:--------:|-------|
 | `buy()` | ✅ | ❌ | Bonding curve only |
 | `sell()` | ✅ | ❌ | Bonding curve only |
 | `graduateToken()` | ✅ | ❌ | Triggers DEX migration |
 | `calculateBuyAmount()` | ✅ | ❌ | Pre-trade calculation |
 | `calculateSellAmount()` | ✅ | ❌ | Pre-trade calculation |
 | `fetchPools()` | ✅ | ❌ | Query bonding curve pools |
-| `dex.swaps.swap()` | ❌ | ✅ | DEX only — queued RequestTrade, call `.confirm()` |
-| `dex.quoting.quoteExactInput()` | ❌ | ✅ | DEX quotes |
-| `dex.quoting.quoteExactOutput()` | ❌ | ✅ | DEX quotes |
-| `dex.positions.addLiquidityByPrice()` | ❌ | ✅ | LP operations |
-| `dex.positions.removeLiquidity()` | ❌ | ✅ | LP operations |
-| `fetchTokenPrice()` | ✅ | ✅ | Smart router auto-detects |
-| `transferToken()` | ✅ | ✅ | Both work (different paths) |
+| `fetchTokenPrice()` | ✅ | ❌ | Launchpad token price (`{ tokenName }` only) |
+| `transferToken()` | ✅ | ✅ | Both work |
 | `lockTokens()` | ✅ | ✅ | Both work |
 | `fetchTokenBalance()` | ✅ | ✅ | Both work |
 
@@ -125,9 +104,12 @@ if (isGraduated) {
 ### Installation
 
 ```bash
-npm install @gala-chain/launchpad-sdk
+npm install @gala-chain/launchpad-sdk@next @gala-chain/gala-core-sdk@next zod
 ```
 
+`@gala-chain/gala-core-sdk` and `zod` are peer dependencies. 9.0 is a release candidate under the
+`next` dist-tag (an install without `@next` gets 8.1.0).
+
 ### Basic Setup
 
 ```typescript
@@ -149,35 +131,23 @@ const sdkWithWallet = createLaunchpadSDK({
 # Complete SDK feature demonstration
 npm run demo
 
-# Interactive liquidity position manager
-npm run demo:liquidity
-
-# DEX swap workflow
-npm run demo:dex
+# Basic bonding curve buy/sell
+npm run demo:trades
 
-# Bonding curve trading orchestrator
-npm run demo:bonding:orchestrator
+# Watch for new launchpad token launches
+npm run demo:watch:tokens
 ```
 
-**Demo Statistics**: 65 comprehensive demos organized into 8 categories covering all SDK features
-
 ---
 
 ## 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
+npm run demo                 # Complete SDK overview
+npm run demo:read-only       # Read-only operations (no wallet needed)
+npm run demo:authenticated   # Authenticated operations (wallet required)
 ```
 
 **Learn:** SDK initialization, configuration, read-only vs full-access modes
@@ -185,89 +155,36 @@ npm run demo:authenticated
 ### 2. Understand Bonding Curve Trading
 
 ```bash
-# Run all bonding curve demos sequentially
-npm run demo:bonding:orchestrator
-
-# Basic buy/sell operations
-npm run demo:trades
-
-# Token graduation workflow
-npm run demo:bonding:graduation
+npm run demo:trades                  # Basic buy/sell operations
+npm run demo:bonding:graduation      # Token graduation workflow
+npm run demo:bonding:pool-discovery  # Pool filtering and discovery
 ```
 
 **Learn:** Pre-graduation token trading, bonding curve mechanics, token launch lifecycle
 
-### 3. Explore Liquidity Management
+### 3. Try Real-Time Features
 
 ```bash
-# Interactive CLI for liquidity positions
-npm run demo:liquidity
-
-# Run all 12 liquidity demos sequentially
-npm run demo:liquidity:all
-
-# Detailed position lifecycle
-npm run demo:liquidity:detailed
+npm run demo:watch:tokens   # Watch for new launchpad token launches
+npm run demo:monitoring:websocket-events
 ```
 
-**Learn:** Add liquidity, collect fees, remove positions, APR calculations
+**Learn:** WebSocket event monitoring, token discovery
 
-### 4. Master DEX Trading
+### 4. Explore Advanced Topics
 
 ```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
+npm run demo:cache          # Metadata cache performance
+npm run demo:token-supply   # Token supply metrics from GalaChain
 ```
 
-**Learn:** Token swaps, quote generation, slippage protection, pool discovery
+**Learn:** Performance optimization, token supply queries
 
-### 5. Understand Fee Management
+### 5. The DEX
 
-```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
-
-### 6. 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
-
-### 7. 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
+Swaps, liquidity, fees, pools and market data are `@gala-chain/gswap-sdk`'s. Its demos:
+[`packages/gswap-sdk/examples/demos/README.md`](../gswap-sdk/examples/demos/README.md)
+(`npx tsx src/<dir>/<file>.ts`).
 
 ---
 
@@ -285,8 +202,8 @@ const sdk = createLaunchpadSDK({
 });
 
 // Query operations work without wallet
-const pools = await sdk.dex.pools.getPools();
-const prices = await sdk.fetchTokenPrice({ tokenName: 'GALA' });
+const pools = await sdk.fetchPools({ type: 'popular', limit: 10 });
+const price = await sdk.fetchTokenPrice({ tokenName: 'anime' });
 ```
 
 **Full-Access Mode** (with wallet for trading):
@@ -297,8 +214,8 @@ const sdk = createLaunchpadSDK({
   privateKey: process.env.WALLET_PRIVATE_KEY
 });
 
-// Now you can submit trades (queued RequestTrade; await result.confirm() for the applied trade)
-const result = await sdk.dex.swaps.swap('GALA|Unit|none|none', 'GUSDC|Unit|none|none', 3000, { exactIn: '100' });
+// Now you can submit trades
+const result = await sdk.buy({ tokenName: 'anime', amount: '100', type: 'native', expectedAmount: '1' });
 ```
 
 **Dynamic Wallet Configuration:**
@@ -321,150 +238,6 @@ const result = await sdk.buy({ tokenName: 'anime', amount: '100', ... });
 
 ---
 
-## 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({
-  env: 'prod',
-  privateKey: process.env.WALLET_PRIVATE_KEY
-});
-
-// Get all current-contract positions for the owner
-const positions = await sdk.dex.positions.getUserPositions('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.fees0 || '0');
-  const fee1 = parseFloat(pos.fees1 || '0');
-  totalFees += fee0 + fee1;
-
-  console.log(`
-    Pool: ${pos.token0Symbol}/${pos.token1Symbol}
-    Liquidity: ${pos.liquidity}
-    Fees: ${pos.fees0} ${pos.token0Symbol} + ${pos.fees1} ${pos.token1Symbol}
-  `);
-});
-
-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 submitted = await sdk.dex.positions.addLiquidityByPrice({
-  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',
-  amount: '1000',         // Amount of the token below
-  amountIsToken0: true,   // Provide 1000 GALA (token0)
-});
-
-console.log(`Submitted: ${submitted.transactionId} (mode: ${submitted.mode})`);
-
-// Wait for confirmation — resolves the created/refreshed position
-const position = await submitted.confirm();
-console.log(`✓ Position confirmed. Liquidity: ${position?.liquidity}`);
-```
-
-### Collect Fees Periodically
-
-```typescript
-// Harvest accumulated fees without closing position (the contract does not support partial collection)
-const submitted = await sdk.dex.positions.collectPositionFees({
-  token0: 'GALA|Unit|none|none',
-  token1: 'GUSDC|Unit|none|none',
-  fee: 3000,
-  tickLower: position.tickLower,
-  tickUpper: position.tickUpper,
-});
-
-const collected = await submitted.confirm();
-
-console.log(`Collected fees:`);
-console.log(`  ${collected?.fees0} GALA`);
-console.log(`  ${collected?.fees1} GUSDC`);
-
-// Position remains active and continues earning fees
-```
-
-### Remove Liquidity & Close Position
-
-```typescript
-// Step 1: Preview what you'll receive
-const estimate = await sdk.dex.positions.estimateRemoveLiquidity({
-  token0: 'GALA|Unit|none|none',
-  token1: 'GUSDC|Unit|none|none',
-  fee: 3000,
-  tickLower: position.tickLower,
-  tickUpper: position.tickUpper,
-  liquidity: position.liquidity,
-});
-
-console.log(`Will receive:`);
-console.log(`  ${estimate.amount0} GALA`);
-console.log(`  ${estimate.amount1} GUSDC`);
-
-// Step 2: Remove full liquidity (omitting both amount0/amount1 closes the position)
-const submitted = await sdk.dex.positions.removeLiquidity({
-  token0: 'GALA|Unit|none|none',
-  token1: 'GUSDC|Unit|none|none',
-  fee: 3000,
-  tickLower: position.tickLower,
-  tickUpper: position.tickUpper,
-});
-
-const closed = await submitted.confirm();
-
-console.log(`Position closed!`);
-console.log(`Withdrawn: ${estimate.amount0} GALA + ${estimate.amount1} GUSDC`);
-```
-
-**Liquidity Demos (12 total):**
-- `npm run demo:liquidity` - Interactive CLI
-- `npm run demo:liquidity:all` - Run all 12 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
-- `npm run demo:liquidity:removal` - Position removal workflow
-- `npm run demo:liquidity:fee-collection` - Fee collection strategies
-- `npm run demo:liquidity:price-range` - Price range optimization
-
-**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).
@@ -486,8 +259,7 @@ const quote = await sdk.calculateBuyAmount({
 
 console.log(`For 100 GALA:`);
 console.log(`  Receive: ${quote.amount} tokens`);
-console.log(`  Fee: ${quote.reverseBondingCurveFee} GALA`);
-console.log(`  Total cost: ${quote.totalCost} GALA`);
+console.log(`  Fees: ${quote.transactionFee} GALA transaction, ${quote.gasFee} GALA gas`);
 
 // Execute purchase
 const result = await sdk.buy({
@@ -527,8 +299,7 @@ const result = await sdk.sell({
 console.log(`✓ Sale completed: ${result.transactionId}`);
 ```
 
-**Bonding Curve Demos (8 total):**
-- `npm run demo:bonding:orchestrator` - Run all 8 bonding curve demos (orchestrator)
+**Bonding Curve Demos:**
 - `npm run demo:trades` - Basic buy/sell operations
 - `npm run demo:bonding:graduation` - Token graduation workflow and simulation
 - `npm run demo:bonding:pool-discovery` - Pool filtering and discovery
@@ -536,290 +307,16 @@ console.log(`✓ Sale completed: ${result.transactionId}`);
 - `npm run demo:bonding:token-launch` - Token launch lifecycle demonstration
 - `npm run demo:bonding:volume-trading` - High-volume trading simulation
 - `npm run demo:bonding:pool-analysis` - Deep pool analytics and metrics
-
-**Orchestrator Usage:**
-
-```bash
-# Run all bonding curve demos
-npm run demo:bonding:orchestrator
-
-# Skip specific demos
-npm run demo:bonding:orchestrator -- --skip=graduation,volume-trading
-
-# Run only specific demos
-npm run demo:bonding:orchestrator -- --only=pool-discovery,price-impact
-```
-
----
-
-## DEX Trading
-
-Trade graduated tokens on the GalaSwap DEX.
-
-### Get Swap Quote
-
-```typescript
-const sdk = createLaunchpadSDK({ env: 'prod' });
-
-// Quote for exact input (how many GUSDC for 100 GALA?)
-// v3.33.0+ requires delimited token format
-const quoteInput = await sdk.dex.quoting.quoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100');
-
-console.log(`Spend 100 GALA → Receive ~${quoteInput.amountOut} GUSDC`);
-console.log(`Price impact: ${quoteInput.priceImpact ?? 'n/a'}`);
-console.log(`Fee tier: ${quoteInput.feeTier} bps`);
-
-// Quote for exact output (how much GALA to get 100 GUSDC?)
-const quoteOutput = await sdk.dex.quoting.quoteExactOutput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100');
-
-console.log(`Need ${quoteOutput.amountIn} GALA → Get 100 GUSDC`);
-console.log(`Price impact: ${quoteOutput.priceImpact ?? 'n/a'}`);
-```
-
-### Submit and Confirm a Swap
-
-```typescript
-const sdk = createLaunchpadSDK({
-  env: 'prod',
-  privateKey: process.env.WALLET_PRIVATE_KEY
-});
-
-// Step 1: Get quote (v3.33.0+ requires delimited token format)
-const quote = await sdk.dex.quoting.quoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100');
-
-// Step 2: Submit the queued RequestTrade with 1% slippage protection
-const submitted = await sdk.dex.swaps.swap(
-  'GALA|Unit|none|none',
-  'GUSDC|Unit|none|none',
-  quote.feeTier,
-  { exactIn: '100', amountOutMinimum: quote.amountOut }  // amountOutMinimum should include your own slippage buffer
-);
-
-console.log(`Swap queued: ${submitted.transactionId} (mode: ${submitted.mode})`);
-console.log(`Expected output: ~${quote.amountOut} GUSDC`);
-
-// Step 3: Wait for the applied trade, or catch the chain's rejection
-const applied = await submitted.confirm();
-
-console.log(`✓ Swap applied!`);
-console.log(`Applied transaction: ${applied.transactionId}`);
-console.log(`Result: ${JSON.stringify(applied.result)}`);
-```
-
-### Discover DEX Pools
-
-```typescript
-// Fetch every current-contract pool, then filter/sort client-side
-const pools = await sdk.dex.pools.getPools();
-
-const topGalaPools = pools
-  .filter(pool => pool.token0 === 'GALA' || pool.token1 === 'GALA')
-  .sort((a, b) => (b.tvlUsd ?? 0) - (a.tvlUsd ?? 0))
-  .slice(0, 10);
-
-topGalaPools.forEach(pool => {
-  console.log(`${pool.poolName}: $${(pool.tvlUsd ?? 0).toLocaleString()} TVL`);
-  console.log(`  24h Volume: $${(pool.volume1d ?? 0).toLocaleString()}`);
-  console.log(`  APR: ${(pool.apr1d ?? 0).toFixed(2)}%`);
-});
-```
-
-**DEX Demos (8 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
-- `npm run demo:dex:leaderboard` - Seasonal leaderboard queries and XP rankings
-- `npm run demo:dex:volume-summary` - Platform volume metrics and trend analysis
-
-**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({ env: 'prod' });
-
-// 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({
-  env: 'prod',
-  privateKey: process.env.WALLET_PRIVATE_KEY
-});
-
-// Step 1: Create liquidity position (v3.33.0+ requires delimited token format)
-const positionTx = await sdk.dex.positions.addLiquidityByPrice({
-  token0: 'GALA|Unit|none|none',
-  token1: 'GUSDC|Unit|none|none',
-  fee: 3000,
-  minPrice: '0.95',
-  maxPrice: '1.05',
-  amount: '1000',
-  amountIsToken0: true,
-});
-
-const position = await positionTx.confirm();
-if (!position) throw new Error('Position confirmation returned null');
-console.log(`Position confirmed. Ticks: ${position.tickLower}..${position.tickUpper}`);
-
-// Step 2: Submit swaps to generate fees (each is a queued RequestTrade; confirm each)
-for (let i = 0; i < 10; i++) {
-  const swapTx = await sdk.dex.swaps.swap('GALA|Unit|none|none', 'GUSDC|Unit|none|none', 3000, { exactIn: '10' });
-  await swapTx.confirm();
-  console.log(`Swap ${i + 1} completed`);
-}
-
-// Step 3: Check accumulated fees
-const positionData = await sdk.dex.positions.getPosition({
-  token0: 'GALA|Unit|none|none',
-  token1: 'GUSDC|Unit|none|none',
-  fee: 3000,
-  owner: 'eth|0x...',
-  tickLower: position.tickLower,
-  tickUpper: position.tickUpper,
-});
-
-console.log(`Fees accumulated:`);
-console.log(`  ${positionData?.fees0} GALA`);
-console.log(`  ${positionData?.fees1} GUSDC`);
-
-// Step 4: Collect fees
-const collectTx = await sdk.dex.positions.collectPositionFees({
-  token0: 'GALA|Unit|none|none',
-  token1: 'GUSDC|Unit|none|none',
-  fee: 3000,
-  tickLower: position.tickLower,
-  tickUpper: position.tickUpper,
-});
-
-const collected = await collectTx.confirm();
-console.log(`✓ Collected: ${collected?.fees0} GALA + ${collected?.fees1} GUSDC`);
-```
-
-### 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.dex.quoting.quoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', swapAmount);
-  const swapTx = await sdk.dex.swaps.swap('GALA|Unit|none|none', 'GUSDC|Unit|none|none', quote.feeTier, {
-    exactIn: swapAmount,
-    amountOutMinimum: quote.amountOut,
-  });
-  await swapTx.confirm();
-
-  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
+- `npm run demo:bonding:user-holder` - Holder context
+- `npm run demo:bonding:pagination-variants` - Pagination variants
+- `npm run demo:bonding:pool-creator-filtering` - Creator filtering
 
 ---
 
 ## Real-Time Monitoring
 
-Monitor pool and token creation events using WebSocket event watchers.
-
-### Watch for DEX Pool Creation
-
-`sdk.onDexPoolCreation()` no longer exists. The gSwap realtime stream client now lives in
-@gala-chain/gswap-sdk (`new GSwap().stream`).
+Monitor token creation events with the SDK's watchers. (New DEX pools are gswap-sdk's:
+`gSwap.pools.watchNewPools()`.)
 
 ### Watch for Launchpad Token Creation
 
@@ -845,9 +342,11 @@ setTimeout(() => {
 }, 120000);
 ```
 
-**Monitoring Demos (2 total):**
-- `npm run demo:watch` - Watch for new DEX pool creation
+**Monitoring Demos:**
 - `npm run demo:watch:tokens` - Watch for new launchpad token launches
+- `npm run demo:watch:integration` - Token creation integration
+- `npm run demo:monitoring:stream-events` - Stream events
+- `npm run demo:monitoring:websocket-events` - WebSocket event handlers
 
 ---
 
@@ -955,15 +454,15 @@ await sdk.connectStreamWebSocket({
 });
 ```
 
-**Streaming & Chat Demos (5 total):**
+**Streaming & Chat Demos (a selection; `npm run demo:list` shows all):**
 - `npm run demo:streaming` - Basic stream management
 - `npm run demo:streaming:recordings` - Recording management
 - `npm run demo:streaming:simulcast` - Simulcast target management
-- `npm run demo:streaming:engagement` - Engagement statistics
 - `npm run demo:chat` - REST chat operations
 - `npm run demo:chat:websocket` - WebSocket real-time chat
 - `npm run demo:chat:typing-indicators` - Typing indicator demo
 
+
 ---
 
 ## Utilities
@@ -975,15 +474,7 @@ const sdk = createLaunchpadSDK({ env: 'prod' });
 
 // GALA balance
 const galaBalance = await sdk.fetchGalaBalance('eth|0x...');
-console.log(`GALA: ${galaBalance.balance}`);
-
-// Token balance on DEX
-const assets = await sdk.dex.assets.getUserAssets('eth|0x...');
-
-console.log('DEX Assets:');
-assets.tokens.forEach(asset => {
-  console.log(`  ${asset.symbol}: ${asset.quantity}`);
-});
+console.log(`GALA: ${galaBalance?.balance}`);
 
 // Tokens you hold
 const held = await sdk.fetchTokensHeld({
@@ -992,7 +483,7 @@ const held = await sdk.fetchTokensHeld({
 });
 
 console.log('Tokens held:');
-held.forEach(token => {
+held.tokens.forEach(token => {
   console.log(`  ${token.symbol}: ${token.balance}`);
 });
 ```
@@ -1064,29 +555,16 @@ console.timeEnd('Batch Calculations');
 // Output: Batch Calculations: ~50ms (vs ~2000ms without cache)
 ```
 
-**Utility Demos (5 total):**
+
+**Utility Demos:**
 - `npm run demo:cache` - Metadata cache warming and performance
 - `npm run demo:token-supply` - Token supply metrics from GalaChain
-- `npm run demo:utilities:balances` - Multi-token balance queries
 - `npm run demo:utilities:balance` - Single token balance check
-- `npm run demo:utilities:price-history` - Historical price data (Node.js only)
-
-**Key Features:**
+- `npm run demo:utilities:multi-token-portfolio` - Multi-token portfolio
+- `npm run demo:utilities:trade-history` - Trade history
 
-**Multi-Token Balances** (`demo:utilities:balances`):
-- Check balances for multiple tokens in a single wallet
-- Useful for portfolio overview and batch queries
-- Example: Query all token holdings at once
-
-**Single Token Balance** (`demo:utilities:balance`):
-- Check balance for a specific token
-- Fast, focused balance query
-- Example: Verify GALA balance before trade
-
-**Price History** (`demo:utilities:price-history`):
-- Fetch historical price data for technical analysis
-- Node.js only (requires file system access)
-- Example: Download price data for charting and trend analysis
+Wallet balances and price history on the DEX are gswap-sdk's (`src/assets/balances.ts`,
+`src/market/price-history.ts` in its demos).
 
 ---
 
@@ -1094,24 +572,6 @@ console.timeEnd('Batch Calculations');
 
 Common error patterns and solutions.
 
-### Network Errors
-
-```typescript
-try {
-  const quote = await sdk.dex.quoting.quoteExactInput('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
@@ -1134,74 +594,28 @@ try {
 
 ```typescript
 try {
-  const quote = await sdk.dex.quoting.quoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '10000');
-  const slippageTolerance = 0.01; // 1%
-  const amountOutMinimum = (Number(quote.amountOut) * (1 - slippageTolerance)).toString();
-  const submitted = await sdk.dex.swaps.swap(
-    'GALA|Unit|none|none',
-    'GUSDC|Unit|none|none',
-    quote.feeTier,
-    { exactIn: '10000', amountOutMinimum },
-  );
-  const applied = await submitted.confirm();
+  const quote = await sdk.calculateBuyAmount({ tokenName: 'anime', amount: '1000', type: 'native' });
+  await sdk.buy({
+    tokenName: 'anime',
+    amount: '1000',
+    type: 'native',
+    expectedAmount: quote.amount,
+    slippageToleranceFactor: 0.01
+  });
 } catch (error) {
   if (error.message.includes('slippage')) {
     console.log('Price moved beyond slippage tolerance');
-    console.log('Increase slippage or retry with fresh quote');
+    console.log('Increase slippage or retry with a 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/
-├── api-keys/          # 2 demos - API key management
-├── bans/              # 1 demo - User ban management
-├── bonding-curve/     # 8 demos - Pre-graduation trading
-├── bridge/            # 23 demos - Cross-chain bridging
-├── chat/              # 3 demos - REST & WebSocket chat
-├── content-flags/     # 1 demo - Content flag management
-├── core/              # 6 demos - SDK fundamentals
-├── dex/               # 8 demos - DEX trading & leaderboard
-├── fees/              # 5 demos - Fee workflows
-├── liquidity/         # 12 demos - LP position management
-├── locks/             # 2 demos - Token locking
-├── moderators/        # 1 demo - Moderator invites
-├── monitoring/        # 11 demos - Real-time events
-├── overseers/         # 1 demo - Overseer management
-├── streaming/         # 4 demos - Stream management & engagement
-├── utilities/         # 7 demos - Helper operations
-└── debug/             # 5 tools - Development utilities (not in npm scripts)
-```
-
-**Total:** 99 demos covering all major SDK features (+ 5 debug tools)
-
-**Category Breakdown:**
-- **API Key Management**: 2 demos for API key CRUD operations
-- **Ban Management**: 1 demo for user ban/unban workflows
-- **Bonding Curve Trading**: 8 demos for pre-graduation token trading (orchestrator + 7 specialized)
-- **Cross-Chain Bridge**: 23 demos for GalaChain ↔ Ethereum/Solana bridging
-- **Chat**: 3 demos for REST chat, WebSocket chat, and typing indicators
-- **Content Flags**: 1 demo for content flag/report management
-- **Core Operations**: 6 demos covering SDK setup, configuration, and multi-wallet testing
-- **DEX Trading**: 8 demos for swaps, pools, leaderboard, and volume analytics
-- **Fee Management**: 5 demos for fee generation and collection workflows
-- **Liquidity Management**: 12 demos for LP positions (orchestrator + 11 specialized)
-- **Token Locking**: 2 demos for lock/unlock workflows
-- **Moderators**: 1 demo for moderator invite management
-- **Real-Time Monitoring**: 11 demos for pool/token creation watchers
-- **Overseers**: 1 demo for overseer management
-- **Streaming**: 4 demos for stream management, recordings, simulcast, and engagement stats
-- **Swap Monitoring**: 4 demos for DEX swap event tracking
-- **Utilities**: 7 demos for balances, cache, supply, and price history
-- **Debug Tools**: 5 development utilities (not exposed as npm scripts)
+See the `examples/` directory for the working demos by category (`examples/README.md` lists them);
+`npm run demo:list` browses them. DEX demos live in
+[`packages/gswap-sdk/examples/demos`](../gswap-sdk/examples/demos/README.md).
 
 For migration from old demo structure, see [docs/DEMO_MIGRATION_GUIDE.md](./docs/DEMO_MIGRATION_GUIDE.md).