markblundeberg / electron-cash

Electrum; Bitcoin thin client

Electron Cash - Lightweight Bitcoin Cash client

Licence: MIT Licence
Author: Electron Cash Developers
Language: Python
Homepage: https://electroncash.org/

Getting started

Note: If running from source, Python 3.6 or above is required to run Electron Cash. If your system lacks Python 3.6, you have other options, such as the AppImage / binary releases or running from source using pyenv (see section Running from source on old Linux below).

macOS: It is recommended that macOS users run the binary .dmg as that's simpler to use and has everything included. Otherwise, if you want to run from source, see section Running from source on macOS below.

Electron Cash is a pure python application forked from Electrum. If you want to use the Qt interface, install the Qt dependencies:

sudo apt-get install python3-pyqt5 python3-pyqt5.qtsvg

If you downloaded the official package (tar.gz), you can run Electron Cash from its root directory (called Electron Cash), without installing it on your system; all the python dependencies are included in the 'packages' directory. To run Electron Cash from its root directory, just do:

./electron-cash

You can also install Electron Cash on your system, by running this command:

sudo apt-get install python3-setuptools
python3 setup.py install

This will download and install the Python dependencies used by Electron Cash, instead of using the 'packages' directory.

If you cloned the git repository, you need to compile extra files before you can run Electron Cash. Read the next section, "Development Version".

Hardware Wallet - Ledger Nano S

Electron Cash natively support Ledger Nano S hardware wallet. If you plan to use you need an additional dependency, namely btchip. To install it run this command:

sudo pip3 install btchip-python

If you still have problems connecting to your Nano S please have a look at this troubleshooting section on Ledger website.

Development version

Check your python version >= 3.6, and install pyqt5, as instructed above in the Getting started section above or Running from source on old Linux section below.

If you are on macOS, see the Running from source on macOS section below.

Check out the code from Github:

git clone https://github.com/Electron-Cash/Electron-Cash
cd Electron-Cash

Install the python dependencies:

pip3 install -r contrib/requirements/requirements.txt --user

Create translations (optional):

sudo apt-get install python-requests gettext
./contrib/make_locale

Compile libsecp256k1 (optional, yet highly recommended):

sudo apt-get install libtool automake
./contrib/make_secp

For plugin development, see the plugin documentation.

Running unit tests (very optional, advanced users only):

pip install tox
tox

Tox will take care of building a faux installation environment, and ensure that the mapped import paths work correctly.

Running from source on old Linux

If your Linux distribution has a different version of python 3 (such as python 3.5 in Debian 9), it is recommended to do a user dir install with pyenv. This allows Electron Cash to run completely independently of your system configuration.

1. Install pyenv in your user account. Follow the printed instructions about updating your environment variables and .bashrc, and restart your shell to ensure that they are loaded.
2. Run pyenv install 3.6.9. This will download and compile that version of python, storing it under .pyenv in your home directory.
3. cd into the Electron Cash directory. Run pyenv local 3.6.9 which inserts a file .python-version into the current directory.
4. While still in this directory, run pip install pyqt5.
5. If you are installing from the source file (.tar.gz or .zip) then you are ready and you may run ./electron-cash. If you are using the git version, then continue by following the Development version instructions above.

Running from source on macOS

