regtest: add Fulcrum (Electrum/WS) with ZMQ push for Hal realtimeregtest-fulcrum

Adds a regtest Fulcrum service matching what prod runs, replacing the old
electrs + ews bridge as the data/realtime backend for the Hal browser wallet.
It connects to `bc` and gets instant block/mempool notifications over bitcoind's
ZMQ (hashblock/hashtx), serving them to the browser over an Electrum WebSocket
(:50003) — sub-second deposit + confirmation updates on regtest.

- docker/fulcrum.Dockerfile: Fulcrum on ghcr.io/coinos/base (shares layers with
  the rest of the stack instead of a separate image tree).
- compose.fulcrum.yml: opt-in overlay (`-f compose.fulcrum.yml up -d`), config +
  datadir under the gitignored data/ (seeded from sampledata by setup.sh).
- sampledata/fulcrum/fulcrum.conf: regtest config pointed at `bc`, ZMQ enabled.
- sampledata/bitcoin/bitcoin.conf: add zmqpubhashblock/hashtx (18508/18509) so
  Fulcrum can subscribe for instant notifications.

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

5 files changed, 55 insertions, 0 deletions

diff --git a/compose.fulcrum.yml b/compose.fulcrum.yml
new file mode 100644
index 00000000..b57e0351
--- /dev/null
+++ b/compose.fulcrum.yml
@@ -0,0 +1,22 @@
+# Fulcrum for regtest — an Electrum server over WebSocket, matching what prod
+# runs. Replaces the old electrs + ews bridge for Hal's realtime: it gets instant
+# block/mempool pushes from bitcoind's ZMQ (see sampledata/bitcoin/bitcoin.conf
+# zmqpubhashblock/hashtx) and serves them to the browser over the WS port.
+# Config + datadir live under the gitignored data/ (seeded from sampledata by
+# setup.sh). Start after the main stack (needs `bc`):
+#   docker compose -f compose.fulcrum.yml up -d
+services:
+  fulcrum:
+    image: coinos/fulcrum:latest
+    container_name: fulcrum
+    volumes:
+      - ./data/fulcrum/fulcrum.conf:/etc/fulcrum/fulcrum.conf:ro
+      - ./data/fulcrum/db:/data
+    ports:
+      - "50001:50001"   # Electrum TCP
+      - "50003:50003"   # Electrum WebSocket (Hal connects here)
+    restart: unless-stopped
+networks:
+  default:
+    name: net
+    external: true
diff --git a/docker/fulcrum.Dockerfile b/docker/fulcrum.Dockerfile
new file mode 100644
index 00000000..3f80b95a
--- /dev/null
+++ b/docker/fulcrum.Dockerfile
@@ -0,0 +1,13 @@
+# Fulcrum on the coinos base image. The static upstream release binary is
+# self-contained, so we just drop it onto ghcr.io/coinos/base — the rest of the
+# coinos stack already uses that base, so this shares layers instead of pulling
+# a separate Fulcrum image tree. Matches the prod Fulcrum version.
+FROM ghcr.io/coinos/base
+USER root
+ARG VERSION=2.1.1
+ADD https://github.com/cculianu/Fulcrum/releases/download/v${VERSION}/Fulcrum-${VERSION}-x86_64-linux.tar.gz /tmp/f.tar.gz
+RUN tar xzf /tmp/f.tar.gz -C /usr/local/bin --strip-components=1 \
+      Fulcrum-${VERSION}-x86_64-linux/Fulcrum Fulcrum-${VERSION}-x86_64-linux/FulcrumAdmin \
+    && rm /tmp/f.tar.gz && mkdir -p /etc/fulcrum /data
+ENTRYPOINT ["Fulcrum"]
+CMD ["/etc/fulcrum/fulcrum.conf"]
diff --git a/sampledata/bitcoin/bitcoin.conf b/sampledata/bitcoin/bitcoin.conf
index 3aa44186..6036a3f9 100644
--- a/sampledata/bitcoin/bitcoin.conf
+++ b/sampledata/bitcoin/bitcoin.conf
@@ -20,3 +20,6 @@ walletnotify=/home/bitcoin/.bitcoin/transaction.sh %s %w
 
 zmqpubrawblock=tcp://0.0.0.0:18506
 zmqpubrawtx=tcp://0.0.0.0:18507
+# hashblock/hashtx for Fulcrum's instant (ZMQ) block + mempool notifications
+zmqpubhashblock=tcp://0.0.0.0:18508
+zmqpubhashtx=tcp://0.0.0.0:18509
diff --git a/sampledata/fulcrum/db/.gitkeep b/sampledata/fulcrum/db/.gitkeep
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/sampledata/fulcrum/db/.gitkeep
diff --git a/sampledata/fulcrum/fulcrum.conf b/sampledata/fulcrum/fulcrum.conf
new file mode 100644
index 00000000..cafdc05d
--- /dev/null
+++ b/sampledata/fulcrum/fulcrum.conf
@@ -0,0 +1,17 @@
+# Fulcrum for the local regtest stack (mirrors prod's config, pointed at `bc`).
+# Serves the Electrum protocol over TCP (50001) and WebSocket (50003) — the WS
+# is what the Hal browser wallet connects to for data + realtime push. Block and
+# mempool notifications arrive over bitcoind's ZMQ (auto-discovered via the
+# getzmqnotifications RPC), so polltimesecs is just a slow safety net.
+datadir = /data
+bitcoind = bc:18443
+rpcuser = admin1
+rpcpassword = 123
+tcp = 0.0.0.0:50001
+ws = 0.0.0.0:50003
+peering = false
+announce = false
+db_mem = 1000
+bitcoind_clients = 1
+polltimesecs = 5
+zmq_allow_hashtx = true