Changeset View
Changeset View
Standalone View
Standalone View
doc/zmq.md
# 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 communication, and shared-memory, | connections, inter-process communication, and shared-memory, | ||||
providing various message-oriented semantics such as publish/subscribe, | providing various message-oriented semantics such as publish/subscribe, | ||||
request/reply, and push/pull. | request/reply, and push/pull. | ||||
The Bitcoin ABC daemon can be configured to act as a trusted "border | The Bitcoin ABC daemon can be configured to act as a trusted "border | ||||
router", implementing the bitcoin wire protocol and relay, making | router", implementing the ecash wire protocol and relay, making | ||||
consensus decisions, maintaining the local blockchain database, | consensus decisions, maintaining the local blockchain database, | ||||
broadcasting locally generated transactions into the network, and | broadcasting locally generated transactions into the network, and | ||||
providing a queryable RPC interface to interact on a polled basis for | providing a queryable RPC interface to interact on a polled basis for | ||||
requesting blockchain related data. However, there exists only a | 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 set | The ZeroMQ facility implements a notification interface through a set | ||||
Show All 23 Lines | |||||
In order to run the example Python client scripts in contrib/ one must | In order to run the example Python client scripts in contrib/ one must | ||||
also install *python3-zmq*, though this is not necessary for daemon | also install *python3-zmq*, though this is not necessary for daemon | ||||
operation. | operation. | ||||
## Enabling | ## Enabling | ||||
By default, the ZeroMQ feature is automatically compiled. | By default, the ZeroMQ feature is automatically compiled. | ||||
To disable, use -DBUILD_BITCOIN_ZMQ=OFF to `cmake` when building bitcoind: | To disable, use -DBUILD_BITCOIN_ZMQ=OFF to `cmake` when building ecashd: | ||||
$ cmake -GNinja .. -DBUILD_BITCOIN_ZMQ=OFF [...] | $ cmake -GNinja .. -DBUILD_BITCOIN_ZMQ=OFF [...] | ||||
To actually enable operation, one must set the appropriate options on | To actually enable operation, one must set the appropriate options on | ||||
the command line or in the configuration file. | the command line or in the configuration file. | ||||
## Usage | ## Usage | ||||
Show All 14 Lines | (SNDHWM) may be set individually for each notification: | ||||
-zmqpubhashblockhwm=n | -zmqpubhashblockhwm=n | ||||
-zmqpubrawblockhwm=n | -zmqpubrawblockhwm=n | ||||
-zmqpubrawtxhwm=n | -zmqpubrawtxhwm=n | ||||
The high water mark value must be an integer greater than or equal to 0. | The high water mark value must be an integer greater than or equal to 0. | ||||
For instance: | For instance: | ||||
$ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \ | $ ecashd -zmqpubhashtx=tcp://127.0.0.1:28332 \ | ||||
-zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw \ | -zmqpubrawtx=ipc:///tmp/ecashd.tx.raw \ | ||||
-zmqpubhashtxhwm=10000 | -zmqpubhashtxhwm=10000 | ||||
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 | corresponds to the notification type. For instance, for the | ||||
notification `-zmqpubhashtx` the topic is `hashtx` (no null | notification `-zmqpubhashtx` the topic is `hashtx` (no null | ||||
terminator) and the body is the transaction hash (32 | terminator) and the body is the transaction hash (32 | ||||
bytes). | bytes). | ||||
These options can also be provided in bitcoin.conf. | These options can also be provided in ecash.conf. | ||||
ZeroMQ endpoint specifiers for TCP (and others) are documented in the | ZeroMQ endpoint specifiers for TCP (and others) are documented in the | ||||
[ZeroMQ API](http://api.zeromq.org/4-0:_start). | [ZeroMQ API](http://api.zeromq.org/4-0:_start). | ||||
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 | ZMQ_SUBSCRIBE option set to one or either of these prefixes (for | ||||
instance, just `hash`); without doing so will result in no messages | instance, just `hash`); without doing so will result in no messages | ||||
arriving. Please see [`contrib/zmq/zmq_sub.py`](/contrib/zmq/zmq_sub.py) for a working example. | arriving. Please see [`contrib/zmq/zmq_sub.py`](/contrib/zmq/zmq_sub.py) for a working example. | ||||
## Remarks | ## Remarks | ||||
From the perspective of bitcoind, the ZeroMQ socket is write-only; PUB | From the perspective of ecashd, the ZeroMQ socket is write-only; PUB | ||||
sockets don't even have a read function. Thus, there is no state | sockets don't even have a read function. Thus, there is no state | ||||
introduced into bitcoind directly. Furthermore, no information is | introduced into ecashd directly. Furthermore, no information is | ||||
broadcast that wasn't already received from the public P2P network. | broadcast that wasn't already received from the public P2P network. | ||||
No authentication or authorization is done on connecting clients; it | 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 | Note that when the block chain tip changes, a reorganisation may occur | ||||
and just the tip will be notified. It is up to the subscriber to | and just the tip will be notified. It is up to the subscriber to | ||||
retrieve the chain from the last known block to the new tip. Also note | retrieve the chain from the last known block to the new tip. Also note | ||||
that no notification occurs if the tip was in the active chain - this | that no notification occurs if the tip was in the active chain - this | ||||
is the case after calling invalidateblock RPC. | is the case after calling invalidateblock RPC. | ||||
There are several possibilities that ZMQ notification can get lost | There are several possibilities that ZMQ notification can get lost | ||||
during transmission depending on the communication type you are | during transmission depending on the communication type you are | ||||
using. Bitcoind appends an up-counting sequence number to each | using. ecashd appends an up-counting sequence number to each | ||||
notification which allows listeners to detect lost notifications. | notification which allows listeners to detect lost notifications. |