0e689341d2
* fix whitespace * added zmq stuff for governance objects and votes it seems that zmq is currently not in a working state, need to figure that out. Need to: plug in the new methods added possibly plug in the old methods, as it doesn't look like they are. * formatting fix. Will probably need to revert for this PR * continue linking new zmq messages in * added comment, might need to revert * fixes error of it not knowing about the classes * Actually link in, all new govobjects and govvotes should be broadcast over zmq now. * fix compile error, forgot to change params when copying * fix compile error * add imports to the header files in zmqconfig.h * fixing linking(i think) error * Revert "added comment, might need to revert" This reverts commit 2918ea40fe9a96834c4bd89e13cb458cde6814f2. * Revert "formatting fix. Will probably need to revert for this PR" This reverts commit ca10558866ab61e3dd0c70541fdcfee6f5115157. * fix tabs etc * EOL added * optimization of hash.begin() @nmarley thoughts? * remove formatting changes * iterator i -> it and removal of notifier * typo in df879f57 * use auto for the iterators * introduce hash prefix * implement changes in zmq_sub.py, update the doc, and change argument name to fix typo * deref iterators before calling methods * continued e8a4c505 * missed one... continued e8a4c505 * killing some tabs * fix spacing for setting or comparing iterators * change order of new variables to match current setup * re-add elif's I didn't realize got removed * Revert "fix spacing for setting or comparing iterators" This reverts commit 8ce2068148dcd275ebba7ee6038d0db1c582b9f3. * Revert "use auto for the iterators" This reverts commit cb16cf0760bfaf68c56684877898611802bf2303. * Revert "missed one... continued e8a4c505" This reverts commit 2087cf894f7e9682508b4692b89897b4fa4e4b7a. * Revert "continued e8a4c505" This reverts commit a78c8ad2c9bb1602242a8f040e17ef958982348c. * Revert "deref iterators before calling methods" This reverts commit e8a4c505d1d34360eaf882d92cd8fbc55436cfcc. * Revert "iterator i -> it and removal of notifier" This reverts commit 29574248b1a0d05c18d60454d07c77979aae6fb2. * Revert "fix whitespace" This reverts commit 612be48d963000b4cbc5f64981a88a3225428b37. * Revert "typo in df879f5" * Revert "Optimization of hash.begin()" * fixes problem with revert * Udjin complain's a lot ;) * help text, init.cpp * add signals in validationinterface.cpp * Change location of vote notification call. * remain consistent * remove unneeded include due to change of notification location * implement raw notifications
113 lines
4.5 KiB
Markdown
113 lines
4.5 KiB
Markdown
# Block and Transaction Broadcasting with ZeroMQ
|
|
|
|
[ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP
|
|
connections, inter-process communication, and shared-memory,
|
|
providing various message-oriented semantics such as publish/subscribe,
|
|
request/reply, and push/pull.
|
|
|
|
The Dash Core daemon can be configured to act as a trusted "border
|
|
router", implementing the dash wire protocol and relay, making
|
|
consensus decisions, maintaining the local blockchain database,
|
|
broadcasting locally generated transactions into the network, and
|
|
providing a queryable RPC interface to interact on a polled basis for
|
|
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 set
|
|
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,
|
|
connections made between two endpoints will be automatically restored
|
|
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
|
|
buffering or reassembly.
|
|
|
|
## Prerequisites
|
|
|
|
The ZeroMQ feature in Dash Core requires ZeroMQ API version 4.x or
|
|
newer. 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 contrib/ one must
|
|
also install *python3-zmq*, though this is not necessary for daemon
|
|
operation.
|
|
|
|
## Enabling
|
|
|
|
By default, the ZeroMQ feature is automatically compiled in if the
|
|
necessary prerequisites are found. To disable, use --disable-zmq
|
|
during the *configure* step of building bitcoind:
|
|
|
|
$ ./configure --disable-zmq (other options)
|
|
|
|
To actually enable operation, one must set the appropriate options on
|
|
the command line or in the configuration file.
|
|
|
|
## Usage
|
|
|
|
Currently, the following notifications are supported:
|
|
|
|
-zmqpubhashtx=address
|
|
-zmqpubhashtxlock=address
|
|
-zmqpubhashblock=address
|
|
-zmqpubrawblock=address
|
|
-zmqpubrawtx=address
|
|
-zmqpubrawtxlock=address
|
|
-zmqpubhashgovernancevote=address
|
|
-zmqpubhashgovernanceobject=address
|
|
-zmqpubrawgovernancevote=address
|
|
-zmqpubhashgovernanceobject=address
|
|
|
|
The socket type is PUB and the address must be a valid ZeroMQ socket
|
|
address. The same address can be used in more than one notification.
|
|
|
|
For instance:
|
|
|
|
$ dashd -zmqpubhashtx=tcp://127.0.0.1:28332 \
|
|
-zmqpubrawtx=ipc:///tmp/dashd.tx.raw
|
|
|
|
Each PUB notification has a topic and body, where the header
|
|
corresponds to the notification type. For instance, for the
|
|
notification `-zmqpubhashtx` the topic is `hashtx` (no null
|
|
terminator) and the body is the hexadecimal transaction hash (32
|
|
bytes).
|
|
|
|
These options can also be provided in dash.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 the
|
|
ZMQ_SUBSCRIBE option set to one or either of these prefixes (for
|
|
instance, just `hash`); without doing so will result in no messages
|
|
arriving. Please see `contrib/zmq/zmq_sub.py` for a working example.
|
|
|
|
## Remarks
|
|
|
|
From the perspective of dashd, the ZeroMQ socket is write-only; PUB
|
|
sockets don't even have a read function. Thus, there is no state
|
|
introduced into dashd directly. Furthermore, no information is
|
|
broadcast that wasn't already received from the public P2P network.
|
|
|
|
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 the tip will be notified. It is up to the subscriber to
|
|
retrieve the chain from the last known block to the new tip.
|
|
|
|
There are several possibilities that ZMQ notification can get lost
|
|
during transmission depending on the communication type your are
|
|
using. Dashd appends an up-counting sequence number to each
|
|
notification which allows listeners to detect lost notifications.
|