@fibscope/agent 0.1.4 → 0.1.6

package/README.md

@@ -74,7 +74,7 @@ The agent pushes to `POST /agent/v1/report` with:
 
 ```json
 {
-  "agentVersion": "0.1.4",
+  "agentVersion": "0.1.6",
   "chain": "testnet",
   "collectedAt": 1710000000000,
   "publicIp": "54.179.226.154",
@@ -100,6 +100,12 @@ For an `API_NODE_PAYMENT`, the agent confirms the sender deposit and checks for
 
 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.
 
+## Owner N2N Test Lifecycle
+
+`N2N_PAYMENT` is an owner-authorized test command. It never confirms or charges an API test-wallet deposit. The selected source node checks its own funding wallet and existing routes, connects the receiving peer, opens a private one-way direct channel when needed, sends over Fiber, and optionally closes only the channel created by that test. FNN v0.8.1 uses dual-funded CKB channel construction, so the receiving node wallet must still provide its configured reserved capacity (commonly about 99 CKB) when a new channel is opened.
+
+When both FNN instances publish the same public IPv4 address, the agent dials the receiving P2P port through loopback so same-VPS nodes can complete the Fiber handshake. Command results include structured source selection, peer connection, channel creation, balance movement, Fiber transfer, optional close, and partial failure steps.
+
 ## Resilience
 
 Collection and transmission are independent loops:

package/index.mjs

@@ -33,7 +33,7 @@ import { virtualizePayment } from "./lib/route/route.mjs";
 import { chooseFnnInstance, describeFnnInstance, discoverFnnInstances, rpcResponds } from "./lib/fnn-discovery.mjs";
 import { buildObservedPeerAddress, discoverPublicIpv4, publishablePeerAddresses } from "./lib/public-peer-address.mjs";
 
-const AGENT_VERSION = "0.1.4";
+const AGENT_VERSION = "0.1.6";
 const DEFAULT_CONFIG_PATH = ".fiber/agent.json";
 const DEFAULT_STATUS_PATH = ".fiber/agent-status.json";
 const DEFAULT_PUSH_INTERVAL_MS = 15_000;
@@ -1145,6 +1145,7 @@ async function executeAndReportCommand(runtime, command) {
       command: command.command,
       status: "failed",
       error: message(error),
+      result: error?.commandResult && typeof error.commandResult === "object" ? error.commandResult : undefined,
     };
     await postCommandResult(config, body);
     console.warn(formatCommandEvent("failed", command, config, "error", body.error));
@@ -1180,6 +1181,9 @@ async function executeAgentCommand(runtime, command) {
   if (name === "API_NODE_PAYMENT" || name === "NODE_PAYMENT") {
     return acceptApiNodePayment(runtime, params);
   }
+  if (name === "N2N_PAYMENT" || name === "NODE_TO_NODE_PAYMENT") {
+    return acceptApiNodePayment(runtime, params, { ownerFunded: true });
+  }
   if (name === "API_WALLET_PAYMENT" || name === "WALLET_PAYMENT") {
     return acceptApiWalletPayment(runtime, params);
   }
@@ -1545,15 +1549,23 @@ async function acceptApiWalletPayment(runtime, params) {
   };
 }
 
-async function acceptApiNodePayment(runtime, params) {
+async function acceptApiNodePayment(runtime, params, options = {}) {
   const config = runtime.config ?? runtime;
+  const ownerFunded = options.ownerFunded === true;
   const info = await rpcCall(config.fiberRpcUrl, "node_info", [], config.timeoutMs);
   const depositTxHash = textValue(params.depositTxHash);
-  const deposit = depositTxHash ? await waitForCkbTransaction(config, depositTxHash, params) : undefined;
+  const deposit = !ownerFunded && depositTxHash ? await waitForCkbTransaction(config, depositTxHash, params) : undefined;
   const targetPubkey = normalizePeerPubkey(firstTextValue(params.receiverNode, params.targetPubkey, params.destinationNode, params.pubkey));
-  const peerAddress = firstTextValue(params.peerAddress, params.receiverPeerAddress, params.address);
+  const publishedPeerAddress = firstTextValue(params.peerAddress, params.receiverPeerAddress, params.address);
+  const peerAddress = resolveN2nPeerAddress(config, publishedPeerAddress, boolValue(params.sameHost, false));
   const provisionChannel = boolValue(params.provisionChannel, true);
   const closeChannelAfterPayment = provisionChannel && boolValue(params.closeChannelAfterPayment, false);
+  const source = {
+    nodeId: textValue(params.sourceNodeId) || undefined,
+    pubkey: normalizePeerPubkey(readNodeId(info)),
+    displayName: textValue(params.sourceNodeName) || undefined,
+    fundingBefore: ownerFunded ? await collectFundingState(config).catch(() => undefined) : undefined,
+  };
   let existingChannel;
   let routeProbe;
   try {
@@ -1587,11 +1599,14 @@ async function acceptApiNodePayment(runtime, params) {
         peerPubkey: targetPubkey,
         peerAddress,
         fundingAmount: firstTextValue(params.channelFundingAmount, params.totalDebit, params.amountShannons, params.amount),
+        oneWay: ownerFunded ? true : params.oneWay,
         connectFirst: true,
         waitUntilReady: true,
         waitTimeoutMs: positiveNumber(params.channelReadyTimeoutMs, 10 * 60_000),
         pollMs: positiveNumber(params.channelPollMs, 5_000),
-        public: true,
+        // FNN v0.8.1 rejects public one-way channels. N2N tests only need a
+        // direct source-to-receiver path, so keep their temporary channel private.
+        public: ownerFunded ? false : true,
       });
       paymentChannel = channelOpen.channel ?? await findReadyChannelForPeer(config.fiberRpcUrl, targetPubkey, config.timeoutMs);
     }
@@ -1603,6 +1618,67 @@ async function acceptApiNodePayment(runtime, params) {
       keysend: true,
     });
   } catch (error) {
+    const partialOpen = error?.commandResult && typeof error.commandResult === "object" ? error.commandResult : undefined;
+    if (!channelOpen && partialOpen) channelOpen = partialOpen;
+    if (!paymentChannel && partialOpen?.channel) paymentChannel = partialOpen.channel;
+    if (ownerFunded) {
+      let recovery;
+      let recoveryError;
+      try {
+        const openedChannelId = channelIdOf(paymentChannel);
+        if (channelOpen && openedChannelId) {
+          const openedState = channelStateName(paymentChannel);
+          if (isChannelReadyState(openedState)) {
+            recovery = await settleFiberChannel(runtime, { channelId: openedChannelId, force: false, feeRate: "1000" });
+            await waitForChannelClosed(config.fiberRpcUrl, openedChannelId, 10 * 60_000, 5_000);
+          } else {
+            const result = await rpcCall(config.fiberRpcUrl, "abandon_channel", [{ channel_id: openedChannelId }], config.timeoutMs);
+            recovery = {
+              ok: true,
+              action: "ABANDON_CHANNEL",
+              channelId: openedChannelId,
+              previousState: openedState || undefined,
+              result,
+            };
+          }
+        }
+      } catch (failure) {
+        recoveryError = message(failure);
+      }
+      const fundingAfter = await collectFundingState(config).catch(() => undefined);
+      const lifecycle = nodePaymentLifecycle({
+        source,
+        targetPubkey,
+        publishedPeerAddress,
+        peerAddress,
+        provisionChannel,
+        closeChannelAfterPayment,
+        existingChannel,
+        routeProbe,
+        channelOpen: channelOpen ?? partialOpen,
+        paymentChannel,
+        channelBeforePayment,
+        fiberPayment,
+        fundingAfter,
+        failure: message(error),
+        recovery,
+        recoveryError,
+      });
+      throw commandResultError(`N2N transfer failed while preparing the peer, channel, or Fiber payment: ${message(error)}. No API test wallet was charged.`, {
+        ok: false,
+        action: "N2N_PAYMENT",
+        mode: "Owner-funded node-to-node test",
+        paymentStatus: "failed",
+        source,
+        receiverNode: targetPubkey,
+        amount: textValue(params.amountShannons ?? params.amount) || undefined,
+        assetType: textValue(params.assetType ?? params.asset) || "CKB",
+        fiberPayment,
+        channelLifecycle: lifecycle,
+        fundingBefore: source.fundingBefore,
+        fundingAfter,
+      });
+    }
     let refund;
     let refundError;
     try {
@@ -1657,19 +1733,22 @@ async function acceptApiNodePayment(runtime, params) {
     }
   }
   let refreshed;
+  const fundingAfter = ownerFunded ? await collectFundingState(config).catch(() => undefined) : undefined;
   if (typeof runtime.collect === "function" && typeof runtime.push === "function") {
     refreshed = await pushWithRegistrationRetry(runtime, await runtime.collect(), {
-      intent: "api-node-payment-completed",
+      intent: ownerFunded ? "n2n-payment-completed" : "api-node-payment-completed",
       retryOnRateLimit: true,
       maxRateLimitRetries: 1,
     }).catch((error) => ({ ok: false, error: message(error) }));
   }
   return {
     ok: true,
-    action: "API_NODE_PAYMENT",
-    mode: "API-managed Fiber node payment",
+    action: ownerFunded ? "N2N_PAYMENT" : "API_NODE_PAYMENT",
+    mode: ownerFunded ? "Owner-funded node-to-node test" : "API-managed Fiber node payment",
     paymentStatus: "completed",
-    message: "Sender deposit is confirmed and the provider agent submitted the Fiber payment to the recipient node.",
+    message: ownerFunded
+      ? "The selected source node funded or reused the Fiber route and sent the N2N payment without charging an API test wallet."
+      : "Sender deposit is confirmed and the provider agent submitted the Fiber payment to the recipient node.",
     paymentId: textValue(params.paymentId) || undefined,
     quoteId: textValue(params.quoteId) || undefined,
     candidateId: textValue(params.candidateId) || undefined,
@@ -1687,29 +1766,36 @@ 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 },
+    source: ownerFunded ? { ...source, fundingAfter } : undefined,
+    fundingBefore: ownerFunded ? source.fundingBefore : undefined,
+    fundingAfter,
+    channelLifecycle: nodePaymentLifecycle({
+      source,
+      targetPubkey,
+      publishedPeerAddress,
+      peerAddress,
+      provisionChannel,
+      closeChannelAfterPayment,
+      existingChannel,
       routeProbe,
       channelOpen,
-      channelId: paymentChannelId || undefined,
-      providerBeforePayment: channelBeforePayment?.provider,
-      receiverBeforePayment: channelBeforePayment?.receiver,
-      providerAfterPayment: channelAfterPayment?.provider,
-      receiverAfterPayment: channelAfterPayment?.receiver,
+      paymentChannel,
+      paymentChannelId,
+      channelBeforePayment,
+      channelAfterPayment,
+      fiberPayment,
       channelClose,
-      providerAtClose: channelClosed?.provider,
-      receiverAtClose: channelClosed?.receiver,
-      finalChannelState: channelClosed?.state ?? channelAfterPayment?.state,
-    },
+      channelClosed,
+      fundingAfter,
+    }),
     fundingRefresh: refreshed,
     routeExecution: {
       status: "fiber_send_payment",
       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.",
+        ? "No viable route existed, so the source connected the receiving peer, opened a direct channel, sent the payment, and applied the requested close policy."
+        : ownerFunded
+          ? "The selected source node used its existing outbound Fiber liquidity."
+          : "The provider used existing outbound Fiber liquidity after confirming the payer deposit.",
     },
     node: {
       pubkey: normalizePeerPubkey(readNodeId(info)),
@@ -1719,6 +1805,86 @@ async function acceptApiNodePayment(runtime, params) {
   };
 }
 
+export function nodePaymentLifecycle(input) {
+  const channelOpen = input.channelOpen && typeof input.channelOpen === "object" ? input.channelOpen : undefined;
+  const connectResult = channelOpen?.connectResult;
+  const observedChannel = input.paymentChannel ?? channelOpen?.channel;
+  const channelId = input.paymentChannelId || channelIdOf(observedChannel);
+  const observedChannelState = channelStateName(observedChannel);
+  const existingRoute = Boolean(input.existingChannel) || input.routeProbe?.status === "success";
+  const peerStatus = existingRoute ? "skipped" : connectResult ? "completed" : input.failure ? "failed" : "pending";
+  const channelStatus = existingRoute ? "skipped" : isChannelReadyState(observedChannelState) ? "completed" : input.failure ? "failed" : "pending";
+  const paymentStatus = input.fiberPayment ? "completed" : input.failure ? "failed" : "pending";
+  const failedChannelAbandoned = input.recovery?.action === "ABANDON_CHANNEL" && input.recovery?.ok !== false;
+  const closeStatus = failedChannelAbandoned
+    ? "completed"
+    : !input.closeChannelAfterPayment
+    ? "skipped"
+    : input.channelClosed ? "completed"
+      : input.channelClose?.status === "failed" || input.failure ? "failed" : "pending";
+  return omitUndefined({
+    mode: channelOpen && !existingRoute ? "provisioned_direct_channel" : input.existingChannel ? "existing_direct_channel" : "existing_routed_liquidity",
+    provisionRequested: input.provisionChannel,
+    closeRequested: input.closeChannelAfterPayment,
+    source: {
+      nodeId: input.source?.nodeId,
+      pubkey: input.source?.pubkey,
+      displayName: input.source?.displayName,
+      fundingBefore: input.source?.fundingBefore,
+      fundingAfter: input.fundingAfter,
+    },
+    peer: {
+      pubkey: input.targetPubkey,
+      publishedAddress: input.publishedPeerAddress || undefined,
+      dialAddress: input.peerAddress || undefined,
+      sameHostLoopback: Boolean(input.publishedPeerAddress && input.peerAddress && input.publishedPeerAddress !== input.peerAddress),
+    },
+    routeProbe: input.routeProbe,
+    peerConnect: connectResult,
+    channelOpen,
+    channelId: channelId || undefined,
+    providerBeforePayment: input.channelBeforePayment?.provider,
+    receiverBeforePayment: input.channelBeforePayment?.receiver,
+    providerAfterPayment: input.channelAfterPayment?.provider,
+    receiverAfterPayment: input.channelAfterPayment?.receiver,
+    channelClose: input.channelClose,
+    providerAtClose: input.channelClosed?.provider,
+    receiverAtClose: input.channelClosed?.receiver,
+    finalChannelState: input.channelClosed?.state ?? input.channelAfterPayment?.state,
+    recovery: input.recovery,
+    recoveryError: input.recoveryError,
+    failure: input.failure,
+    steps: [
+      { key: "source_selected", label: "Source node selected", status: "completed", detail: input.source?.displayName || shortText(input.source?.pubkey, 10, 8) },
+      { key: "peer_connect", label: "Receiving peer connected", status: peerStatus, detail: existingRoute ? "Existing route does not require a new direct peer connection." : input.failure && !connectResult ? input.failure : input.peerAddress },
+      { key: "channel_open", label: "Channel ready", status: channelStatus, detail: existingRoute ? "Existing Fiber liquidity selected." : channelStatus === "completed" && channelId ? `Channel ${shortText(channelId, 10, 8)}` : input.failure },
+      { key: "fiber_transfer", label: "Funds moved over Fiber", status: paymentStatus, detail: input.fiberPayment ? `Payment ${shortText(input.fiberPayment.paymentHash ?? input.fiberPayment.payment_hash ?? input.fiberPayment.targetPubkey, 10, 8)}` : input.failure },
+      ...(failedChannelAbandoned
+        ? [{ key: "channel_cleanup", label: "Failed channel abandoned", status: closeStatus, detail: `Released pending channel ${shortText(channelId, 10, 8)}` }]
+        : input.closeChannelAfterPayment
+          ? [{ key: "channel_close", label: "Provisioned channel closed", status: closeStatus, detail: input.channelClose?.error ?? input.channelClosed?.state ?? (input.failure ? "Not attempted because the channel never became ready." : undefined) }]
+          : []),
+    ],
+  });
+}
+
+export function resolveN2nPeerAddress(config, address, sameHost) {
+  const normalized = textValue(address);
+  if (!normalized) return "";
+  const addressIp = /\/ip4\/([^/]+)/i.exec(normalized)?.[1];
+  const localPublicIp = textValue(config.publicIp);
+  if ((sameHost || (addressIp && localPublicIp && addressIp === localPublicIp)) && addressIp) {
+    return normalized.replace(/\/ip4\/[^/]+/i, "/ip4/127.0.0.1");
+  }
+  return normalized;
+}
+
+function commandResultError(errorMessage, commandResult) {
+  const error = new Error(errorMessage);
+  error.commandResult = commandResult;
+  return error;
+}
+
 async function waitForCkbTransaction(config, txHash, params = {}) {
   const rpcUrl = resolveCkbIndexerUrl(config);
   if (!rpcUrl) throw new Error("No CKB RPC URL is configured for deposit confirmation.");
@@ -2061,6 +2227,9 @@ async function openFiberChannel(config, params) {
     public: boolValue(params.public ?? params.publicChannel, true),
   };
   if (params.oneWay !== undefined || params.one_way !== undefined) openRequest.one_way = boolValue(params.oneWay ?? params.one_way, false);
+  if (openRequest.one_way && openRequest.public) {
+    throw new Error("FNN does not allow a channel to be both public and one-way.");
+  }
   if (params.fundingUdtTypeScript ?? params.funding_udt_type_script) openRequest.funding_udt_type_script = params.fundingUdtTypeScript ?? params.funding_udt_type_script;
   if (params.commitmentFeeRate ?? params.commitment_fee_rate) openRequest.commitment_fee_rate = quantity(params.commitmentFeeRate ?? params.commitment_fee_rate);
   if (params.fundingFeeRate ?? params.funding_fee_rate) openRequest.funding_fee_rate = quantity(params.fundingFeeRate ?? params.funding_fee_rate);
@@ -2072,37 +2241,57 @@ async function openFiberChannel(config, params) {
 
   const fundingCheck = await assertChannelFundingAvailable(config, openRequest.funding_amount);
   let connectResult;
-  const connectFirst = boolValue(params.connectFirst, true) && !boolValue(params.skipConnect, false);
-  if (connectFirst) {
-    connectResult = await ensurePeerConnected(config, peer, pubkey);
-  }
-  const openResult = await openChannelWhenPeerReady(config, peer, pubkey, openRequest, params);
+  let openResult;
   let channelWatch;
-  if (!boolValue(params.wait, false) && !boolValue(params.waitUntilReady, false)) {
-    channelWatch = await watchForImmediateChannelFailure(
-      config.fiberRpcUrl,
-      pubkey,
-      positiveNumber(params.failureWatchMs ?? config.channelFailureWatchMs, DEFAULT_CHANNEL_FAILURE_WATCH_MS),
-      positiveNumber(params.failurePollMs ?? params.pollMs ?? config.channelFailurePollMs, DEFAULT_CHANNEL_FAILURE_POLL_MS),
-    );
-  }
-  const result = {
-    ok: true,
-    action: "OPEN_CHANNEL",
-    peerPubkey: pubkey,
-    peer: peer.meta,
-    peerAddress: peer.address,
-    fundingAmount: openRequest.funding_amount,
-    public: openRequest.public,
-    fundingCheck,
-    connectResult,
-    openResult,
-    channelWatch,
-  };
-  if (boolValue(params.wait, false) || boolValue(params.waitUntilReady, false)) {
-    result.channel = await waitForChannel(config.fiberRpcUrl, pubkey, positiveNumber(params.waitTimeoutMs, 20 * 60_000), positiveNumber(params.pollMs, 10_000));
+  const connectFirst = boolValue(params.connectFirst, true) && !boolValue(params.skipConnect, false);
+  try {
+    if (connectFirst) connectResult = await ensurePeerConnected(config, peer, pubkey);
+    openResult = await openChannelWhenPeerReady(config, peer, pubkey, openRequest, params);
+    if (!boolValue(params.wait, false) && !boolValue(params.waitUntilReady, false)) {
+      channelWatch = await watchForImmediateChannelFailure(
+        config.fiberRpcUrl,
+        pubkey,
+        positiveNumber(params.failureWatchMs ?? config.channelFailureWatchMs, DEFAULT_CHANNEL_FAILURE_WATCH_MS),
+        positiveNumber(params.failurePollMs ?? params.pollMs ?? config.channelFailurePollMs, DEFAULT_CHANNEL_FAILURE_POLL_MS),
+      );
+    }
+    const result = {
+      ok: true,
+      action: "OPEN_CHANNEL",
+      peerPubkey: pubkey,
+      peer: peer.meta,
+      peerAddress: peer.address,
+      fundingAmount: openRequest.funding_amount,
+      public: openRequest.public,
+      oneWay: openRequest.one_way === true,
+      fundingCheck,
+      connectResult,
+      openResult,
+      channelWatch,
+    };
+    if (boolValue(params.wait, false) || boolValue(params.waitUntilReady, false)) {
+      result.channel = await waitForChannel(config.fiberRpcUrl, pubkey, positiveNumber(params.waitTimeoutMs, 20 * 60_000), positiveNumber(params.pollMs, 10_000));
+    }
+    return result;
+  } catch (error) {
+    const observed = error?.commandResult && typeof error.commandResult === "object" ? error.commandResult : undefined;
+    throw commandResultError(message(error), {
+      ok: false,
+      action: "OPEN_CHANNEL",
+      peerPubkey: pubkey,
+      peer: peer.meta,
+      peerAddress: peer.address,
+      fundingAmount: openRequest.funding_amount,
+      public: openRequest.public,
+      oneWay: openRequest.one_way === true,
+      fundingCheck,
+      connectResult,
+      openResult,
+      channelWatch,
+      channel: observed?.channel,
+      failure: message(error),
+    });
   }
-  return result;
 }
 
 async function settleFiberChannel(runtime, params) {
@@ -3003,7 +3192,25 @@ async function waitForChannel(rpcUrl, pubkey, timeoutMs, pollMs) {
     if (failed) throw new Error(describeChannelTerminalFailure(failed));
     await sleep(pollMs);
   }
-  throw new Error(`Timed out waiting for channel readiness. Last channel: ${JSON.stringify(lastChannel ?? null)}`);
+  const fundingHint = isAwaitingRemoteFundingCollaboration(lastChannel)
+    ? " The receiving FNN did not complete funding collaboration. A CKB channel acceptor must provide its configured reserved capacity (commonly about 99 CKB), even for a private one-way channel. Fund the receiving node wallet and inspect its FNN logs."
+    : "";
+  throw commandResultError(`Timed out waiting for channel readiness.${fundingHint} Last channel: ${JSON.stringify(lastChannel ?? null)}`, {
+    channel: lastChannel,
+    channelId: channelIdOf(lastChannel) || undefined,
+  });
+}
+
+function isAwaitingRemoteFundingCollaboration(channel) {
+  const state = channel?.state && typeof channel.state === "object" ? channel.state : {};
+  const name = textValue(state.state_name ?? state.stateName ?? channel?.state_name ?? channel?.stateName).toLowerCase();
+  const flags = textValue(state.state_flags ?? state.stateFlags ?? channel?.state_flags ?? channel?.stateFlags).toLowerCase();
+  return name === "collaboratingfundingtx" && flags.includes("awaiting_remote_tx_collaboration_msg");
+}
+
+function isChannelReadyState(state) {
+  const normalized = textValue(state).toLowerCase();
+  return normalized === "channelready" || normalized === "open";
 }
 
 async function watchForImmediateChannelFailure(rpcUrl, pubkey, timeoutMs, pollMs) {

package/package.json

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