@fibscope/agent 0.1.2 → 0.1.4

package/.env.example

@@ -5,3 +5,5 @@ FIBSCOPE_AGENT_CHAIN=testnet
 FIBSCOPE_AGENT_FIBER_RPC_URL=http://127.0.0.1:8227
 FIBSCOPE_AGENT_PUSH_INTERVAL_MS=15000
 FIBSCOPE_AGENT_PUBLIC_PROFILE=false
+# Optional override; by default the agent discovers its own public IPv4.
+# FIBSCOPE_AGENT_PUBLIC_IP=54.179.226.154

package/README.md

@@ -48,7 +48,7 @@ The agent also supports `.fiber/agent.json`:
 }
 ```
 
-The hosted gateway returns the public IPv4 it observes for the authenticated agent request. The agent combines that IP with the local FNN P2P port and reports the resulting public multiaddr. Loopback, wildcard, private, and documentation addresses are never published. Set `peerAddress` only when intentionally overriding automatic discovery with another publicly dialable multiaddr.
+The agent discovers its own public IPv4 through `https://api.ipify.org`, combines it with the local FNN P2P port, and includes both the IP and resulting public multiaddr in registration and report requests. Loopback, wildcard, private, and documentation addresses are never published. Set `FIBSCOPE_AGENT_PUBLIC_IP` only when intentionally overriding automatic discovery, or `FIBSCOPE_AGENT_PUBLIC_IP_URL` to use another compatible JSON or plain-text discovery endpoint.
 
 ## Commands
 
@@ -74,9 +74,11 @@ The agent pushes to `POST /agent/v1/report` with:
 
 ```json
 {
-  "agentVersion": "0.1.2",
+  "agentVersion": "0.1.4",
   "chain": "testnet",
   "collectedAt": 1710000000000,
+  "publicIp": "54.179.226.154",
+  "peerAddress": "/ip4/54.179.226.154/tcp/8228",
   "node": {},
   "peers": [],
   "channels": [],
@@ -92,6 +94,12 @@ Fibscope authenticates this with `x-agent-token`. This is an agent key for local
 
 Before the first push, the agent registers the local Fiber node with `POST /agent/v1/register`. That saves the node owner, Fiber node id, display name, chain, public profile setting, and the latest local node details in the hosted database. If the agent key is already attached to a different registered Fiber node, set `overwriteNodeRegistration` to `true` only when you intentionally want this agent to replace that old node binding.
 
+## API Node Payment Lifecycle
+
+For an `API_NODE_PAYMENT`, the agent confirms the sender deposit and checks for a viable existing Fiber route. When the quote permits provisioning and no route exists, it connects the receiving peer, opens a direct funded channel, waits for readiness, and sends the payment. A close-after-test policy applies only to the channel opened by that payment; existing channels are never closed automatically.
+
+The command result includes provider and receiver balance views before payment, after payment, and at close. The receiver view reverses the provider-local and provider-remote balances so the receiving channel's credited local balance and remaining inbound capacity are explicit.
+
 ## Resilience
 
 Collection and transmission are independent loops:
@@ -117,7 +125,7 @@ The Agent Setup page generates this command from a masked password field. The `f
 ## NPM Usage
 
 ```bash
-npm install -g @fibscope/agent@0.1.2 pm2 && agent init && pm2 start "$(command -v agent)" --name fibscope-agent --interpreter node -- start && pm2 save
+npm install -g @fibscope/agent pm2 && agent init && pm2 start "$(command -v agent)" --name fibscope-agent --interpreter none -- start && pm2 save
 ```
 
 Or run without a global install:

package/index.mjs

@@ -31,15 +31,17 @@ import { createTelemetryCollector } from "./lib/observe/collector.mjs";
 import { recommend } from "./lib/bridge/recommendation.mjs";
 import { virtualizePayment } from "./lib/route/route.mjs";
 import { chooseFnnInstance, describeFnnInstance, discoverFnnInstances, rpcResponds } from "./lib/fnn-discovery.mjs";
