Merge pull request #6736

ab0b8be zmq: update and cleanup build-unix, release-notes, and zmq docs (Johnathan Corgan)
6cebd5d zmq: require version 4.x or newer of libzmq (Johnathan Corgan)

configure.ac

@@ -843,10 +843,10 @@ fi
 AC_MSG_CHECKING([whether to build ZMQ support])
 if test "x$use_zmq" = "xyes"; then
   AC_MSG_RESULT([yes])
-  PKG_CHECK_MODULES([ZMQ],[libzmq],
+  PKG_CHECK_MODULES([ZMQ],[libzmq >= 4],
     [AC_DEFINE([ENABLE_ZMQ],[1],[Define to 1 to enable ZMQ functions])],
     [AC_DEFINE([ENABLE_ZMQ],[0],[Define to 1 to enable ZMQ functions])
-     AC_MSG_WARN([libzmq not found, disabling])
+     AC_MSG_WARN([libzmq version 4.x or greater not found, disabling])
      use_zmq=no])
 else
   AC_MSG_RESULT([no, --disable-zmq used])

doc/build-unix.md

@@ -44,6 +44,7 @@ Optional dependencies:
  qt          | GUI              | GUI toolkit (only needed when GUI enabled)
  protobuf    | Payments in GUI  | Data interchange format used for payment protocol (only needed when GUI enabled)
  libqrencode | QR codes in GUI  | Optional for generating QR codes (only needed when GUI enabled)
+ libzmq3     | ZMQ notification | Optional, allows generating ZMQ notifications (requires ZMQ version >= 4.x)
 
 For the versions used in the release, see [release-process.md](release-process.md) under *Fetch and build inputs*.
 
@@ -81,6 +82,11 @@ Optional:
 
 	sudo apt-get install libminiupnpc-dev (see --with-miniupnpc and --enable-upnp-default)
 
+ZMQ dependencies:
+
+        sudo apt-get install libzmq3-dev (provides ZMQ API 4.x)
+
+
 Dependencies for the GUI: Ubuntu & Debian
 -----------------------------------------
 
@@ -229,4 +235,3 @@ In this case there is no dependency on Berkeley DB 4.8.
 
 Mining is also possible in disable-wallet mode, but only using the `getblocktemplate` RPC
 call not `getwork`.
-

doc/release-notes.md

@@ -171,3 +171,11 @@ configured specifically to process scriptPubKey and not scriptSig scripts.
 
 - Removed bitrpc.py from contrib
 
+Addition of ZMQ-based Notifcations
+==================================
+
+Bitcoind can now (optionally) asynchronously notify clients through a
+ZMQ-based PUB socket of the arrival of new transactions and blocks.
+This feature requires installation of the ZMQ C API library 4.x and
+configuring its use through the command line or configuration file.
+Please see docs/zmq.md for details of operation.

doc/zmq.md

@@ -1,7 +1,7 @@
 # Block and Transaction Broadcasting With ZeroMQ
 
 [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,
 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
 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 publish
+of specific notifiers. Currently there are notifiers that publish
 blocks and transactions. This read-only facility requires only the
 connection of a corresponding ZeroMQ subscriber port in receiving
 software; it is not authenticated nor is there any two-way protocol
 involvement. Therefore, subscribers should validate the received data
 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
 and blocks all-at-once and do not need to implement any sort of
@@ -32,13 +33,13 @@ buffering or reassembly.
 
 ## 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
 
@@ -60,17 +61,19 @@ Currently, the following notifications are supported:
     -zmqpubrawblock=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:
 
-    $ 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
-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 the
+notification `-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.
 
@@ -78,9 +81,9 @@ ZeroMQ endpoint specifiers for TCP (and others) are documented in the
 [ZeroMQ API](http://api.zeromq.org).
 
 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
 
@@ -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,
 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.