blue-js-sdk 2.0.0

package/preflight.js

@@ -0,0 +1,352 @@
+/**
+ * Sentinel SDK — Pre-Flight System Check
+ *
+ * Run before any connection attempt. Detects:
+ * - Missing binaries (WireGuard, V2Ray) with install instructions
+ * - Admin/root permissions
+ * - Orphaned tunnels from previous crashes
+ * - Orphaned V2Ray processes
+ * - Conflicting VPN software
+ * - Port conflicts
+ *
+ * Returns actionable steps — not just pass/fail.
+ */
+
+import { execSync, execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import { WG_EXE, WG_QUICK, WG_AVAILABLE, IS_ADMIN, emergencyCleanupSync } from './wireguard.js';
+
+// ─── Orphaned Tunnel Detection ──────────────────────────────────────────────
+
+/**
+ * Check for orphaned WireGuard tunnels (left over from crashes).
+ * @returns {{ found: boolean, tunnels: string[], cleaned: boolean }}
+ */
+export function checkOrphanedTunnels() {
+  const result = { found: false, tunnels: [], cleaned: false };
+
+  if (process.platform === 'win32') {
+    try {
+      const services = execSync('sc query type= service state= all', { encoding: 'utf8', timeout: 5000, stdio: 'pipe' });
+      const matches = services.match(/WireGuardTunnel\$wgsent\S*/g) || [];
+      if (matches.length > 0) {
+        result.found = true;
+        result.tunnels = matches.map(s => s.replace('WireGuardTunnel$', ''));
+      }
+    } catch { /* sc query may fail */ }
+  } else {
+    // Linux/macOS: check for wgsent* interfaces
+    try {
+      const ifaces = execSync('ip link show 2>/dev/null || ifconfig 2>/dev/null', { encoding: 'utf8', timeout: 3000, stdio: 'pipe' });
+      const matches = ifaces.match(/wgsent\d+/g) || [];
+      if (matches.length > 0) {
+        result.found = true;
+        result.tunnels = [...new Set(matches)];
+      }
+    } catch { /* ip/ifconfig may not exist */ }
+  }
+
+  return result;
+}
+
+/**
+ * Clean up orphaned WireGuard tunnels.
+ * @returns {{ cleaned: number, errors: string[] }}
+ */
+export function cleanOrphanedTunnels() {
+  const before = checkOrphanedTunnels();
+  if (!before.found) return { cleaned: 0, errors: [] };
+
+  emergencyCleanupSync();
+
+  const after = checkOrphanedTunnels();
+  const cleaned = before.tunnels.length - after.tunnels.length;
+  const errors = after.found
+    ? [`${after.tunnels.length} tunnel(s) could not be removed: ${after.tunnels.join(', ')}`]
+    : [];
+
+  return { cleaned, errors };
+}
+
+// ─── V2Ray Orphan Detection ─────────────────────────────────────────────────
+
+/**
+ * Check for orphaned V2Ray processes.
+ * @returns {{ found: boolean, pids: number[] }}
+ */
+export function checkOrphanedV2Ray() {
+  const result = { found: false, pids: [] };
+
+  try {
+    if (process.platform === 'win32') {
+      const out = execSync('tasklist /FI "IMAGENAME eq v2ray.exe" /NH /FO CSV', { encoding: 'utf8', timeout: 5000, stdio: 'pipe' });
+      const lines = out.split('\n').filter(l => l.includes('v2ray.exe'));
+      for (const line of lines) {
+        const match = line.match(/"v2ray\.exe","(\d+)"/);
+        if (match) result.pids.push(parseInt(match[1], 10));
+      }
+    } else {
+      const out = execSync('pgrep -x v2ray 2>/dev/null || true', { encoding: 'utf8', timeout: 3000, stdio: 'pipe' });
+      for (const line of out.trim().split('\n')) {
+        const pid = parseInt(line, 10);
+        if (!isNaN(pid)) result.pids.push(pid);
+      }
+    }
+  } catch { /* process listing may fail */ }
+
+  result.found = result.pids.length > 0;
+  return result;
+}
+
+// ─── Conflicting VPN Detection ──────────────────────────────────────────────
+
+/** Known VPN processes that conflict with WireGuard routing. */
+const KNOWN_VPN_PROCESSES = [
+  { name: 'NordVPN', process: 'nordvpn', service: 'nordvpn-service' },
+  { name: 'ExpressVPN', process: 'expressvpn', service: 'ExpressVpnService' },
+  { name: 'Surfshark', process: 'surfshark', service: 'Surfshark' },
+  { name: 'ProtonVPN', process: 'protonvpn', service: 'ProtonVPN Service' },
+  { name: 'Mullvad', process: 'mullvad-vpn', service: 'mullvad' },
+  { name: 'CyberGhost', process: 'cyberghost', service: 'CyberGhostVPN' },
+  { name: 'PIA', process: 'pia-client', service: 'PrivateInternetAccessService' },
+  { name: 'Windscribe', process: 'windscribe', service: 'WindscribeService' },
+  { name: 'TunnelBear', process: 'tunnelbear', service: 'TunnelBearService' },
+  { name: 'OpenVPN', process: 'openvpn', service: 'OpenVPNService' },
+];
+
+/**
+ * Check for running VPN software that may conflict.
+ * @returns {{ conflicts: Array<{ name: string, running: boolean }> }}
+ */
+export function checkVpnConflicts() {
+  const conflicts = [];
+
+  if (process.platform === 'win32') {
+    try {
+      const tasks = execSync('tasklist /NH /FO CSV', { encoding: 'utf8', timeout: 5000, stdio: 'pipe' }).toLowerCase();
+      for (const vpn of KNOWN_VPN_PROCESSES) {
+        if (tasks.includes(vpn.process.toLowerCase())) {
+          conflicts.push({ name: vpn.name, running: true });
+        }
+      }
+    } catch { /* tasklist may fail */ }
+  } else {
+    try {
+      const ps = execSync('ps aux 2>/dev/null || ps -ef', { encoding: 'utf8', timeout: 3000, stdio: 'pipe' }).toLowerCase();
+      for (const vpn of KNOWN_VPN_PROCESSES) {
+        if (ps.includes(vpn.process.toLowerCase())) {
+          conflicts.push({ name: vpn.name, running: true });
+        }
+      }
+    } catch { /* ps may fail */ }
+  }
+
+  return { conflicts };
+}
+
+// ─── Port Conflict Detection ────────────────────────────────────────────────
+
+/**
+ * Check if common V2Ray SOCKS5 ports are in use.
+ * @returns {{ conflicts: Array<{ port: number, inUse: boolean }> }}
+ */
+export function checkPortConflicts() {
+  const portsToCheck = [10808, 10809, 10810]; // common V2Ray SOCKS ports
+  const conflicts = [];
+
+  try {
+    if (process.platform === 'win32') {
+      const netstat = execSync('netstat -ano', { encoding: 'utf8', timeout: 5000, stdio: 'pipe' });
+      for (const port of portsToCheck) {
+        if (netstat.includes(`:${port} `)) {
+          conflicts.push({ port, inUse: true });
+        }
+      }
+    } else {
+      for (const port of portsToCheck) {
+        try {
+          execSync(`lsof -i :${port} -t 2>/dev/null`, { encoding: 'utf8', timeout: 3000, stdio: 'pipe' });
+          conflicts.push({ port, inUse: true });
+        } catch { /* port free */ }
+      }
+    }
+  } catch { /* netstat may fail */ }
+
+  return { conflicts };
+}
+
+// ─── Main Preflight Check ───────────────────────────────────────────────────
+
+/**
+ * Complete pre-flight system check. Run at app startup before any connection.
+ *
+ * Returns a structured report with:
+ * - ok: boolean (true if everything is ready to connect)
+ * - issues: array of { severity, message, action, autoFix }
+ * - Each issue has a human-readable message and an actionable fix
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.autoClean=false] - Auto-clean orphaned tunnels/processes
+ * @param {string} [opts.v2rayExePath] - Explicit V2Ray path
+ * @returns {object} Pre-flight report
+ */
+export function preflight(opts = {}) {
+  const issues = [];
+
+  // ── 1. WireGuard ──
+  if (!WG_AVAILABLE) {
+    issues.push({
+      severity: 'warning',
+      component: 'wireguard',
+      message: 'WireGuard is not installed.',
+      detail: 'WireGuard nodes (faster, more reliable) will not work. V2Ray nodes still work without it.',
+      action: process.platform === 'win32'
+        ? 'Download and install from: https://download.wireguard.com/windows-client/wireguard-installer.exe'
+        : process.platform === 'darwin'
+          ? 'Run: brew install wireguard-tools'
+          : 'Run: sudo apt install wireguard (Ubuntu/Debian) or sudo dnf install wireguard-tools (Fedora)',
+      autoFix: false,
+    });
+  } else if (!IS_ADMIN) {
+    issues.push({
+      severity: 'warning',
+      component: 'wireguard',
+      message: 'WireGuard requires administrator privileges.',
+      detail: 'WireGuard is installed but the app is not running as admin. WireGuard nodes will fail. V2Ray nodes still work.',
+      action: process.platform === 'win32'
+        ? 'Right-click your app → "Run as administrator", or add a manifest with requireAdministrator.'
+        : 'Run with: sudo node your-app.js',
+      autoFix: false,
+    });
+  }
+
+  // ── 2. V2Ray ──
+  const findV2Ray = () => {
+    const paths = [
+      opts.v2rayExePath,
+      process.env.V2RAY_PATH,
+      './bin/v2ray.exe', './bin/v2ray',
+      '../bin/v2ray.exe', '../bin/v2ray',
+    ].filter(Boolean);
+    for (const p of paths) { if (existsSync(p)) return p; }
+    try {
+      const cmd = process.platform === 'win32' ? 'where v2ray.exe' : 'which v2ray';
+      return execSync(cmd, { encoding: 'utf8', stdio: 'pipe', timeout: 3000 }).trim().split('\n')[0];
+    } catch { return null; }
+  };
+
+  const v2path = findV2Ray();
+  if (!v2path) {
+    issues.push({
+      severity: 'warning',
+      component: 'v2ray',
+      message: 'V2Ray binary not found.',
+      detail: 'V2Ray nodes will not work. WireGuard nodes still work without it.',
+      action: 'Run: node js-sdk/setup.js (auto-downloads V2Ray 5.2.1), or place v2ray.exe + geoip.dat + geosite.dat in a bin/ folder.',
+      autoFix: false,
+    });
+  }
+
+  // ── 3. Neither installed ──
+  if (!WG_AVAILABLE && !v2path) {
+    // Upgrade to error — no protocol available at all
+    issues.push({
+      severity: 'error',
+      component: 'protocols',
+      message: 'No VPN protocol available. Cannot connect to any node.',
+      detail: 'Neither WireGuard nor V2Ray is installed. You need at least one.',
+      action: 'Install WireGuard (recommended) and/or run: node js-sdk/setup.js to download V2Ray.',
+      autoFix: false,
+    });
+  }
+
+  // ── 4. Orphaned WireGuard tunnels ──
+  const orphanedWg = checkOrphanedTunnels();
+  if (orphanedWg.found) {
+    if (opts.autoClean) {
+      const cleaned = cleanOrphanedTunnels();
+      if (cleaned.errors.length > 0) {
+        issues.push({
+          severity: 'warning',
+          component: 'wireguard',
+          message: `Found ${orphanedWg.tunnels.length} orphaned tunnel(s), cleaned ${cleaned.cleaned}. ${cleaned.errors[0]}`,
+          detail: 'Stale tunnels from a previous crash. Some could not be removed automatically.',
+          action: process.platform === 'win32'
+            ? `Run as admin: sc stop WireGuardTunnel$${orphanedWg.tunnels[0]} && sc delete WireGuardTunnel$${orphanedWg.tunnels[0]}`
+            : `Run: sudo wg-quick down ${orphanedWg.tunnels[0]}`,
+          autoFix: false,
+        });
+      }
+      // If all cleaned, no issue to report
+    } else {
+      issues.push({
+        severity: 'warning',
+        component: 'wireguard',
+        message: `Found ${orphanedWg.tunnels.length} orphaned WireGuard tunnel(s): ${orphanedWg.tunnels.join(', ')}`,
+        detail: 'Left over from a previous crash or app exit. Will block new connections. Set autoClean: true to fix automatically.',
+        action: 'Call preflight({ autoClean: true }) or cleanOrphanedTunnels() to remove them.',
+        autoFix: true,
+      });
+    }
+  }
+
+  // ── 5. Orphaned V2Ray processes ──
+  const orphanedV2 = checkOrphanedV2Ray();
+  if (orphanedV2.found) {
+    issues.push({
+      severity: 'info',
+      component: 'v2ray',
+      message: `Found ${orphanedV2.pids.length} V2Ray process(es) running: PIDs ${orphanedV2.pids.join(', ')}`,
+      detail: 'May be from a previous session or another application. These consume SOCKS5 ports.',
+      action: 'If these are unexpected, they will be replaced on next connection. No action needed unless ports conflict.',
+      autoFix: false,
+    });
+  }
+
+  // ── 6. Conflicting VPN software ──
+  const vpnCheck = checkVpnConflicts();
+  if (vpnCheck.conflicts.length > 0) {
+    const names = vpnCheck.conflicts.map(c => c.name).join(', ');
+    issues.push({
+      severity: 'warning',
+      component: 'system',
+      message: `Other VPN software detected: ${names}`,
+      detail: 'Running multiple VPNs simultaneously can cause routing conflicts, DNS leaks, or connection failures. Disconnect the other VPN before connecting.',
+      action: `Disconnect ${names} before using this app.`,
+      autoFix: false,
+    });
+  }
+
+  // ── 7. Port conflicts ──
+  const portCheck = checkPortConflicts();
+  if (portCheck.conflicts.length > 0) {
+    const ports = portCheck.conflicts.map(c => c.port).join(', ');
+    issues.push({
+      severity: 'info',
+      component: 'v2ray',
+      message: `SOCKS5 port(s) already in use: ${ports}`,
+      detail: 'V2Ray will use a random port to avoid conflicts. This is usually fine.',
+      action: 'No action needed — SDK uses random ports. If you need a specific port, close the process using it.',
+      autoFix: false,
+    });
+  }
+
+  // ── Summary ──
+  const errors = issues.filter(i => i.severity === 'error');
+  const warnings = issues.filter(i => i.severity === 'warning');
+
+  return {
+    ok: errors.length === 0,
+    ready: {
+      wireguard: WG_AVAILABLE && IS_ADMIN,
+      v2ray: !!v2path,
+      anyProtocol: (WG_AVAILABLE && IS_ADMIN) || !!v2path,
+    },
+    issues,
+    summary: errors.length === 0 && warnings.length === 0
+      ? 'All checks passed. Ready to connect.'
+      : errors.length > 0
+        ? `${errors.length} error(s), ${warnings.length} warning(s). Fix errors before connecting.`
+        : `${warnings.length} warning(s). Can still connect with available protocols.`,
+  };
+}

package/pricing/index.js

@@ -0,0 +1,262 @@
+/**
+ * Sentinel SDK — Pricing, Display & Filtering Module
+ *
+ * Extracted from cosmjs-setup.js during domain-module refactor.
+ * Provides node price lookups, network overview, display formatting,
+ * node filtering, and BigInt-safe serialization.
+ *
+ * Usage:
+ *   import { getNodePrices, formatDvpn, filterNodes } from './pricing/index.js';
+ *   const prices = await getNodePrices('sentnode1abc...');
+ *   console.log(formatDvpn(prices.gigabyte.udvpn)); // "0.04 P2P"
+ */
+
+import { lcd } from '../chain/index.js';
+import { fetchActiveNodes } from '../chain/index.js';
+import { LCD_ENDPOINTS, tryWithFallback } from '../config/index.js';
+import { ValidationError, NodeError, ErrorCodes } from '../errors/index.js';
+
+// ─── Node Price Lookup ──────────────────────────────────────────────────────
+
+/**
+ * Get standardized prices for a node — abstracts V3 LCD price parsing entirely.
+ *
+ * Solves the common "NaN / GB" problem by defensively extracting quote_value,
+ * base_value, or amount from the nested LCD response structure.
+ *
+ * @param {string} nodeAddress - sentnode1... address
+ * @param {string} [lcdUrl] - LCD endpoint URL (default: cascading fallback across all endpoints)
+ * @returns {Promise<{ gigabyte: { dvpn: number, udvpn: number, raw: object|null }, hourly: { dvpn: number, udvpn: number, raw: object|null }, denom: string, nodeAddress: string }>}
+ *
+ * @example
+ *   const prices = await getNodePrices('sentnode1abc...');
+ *   console.log(`${prices.gigabyte.dvpn} P2P/GB, ${prices.hourly.dvpn} P2P/hr`);
+ *   // Use prices.gigabyte.raw for the full { denom, base_value, quote_value } object
+ *   // needed by encodeMsgStartSession's max_price field.
+ */
+export async function getNodePrices(nodeAddress, lcdUrl) {
+  if (typeof nodeAddress !== 'string' || !/^sentnode1[a-z0-9]{38}$/.test(nodeAddress)) {
+    throw new ValidationError(ErrorCodes.INVALID_NODE_ADDRESS, 'nodeAddress must be a valid sentnode1... bech32 address (46 characters)', { value: nodeAddress });
+  }
+
+  const fetchNode = async (baseUrl) => {
+    let nextKey = null;
+    let pages = 0;
+    do {
+      const keyParam = nextKey ? `&pagination.key=${encodeURIComponent(nextKey)}` : '';
+      const data = await lcd(baseUrl, `/sentinel/node/v3/nodes?status=1&pagination.limit=500${keyParam}`);
+      const nodes = data.nodes || [];
+      const found = nodes.find(n => n.address === nodeAddress);
+      if (found) return found;
+      nextKey = data.pagination?.next_key || null;
+      pages++;
+    } while (nextKey && pages < 20);
+    return null;
+  };
+
+  let node;
+  if (lcdUrl) {
+    node = await fetchNode(lcdUrl);
+  } else {
+    const result = await tryWithFallback(LCD_ENDPOINTS, fetchNode, 'getNodePrices');
+    node = result.result;
+  }
+
+  if (!node) throw new NodeError(ErrorCodes.NODE_NOT_FOUND, `Node ${nodeAddress} not found on LCD (may be inactive or deregistered)`, { nodeAddress });
+
+  function extractPrice(priceArray) {
+    if (!Array.isArray(priceArray)) return { dvpn: 0, udvpn: 0, raw: null };
+    const entry = priceArray.find(p => p.denom === 'udvpn');
+    if (!entry) return { dvpn: 0, udvpn: 0, raw: null };
+    // Defensive fallback chain: quote_value (V3 current) -> base_value -> amount (legacy)
+    const rawVal = entry.quote_value || entry.base_value || entry.amount || '0';
+    const udvpn = parseInt(rawVal, 10) || 0;
+    return { dvpn: parseFloat((udvpn / 1_000_000).toFixed(6)), udvpn, raw: entry };
+  }
+
+  return {
+    gigabyte: extractPrice(node.gigabyte_prices),
+    hourly: extractPrice(node.hourly_prices),
+    denom: 'P2P',
+    nodeAddress,
+  };
+}
+
+// ─── Network Overview ───────────────────────────────────────────────────────
+
+/**
+ * Get a quick network overview — total nodes, counts by country and service type, average prices.
+ * Perfect for dashboard UIs, onboarding screens, and network health displays.
+ *
+ * @param {string} [lcdUrl] - LCD endpoint (default: cascading fallback)
+ * @returns {Promise<{ totalNodes: number, byCountry: Array<{country: string, count: number}>, byType: {wireguard: number, v2ray: number, unknown: number}, averagePrice: {gigabyteDvpn: number, hourlyDvpn: number}, nodes: Array }>}
+ *
+ * @example
+ *   const overview = await getNetworkOverview();
+ *   console.log(`${overview.totalNodes} nodes across ${overview.byCountry.length} countries`);
+ *   console.log(`Average: ${overview.averagePrice.gigabyteDvpn.toFixed(3)} P2P/GB`);
+ */
+export async function getNetworkOverview(lcdUrl) {
+  const fetchFn = async (url) => fetchActiveNodes(url);
+  let nodes;
+  if (lcdUrl) {
+    nodes = await fetchFn(lcdUrl);
+  } else {
+    const result = await tryWithFallback(LCD_ENDPOINTS, fetchFn, 'getNetworkOverview');
+    nodes = result.result;
+  }
+
+  // Filter to nodes that accept udvpn
+  const active = nodes.filter(n => n.remote_url && (n.gigabyte_prices || []).some(p => p.denom === 'udvpn'));
+
+  // Count by country (from LCD metadata, limited — enrichNodes gives better data)
+  const countryMap = {};
+  for (const n of active) {
+    const c = n.location?.country || n.country || 'Unknown';
+    countryMap[c] = (countryMap[c] || 0) + 1;
+  }
+  const byCountry = Object.entries(countryMap)
+    .map(([country, count]) => ({ country, count }))
+    .sort((a, b) => b.count - a.count);
+
+  // Count by type (type not in LCD — estimate from service_type field if present)
+  const byType = { wireguard: 0, v2ray: 0, unknown: 0 };
+  for (const n of active) {
+    const t = n.service_type || n.type;
+    if (t === 'wireguard' || t === 1) byType.wireguard++;
+    else if (t === 'v2ray' || t === 2) byType.v2ray++;
+    else byType.unknown++;
+  }
+
+  // Average prices
+  let gbTotal = 0, gbCount = 0, hrTotal = 0, hrCount = 0;
+  for (const n of active) {
+    const gb = (n.gigabyte_prices || []).find(p => p.denom === 'udvpn');
+    if (gb?.quote_value) { gbTotal += parseInt(gb.quote_value, 10); gbCount++; }
+    const hr = (n.hourly_prices || []).find(p => p.denom === 'udvpn');
+    if (hr?.quote_value) { hrTotal += parseInt(hr.quote_value, 10); hrCount++; }
+  }
+
+  return {
+    totalNodes: active.length,
+    byCountry,
+    byType,
+    averagePrice: {
+      gigabyteDvpn: gbCount > 0 ? (gbTotal / gbCount) / 1_000_000 : 0,
+      hourlyDvpn: hrCount > 0 ? (hrTotal / hrCount) / 1_000_000 : 0,
+    },
+    nodes: active,
+  };
+}
+
+// ─── Display Formatting ─────────────────────────────────────────────────────
+
+/**
+ * Format a micro-denom (udvpn) amount as a human-readable P2P string.
+ *
+ * @param {number|string} udvpn - Amount in micro-denom (1 P2P = 1,000,000 udvpn)
+ * @param {number} [decimals=2] - Decimal places to show
+ * @returns {string} e.g., "0.04 P2P", "47.69 P2P"
+ *
+ * @example
+ *   formatDvpn(40152030);      // "40.15 P2P"
+ *   formatDvpn('1000000', 0);  // "1 P2P"
+ *   formatDvpn(500000, 4);     // "0.5000 P2P"
+ */
+export function formatDvpn(udvpn, decimals = 2) {
+  const val = Number(udvpn) / 1_000_000;
+  if (isNaN(val)) return '? P2P';
+  return `${val.toFixed(decimals)} P2P`;
+}
+
+/** Alias for formatDvpn — uses the new P2P token ticker. */
+export const formatP2P = formatDvpn;
+
+// ─── Node Filtering ─────────────────────────────────────────────────────────
+
+/**
+ * Filter a node list by country, service type, and/or max price.
+ * Works with results from listNodes(), enrichNodes(), or fetchAllNodes().
+ *
+ * @param {Array} nodes - Array of node objects
+ * @param {object} criteria
+ * @param {string} [criteria.country] - Country name (case-insensitive partial match)
+ * @param {string} [criteria.serviceType] - 'wireguard' or 'v2ray'
+ * @param {number} [criteria.maxPriceDvpn] - Maximum GB price in P2P (e.g., 0.1)
+ * @param {number} [criteria.minScore] - Minimum quality score (0-100)
+ * @returns {Array} Filtered nodes
+ *
+ * @example
+ *   const cheap = filterNodes(nodes, { maxPriceDvpn: 0.05, serviceType: 'v2ray' });
+ *   const german = filterNodes(nodes, { country: 'Germany' });
+ */
+export function filterNodes(nodes, criteria = {}) {
+  if (!Array.isArray(nodes)) return [];
+  return nodes.filter(node => {
+    if (criteria.country) {
+      const c = (node.country || node.location?.country || '').toLowerCase();
+      if (!c.includes(criteria.country.toLowerCase())) return false;
+    }
+    if (criteria.serviceType) {
+      const t = node.serviceType || node.type || '';
+      if (t !== criteria.serviceType) return false;
+    }
+    if (criteria.maxPriceDvpn != null) {
+      const prices = node.gigabytePrices || node.gigabyte_prices || [];
+      const entry = prices.find(p => p.denom === 'udvpn');
+      if (entry) {
+        const dvpn = parseInt(entry.quote_value || entry.base_value || entry.amount || '0', 10) / 1_000_000;
+        if (dvpn > criteria.maxPriceDvpn) return false;
+      }
+    }
+    if (criteria.minScore != null && node.qualityScore != null) {
+      if (node.qualityScore < criteria.minScore) return false;
+    }
+    return true;
+  });
+}
+
+// ─── Serialization ──────────────────────────────────────────────────────────
+
+/**
+ * Serialize a ConnectResult for JSON APIs. Handles BigInt -> string conversion.
+ * Without this, JSON.stringify(connectResult) throws "BigInt can't be serialized".
+ *
+ * @param {object} result - ConnectResult from connectDirect/connectAuto/connectViaPlan
+ * @returns {object} JSON-safe object with sessionId as string
+ *
+ * @example
+ *   const conn = await connectDirect(opts);
+ *   res.json(serializeResult(conn)); // Safe for Express response
+ */
+export function serializeResult(result) {
+  if (!result || typeof result !== 'object') return result;
+  const out = {};
+  for (const [key, val] of Object.entries(result)) {
+    if (typeof val === 'bigint') out[key] = String(val);
+    else if (typeof val === 'function') continue; // skip cleanup()
+    else out[key] = val;
+  }
+  return out;
+}
+
+// ─── PriceResolver Class ────────────────────────────────────────────────────
+
+/**
+ * Static class providing a unified API for all pricing operations.
+ * Convenience wrapper around the standalone functions above.
+ *
+ * @example
+ *   const prices = await PriceResolver.getNodePrices('sentnode1abc...');
+ *   const overview = await PriceResolver.getNetworkOverview();
+ *   const display = PriceResolver.format(prices.gigabyte.udvpn);
+ *   const filtered = PriceResolver.filter(overview.nodes, { country: 'Germany' });
+ *   const safe = PriceResolver.serialize(connectResult);
+ */
+export class PriceResolver {
+  static async getNodePrices(nodeAddress, lcdUrl) { return getNodePrices(nodeAddress, lcdUrl); }
+  static async getNetworkOverview(lcdUrl) { return getNetworkOverview(lcdUrl); }
+  static format(udvpn, decimals) { return formatDvpn(udvpn, decimals); }
+  static filter(nodes, criteria) { return filterNodes(nodes, criteria); }
+  static serialize(result) { return serializeResult(result); }
+}