-import { buildObservedPeerAddress, peerTcpPort, publishablePeerAddresses } from "./lib/public-peer-address.mjs";
+import { buildObservedPeerAddress, discoverPublicIpv4, publishablePeerAddresses } from "./lib/public-peer-address.mjs";
 
-const AGENT_VERSION = "0.1.2";
+const AGENT_VERSION = "0.1.4";
 const DEFAULT_CONFIG_PATH = ".fiber/agent.json";
 const DEFAULT_STATUS_PATH = ".fiber/agent-status.json";
 const DEFAULT_PUSH_INTERVAL_MS = 15_000;
 const MAX_BACKOFF_MS = 300_000;
 const DEFAULT_PULSE_MODULE = new URL("./lib/pulse/index.mjs", import.meta.url).href;
 const DEFAULT_FNN_PREFLIGHT_TIMEOUT_MS = 2_500;
+const DEFAULT_PUBLIC_IP_DISCOVERY_URL = "https://api.ipify.org?format=json";
+const DEFAULT_PUBLIC_IP_DISCOVERY_TIMEOUT_MS = 5_000;
 const DEFAULT_REPORT_URL = "https://ejchwtvdxpyojxsursmh.supabase.co/functions/v1/fibscope-gateway/agent/v1/report";
 const AGENT_ENV_PATHS = [resolve("agent/.env"), resolve(".env")];
 const ENV_REPORT_URL = "FIBGATE";
