doc/zmq.md

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