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:**
```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/`)

---

## BitcoinPurple (BTCP) Support

BitcoinPurple is a Bitcoin fork with 1-minute blocks and a shorter difficulty retarget window. The Electrum client has been extended to support it as a first-class network alongside mainnet and testnet.

### Key Parameters (differ from Bitcoin)

| Constant | Bitcoin | BTCP |
|----------|---------|------|
| `DIFFICULTY_ADJUSTMENT_INTERVAL` | 2016 blocks | **120 blocks** |
| `POW_TARGET_TIMESPAN` | 1,209,600 s | **7,200 s** |
| `MAX_TARGET` | `0x00000000ffff…` (compact `0x1d00ffff`) | `0x00000ffff…` (compact `0x1e0fffff`) |
| `POW_GENESIS_BITS` | `None` (derived from MAX_TARGET) | **`0x1e0ffff0`** (genesis nBits differ from powLimit) |
| `MAX_ADJUSTMENT_FACTOR` | 4 | 4 |

`POW_GENESIS_BITS` is non-`None` for BTCP because the genesis block's `nBits` (`0x1e0ffff0`) is stricter than the `powLimit` compact (`0x1e0fffff`). `get_target(-1)` in `blockchain.py` returns `bits_to_target(POW_GENESIS_BITS)` when this is set, so period-0 header verification passes the exact equality check.

### Retarget Clamping (BTCP only)

At each 120-block boundary:
```
actual_timespan = clamp(last.time - first.time, 1800, 28800)   # [7200/4, 7200*4]
new_target = old_target * actual_timespan / 7200
new_target = min(new_target, MAX_TARGET)
```

### Critical `blockchain.py` Logic

`verify_chunk()` has two paths:
- `adj_interval == CHUNK_SIZE` (Bitcoin, 2016): reads old targets from on-disk headers.
- `adj_interval < CHUNK_SIZE` (BTCP, 120): retargets happen *within* a chunk, so headers are still in RAM (the buffer being verified). Uses an internal `_read_hdr(data, i)` helper to read from the buffer instead of `read_header()`.

### Files

| Path | Purpose |
|------|---------|
| `electrum/constants.py` | `BitcoinPurple` and `BitcoinPurpleTestnet` classes with all chain params |
| `electrum/blockchain.py` | `verify_chunk`, `get_target`, `can_connect` — all generalised for per-chain PoW constants |
| `electrum/chains/bitcoinpurple/servers.json` | Known ElectrumX servers (TCP 51001, SSL 51002) |
| `electrum/chains/bitcoinpurple/checkpoints.json` | SPV checkpoints (one entry = one 2016-block chunk) |
| `tests/test_bitcoinpurple.py` | 46 BTCP-specific tests (address encoding, difficulty, header verification) |
| `tecnichal-data.md` | Complete BTCP parameter reference (ports, genesis, PoW, LN, ElectrumX) |

### Running with BitcoinPurple

```bash
# Mainnet
./run_electrum --bitcoinpurple

# Testnet
./run_electrum --bitcoinpurple_testnet

# BitcoinPurple tests only
pytest tests/test_bitcoinpurple.py -v

# Blockchain + bitcoin + BitcoinPurple together
pytest tests/test_blockchain.py tests/test_bitcoin.py tests/test_bitcoinpurple.py -v
```

### LN Block-Scaled Timeouts

BTCP has 1-minute blocks (10× faster than Bitcoin). All LN timeout values expressed in blocks must be scaled ×10 to preserve the same real-world security windows (e.g. `to_self_delay` 144 → 1440, `cltv_expiry_delta` 40 → 400). See `tecnichal-data.md §8.3` for the full table.