purple-electrumwallet/CLAUDE.md

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:

python3 -m pip install --user -e .

Run from source:

./run_electrum

Run all tests:

pytest tests -v

Run a single test file or test:

pytest tests/test_bitcoin.py -v
pytest tests/test_bitcoin.py::TestBitcoin::test_address -v

Run tests in parallel:

pytest tests -v -n auto

Build translations (requires gettext):

./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/)