Better documentation for remote `bitcoind` (#3359)
What the developer wrote
Authored by Bastien Teinturier
Better documentation for remote `bitcoind` (#3359)
Our documentation didn't make it clear enough that `bitcoind` should
ideally run on the same machine as `eclair`. If that's not possible,
since `bitcoind` doesn't provide support for TLS for its RPC and ZMQ
endpoints, the node operator MUST setup a secure tunnel (providing
encryption and authentication) between `eclair` and `bitcoind`. If
that isn't provided, a network attacker may drop or alter messages
between `eclair` and `bitcoind`, which can lead to a loss of funds.
What changed, and why it matters
This commit only updates user documentation. It adds warnings that the Bitcoin node (bitcoind) should run on the same machine as Eclair, and if it runs remotely, operators must use a secure encrypted tunnel. No code was changed, so this patch does not by itself fix or introduce a security flaw.
No action required beyond reviewing the updated guidance. Operators running remote bitcoind should follow the documented recommendation to use an encrypted, authenticated tunnel.
Security signals we found
Documentation-only change
No code, configuration, or cryptographic modifications
Describes pre-existing deployment risk rather than a new vulnerability
Evidence from the diff
The diff modifies README.md and a release-notes file to document operational security guidance for remote bitcoind deployments. It explains that bitcoind’s RPC and ZMQ endpoints lack TLS and therefore require an external secure tunnel (e.g., SSH or WireGuard). There are no code, configuration, or cryptographic changes.
Changed components
README.mddocs/release-notes/eclair-vnext.mdInspect captured patch +7 / −0
### README.md
@@ -90,6 +90,11 @@ rpcworkqueue=128
rpcclienttimeout=30
```
+:warning: We recommend running bitcoind on the same machine as your eclair node.
+:warning: If you run bitcoind on a remote machine, you MUST use a secure tunnel between bitcoind and eclair: the RPC and ZMQ events must be encrypted and authenticated.
+
+Note that bitcoind does not provide a built-in mechanism for using TLS (or another encryption protocol): it is up to the node operator to setup a secure tunnel (e.g. using ssh or wireguard).
+
### Installing Eclair
Eclair is developed in [Scala](https://www.scala-lang.org/), a powerful functional language that runs on the JVM, and is packaged as a ZIP archive.
### docs/release-notes/eclair-vnext.md
@@ -2,6 +2,8 @@
<insert here a high-level description of the release>
+We explicitly document that bitcoind should run on the same machine as eclair, or that a secure tunnel (providing encryption and authentication) must be setup between eclair and bitcoind.
+
## Major changes
<insert changes>Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.