@gala-chain/launchpad-sdk 4.0.6 → 4.0.7-beta.10

package/README.md

@@ -73,6 +73,8 @@ console.log(pools.hasNext); // Computed convenience properties
 - **User Operations**: Portfolio management, token balances, and account management
 - **Comment System**: Post and retrieve comments on token pools
 - **Price History**: Fetch historical price data for DEX tokens with pagination (Node.js only)
+- **Cross-Chain Bridging**: Transfer tokens between GalaChain, Ethereum, and Solana with fee estimation
+- **External Wallet Balances**: Query Ethereum and Solana wallet balances (single-token or full portfolio)
 - **Comprehensive Validation**: Input validation and error handling for all operations
 - **Multi-Environment Support**: Production, staging, and custom backend URLs
 
@@ -1232,6 +1234,106 @@ await sdk.unlockToken({
 - **Escrow**: Third-party holds tokens until conditions met
 - **Vesting**: Time-locked token releases with expiration
 
+## Cross-Chain Bridge Operations
+
+The SDK provides comprehensive cross-chain bridging for GalaChain ↔ Ethereum and GalaChain ↔ Solana transfers.
+
+### Configuration
+
+```typescript
+import { LaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = new LaunchpadSDK({
+  wallet: process.env.PRIVATE_KEY,
+  // Bridge configuration (optional - enables bridge operations)
+  ethereumPrivateKey: process.env.ETHEREUM_PRIVATE_KEY, // Required for Ethereum bridging
+  solanaPrivateKey: process.env.SOLANA_PRIVATE_KEY,     // Required for Solana bridging
+});
+```
+
+### Wallet Balance Queries
+
+Query Ethereum and Solana wallet balances with two approaches:
+
+**Single Token Queries (Fast - 1 RPC call)**
+```typescript
+// Single ERC-20 token balance
+const gala = await sdk.fetchEthereumWalletTokenBalance('GALA');
+// Returns: { symbol: 'GALA', quantity: '1234.56', decimals: 8, contractAddress: '0x...', isNative: false }
+
+// Native ETH balance
+const eth = await sdk.fetchEthereumWalletNativeBalance();
+// Returns: { symbol: 'ETH', quantity: '0.5', decimals: 18, contractAddress: null, isNative: true }
+
+// Single SPL token balance (Solana)
+const solGala = await sdk.fetchSolanaWalletTokenBalance('GALA');
+// Returns: { symbol: 'GALA', quantity: '789.01', decimals: 8, contractAddress: '...', isNative: false }
+
+// Native SOL balance
+const sol = await sdk.fetchSolanaWalletNativeBalance();
+// Returns: { symbol: 'SOL', quantity: '2.5', decimals: 9, contractAddress: null, isNative: true }
+```
+
+**All Tokens Queries (Complete portfolio view)**
+```typescript
+// Ethereum: ETH + all supported ERC-20s (GALA, GWETH, GUSDC, GUSDT, GWTRX, GWBTC)
+const allEth = await sdk.fetchEthereumWalletAllBalances();
+console.log(allEth.native.quantity);  // ETH balance
+console.log(allEth.tokens);           // 6 ERC-20 balances
+console.log(allEth.address);          // Wallet address
+console.log(allEth.timestamp);        // Query timestamp
+
+// Solana: SOL + all supported SPL tokens (GALA, GSOL)
+const allSol = await sdk.fetchSolanaWalletAllBalances();
+console.log(allSol.native.quantity);  // SOL balance
+console.log(allSol.tokens);           // 2 SPL balances
+```
+
+**When to use which:**
+- **Single-token queries**: Quick checks, performance-critical scenarios, frequent polling
+- **All-tokens queries**: Portfolio dashboards, wallet UIs, multi-token operations
+
+### Bridge Operations
+
+```typescript
+// Estimate fees before bridging
+const fee = await sdk.estimateBridgeFee({
+  tokenSymbol: 'GALA',
+  destinationChain: 'Ethereum',
+  amount: '1000',
+});
+
+// Bridge OUT: GalaChain → Ethereum/Solana
+const result = await sdk.bridgeOut({
+  tokenSymbol: 'GALA',
+  amount: '1000',
+  destinationChain: 'Ethereum',
+  recipientAddress: '0x...',
+});
+
+// Bridge IN: Ethereum/Solana → GalaChain
+const result = await sdk.bridgeIn({
+  tokenSymbol: 'GALA',
+  amount: '1000',
+  sourceChain: 'Ethereum',
+});
+
+// Check bridge status
+const status = await sdk.getBridgeStatus(result.transactionHash);
+```
+
+### Supported Tokens
+
+| Token | Symbol | Ethereum | Solana | Decimals |
+|-------|--------|----------|--------|----------|
+| GALA | GALA | ✅ | ✅ | 8 |
+| Wrapped ETH | GWETH | ✅ | - | 18 |
+| USD Coin | GUSDC | ✅ | - | 6 |
+| Tether USD | GUSDT | ✅ | - | 6 |
+| Wrapped TRON | GWTRX | ✅ | - | 6 |
+| Wrapped BTC | GWBTC | ✅ | - | 8 |
+| Wrapped SOL | GSOL | - | ✅ | 9 |
+
 ## Multi-Wallet Support
 
 The SDK supports **per-operation wallet overrides** for testing multi-wallet workflows without creating new SDK instances. This is ideal for:
@@ -2138,8 +2240,21 @@ executeSwap(fromToken, toToken, amount, estimatedOutput, feeTier, slippageTolera
 
 // GSwap User Operations
 getSwapUserAssets(walletAddress): Promise<UserAsset[]>
-// Returns: [{ tokenId, symbol, balance, decimals }, ...]
-// Get user token balances across all DEX pools
+// Returns: [{ tokenId, symbol, name, description, image, balance, decimals, verified, compositeKey }, ...]
+// Get user token balances with rich metadata (v4.1.0+)
+
+getAllSwapUserAssets(walletAddress): Promise<UserAsset[]>
+// Returns: All user tokens with rich metadata (auto-paginated)
+// Optimized: Stops fetching when zero-balance tokens encountered
+
+// Token Discovery (no wallet required)
+fetchAvailableDexTokens({ search?, limit?, page? }): Promise<AvailableDexTokensResult>
+// Returns: { tokens: DexToken[], count, page, limit, hasMore }
+// Paginated token discovery with rich metadata
+
+fetchAllAvailableDexTokens({ search? }): Promise<DexToken[]>
+// Returns: All available DEX tokens (auto-paginated)
+// Use for comprehensive token catalogs and listings
 
 getSwapPoolInfo(tokenA, tokenB): Promise<PoolInfo>
 // Returns: { tokenA, tokenB, liquidity, feeTiers, swapCount }
@@ -2196,12 +2311,25 @@ const swapResult = await gswapService.executeSwap({
 console.log(`Swap completed! TX: ${swapResult.transactionId}`);
 console.log(`Received: ${swapResult.outputAmount} GUSDC`);
 
-// Query user assets on DEX
+// Query user assets on DEX (returns rich metadata)
 const assets = await gswapService.getUserAssets('eth|0x...');
 assets.forEach(asset => {
-  console.log(`${asset.symbol}: ${asset.balance}`);
+  console.log(`${asset.symbol} (${asset.name}): ${asset.balance}`);
+  console.log(`  Image: ${asset.image}`);
+  console.log(`  Verified: ${asset.verified}`);
 });
 
+// Discover all available DEX tokens (no wallet required)
+const availableTokens = await sdk.fetchAvailableDexTokens({ limit: 20, page: 1 });
+console.log(`Found ${availableTokens.count} tokens on DEX`);
+availableTokens.tokens.forEach(token => {
+  console.log(`${token.symbol}: ${token.name} - ${token.description}`);
+});
+
+// Get ALL available tokens (auto-paginated)
+const allTokens = await sdk.fetchAllAvailableDexTokens();
+console.log(`Total: ${allTokens.length} tokens available on DEX`);
+
 // Get pool information for token pair
 const poolInfo = await gswapService.getPoolInfo('GALA', 'GUSDC');
 console.log(`Liquidity: ${poolInfo.liquidity}`);
@@ -2304,6 +2432,48 @@ uploadProfileImage(options): Promise<ImageUploadResult>
 - `resolveVaultAddress(tokenName: string): Promise<string>`
 - `cleanup(): void` - Cleanup resources
 
+### **Cross-Chain Bridge Operations**
+
+```typescript
+// Bridge Configuration (requires ethereumPrivateKey and/or solanaPrivateKey)
+
+// Wallet Balance Queries - Single Token (Fast - 1 RPC call)
+fetchEthereumWalletTokenBalance(symbol, address?): Promise<ExternalChainBalance>
+// Fetch single ERC-20 balance (GALA, GWETH, GUSDC, GUSDT, GWTRX, GWBTC)
+
+fetchEthereumWalletNativeBalance(address?): Promise<ExternalChainBalance>
+// Fetch native ETH balance only
+
+fetchSolanaWalletTokenBalance(symbol, address?): Promise<ExternalChainBalance>
+// Fetch single SPL token balance (GALA, GSOL)
+
+fetchSolanaWalletNativeBalance(address?): Promise<ExternalChainBalance>
+// Fetch native SOL balance only
+
+// Wallet Balance Queries - All Tokens (Complete Portfolio)
+fetchEthereumWalletAllBalances(address?): Promise<EthereumWalletBalanceResult>
+// Returns: { address, native, tokens[], timestamp } - ETH + 6 ERC-20s
+
+fetchSolanaWalletAllBalances(address?): Promise<SolanaWalletBalanceResult>
+// Returns: { address, native, tokens[], timestamp } - SOL + 2 SPL tokens
+
+// Bridge Operations
+estimateBridgeFee(options): Promise<BridgeFeeEstimate>
+// Estimate fees for bridging tokens
+
+bridgeOut(options): Promise<BridgeResult>
+// Bridge tokens FROM GalaChain TO Ethereum/Solana
+
+bridgeIn(options): Promise<BridgeResult>
+// Bridge tokens FROM Ethereum/Solana TO GalaChain
+
+getBridgeStatus(transactionHash, chainHint?): Promise<BridgeStatus>
+// Check status of bridge transaction
+
+getSupportedBridgeTokens(chain?): BridgeTokenInfo[]
+// List supported bridge tokens
+```
+
 ## Configuration
 
 ### Constants