git / moonbite-core / doc/zmq.md · raw

# Block and Transaction Broadcasting with ZeroMQ[ZeroMQ](https://zeromq.org/) is a lightweight wrapper around TCPconnections, inter-process communication, and shared-memory,providing various message-oriented semantics such as publish/subscribe,request/reply, and push/pull.The Litecoin Core daemon can be configured to act as a trusted "borderrouter", implementing the litecoin wire protocol and relay, makingconsensus decisions, maintaining the local blockchain database,broadcasting locally generated transactions into the network, andproviding a queryable RPC interface to interact on a polled basis forrequesting blockchain related data. However, there exists only alimited service to notify external software of events like the arrivalof new blocks or transactions.The ZeroMQ facility implements a notification interface through a setof specific notifiers. Currently there are notifiers that publishblocks and transactions. This read-only facility requires only theconnection of a corresponding ZeroMQ subscriber port in receivingsoftware; it is not authenticated nor is there any two-way protocolinvolvement. Therefore, subscribers should validate the received datasince it may be out of date, incomplete or even invalid.ZeroMQ sockets are self-connecting and self-healing; that is,connections made between two endpoints will be automatically restoredafter an outage, and either end may be freely started or stopped inany order.Because ZeroMQ is message oriented, subscribers receive transactionsand blocks all-at-once and do not need to implement any sort ofbuffering or reassembly.## PrerequisitesThe ZeroMQ feature in Litecoin Core requires the ZeroMQ API >= 4.0.0[libzmq](https://github.com/zeromq/libzmq/releases).For version information, see [dependencies.md](dependencies.md).Typically, it is packaged by distributions as something like*libzmq3-dev*. The C++ wrapper for ZeroMQ is *not* needed.In order to run the example Python client scripts in the `contrib/zmq/`directory, one must also install [PyZMQ](https://github.com/zeromq/pyzmq)(generally with `pip install pyzmq`), though this is not necessary for daemonoperation.## EnablingBy default, the ZeroMQ feature is automatically compiled in if thenecessary prerequisites are found.  To disable, use --disable-zmqduring the *configure* step of building litecoind:    $ ./configure --disable-zmq (other options)To actually enable operation, one must set the appropriate options onthe command line or in the configuration file.## UsageCurrently, the following notifications are supported:    -zmqpubhashtx=address    -zmqpubhashblock=address    -zmqpubrawblock=address    -zmqpubrawtx=address    -zmqpubsequence=addressThe socket type is PUB and the address must be a valid ZeroMQ socketaddress. The same address can be used in more than one notification.The same notification can be specified more than once.The option to set the PUB socket's outbound message high water mark(SNDHWM) may be set individually for each notification:    -zmqpubhashtxhwm=n    -zmqpubhashblockhwm=n    -zmqpubrawblockhwm=n    -zmqpubrawtxhwm=n    -zmqpubsequencehwm=addressThe high water mark value must be an integer greater than or equal to 0.For instance:    $ litecoind -zmqpubhashtx=tcp://127.0.0.1:28332 \               -zmqpubhashtx=tcp://192.168.1.2:28332 \               -zmqpubrawtx=ipc:///tmp/litecoind.tx.raw \               -zmqpubhashtxhwm=10000Each PUB notification has a topic and body, where the headercorresponds to the notification type. For instance, for thenotification `-zmqpubhashtx` the topic is `hashtx` (no nullterminator) and the body is the transaction hash (32bytes) for all but `sequence` topic. For `sequence`, the bodyis structured as the following based on the type of message:    <32-byte hash>C :                 Blockhash connected    <32-byte hash>D :                 Blockhash disconnected    <32-byte hash>R<8-byte LE uint> : Transactionhash removed from mempool for non-block inclusion reason    <32-byte hash>A<8-byte LE uint> : Transactionhash added mempoolWhere the 8-byte uints correspond to the mempool sequence number.These options can also be provided in litecoin.conf.ZeroMQ endpoint specifiers for TCP (and others) are documented in the[ZeroMQ API](http://api.zeromq.org/4-0:_start).Client side, then, the ZeroMQ subscriber socket must have theZMQ_SUBSCRIBE option set to one or either of these prefixes (forinstance, just `hash`); without doing so will result in no messagesarriving. Please see [`contrib/zmq/zmq_sub.py`](/contrib/zmq/zmq_sub.py) for a working example.The ZMQ_PUB socket's ZMQ_TCP_KEEPALIVE option is enabled. This means thatthe underlying SO_KEEPALIVE option is enabled when using a TCP transport.The effective TCP keepalive values are managed through the underlyingoperating system configuration and must be configured prior to connection establishment.For example, when running on GNU/Linux, one might use the followingto lower the keepalive setting to 10 minutes:sudo sysctl -w net.ipv4.tcp_keepalive_time=600Setting the keepalive values appropriately for your operating environment mayimprove connectivity in situations where long-lived connections are silentlydropped by network middle boxes.## RemarksFrom the perspective of litecoind, the ZeroMQ socket is write-only; PUBsockets don't even have a read function. Thus, there is no stateintroduced into litecoind directly. Furthermore, no information isbroadcast that wasn't already received from the public P2P network.No authentication or authorization is done on connecting clients; itis assumed that the ZeroMQ port is exposed only to trusted entities,using other means such as firewalling.Note that for `*block` topics, when the block chain tip changes,a reorganisation may occur and just the tip will be notified.It is up to the subscriber to retrieve the chain from the last knownblock to the new tip. Also note that no notification will occur if the tipwas in the active chain--as would be the case after calling invalidateblock RPC.In contrast, the `sequence` topic publishes all block connections anddisconnections.There are several possibilities that ZMQ notification can get lostduring transmission depending on the communication type you areusing. Litecoind appends an up-counting sequence number to eachnotification which allows listeners to detect lost notifications.The `sequence` topic refers specifically to the mempool sequencenumber, which is also published along with all mempool events. Thisis a different sequence value than in ZMQ itself in order to allow a totalordering of mempool events to be constructed.