Electrum eCash -- lightweight ECX wallet

A fork of Electrum for ECX, the Layer Two Labs Bitcoin hard fork ("eCash").

Licence:  MIT
Language: Python (>= 3.10)
Upstream: https://github.com/spesmilo/electrum  (v4.8.1)

Not affiliated with, endorsed by, or supported by the Electrum developers or Electrum Technologies GmbH. Do not report issues with this software to them. If you want the Bitcoin Electrum wallet, get it from electrum.org -- not from here. This wallet cannot connect to Bitcoin.

⚠ Pre-release. Do not use with funds you cannot afford to lose. There are no signed binaries, no reproducible-build attestation, and no update mechanism yet. Known gaps are listed in FORK.md. Build from source and read the diff.

What this is

ECX is a Bitcoin hard fork. Everything key- and address-related is byte-identical to Bitcoin -- same genesis block, same bc bech32 prefix, same WIF/xpub prefixes, same SLIP-44 coin type. A Bitcoin address is an ECX address, and nothing in the string tells you which chain it belongs to.

That similarity is the whole reason this fork exists rather than a config file: almost every place upstream says "Bitcoin" becomes silently wrong rather than obviously broken. This wallet talks only to ECX, sets ECX's replay-protection marker on every transaction, and refuses to broadcast one that could replay onto Bitcoin.

Which chain this build tracks

ECX launches in phases, and each phase is a different chain, forked from Bitcoin at a different height. Alpha and beta coins are destroyed and reissued at full launch, so a build only ever speaks to one of them.

Phase         beta  (betanet)
Fork height   967,680          -- Bitcoin-identical up to and including 967,679
Fork target   0x19044b7e       -- difficulty 1e9, vs Bitcoin's ~127e12
Server        ssl://explorer.beta.ecash.ninja:50002   (Fulcrum 2.1.2)
Explorer      https://explorer.beta.ecash.ninja/
Upstream C++  ecash-com/bitcoin @ betanet

Alphanet is not supported by this build and its coins no longer matter. An alpha-era data directory will not sync: delete ~/.electrum-ecash/blockchain_headers and ~/.electrum-ecash/forks before first run, and expect any existing wallet's transaction history to be rebuilt against the new chain.

Moving a build between phases is two constants plus a checkpoint rebuild, and it has a sharp edge or two -- the procedure is in FORK.md.

What we changed

The fork is a linear patch series on the GPG-signed upstream 4.8.1 tag. Most of it lives in new files, chiefly electrum/ecx.py, which holds every ECX parameter; show-fork-diff.sh prints the current split between new files and edits to pre-existing ones. The behavioural changes are a handful of one-liners -- the bulk of the rest is branding and packaging.

Read the whole thing in one command:

git log 4.8.1..HEAD                     # ~30 self-contained commits
contrib/ecx/show-fork-diff.sh           # summary
contrib/ecx/show-fork-diff.sh --full    # the complete patch
contrib/ecx/show-fork-diff.sh --markers # every '# ECX:' line in the tree

Every edit in an existing file is a one-liner tagged # ECX:, so grep -rn '# ECX:' electrum/ enumerates the entire fork surface.

That is deliberate. Wallets for claiming forkcoins are a classic malware lure, so "here is signed upstream Electrum, and here are our commits" needs to be checkable in a few minutes. See FORK.md for what each change does and why.

Running from source

Verified on macOS with Python 3.14 and on Linux.

git clone https://github.com/ecash-com/electrum-ecash.git
cd electrum-ecash
git checkout ecx/4.8.1
git submodule update --init

python3 -m venv .venv
.venv/bin/pip install -r contrib/requirements/requirements.txt

# NOT in requirements.txt -- that file is restricted to pure-python packages,
# but electrum/crypto.py hard-requires one of pycryptodomex/cryptography.
.venv/bin/pip install cryptography "dnspython[DNSSEC]"

.venv/bin/pip install PyQt6                                        # GUI
.venv/bin/pip install -r contrib/requirements/requirements-hw.txt  # hardware wallets

.venv/bin/python ./run_electrum

Data lives in ~/.electrum-ecash, never ~/.electrum, so this cannot disturb an existing Bitcoin Electrum install.

On Debian/Ubuntu you may also want libsecp256k1-dev (otherwise electrum-ecc compiles it locally, which needs automake and libtool) and python3-pyqt6.

Tests

contrib/ecx/run-tests.sh          # upstream's suite, minus tests our changes invalidate
contrib/ecx/run-tests.sh --audit  # re-run the excluded ones, to catch a stale list
contrib/ecx/check.sh              # static checks (undefined names, ecx imports)

Exclusions are listed with their cause in contrib/ecx/known-test-failures.txt, and were established by diffing against a pristine 4.8.1 checkout -- not assumed. Upstream's test files are deliberately left unedited so they keep merging cleanly.

Building binaries

CI builds unsigned artifacts on demand: Actions -> builds -> Run workflow, then pick a target (all, windows, macos, appimage, tarball, android).

Target	Notes
Windows	Docker + Wine, ~18 min
macOS	arm64 only (see below), ~9 min
AppImage	~9 min
tarball (x2)	Electrum-eCash-<version>.tar.gz
Android	excluded from all; over an hour, and the QML GUI is barely exercised by this fork

Upstream's tooling otherwise unchanged: Linux tarball * AppImage * macOS * Windows * Android

Nothing is signed. No Developer ID, no notarization, no Authenticode, no GPG attestation. macOS and Windows will both warn on first launch. See FORK.md.

macOS is arm64 only

Upstream builds macOS on a pinned 11.7.10 Intel VM, because that is what makes the binary reproducible. Every hosted Intel macOS runner is retired (macos-13 went on 2025-12-04) and GitHub drops x86_64 entirely after Fall 2027, so CI can only produce arm64. The CI dmg will not run on an Intel Mac. Intel coverage needs the pinned VM, or a universal2 build, which is still upstream's open TODO.

Three fixes were needed to build for Apple Silicon at all. They are upstream bugs for arm64, not fork-specific -- nobody had built Electrum for Apple Silicon before:

• contrib/osx/make_osx.sh hardcoded ARCHFLAGS="-arch x86_64", so every C extension compiled for the wrong architecture on an arm64 host; Cython then could not be imported, which surfaced as a confusing failure in an unrelated package's build backend. Now -arch $(uname -m).
• contrib/make_zbar.sh needs an explicit -liconv: iconv_open/iconv_close resolve implicitly from libSystem on x86_64 but not arm64.
• contrib/osx/pyinstaller.spec hardcoded target_arch='x86_64'; now derived from platform.machine().

All three leave upstream's Intel VM behaviour identical, and are separable commits if we ever offer them upstream -- they will need them by 2027.

Maintaining the fork

master tracks upstream untouched; our work lives on ecx/<upstream-tag> branches, rebased onto signed upstream tags so every release has verifiable provenance. ECX relaunches once more (full, at height 973,728) and that relaunch is a different chain again -- the procedure is in FORK.md.

Contributing

Issues and pull requests here: https://github.com/ecash-com/electrum-ecash.

Please do not take questions about this fork to upstream's issue tracker, IRC channel, or Crowdin project. Bugs in unmodified upstream code should go upstream; bugs in the ECX changes belong here.

The guiding constraint is that the diff stays small: every line added is a line to be re-merged on every upstream security release.

Credit

Electrum is the work of Thomas Voegtlin and the Electrum contributors, MIT licensed. This fork only exists because of theirs.