@pioneer-platform/pioneer-sdk 8.15.14 → 8.15.16

package/src/utils/fee-reserves.ts

@@ -0,0 +1,162 @@
+/**
+ * Fee Reserve Utilities
+ *
+ * Provides conservative fee reserves for max amount calculations.
+ * These reserves ensure users don't send their entire balance and leave
+ * insufficient funds for transaction fees.
+ *
+ * Integration with fees module planned for dynamic reserve calculation.
+ */
+
+const TAG = ' | Pioneer-sdk | fee-reserves | ';
+
+/**
+ * Fee reserve configuration for each network
+ * Values are conservative estimates in native currency units
+ */
+const FEE_RESERVE_MAP: Record<string, number> = {
+  // Bitcoin (BTC)
+  'bip122:000000000019d6689c085ae165831e93/slip44:0': 0.00005, // ~$3-5 at current prices
+
+  // Ethereum (ETH)
+  'eip155:1/slip44:60': 0.001, // ~$2-4 for ERC20 transfer at 20 gwei
+
+  // THORChain (RUNE)
+  'cosmos:thorchain-mainnet-v1/slip44:931': 0.02, // Network standard fee
+
+  // Dogecoin (DOGE)
+  'bip122:00000000001a91e3dace36e2be3bf030/slip44:3': 1, // ~$0.10-0.20, DOGE has cheap fees
+
+  // Dash (DASH)
+  'bip122:000007d91d1254d60e2dd1ae58038307/slip44:5': 0.001, // ~$0.03-0.05
+
+  // Bitcoin Cash (BCH)
+  'bip122:000000000000000000651ef99cb9fcbe/slip44:145': 0.0005, // ~$0.20-0.40
+
+  // Litecoin (LTC)
+  'bip122:12a765e31ffd4059bada1e25190f6e98/slip44:2': 0.001, // ~$0.10-0.20
+
+  // DigiByte (DGB)
+  'bip122:4da631f2ac1bed857bd968c67c913978/slip44:20': 0.1, // Very cheap fees
+
+  // Cosmos (ATOM)
+  'cosmos:cosmoshub-4/slip44:118': 0.005, // Network standard fee
+
+  // Osmosis (OSMO)
+  'cosmos:osmosis-1/slip44:118': 0.035, // Network standard fee
+
+  // Maya (CACAO)
+  'cosmos:mayachain-mainnet-v1/slip44:931': 0.5, // Network standard fee
+
+  // BNB Smart Chain (BNB)
+  'eip155:56/slip44:60': 0.001, // ~$0.50-1.00 for BEP20 transfer
+
+  // Polygon (MATIC)
+  'eip155:137/slip44:60': 0.01, // ~$0.01-0.02, very cheap
+
+  // Avalanche (AVAX)
+  'eip155:43114/slip44:60': 0.01, // ~$0.30-0.60
+
+  // Optimism (OP/ETH)
+  'eip155:10/slip44:60': 0.0001, // L2, very cheap
+
+  // Base (ETH)
+  'eip155:8453/slip44:60': 0.0001, // L2, very cheap
+
+  // Arbitrum (ETH)
+  'eip155:42161/slip44:60': 0.0001, // L2, very cheap
+
+  // Ripple (XRP)
+  'ripple:4109c6f2045fc7eff4cde8f9905d19c2/slip44:144': 0.00001, // Fixed network fee
+};
+
+/**
+ * Default fee reserve for unknown networks
+ * Uses a conservative estimate suitable for most chains
+ */
+const DEFAULT_FEE_RESERVE = 0.001;
+
+/**
+ * Get fee reserve for a given network (CAIP identifier)
+ *
+ * @param caip - CAIP identifier (e.g., 'bip122:000000000019d6689c085ae165831e93/slip44:0')
+ * @returns Fee reserve amount in native currency units
+ *
+ * @example
+ * ```typescript
+ * const reserve = getFeeReserve('eip155:1/slip44:60'); // 0.001 ETH
+ * const maxSendable = balance - reserve;
+ * ```
+ */
+export function getFeeReserve(caip: string): number {
+  // Direct lookup
+  if (FEE_RESERVE_MAP[caip]) {
+    return FEE_RESERVE_MAP[caip];
+  }
+
+  // EVM wildcard matching (all EVM chains not explicitly defined)
+  if (caip.startsWith('eip155:') && caip.includes('/slip44:60')) {
+    // Use Ethereum's reserve as default for all EVM chains
+    return FEE_RESERVE_MAP['eip155:1/slip44:60'] || 0.001;
+  }
+
+  // Cosmos SDK chains
+  if (caip.startsWith('cosmos:')) {
+    // Conservative default for Cosmos chains
+    return 0.01;
+  }
+
+  // UTXO chains
+  if (caip.startsWith('bip122:')) {
+    // Conservative default for UTXO chains
+    return 0.0001;
+  }
+
+  // Unknown network - use conservative default
+  console.warn(TAG, `No fee reserve defined for ${caip}, using default: ${DEFAULT_FEE_RESERVE}`);
+  return DEFAULT_FEE_RESERVE;
+}
+
+/**
+ * Calculate max sendable amount for a given balance
+ * Subtracts conservative fee reserve to ensure transaction can be completed
+ *
+ * @param balance - Total balance in native units
+ * @param caip - CAIP identifier for the network
+ * @returns Maximum amount that can be safely sent
+ *
+ * @example
+ * ```typescript
+ * const maxSendable = getMaxSendableAmount(1.5, 'eip155:1/slip44:60');
+ * // Returns 1.499 (1.5 - 0.001 ETH reserve)
+ * ```
+ */
+export function getMaxSendableAmount(balance: number, caip: string): number {
+  const reserve = getFeeReserve(caip);
+  const maxAmount = Math.max(0, balance - reserve);
+
+  console.log(TAG, `Max sendable for ${caip}: ${maxAmount} (balance: ${balance}, reserve: ${reserve})`);
+
+  return maxAmount;
+}
+
+/**
+ * Check if balance is sufficient for a transaction
+ *
+ * @param balance - Available balance
+ * @param amount - Amount to send
+ * @param caip - CAIP identifier
+ * @returns true if balance covers amount + fees
+ */
+export function hasSufficientBalance(balance: number, amount: number, caip: string): boolean {
+  const reserve = getFeeReserve(caip);
+  return balance >= (amount + reserve);
+}
+
+/**
+ * Get fee reserve configuration for display/debugging
+ * @returns Complete fee reserve map
+ */
+export function getFeeReserveMap(): Readonly<Record<string, number>> {
+  return FEE_RESERVE_MAP;
+}

