From e0a4a5e9d332f998456b637f5d8ba38563d19827 Mon Sep 17 00:00:00 2001 From: Adam Soltys Date: Sat, 27 Jun 2026 11:00:08 -0700 Subject: regtest: add Fulcrum (Electrum/WS) with ZMQ push for Hal realtime MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- compose.fulcrum.yml | 22 ++++++++++++++++++++++ docker/fulcrum.Dockerfile | 13 +++++++++++++ sampledata/bitcoin/bitcoin.conf | 3 +++ sampledata/fulcrum/db/.gitkeep | 0 sampledata/fulcrum/fulcrum.conf | 17 +++++++++++++++++ 5 files changed, 55 insertions(+) create mode 100644 compose.fulcrum.yml create mode 100644 docker/fulcrum.Dockerfile create mode 100644 sampledata/fulcrum/db/.gitkeep create mode 100644 sampledata/fulcrum/fulcrum.conf 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 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 -- cgit v1.2.3