@@ -367,9 +369,8 @@ export async function createRuntime(options = {}) {
   const statusPath = resolve(options.status ?? DEFAULT_STATUS_PATH);
   const config = await loadConfig(configPath, options);
   await ensureFnnPreflight(config, statusPath, options);
+  await resolveAgentPublicIdentity(config);
   const remoteConfig = await fetchAgentConfig(config).catch(() => undefined);
-  config.observedPublicIp = remoteConfig?.observedPublicIp ?? config.observedPublicIp;
-  config.observedPeerAddress = remoteConfig?.observedPeerAddress ?? config.observedPeerAddress;
   if (!config.nodeDisplayName && remoteConfig?.node?.displayName) {
     config.nodeDisplayName = remoteConfig.node.displayName;
   }
@@ -481,6 +482,8 @@ export async function collectReport(config, previousReport = undefined) {
     agentVersion: AGENT_VERSION,
     chain: config.chain ?? "testnet",
     collectedAt,
+    publicIp: config.publicIp,
+    peerAddress: config.publicPeerAddress,
     node: state.node,
     peers: state.peers ?? [],
     channels: state.channels ?? [],
@@ -509,8 +512,8 @@ async function enrichReportNode(node, config) {
     ...await inferPeerAddressesFromLocalFnn(config),
   ]);
   const addresses = publishablePeerAddresses([
-    config.observedPeerAddress,
-    buildObservedPeerAddress(config.observedPublicIp, [config.fnnP2pListenAddr, ...candidates]),
+    config.publicPeerAddress,
+    buildObservedPeerAddress(config.publicIp, [config.fnnP2pListenAddr, ...candidates]),
     ...candidates,
   ]);
   const enriched = {
@@ -1548,12 +1551,111 @@ async function acceptApiNodePayment(runtime, params) {
   const depositTxHash = textValue(params.depositTxHash);
   const deposit = depositTxHash ? await waitForCkbTransaction(config, depositTxHash, params) : undefined;
   const targetPubkey = normalizePeerPubkey(firstTextValue(params.receiverNode, params.targetPubkey, params.destinationNode, params.pubkey));
-  const fiberPayment = await sendFiberPayment(config, {
-    ...params,
-    targetPubkey,
-    amountShannons: textValue(params.amountShannons ?? params.amount),
-    keysend: true,
-  });
+  const peerAddress = firstTextValue(params.peerAddress, params.receiverPeerAddress, params.address);
+  const provisionChannel = boolValue(params.provisionChannel, true);
+  const closeChannelAfterPayment = provisionChannel && boolValue(params.closeChannelAfterPayment, false);
+  let existingChannel;
+  let routeProbe;
+  try {
+    existingChannel = await findReadyChannelForPeer(config.fiberRpcUrl, targetPubkey, config.timeoutMs).catch(() => undefined);
+    try {
+      routeProbe = await simulateFiberRoute(config, {
+        destinationNode: targetPubkey,
+        amountShannons: textValue(params.amountShannons ?? params.amount),
+        assetType: textValue(params.assetType ?? params.asset) || "CKB",
+      });
+    } catch (error) {
+      routeProbe = { status: "failed", error: message(error) };
+    }
+  } catch (error) {
+    routeProbe = { status: "failed", error: message(error) };
+  }
+  const existingRouteReady = routeProbe?.status === "success" || Boolean(existingChannel);
+  let channelOpen;
+  let paymentChannel = existingChannel;
+  let channelBeforePayment;
+  let fiberPayment;
+  try {
+    if (!existingRouteReady) {
+      if (!provisionChannel) {
+        throw new Error(`No viable Fiber route to ${shortText(targetPubkey, 10, 8)} and direct channel provisioning is disabled.`);
+      }
+      if (!peerAddress) {
+        throw new Error(`No viable Fiber route to ${shortText(targetPubkey, 10, 8)} and the receiving node has no public peer address for automatic connection.`);
+      }
+      channelOpen = await openFiberChannel(config, {
+        peerPubkey: targetPubkey,
+        peerAddress,
+        fundingAmount: firstTextValue(params.channelFundingAmount, params.totalDebit, params.amountShannons, params.amount),
+        connectFirst: true,
+        waitUntilReady: true,
+        waitTimeoutMs: positiveNumber(params.channelReadyTimeoutMs, 10 * 60_000),
+        pollMs: positiveNumber(params.channelPollMs, 5_000),
+        public: true,
+      });
+      paymentChannel = channelOpen.channel ?? await findReadyChannelForPeer(config.fiberRpcUrl, targetPubkey, config.timeoutMs);
+    }
+    channelBeforePayment = channelLiquiditySnapshot(paymentChannel);
+    fiberPayment = await sendFiberPayment(config, {
+      ...params,
+      targetPubkey,
+      amountShannons: textValue(params.amountShannons ?? params.amount),
+      keysend: true,
+    });
+  } catch (error) {
+    let refund;
+    let refundError;
+    try {
+      const openedChannelId = channelIdOf(paymentChannel);
+      if (channelOpen && openedChannelId) {
+        await settleFiberChannel(runtime, { channelId: openedChannelId, force: false, feeRate: "1000" });
+        await waitForChannelClosed(config.fiberRpcUrl, openedChannelId, 10 * 60_000, 5_000);
+      }
+      refund = await executeProviderWalletPayout(config, {
+        receiverWallet: textValue(params.senderWallet),
+        amount: textValue(params.totalDebit ?? params.depositAmount),
+        paymentId: textValue(params.paymentId),
+        depositTxHash,
+      });
+    } catch (failure) {
+      refundError = message(failure);
+    }
+    const refundDetail = refund?.txHash
+      ? ` Refund broadcast to the sender: ${refund.txHash}.`
+      : ` Automatic refund also failed: ${refundError ?? "unknown refund error"}.`;
+    throw new Error(`Fiber node delivery failed after deposit confirmation: ${message(error)}.${refundDetail}`);
+  }
+  const paymentChannelId = channelIdOf(paymentChannel);
+  const channelAfterPaymentRaw = paymentChannelId
+    ? await waitForChannelBalanceChange(
+        config.fiberRpcUrl,
+        paymentChannelId,
+        channelBeforePayment,
+        positiveNumber(params.channelBalanceTimeoutMs, 60_000),
+        positiveNumber(params.channelBalancePollMs, 2_000),
+      ).catch(() => undefined)
+    : await findReadyChannelForPeer(config.fiberRpcUrl, targetPubkey, config.timeoutMs).catch(() => undefined);
+  const channelAfterPayment = channelLiquiditySnapshot(channelAfterPaymentRaw);
+  let channelClose;
+  let channelClosed;
+  if (channelOpen && closeChannelAfterPayment && paymentChannelId) {
+    try {
+      channelClose = await settleFiberChannel(runtime, {
+        channelId: paymentChannelId,
+        force: false,
+        feeRate: params.channelCloseFeeRate ?? params.feeRate ?? "1000",
+      });
+      const closed = await waitForChannelClosed(
+        config.fiberRpcUrl,
+        paymentChannelId,
+        positiveNumber(params.channelCloseTimeoutMs, 10 * 60_000),
+        positiveNumber(params.channelPollMs, 5_000),
+      );
+      channelClosed = channelLiquiditySnapshot(closed);
+    } catch (error) {
+      channelClose = { status: "failed", error: message(error) };
+    }
+  }
   let refreshed;
   if (typeof runtime.collect === "function" && typeof runtime.push === "function") {
     refreshed = await pushWithRegistrationRetry(runtime, await runtime.collect(), {
@@ -1585,10 +1687,29 @@ async function acceptApiNodePayment(runtime, params) {
     depositAmount: textValue(params.depositAmount) || undefined,
     deposit,
     fiberPayment,
+    channelLifecycle: {
+      mode: channelOpen ? "provisioned_direct_channel" : existingChannel ? "existing_direct_channel" : "existing_routed_liquidity",
+      provisionRequested: provisionChannel,
+      closeRequested: closeChannelAfterPayment,
+      peer: { pubkey: targetPubkey, address: peerAddress || undefined },
+      routeProbe,
+      channelOpen,
+      channelId: paymentChannelId || undefined,
+      providerBeforePayment: channelBeforePayment?.provider,
+      receiverBeforePayment: channelBeforePayment?.receiver,
+      providerAfterPayment: channelAfterPayment?.provider,
+      receiverAfterPayment: channelAfterPayment?.receiver,
+      channelClose,
+      providerAtClose: channelClosed?.provider,
+      receiverAtClose: channelClosed?.receiver,
+      finalChannelState: channelClosed?.state ?? channelAfterPayment?.state,
+    },
     fundingRefresh: refreshed,
     routeExecution: {
       status: "fiber_send_payment",
-      reason: "Fiber node recipients are channel endpoints, so the provider uses outbound Fiber liquidity after confirming the payer deposit.",
+      reason: channelOpen
+        ? "No viable route existed, so the provider connected the receiving peer, opened a direct channel, sent the payment, and applied the requested close policy."
+        : "The provider used existing outbound Fiber liquidity after confirming the payer deposit.",
     },
     node: {
       pubkey: normalizePeerPubkey(readNodeId(info)),
@@ -2047,6 +2168,78 @@ async function findChannelById(rpcUrl, channelId, timeoutMs) {
   return channels.find((channel) => textValue(channel?.channel_id ?? channel?.channelId ?? channel?.id).toLowerCase() === normalized);
 }
 
+async function findReadyChannelForPeer(rpcUrl, pubkey, timeoutMs) {
+  const response = await rpcCall(rpcUrl, "list_channels", [{ pubkey, include_closed: true }], timeoutMs);
+  const channels = Array.isArray(response?.channels) ? response.channels : Array.isArray(response) ? response : [];
+  return channels.find((channel) => {
+    const state = channelStateName(channel).toLowerCase();
+    return state === "channelready" || state === "open";
+  });
+}
+
+async function waitForChannelClosed(rpcUrl, channelId, timeoutMs, pollMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastChannel;
+  while (Date.now() < deadline) {
+    lastChannel = await findChannelById(rpcUrl, channelId, Math.min(pollMs, 10_000)).catch(() => lastChannel);
+    const state = channelStateName(lastChannel).toLowerCase();
+    if (["closed", "abandoned"].includes(state)) return lastChannel;
+    await sleep(pollMs);
+  }
+  return {
+    ...asObject(lastChannel),
+    channel_id: channelId,
+    close_wait_status: "timeout",
+    close_wait_timeout_ms: timeoutMs,
+  };
+}
+
+async function waitForChannelBalanceChange(rpcUrl, channelId, before, timeoutMs, pollMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastChannel;
+  while (Date.now() < deadline) {
+    lastChannel = await findChannelById(rpcUrl, channelId, Math.min(pollMs, 10_000)).catch(() => lastChannel);
+    const current = channelLiquiditySnapshot(lastChannel);
+    if (!before || channelBalanceChanged(before, current)) return lastChannel;
+    await sleep(pollMs);
+  }
+  return lastChannel;
+}
+
+function channelBalanceChanged(before, after) {
+  if (!before || !after) return false;
+  return before.provider.localBalance !== after.provider.localBalance
+    || before.provider.remoteBalance !== after.provider.remoteBalance;
+}
+
+function channelIdOf(channel) {
+  return firstTextValue(channel?.channel_id, channel?.channelId, channel?.id);
+}
+
+function channelLiquiditySnapshot(channel) {
+  if (!channel || typeof channel !== "object") return undefined;
+  const localBalance = amountString(channel.local_balance ?? channel.localBalance ?? channel.outbound_liquidity ?? channel.outboundLiquidity);
+  const remoteBalance = amountString(channel.remote_balance ?? channel.remoteBalance ?? channel.inbound_liquidity ?? channel.inboundLiquidity);
+  const capacity = amountString(channel.funding_amount ?? channel.fundingAmount ?? channel.capacity);
+  return {
+    channelId: channelIdOf(channel) || undefined,
+    state: channelStateName(channel),
+    capacity,
+    provider: {
+      localBalance,
+      outbound: localBalance,
+      remoteBalance,
+      inbound: remoteBalance,
+    },
+    receiver: {
+      localBalance: remoteBalance,
+      outbound: remoteBalance,
+      remoteBalance: localBalance,
+      inbound: localBalance,
+    },
+  };
+}
+
 async function assertNotLocalPeer(config, pubkey) {
   try {
     const info = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs);
@@ -2294,6 +2487,8 @@ async function loadConfig(configPath, options = {}) {
       ckbIndexerUrl: process.env.FIBSCOPE_AGENT_CKB_INDEXER_URL,
       walletPath: process.env.FIBSCOPE_AGENT_WALLET_PATH ?? envValue(ENV_WALLET_PATH),
       peerAddress: process.env.FIBSCOPE_AGENT_PEER_ADDRESS,
+      publicIp: process.env.FIBSCOPE_AGENT_PUBLIC_IP,
+      publicIpDiscoveryUrl: process.env.FIBSCOPE_AGENT_PUBLIC_IP_URL,
     };
     label = "agent/.env";
   } else if (!existsSync(configPath)) {
@@ -2315,10 +2510,6 @@ function resolveReportUrl(config = {}) {
 
 async function fetchAgentConfig(config) {
   const configUrl = new URL(config.configUrl ?? config.reportUrl.replace(/\/report\/?$/, "/config"));
-  configUrl.searchParams.set("p2pPort", String(peerTcpPort([
-    config.fnnP2pListenAddr,
-    ...configuredPeerAddresses(config),
-  ], 8228)));
   const response = await fetch(configUrl, {
     headers: {
       "x-agent-token": config.agentToken,
@@ -2368,6 +2559,8 @@ async function registerAgentNode(config, report, remoteConfig) {
       displayName: config.nodeDisplayName ?? remoteConfig?.node?.displayName,
       publicProfileEnabled: Boolean(report.publicProfileEnabled),
       overwrite: Boolean(config.overwriteNodeRegistration),
+      publicIp: report.publicIp ?? config.publicIp,
+      peerAddress: report.peerAddress ?? config.publicPeerAddress,
       node: report.node ?? {},
     }),
   });
@@ -2505,6 +2698,8 @@ function normalizeConfig(config, label) {
     ckbRpcUrl: process.env.FIBSCOPE_AGENT_CKB_RPC_URL ?? envValue(ENV_CKB_RPC_URL) ?? config.ckbRpcUrl,
     ckbIndexerUrl: process.env.FIBSCOPE_AGENT_CKB_INDEXER_URL ?? config.ckbIndexerUrl,
     walletPath: process.env.FIBSCOPE_AGENT_WALLET_PATH ?? envValue(ENV_WALLET_PATH) ?? config.walletPath,
+    publicIp: process.env.FIBSCOPE_AGENT_PUBLIC_IP ?? config.publicIp,
+    publicIpDiscoveryUrl: process.env.FIBSCOPE_AGENT_PUBLIC_IP_URL ?? config.publicIpDiscoveryUrl,
     pushIntervalMs: positiveNumber(config.pushIntervalMs, DEFAULT_PUSH_INTERVAL_MS),
     commandPollMs: positiveNumber(config.commandPollMs, DEFAULT_COMMAND_POLL_MS),
     knownPeerReconnectMs: positiveNumber(config.knownPeerReconnectMs, DEFAULT_KNOWN_PEER_RECONNECT_MS),
@@ -2516,6 +2711,25 @@ function normalizeConfig(config, label) {
   return normalized;
 }
 
+async function resolveAgentPublicIdentity(config) {
+  try {
+    const publicIp = await discoverPublicIpv4({
+      publicIp: config.publicIp,
+      endpoint: config.publicIpDiscoveryUrl ?? DEFAULT_PUBLIC_IP_DISCOVERY_URL,
+      timeoutMs: config.publicIpDiscoveryTimeoutMs ?? DEFAULT_PUBLIC_IP_DISCOVERY_TIMEOUT_MS,
+    });
+    config.publicIp = publicIp;
+    config.publicPeerAddress = buildObservedPeerAddress(publicIp, [
+      config.fnnP2pListenAddr,
+      ...configuredPeerAddresses(config),
+    ]);
+  } catch (error) {
+    console.warn(`Fibscope agent public IP unavailable: ${message(error)}`);
+    config.publicIp = undefined;
+    config.publicPeerAddress = publishablePeerAddresses(configuredPeerAddresses(config))[0];
+  }
+}
+
 async function bindAgentConfigToFnn(config, label, options = {}) {
   const next = { ...config };
   if (options.fiberRpcUrl) {

package/lib/public-peer-address.mjs

@@ -5,6 +5,39 @@ export function buildObservedPeerAddress(observedPublicIp, candidates = [], fall
   return `/ip4/${ip}/tcp/${port}`;
 }
 
+export async function discoverPublicIpv4(options = {}) {
+  const configured = normalizePublicIpv4(options.publicIp);
+  if (configured) return configured;
+
+  const endpoint = String(options.endpoint ?? "https://api.ipify.org?format=json").trim();
+  if (!endpoint) throw new Error("Public IPv4 discovery endpoint is not configured.");
+  const timeoutMs = positiveTimeout(options.timeoutMs, 5_000);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await (options.fetchImpl ?? fetch)(endpoint, {
+      headers: { accept: "application/json, text/plain;q=0.9" },
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const body = await response.text();
+    let candidate = body;
+    try {
+      candidate = JSON.parse(body)?.ip ?? body;
+    } catch {
+      // Configurable plain-text IP endpoints are supported too.
+    }
+    const publicIp = normalizePublicIpv4(candidate);
+    if (!publicIp) throw new Error("response did not contain a public IPv4 address");
+    return publicIp;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Public IPv4 discovery failed at ${endpoint}: ${detail}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 export function peerTcpPort(values, fallback = 8228) {
   for (const value of flatStrings(values)) {
     const match = value.match(/\/tcp\/(\d{1,5})(?:\/|$)/i);
@@ -52,3 +85,8 @@ function flatStrings(values) {
   const input = Array.isArray(values) ? values.flat(Infinity) : [values];
   return input.map((value) => String(value ?? "").trim()).filter(Boolean);
 }
+
+function positiveTimeout(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fibscope/agent",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Fibscope Agent for Fiber node owners.",
   "bin": {