Public commit record
88/100 · Strong
What the developer wrote
Authored by Bastien Teinturier
Add basic CLAUDE.md (#3254)
This was generated using Opus 4.6 with the `/init` command. It provides
overall context about the codebase to every Claude session, to avoid
repeating work to build that context (consume less token whenever using
Claude for a task).
✓ Descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context✓ Explains rationale or failure mode✓ Links an issue, advisory, or supporting reference
What changed, and why it matters
This commit adds a documentation file called CLAUDE.md that gives the Claude AI coding assistant general context about the Eclair Lightning Network project. It contains no code changes, no configuration changes, and nothing that affects how the software runs or processes data. It is purely informational for AI-assisted development.
Recommended action
No security action needed. This is a documentation-only change. Normal code review for accuracy of the documentation is sufficient.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The commit introduces a single new markdown file, CLAUDE.md, intended for use with Claude Code. It describes the project structure, build commands, architecture, testing conventions, code style, and key dependencies. The diff shows only additions to CLAUDE.md (+79 lines, 0 deletions). No source code, build files, dependencies, or runtime configuration were modified.
Changed components
Not specified
Inspect captured patch +79 / −0
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..64440b7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Eclair is a Scala implementation of the Lightning Network specification (BOLTs). It is a payment channel network built on Bitcoin, developed by ACINQ. The codebase uses Scala 2.13 with the Akka actor framework on Java 21.
+
+## Build Commands
+
+```bash
+./mvnw package # Build all modules with tests
+./mvnw package -DskipTests # Build without tests
+./mvnw test # Run all tests
+./mvnw test -Dsuites=*<TestClassName> # Run a single test class
+./mvnw -T <threads> test # Run tests with parallelism
+./mvnw package -pl eclair-node -am -Dmaven.test.skip=true # Build only eclair-node
+./mvnw clean install -pl eclair-core -am -Dmaven.test.skip=true # Install eclair-core to local Maven repo
+```
+
+Scala compiler flags include `-Werror`, so warnings are treated as errors.
+
+## Module Structure
+
+- **eclair-core**: Core Lightning implementation library. Contains channel state machine, payment logic, routing, crypto, database layer, and protocol wire messages.
+- **eclair-node**: Server daemon. Entry point (`Boot.scala`), REST API (`api/`), and plugin system (`Plugin.scala`).
+- **eclair-front**: Front-end server for cluster mode deployments, handling peer connections.
+
+## Architecture
+
+Eclair uses an **Akka actor model** where nearly every entity is a separate actor:
+
+- **Switchboard** creates/manages **Peer** actors (one per p2p connection)
+- Each **Peer** manages multiple **Channel** actors (one per Lightning channel)
+- **Register** maps channel IDs to channel actors
+- **Router** handles network graph gossip (BOLT 7) and path-finding
+- **PaymentInitiator** orchestrates sending payments via **MultiPartPaymentLifecycle** → **PaymentLifecycle** actors
+- **PaymentHandler** manages receiving payments
+- **Relayer** delegates forwarding to **ChannelRelayer** (standard) or **NodeRelayer** (trampoline)
+
+The entry point for `eclair-core` is `Setup.scala`, which starts the actor system, connects to bitcoind, and creates top-level actors.
+
+Actors communicate via direct messages or a shared event stream.
+
+## Key Source Paths (eclair-core)
+
+All under `eclair-core/src/main/scala/fr/acinq/eclair/`:
+
+- `channel/` - Channel state machine (BOLT 2)
+- `payment/` - Payment send/receive/relay
+- `router/` - Network routing and gossip
+- `wire/` - Lightning protocol message codecs (scodec-based)
+- `blockchain/` - Bitcoin Core integration (RPC, ZMQ)
+- `db/` - Database layer (SQLite and PostgreSQL)
+- `io/` - Peer connection handling
+- `crypto/` - Cryptographic operations
+
+## Testing
+
+- Framework: ScalaTest. Tests are parallelized by suite (not individual tests).
+- Keep each test suite under one minute; split into smaller suites if needed.
+- Bug fixes should start with a failing test in a separate commit before the fix.
+- Tests live alongside sources in `src/test/scala/`.
+
+## Code Style
+
+- IntelliJ default Scala formatting is used (Ctrl+Alt+L to format, Ctrl+Alt+O to optimize imports).
+- No hard style rules, but code should be consistent with surrounding code.
+- Commit messages use present tense ("Fix bug" not "Fixed bug"), 50-char summary line.
+- Signed commits are required.
+
+## Key Dependencies
+
+- **Akka** 2.6.20 (actors, HTTP, streams, cluster)
+- **bitcoin-lib** 0.46 (ACINQ's Bitcoin library, Kotlin-based)
+- **scodec** (binary protocol encoding/decoding for wire messages)
+- **json4s** (JSON serialization)
+- **Kamon** (metrics/monitoring)
+- **SQLite** (default DB) / **PostgreSQL** (production option with HikariCP pooling)
Risk score
Our methodology →Why this scored 15/100
Human-validated context
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
No validated notes yet.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.