ACINQ/eclair: Scala Lightning Node Installation and Operations

Eclair's division of Lightning and on-chain responsibilities

Eclair solves the operational problem of running a Lightning Network node while leaving blockchain interaction and on-chain wallet management to Bitcoin Core. It is aimed at operators who need Lightning channels, payment capabilities and an application-facing JSON API. It is not a standalone Bitcoin wallet, and the separation between Eclair and Bitcoin Core defines most of its installation requirements and operational risks.

Eclair uses Bitcoin Core to interface with the blockchain, monitor chain events and manage on-chain funds. Bitcoin Core funds channel-opening transactions. Channel-closing transactions return funds to the Bitcoin Core node. Because Eclair does not implement its own on-chain wallet, an operator must protect and maintain the Bitcoin Core wallet as part of operating Eclair.

The README says Eclair uses ACINQ's `bitcoin-kmp` library to verify data returned by Bitcoin Core. This is a useful trust boundary within the deployment. Eclair does not need to duplicate the Bitcoin Core wallet, transaction handling and fee-management implementation. In return, it inherits strict requirements on how Bitcoin Core must be configured and how the two applications communicate.

A synchronized, segwit-ready, ZeroMQ-enabled, wallet-enabled, non-pruning Bitcoin Core node with transaction indexing is required. Bitcoin Core 31 or higher is required. Unsupported `non-segwit UTXOs` must be moved to a `bech32` or `bech32m` address before Eclair runs. Operators whose existing wallet or chain backend does not meet those conditions cannot treat Eclair as a plug-in component; they must change the underlying Bitcoin Core deployment first.

Bitcoin Core configuration for Eclair communication

Eclair communicates with Bitcoin Core through RPC requests and ZeroMQ event publications. The minimal `bitcoin.conf` in the README enables the RPC server, supplies credentials, turns on transaction indexing, selects `bech32m` addresses and publishes block and raw transaction events on loopback port `29000`.

server=1
rpcuser=foo
rpcpassword=bar
txindex=1
addresstype=bech32m
changetype=bech32m
zmqpubhashblock=tcp://127.0.0.1:29000
zmqpubrawtx=tcp://127.0.0.1:29000

The two ZeroMQ settings have different event roles. `zmqpubhashblock` publishes new block information, while `zmqpubrawtx` publishes raw transaction information. Eclair needs timely chain information to maintain its view of the blockchain and process transactions relevant to channel state. The RPC settings support commands such as wallet operations and chain queries, while `txindex=1` supplies the transaction index required by the documented configuration.

The README recommends running `bitcoind` on the same machine as Eclair. If Bitcoin Core is remote, Eclair requires a secure tunnel between the applications. RPC calls and ZeroMQ events must be encrypted and authenticated. The README notes that Bitcoin Core does not provide a built-in TLS mechanism for this arrangement and names SSH and WireGuard as possible tunnel technologies.

This security boundary matters because Bitcoin Core controls on-chain funds. Publishing an unprotected RPC interface or forwarding raw ZeroMQ traffic over an untrusted network would expose a sensitive control surface. The loopback addresses in the example also mean that an operator who moves the services to separate hosts must revise the address and transport arrangement rather than copying the local-only example unchanged.

Wallet preparation, backups and database tuning

Bitcoin Core configuration is only one part of preparation. Eclair also places requirements on the wallet's address types. The README states that the wallet must use `bech32` or `bech32m` segwit addresses. If the Bitcoin Core wallet contains `non-segwit UTXOs`, including outputs that are neither `p2sh-segwit`, `bech32` nor `bech32m`, those funds must be sent to a supported address before Eclair is started.

For an existing wallet, the README says an upgrade may require creating a new address and sending all funds to it. This can introduce operational steps that are easy to miss when planning a node deployment. Channel funding also depends on Bitcoin Core's wallet, so an operator should confirm the available spendable outputs before configuring channels.

Backups are a separate requirement. The README explicitly says to back up both the Bitcoin Core wallet and the Eclair node. A Bitcoin Core backup does not replace the Eclair backup because the two applications hold different state. A node backup does not replace the wallet backup because it does not duplicate on-chain funds. Recovery planning should identify which component supplies chain state, which supplies wallet state and which supplies Lightning node state.

The README lists optional Bitcoin Core tuning parameters. A larger `dbcache` may improve verification speed, while a larger `rpcworkqueue` can improve handling of API requests. It also documents `rpcclienttimeout` as the number of seconds Bitcoin waits for a complete RPC HTTP request after the connection is established.

# UTXO database cache size, in MiB
dbcache=2048
# Number of allowed pending RPC requests (default is 16)
rpcworkqueue=128

# How many seconds bitcoin will wait for a complete RPC HTTP request.
# after the HTTP connection is established.
rpcclienttimeout=30

These values address performance and request handling, but they do not replace the required server, indexing, wallet or ZeroMQ settings. Operators should apply them only after the functional requirements are in place.

Installing Eclair and starting the node

Eclair is implemented in Scala, runs on the JVM and is packaged as a ZIP archive. The README targets Java 21 and recommends OpenJDK 21. The installation process begins by obtaining the latest Eclair release, extracting the archive and running its node launcher from the extracted directory.

eclair-node-<version>-<commit_id>/bin/eclair-node.sh

