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

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:

git submodule update --init --recursive

2. Create and activate the virtual environment

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

Upgrade packaging tools:

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

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:

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

---

4. Run Electrum from source

# 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:

electrum-purple --bitcoinpurple -g qt
electrum-purple --bitcoinpurple -g qml

---

5. Run tests

# 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:

# 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