package/src/utils/logger.ts

@@ -0,0 +1,21 @@
+// Simple client-side logger for Pioneer SDK
+// Replaces server-side loggerdog dependency
+
+const DEBUG = process.env.DEBUG === 'true' || typeof window !== 'undefined' && (window as any).DEBUG;
+
+export const logger = {
+  info: (tag: string, ...args: any[]) => {
+    console.log(`[INFO] ${tag}`, ...args);
+  },
+  debug: (tag: string, ...args: any[]) => {
+    if (DEBUG) {
+      console.log(`[DEBUG] ${tag}`, ...args);
+    }
+  },
+  warn: (tag: string, ...args: any[]) => {
+    console.warn(`[WARN] ${tag}`, ...args);
+  },
+  error: (tag: string, ...args: any[]) => {
+    console.error(`[ERROR] ${tag}`, ...args);
+  },
+};

package/src/utils/network-helpers.ts

@@ -0,0 +1,85 @@
+// Network matching utilities
+
+/**
+ * Check if item (path or pubkey) matches network with EVM wildcard support
+ */
+export function matchesNetwork(item: any, networkId: string): boolean {
+  if (!item.networks || !Array.isArray(item.networks)) return false;
+  if (item.networks.includes(networkId)) return true;
+  if (networkId.startsWith('eip155:') && item.networks.includes('eip155:*')) return true;
+  return false;
+}
+
+/**
+ * Normalize network ID for EVM chains (converts specific chain to wildcard)
+ */
+export function normalizeNetworkId(networkId: string): string {
+  return networkId.includes('eip155:') ? 'eip155:*' : networkId;
+}
+
+/**
+ * Find pubkeys that match a specific network
+ */
+export function findPubkeysForNetwork(
+  pubkeys: any[],
+  networkId: string,
+  paths: any[],
+  tag: string = ''
+): any[] {
+  const isEip155 = networkId.includes('eip155');
+
+  // Primary query: find pubkeys with matching networks field
+  let matchingPubkeys = pubkeys.filter((pubkey) =>
+    pubkey.networks?.some((network: string) =>
+      isEip155 ? network.startsWith('eip155:') : network === networkId
+    )
+  );
+
+  // Fallback: if no pubkeys found, try path matching
+  if (matchingPubkeys.length === 0) {
+    if (tag) console.warn(tag, `⚠️ No pubkeys found for ${networkId}, attempting path fallback`);
+
+    const pathsForNetwork = paths.filter(p =>
+      p.networks?.includes(networkId) ||
+      (isEip155 && p.networks?.includes('eip155:*'))
+    );
+
+    for (const path of pathsForNetwork) {
+      const matchingPubkey = pubkeys.find(pk =>
+        JSON.stringify(pk.addressNList) === JSON.stringify(path.addressNList)
+      );
+      if (matchingPubkey) {
+        if (tag) console.warn(tag, `✓ Found via path: ${matchingPubkey.note || matchingPubkey.pubkey.slice(0, 10)}`);
+        matchingPubkeys.push(matchingPubkey);
+      }
+    }
+
+    if (tag && matchingPubkeys.length > 0) {
+      console.warn(tag, `✅ Fallback found ${matchingPubkeys.length} pubkeys for ${networkId}`);
+    } else if (tag) {
+      console.error(tag, `❌ No pubkeys found for ${networkId}`);
+    }
+  }
+
+  return matchingPubkeys;
+}
+
+/**
+ * Validate pubkeys have required networks field
+ */
+export function validatePubkeysNetworks(pubkeys: any[], tag: string = ''): {
+  valid: any[];
+  invalid: any[];
+} {
+  const valid = pubkeys.filter(p => p.networks && Array.isArray(p.networks));
+  const invalid = pubkeys.filter(p => !p.networks || !Array.isArray(p.networks));
+
+  if (tag && invalid.length > 0) {
+    console.warn(tag, `⚠️ ${invalid.length} pubkeys missing networks field`);
+    invalid.forEach(pk => {
+      console.warn(tag, `  - ${pk.note || pk.pubkey.slice(0, 10)}: networks=${pk.networks}`);
+    });
+  }
+
+  return { valid, invalid };
+}

