mirror of
https://github.com/bitcoin/bitcoin.git
synced 2025-11-12 23:18:14 +01:00
Add ZeroMQ support. Notify blocks and transactions via ZeroMQ
Continues Johnathan Corgan's work. Publishing multipart messages Bugfix: Add missing zmq header includes Bugfix: Adjust build system to link ZeroMQ code for Qt binaries
This commit is contained in:
committed by
João Barbosa
parent
1136879df8
commit
e6a14b64d6
98
doc/zmq.md
Normal file
98
doc/zmq.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# Block and Transaction Broadcasting With ZeroMQ
|
||||
|
||||
[ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP
|
||||
connections, inter-process communications, and shared-memory,
|
||||
providing various message-oriented semantics such as publish/subcribe,
|
||||
request/reply, and push/pull.
|
||||
|
||||
The Bitcoin Core daemon can be configured to act as a trusted "border
|
||||
router", implementing the bitcoin 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, connects
|
||||
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 Bitcoin Core uses only a very small part of the
|
||||
ZeroMQ C API, and is thus compatible with any version of ZeroMQ
|
||||
from 2.1 onward, including all versions in the 3.x and 4.x release
|
||||
series. Typically, it is packaged by distributions as something like
|
||||
*libzmq-dev*.
|
||||
|
||||
The C++ wrapper for ZeroMQ is *not* needed.
|
||||
|
||||
## Enabling
|
||||
|
||||
By default, the ZeroMQ port functionality is enabled. Two steps are
|
||||
required to enable--compiling in the ZeroMQ code, and configuring
|
||||
runtime operation on the command-line or configuration file.
|
||||
|
||||
$ ./configure --enable-zmq (other options)
|
||||
|
||||
This will produce a binary that is capable of providing the ZeroMQ
|
||||
facility, but will not do so until also configured properly.
|
||||
|
||||
## Usage
|
||||
|
||||
Currently, the following notifications are supported:
|
||||
|
||||
-zmqpubhashtx=address
|
||||
-zmqpubhashblock=address
|
||||
-zmqpubrawblock=address
|
||||
-zmqpubrawtx=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:
|
||||
|
||||
$ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 -zmqpubrawtx=ipc:///tmp/bitcoind.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 bitcoin.conf.
|
||||
|
||||
ZeroMQ endpoint specifiers for TCP (and others) are documented in the
|
||||
[ZeroMQ API](http://api.zeromq.org).
|
||||
|
||||
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 bitcoind, the ZeroMQ socket is write-only; PUB
|
||||
sockets don't even have a read function. Thus, there is no state
|
||||
introduced into bitcoind 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.
|
||||
Reference in New Issue
Block a user