From 1464b1b24df56f21afbc985820e90da498f55653 Mon Sep 17 00:00:00 2001
From: archipelago <archipelago@localhost>
Date: Tue, 1 Sep 2026 11:40:25 -0400
Subject: [PATCH] fix(wallet): the Lightning funding gate states the node's
 real channel state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"LND thinks I do not have a channel" while the wallet showed plenty of
liquidity (framework-pt, 2026-09-01): the send gate sums outbound over
FULLY-OPEN channels only, which is correct — a just-opened channel
sits in LND's pending list until it has ~3 confirmations, and an
open channel can have all its balance on the far side — but the modal
then claimed the node had NO channel at all, in every one of those
states, and pointed the user at opening another one.

The gate already fetched the full channel list; it now records WHY
liquidity is zero and the modal says the truth per state:
- pending channels -> "your new channel is waiting for on-chain
  confirmations, it unlocks automatically, nothing is needed from you"
  (and no "Open a channel" button — that would send the user to fix
  a problem they don't have, possibly opening a second channel)
- open channels, zero on the needed side -> "balance is on the far
  side — you can receive but there's nothing to send right now"
- payment refused with a routing/liquidity error -> says so, instead
  of claiming no channels
- only a genuinely channel-less node keeps the open-one guidance

Eleven unit tests pin the state machine, including the regression
case (pending-only -> 'pending', not 'none') and fail-open on RPC
errors.
---
 CHANGELOG.md                                  |  2 +
 .../src/components/LightningRequiredModal.vue | 67 ++++++++++++---
 .../__tests__/useLightningRequired.test.ts    | 85 +++++++++++++++++++
 .../src/composables/useLightningRequired.ts   | 41 ++++++++-
 .../src/views/settings/AccountInfoSection.vue |  1 +
 5 files changed, 182 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b58cd470..de9d3f82 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,8 @@
 
 - **Portainer's first-run token is in the app page, not buried in "server logs."** New Portainer versions mint a one-time setup token on a fresh install and print it only to the container logs — on an appliance that meant telling the user to go read a server log to get into their own app. The token now appears in the same launch interstitial as app login credentials (with a copy button), only while first-run setup is actually pending; once the admin account exists the card disappears on its own.
 
+- **The Lightning wallet states the node's real funding state instead of "you have no channel."** Trying to send while a freshly opened channel was still waiting for on-chain confirmations — or when all its balance sits on the far side — raised a modal that claimed the node had no channel at all (the outbound sum is legitimately zero in both states). The funding gate now reads the channel list it already fetched: a confirming channel gets "it unlocks automatically once confirmed, nothing is needed from you", a far-side balance gets "you can receive, but there's nothing to send right now", a routing/liquidity payment failure says so instead of pointing at channel setup, and only a genuinely channel-less node is sent to open one.
+
 ## v1.8.8-alpha (2026-09-01)
 
 - **SSH over the mesh is now a first-class setting.** Settings gains an "SSH over mesh" card: off by default, and when you allow it the node's mesh firewall opens port 22 — either to every mesh peer (behind an explicit "I understand" confirmation, because that's a real exposure) or only to the mesh addresses you list. The rule is owned by the node (the `90-ssh.nft` drop-in), so it survives upgrades and daemon reinstalls, and the card tells you up front whether sshd is running, whether it listens on IPv6 (the mesh is IPv6-only — this is what a broken attempt looks like before it happens), and whether password login is on (keys-only is the recommended pairing). From Termux on your phone, `fipssh <user>@<node-npub>` connects once the toggle is on — the npub is the durable address, and the command is shown with a copy button on the card.
diff --git a/neode-ui/src/components/LightningRequiredModal.vue b/neode-ui/src/components/LightningRequiredModal.vue
index 831bac89..4669f10d 100644
--- a/neode-ui/src/components/LightningRequiredModal.vue
+++ b/neode-ui/src/components/LightningRequiredModal.vue
@@ -10,7 +10,32 @@
     z-index="z-[3600]"
     @close="onClose"
   >
