From 88525ef5102d4b85282de0fdb45c87822358f4bb Mon Sep 17 00:00:00 2001
From: Davide Grilli <davide.grilli@outlook.com>
Date: Wed, 29 Apr 2026 10:08:48 +0200
Subject: [PATCH] docs: add CLAUDE.md

Project guidance for Claude Code covering dev commands (install, run, test,
build translations), high-level architecture (entry/routing, core module
table, GUI backends, plugin system, async model, testing conventions)
---
 CLAUDE.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..648db4d2a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Electrum is a lightweight Bitcoin wallet with full Lightning Network support. It communicates with Electrum servers (not full nodes) via the Electrum protocol, and can run as a daemon with GUI/CLI clients or as an embedded library.
+
+## Development Commands
+
+**Install for development:**
+```bash
+python3 -m pip install --user -e .
+```
+
+**Run from source:**
+```bash
+./run_electrum
+```
+
+**Run all tests:**
+```bash
+pytest tests -v
+```
+
+**Run a single test file or test:**
+```bash
+pytest tests/test_bitcoin.py -v
+pytest tests/test_bitcoin.py::TestBitcoin::test_address -v
+```
+
+**Run tests in parallel:**
+```bash
+pytest tests -v -n auto
+```
+
+**Build translations** (requires `gettext`):
+```bash
+./contrib/locale/build_locale.sh electrum/locale/locale electrum/locale/locale
+```
+
+Python >= 3.10.0 is required. Key optional dependencies are in `contrib/requirements/`.
+
+## High-Level Architecture
+
+### Entry and Routing
+
+`run_electrum` is the single entry point. It parses config/CLI args and routes to one of three modes:
+- **GUI mode** — starts a Qt, QML, text, or stdio interface
+- **Daemon mode** — runs a background process that manages wallets and network, exposing an RPC socket
+- **Command mode** — sends an RPC command to a running daemon (or runs offline)
+
+The daemon is the central hub: it owns the `Network` instance, loads wallets, and services all clients.
+
+### Core Module Responsibilities
+
+| Module | Role |
+|--------|------|
+| `wallet.py` | Wallet logic: coin selection, address management, signing, history. Hierarchy: `Abstract_Wallet` → `Deterministic_Wallet` → `Standard_Wallet` / `Multisig_Wallet`; also `Imported_Wallet` |
+| `keystore.py` | Key material: HD derivation, hardware wallet abstraction, signing |
+| `transaction.py` | `Transaction` and `PartialTransaction` (PSBT) construction and parsing |
+| `network.py` | Manages the pool of server connections, subscriptions, request dispatching |
+| `interface.py` | Single Electrum-protocol TCP/SSL connection to one server |
+| `blockchain.py` | Header chain verification and tracking |
+| `address_synchronizer.py` | Keeps UTXOs, history, and labels in sync with the network |
+| `lnworker.py` | Lightning wallet logic (payments, channel management, routing) |
+| `lnpeer.py` | Lightning peer connection (BOLT messaging) |
+| `lnchannel.py` | Channel state machine |
+| `daemon.py` | Daemon process and JSON-RPC server |
+| `commands.py` | All CLI/RPC commands; also the authoritative list of public API calls |
+| `simple_config.py` | User configuration; wraps file-backed and in-memory config |
+| `storage.py` / `wallet_db.py` | Wallet file I/O with AES encryption and JSON serialization |
+| `plugin.py` | Plugin loader and base classes |
+| `bitcoin.py` | Address types, script helpers, encoding (Base58, Bech32m) |
+| `chains/` | Per-network constants (mainnet, testnet, regtest, signet) |
+
+### GUI Backends
+
+`electrum/gui/` contains four independent implementations:
+- `qt/` — full-featured desktop GUI (PyQt5/PyQt6)
+- `qml/` — mobile GUI (Qt Quick / QML)
+- `text.py` — curses terminal UI
+- `stdio.py` — minimal stdio interface
+
+### Plugin System
+
+`electrum/plugins/` holds all optional features: hardware wallets (Ledger, Trezor, BitBox02, ColdCard, Jade, KeepKey, …), swap servers, watchtowers, label sync, audio modem, etc. Plugins register hooks that the core calls at defined points.
+
+### Async Model
+
+Network and Lightning code is heavily async (asyncio). Background tasks run as coroutines managed by `TaskGroup` / `MonitoredTaskGroup`. GUI threads communicate with async tasks via `aiohttp`-style futures or Qt signals.
+
+### Testing Conventions
+
+- Base class: `ElectrumTestCase` in `tests/__init__.py` (extends `unittest.IsolatedAsyncioTestCase`)
+- Testnet mode: `@as_testnet` decorator on test classes/methods
+- Implementation sweeps: `@needs_test_with_all_aes_implementations`, `@needs_test_with_all_chacha20_implementations`
+- `FAST_TESTS = True` skips slow implementation variants
+- Test vectors live alongside tests as JSON files (e.g., `tests/test_vectors/`)