package/src/utils/path-discovery.ts

@@ -0,0 +1,67 @@
+// Path discovery utilities for blockchain synchronization
+
+import { getPaths } from '@pioneer-platform/pioneer-coins';
+import { matchesNetwork, normalizeNetworkId } from './network-helpers.js';
+import { logger as log } from './logger.js';
+
+/**
+ * Ensure paths exist for all blockchains
+ * Discovers and adds missing paths automatically
+ */
+export async function ensurePathsForBlockchains(
+  blockchains: string[],
+  currentPaths: any[],
+  tag: string
+): Promise<any[]> {
+  let allPaths = [...currentPaths];
+
+  for (const blockchain of blockchains) {
+    const networkId = normalizeNetworkId(blockchain);
+    const existingPaths = allPaths.filter(path => matchesNetwork(path, networkId));
+
+    if (existingPaths.length === 0) {
+      log.info(tag, `Discovering paths for ${networkId}...`);
+      const newPaths = getPaths([networkId]);
+
+      if (!newPaths || newPaths.length === 0) {
+        throw new Error(
+          `Path discovery failed for ${networkId}. ` +
+          `Available blockchains: ${blockchains.join(', ')}`
+        );
+      }
+
+      log.debug(tag, `Added ${newPaths.length} paths for ${networkId}`);
+      allPaths = allPaths.concat(newPaths);
+    }
+  }
+
+  return allPaths;
+}
+
+/**
+ * Validate that paths exist for a blockchain
+ * Throws descriptive error if validation fails
+ */
+export function validatePathsForBlockchain(
+  paths: any[],
+  blockchain: string,
+  tag: string = ''
+): void {
+  const networkId = normalizeNetworkId(blockchain);
+  const pathsForChain = paths.filter(path => matchesNetwork(path, networkId));
+
+  if (pathsForChain.length === 0) {
+    const availableNetworks = [
+      ...new Set(paths.flatMap(p => p.networks || []))
+    ];
+
+    throw new Error(
+      `No paths found for blockchain ${networkId}. ` +
+      `Available paths for: ${availableNetworks.join(', ')}`
+    );
+  }
+
+  if (tag) {
+    log.debug(tag, `Validated ${pathsForChain.length} paths for ${networkId}`);
+  }
+}

