# 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/`)