-    <p v-if="lightning.status.value === 'no-funds'" class="text-sm text-white/70 leading-relaxed">
+    <p v-if="lightning.status.value === 'no-funds' && lightning.fundingReason.value === 'pending'" class="text-sm text-white/70 leading-relaxed">
+      Your new channel is <span class="text-white/90">waiting for its on-chain confirmations</span> —
+      that's why the network doesn't see it yet. It unlocks automatically once
+      confirmed (usually within about half an hour); nothing is needed from
+      you. This screen will work as soon as it lands.
+    </p>
+    <p v-else-if="lightning.status.value === 'no-funds' && lightning.fundingReason.value === 'far-side'" class="text-sm text-white/70 leading-relaxed">
+      <template v-if="lightning.fundingDirection.value === 'receive'">
+        You have channels, but <span class="text-white/90">all the balance is on your side</span> —
+        you can send, but there's nothing to be paid into right now. Receive a
+        payment by spending first, or open another channel to bring inbound
+        liquidity in.
+      </template>
+      <template v-else>
+        You have channels, but <span class="text-white/90">all the balance is on the far side</span> —
+        you can receive, but there's nothing to send right now. Someone has to
+        pay you first (or rebalance the channel), and sending unlocks on its own.
+      </template>
+    </p>
+    <p v-else-if="lightning.status.value === 'no-funds' && lightning.fundingReason.value === 'failed-payment'" class="text-sm text-white/70 leading-relaxed">
+      LND couldn't route this payment — most often there's
+      <span class="text-white/90">not enough outbound for this amount</span>, or no
+      route to the recipient at the fees offered. Smaller amounts sometimes
+      get through; check the channels screen to see what's actually spendable.
+    </p>
+    <p v-else-if="lightning.status.value === 'no-funds'" class="text-sm text-white/70 leading-relaxed">
       Your Lightning node is running, but it has no payment channel yet.
       <template v-if="lightning.fundingDirection.value === 'receive'">
         Receiving needs <span class="text-white/90">inbound liquidity</span> — a
@@ -101,14 +126,31 @@
         @click="openApps"
       >Open My Apps</button>
       <template v-else-if="lightning.status.value === 'no-funds'">
-        <button
-          class="flex-1 glass-button px-4 py-2 rounded-lg text-sm"
-          @click="openSetupGuide"
-        >Setup Guide</button>
-        <button
-          class="flex-1 glass-button glass-button-warning px-4 py-2 rounded-lg text-sm font-medium"
-          @click="openLightningSetup"
-        >Open a channel</button>
+        <!-- A confirming channel needs no action at all — offering "open a
+             channel" here would send the user to fix a problem they don't
+             have (and possibly open a second one). -->
+        <template v-if="lightning.fundingReason.value === 'pending'">
+          <button
+            class="flex-1 glass-button px-4 py-2 rounded-lg text-sm"
+            @click="onClose"
+          >Got it — I'll wait</button>
+        </template>
+        <template v-else>
+          <button
+            class="flex-1 glass-button px-4 py-2 rounded-lg text-sm"
+            @click="openSetupGuide"
+          >Setup Guide</button>
+          <button
+            v-if="lightning.fundingReason.value !== 'failed-payment'"
+            class="flex-1 glass-button glass-button-warning px-4 py-2 rounded-lg text-sm font-medium"
+            @click="openLightningSetup"
+          >Open a channel</button>
+          <button
+            v-else
+            class="flex-1 glass-button px-4 py-2 rounded-lg text-sm"
+            @click="onClose"
+          >Close</button>
+        </template>
       </template>
     </div>
   </BaseModal>
