@ -1,7 +1,7 @@
# Block and Transaction Broadcasting With ZeroMQ
# Block and Transaction Broadcasting With ZeroMQ
[ZeroMQ ](http://zeromq.org/ ) is a lightweight wrapper around TCP
[ZeroMQ ](http://zeromq.org/ ) is a lightweight wrapper around TCP
connections, inter-process communications , and shared-memory,
connections, inter-process communication, and shared-memory,
providing various message-oriented semantics such as publish/subcribe,
providing various message-oriented semantics such as publish/subcribe,
request/reply, and push/pull.
request/reply, and push/pull.
@ -14,17 +14,18 @@ requesting blockchain related data. However, there exists only a
limited service to notify external software of events like the arrival
limited service to notify external software of events like the arrival
of new blocks or transactions.
of new blocks or transactions.
The ZeroMQ facility implements a notification interface through a
The ZeroMQ facility implements a notification interface through a set
set of specific notifiers. Currently there are notifiers that publishof specific notifiers. Currently there are notifiers that publish
blocks and transactions. This read-only facility requires only the
blocks and transactions. This read-only facility requires only the
connection of a corresponding ZeroMQ subscriber port in receiving
connection of a corresponding ZeroMQ subscriber port in receiving
software; it is not authenticated nor is there any two-way protocol
software; it is not authenticated nor is there any two-way protocol
involvement. Therefore, subscribers should validate the received data
involvement. Therefore, subscribers should validate the received data
since it may be out of date, incomplete or even invalid.
since it may be out of date, incomplete or even invalid.
ZeroMQ sockets are self-connecting and self-healing; that is, connects
ZeroMQ sockets are self-connecting and self-healing; that is,
made between two endpoints will be automatically restored after an
connections made between two endpoints will be automatically restored
outage, and either end may be freely started or stopped in any order.
after an outage, and either end may be freely started or stopped in
any order.
Because ZeroMQ is message oriented, subscribers receive transactions
Because ZeroMQ is message oriented, subscribers receive transactions
and blocks all-at-once and do not need to implement any sort of
and blocks all-at-once and do not need to implement any sort of
@ -32,13 +33,13 @@ buffering or reassembly.
## Prerequisites
## Prerequisites
The ZeroMQ feature in Bitcoin Core uses only a very small part of the
The ZeroMQ feature in Bitcoin Core requires ZeroMQ API version 4.x or
ZeroMQ C API, and is thus compatible with any version of ZeroMQ
newer. Typically, it is packaged by distributions as something like
from 2.1 onward, including all versions in the 3.x and 4.x release
*libzmq3-dev*. The C++ wrapper for ZeroMQ is *not* needed.
series. Typically, it is packaged by distributions as something like
*libzmq-dev*.
The C++ wrapper for ZeroMQ is *not* needed.
In order to run the example Python client scripts in contrib/ one must
also install *python-zmq* , though this is not necessary for daemon
operation.
## Enabling
## Enabling
@ -60,17 +61,19 @@ Currently, the following notifications are supported:
-zmqpubrawblock=address
-zmqpubrawblock=address
-zmqpubrawtx=address
-zmqpubrawtx=address
The socket type is PUB and the address must be a valid ZeroMQ
The socket type is PUB and the address must be a valid ZeroMQ socket
socket address. The same address can be used in more than one notification.address. The same address can be used in more than one notification.
For instance:
For instance:
$ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw
$ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \
-zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw
Each PUB notification has a topic and body, where the header
Each PUB notification has a topic and body, where the header
corresponds to the notification type. For instance, for the notification
corresponds to the notification type. For instance, for the
`-zmqpubhashtx` the topic is `hashtx` (no null terminator) and the body is thenotification `-zmqpubhashtx` the topic is `hashtx` (no null
hexadecimal transaction hash (32 bytes).
terminator) and the body is the hexadecimal transaction hash (32
bytes).
These options can also be provided in bitcoin.conf.
These options can also be provided in bitcoin.conf.
@ -78,9 +81,9 @@ ZeroMQ endpoint specifiers for TCP (and others) are documented in the
[ZeroMQ API ](http://api.zeromq.org ).
[ZeroMQ API ](http://api.zeromq.org ).
Client side, then, the ZeroMQ subscriber socket must have the
Client side, then, the ZeroMQ subscriber socket must have the
ZMQ_SUBSCRIBE option set to one or either of these prefixes (for instance, just `hash` ); without
ZMQ_SUBSCRIBE option set to one or either of these prefixes (for
doing so will result in no messages arriving. Please see `contrib/zmq/zmq_sub.py`
instance, just `hash` ); without doing so will result in no messages
for a working example.
arriving. Please see `contrib/zmq/zmq_sub.py` for a working example.
## Remarks
## Remarks
@ -93,6 +96,6 @@ No authentication or authorization is done on connecting clients; it
is assumed that the ZeroMQ port is exposed only to trusted entities,
is assumed that the ZeroMQ port is exposed only to trusted entities,
using other means such as firewalling.
using other means such as firewalling.
Note that when the block chain tip changes, a reorganisation may occur and just
Note that when the block chain tip changes, a reorganisation may occur
the tip will be notified. It is up to the subscriber to retrieve the chain
and just the tip will be notified. It is up to the subscriber to
from the last known block to the new tip.
retrieve the chain from the last known block to the new tip.
Wladimir J. van der Laan
9 years ago