@fibscope/agent 0.1.0

package/lib/route/route.mjs

@@ -0,0 +1,1053 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+
+export class FiberRouteVirtualizerError extends Error {
+  constructor(message, code = "FIBER_ROUTE_VIRTUALIZER_ERROR", details = undefined) {
+    super(message);
+    this.name = "FiberRouteVirtualizerError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export async function virtualizePayment(request, options = {}) {
+  const normalized = normalizePaymentRequest(request);
+  const componentState = await resolveComponentState(options);
+  const readinessPrediction = predictComponentReadinessFailure(normalized, componentState);
+  const graph = await discoverRouteGraph(normalized, options, componentState);
+  const routes = discoverRoutes(normalized, graph, options);
+  const analyzedRoutes = routes.map((route, index) => analyzeRoute(route, normalized, componentState, index));
+  const selectedRoute = selectRoute(analyzedRoutes);
+  const simulation = selectedRoute
+    ? simulateRoute(selectedRoute, normalized)
+    : noRouteSimulation(normalized, readinessPrediction);
+  const execution = buildVirtualExecution(normalized, selectedRoute, simulation);
+  const predictions = predictFailures(normalized, componentState, graph, analyzedRoutes, selectedRoute, simulation, readinessPrediction);
+  const visualization = buildPaymentVisualization(selectedRoute, simulation, execution, predictions);
+  const diagnostics = diagnoseVirtualPayment(normalized, componentState, graph, routes, selectedRoute, simulation);
+
+  return {
+    request: normalized,
+    componentState,
+    graph,
+    routes: analyzedRoutes,
+    selectedRoute,
+    simulation,
+    execution,
+    predictions,
+    visualization,
+    diagnostics,
+  };
+}
+
+export async function discoverPaymentRoutes(request, options = {}) {
+  const normalized = normalizePaymentRequest(request);
+  const componentState = await resolveComponentState(options);
+  const graph = await discoverRouteGraph(normalized, options, componentState);
+  return discoverRoutes(normalized, graph, options);
+}
+
+export function analyzePaymentRoute(route, request, componentState = {}) {
+  return analyzeRoute(route, normalizePaymentRequest(request), componentState, 0);
+}
+
+export function simulatePaymentRoute(route, request) {
+  return simulateRoute(route, normalizePaymentRequest(request));
+}
+
+export function simulatePaymentFees(route, request) {
+  return simulateRoute(route, normalizePaymentRequest(request)).feeBreakdown;
+}
+
+export function buildPaymentExecution(route, request) {
+  const normalized = normalizePaymentRequest(request);
+  const analyzedRoute = route ? (route.analysis ? route : analyzeRoute(route, normalized, {}, 0)) : undefined;
+  const simulation = analyzedRoute ? simulateRoute(analyzedRoute, normalized) : noRouteSimulation(normalized);
+  return buildVirtualExecution(normalized, analyzedRoute, simulation);
+}
+
+export function buildPaymentVisualization(route, simulation, execution, predictions = []) {
+  return {
+    route: route ?? null,
+    liquidityChanges: simulation.liquidityChanges,
+    feeBreakdown: simulation.feeBreakdown,
+    executionSteps: execution.steps,
+    predictions,
+  };
+}
+
+export function predictPaymentFailures(route, request, componentState = {}) {
+  const normalized = normalizePaymentRequest(request);
+  const readinessPrediction = predictComponentReadinessFailure(normalized, componentState);
+  const analyzedRoute = route ? (route.analysis ? route : analyzeRoute(route, normalized, componentState, 0)) : undefined;
+  const simulation = analyzedRoute
+    ? simulateRoute(analyzedRoute, normalized)
+    : noRouteSimulation(normalized, readinessPrediction);
+  return predictFailures(normalized, componentState, { channels: [] }, analyzedRoute ? [analyzedRoute] : [], analyzedRoute, simulation, readinessPrediction);
+}
+
+export function normalizePaymentRequest(request = {}) {
+  const sourceNode = stringField(request, "sourceNode", "source node");
+  const destinationNode = stringField(request, "destinationNode", "destination node");
+  const amount = amountField(request.amount);
+  const assetType = request.assetType ? String(request.assetType) : "CKB";
+  if (sourceNode === destinationNode) {
+    throw new FiberRouteVirtualizerError("sourceNode and destinationNode must be different.", "INVALID_PAYMENT_REQUEST");
+  }
+  return { sourceNode, destinationNode, amount, assetType };
+}
+
+export async function discoverRouteGraph(request, options = {}, componentState = {}) {
+  if (options.graph) return normalizeGraph(options.graph);
+  const localGraph = graphFromComponentState(componentState, request);
+  if (options.rpcUrl) {
+    const rpcGraph = await graphFromRpc(options.rpcUrl, options);
+    return mergeGraphs(rpcGraph, localGraph);
+  }
+  return localGraph;
+}
+
+export function discoverRoutes(request, graph, options = {}) {
+  const normalizedGraph = normalizeGraph(graph);
+  const nodeById = new Map(normalizedGraph.nodes.map((node) => [node.nodeId, node]));
+  const maxHops = options.maxHops ?? 6;
+  const maxRoutes = options.maxRoutes ?? 10;
+  const queue = [{ nodeId: request.sourceNode, hops: [], visited: new Set([request.sourceNode]) }];
+  const routes = [];
+
+  while (queue.length > 0 && routes.length < maxRoutes) {
+    const current = queue.shift();
+    if (current.hops.length >= maxHops) continue;
+    const outgoing = normalizedGraph.channels.filter((channel) =>
+      channel.sourceNode === current.nodeId &&
+      !current.visited.has(channel.destinationNode) &&
+      assetMatches(channel.assetType, request.assetType)
+    );
+    for (const channel of outgoing) {
+      const fromNode = nodeById.get(channel.sourceNode);
+      const toNode = nodeById.get(channel.destinationNode);
+      const hop = {
+        nodeId: channel.destinationNode,
+        channelId: channel.channelId,
+        fromNode: channel.sourceNode,
+        toNode: channel.destinationNode,
+        assetType: channel.assetType,
+        capacity: channel.capacity,
+        localBalance: channel.localBalance,
+        remoteBalance: channel.remoteBalance,
+        outboundLiquidity: channel.outboundLiquidity,
+        feeRate: channel.feeRate,
+        baseFee: channel.baseFee,
+        enabled: channel.enabled,
+        status: channel.status,
+        fromNodeOnline: knownNodeOnline(fromNode),
+        toNodeOnline: knownNodeOnline(toNode),
+      };
+      const hops = [...current.hops, hop];
+      if (channel.destinationNode === request.destinationNode) {
+        routes.push({ hops });
+      } else {
+        queue.push({
+          nodeId: channel.destinationNode,
+          hops,
+          visited: new Set([...current.visited, channel.destinationNode]),
+        });
+      }
+    }
+  }
+
+  return routes;
+}
+
+function analyzeRoute(route, request, componentState, index) {
+  const context = routeContext(componentState);
+  const hops = [];
+  let amountToForward = request.amount;
+
+  for (let hopIndex = route.hops.length - 1; hopIndex >= 0; hopIndex -= 1) {
+    const hop = route.hops[hopIndex];
+    const fee = estimateHopFee(hop, amountToForward);
+    const incomingAmount = amountToForward + fee.hopFee;
+    const localBefore = hop.localBalance ?? hop.outboundLiquidity;
+    const remoteBefore = deriveRemoteBalance(hop, localBefore);
+    const channelStatus = hop.status ?? context.channels.get(hop.channelId)?.status;
+    const channelOpen = channelStatus ? channelStatus === "open" : hop.enabled !== false;
+    const fromNodeOnline = resolveNodeOnline(hop.fromNode, hop.fromNodeOnline, context);
+    const toNodeOnline = resolveNodeOnline(hop.toNode, hop.toNodeOnline, context);
+    const liquidityKnown = localBefore !== undefined;
+    const hasLiquidity = liquidityKnown && localBefore >= incomingAmount;
+
+    hops.unshift({
+      ...hop,
+      step: hopIndex + 1,
+      estimatedFee: fee.hopFee,
+      outgoingAmount: amountToForward,
+      incomingAmount,
+      requiredOutbound: incomingAmount,
+      baseFee: hop.baseFee ?? 0n,
+      proportionalFee: fee.proportionalFee,
+      localBefore,
+      localAfter: localBefore === undefined ? undefined : localBefore - incomingAmount,
+      remoteBefore,
+      remoteAfter: remoteBefore === undefined ? undefined : remoteBefore + incomingAmount,
+      channelOpen,
+      channelStatus,
+      fromNodeOnline,
+      toNodeOnline,
+      liquidityKnown,
+      hasLiquidity,
+      liquidityAfter: localBefore === undefined ? undefined : localBefore - incomingAmount,
+    });
+    amountToForward = incomingAmount;
+  }
+
+  const totalFee = amountToForward - request.amount;
+  const issues = analyzeHopIssues(hops);
+  const routeAnalysis = {
+    routeValid: hops.length > 0 && issues.length === 0,
+    issues,
+  };
+
+  return {
+    id: `route-${index + 1}`,
+    hops,
+    hopCount: hops.length,
+    totalFee,
+    amountDelivered: request.amount,
+    amountDebited: amountToForward,
+    assetType: request.assetType,
+    analysis: routeAnalysis,
+    routeValid: routeAnalysis.routeValid,
+    issues,
+    viable: routeAnalysis.routeValid,
+    sourceReadiness: readinessSummary(componentState),
+  };
+}
+
+function simulateRoute(route, request) {
+  const analyzedRoute = route.analysis ? route : analyzeRoute(route, request, {}, 0);
+  const steps = analyzedRoute.hops.map((hop) => {
+    const hopIssues = analyzedRoute.analysis.issues.filter((issue) => issue.hop === hop.step);
+    const reason = hopIssues[0]?.code;
+    return {
+      step: hop.step,
+      channelId: hop.channelId,
+      fromNode: hop.fromNode,
+      toNode: hop.toNode,
+      outgoingAmount: hop.outgoingAmount,
+      incomingAmount: hop.incomingAmount,
+      hopFee: hop.estimatedFee,
+      baseFee: hop.baseFee ?? 0n,
+      proportionalFee: hop.proportionalFee ?? 0n,
+      beforeLocal: hop.localBefore,
+      afterLocal: hop.localAfter,
+      beforeRemote: hop.remoteBefore,
+      afterRemote: hop.remoteAfter,
+      outboundBefore: hop.localBefore,
+      outboundAfter: hop.localAfter,
+      status: hopIssues.length === 0 ? "pass" : "blocked",
+      reason,
+      issues: hopIssues,
+    };
+  });
+
+  const blocked = steps.find((step) => step.status === "blocked");
+  return {
+    result: blocked ? "failure" : "success",
+    amount: request.amount,
+    totalFee: analyzedRoute.totalFee,
+    totalDebit: analyzedRoute.amountDebited,
+    routeAnalysis: analyzedRoute.analysis,
+    liquidityChanges: steps.map(liquidityChangeFromStep),
+    feeBreakdown: buildFeeBreakdown(steps),
+    steps,
+    failure: blocked ? { step: blocked.step, code: blocked.reason, channelId: blocked.channelId, issues: blocked.issues } : undefined,
+  };
+}
+
+function noRouteSimulation(request, readinessPrediction = undefined) {
+  return {
+    result: "failure",
+    amount: request.amount,
+    totalFee: 0n,
+    totalDebit: request.amount,
+    liquidityChanges: [],
+    feeBreakdown: {
+      hopFees: [],
+      totalFee: 0n,
+    },
+    steps: [],
+    failure: {
+      step: 0,
+      code: readinessPrediction?.code ?? "NO_ROUTE",
+    },
+  };
+}
+
+function buildVirtualExecution(request, route, simulation) {
+  const steps = [];
+  steps.push(executionStep(
+    steps.length + 1,
+    "Route Found",
+    route ? "success" : "failed",
+    route ? `${route.hopCount} hop route selected.` : "No route could be selected."
+  ));
+
+  if (route) {
+    for (const hop of simulation.steps) {
+      const hopStatus = hop.status === "pass" ? "success" : "failed";
+      steps.push(executionStep(
+        steps.length + 1,
+        `Hop ${hop.step} Validated`,
+        hopStatus,
+        hop.reason
+          ? `${short(hop.fromNode)} -> ${short(hop.toNode)} failed with ${hop.reason}.`
+          : `${short(hop.fromNode)} -> ${short(hop.toNode)} is online, open, and liquid enough.`
+      ));
+      steps.push(executionStep(
+        steps.length + 1,
+        "Liquidity Reserved",
+        hopStatus,
+        hopStatus === "success"
+          ? `${hop.incomingAmount.toString()} ${request.assetType} reserved on ${short(hop.channelId)}.`
+          : `Cannot reserve ${hop.incomingAmount.toString()} ${request.assetType} on ${short(hop.channelId)}.`
+      ));
+      steps.push(executionStep(
+        steps.length + 1,
+        hop.toNode === request.destinationNode ? "Forwarded To Receiver" : `Forwarded To Hop ${hop.step + 1}`,
+        hopStatus,
+        hopStatus === "success"
+          ? `${hop.outgoingAmount.toString()} ${request.assetType} virtually forwarded to ${short(hop.toNode)}.`
+          : `Forwarding stopped at ${short(hop.toNode)}.`
+      ));
+      if (hopStatus === "failed") break;
+    }
+  }
+
+  steps.push(executionStep(
+    steps.length + 1,
+    simulation.result === "success" ? "Settled" : "Not Settled",
+    simulation.result === "success" ? "success" : "failed",
+    simulation.result === "success"
+      ? `Payment can deliver ${request.amount.toString()} ${request.assetType} with estimated fee ${simulation.feeBreakdown.totalFee.toString()}.`
+      : `Payment simulation failed: ${simulation.failure?.code ?? "UNKNOWN"}.`
+  ));
+
+  return {
+    readOnly: true,
+    broadcast: false,
+    mutatesChannels: false,
+    steps,
+  };
+}
+
+function buildVisualization(request, route, simulation, execution) {
+  return {
+    title: `Send ${request.amount.toString()} ${request.assetType}`,
+    route: route
+      ? [request.sourceNode, ...route.hops.map((hop) => hop.toNode)]
+      : [request.sourceNode, request.destinationNode],
+    routeText: route
+      ? [request.sourceNode, ...route.hops.map((hop) => hop.toNode)].map(short).join(" -> ")
+      : `${short(request.sourceNode)} -/-> ${short(request.destinationNode)}`,
+    lanes: [
+      { id: "route", label: "Route Selection" },
+      { id: "liquidity", label: "Liquidity Consumption" },
+      { id: "fees", label: "Fee Accumulation" },
+      { id: "result", label: "Final Result" },
+    ],
+    nodes: execution.steps.map((step) => ({
+      id: `step-${step.step}`,
+      label: step.title,
+      lane: laneForExecutionStep(step),
+      status: step.status,
+    })),
+    edges: simulation.steps.map((step) => ({
+      from: step.fromNode,
+      to: step.toNode,
+      channelId: step.channelId,
+      label: `${step.incomingAmount.toString()} ${request.assetType}`,
+    })),
+    summary: {
+      result: simulation.result,
+      amount: request.amount,
+      totalFee: simulation.feeBreakdown.totalFee,
+      totalDebit: simulation.totalDebit,
+      failure: simulation.failure,
+    },
+  };
+}
+
+function predictFailures(request, componentState, graph, routes, selectedRoute, simulation, readinessPrediction = undefined) {
+  const predictions = [];
+  if (readinessPrediction) predictions.push(readinessPrediction);
+
+  const sourceDiagnostics = Array.isArray(componentState.diagnostics) ? componentState.diagnostics : [];
+  for (const diagnostic of sourceDiagnostics) {
+    if (diagnostic.severity === "critical") {
+      predictions.push(failurePrediction(
+        diagnostic.code,
+        0.95,
+        diagnostic.description ?? diagnostic.title ?? "Component 1 reports a critical source node problem.",
+        diagnostic.recommendation ?? "Resolve the source node diagnostic before simulating payment routes."
+      ));
+    }
+  }
+
+  if ((graph.channels ?? []).length === 0) {
+    predictions.push(failurePrediction(
+      "NO_GRAPH_CHANNELS",
+      0.9,
+      "No Fiber channel edges are available for route discovery.",
+      "Query Fiber graph data, connect peers, or open channels before attempting payment."
+    ));
+  }
+
+  if (routes.length === 0) {
+    predictions.push(failurePrediction(
+      "NO_ROUTE",
+      0.88,
+      "No route connects the source node to the destination node for this asset.",
+      "Use an alternate receiver route, connect to more peers, or wait for graph gossip."
+    ));
+  }
+
+  if (selectedRoute) {
+    for (const issue of selectedRoute.analysis.issues) {
+      predictions.push(predictionFromRouteIssue(issue));
+    }
+  }
+
+  if (simulation.result === "success" && predictions.length === 0) {
+    predictions.push(failurePrediction(
+      "LIKELY_SUCCESS",
+      0.82,
+      "The selected route is open and has enough known liquidity for the requested amount plus estimated fees.",
+      "Proceed with this route or compare alternate routes for lower fees."
+    ));
+  }
+
+  return dedupePredictions(predictions);
+}
+
+function predictComponentReadinessFailure(request, componentState = {}) {
+  const maxSendable = amountMaybe(componentState.liquidity?.totalOutbound);
+  if (maxSendable !== undefined && request.amount > maxSendable) {
+    return failurePrediction(
+      "INSUFFICIENT_OUTBOUND_LIQUIDITY",
+      0.98,
+      `Requested amount ${request.amount.toString()} exceeds total outbound liquidity ${maxSendable.toString()}.`,
+      "Add outbound liquidity, rebalance channels, or try a smaller payment amount."
+    );
+  }
+  if (componentState.node?.online === false) {
+    return failurePrediction(
+      "NODE_OFFLINE",
+      0.99,
+      "The source Fiber node is offline according to Component 1.",
+      "Verify FNN is running and reachable before attempting payment."
+    );
+  }
+  if ((componentState.peers ?? []).length === 0) {
+    return failurePrediction(
+      "NO_PEERS",
+      0.95,
+      "The source node has no known Fiber peers.",
+      "Connect to a Fiber peer before attempting payment."
+    );
+  }
+  if ((componentState.channels ?? []).length === 0) {
+    return failurePrediction(
+      "NO_CHANNELS",
+      0.95,
+      "The source node has no Fiber channels.",
+      "Open or discover a usable Fiber channel before attempting payment."
+    );
+  }
+  return undefined;
+}
+
+function predictionFromRouteIssue(issue) {
+  if (issue.code === "INSUFFICIENT_LIQUIDITY") {
+    return failurePrediction(
+      "INSUFFICIENT_LIQUIDITY",
+      0.94,
+      `Hop ${issue.hop} lacks liquidity: required ${stringAmount(issue.required)}, available ${stringAmount(issue.available)}.`,
+      "Rebalance the channel, choose an alternate route, or reduce the payment amount."
+    );
+  }
+  if (issue.code === "CHANNEL_NOT_OPEN") {
+    return failurePrediction(
+      "CHANNEL_NOT_OPEN",
+      0.93,
+      `Hop ${issue.hop} uses a channel that is not open.`,
+      "Wait for the channel to open or use an alternate route."
+    );
+  }
+  if (issue.code === "NODE_OFFLINE") {
+    return failurePrediction(
+      "NODE_OFFLINE",
+      0.92,
+      `Hop ${issue.hop} includes a node known to be offline.`,
+      "Reconnect the peer or route around this node."
+    );
+  }
+  if (issue.code === "UNKNOWN_LIQUIDITY") {
+    return failurePrediction(
+      "UNKNOWN_LIQUIDITY",
+      0.62,
+      `Hop ${issue.hop} has unknown outbound liquidity, so payment success cannot be confirmed.`,
+      "Refresh graph data or use a route with known liquidity."
+    );
+  }
+  return failurePrediction(
+    issue.code,
+    0.7,
+    issue.message ?? `Hop ${issue.hop} has a route issue.`,
+    "Inspect this hop and try an alternate route if needed."
+  );
+}
+
+function failurePrediction(code, confidence, explanation, recommendation) {
+  return { code, confidence, explanation, recommendation };
+}
+
+function dedupePredictions(predictions) {
+  const seen = new Set();
+  const deduped = [];
+  for (const prediction of predictions) {
+    const key = `${prediction.code}:${prediction.explanation}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(prediction);
+  }
+  return deduped.sort((left, right) => right.confidence - left.confidence);
+}
+
+function diagnoseVirtualPayment(request, componentState, graph, routes, selectedRoute, simulation) {
+  const diagnostics = [];
+  const componentDiagnostics = Array.isArray(componentState.diagnostics) ? componentState.diagnostics : [];
+  for (const diagnostic of componentDiagnostics) {
+    if (diagnostic.severity === "critical") {
+      diagnostics.push({
+        code: `SOURCE_${diagnostic.code}`,
+        severity: diagnostic.severity,
+        title: diagnostic.title,
+        description: diagnostic.description,
+        recommendation: diagnostic.recommendation,
+      });
+    }
+  }
+  if (graph.channels.length === 0) {
+    diagnostics.push(diagnostic("NO_GRAPH_CHANNELS", "critical", "No route graph channels", "Route discovery had no channel edges to evaluate.", "Query Fiber graph data or open/connect channels."));
+  }
+  if (routes.length === 0) {
+    diagnostics.push(diagnostic("NO_ROUTE", "critical", "No payment route found", "No path connects the source node to the destination node for the requested asset.", "Connect to more peers or wait for graph gossip."));
+  }
+  if (selectedRoute && !selectedRoute.viable) {
+    diagnostics.push(diagnostic("ROUTE_NOT_VIABLE", "warning", "Route exists but is not viable", "At least one hop is disabled or lacks enough outbound liquidity.", "Try a smaller amount or another route."));
+  }
+  if (simulation.failure?.code === "INSUFFICIENT_LIQUIDITY") {
+    diagnostics.push(diagnostic("INSUFFICIENT_ROUTE_LIQUIDITY", "critical", "Insufficient route liquidity", "A route hop cannot carry the requested amount plus fees.", "Try a lower amount or rebalance/open channels."));
+  }
+  if (simulation.failure?.code === "CHANNEL_NOT_OPEN") {
+    diagnostics.push(diagnostic("ROUTE_CHANNEL_NOT_OPEN", "critical", "Route channel is not open", "A route hop uses a channel that is not currently open.", "Wait for the channel to open or select another route."));
+  }
+  if (simulation.failure?.code === "NODE_OFFLINE") {
+    diagnostics.push(diagnostic("ROUTE_NODE_OFFLINE", "critical", "Route node is offline", "A route hop includes a node known to be offline.", "Reconnect the peer or select another route."));
+  }
+  if (diagnostics.length === 0) {
+    diagnostics.push(diagnostic("PAYMENT_VIRTUALIZED", "info", "Payment route appears viable", "The simulation found a route with enough known liquidity."));
+  }
+  return diagnostics;
+}
+
+async function resolveComponentState(options) {
+  if (options.componentState) return options.componentState;
+  const pulseUrl = options.pulseUrl;
+  const pulseModule = options.pulseModule;
+  if (pulseUrl) {
+    const response = await fetch(`${pulseUrl.replace(/\/$/, "")}/state`);
+    if (!response.ok) throw new FiberRouteVirtualizerError(`Pulse /state failed with HTTP ${response.status}`, "PULSE_STATE_FAILED");
+    return response.json();
+  }
+  if (pulseModule && options.rpcUrl) {
+    const imported = await import(resolveImportSpecifier(pulseModule));
+    return imported.collectFiberStateReport({ rpcUrl: options.rpcUrl, timeoutMs: options.timeoutMs ?? 8000 });
+  }
+  return {};
+}
+
+async function graphFromRpc(rpcUrl, options) {
+  const nodes = await safeRpc(rpcUrl, "graph_nodes", [{}], options);
+  const channels = await safeRpc(rpcUrl, "graph_channels", [{}], options);
+  return normalizeGraph({
+    nodes: extractList(nodes, "nodes").map((node) => ({
+      nodeId: node.pubkey ?? node.nodeId ?? node.node_id,
+      addresses: node.addresses ?? [],
+      version: node.version,
+      features: node.features ?? [],
+      online: node.online,
+      connected: node.connected,
+    })),
+    channels: extractList(channels, "channels").flatMap(graphChannelToEdges),
+  });
+}
+
+function graphFromComponentState(componentState = {}, request) {
+  const source = componentState.node?.nodeId ?? request.sourceNode;
+  const nodes = [
+    componentState.node ? {
+      nodeId: componentState.node.nodeId,
+      version: componentState.node.version,
+      online: componentState.node.online,
+    } : undefined,
+    ...(componentState.peers ?? []).map((peer) => ({
+      nodeId: peer.peerId,
+      address: peer.address,
+      connected: peer.connected,
+      online: peer.connected,
+      lastSeen: peer.lastSeen,
+    })),
+  ].filter(Boolean);
+  const channels = (componentState.channels ?? []).flatMap((channel) => {
+    const capacity = amountMaybe(channel.capacity);
+    const localBalance = amountMaybe(channel.localBalance);
+    const remoteBalance = amountMaybe(channel.remoteBalance);
+    const local = {
+      channelId: channel.channelId,
+      sourceNode: source,
+      destinationNode: channel.peerId,
+      assetType: channel.assetType ?? "CKB",
+      capacity,
+      localBalance,
+      remoteBalance,
+      outboundLiquidity: localBalance,
+      enabled: channel.status === "open",
+      status: channel.status,
+    };
+    const remote = {
+      channelId: channel.channelId,
+      sourceNode: channel.peerId,
+      destinationNode: source,
+      assetType: channel.assetType ?? "CKB",
+      capacity,
+      localBalance: remoteBalance,
+      remoteBalance: localBalance,
+      outboundLiquidity: remoteBalance,
+      enabled: channel.status === "open",
+      status: channel.status,
+    };
+    return [local, remote];
+  });
+  return normalizeGraph({ nodes, channels });
+}
+
+function graphChannelToEdges(channel) {
+  const node1 = channel.node1 ?? channel.node_a ?? channel.source ?? channel.pubkey1;
+  const node2 = channel.node2 ?? channel.node_b ?? channel.target ?? channel.pubkey2;
+  if (!node1 || !node2) return [];
+  const channelId = channel.channel_id ?? channel.channelId ?? channel.channel_outpoint ?? "";
+  const assetType = channel.udt_type_script ? `UDT:${channel.udt_type_script.code_hash ?? "unknown"}` : "CKB";
+  const capacity = amountMaybe(channel.capacity);
+  const node1Liquidity = amountMaybe(channel.update_info_of_node1?.outbound_liquidity);
+  const node2Liquidity = amountMaybe(channel.update_info_of_node2?.outbound_liquidity);
+  const node1Balance = node1Liquidity ?? capacity;
+  const node2Balance = node2Liquidity ?? (capacity !== undefined && node1Balance !== undefined && capacity >= node1Balance ? capacity - node1Balance : undefined);
+  return [
+    {
+      channelId,
+      sourceNode: node1,
+      destinationNode: node2,
+      assetType,
+      capacity,
+      localBalance: node1Balance,
+      remoteBalance: node2Balance,
+      outboundLiquidity: node1Balance,
+      feeRate: amountMaybe(channel.update_info_of_node1?.fee_rate),
+      enabled: channel.update_info_of_node1?.enabled ?? true,
+      status: channel.status,
+    },
+    {
+      channelId,
+      sourceNode: node2,
+      destinationNode: node1,
+      assetType,
+      capacity,
+      localBalance: node2Balance,
+      remoteBalance: node1Balance,
+      outboundLiquidity: node2Balance,
+      feeRate: amountMaybe(channel.update_info_of_node2?.fee_rate),
+      enabled: channel.update_info_of_node2?.enabled ?? true,
+      status: channel.status,
+    },
+  ];
+}
+
+function normalizeGraph(graph = {}) {
+  return {
+    nodes: (graph.nodes ?? []).map((node) => ({
+      ...node,
+      nodeId: String(node.nodeId ?? node.node_id ?? node.pubkey ?? ""),
+      online: knownNodeOnline(node),
+    })).filter((node) => node.nodeId),
+    channels: (graph.channels ?? []).map((channel) => ({
+      channelId: String(channel.channelId ?? channel.channel_id ?? ""),
+      sourceNode: String(channel.sourceNode ?? channel.source_node ?? channel.fromNode ?? channel.from ?? ""),
+      destinationNode: String(channel.destinationNode ?? channel.destination_node ?? channel.toNode ?? channel.to ?? ""),
+      assetType: channel.assetType ?? channel.asset_type ?? "CKB",
+      capacity: amountMaybe(channel.capacity),
+      localBalance: amountMaybe(channel.localBalance ?? channel.local_balance),
+      remoteBalance: amountMaybe(channel.remoteBalance ?? channel.remote_balance),
+      outboundLiquidity: amountMaybe(channel.outboundLiquidity ?? channel.outbound_liquidity ?? channel.localBalance ?? channel.local_balance),
+      feeRate: amountMaybe(channel.feeRate ?? channel.fee_rate),
+      baseFee: amountMaybe(channel.baseFee ?? channel.base_fee),
+      status: channel.status,
+      enabled: channel.enabled ?? (channel.status ? channel.status === "open" : true),
+    })).filter((channel) => channel.sourceNode && channel.destinationNode),
+  };
+}
+
+function mergeGraphs(...graphs) {
+  const merged = { nodes: [], channels: [] };
+  const nodeById = new Map();
+  const channelByKey = new Map();
+  for (const graph of graphs.map(normalizeGraph)) {
+    for (const node of graph.nodes) {
+      const existing = nodeById.get(node.nodeId);
+      if (existing) {
+        mergeDefined(existing, node);
+      } else {
+        nodeById.set(node.nodeId, node);
+        merged.nodes.push(node);
+      }
+    }
+    for (const channel of graph.channels) {
+      const key = `${channel.channelId}:${channel.sourceNode}:${channel.destinationNode}:${channel.assetType}`;
+      const existing = channelByKey.get(key);
+      if (existing) {
+        mergeDefined(existing, channel);
+      } else {
+        channelByKey.set(key, channel);
+        merged.channels.push(channel);
+      }
+    }
+  }
+  return merged;
+}
+
+async function safeRpc(rpcUrl, method, params, options) {
+  try {
+    return await rpc(rpcUrl, method, params, options);
+  } catch {
+    return {};
+  }
+}
+
+async function rpc(rpcUrl, method, params = [], options = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 8000);
+  try {
+    const response = await fetch(rpcUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ id: 1, jsonrpc: "2.0", method, params }),
+      signal: controller.signal,
+    });
+    const payload = await response.json();
+    if (payload.error) throw new FiberRouteVirtualizerError(payload.error.message ?? "Fiber RPC error", "FIBER_RPC_ERROR", payload.error);
+    return payload.result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function selectRoute(routes) {
+  return [...routes].sort((a, b) => {
+    if (a.viable !== b.viable) return a.viable ? -1 : 1;
+    if (a.hopCount !== b.hopCount) return a.hopCount - b.hopCount;
+    return compareBigInt(a.totalFee, b.totalFee);
+  })[0];
+}
+
+function estimateHopFee(hop, amount) {
+  const baseFee = hop.baseFee ?? 0n;
+  const rate = hop.feeRate ?? 0n;
+  const proportionalFee = (amount * rate) / 1_000_000n;
+  return {
+    hopFee: baseFee + proportionalFee,
+    baseFee,
+    proportionalFee,
+    downstreamReserve: 0n,
+  };
+}
+
+function buildFeeBreakdown(steps) {
+  const hopFees = steps.map((step) => ({
+    nodeId: step.toNode,
+    channelId: step.channelId,
+    baseFee: step.baseFee,
+    proportionalFee: step.proportionalFee,
+    fee: step.hopFee,
+  }));
+  return {
+    hopFees,
+    totalFee: hopFees.reduce((sum, hop) => sum + hop.fee, 0n),
+  };
+}
+
+function executionStep(step, title, status, details) {
+  return { step, title, status, details };
+}
+
+function laneForExecutionStep(step) {
+  if (step.title.includes("Liquidity")) return "liquidity";
+  if (step.title.includes("Settled")) return "result";
+  if (step.title.includes("Forwarded")) return "route";
+  return "route";
+}
+
+function analyzeHopIssues(hops) {
+  const issues = [];
+  for (const hop of hops) {
+    if (hop.fromNodeOnline === false) {
+      issues.push(routeIssue("NODE_OFFLINE", hop, "Source side of this hop is known to be offline."));
+    }
+    if (hop.toNodeOnline === false) {
+      issues.push(routeIssue("NODE_OFFLINE", hop, "Destination side of this hop is known to be offline."));
+    }
+    if (!hop.channelOpen) {
+      issues.push(routeIssue("CHANNEL_NOT_OPEN", hop, `Channel status is ${hop.channelStatus ?? "disabled"}.`));
+    }
+    if (!hop.liquidityKnown) {
+      issues.push(routeIssue("UNKNOWN_LIQUIDITY", hop, "Outbound liquidity is not available for this hop."));
+    } else if (!hop.hasLiquidity) {
+      issues.push(routeIssue("INSUFFICIENT_LIQUIDITY", hop, "Hop outbound liquidity cannot cover the amount plus fees."));
+    }
+  }
+  return issues;
+}
+
+function routeIssue(code, hop, message) {
+  return {
+    code,
+    hop: hop.step,
+    channelId: hop.channelId,
+    fromNode: hop.fromNode,
+    toNode: hop.toNode,
+    required: hop.requiredOutbound,
+    available: hop.localBefore,
+    message,
+  };
+}
+
+function liquidityChangeFromStep(step) {
+  return {
+    channelId: step.channelId,
+    beforeLocal: step.beforeLocal,
+    afterLocal: step.afterLocal,
+    beforeRemote: step.beforeRemote,
+    afterRemote: step.afterRemote,
+    fromNode: step.fromNode,
+    toNode: step.toNode,
+    amount: step.incomingAmount,
+  };
+}
+
+function routeContext(componentState = {}) {
+  const nodes = new Map();
+  const channels = new Map();
+  if (componentState.node?.nodeId) {
+    nodes.set(componentState.node.nodeId, {
+      online: componentState.node.online,
+      connected: componentState.node.online,
+    });
+  }
+  for (const peer of componentState.peers ?? []) {
+    nodes.set(peer.peerId, {
+      online: peer.connected,
+      connected: peer.connected,
+      lastSeen: peer.lastSeen,
+    });
+  }
+  for (const channel of componentState.channels ?? []) {
+    channels.set(channel.channelId, channel);
+  }
+  return { nodes, channels };
+}
+
+function knownNodeOnline(node) {
+  if (!node) return undefined;
+  if (typeof node.online === "boolean") return node.online;
+  if (typeof node.connected === "boolean") return node.connected;
+  return undefined;
+}
+
+function resolveNodeOnline(nodeId, hinted, context) {
+  if (typeof hinted === "boolean") return hinted;
+  const state = context.nodes.get(nodeId);
+  if (!state) return undefined;
+  return knownNodeOnline(state);
+}
+
+function deriveRemoteBalance(hop, localBefore) {
+  if (hop.remoteBalance !== undefined) return hop.remoteBalance;
+  if (hop.capacity !== undefined && localBefore !== undefined && hop.capacity >= localBefore) {
+    return hop.capacity - localBefore;
+  }
+  return undefined;
+}
+
+function mergeDefined(target, source) {
+  for (const [key, value] of Object.entries(source)) {
+    if (value !== undefined && value !== null && value !== "") {
+      target[key] = value;
+    }
+  }
+  return target;
+}
+
+function readinessSummary(componentState) {
+  if (!componentState.liquidity) return undefined;
+  return {
+    totalOutbound: amountMaybe(componentState.liquidity.totalOutbound),
+    totalInbound: amountMaybe(componentState.liquidity.totalInbound),
+    channelCount: componentState.liquidity.channelCount,
+  };
+}
+
+function diagnostic(code, severity, title, description, recommendation) {
+  return { code, severity, title, description, recommendation };
+}
+
+function extractList(value, key) {
+  if (Array.isArray(value)) return value;
+  if (Array.isArray(value?.[key])) return value[key];
+  return [];
+}
+
+function assetMatches(left, right) {
+  return String(left ?? "CKB").toLowerCase() === String(right ?? "CKB").toLowerCase();
+}
+
+function amountField(value) {
+  const amount = amountMaybe(value);
+  if (amount === undefined || amount <= 0n) {
+    throw new FiberRouteVirtualizerError("amount must be a positive integer.", "INVALID_PAYMENT_REQUEST");
+  }
+  return amount;
+}
+
+function amountMaybe(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return BigInt(Math.trunc(value));
+  if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value)) return BigInt(value);
+  if (typeof value === "string" && /^[0-9]+$/.test(value)) return BigInt(value);
+  return undefined;
+}
+
+function stringAmount(value) {
+  return value === undefined ? "unknown" : value.toString();
+}
+
+function stringField(source, key, label) {
+  const value = source[key];
+  if (!value || typeof value !== "string") {
+    throw new FiberRouteVirtualizerError(`${label} is required.`, "INVALID_PAYMENT_REQUEST");
+  }
+  return value;
+}
+
+function compareBigInt(left, right) {
+  return left === right ? 0 : left < right ? -1 : 1;
+}
+
+function short(value) {
+  const text = String(value ?? "");
+  return text.length <= 14 ? text : `${text.slice(0, 8)}...${text.slice(-6)}`;
+}
+
+function resolveImportSpecifier(specifier) {
+  if (/^(file|data|node|https?):/.test(specifier)) return specifier;
+  if (specifier.startsWith(".") || specifier.includes("\\") || specifier.includes("/")) {
+    return pathToFileURL(path.resolve(process.cwd(), specifier)).href;
+  }
+  return specifier;
+}
+
+function stringify(value) {
+  return JSON.stringify(value, (_, nested) => typeof nested === "bigint" ? nested.toString() : nested, 2);
+}
+
+function routeText(result) {
+  const route = result.visualization?.route;
+  if (route?.hops?.length) {
+    const nodes = [result.request.sourceNode, ...route.hops.map((hop) => hop.toNode)];
+    return nodes.map(short).join(" -> ");
+  }
+  return `${short(result.request.sourceNode)} -/-> ${short(result.request.destinationNode)}`;
+}
+
+function parseCliArgs(argv) {
+  const options = {};
+  const request = {};
+  let command = argv[0]?.startsWith("--") ? "virtualize" : (argv.shift() ?? "help");
+  for (let index = 0; index < argv.length; index += 1) {
+    const raw = argv[index];
+    const [flag, inline] = raw.split("=", 2);
+    const value = () => inline ?? argv[++index];
+    if (flag === "--source") request.sourceNode = value();
+    else if (flag === "--destination") request.destinationNode = value();
+    else if (flag === "--amount") request.amount = value();
+    else if (flag === "--asset") request.assetType = value();
+    else if (flag === "--rpc") options.rpcUrl = value();
+    else if (flag === "--pulse-url") options.pulseUrl = value();
+    else if (flag === "--pulse-module") options.pulseModule = value();
+    else if (flag === "--max-hops") options.maxHops = Number(value());
+    else if (flag === "--json") options.json = true;
+    else if (flag === "--help" || flag === "-h") command = "help";
+    else throw new FiberRouteVirtualizerError(`Unknown option ${flag}`, "CLI_USAGE_ERROR");
+  }
+  return { command, request, options };
+}
+
+function help() {
+  return [
+    "Fiber Payment Route Virtualizer",
+    "",
+    "Usage:",
+    "  node route.mjs virtualize --source <node> --destination <node> --amount <amount> [--rpc <url>] --json",
+    "  route virtualize --source <node> --destination <node> --amount <amount> [--rpc <url>] --json",
+    "",
+    "Options:",
+    "  --source <node>              Source Fiber node pubkey",
+    "  --destination <node>         Destination Fiber node pubkey",
+    "  --amount <amount>            Amount as decimal or 0x integer",
+    "  --asset <asset>              Asset type. Default: CKB",
+    "  --rpc <url>                  Fiber RPC URL for graph discovery",
+    "  --pulse-url <url>            Pulse API URL for Component 1 state",
+    "  --pulse-module <path>        Import Pulse module and call collectFiberStateReport",
+    "  --max-hops <n>               Max route depth. Default: 6",
+    "  --json                       Print full JSON",
+  ].join("\n");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const { command, request, options } = parseCliArgs(process.argv.slice(2));
+  if (command === "help") {
+    console.log(help());
+  } else if (command === "virtualize") {
+    virtualizePayment(request, options)
+      .then((result) => console.log(options.json ? stringify(result) : routeText(result)))
+      .catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+      });
+  } else {
+    console.error(`Unknown command ${command}`);
+    process.exitCode = 1;
+  }
+}