Explore Website

Building a Bitcoin protocol CLI using Javascript

Introduction

In this tutorial, we will be building our very own command line interface for the bitcoin wire protocol which can be used for simple debugging or educational purposes.

Background

The bitcoin core client currently comes bundled with a Remote Procedure Call (RPC) client tool called bitcoin-cli. In our Bitcoin wire protocol 101 however, we demonstrated how you can communicate over the raw TCP bitcoin socket by using existing command line based tools.

In this tutorial we will be taking this a step further by implementing our own command line tool which simplifies this process. Something I find very useful is talking to TCP services using either telnet or netcat. Testing an http server over clear text is a simple process.

Here is a simple command for connecting to an http server over port 80 and issuing an HTTP HEAD request.

Unfortunately, none of these tools work out of the box due to the bitcoin wire protocol being binary and not clear text. If you know of one, please feel free to leave it in the comments. Either way, we will be writing our own so we can learn more about how this works in detail.

Before we begin

So, let's firstly have a look at what we could expect from having a tool which helps us test a connection to a remote node and printing out its version number to screen.

The connection

Our first challenge will be to establish and test the connectivity to a bitcoin node. For this we will make use of the net package provided by nodejs. Open up your favourite text editor, and create an index.js file containing the follow:

Note: There a are many useful packages which help in creating complex cli tools including prompt, commander and yargs. We have omitted these for the sake of simplicity, but feel free to explore these yourself.

The conversation

Now that we've been able to successfully test a remote connection, let's test this against our bitcoin server. You can either test this against your own server, or by selecting a node as explained in our previous tutorial on Bitcoin Network statistics.

As previously demonstrated in that tutorial, here is a snippet from our latest dnsseed.dump file.

It is not recommended that you execute commands against these nodes unless it is either your own, or you have informed the owner of that node that you will be conducting these tests. The protocol will however ban you if you start flooding it with spam or invalid messages. For the purposes of our tutorial, we will be poking at a local regtest instance.

Note: We have provided a simple docker container configured in regtest mode that you can install for testing purposes.

Now that we've tested for connectivity, let's get into some more interesting things.

Note: Etiquette
Remember, from our Bitcoin wire protocol 101 tutorial. When a node creates an outgoing connection, it will immediately advertise its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.

To establish a conversation with our remote node, we'll need to first announce ourselves. We can do this by updating our connection function as follows. We are currently using

Nice! If we receive some response as demonstrated in the above example, we should be in good shape. If not, there might be something wrong with the message you are sending, or it could be that the service running on that port is not a bitcoin node! This should however be unlikely assuming you are confident that the host and port are in fact correct.

Note: You can always look at the debug.log file of your node to see if it is receiving incoming requests. Ensure that you have updated your bitcoin.conf file to set debug=1.

Next up, we'll need to sanitise the response received from the targeted node. You might notice some strings including version, /Satoshi:0.12.1/ or even verack. This is because these are ascii bytes wrapped in our general bitcoin messaging protocol data.

We can decode this by first converting our response to a buffer as follows.

Conclusion

In this tutorial, we walked through the various steps for building our very own bitcoin command line interface! You might wish to extend this with some of the other message types, but this should get you started!

Explore Website

About Bitcoin Developer Network

The Bitcoin Developer Network (BDN) is a community-driven project looking at educating the generation of Bitcoin developers. We invite developers, authors, editors, proofreaders, enthusiasts, subject matter experts and technical writers to get in touch so that we may reduce the barrier to entry in developing solutions at various layers of this technology.

Bitcoin Developer Network Newsletter

Enter your email address to subscribe to this blog and receive notifications of new posts by email.