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 Litecoin Core daemon can be configured to act as a trusted "border
9router", implementing the litecoin 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 Litecoin Core requires the ZeroMQ API >= 4.0.0
37[libzmq](https://github.com/zeromq/libzmq/releases).
38For version information, see [dependencies.md](dependencies.md).
39Typically, it is packaged by distributions as something like
40*libzmq3-dev*. The C++ wrapper for ZeroMQ is *not* needed.
41
42In order to run the example Python client scripts in contrib/ one must
43also install *python3-zmq*, though this is not necessary for daemon
44operation.
45
46## Enabling
47
48By default, the ZeroMQ feature is automatically compiled in if the
49necessary prerequisites are found.  To disable, use --disable-zmq
50during the *configure* step of building litecoind:
51
52    $ ./configure --disable-zmq (other options)
53
54To actually enable operation, one must set the appropriate options on
55the command line or in the configuration file.
56
57## Usage
58
59Currently, the following notifications are supported:
60
61    -zmqpubhashtx=address
62    -zmqpubhashblock=address
63    -zmqpubrawblock=address
64    -zmqpubrawtx=address
65
66The socket type is PUB and the address must be a valid ZeroMQ socket
67address. The same address can be used in more than one notification.
68
69The option to set the PUB socket's outbound message high water mark
70(SNDHWM) may be set individually for each notification:
71
72    -zmqpubhashtxhwm=n
73    -zmqpubhashblockhwm=n
74    -zmqpubrawblockhwm=n
75    -zmqpubrawtxhwm=n
76
77The high water mark value must be an integer greater than or equal to 0.
78
79For instance:
80
81    $ litecoind -zmqpubhashtx=tcp://127.0.0.1:28332 \
82               -zmqpubrawtx=ipc:///tmp/litecoind.tx.raw \
83               -zmqpubhashtxhwm=10000
84
85Each PUB notification has a topic and body, where the header
86corresponds to the notification type. For instance, for the
87notification `-zmqpubhashtx` the topic is `hashtx` (no null
88terminator) and the body is the transaction hash (32
89bytes).
90
91These options can also be provided in litecoin.conf.
92
93ZeroMQ endpoint specifiers for TCP (and others) are documented in the
94[ZeroMQ API](http://api.zeromq.org/4-0:_start).
95
96Client side, then, the ZeroMQ subscriber socket must have the
97ZMQ_SUBSCRIBE option set to one or either of these prefixes (for
98instance, just `hash`); without doing so will result in no messages
99arriving. Please see `contrib/zmq/zmq_sub.py` for a working example.
100
101## Remarks
102
103From the perspective of litecoind, the ZeroMQ socket is write-only; PUB
104sockets don't even have a read function. Thus, there is no state
105introduced into litecoind directly. Furthermore, no information is
106broadcast that wasn't already received from the public P2P network.
107
108No authentication or authorization is done on connecting clients; it
109is assumed that the ZeroMQ port is exposed only to trusted entities,
110using other means such as firewalling.
111
112Note that when the block chain tip changes, a reorganisation may occur
113and just the tip will be notified. It is up to the subscriber to
114retrieve the chain from the last known block to the new tip.
115
116There are several possibilities that ZMQ notification can get lost
117during transmission depending on the communication type you are
118using. Litecoind appends an up-counting sequence number to each
119notification which allows listeners to detect lost notifications.
120