The command shown is a template from the README. Replace `<version>` and `<commit_id>` with the directory name created by the downloaded release. After the launcher starts the node, the README says that it can be controlled with `eclair-cli` or the API. The launcher itself is not a complete channel-opening or payment tutorial, so operators must consult `docs/Usage.md`, `docs/Configure.md` and the project guides for those tasks.

Eclair reads its configuration and writes logs to `~/.eclair` by default. A minimal `eclair.conf` sets the node alias and color:

eclair.node-alias=eclair
eclair.node-color=49daaa

The documented chain option accepts `regtest`, `testnet`, `signet` or `mainnet`, with `mainnet` as the default. The default Lightning TCP port is `9735`. The JSON API is disabled by default through `eclair.api.enabled=false`. Enabling it requires a password.

For a first controlled use, `regtest` is the relevant option because it provides a local development chain. The README lists it as a supported chain, but it does not provide the complete topology, mining setup, channel funding sequence or payment commands needed for a self-contained regtest exercise. Those details belong in the repository's configuration and guide documentation.

The repository also contains a `Dockerfile`. Its build uses `eclipse-temurin:21-jdk-noble` and the final image uses `eclipse-temurin:21-jre-noble`, creates `/data`, sets `ECLAIR_DATADIR=/data` and declares `/data` as a volume. The README does not give a complete Docker deployment tutorial, including how to connect the container securely to Bitcoin Core or expose Eclair's interfaces.

Eclair API access and integration constraints

The JSON API is Eclair's main documented integration surface. The README describes it as feature-rich and says it enables application developers to integrate with the node. The associated documentation is hosted at `https://acinq.github.io/eclair`, while `eclair-cli` is identified as the command-line control tool after installation.

The API is disabled by default, and enabling it requires setting a password. That default reduces the chance of accidentally starting an open management service. It does not make the API suitable for direct Internet exposure. The README explicitly says that Eclair's JSON API should not be accessible from the outside world, similarly to the Bitcoin Core API.

The configuration keys shown in the README separate the API control plane from node identity and chain selection. `eclair.api.enabled` enables or disables the API, and `eclair.api.port` selects its HTTP port. The README excerpt does not document the complete API endpoint list, request schemas, authentication sequence, error model or rate limits. An application developer should inspect `docs/API.md` and the generated API documentation before deciding that Eclair's interface fits a particular payment workflow.

Eclair's API is therefore best understood as an operator-controlled local service. The documentation does not claim public multi-tenant access, tenant isolation or a complete reverse-proxy design. A service that needs remote clients should add its own carefully designed access boundary after reviewing the API documentation. That is separate work, not a capability promised by the README.

The API and `eclair-cli` should also be considered part of the node's operational security. Passwords, process permissions and host access controls affect who can create channels, request payments or inspect node state. The README explicitly provides the API exposure warning, but it does not prescribe a complete host-hardening policy for every supported operating system.

BOLT support, alternatives and maintenance considerations

Eclair states that it follows the Lightning Network Specifications, or BOLTs. The README does not claim that every current BOLT is supported in every release. Instead, it directs readers to the latest release note for detailed compliance information. That is the correct source to consult when selecting a version for a particular Lightning deployment.

The README names core lightning, `lnd`, Electrum and LDK as other implementations, but it does not provide a technical comparison. Eclair's documented architecture is nevertheless distinguishable through its prerequisites: it delegates on-chain interaction and wallet management to a non-pruning Bitcoin Core node, uses ZeroMQ for chain events, uses RPC for wallet operations and verifies returned data with `bitcoin-kmp`. An operator whose priority is a different architecture can compare that dependency profile against the alternatives instead of assuming all Lightning nodes have the same backend requirements.

Eclair is identified under Apache-2.0. The repository includes a `LICENSE` file and the README displays an Apache 2.0 license badge. This records the project's stated licensing information, but it is not legal advice about whether a particular distribution or integration satisfies a separate compliance process.

Maintenance activity is visible in the repository status. The repository is not archived, and the last push was on 2026-10-15. Recent releases include v0.14.3 on 2026-09-14, v0.14.2 on 2026-08-26 and v0.14.1 on 2026-07-29. This indicates recent development activity, but upgrades still carry operational work. Operators must check Bitcoin Core compatibility, BOLT changes, configuration changes, wallet backups and connectivity after each Eclair update.

The main limitation is architectural rather than cosmetic. Eclair cannot operate as documented with a pruned Bitcoin Core backend, a wallet-less Bitcoin Core node, a remote unprotected connection or a missing ZeroMQ configuration. It is better suited to an operator who accepts that two-node deployment and its security requirements than to a user searching for a single-process Lightning wallet.

Editorial conclusion

Operators who already control a compatible Bitcoin Core wallet and can protect its RPC and ZeroMQ traffic should consider Eclair for its Scala implementation, documented configuration and HTTP integration surface. Operators seeking a self-contained wallet, a pruned blockchain backend or a management API exposed directly to the Internet should reject this deployment model. Before adoption, verify Bitcoin Core 31 or higher, segwit-ready funds, backups for both applications, Java 21, ZeroMQ connectivity and BOLT compliance in the release note for the selected Eclair version.

Frequently asked questions

Official sources

1. ACINQ/eclair on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases