purple-electrumwallet/quickstart.md

# Quickstart - Electrum Purple from source

This guide creates a complete local `.venv` on Ubuntu for:

- desktop Qt GUI
- QML GUI
- hardware-wallet Python dependencies
- tests and coverage

## System prerequisites

```bash
sudo apt update
sudo apt install -y \
  git python3 python3-venv python3-dev build-essential pkg-config automake libtool gettext \
  libsecp256k1-dev libusb-1.0-0-dev libudev-dev libhidapi-dev libzbar0 \
  libgl1 libegl1 libxkbcommon-x11-0 libxcb-cursor0 libxcb-xinerama0 \
  libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 \
  libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 qt6-wayland xvfb
```

Notes:

- `libsecp256k1-dev` avoids recompiling secp256k1 via `electrum_ecc`.
- `libzbar0` enables QR scanning/reading support.
- `xvfb` is useful for GUI/QML tests on headless systems.
- The `libxcb-*`, `libgl1`, `libegl1`, and `qt6-wayland` packages avoid common PyQt6 runtime errors on Ubuntu.

---

## 1. Clone the repository

If you are already inside the repository, just run:

```bash
git submodule update --init --recursive
```

## 2. Create and activate the virtual environment

```bash
python3 -m venv .venv
source .venv/bin/activate
```

Upgrade packaging tools:

```bash
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r contrib/requirements/requirements-build-base.txt
python -m pip install "Cython>=0.27"
```

---

## 3. Install dependencies

### Complete development environment

```bash
ELECTRUM_ECC_DONT_COMPILE=1 python -m pip install -e ".[full,qml_gui,tests]"
python -m pip install -r contrib/requirements/requirements-ci.txt
python -m pip install pytest-xdist pillow
```

What this installs:

- base runtime dependencies from `contrib/requirements/requirements.txt`
- `full`: Qt GUI, crypto, and hardware-wallet Python dependencies
- `qml_gui`: PyQt6/Qt6 packages suitable for the QML GUI
- `tests`: extra Python packages used by the test suite
- `requirements-ci.txt`: `pytest`, `coverage`, and `coveralls`
- `pytest-xdist`: optional parallel test execution with `-n auto`
- `pillow`: optional image support used by some hardware-wallet/plugin flows

Verify the main imports:

```bash
python -c "import PyQt6.QtCore, PyQt6.QtQml, PyQt6.QtQuick, PyQt6.QtMultimedia, electrum_ecc, cryptography; print('ok')"
```

---

## 4. Run Electrum from source

```bash
# Qt GUI (default)
./run_electrum

# Qt GUI on BitcoinPurple network
./run_electrum --bitcoinpurple -g qt

# BitcoinPurple network
./run_electrum --bitcoinpurple

# BitcoinPurple testnet
./run_electrum --bitcoinpurple_testnet

# QML GUI
./run_electrum --bitcoinpurple -g qml

# Text UI (terminal)
./run_electrum --gui text

# Daemon mode
./run_electrum daemon -d
```

After the editable install, the generated command should also work while the venv is active:

```bash
electrum-purple --bitcoinpurple -g qt
electrum-purple --bitcoinpurple -g qml
```

---

## 5. Run tests

```bash
# All tests
pytest tests -v

# Parallel (requires pytest-xdist)
pytest tests -v -n auto

# Single file
pytest tests/test_bitcoin.py -v

# BitcoinPurple tests
pytest tests/test_bitcoinpurple.py -v

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

# QML tests
QT_QPA_PLATFORM=offscreen pytest tests/qml -v

# QML tests on a headless system
xvfb-run -a pytest tests/qml -v
```

Run tests with coverage:

```bash
# Full suite with coverage
coverage run --source=electrum -m pytest tests -v
coverage report -m
coverage html

# QML tests with coverage
QT_QPA_PLATFORM=offscreen coverage run --source=electrum -m pytest tests/qml -v
coverage report -m
```

---

## Project structure (quick reference)

| Path | Contents |
|---|---|
| `run_electrum` | Main entry point |
| `electrum/constants.py` | Network parameters (Bitcoin, BitcoinPurple, …) |
| `electrum/blockchain.py` | Header verification and PoW difficulty |
| `electrum/wallet.py` | Wallet logic |
| `electrum/lnworker.py` | Lightning Network |
| `electrum/gui/qt/` | Desktop Qt GUI |
| `electrum/gui/qml/` | Mobile QML GUI (Android) |
| `electrum/chains/bitcoinpurple/` | BitcoinPurple servers and checkpoints |
| `tests/test_bitcoinpurple.py` | BitcoinPurple test suite |
| `contrib/requirements/` | Dependency files |