electrum-cash: debugging problems and reporting issues

Introduction

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

This example demonstrates how to enable debug output, control what debug messages to show and where to submit bug reports.

Sample application

For this article, we will be using a small and simple application that connects to a server, subscribes to notification for given address, waits 10 seconds and then shuts down.

// Include the electrum-cash library in our project.
const { ElectrumClient } = require('electrum-cash');

// Wrap the application in an async function to allow async/await.
const main = async function()
{
	// Initialize an electrum client.
	const electrum = new ElectrumClient('Electrum client test', '1.4.3', 'bch.imaginary.cash');

	// Wait for the connection to be ready and version negotiation to complete.
	await electrum.connect();

	// Log address change notifications for ☯ jonathan#100 <qr4aadjrpu73d2wxwkxkcrt6gqxgu6a7usxfm96fst>
	await electrum.subscribe(console.log, 'blockchain.address.subscribe', 'qr4aadjrpu73d2wxwkxkcrt6gqxgu6a7usxfm96fst');

	// Disconnect after 10 seconds.
	setTimeout(electrum.disconnect.bind(electrum), 10000);
}

// Start the application.
main();

Enable debug output

The electrum-cash library uses the debug library to manage log output. To enable all debug logs, simply start the application with DEBUG="*" prepended to the command line or set as an environment variable.

Note: this also enables debug output for all other components that use the debug library.

$ DEBUG="*" node example.js

Configure what output to show

The electrum-cash library can enable or disable specific types of output. Set the DEBUG environment variable to a list of entries separated by commas, and to exclude output, prepend the entry with a minus sign.

For example, to show all electrum-cash output, but not the keep-alive pulse entries:

$ DEBUG="electrum-cash:*, -electrum-cash:pulse*" node example.js

In order to keep the log output aligned, some of the log names currently end with one or more spaces, and as such you might need to end the log name with a wildcard symbol.

List of available outputs

The electrum-cash library currently have 6 different output types:

• Warnings and Errors: Messages that inform you when things can or have gone wrong.

• Network, Client and Cluster: Provides insight into how the library operates.

• Pulses: Prints a log message when we send a message to keep the connection alive.

Reporting bugs and issues

If you have come across a bug or are having a problem with the electrum-cash library, please let us know. Go to the repository issues page to see if we are already aware of your situation, and make a new issue if you want to.