You need to install either MacPorts or HomeBrew. Follow the instructions on either site for installing (Xcode from Apple's developer site is required for either).

1. After installing either HomeBrew or MacPorts, clone this repository and switch to the directory: git clone https://github.com/Electron-Cash/Electron-Cash && cd Electron-Cash
2. Install python 3.6 or 3.7. For brew: brew install python3 or if using MacPorts: sudo port install python36
3. Install PyQt5: python3 -m pip install --user pyqt5
4. Install Electron Cash requirements: python3 -m pip install --user -r contrib/requirements/requirements.txt
5. Compile libsecp256k1 (optional, yet highly recommended): ./contrib/make_secp. This requires GNU tools and automake, install with brew: brew install coreutils automake or if using MacPorts: sudo port install coreutils automake
6. At this point you should be able to just run the sources: ./electron-cash

Creating Binaries

Linux AppImage & Source Tarball

See contrib/build-linux/README.md.

Mac OS X / macOS

See contrib/osx/.

Windows

See contrib/build-wine/.

Android

See android/.

iOS

See ios/.

electron-cash's Issues

more robust input checking

Collin was on a Tor electron server and it was too slow during blame verify... so the check_input_electrumx timed out.

Not only should timeouts not pose an issue, but also we probably want to blast out all the queries in parallel since they can be so darn slow to respond. We also don't want to have any of this cause us to miss the end of the blame verify window.

privacy improvement: logging of rounds

In order to stop the server from playing multi-round tricks, the session hash needs to include a log of things shared from previous rounds.

Also, the startround message should include a clock timestamp like introduced in #8.

don't fuse when network not well-connected

todo fusion

Critical::

• Blockchain checking during blame is still TODO.
• Client needs sensible limits on feerate and excess_fee, so a malicious server can't cause them to blast everything into miner fees.
• Test server prevents multiple players from same IP going in same round. (But they may wait together)
• Fix bugs. (see other Issues)
• Coin chooser tweaking. -- Better coin fraction selection. Whale wallets may want to fuse at lower tiers. Some users may want to consolidate down to fewer utxo.

Important:

• Fusions watch their source coins and stop themselves if coins are spent. (this is especially important when still in waiting pool since it's not too late to avoid blame)
• Waiting autofusions stop when user stops autofusion. Not sure what to do about in-progress.
• Client and server detection on 'sensibly private' fusions and aborting (based on examining components).
• When stopping wallets, need a way for user to stop it cold so they don't have to wait forever.
• Sanity protections against infinite rounds, both client and server. (what happens when nobody is blamed?)
• Error indicator when fusion just isn't working right, and a clear diagnostic. Some kind of (!) icon in statusbar.
  • Network errors
  • Can't-find-a-tier errors
  • Fusion procedural failures
• Make it less net-spammy when doing auto fusions which constantly fail. Need to remember the server's last greeting params message, and do a connection AFTER selecting outputs. See #13
• Greeting should indicate something like: height, tip hash and prevhash. Clients can use this to identify if they're on different chain.
• Complete fusions need a wait time after done, before unfreezing coins. If the transaction hasn't shown up in wallet yet then another fusion might mistakenly grab one of those coins. (it will likely harmlessly fail due to the periodic input spend sanity check, but it could happen it starts rounds too soon)
• Lighten the Tor connection load: see #8 .
• Better UX for wallet parameter selection ('consolidation mode' etc.)
• Rate limiting on fusions, for people who want to leave it running constantly
• Add metadata tracking, add limit on fusion depth for people who just want to increase privacy sligthly and don't want to be burning fees all day long.
• (BIG work) make electron cash / cash fusion actually provide privacy (marking coins, spending them appropriately).

Wishlist:

• #20 - Variable number of commitments/components per player.
  • Note: max_excess_fee should now be max_excess_fee_per_component.
  • Players need to announce their component count during pool registry, to avoid absurd fee condition and so the server knows how many blind nonces to send during round start.
  • Question: what random distribution should client use to choose number of excess (blank) components?
• Easier Tor for users (at first just find tor installation, later do bundling?)
• Clean up race condition between coin selection and coin-freezing. (esp in user selection)
• Test server SSL. Note the server needs to know its host so it can issue covert host correctly.
• For manually-started fusions make a window that shows progress / allows restarting / etc..
• Sometimes we want to cancel stale autofusions and try new ones, since wallet may have new coins, or we might want to try different tiers.
• Better user-friendly diagnostic panel.
• Whale splitter and whale consolidator (having a single giant input or output that gets peeled off, or built up).
• #21- Automatic address consolidation for addresses with many utxo. (Currently, Fusion ignores addrs with >3 coins)

bug: frozen coin updates don't notify GUI

fusion bug: ctrl-C doesn't initiate right shut down

feature: Provide a heuristic for a coin's privacy in the tx description.

The specific idea I had is if we put the total in/out count at the front of fusion descriptions, then that description also appears on any coins in the coin chooser. That helps a sophisticated user to select coins and I assume the cost of adding the information is low.

idea: client dynamic choosiness

Right now we have a few problems:

• Liquidity providers get turbo fusions sometimes and may want to rate limit.
• If they rate limit by turning off fusion entirely then liquidity is unfortunately lower. Whether this happens manually or automatically, it sucks.
• We want liquidity providers to be always available to help make big fusions even bigger. Yet also make them happy by having rate limiting.

If clients can specify to the server 'I only want to participate in fusions txes with at least N tx components' (or pools with N fusion components), then they can vary this limit over time to rate limit the fusions they are involved in. When a fusion happens they bump up the limit, and if they are waiting a long time without action they can lower the limit.

This ought to lead to a critical mass effect amongst any liquidity providers. They can set their minimum to a pretty high point, corresponding to, say, 400 fusion components. If there are multiple liquidity providers then the server can notice this and bring them in. For example let's say there are 8 such liquidity providers who would altogether bring 200 fusion components if included. Then only 200 fusion components from regular folks would be needed to trigger this.

This also gives a natural repulsion effect if there are too many liquidity providers -- if they start to fuse constantly with each other then they will dynamically back off. But if organic demand comes in, there will be a ton of them in waiting, ready to make giant fusions.

server params caching and pre-connection client side work (less net spammy!)

• Put server params in a submessage.
• In the initial greeting, server provides hash of server params.
• Client checks hash against in-memory cache. If different/missing then can request full params.

Then, client can do pre-connection things like choosing inputs / allocating outputs; if params change compared to the known conditions, then abort.

be gentler on Tor

Make a Tor connection counting system... remember that for each fusion round, we open 23+ tor connections.

After a heavy round where many failures happened so many tor connections were made, we need a cooldown time of 10 minutes before starting up again.

• remember times and numbers of tor connections made
• connections that happened more than 10 minutes ago (+1 minute to disconnect) can be forgotten.
• if the number of connections made in last 10 minutes is >60, then delay starting fusions.

bug: txid labels sometimes don't stick

observed by both sploit (only one of two labels stuck) and JF (no labels stuck)

watching-only wallet and autofuse play badly together

0-balance wallets shouldn't cause a problem

proto optimization: early kick clients but keep round going

If clients fail before the blind signature responses are shared with them, (i.e., their commitments are late or bad) they can be simply dropped from the clients pool and the round keeps going without them.

This change can be done on server without any protocol change.

protocol change: make fewer Tor connections and be more reliable and faster!

When implementing fusion I didn't anticipate that Tor connections could be so slow and unreliable to establish, nor the DoS limits in place. Right now there is a glaring problem in the current protocol which is that on every round, every player establishes new Tor connections. It doesn't have to be this way. Clients can keep the connections open and share the same component (with different salt hash but otherwise same) on the same connection.

New approach:

• The covert server persists until all rounds are finished.
• Clients keep their covert connections open until all rounds are finished.
• The covert port is instead provided to clients in the FusionBegin message.

This is unfortunately a significant architectural change. It can be achieved in steps:

1. The client needs to start reusing the same randomized user/pass for the proxy stream isolation on subsequent rounds. This will make it so Tor reuses the same circuit, provided the next round is on the same IP and the user has not turned on IsolateDestPort (which as I understand is not recommended anyway).
2. The server should not close covert connections after receipt of data. The CovertServer needs to persist longer and allow the round key to be changed during its life. The server can then be changed to keep using the same CovertServer for each round (telling same port to clients each time).
3. Once both client and server have been upgraded per 1 and 2, the covert server/port can be moved into the fusionbegin message. This will also involve adding a new 'Warmup' phase that happens before round 1, and likewise tightening up the covert submissions phase. Need to be careful about the timing as round 1's covert window limits will be used to enforce that the FusionBegin message was sent to everyone at the same time (i.e., covert_T0 will be referenced to FusionBegin for round 1; for subsequent rounds referenced to StartRound).
4. It may be needed for clients to establish new spare connections as rounds progress, if it happens that the connections get randomly dropped.

As an additional privacy boost, clients should reuse the same random time delta for submissions on each round. If each round uses a different delta, like now, then the server gains new info about the client's time window on each round.

Auto per-address consolidation (brainstorm)

• Can't just naively consolidate everything we see because that would be a privacy risk.
• With new fusion protocol allowing more components, this will be less of an issue since >3 on one address is not so bad.
• By consolidating back to the same addr, the coin chooser still knows which txids are correlated.

Possible idea:

1. Every candidate addr has a certain chance per unit time of being consolidated.

   This can be implemented sanely by having fusion calculate the number N of consolidation candidates, then multiplying this by the base rate gamma. N*gamma is the rate of any address being consolidated. Fusion generates an exponential random timestamp according to this rate, and saves it in the wallet file. When the timestamp is reached, then a random consolidation candidate address is chosen and consolidated.

2. Not sure what the best choice for the base time constant is. 1 day, perhaps?

Fusion protocol upgrade items

For 'version 2' protocol it is worth bringing in a bunch of things at once. Each protocol upgrade is an annoyance for users who must update their wallet version. Combining everything into one big switchover, both client and server can thereafter be polished up independently.

Key items:

• Params prefetching/caching (#13 )
  • Not only does this reduce traffic, it means on the wallet side there are more options for pre-adjusting a fusion (For example, user could generate a manual fusion candidate and remove unwanted tiers) and the API is also more convenient for third party plugins to do fusions. Desired flow is setup-adjust-connect, with failure in case of a (rare) change in parameter set.
• Players indicate dynamic number of components, and a minimum-total-component-count when subscribing. (#17)
  • Server will primarily use component count to determine launching/ending of fusions. Though each player can indicate a different minimum, it's still easy for server to figure out the thresholds.
• Encrypted connections for covert submission (so Tor exit nodes can't spy on the process, even though they don't learn much as-is); multiplexed via one static port so server admin is easier.
• Minor change: minimum excess fee is fixed by protocol (split tx overhead over the indicated minimum # of components) instead of being server-defined.
• Protocol fixes suggested by Kudelski.

Timing and privacy issues

Turning off fusion suddenly with hundreds of utxo, then coming back months later and fusing them all, is a pretty big privacy giveaway.

Ideas:

• Write guides to encourage users to consolidate before closing wallet for extended time.
• Add detection in fusion plugin on startup, to check whether coins have a common age and to warn the user.
• Add nag warning when wallet is closed / autofusions are stopped, and wallet has many coins.
• Develop 'slow mode' where new coins have a random delay before they are allowed to be fused.
  • This works two ways: the wallet will end up with a larger spread of fusion coin creation times, and it will have a larger spread in coin spend times.
  • In order that slow mode users don't stand out, it is helpful if regular fusion will occasionally slow some coins. This can be difficult.