15.3 Receiving Bitcoind Notifications with ZMQ

NOTE: This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning.

§15.2 showed one of the advantages of accessing Bitcoin's RPC commands through a programming language: the ability to reasonably create much more complex programs. This chapter reveals another one: the ability to integrate with other libraries and to do more difficult things, such as monitoring for notifications.

This section will show how to create a simple listener for the Bitcoin blockchain to receive notifications using ZMQ-based (http://zeromq.org/) notification interface. It will then link to your bitcoind, which supports connection points that clients can subscribe to in order to get notified about blockchain events like raw transactions or raw blocks.

📖 What is ZMQ? ZeroMQ (ZMQ)is a high-performance asynchronous messaging library that provides a message queue. ZeroMQ supports common messaging patterns (pub/sub, request/reply, client/server and others) over a variety of transports (TCP, in-process, inter-process, multicast, WebSocket and more), making inter-process messaging as simple as inter-thread messaging. You can find more details about ZMQ notifications and others kind of messages in this repo.

Setting Up ZMQ

Before you can create a blockchain listener, you will need to configure bitcoind to allow ZMQ notifications, and the you'll also need to install a ZMQ library to take advantage of that.

Configuring `bitcoind` for ZMQ

Bitcoin Core is is ZMQ-ready, but you must specify ZMQ endpoints. ZeroMQ publish-sockets prepend each data item with an arbitrary topic prefix that allows subscriber clients to request only those items with a matching prefix. There are currently four topics:

$ bitcoind --help | grep zmq | grep address
  -zmqpubhashblock=<address>
  -zmqpubhashtx=<address>
  -zmqpubrawblock=<address>
  -zmqpubrawtx=<address>

You can make an endpoint accessible by adding appropriate lines to your ~/.bitcoin/bitcoin.conf file and restarting your daemon.

zmqpubrawblock=tcp://127.0.0.1:28332
zmqpubrawtx=tcp://127.0.0.1:28333

You can then test its working using the getzmqnotifications RPC:

$ bitcoin-cli getzmqnotifications
[
  {
    "type": "pubrawblock",
    "address": "tcp://127.0.0.1:28332",
    "hwm": 1000
  },
  {
    "type": "pubrawtx",
    "address": "tcp://127.0.0.1:28333",
    "hwm": 1000
  }
]

Your bitcoind will now issue ZMQ notifications

Installing ZMQ

To take advantage of those notifications, you need a ZMQ library to go with your C; we'll be using that instead of the libbitcoinrpc library in this section, to show the variable power of C. FOrtunately, this one is available as a standard Debian package:

$ sudo apt-get install libzmq3-dev
$ sudo apt-get install libczmq-dev

You're now ready to code!

Writing Your Notification Program

The following C program is a simple client that subscribes to a ZMQ connection point served by bitcoind and reads incoming messages.

The program receives two parameters: the first parameter is the "server", the TCP connection point exposed by bitcoind that should be tcp connection point; and the second is the "topic", which is currently zmqpubhashblock, zmqpubhashtx, zmqpubrawblock, or zmqpubrawtx. The topic must be supported through the bitcoin.conf and the server's IP address and port must match what's defined there.

#include <czmq.h>
int main(int argc, char ** argv) {

  char *zmqserver;
  char *topic;

  if (argc < 3) {
    printf("\nUSAGE:\nchainlistener <tcp://localhost:port> <topic>\n\n");
    return 0;
  } else {
    zmqserver = argv[1];
    topic = argv[2];
  }

You will open a ZMQ socket to the defined server for the defined topic:

  zsock_t *socket = zsock_new_sub(zmqserver, topic);
  assert(socket);

After that, you wait:

  while(1) {
    zmsg_t *msg;
    int rc = zsock_recv(socket, "m", &msg);
    assert(rc == 0);

    char *header = zmsg_popstr(msg);
    zframe_t *zdata = zmsg_pop(msg);
    unsigned int *no = (unsigned int*)zmsg_popstr(msg);

    char *data = zframe_strhex(zdata);
    int len = zframe_size(zdata);
    printf("Size: %d\n", len);
    printf("Data: %s", data);
    printf("\nNo: %d\n", *no);

    free(header);
    free(data);
    free(no);
    free(zdata);
    zmsg_destroy(&msg);
    sleep(1);
 }

While, waiting, you watch for messages on the ZMQ socket. Whenever you receive a message, you will pop it off the stack and report out its number, its length, and most importantly the data.

That's it!

Of course when you're done, you should clean up:

  zsock_destroy(&socket);
  return 0;
}

Testing the Notification Code

The source code is in the src directory as usual. You should compile it:

$ cc -o chainlistener chainlistener.c -I/usr/local/include -L/usr/local/lib -lzmq -lczmq

Afterward, you can run it with the topics and addresses you defined in your bitcoin.conf:

$ ./chainlistener tcp://127.0.0.1:28333 rawtx
Size: 250
Data: 02000000000101F5BD2032E5A9E6650D4E411AD272E391F26AFC3C9102B7C0C7444F8F74AE86010000000017160014AE9D51ADEEE8F46ED2017F41CD631D210F2ED9C5FEFFFFFF0203A732000000000017A9147231060F1CDF34B522E9DB650F44EDC6C0714E4C8710270000000000001976A914262437B129CF8592AB2EDC59C07D19C57729F72888AC02483045022100AE316D5F21657E3525271DE39EB285D8A0E89A20AB6413824E88CE47DCD0EFE702202F61E10C2A8F4A7125D5EB63AEF883D8E3584A0ECED0D349283AABB6CA5E066D0121035A77FE575A9005E3D3FF0682E189E753E82FA8BFF0A20F8C45F06DC6EBE3421079111B00
No: 67
Size: 249
Data: 0200000000010165C986992F7DAD22BBCE3FCF0BF546EDBC3C599618B04CFA22D9E64EF0CE4C030000000017160014B58E0A5CD68B249F1C407E9AAE9CD0332AAA3067FEFFFFFF02637932000000000017A914CCC47261489036CB6B9AA610857793FF5752E5378710270000000000001976A914262437B129CF8592AB2EDC59C07D19C57729F72888AC0247304402206CCC3F3B4BE01D4E532A01C2DC6BC3B53E4FFB6B494C8B87DD603EFC648A159902201653841E8B16A814DC375129189BB7CF01CFF7D269E91178645B6A97F5C7F4F10121030E20F3D2F172281B8DC747F007DF24B352248AC09E48CA64016942A8F01D317079111B00
No: 68
Size: 250
Data: 02000000000101E889CFC1FFE127BA49F6C1011388606A194109AE1EDAAB9BEE215E123C14A7920000000017160014577B0B3C2BF91B33B5BD70AE9E8BD8144F4B87E7FEFFFFFF02C34B32000000000017A914A9F1440402B46235822639C4FD2F78A31E8D269E8710270000000000001976A914262437B129CF8592AB2EDC59C07D19C57729F72888AC02483045022100B46318F53E1DCE63E7109DB4FA54AF40AADFC2FEB0E08263756BC3B7A6A744CB02200851982AF87DBABDC3DFC3362016ECE96AECFF50E24D9DCF264AE8966A5646FE0121039C90FCB46AEA1530E5667F8FF15CB36169D2AD81247472F236E3A3022F39917079111B00
No: 69
Size: 250
Data: 0200000000010137527957C9AD6CFF0C9A74597E6EFCD7E1EBD53E942AB2FA34A831046CA11488000000001716001429BFF05B3CD79E9CCEFDB5AE82139F72EB3E9DB0FEFFFFFF0210270000000000001976A914262437B129CF8592AB2EDC59C07D19C57729F72888AC231E32000000000017A9146C8D5FE29BFDDABCED0D6F4D8E82DCBFD9D34A8B8702483045022100F259846BAE29EB2C7A4AD711A3BC6109DE69AE91E35B14CA2742157894DD9760022021464E09C00ABA486AEAA0C49FEE12D2850DC03F57F04A1A9E2CC4D0F4F1459C012102899F24A9D60132F4DD1A5BA6DCD1E4E4B6C728927BA482C2C4E511679F60CA5779111B00
No: 70
.......

Summary Receiving Bitcoind Notifications with C.md

By using ZMQ framework, you can easily receive notifications by subscribing to a connection point exposed by bitcoind changing configuration file.

🔥 What is the Power of Notifications? With notifications, you're no longer entirely dependent upon users to issue commands. Instead, you can create programs that monitor the Bitcoin blockchain and take appropriate actions when certain things occur. This in turn could be merged with the RPC commands that you programmed in previous sections. This is also a big step beyond what you could do with shell scripts: certainly, you can create infinite-loop listener shell scripts, but programming languages tend to be a better tool for that task.

What's Next?

Learn more about "Talking to Bitcoind with Libwally" in Chapter 16: Talking to Bitcoind with Libwally.

8.1 KiB Raw Blame History