@gala-chain/launchpad-sdk 4.0.3 → 4.0.4-beta.1

package/dist/src/LaunchpadSDK.d.ts

@@ -874,17 +874,60 @@ export declare class LaunchpadSDK {
      */
     calculateDexPoolQuoteExactAmount(options: CalculateDexPoolQuoteOptions, mode?: 'local' | 'external'): Promise<DexPoolQuoteResult>;
     /**
-     * Token distribution information
+     * Fetch token ownership distribution with holder percentages
      *
-     * @param tokenName Token name to fetch distribution for
-     * @returns Promise<TokenDistributionResult>
+     * Retrieves complete token holder distribution data including all wallet addresses,
+     * their token balances, and ownership percentages. This endpoint returns ALL holders
+     * in a single non-paginated response, making it perfect for distribution analysis,
+     * whale tracking, and supply health metrics.
+     *
+     * @category Token Information
+     * @param tokenName - Token name to fetch distribution for (e.g., 'anime', 'mytoken')
+     * @returns Promise with distribution data including holders array, total supply, and total holder count
+     * @throws {ValidationError} If tokenName is invalid or empty
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.4-beta.0
+     *
+     * @example Basic distribution query
+     * ```typescript
+     * const distribution = await sdk.fetchTokenDistribution('anime');
+     * console.log(`Total holders: ${distribution.totalHolders}`);
+     * console.log(`Total supply: ${distribution.totalSupply}`);
+     * distribution.holders.forEach(holder => {
+     *   console.log(`${holder.address}: ${holder.percentage}%`);
+     * });
+     * ```
+     *
+     * @example Whale analysis
+     * ```typescript
+     * const dist = await sdk.fetchTokenDistribution('mytoken');
+     * const whales = dist.holders.filter(h => h.percentage > 5);
+     * console.log(`Found ${whales.length} whales with >5% ownership`);
+     * ```
      */
     fetchTokenDistribution(tokenName: string): Promise<import("./types/launchpad.dto").TokenDistributionResult>;
     /**
-     * Fetch token badges
+     * Fetch token achievement badges and metadata
      *
-     * @param tokenName Token name to fetch badges for
-     * @returns Promise<TokenBadgesResult>
+     * Retrieves badge data for a token including achievement milestones, special recognitions,
+     * and platform-assigned attributes. Badges provide additional context about token
+     * performance, community engagement, and platform status.
+     *
+     * @category Token Information
+     * @param tokenName - Token name to fetch badges for (e.g., 'anime', 'mytoken')
+     * @returns Promise with badge data including badge types, timestamps, and metadata
+     * @throws {ValidationError} If tokenName is invalid or empty
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.4-beta.0
+     *
+     * @example Fetch token badges
+     * ```typescript
+     * const badges = await sdk.fetchTokenBadges('anime');
+     * console.log(`Token has ${badges.length} badges`);
+     * badges.forEach(badge => {
+     *   console.log(`Badge: ${badge.name} - ${badge.description}`);
+     * });
+     * ```
      */
     fetchTokenBadges(tokenName: string): Promise<import("./types/launchpad.dto").TokenBadgesResult>;
     /**
@@ -1342,24 +1385,136 @@ export declare class LaunchpadSDK {
      */
     isTokenGraduated(tokenName: string): Promise<boolean>;
     /**
-     * Fetch volume data for a token
+     * Fetch historical trading volume data for charting
+     *
+     * Retrieves time-series trading volume data for a specific token, perfect for
+     * building volume charts, analyzing trading activity patterns, and monitoring
+     * market engagement. Data is aggregated by time period with buy/sell breakdowns.
+     *
+     * @category Trading Data
+     * @param options - Volume data options with required tokenName and optional time range
+     * @param options.tokenName - Token name to fetch volume data for (required)
+     * @param options.startDate - Start date for volume data range (optional)
+     * @param options.endDate - End date for volume data range (optional)
+     * @param options.interval - Time interval for aggregation (e.g., '1h', '1d', '1w') (optional)
+     * @returns Promise with graph data containing timestamps, volume amounts, and trade counts
+     * @throws {ValidationError} If tokenName is missing or invalid
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.4-beta.0
+     *
+     * @example Fetch all-time volume
+     * ```typescript
+     * const volumeData = await sdk.fetchVolumeData({ tokenName: 'anime' });
+     * console.log(`Total data points: ${volumeData.length}`);
+     * volumeData.forEach(point => {
+     *   console.log(`${point.timestamp}: $${point.volume} volume`);
+     * });
+     * ```
      *
-     * @param options Volume data options with required tokenName
-     * @returns Promise<GraphDataResult>
+     * @example Fetch volume for date range
+     * ```typescript
+     * const volumeData = await sdk.fetchVolumeData({
+     *   tokenName: 'mytoken',
+     *   startDate: new Date('2024-01-01'),
+     *   endDate: new Date('2024-01-31')
+     * });
+     * console.log(`January volume: ${volumeData.reduce((sum, p) => sum + p.volume, 0)}`);
+     * ```
      */
     fetchVolumeData(options: FetchVolumeDataOptions): Promise<import("./types/launchpad.dto").GraphDataResult>;
     /**
-     * Fetch trade history with filters
+     * Fetch trade history with optional filters and pagination
      *
+     * Retrieves paginated historical trades for a specific token from the Launchpad backend.
+     * Supports filtering by trade type (buy/sell), wallet address, and time range for detailed
+     * trade analysis and portfolio tracking.
+     *
+     * @category Trading Data
      * @param options Trade fetching options with required tokenName
-     * @returns Promise<TradesResult>
+     * @param options.tokenName - Token name to fetch trades for (required)
+     * @param options.page - Page number (1-based), defaults to 1
+     * @param options.limit - Items per page, defaults to 20
+     * @param options.type - Filter by trade type: 'buy' or 'sell' (optional)
+     * @param options.address - Filter by wallet address (optional)
+     * @param options.startDate - Filter trades after this date (optional)
+     * @param options.endDate - Filter trades before this date (optional)
+     * @returns Promise<TradesResult> Paginated trade history with metadata
+     * @throws {ValidationError} If tokenName is not provided
+     * @throws {NetworkError} If API request fails
+     * @since 1.0.0
+     *
+     * @example Basic trade history
+     * ```typescript
+     * const trades = await sdk.fetchTrades({
+     *   tokenName: 'anime',
+     *   page: 1,
+     *   limit: 50
+     * });
+     * console.log(`Found ${trades.total} trades`);
+     * trades.trades.forEach(trade => {
+     *   console.log(`${trade.type}: ${trade.amount} @ ${trade.price}`);
+     * });
+     * ```
+     *
+     * @example Filter by trade type
+     * ```typescript
+     * const buys = await sdk.fetchTrades({
+     *   tokenName: 'anime',
+     *   type: 'buy',
+     *   limit: 20
+     * });
+     * console.log(`Recent buy trades: ${buys.trades.length}`);
+     * ```
+     *
+     * @example Filter by wallet and date range
+     * ```typescript
+     * const myTrades = await sdk.fetchTrades({
+     *   tokenName: 'anime',
+     *   address: sdk.getAddress(),
+     *   startDate: new Date('2025-01-01'),
+     *   endDate: new Date('2025-01-31')
+     * });
+     * console.log(`My January trades: ${myTrades.total}`);
+     * ```
      */
     fetchTrades(options: FetchTradesOptions): Promise<import("./types/trade.dto").TradesResult>;
     /**
-     * Fetch GALA balance for a user
+     * Fetch GALA token balance for a wallet address
      *
-     * @param address Optional wallet address (0x... or eth|... format), defaults to current user
-     * @returns Promise<GalaBalanceResult>
+     * Retrieves the current GALA token balance for a specified wallet address or the authenticated
+     * user's wallet if no address is provided. Returns complete balance information including
+     * token quantity, token metadata, and collection details from GalaChain.
+     *
+     * **Supports both address formats:**
+     * - Standard Ethereum format: `0x...` (64 hex characters after 0x prefix)
+     * - Backend format: `eth|...` (full GalaChain address format)
+     *
+     * @category Main SDK
+     * @param address - Optional wallet address in 0x... or eth|... format. Defaults to current SDK wallet address.
+     * @returns Promise<GalaBalanceResult> Complete balance details including quantity and token metadata
+     * @throws {ValidationError} If wallet is not configured and no address is provided
+     * @throws {NetworkError} If GalaChain query fails or network connection is unavailable
+     * @since 4.0.4-beta.0
+     *
+     * @example Fetch balance for authenticated wallet
+     * ```typescript
+     * const balance = await sdk.fetchGalaBalance();
+     * console.log(`Your GALA balance: ${balance.quantity}`);
+     * ```
+     *
+     * @example Fetch balance for specific address
+     * ```typescript
+     * const address = 'eth|742d35Cc6634C0532925a3b8D0Ea2c76f94C31C0';
+     * const balance = await sdk.fetchGalaBalance(address);
+     * console.log(`Balance: ${balance.quantity} GALA`);
+     * ```
+     *
+     * @example Fetch and format balance
+     * ```typescript
+     * const balance = await sdk.fetchGalaBalance();
+     * const formattedBalance = (BigInt(balance.quantity) / BigInt(10 ** 8)).toString();
+     * console.log(`GALA: ${formattedBalance}`);
+     * ```
      */
     fetchGalaBalance(address?: string): Promise<import("./types/user.dto").TokenBalanceResult | null>;
     /**
@@ -1463,17 +1618,134 @@ export declare class LaunchpadSDK {
      */
     fetchAvailableBalance(options: FetchTokenBalanceOptions): Promise<AvailableBalanceResult | null>;
     /**
-     * Calculate buy amount for a token purchase
+     * Calculate buy amount for a token purchase with automatic mode selection
+     *
+     * Flexible calculation method that automatically routes to either local (instant, client-side)
+     * or external (real-time, GalaChain) calculation based on available parameters. Defaults to
+     * external calculation for guaranteed accuracy unless currentSupply is provided.
+     *
+     * Supports two calculation types:
+     * - **type: 'native'** - Calculate tokens received for a given GALA amount
+     * - **type: 'exact'** - Calculate GALA needed to buy a specific token amount
+     *
+     * @category Calculations
+     * @param options Calculation options with required tokenName and amount
+     * @param options.tokenName - Token name to calculate for (required)
+     * @param options.amount - Amount to calculate (GALA or tokens depending on type)
+     * @param options.type - 'native' (spending GALA) or 'exact' (buying tokens)
+     * @param options.currentSupply - Current token supply for local calculation (optional, enables instant calculation)
+     * @returns Promise<AmountCalculationResult> Calculated amount with fees breakdown
+     * @throws {ValidationError} If tokenName or amount is invalid
+     * @throws {NetworkError} If external calculation fails
+     * @since 1.0.0
+     *
+     * @example Calculate tokens from GALA (external mode)
+     * ```typescript
+     * const result = await sdk.calculateBuyAmount({
+     *   tokenName: 'anime',
+     *   amount: '100',      // 100 GALA
+     *   type: 'native'
+     * });
+     * console.log('Tokens you will receive:', result.amount);
+     * console.log('Transaction fee:', result.transactionFee);
+     * ```
      *
-     * @param options Calculation options with required tokenName
-     * @returns Promise<AmountCalculationResult>
+     * @example Calculate GALA needed for tokens (external mode)
+     * ```typescript
+     * const result = await sdk.calculateBuyAmount({
+     *   tokenName: 'anime',
+     *   amount: '1000',     // 1000 tokens
+     *   type: 'exact'
+     * });
+     * console.log('GALA needed:', result.amount);
+     * console.log('Total cost with fees:', result.totalCost);
+     * ```
+     *
+     * @example Performance-optimized with local calculation
+     * ```typescript
+     * // Fetch supply once, reuse for multiple calculations
+     * const poolDetails = await sdk.fetchPoolDetailsForCalculation('anime');
+     *
+     * const calc1 = await sdk.calculateBuyAmount({
+     *   tokenName: 'anime',
+     *   amount: '100',
+     *   type: 'native',
+     *   currentSupply: poolDetails.currentSupply  // Enables instant local calculation
+     * });
+     *
+     * const calc2 = await sdk.calculateBuyAmount({
+     *   tokenName: 'anime',
+     *   amount: '500',
+     *   type: 'native',
+     *   currentSupply: poolDetails.currentSupply  // Reuse same supply
+     * });
+     * ```
      */
     calculateBuyAmount(options: CalculateBuyAmountOptions): Promise<import("./types/launchpad.dto").AmountCalculationResult>;
     /**
-     * Calculate sell amount for a token sale
+     * Calculate sell amount for a token sale with automatic mode selection
+     *
+     * Flexible calculation method that automatically routes to either local (instant, client-side)
+     * or external (real-time, GalaChain) calculation based on available parameters. Defaults to
+     * external calculation for guaranteed accuracy unless currentSupply and RBC fees are provided.
+     *
+     * Supports two calculation types:
+     * - **type: 'exact'** - Calculate GALA received for selling a specific token amount
+     * - **type: 'native'** - Calculate tokens needed to receive a specific GALA amount
+     *
+     * Includes reverse bonding curve (RBC) fee calculation that scales with token supply.
+     *
+     * @category Calculations
+     * @param options Calculation options with required tokenName and amount
+     * @param options.tokenName - Token name to calculate for (required)
+     * @param options.amount - Amount to calculate (tokens or GALA depending on type)
+     * @param options.type - 'exact' (selling tokens) or 'native' (receiving GALA)
+     * @param options.currentSupply - Current token supply for local calculation (optional)
+     * @param options.reverseBondingCurveMaxFeeFactor - RBC max fee for local calculation (optional)
+     * @param options.reverseBondingCurveMinFeeFactor - RBC min fee for local calculation (optional)
+     * @returns Promise<AmountCalculationResult> Calculated amount with fees breakdown including RBC fee
+     * @throws {ValidationError} If tokenName or amount is invalid
+     * @throws {NetworkError} If external calculation fails
+     * @since 1.0.0
      *
-     * @param options Calculation options with required tokenName
-     * @returns Promise<AmountCalculationResult>
+     * @example Calculate GALA from selling tokens (external mode)
+     * ```typescript
+     * const result = await sdk.calculateSellAmount({
+     *   tokenName: 'anime',
+     *   amount: '500',      // 500 tokens
+     *   type: 'exact'
+     * });
+     * console.log('GALA you will receive:', result.amount);
+     * console.log('Reverse bonding fee:', result.reverseBondingCurveFee);
+     * console.log('Transaction fee:', result.transactionFee);
+     * ```
+     *
+     * @example Calculate tokens needed for GALA (external mode)
+     * ```typescript
+     * const result = await sdk.calculateSellAmount({
+     *   tokenName: 'anime',
+     *   amount: '50',       // 50 GALA desired
+     *   type: 'native'
+     * });
+     * console.log('Tokens to sell:', result.amount);
+     * console.log('Total fees deducted:', result.totalFees);
+     * ```
+     *
+     * @example Performance-optimized with local calculation
+     * ```typescript
+     * // Fetch pool details once, reuse for multiple calculations
+     * const poolDetails = await sdk.fetchPoolDetailsForCalculation('anime');
+     *
+     * const calc1 = await sdk.calculateSellAmount({
+     *   tokenName: 'anime',
+     *   amount: '500',
+     *   type: 'exact',
+     *   currentSupply: poolDetails.currentSupply,
+     *   reverseBondingCurveMaxFeeFactor: poolDetails.reverseBondingCurveMaxFeeFactor,
+     *   reverseBondingCurveMinFeeFactor: poolDetails.reverseBondingCurveMinFeeFactor
+     * });
+     * // Instant local calculation - no network calls
+     * ```
      */
     calculateSellAmount(options: CalculateSellAmountOptions): Promise<import("./types/launchpad.dto").AmountCalculationResult>;
     /**
@@ -1665,35 +1937,151 @@ export declare class LaunchpadSDK {
      */
     graduateToken(options: GraduateTokenOptions): Promise<TradeResult>;
     /**
-     * Calculate initial buy amount (pre-mint phase)
+     * Calculate initial buy amount for pre-mint token launches
+     *
+     * Calculates the number of tokens that will be received when purchasing during
+     * the token launch pre-buy phase. This is used internally during token creation
+     * with the preBuyQuantity parameter.
+     *
+     * The pre-mint phase uses the same exponential bonding curve formula but starts
+     * from zero supply, providing the best possible price for early supporters.
+     *
+     * @category Calculations
+     * @param nativeTokenQuantity Amount of GALA to spend during pre-buy (decimal string)
+     * @returns Promise<PreMintCalculationResult> Calculated tokens with fee breakdown
+     * @throws {ValidationError} If nativeTokenQuantity is invalid or negative
+     * @throws {NetworkError} If API request fails
+     * @since 1.0.0
+     *
+     * @example Calculate pre-buy tokens
+     * ```typescript
+     * const result = await sdk.calculateInitialBuyAmount('100');
+     * console.log('Tokens from 100 GALA pre-buy:', result.amount);
+     * console.log('Transaction fee:', result.transactionFee);
+     * console.log('Starting supply:', result.currentSupply); // Should be "0"
+     * ```
      *
-     * @param nativeTokenQuantity Amount of native token (GALA) to spend
-     * @returns Promise<PreMintCalculationResult>
+     * @example Validate pre-buy before launch
+     * ```typescript
+     * // Check what you'll receive before launching token
+     * const preBuyAmount = '50'; // 50 GALA
+     * const calc = await sdk.calculateInitialBuyAmount(preBuyAmount);
+     *
+     * console.log(`Pre-buying with ${preBuyAmount} GALA will give you ${calc.amount} tokens`);
+     *
+     * // Now launch with this pre-buy amount
+     * const launch = await sdk.launchToken({
+     *   tokenName: 'mytoken',
+     *   tokenSymbol: 'MTK',
+     *   tokenDescription: 'My token',
+     *   preBuyQuantity: preBuyAmount
+     * });
+     * ```
      */
     calculateInitialBuyAmount(nativeTokenQuantity: string): Promise<import("./types/launchpad.dto").AmountCalculationResult>;
     /**
-     * Buy tokens with confirmation
+     * Buy tokens with blockchain confirmation and WebSocket monitoring
+     *
+     * Executes a buy order on the bonding curve and waits for GalaChain confirmation via WebSocket,
+     * returning complete trade details including actual amounts traded, fees paid, and transaction metadata.
+     *
+     * **Slippage Protection:**
+     * - Uses `expectedAmount` to protect against price changes during execution
+     * - `slippageToleranceFactor` allows variance (e.g., 0.01 = 1% tolerance)
+     * - Transaction fails if actual amount deviates beyond tolerance
+     *
+     * **Transaction Types:**
+     * - **type: 'native'** - Spend exact GALA amount, receive variable tokens
+     * - **type: 'exact'** - Buy exact token amount, spend variable GALA
+     *
+     * **WebSocket Confirmation:**
+     * - Pre-connects WebSocket before submission to avoid race conditions
+     * - Blocks until transaction confirmed on GalaChain
+     * - Returns rich trade result with all transaction details
+     *
+     * @category Trading Actions
+     * @param options Buy options with required tokenName, amount, and slippage protection
+     * @param options.tokenName - Token name to buy (required)
+     * @param options.amount - Amount to buy (GALA or tokens depending on type)
+     * @param options.type - 'native' (spending GALA) or 'exact' (buying tokens)
+     * @param options.expectedAmount - Expected output amount for slippage check (required)
+     * @param options.slippageToleranceFactor - Slippage tolerance (0.01 = 1%), defaults to SDK config
+     * @param options.maxAcceptableReverseBondingCurveFeeSlippageFactor - RBC fee slippage tolerance (optional)
+     * @param options.privateKey - Override wallet private key for this transaction (optional)
+     * @returns Promise<TradeResult> Complete trade result with amounts, fees, and blockchain metadata
+     * @throws {ValidationError} If wallet not configured or parameters invalid
+     * @throws {TransactionError} If transaction fails or no transaction ID returned
+     * @throws {WebSocketError} If confirmation fails or times out
+     * @throws {SlippageError} If price moves beyond tolerance
+     * @since 1.0.0
      *
-     * Executes a buy order and waits for blockchain confirmation, returning
-     * complete trade details including actual amounts traded and fees paid.
+     * @example Buy tokens with GALA (type: 'native')
+     * ```typescript
+     * // Step 1: Calculate expected output
+     * const quote = await sdk.calculateBuyAmount({
+     *   tokenName: 'anime',
+     *   amount: '100',     // 100 GALA
+     *   type: 'native'
+     * });
      *
-     * @param options Buy options with required tokenName and expectedAmount
-     * @returns Promise<TradeResult> Complete trade result with amounts and fees
-     * @since 3.0.0 - Now returns TradeResult instead of basic response
+     * // Step 2: Execute buy with slippage protection
+     * const result = await sdk.buy({
+     *   tokenName: 'anime',
+     *   amount: '100',                    // Spend 100 GALA
+     *   type: 'native',
+     *   expectedAmount: quote.amount,     // Expected tokens from quote
+     *   slippageToleranceFactor: 0.01    // 1% slippage tolerance
+     * });
      *
-     * @example
+     * console.log('Spent GALA:', result.inputAmount);
+     * console.log('Received tokens:', result.outputAmount);
+     * console.log('Transaction fee:', result.transactionFee);
+     * console.log('Total fees:', result.totalFees);
+     * console.log('Block hash:', result.blockHash);
+     * console.log('Transaction ID:', result.transactionId);
+     * ```
+     *
+     * @example Buy exact token amount (type: 'exact')
      * ```typescript
+     * // Step 1: Calculate GALA cost
+     * const quote = await sdk.calculateBuyAmount({
+     *   tokenName: 'anime',
+     *   amount: '1000',    // 1000 tokens desired
+     *   type: 'exact'
+     * });
+     *
+     * // Step 2: Execute buy
      * const result = await sdk.buy({
-     *   tokenName: 'mytoken',
-     *   amount: '100',
-     *   type: 'native',
-     *   expectedAmount: '1000',
-     *   slippageToleranceFactor: 0.05
+     *   tokenName: 'anime',
+     *   amount: '1000',                   // Buy exactly 1000 tokens
+     *   type: 'exact',
+     *   expectedAmount: quote.amount,     // Expected GALA cost from quote
+     *   slippageToleranceFactor: 0.02    // 2% slippage tolerance
      * });
      *
-     * console.log('Bought tokens:', result.outputAmount);
+     * console.log('Bought tokens:', result.outputAmount);  // Should be ~1000
      * console.log('Spent GALA:', result.inputAmount);
-     * console.log('Fees paid:', result.totalFees);
+     * ```
+     *
+     * @example Error handling with slippage
+     * ```typescript
+     * try {
+     *   const result = await sdk.buy({
+     *     tokenName: 'anime',
+     *     amount: '100',
+     *     type: 'native',
+     *     expectedAmount: '950',
+     *     slippageToleranceFactor: 0.01
+     *   });
+     *   console.log('Trade successful:', result.transactionId);
+     * } catch (error) {
+     *   if (error instanceof SlippageError) {
+     *     console.error('Price moved too much:', error.message);
+     *     // Retry with fresh quote
+     *   } else {
+     *     console.error('Trade failed:', error);
+     *   }
+     * }
      * ```
      */
     buy(options: BuyTokenOptions): Promise<TradeResult>;
@@ -1746,73 +2134,345 @@ export declare class LaunchpadSDK {
      */
     getBundlerTransactionResult(transactionId: string): Promise<import("./types/common").ApiResponse<unknown>>;
     /**
-     * Launch a new token
+     * Launch a new token with bonding curve trading
+     *
+     * Creates a new launchpad token with an automated bonding curve for initial price discovery
+     * and liquidity. This method handles the complete token creation workflow including blockchain
+     * submission, WebSocket monitoring, and confirmation waiting. Returns comprehensive launch
+     * details after on-chain confirmation.
+     *
+     * **Process Flow:**
+     * 1. Validates token data (name uniqueness, symbol format, etc.)
+     * 2. Submits launch transaction to GalaChain
+     * 3. Monitors transaction via WebSocket for real-time updates
+     * 4. Waits for blockchain confirmation
+     * 5. Returns complete token metadata including vault address
+     *
+     * **Important:** This is a write operation requiring wallet configuration.
+     *
+     * @category Token Creation
+     * @param data - Token launch configuration
+     * @param data.tokenName - Unique token name (3-20 lowercase alphanumeric, required)
+     * @param data.tokenSymbol - Token symbol (3-6 characters, required)
+     * @param data.tokenDescription - Token description (optional)
+     * @param data.tokenImage - Image URL or path (optional)
+     * @param data.preBuyQuantity - Initial token amount to purchase (optional, decimal format)
+     * @param data.maxSupply - Maximum token supply (optional, defaults to 10,000,000)
+     * @param data.bondingCurveFees - Bonding curve fee configuration (optional)
+     * @param data.privateKey - Private key override for this operation (optional)
+     * @returns Promise with complete token launch result including vault address, transaction ID, and metadata
+     * @throws {ValidationError} If wallet not configured or token data invalid
+     * @throws {WebSocketError} If transaction monitoring fails
+     * @throws {TransactionFailedError} If blockchain transaction fails
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.4-beta.0
      *
-     * Creates a new token with bonding curve and returns complete launch details
-     * after blockchain confirmation. This method now blocks until the transaction
-     * is confirmed, providing rich data about the created token.
+     * @example Basic token launch
+     * ```typescript
+     * import { Wallet } from 'ethers';
+     * import { LaunchpadSDK } from '@gala-chain/launchpad-sdk';
      *
-     * @param data Token launch data
-     * @returns Promise<TokenLaunchResult> Complete token launch result with vault address and metadata
-     * @since 3.0.0 - Now returns TokenLaunchResult instead of transaction ID
+     * const wallet = new Wallet(process.env.PRIVATE_KEY);
+     * const sdk = new LaunchpadSDK({ wallet });
      *
-     * @example
-     * ```typescript
      * const result = await sdk.launchToken({
      *   tokenName: 'mytoken',
      *   tokenSymbol: 'MTK',
-     *   tokenDescription: 'My amazing token',
-     *   tokenImage: 'https://example.com/image.png',
-     *   preBuyQuantity: '100'
+     *   tokenDescription: 'My amazing token for the community',
+     *   tokenImage: 'https://example.com/token.png'
      * });
      *
-     * console.log('Token created:', result.tokenName);
-     * console.log('Vault address:', result.vaultAddress);
-     * console.log('Creator:', result.creatorAddress);
+     * console.log('Token launched successfully!');
+     * console.log('Token:', result.tokenName);
+     * console.log('Symbol:', result.tokenSymbol);
+     * console.log('Vault:', result.vaultAddress);
      * console.log('Transaction:', result.transactionId);
+     * console.log('Creator:', result.creatorAddress);
+     * ```
+     *
+     * @example Launch with pre-buy and custom supply
+     * ```typescript
+     * const result = await sdk.launchToken({
+     *   tokenName: 'premium',
+     *   tokenSymbol: 'PREM',
+     *   tokenDescription: 'Premium features token',
+     *   tokenImage: 'https://example.com/premium.png',
+     *   preBuyQuantity: '1000', // Buy 1000 tokens immediately
+     *   maxSupply: '5000000' // Custom max supply of 5 million
+     * });
+     *
+     * console.log(`Pre-bought ${result.preBuyQuantity} tokens`);
+     * ```
+     *
+     * @example Launch with custom bonding curve fees
+     * ```typescript
+     * const result = await sdk.launchToken({
+     *   tokenName: 'custom',
+     *   tokenSymbol: 'CSTM',
+     *   tokenDescription: 'Custom fee structure',
+     *   bondingCurveFees: {
+     *     minFeePortion: '0.15', // 15% minimum fee
+     *     maxFeePortion: '0.45'  // 45% maximum fee
+     *   }
+     * });
+     * ```
+     *
+     * @example Error handling
+     * ```typescript
+     * try {
+     *   const result = await sdk.launchToken({
+     *     tokenName: 'newtoken',
+     *     tokenSymbol: 'NEW',
+     *     tokenDescription: 'New project token'
+     *   });
+     *   console.log('Success!', result.transactionId);
+     * } catch (error) {
+     *   if (error.code === 'WALLET_REQUIRED') {
+     *     console.error('Please configure wallet before launching token');
+     *   } else if (error.code === 'TOKEN_NAME_TAKEN') {
+     *     console.error('Token name already exists, choose another');
+     *   } else if (error.code === 'TRANSACTION_FAILED') {
+     *     console.error('Blockchain transaction failed:', error.message);
+     *   } else {
+     *     console.error('Launch failed:', error);
+     *   }
+     * }
      * ```
      */
     launchToken(data: LaunchTokenData): Promise<TokenLaunchResult>;
     /**
-     * Upload an image for a token
+     * Upload a token image to the launchpad server
+     *
+     * Uploads an image file from the local filesystem for a specific token. The image is stored on the
+     * launchpad server and can be displayed in the UI and API responses. Supports common image formats
+     * (PNG, JPG, GIF) and automatically handles image validation and optimization.
+     *
+     * **Important:** This method is only available in Node.js environments (not in browsers).
+     * Use for backend applications, build scripts, or CLI tools that manage token metadata.
+     *
+     * **Requires wallet configuration** for authentication. Use optional `privateKey` parameter
+     * to override the default wallet for this operation.
+     *
+     * @category Main SDK
+     * @param options - Image upload options with required tokenName and imagePath
+     * @param options.tokenName - Token name to upload image for (3-20 lowercase alphanumeric)
+     * @param options.imagePath - Absolute filesystem path to the image file (e.g., '/path/to/image.png')
+     * @param options.privateKey - Optional private key override for this operation (format: 0x + 64 hex characters)
+     * @returns Promise<string> URL where the image is hosted and can be accessed
+     * @throws {ValidationError} If tokenName is invalid, imagePath doesn't exist, or wallet not configured
+     * @throws {FileError} If image file cannot be read or is too large
+     * @throws {NetworkError} If upload request fails
+     * @since 4.0.4-beta.0
+     *
+     * @example Upload image from file
+     * ```typescript
+     * import path from 'path';
+     *
+     * const imageUrl = await sdk.uploadTokenImage({
+     *   tokenName: 'mytoken',
+     *   imagePath: path.join(process.cwd(), 'token-image.png')
+     * });
+     *
+     * console.log(`Image uploaded: ${imageUrl}`);
+     * ```
      *
-     * @param options Upload options with required tokenName
-     * @returns Promise<string>
+     * @example Upload with private key override
+     * ```typescript
+     * const imageUrl = await sdk.uploadTokenImage({
+     *   tokenName: 'mytoken',
+     *   imagePath: '/absolute/path/to/image.png',
+     *   privateKey: process.env.ALTERNATIVE_PRIVATE_KEY
+     * });
+     * ```
      */
     uploadTokenImage(options: UploadImageByTokenNameOptions): Promise<string>;
     /**
-     * Check if token name is available
+     * Check if a token name is available for use
      *
-     * @param tokenName Token name to check
-     * @returns Promise<boolean>
+     * Validates whether a token name is available to be registered on the platform.
+     * Token names must be unique across the entire launchpad. Use this before
+     * attempting to launch a token to prevent registration failures.
+     *
+     * @category Token Validation
+     * @param tokenName - Token name to check availability for (3-20 lowercase alphanumeric characters)
+     * @returns Promise resolving to true if name is available, false if already taken
+     * @throws {ValidationError} If tokenName format is invalid
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.4-beta.0
+     *
+     * @example Check name availability before launch
+     * ```typescript
+     * const isAvailable = await sdk.isTokenNameAvailable('mytoken');
+     * if (isAvailable) {
+     *   console.log('Name is available!');
+     *   await sdk.launchToken({ tokenName: 'mytoken', ... });
+     * } else {
+     *   console.log('Name already taken, choose another');
+     * }
+     * ```
      */
     isTokenNameAvailable(tokenName: string): Promise<boolean>;
     /**
-     * Check if token symbol is available
+     * Check if a token symbol is available for use
      *
-     * @param symbol Token symbol to check
-     * @returns Promise<boolean>
+     * Validates whether a token symbol is available to be registered on the platform.
+     * Token symbols must be unique across the entire launchpad. Use this before
+     * attempting to launch a token to prevent registration failures.
+     *
+     * @category Token Validation
+     * @param symbol - Token symbol to check availability for (typically 3-6 uppercase characters)
+     * @returns Promise resolving to true if symbol is available, false if already taken
+     * @throws {ValidationError} If symbol format is invalid
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.4-beta.0
+     *
+     * @example Check symbol availability before launch
+     * ```typescript
+     * const isAvailable = await sdk.isTokenSymbolAvailable('MTK');
+     * if (isAvailable) {
+     *   console.log('Symbol is available!');
+     *   await sdk.launchToken({ tokenSymbol: 'MTK', ... });
+     * } else {
+     *   console.log('Symbol already taken, choose another');
+     * }
+     * ```
      */
     isTokenSymbolAvailable(symbol: string): Promise<boolean>;
     /**
-     * Get user profile information
+     * Fetch user profile information by wallet address
+     *
+     * Retrieves public profile metadata for a specific wallet address, including name,
+     * profile image URL, and other user-provided information. Returns null if no profile
+     * has been created for the address.
+     *
+     * **Supports both address formats:**
+     * - Standard Ethereum format: `0x...` (64 hex characters after 0x prefix)
+     * - Backend format: `eth|...` (full GalaChain address format)
+     *
+     * @category Main SDK
+     * @param address - Optional wallet address in 0x... or eth|... format. Defaults to current SDK wallet address.
+     * @returns Promise<UserProfile | null> User profile data with name, image, and metadata, or null if no profile exists
+     * @throws {ValidationError} If wallet is not configured and no address is provided
+     * @throws {NetworkError} If launchpad API request fails
+     * @since 4.0.4-beta.0
      *
-     * @param address Optional wallet address (defaults to SDK wallet address)
-     * @returns Promise<any> User profile information
+     * @example Fetch current user's profile
+     * ```typescript
+     * const profile = await sdk.fetchProfile();
+     * if (profile) {
+     *   console.log(`User: ${profile.fullName}`);
+     *   console.log(`Image: ${profile.profileImage}`);
+     * } else {
+     *   console.log('No profile created yet');
+     * }
+     * ```
+     *
+     * @example Fetch profile for specific address
+     * ```typescript
+     * const profile = await sdk.fetchProfile('eth|742d35Cc6634C0532925a3b8D0Ea2c76f94C31C0');
+     * console.log(`Profile owner: ${profile?.fullName}`);
+     * ```
      */
     fetchProfile(address?: string): Promise<any>;
     /**
-     * Update user profile information
+     * Update user profile information for a wallet address
+     *
+     * Updates public profile metadata for a wallet, including display name and profile image.
+     * Only the wallet owner can update their own profile. Changes take effect immediately after
+     * successful submission to the launchpad server.
      *
-     * @param data Profile update data
+     * **Requires wallet configuration** for authentication. Use optional `privateKey` parameter
+     * to override the default wallet for this operation.
+     *
+     * @category Main SDK
+     * @param data - Profile update data with wallet address and fields to update
+     * @param data.address - Wallet address to update profile for (required, 0x... or eth|... format)
+     * @param data.fullName - User's full name (optional, max 100 characters)
+     * @param data.profileImage - Profile image URL (optional, can be empty string to clear)
+     * @param data.privateKey - Optional private key override for this operation (format: 0x + 64 hex characters)
      * @returns Promise<void> No return data - throws on failure
+     * @throws {ValidationError} If address format is invalid, wallet not configured, or user is not authorized
+     * @throws {NetworkError} If launchpad API request fails
+     * @since 4.0.4-beta.0
+     *
+     * @example Update profile name and image
+     * ```typescript
+     * await sdk.updateProfile({
+     *   address: sdk.getAddress(),
+     *   fullName: 'John Crypto',
+     *   profileImage: 'https://example.com/profile-pic.png'
+     * });
+     *
+     * console.log('Profile updated successfully!');
+     * ```
+     *
+     * @example Update only name
+     * ```typescript
+     * await sdk.updateProfile({
+     *   address: sdk.getAddress(),
+     *   fullName: 'Jane Blockchain'
+     * });
+     * ```
+     *
+     * @example Clear profile image
+     * ```typescript
+     * await sdk.updateProfile({
+     *   address: sdk.getAddress(),
+     *   profileImage: '' // Clear image
+     * });
+     * ```
      */
     updateProfile(data: UpdateProfileData): Promise<void>;
     /**
-     * Upload a profile image
+     * Upload a profile image for a user wallet
+     *
+     * Uploads an image file from the local filesystem as a user's profile picture. The image is stored on the
+     * launchpad server and displayed in user profiles and UI throughout the platform. Supports common image formats
+     * (PNG, JPG, GIF) and automatically handles image validation and optimization.
+     *
+     * **Important:** This method is only available in Node.js environments (not in browsers).
+     * Use for backend applications, build scripts, or CLI tools that manage user profiles.
+     *
+     * **Requires wallet configuration** for authentication. The wallet owner can only upload an image for their own profile.
+     * Use optional `privateKey` parameter to override the default wallet for this operation.
+     *
+     * @category Main SDK
+     * @param options - Profile image upload options
+     * @param options.imagePath - Absolute filesystem path to the image file (e.g., '/path/to/profile-pic.png')
+     * @param options.address - Optional wallet address for profile (0x... or eth|... format). Defaults to current SDK wallet address.
+     * @param options.privateKey - Optional private key override for this operation (format: 0x + 64 hex characters)
+     * @returns Promise<string> URL where the profile image is hosted and can be accessed
+     * @throws {ValidationError} If imagePath doesn't exist, wallet not configured, or user is not authorized
+     * @throws {FileError} If image file cannot be read or is too large
+     * @throws {NetworkError} If upload request fails
+     * @since 4.0.4-beta.0
+     *
+     * @example Upload profile image from file
+     * ```typescript
+     * import path from 'path';
+     *
+     * const imageUrl = await sdk.uploadProfileImage({
+     *   imagePath: path.join(process.cwd(), 'profile-picture.png')
+     * });
      *
-     * @param options Profile image upload options
-     * @returns Promise<string> Upload result with image URL
+     * console.log(`Profile image uploaded: ${imageUrl}`);
+     * ```
+     *
+     * @example Upload image for specific address
+     * ```typescript
+     * const imageUrl = await sdk.uploadProfileImage({
+     *   imagePath: '/absolute/path/to/profile.png',
+     *   address: 'eth|742d35Cc6634C0532925a3b8D0Ea2c76f94C31C0'
+     * });
+     * ```
+     *
+     * @example Upload with private key override
+     * ```typescript
+     * const imageUrl = await sdk.uploadProfileImage({
+     *   imagePath: '/absolute/path/to/profile.png',
+     *   privateKey: process.env.ALTERNATIVE_PRIVATE_KEY
+     * });
+     * ```
      */
     uploadProfileImage(options: UploadProfileImageOptions): Promise<string>;
     /**
@@ -2116,10 +2776,28 @@ export declare class LaunchpadSDK {
      */
     unlockToken(data: UnlockTokenData): Promise<string>;
     /**
-     * Resolve vault address for a token name
+     * Resolve token name to its GalaChain vault address
+     *
+     * Performs a lookup to find the blockchain vault address associated with a token name.
+     * Vault addresses are used internally for direct GalaChain API calls. This method is
+     * useful for caching, optimization, or low-level blockchain operations.
+     *
+     * @category Token Resolution
+     * @param tokenName - Token name to resolve (e.g., 'anime', 'mytoken')
+     * @returns Promise resolving to vault address string, or null if token not found
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.4-beta.0
      *
-     * @param tokenName Token name to resolve
-     * @returns Promise<string | null> Vault address or null if not found
+     * @example Resolve vault for direct API calls
+     * ```typescript
+     * const vaultAddress = await sdk.resolveVaultAddress('anime');
+     * if (vaultAddress) {
+     *   console.log(`Vault address: ${vaultAddress}`);
+     *   // Use for direct GalaChain API calls or caching
+     * } else {
+     *   console.log('Token not found');
+     * }
+     * ```
      */
     resolveVaultAddress(tokenName: string): Promise<string | null>;
     /**