electrum-cash: strategic use of clusters

Introduction

Electrum-cash is a javascript/typescript library for communicating with electrum servers.

This article will showcase some common ways you can set up and configure clusters as well as give some examples for when you might want to use each setup.

Available configuration options

Before we look at the various setups, it is helpful to understand the terminology and parameters. In the context of this library we define the following terms:

• Cluster: A list of electrum servers to use.

• Confidence: Number of servers that need to be in agreement before we use their data.

• Distribution: How many of the available servers we select to request data from.

• Ordering: How we select which of the available servers to request data from.

The default settings

If you try to create a cluster and does not configure the settings, you will have a confidence of 1 so you will trust any server and get a dynamic cluster distribution of ALL which means that the cluster will be ready as soon as any server is available. The ordering is less important since requests will be sent to all servers, but is set to RANDOM.

The benefit of this approach is that it provides low latency and as such is well suited during development of your project, and also provides a good user experience.

// Initialize an electrum cluster using the default 1-of-ALL strategy.
const electrum = new ElectrumCluster('Your Electrum App Name', '1.4.3');

Hiding the big picture

When you send requests to your cluster, the servers you send to can learn information about your usage which might be undesirable. While it's not possible to both get the convenience of 3rd party servers and perfect privacy at the same time, you can configure your cluster to gain some privacy by not sending all requests to the same few servers.

To do so, you should set a low confidence and use a large number of servers with a low and random distribution.

The benefit of this approach is that it's very unlikely that any server will be able to fully track your usage. Sadly, it also means that it's possible to randomly send to high-latency servers which has an impact on the user experience.

// Initialize an electrum cluster with a 1-of-1 privacy-oriented strategy.
const electrum = new ElectrumCluster('Your Electrum App Name', '1.4.3', 1, 1);

// Add as many servers as possible
electrum.addServer('electrum.imaginary.cash');
...

Avoiding issues by consensus

When you are using multiple servers there is a chance they will not agree about the state of the network. It could be due to simple things like one server just having gotten a new block another server is not yet aware or, an accidental chainsplit where the servers consensus code made them follow different chaintips. It could also be due to the server operator being hostile and trying to defraud naive applications that trusts them without verifying the information.

It's recommended that you should always verify all information you are able to, but sometimes you just don't want bad data to begin with, in which case you can configure your cluster to require a higher confidence and then either using a random distribution, or a prioritized distribution with trusted servers added first.

The benefit of this approach is that no single server that gets compromised can cause your application to act on bad data, which reduces that attack surface of your application.

// Initialize an electrum cluster with a 2-of-3 consensus-oriented strategy.
const electrum = new ElectrumCluster('Your Electrum App Name', '1.4.3', 2, 3, ClusterOrder.RANDOM);

// Initialize an electrum cluster with a 2-of-3 consensus-oriented strategy.
const electrum = new ElectrumCluster('Your Electrum App Name', '1.4.3', 2, 3, ClusterOrder.PRIORITY);

// Add trusted servers first.. 
electrum.addServer('electrum.imaginary.cash');
electrum.addServer('bch.imaginary.cash');

// ..then as many backup servers as you want.
electrum.addServer('electroncash.de');
electrum.addServer('electroncash.dk');

Conclusion

By using electrum-cash clusters, you get automatic fail-over, automatic re-connection after outages and by choosing your confidence and disitribution strategy, you can choose how you want to balance performance, reliability and privacy.