electrum-cash: how to use a cluster with multiple servers

Introduction

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

This example demonstrates how to create and connect to a cluster of servers, wait for the cluster to get ready, respond to changes in the cluster status and shut down the cluster when you're done using it.

Including the cluster library in your project

When you are using multiple servers for your project, you should include the cluster, either in CommonJS or as an ES2015 module depending on your project.

// Import the electrum client in CommonJS.
const { ElectrumCluster } = require('electrum-cash');

// Import the electrum client as an ES2015 module.
import ElectrumCluster from 'electrum-cash';

Set up the library and add servers to your cluster

You will need to create an instance of the electrum cluster with an optional distribution and confidence strategy and then add as many servers as you want.

We use the default 1-of-all strategy here, and will cover alternatives in a future articles.

// Initialize an electrum cluster.
const electrum = new ElectrumCluster('Your Electrum App Name', '1.4.3');

// Add some servers to the cluster.
electrum.addServer('bch.imaginary.cash');
electrum.addServer('electroncash.de');
electrum.addServer('electroncash.dk');
electrum.addServer('electron.jochen-hoenicke.de', 51002);
electrum.addServer('electrum.imaginary.cash');

Waiting for the cluster to be ready

Before you can start using the cluster, you need to wait for the required number of servers to connect and complete version negotiation.

// Wait for the cluster to become ready for use.
await electrum.ready();

Detecting cluster outages

The electrum-cash library automatically reconnects and tries to keep you connected to the servers at all times. However, outages are sometimes unavoidable and if one or more servers in your clusters become unavailable your cluster can be degraded or disabled.

To log a message when your cluster becomes degraded, listen for the degraded signal.

// Write to the console log when the cluster is degraded.
electrum.on('degraded', console.log.bind(null, 'cluster is degraded'));

To detect when your cluster us unusable, listen to the disabled signal.

// Function that will handle when cluster is disabled
const handleClusterOutage = function()
{
     // Handle the outage by pausing activites that require network or similar.
}

// Listen for cluster disable events.
electrum.on('disabled', handleClusterOutage);

To detect when your cluster status is automatically restored, listen to the ready signal.

Note that the ready signal is also emitted when the cluster initially becomes available.

// Function that will act when the cluster becomes available.
const handleClusterRestoration = function()
{
     // The cluster is at a good state.
}

// Listen for cluster ready events.
electrum.on('ready', handleClusterRestoration);

Shutting down when you're done

After you are done with the cluster, you should ask all connections to shut down gracefully.

// Close all connections gracefully.
await electrum.shutdown();