From 9ed4409e258697ff6ce5f2a1890af70a9d31c375 Mon Sep 17 00:00:00 2001
From: naturallaw777 <99053422+naturallaw777@users.noreply.github.com>
Date: Wed, 29 Jul 2026 00:45:06 +0000
Subject: [PATCH] Add NWC channel liquidity guide and UI/UX explanation for new
 LND nodes

Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
---
 .../static/css/modals.css                     | 59 +++++++++++++++++++
 .../static/js/service-detail.js               | 42 ++++++++++++-
 2 files changed, 99 insertions(+), 2 deletions(-)

diff --git a/app/sovran_systemsos_web/static/css/modals.css b/app/sovran_systemsos_web/static/css/modals.css
index 17b967d..e5ba26e 100644
--- a/app/sovran_systemsos_web/static/css/modals.css
+++ b/app/sovran_systemsos_web/static/css/modals.css
@@ -546,3 +546,62 @@ button.btn-reboot:hover:not(:disabled) {
 .nwc-share-formats-hint {
   text-align: center;
 }
+
+/* ── NWC Liquidity Guide Card ────────────────────────────────────── */
+
+.nwc-liquidity-guide-card {
+  background: rgba(255, 255, 255, 0.02);
+  border: 1px solid var(--border-color);
+  border-radius: 12px;
+  padding: 16px;
+  margin-bottom: 16px;
+  color: var(--text-primary);
+}
+
+.nwc-liquidity-header {
+  display: flex;
+  gap: 12px;
+  align-items: flex-start;
+  margin-bottom: 12px;
+}
+
+.nwc-liquidity-icon {
+  font-size: 24px;
+}
+
+.nwc-liquidity-steps {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  margin-bottom: 14px;
+}
+
+.nwc-liquidity-step {
+  display: flex;
+  gap: 10px;
+  align-items: flex-start;
+  font-size: 0.85rem;
+}
+
+.step-num {
+  background: var(--accent-color);
+  color: #0A1A10;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 0.75rem;
+  flex-shrink: 0;
+  margin-top: 1px;
+}
+
+.nwc-liquidity-action {
+  background: rgba(109, 191, 139, 0.08);
+  border-left: 3px solid var(--green);
+  padding: 10px 12px;
+  border-radius: 0 8px 8px 0;
+  font-size: 0.82rem;
+}
diff --git a/app/sovran_systemsos_web/static/js/service-detail.js b/app/sovran_systemsos_web/static/js/service-detail.js
index 85a7a9e..7acee5d 100644
--- a/app/sovran_systemsos_web/static/js/service-detail.js
+++ b/app/sovran_systemsos_web/static/js/service-detail.js
@@ -634,9 +634,41 @@ async function openServiceDetailModal(unit, name, icon) {
     // Section E: Credentials & Links
     if (_isNwcServiceUnit(unit)) {
       html += '<div class="svc-detail-section">' +
-        '<div class="svc-detail-section-title">Wallet Connections</div>';
+        '<div class="svc-detail-section-title">Wallet Connections &amp; Node Liquidity</div>';
       if (effectiveEnabled || data.enabled) {
-        html += '<p class="svc-detail-desc">Create, verify, drain, and delete isolated NWC wallet connections without leaving the Hub.</p>' +
+        html += '<div class="nwc-liquidity-guide-card">' +
+          '<div class="nwc-liquidity-header">' +
+            '<span class="nwc-liquidity-icon">⚡</span>' +
+            '<div>' +
+              '<h4 style="margin:0 0 4px 0; font-size:15px; font-weight:600;">Lightning Channel &amp; Liquidity Guide</h4>' +
+              '<p class="nwc-liquidity-subtitle" style="margin:0; font-size:12px; color:var(--text-secondary);">How NWC &amp; Lightning Addresses work on new nodes</p>' +
+            '</div>' +
+          '</div>' +
+          '<p style="font-size:13px; line-height:1.5; margin:0 0 12px 0;">' +
+            'Your Alby Hub, NWC pairing keys, and Lightning Address endpoints (like <code>name@yourdomain.com</code>) are set up and working instantly. However, sending and receiving actual Bitcoin payments requires an operational Lightning node with active channels.' +
+          '</p>' +
+          '<div class="nwc-liquidity-steps">' +
+            '<div class="nwc-liquidity-step">' +
+              '<div class="step-num">1</div>' +
+              '<div>' +
+                '<strong>Outbound Liquidity (Sending)</strong>' +
+                '<p style="margin:2px 0 0 0; color:var(--text-secondary); font-size:12px;">Required so apps connected via NWC can pay invoices and send funds.</p>' +
+              '</div>' +
+            '</div>' +
+            '<div class="nwc-liquidity-step">' +
+              '<div class="step-num">2</div>' +
+              '<div>' +
+                '<strong>Inbound Liquidity (Receiving)</strong>' +
+                '<p style="margin:2px 0 0 0; color:var(--text-secondary); font-size:12px;">Required so your Lightning Address can receive incoming payments from anyone.</p>' +
+              '</div>' +
+            '</div>' +
+          '</div>' +
+          '<div class="nwc-liquidity-action">' +
+            '<p style="margin:0 0 10px 0; font-size:12.55px; line-height:1.4;">💧 <strong>The Plumbing Analogy:</strong> Think of channels like two-way water pipes. To pour water in (receive) or pump water out (send), you need open channels with liquidity on both sides.</p>' +
+            '<button class="matrix-action-btn secondary-btn" id="nwc-open-rtl-btn" style="display:inline-flex; align-items:center; gap:6px; background:var(--border-color); color:var(--text-primary); border:none; padding:8px 14px; border-radius:8px; font-size:12.55px; cursor:pointer;">🚀 Open Ride The Lightning (RTL) to Manage Channels</button>' +
+          '</div>' +
+        '</div>' +
+        '<p class="svc-detail-desc" style="margin-top:16px;">Create, verify, drain, and delete isolated NWC wallet connections without leaving the Hub.</p>' +
           '<div id="nwc-wallets-body"><p class="creds-loading">Loading wallet connections…</p></div>';
       } else {
         html += '<p class="creds-empty">Wallet Connections is disabled. Enable this feature below, rebuild, then return here to create and manage NWC wallet connections.</p>';
@@ -725,6 +757,12 @@ async function openServiceDetailModal(unit, name, icon) {
     _attachCopyHandlers($credsBody);
     if (_isNwcServiceUnit(unit) && (effectiveEnabled || data.enabled)) {
       await _nwcInitWalletFlow(unit, name, icon);
+      var nwcRtlBtn = document.getElementById("nwc-open-rtl-btn");
+      if (nwcRtlBtn) {
+        nwcRtlBtn.addEventListener("click", function() {
+          openServiceDetailModal("rtl.service", "Ride The Lightning", "rtl");
+        });
+      }
     }
 
     if (unit === "matrix-synapse.service") {