1# Block and Transaction Broadcasting With ZeroMQ 2 3[ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP 4connections, inter-process communication, and shared-memory, 5providing various message-oriented semantics such as publish/subscribe, 6request/reply, and push/pull. 7 8The Bitcoin Core daemon can be configured to act as a trusted "border 9router", implementing the bitcoin wire protocol and relay, making 10consensus decisions, maintaining the local blockchain database, 11broadcasting locally generated transactions into the network, and 12providing a queryable RPC interface to interact on a polled basis for 13requesting blockchain related data. However, there exists only a 14limited service to notify external software of events like the arrival 15of new blocks or transactions. 16 17The ZeroMQ facility implements a notification interface through a set 18of specific notifiers. Currently there are notifiers that publish 19blocks and transactions. This read-only facility requires only the 20connection of a corresponding ZeroMQ subscriber port in receiving 21software; it is not authenticated nor is there any two-way protocol 22involvement. Therefore, subscribers should validate the received data 23since it may be out of date, incomplete or even invalid. 24 25ZeroMQ sockets are self-connecting and self-healing; that is, 26connections made between two endpoints will be automatically restored 27after an outage, and either end may be freely started or stopped in 28any order. 29 30Because ZeroMQ is message oriented, subscribers receive transactions 31and blocks all-at-once and do not need to implement any sort of 32buffering or reassembly. 33 34## Prerequisites 35 36The ZeroMQ feature in Bitcoin Core requires ZeroMQ API version 4.x or 37newer. Typically, it is packaged by distributions as something like 38*libzmq3-dev*. The C++ wrapper for ZeroMQ is *not* needed. 39 40In order to run the example Python client scripts in contrib/ one must 41also install *python3-zmq*, though this is not necessary for daemon 42operation. 43 44## Enabling 45 46By default, the ZeroMQ feature is automatically compiled in if the 47necessary prerequisites are found. To disable, use --disable-zmq 48during the *configure* step of building bitcoind: 49 50 $ ./configure --disable-zmq (other options) 51 52To actually enable operation, one must set the appropriate options on 53the commandline or in the configuration file. 54 55## Usage 56 57Currently, the following notifications are supported: 58 59 -zmqpubhashtx=address 60 -zmqpubhashblock=address 61 -zmqpubrawblock=address 62 -zmqpubrawtx=address 63 64The socket type is PUB and the address must be a valid ZeroMQ socket 65address. The same address can be used in more than one notification. 66 67For instance: 68 69 $ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \ 70 -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw 71 72Each PUB notification has a topic and body, where the header 73corresponds to the notification type. For instance, for the 74notification `-zmqpubhashtx` the topic is `hashtx` (no null 75terminator) and the body is the hexadecimal transaction hash (32 76bytes). 77 78These options can also be provided in bitcoin.conf. 79 80ZeroMQ endpoint specifiers for TCP (and others) are documented in the 81[ZeroMQ API](http://api.zeromq.org/4-0:_start). 82 83Client side, then, the ZeroMQ subscriber socket must have the 84ZMQ_SUBSCRIBE option set to one or either of these prefixes (for 85instance, just `hash`); without doing so will result in no messages 86arriving. Please see `contrib/zmq/zmq_sub.py` for a working example. 87 88## Remarks 89 90From the perspective of bitcoind, the ZeroMQ socket is write-only; PUB 91sockets don't even have a read function. Thus, there is no state 92introduced into bitcoind directly. Furthermore, no information is 93broadcast that wasn't already received from the public P2P network. 94 95No authentication or authorization is done on connecting clients; it 96is assumed that the ZeroMQ port is exposed only to trusted entities, 97using other means such as firewalling. 98 99Note that when the block chain tip changes, a reorganisation may occur 100and just the tip will be notified. It is up to the subscriber to 101retrieve the chain from the last known block to the new tip. 102 103There are several possibilities that ZMQ notification can get lost 104during transmission depending on the communication type your are 105using. Bitcoind appends an up-counting sequence number to each 106notification which allows listeners to detect lost notifications. 107