package/src/utils/portfolio-helpers.ts

@@ -0,0 +1,209 @@
+// Portfolio validation and helper utilities
+
+import { logger as log } from './logger.js';
+const TAG = ' | portfolio-helpers | ';
+
+export function isCacheDataValid(portfolioData: any): boolean {
+  // Check if networks data is reasonable (should be < 50 networks, not thousands)
+  if (!portfolioData.networks || !Array.isArray(portfolioData.networks)) {
+    console.warn('[CACHE VALIDATION] Networks is not an array');
+    return false;
+  }
+
+  if (portfolioData.networks.length > 50) {
+    console.error(
+      `[CACHE VALIDATION] CORRUPTED: ${portfolioData.networks.length} networks (should be < 50)`,
+    );
+    return false;
+  }
+
+  // Check if at least some networks have required fields
+  const validNetworks = portfolioData.networks.filter(
+    (n: any) => n.networkId && n.totalValueUsd !== undefined && n.gasAssetSymbol,
+  );
+
+  if (validNetworks.length === 0 && portfolioData.networks.length > 0) {
+    console.error('[CACHE VALIDATION] CORRUPTED: No networks have required fields');
+    return false;
+  }
+
+  console.log(
+    `[CACHE VALIDATION] Found ${portfolioData.networks.length} networks, ${validNetworks.length} valid`,
+  );
+  return true;
+}
+
+/**
+ * Fetch fresh market price for an asset
+ */
+export async function fetchMarketPrice(pioneer: any, caip: string): Promise<number> {
+  const tag = TAG + ' | fetchMarketPrice | ';
+  try {
+    // Validate CAIP before calling API
+    if (!caip || typeof caip !== 'string' || !caip.includes(':')) {
+      log.warn(tag, 'Invalid or missing CAIP, skipping market price fetch:', caip);
+      return 0;
+    }
+
+    log.debug(tag, 'Fetching fresh market price for:', caip);
+    const marketData = await pioneer.GetMarketInfo([caip]);
+    log.debug(tag, 'Market data response:', marketData);
+
+    if (marketData && marketData.data && marketData.data.length > 0) {
+      const price = marketData.data[0];
+      log.debug(tag, '✅ Fresh market price:', price);
+      return price;
+    } else {
+      log.warn(tag, 'No market data returned for:', caip);
+      return 0;
+    }
+  } catch (marketError) {
+    log.error(tag, 'Error fetching market price:', marketError);
+    return 0;
+  }
+}
+
+/**
+ * Extract price from balance entries
+ */
+export function extractPriceFromBalances(balances: any[]): number {
+  const tag = TAG + ' | extractPriceFromBalances | ';
+  if (balances.length === 0) return 0;
+
+  // Use price from first balance entry (all should have same price)
+  let priceValue = balances[0].priceUsd || balances[0].price;
+
+  // If no price but we have valueUsd and balance, calculate the price
+  if ((!priceValue || priceValue === 0) && balances[0].valueUsd && balances[0].balance) {
+    const balance = parseFloat(balances[0].balance);
+    const valueUsd = parseFloat(balances[0].valueUsd);
+    if (balance > 0 && valueUsd > 0) {
+      priceValue = valueUsd / balance;
+      log.debug(tag, 'Calculated priceUsd from valueUsd/balance:', priceValue);
+    }
+  }
+
+  return priceValue || 0;
+}
+
+/**
+ * Aggregate balances for an asset (critical for UTXO chains with multiple xpubs)
+ */
+export function aggregateBalances(balances: any[], caip: string): {
+  totalBalance: number;
+  totalValueUsd: number;
+} {
+  const tag = TAG + ' | aggregateBalances | ';
+  let totalBalance = 0;
+  let totalValueUsd = 0;
+
+  log.debug(tag, `Aggregating ${balances.length} balance entries for ${caip}`);
+  for (const balanceEntry of balances) {
+    const balance = parseFloat(balanceEntry.balance) || 0;
+    const valueUsd = parseFloat(balanceEntry.valueUsd) || 0;
+    totalBalance += balance;
+    totalValueUsd += valueUsd;
+    log.debug(tag, `  Balance entry: ${balance} (${valueUsd} USD)`);
+  }
+
+  log.debug(tag, `Aggregated balance: ${totalBalance} (${totalValueUsd.toFixed(2)} USD)`);
+  return { totalBalance, totalValueUsd };
+}
+
+/**
+ * Update balances with fresh price data
+ */
+export function updateBalancesWithPrice(balances: any[], freshPriceUsd: number): void {
+  const tag = TAG + ' | updateBalancesWithPrice | ';
+  for (const balance of balances) {
+    balance.price = freshPriceUsd;
+    balance.priceUsd = freshPriceUsd;
+    // Recalculate valueUsd with fresh price
+    const balanceAmount = parseFloat(balance.balance || 0);
+    balance.valueUsd = (balanceAmount * freshPriceUsd).toString();
+  }
+  log.debug(tag, 'Updated all balances with fresh price data');
+}
+
+export function buildDashboardFromPortfolioData(portfolioData: any) {
+  const cacheAge = portfolioData.lastUpdated
+    ? Math.floor((Date.now() - portfolioData.lastUpdated) / 1000)
+    : 0;
+
+  return {
+    totalValueUsd: portfolioData.totalValueUsd,
+    pairedDevices: portfolioData.pairedDevices,
+    devices: portfolioData.devices || [],
+    networks: portfolioData.networks || [],
+    assets: portfolioData.assets || [],
+    statistics: portfolioData.statistics || {},
+    cached: portfolioData.cached,
+    lastUpdated: portfolioData.lastUpdated,
+    cacheAge,
+    networkPercentages:
+      portfolioData.networks?.map((network: any) => ({
+        networkId: network.network_id || network.networkId,
+        percentage: network.percentage || 0,
+      })) || [],
+  };
+}
+
+/**
+ * Build asset query from pubkeys and CAIP
+ */
+export function buildAssetQuery(pubkeys: any[], caip: string): Array<{ caip: string; pubkey: string }> {
+  return pubkeys.map(pubkey => ({ caip, pubkey: pubkey.pubkey }));
+}
+
+/**
+ * Log query diagnostics (grouped by CAIP)
+ */
+export function logQueryDiagnostics(
+  assetQuery: Array<{ caip: string; pubkey: string }>,
+  tag: string = ''
+): void {
+  const caipCounts = new Map<string, number>();
+  for (const query of assetQuery) {
+    caipCounts.set(query.caip, (caipCounts.get(query.caip) || 0) + 1);
+  }
+
+  if (tag) {
+    console.log(tag, 'Built assetQuery with', assetQuery.length, 'entries');
+    console.log(tag, 'Sample queries:', assetQuery.slice(0, 5));
+    console.log(tag, 'Queries by chain:');
+    caipCounts.forEach((count, caip) => {
+      console.log(`   - ${caip}: ${count} queries`);
+    });
+  }
+}
+
+/**
+ * Enrich balances with asset metadata
+ */
+export function enrichBalancesWithAssetInfo(
+  balances: any[],
+  assetsMap: Map<string, any>,
+  caipToNetworkId: (caip: string) => string
+): any[] {
+  const tag = TAG + ' | enrichBalancesWithAssetInfo | ';
+
+  for (const balance of balances) {
+    const assetInfo = assetsMap.get(balance.caip.toLowerCase()) || assetsMap.get(balance.caip);
+
+    if (!assetInfo) {
+      throw new Error(`Missing AssetInfo for ${balance.caip}`);
+    }
+
+    Object.assign(balance, assetInfo, {
+      type: balance.type || assetInfo.type,
+      isNative: balance.isNative ?? assetInfo.isNative,
+      networkId: caipToNetworkId(balance.caip),
+      icon: assetInfo.icon || 'https://pioneers.dev/coins/etherum.png',
+      identifier: `${balance.caip}:${balance.pubkey}`,
+      updated: Date.now(),
+      color: assetInfo.color,
+    });
+  }
+
+  return balances;
+}