@@ -155,7 +197,12 @@ const nodes: NodeChoice[] = [
 const router = useRouter()
 
 const modalTitle = computed(() => {
-  if (lightningStatusIs('no-funds')) return 'You need a Lightning channel'
+  if (lightningStatusIs('no-funds')) {
+    if (lightning.fundingReason.value === 'pending') return 'Channel confirming…'
+    if (lightning.fundingReason.value === 'far-side') return 'Balance is on the far side'
+    if (lightning.fundingReason.value === 'failed-payment') return 'Payment couldn\u2019t route'
+    return 'You need a Lightning channel'
+  }
   if (lightningStatusIs('stopped')) return 'Lightning node not running'
   return 'Lightning node required'
 })
diff --git a/neode-ui/src/composables/__tests__/useLightningRequired.test.ts b/neode-ui/src/composables/__tests__/useLightningRequired.test.ts
index 7fef5313..c2f818f5 100644
--- a/neode-ui/src/composables/__tests__/useLightningRequired.test.ts
+++ b/neode-ui/src/composables/__tests__/useLightningRequired.test.ts
@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest'
 import { createPinia, setActivePinia } from 'pinia'
 import { useLightningRequired } from '../useLightningRequired'
+import { rpcClient } from '@/api/rpc-client'
 
 // The gate reads install state off the app store's package list. Stub the
 // store rather than the RPC layer so the test pins the decision, not the
@@ -14,6 +15,12 @@ vi.mock('@/stores/app', () => ({
   }),
 }))
 
