How acinq/eclair works
Project type and purpose
• Eclair is a multi‐module, actor‐based Scala implementation of a Lightning Network node.
• It comprises a core library (eclair-core), a standalone node runtime with HTTP JSON API (eclair-node), an optional cluster/front-end service (eclair-front), a CLI client (eclair-cli), plugin support, Docker packaging, and monitoring assets.
• It interfaces with Bitcoin Core for on-chain operations, speaks the Lightning wire protocol to other peers, and exposes a JSON API for client applications.
File structure
• Top-level directories/modules:
• eclair-core: the heart of the system (actors, FSMs, routers, DB layer, crypto, key management, blockchain watchers).
• eclair-node: bootstraps eclair-core, loads plugins, hosts Akka HTTP JSON API and WebSocket handlers.
• eclair-front: an Akka-cluster-based front-end gateway (cluster listener, front router), packaged for AWS EB.
• monitoring: Grafana dashboard definitions for metrics.
• contrib, Dockerfile, CI/CD config, docs, pom.xml/mvn wrapper.
• Config/build files: application.conf (HOCON), logback.xml, Dockerfile, maven-wrapper.
• Persistence: supports SQLite or PostgreSQL via JDBC (eclair-core/src/main/scala/fr/acinq/eclair/db).
README for additional insights
• Project description, JSON API warnings, plugin interface, Docker usage, external Bitcoin Core requirements, monitoring guidance.
• References to Akka actor system (Kamon instrumentation), plugin SPI, cluster usage (Cluster.md).
a. External dependencies
• Bitcoin Core node
– Interfaces: JSON-RPC (funding, closing, fee estimation), ZMQ (block/tx notifications)
• Lightning P2P network
– TCP Lightning wire protocol
• Clients / CLI (eclair-cli, custom apps)
• Monitoring stack (Prometheus/Kamon → Grafana dashboards)
b. Core runtime
• Eclair-core (Akka Actor System)
– On-chain actors (OnChainWallet, ZmqWatcher, RPC client)
– Channel FSM actors (ChannelOpen, Commitments, HTLC handlers)
– Router actor (Gossip, PathFinding, Graph)
– Payment manager actors (send, receive, relay workflows)
– Crypto/KeyManager (noise handshake, onion, ChaCha20, ShaChain)
– DB layer (audit, channels, peers, payments; migrations; SQLite / PG)
• Eclair-node
– Boot.scala (startup), plugin loader, Service.scala (Akka HTTP routes), API handlers (Channel, Payment, Node, Fees, WebSocket)
• Eclair-front (optional cluster gateway)
– ClusterListener, FrontRouter
c. Persistence
• SQLite / PostgreSQL – channel and node state, migrations
d. Monitoring & logging
• Kamon metrics exported → Prometheus → Grafana dashboards (monitoring/grafana-dashboard)
• Logback for application logs
Architectural patterns & technologies
• Actor model (Akka actors & FSM)
• Layered modules: core library → node application → front gateway → CLI/API clients
• Plugin SPI (dynamic JARs implementing Plugin.scala)
• Configuration via HOCON (application.conf), Logback
• Docker containers for node (x86_64/arm64), Bitcoin Core, monitoring
• CI/CD (GitHub Actions)