Regtest realtime via a local Electrum-over-WebSocket bridge

On regtest there's no realtime push (coinos watcher is mainnet-only), so the UI
only updated on the 5–10s poll — a funded tx took a while to appear and a
just-mined block stayed "pending" until the next reconcile. electrs speaks the
Electrum protocol the watcher already understands, but only over TCP; route it
through a small WS<->TCP bridge (see coinos-server/electrum-ws) so the wallet
subscribes scripthashes and reconciles instantly on each notification. Data
still comes from esplora; this only adds the push channel. Configurable in
Settings (default ws://localhost:50003); falls back to polling if unreachable.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

2 files changed, 31 insertions, 11 deletions

diff --git a/src/api.js b/src/api.js
index d135218..98b7528 100644
--- a/src/api.js
+++ b/src/api.js
@@ -166,8 +166,20 @@ export function resolveElectrumUrl() {
   return electrumCandidates()[0] || null;
 }
 
+// Regtest realtime push: a local electrs reached over a WS<->TCP bridge (electrs
+// is TCP-only). Same Electrum protocol the watcher already speaks, so the wallet
+// subscribes scripthashes and reconciles via esplora on each notification.
+const REGTEST_ELECTRUM_KEY = 'btc-wallet-regtest-electrum';
+export function getRegtestElectrumWs() {
+  try { return (localStorage.getItem(REGTEST_ELECTRUM_KEY) || '').trim() || 'ws://localhost:50003'; }
+  catch { return 'ws://localhost:50003'; }
+}
+export function setRegtestElectrumWs(url) { try { localStorage.setItem(REGTEST_ELECTRUM_KEY, (url || '').trim()); } catch {} }
+
 export function wsUrl(net) {
-  if (net !== 'mainnet') return null; // coinos watcher is mainnet-only
+  // Regtest gets realtime via the local electrs WS bridge (data still via esplora).
+  if (net === 'regtest') return getRealtimeEnabled() ? getRegtestElectrumWs() : null;
+  if (net !== 'mainnet') return null; // testnet: poll-only
   // Electrum backend selects/rotates candidates in the wallet; here we only
   // resolve the coinos watcher (esplora 'coinos' mode) or null (esplora 'explorer').
   if (getBackend() === 'electrum') return null;
diff --git a/src/app.js b/src/app.js
index 1dbd478..81f952c 100644
--- a/src/app.js
+++ b/src/app.js
@@ -8,7 +8,7 @@ import { Wallet, newMnemonic, isValidMnemonic, accountXpubFor, cacheKeyFor, utxo
 import { qrSvg } from './qr.js';
 import { scanQr } from './scan.js';
 import { getSyncConfig, setSyncConfig } from './nostr.js';
-import { getExplorerConfig, setExplorerConfig, EXPLORER_PRESETS, getDataMode, setDataMode, ELECTRUM_PRESETS, getElectrumServerConfig, setElectrumServerConfig, getNetwork, setNetwork, getRegtestEsplora, setRegtestEsplora } from './api.js';
+import { getExplorerConfig, setExplorerConfig, EXPLORER_PRESETS, getDataMode, setDataMode, ELECTRUM_PRESETS, getElectrumServerConfig, setElectrumServerConfig, getNetwork, setNetwork, getRegtestEsplora, setRegtestEsplora, getRegtestElectrumWs, setRegtestElectrumWs } from './api.js';
 import { isSilentPaymentAddress } from './silentpay.js';
 import { t, LANGS, getLang, setLang, isRTL, loadLocale } from './i18n.js';
 import {
@@ -1577,15 +1577,23 @@ function networkCard() {
       h('option', { value: 'regtest', selected: net === 'regtest' }, 'Regtest')
     ),
     net === 'regtest'
-      ? h('label', { class: 'field' },
-          h('span', { class: 'lab' }, 'Regtest Esplora URL'),
-          h('input', {
-            type: 'text', class: 'mono-input', placeholder: 'http://localhost:3000',
-            autocapitalize: 'none', autocomplete: 'off', spellcheck: 'false', value: getRegtestEsplora(),
-            onChange: (e) => { setRegtestEsplora(e.target.value.trim()); wallet.reloadExplorer(); },
-          }),
-          h('div', { class: 'small faint' }, 'Esplora-compatible REST endpoint (coinos chopsticks/electrs).')
-        )
+      ? h('div', { class: 'col', style: 'gap:10px' },
+          h('label', { class: 'field' },
+            h('span', { class: 'lab' }, 'Regtest Esplora URL'),
+            h('input', {
+              type: 'text', class: 'mono-input', placeholder: 'http://localhost:3000',
+              autocapitalize: 'none', autocomplete: 'off', spellcheck: 'false', value: getRegtestEsplora(),
+              onChange: (e) => { setRegtestEsplora(e.target.value.trim()); wallet.reloadExplorer(); },
+            }),
+            h('div', { class: 'small faint' }, 'Esplora-compatible REST endpoint (coinos chopsticks/electrs).')),
+          h('label', { class: 'field' },
+            h('span', { class: 'lab' }, 'Regtest realtime (Electrum WS)'),
+            h('input', {
+              type: 'text', class: 'mono-input', placeholder: 'ws://localhost:50003',
+              autocapitalize: 'none', autocomplete: 'off', spellcheck: 'false', value: getRegtestElectrumWs(),
+              onChange: (e) => { setRegtestElectrumWs(e.target.value.trim()); wallet.reloadExplorer(); },
+            }),
+            h('div', { class: 'small faint' }, 'Electrum-over-WebSocket bridge (ews) for instant updates; falls back to polling if unreachable.')))
       : null
   );
 }