package/src/utils/pubkey-management.ts

@@ -0,0 +1,124 @@
+// Pubkey management utilities
+
+export function getPubkeyKey(pubkey: any): string {
+  return `${pubkey.pubkey}_${pubkey.pathMaster}`;
+}
+
+export function deduplicatePubkeys(pubkeys: any[]): any[] {
+  const seen = new Set<string>();
+  return pubkeys.filter((pubkey) => {
+    const key = getPubkeyKey(pubkey);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function validatePubkey(pubkey: any): boolean {
+  return !!(pubkey.pubkey && pubkey.pathMaster);
+}
+
+/**
+ * Find pubkeys that support a given network
+ * Handles EVM wildcard matching (eip155:*)
+ */
+export function findPubkeysForNetwork(pubkeys: any[], networkId: string): any[] {
+  return pubkeys.filter((p: any) => {
+    if (!p.networks || !Array.isArray(p.networks)) return false;
+
+    // Exact match
+    if (p.networks.includes(networkId)) return true;
+
+    // For EVM chains, check if pubkey has eip155:* wildcard
+    if (networkId.startsWith('eip155:') && p.networks.includes('eip155:*')) {
+      return true;
+    }
+
+    return false;
+  });
+}
+
+/**
+ * Find a single pubkey for a network
+ */
+export function findPubkeyForNetwork(pubkeys: any[], networkId: string): any | undefined {
+  return pubkeys.find((p: any) => {
+    if (!p.networks || !Array.isArray(p.networks)) return false;
+
+    // Exact match
+    if (p.networks.includes(networkId)) return true;
+
+    // For EVM chains, check if pubkey has eip155:* wildcard
+    if (networkId.startsWith('eip155:') && p.networks.includes('eip155:*')) return true;
+
+    return false;
+  });
+}
+
+/**
+ * Validate that pubkeys exist for a given network
+ * Throws descriptive errors if validation fails
+ */
+export function validatePubkeysForNetwork(
+  pubkeys: any[],
+  networkId: string,
+  caip: string,
+): void {
+  if (!pubkeys || pubkeys.length === 0) {
+    throw new Error(
+      `Cannot set asset context for ${caip} - no pubkeys loaded. Please initialize wallet first.`,
+    );
+  }
+
+  const pubkeysForNetwork = findPubkeysForNetwork(pubkeys, networkId);
+
+  if (pubkeysForNetwork.length === 0) {
+    const availableNetworks = [...new Set(pubkeys.flatMap((p: any) => p.networks || []))];
+    throw new Error(
+      `Cannot set asset context for ${caip} - no address/xpub found for network ${networkId}. Available networks: ${availableNetworks.join(', ')}`,
+    );
+  }
+
+  // For UTXO chains, verify we have xpub
+  const isUtxoChain = networkId.startsWith('bip122:');
+  if (isUtxoChain) {
+    const xpubFound = pubkeysForNetwork.some((p: any) => p.type === 'xpub' && p.pubkey);
+    if (!xpubFound) {
+      throw new Error(
+        `Cannot set asset context for UTXO chain ${caip} - xpub required but not found`,
+      );
+    }
+  }
+
+  // Verify we have a valid address or pubkey
+  const hasValidAddress = pubkeysForNetwork.some((p: any) => p.address || p.master || p.pubkey);
+  if (!hasValidAddress) {
+    throw new Error(`Cannot set asset context for ${caip} - no valid address found in pubkeys`);
+  }
+}
+
+/**
+ * Filter pubkeys for a specific asset
+ * Used to attach relevant pubkeys to asset context
+ */
+export function filterPubkeysForAsset(
+  pubkeys: any[],
+  caip: string,
+  caipToNetworkId: (caip: string) => string,
+): any[] {
+  const networkId = caipToNetworkId(caip);
+
+  return pubkeys.filter((p) => {
+    if (!p.networks || !Array.isArray(p.networks)) return false;
+
+    // Exact match
+    if (p.networks.includes(networkId)) return true;
+
+    // For EVM chains, check if pubkey has eip155:* wildcard
+    if (networkId.includes('eip155') && p.networks.some((n) => n.startsWith('eip155'))) {
+      return true;
+    }
+
+    return false;
+  });
+}