+vi.mock('@/api/rpc-client', () => ({
+  rpcClient: {
+    call: vi.fn(),
+  },
+}))
+
 describe('useLightningRequired', () => {
   beforeEach(() => {
     setActivePinia(createPinia())
@@ -73,4 +80,82 @@ describe('useLightningRequired', () => {
     packages.value = {}
     expect(useLightningRequired().lightningStatus()).toBe('absent')
   })
+
+  describe('requireLightningReady states the node\u2019s real funding state', () => {
+    beforeEach(() => {
+      packages.value = { lnd: { state: 'running' } }
+      vi.mocked(rpcClient.call).mockReset()
+    })
+
+    it('says the channel is confirming, not \u201cno channel\u201d, while pending', async () => {
+      // The regression (framework-pt, 2026-09-01): a just-opened channel
+      // sits in LND's pending list; the outbound sum is legitimately 0, but
+      // the modal claimed the node had no channel at all.
+      vi.mocked(rpcClient.call).mockResolvedValue({
+        total_inbound: 0,
+        total_outbound: 0,
+        channels: [{ status: 'pending_open', local_balance: 900000, remote_balance: 0 }],
+      })
+      const lightning = useLightningRequired()
+
+      expect(await lightning.requireLightningReady('send')).toBe(false)
+      expect(lightning.show.value).toBe(true)
+      expect(lightning.status.value).toBe('no-funds')
+      expect(lightning.fundingReason.value).toBe('pending')
+    })
+
+    it('says the balance is on the far side when channels exist but outbound is 0', async () => {
+      vi.mocked(rpcClient.call).mockResolvedValue({
+        total_inbound: 985000,
+        total_outbound: 0,
+        channels: [{ status: 'active', local_balance: 0, remote_balance: 985000 }],
+      })
+      const lightning = useLightningRequired()
+
+      expect(await lightning.requireLightningReady('send')).toBe(false)
+      expect(lightning.fundingReason.value).toBe('far-side')
+      // The same node CAN receive — the gate must pass for the other way.
+      vi.mocked(rpcClient.call).mockResolvedValue({
+        total_inbound: 985000,
+        total_outbound: 0,
+        channels: [{ status: 'active', local_balance: 0, remote_balance: 985000 }],
+      })
+      expect(await lightning.requireLightningReady('receive')).toBe(true)
+    })
+
+    it('keeps the open-a-channel guidance only when there truly is no channel', async () => {
+      vi.mocked(rpcClient.call).mockResolvedValue({
+        total_inbound: 0,
+        total_outbound: 0,
+        channels: [],
+      })
+      const lightning = useLightningRequired()
+
+      expect(await lightning.requireLightningReady('send')).toBe(false)
+      expect(lightning.fundingReason.value).toBe('none')
+    })
+
+    it('fails OPEN on an RPC error \u2014 a transient blip must not block a working wallet', async () => {
+      vi.mocked(rpcClient.call).mockRejectedValue(new Error('Failed to fetch'))
+      const lightning = useLightningRequired()
+
+      expect(await lightning.requireLightningReady('send')).toBe(true)
+      expect(lightning.show.value).toBe(false)
+    })
+
+    it('maps a routing/liquidity payment failure onto the modal without claiming \u201cno channel\u201d', () => {
+      const lightning = useLightningRequired()
+
+      expect(lightning.handleLightningFailure(new Error('Payment failed: unable to find a path to destination'))).toBe(true)
+      expect(lightning.status.value).toBe('no-funds')
+      expect(lightning.fundingReason.value).toBe('failed-payment')
+    })
+
+    it('leaves non-funding payment errors to the caller', () => {
+      const lightning = useLightningRequired()
+
+      expect(lightning.handleLightningFailure(new Error('Payment failed: Not Found'))).toBe(false)
+      expect(lightning.show.value).toBe(false)
+    })
+  })
 })
diff --git a/neode-ui/src/composables/useLightningRequired.ts b/neode-ui/src/composables/useLightningRequired.ts
index 283c6d69..6e0eba41 100644
--- a/neode-ui/src/composables/useLightningRequired.ts
+++ b/neode-ui/src/composables/useLightningRequired.ts
@@ -34,12 +34,27 @@ export const LIGHTNING_NODE_APP_IDS = ['lnd'] as const
  *  `running` — good to go. */
 export type LightningStatus = 'absent' | 'stopped' | 'running' | 'no-funds'
 
+/** WHY the funding modal opened — the old copy always said "you have no
+ *  channel yet", which was a lie three ways: a just-opened channel sits in
+ *  LND's pending list (invisible to the outbound sum) until it has ~3
+ *  confirmations, channels can exist with all their balance on the far
+ *  side, and a payment failure can look like a funding problem. The user
+ *  sees "no channel" while looking at a wallet full of pending liquidity
+ *  (framework-pt, 2026-09-01: "LND thinks I do not have a channel").
+ *  `none` — genuinely no channels, the open-one flow is right.
+ *  `pending` — channel(s) exist but are still confirming on-chain.
+ *  `far-side` — open channel(s), but the needed direction has zero balance.
+ *  `failed-payment` — LND refused a payment; looks like routing/liquidity. */
+export type FundingReason = 'none' | 'pending' | 'far-side' | 'failed-payment'
+
 // Module-scope: one source of truth shared by every caller and the single
 // global modal mounted in App.vue.
 const show = ref(false)
 const status = ref<LightningStatus>('absent')
 /** Which direction raised the funding modal, so the copy can be specific. */
 const fundingDirection = ref<'send' | 'receive'>('receive')
+/** Why the funding modal opened, so the copy states the node's real state. */
+const fundingReason = ref<FundingReason>('none')
 
 export function useLightningRequired() {
   // The store is resolved lazily, inside the functions that need it, rather
@@ -86,8 +101,9 @@ export function useLightningRequired() {
    * rather than inventing a second one, and routes to the Lightning setup
    * goal where funding and channel-opening already live.
    */
-  function openLightningFunding() {
+  function openLightningFunding(reason: FundingReason = 'none') {
     status.value = 'no-funds'
+    fundingReason.value = reason
     show.value = true
   }
 
@@ -114,7 +130,9 @@ export function useLightningRequired() {
       'no path',
     ].some((needle) => msg.includes(needle))
     if (!fundingRelated) return false
-    openLightningFunding()
+    // LND refused the payment itself — not necessarily "no channels", so
+    // the modal must not claim it is. Most often this is routing/liquidity.
+    openLightningFunding('failed-payment')
     return true
   }
 
@@ -133,14 +151,28 @@ export function useLightningRequired() {
   async function requireLightningReady(direction: 'send' | 'receive'): Promise<boolean> {
     if (!requireLightningNode()) return false
     try {
-      const res = await rpcClient.call<{ total_inbound?: number; total_outbound?: number }>({
+      const res = await rpcClient.call<{
+        total_inbound?: number
+        total_outbound?: number
+        channels?: { status?: string; local_balance?: number; remote_balance?: number }[]
+      }>({
         method: 'lnd.listchannels',
         timeout: 15000,
       })
       const liquidity = direction === 'receive' ? res?.total_inbound ?? 0 : res?.total_outbound ?? 0
       if (liquidity > 0) return true
       fundingDirection.value = direction
-      openLightningFunding()
+      // Zero in the needed direction — say WHY, from the same response.
+      // The channel list carries pending entries (status 'pending_open');
+      // the totals deliberately exclude them (nothing is spendable through
+      // an unconfirmed channel), so "0 outbound + pending channels" is the
+      // just-opened-a-channel state, not "no channel".
+      const channels = res?.channels ?? []
+      const hasPending = channels.some(c => c.status === 'pending_open')
+      const hasOpen = channels.some(
+        c => c.status === 'active' || c.status === 'inactive' || (!c.status && (c.local_balance || c.remote_balance)),
+      )
+      openLightningFunding(hasPending ? 'pending' : hasOpen ? 'far-side' : 'none')
       return false
     } catch {
       return true
@@ -150,6 +182,7 @@ export function useLightningRequired() {
   return {
     show,
     fundingDirection,
+    fundingReason,
     status,
     lightningStatus,
     hasLightningNode,
diff --git a/neode-ui/src/views/settings/AccountInfoSection.vue b/neode-ui/src/views/settings/AccountInfoSection.vue
index 002615db..22db58c2 100644
--- a/neode-ui/src/views/settings/AccountInfoSection.vue
+++ b/neode-ui/src/views/settings/AccountInfoSection.vue
@@ -374,6 +374,7 @@ init()
                   <p><strong>Apps open over HTTPS again, including Mempool, Bitcoin and IndeeHub.</strong> The launcher looked each app's port policy up in the signed catalog under the name you click, but the catalog lists that port under the app that owns it — so Mempool "did not connect", Bitcoin opened a plain-http tab, and Nostr sign-in on IndeeHub silently did nothing over HTTPS. Launches now follow the alias to the owning manifest, the catalog is loaded before the first app you open (not just in the App Store), and the Nostr bridge replies to the app frame's real origin instead of a stale recorded address.</p>
                   <p><strong>Nginx Proxy Manager starts again.</strong> Its manifest was missing two things its image requires — the LetsEncrypt folder mount and the permission to bind low ports — leaving it in an endless restart loop on nodes that had it installed. Both are declared now; your existing certificates are untouched, and the fix arrives via the signed catalog without waiting for this release.</p>
                   <p><strong>Portainer's first-run token is on the app page, not buried in "server logs".</strong> New Portainer versions hand the first admin a one-time setup token that was only printed in the container logs — on this box, that token now appears with your app's other credentials, with a copy button, and disappears once setup is done.</p>
+                  <p><strong>The Lightning wallet says what's actually wrong, instead of "you have no channel".</strong> Trying to send while a channel you just opened was still confirming — or when all its balance sits on the far side — produced a modal claiming you had no channel at all. The gate now looks at your real channel list: a confirming channel gets "it unlocks automatically once confirmed, nothing needed from you", a far-side balance gets "you can receive but there's nothing to send right now", and only a genuinely channel-less node is sent to open one.</p>
                 </div>
               </div>
               <!-- v1.8.8-alpha -->