Browse Source

zmq: update and cleanup build-unix, release-notes, and zmq docs

Signed-off-by: Johnathan Corgan <johnathan@corganlabs.com>
pull/1/head
Johnathan Corgan 7 years ago
parent
commit
ab0b8be857
  1. 11
      doc/build-unix.md
  2. 10
      doc/release-notes.md
  3. 53
      doc/zmq.md

11
doc/build-unix.md

@ -1,6 +1,6 @@ @@ -1,6 +1,6 @@
UNIX BUILD NOTES
====================
Some notes on how to build Bitcoin in Unix.
Some notes on how to build Bitcoin in Unix.
Note
---------------------
@ -44,6 +44,7 @@ Optional dependencies: @@ -44,6 +44,7 @@ Optional dependencies:
qt | GUI | GUI toolkit (only needed when GUI enabled)
protobuf | Payments in GUI | Data interchange format used for payment protocol (only needed when GUI enabled)
libqrencode | QR codes in GUI | Optional for generating QR codes (only needed when GUI enabled)
libzmq3 | ZMQ notification | Optional, allows generating ZMQ notifications (requires ZMQ version >= 4.x)
For the versions used in the release, see [release-process.md](release-process.md) under *Fetch and build inputs*.
@ -59,7 +60,7 @@ Dependency Build Instructions: Ubuntu & Debian @@ -59,7 +60,7 @@ Dependency Build Instructions: Ubuntu & Debian
Build requirements:
sudo apt-get install build-essential libtool autotools-dev autoconf pkg-config libssl-dev libevent-dev
For Ubuntu 12.04 and later or Debian 7 and later libboost-all-dev has to be installed:
sudo apt-get install libboost-all-dev
@ -81,6 +82,11 @@ Optional: @@ -81,6 +82,11 @@ Optional:
sudo apt-get install libminiupnpc-dev (see --with-miniupnpc and --enable-upnp-default)
ZMQ dependencies:
sudo apt-get install libzmq3-dev (provides ZMQ API 4.x)
Dependencies for the GUI: Ubuntu & Debian
-----------------------------------------
@ -229,4 +235,3 @@ In this case there is no dependency on Berkeley DB 4.8. @@ -229,4 +235,3 @@ In this case there is no dependency on Berkeley DB 4.8.
Mining is also possible in disable-wallet mode, but only using the `getblocktemplate` RPC
call not `getwork`.

10
doc/release-notes.md

@ -46,7 +46,7 @@ caching. A sample config for apache2 could look like: @@ -46,7 +46,7 @@ caching. A sample config for apache2 could look like:
# optional enable digest auth
# AuthType Digest
# ...
# optional bypass bitcoind rpc basic auth
# RequestHeader set Authorization "Basic <hash>"
# get the <hash> from the shell with: base64 <<< bitcoinrpc:<password>
@ -171,3 +171,11 @@ configured specifically to process scriptPubKey and not scriptSig scripts. @@ -171,3 +171,11 @@ configured specifically to process scriptPubKey and not scriptSig scripts.
- Removed bitrpc.py from contrib
Addition of ZMQ-based Notifcations
==================================
Bitcoind can now (optionally) asynchronously notify clients through a
ZMQ-based PUB socket of the arrival of new transactions and blocks.
This feature requires installation of the ZMQ C API library 4.x and
configuring its use through the command line or configuration file.
Please see docs/zmq.md for details of operation.

53
doc/zmq.md

@ -1,7 +1,7 @@ @@ -1,7 +1,7 @@
# Block and Transaction Broadcasting With ZeroMQ
[ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP
connections, inter-process communications, and shared-memory,
connections, inter-process communication, and shared-memory,
providing various message-oriented semantics such as publish/subcribe,
request/reply, and push/pull.
@ -14,17 +14,18 @@ requesting blockchain related data. However, there exists only a @@ -14,17 +14,18 @@ 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
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
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.
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
@ -32,13 +33,13 @@ buffering or reassembly. @@ -32,13 +33,13 @@ 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 ZeroMQ feature in Bitcoin 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.
The C++ wrapper for ZeroMQ is *not* needed.
In order to run the example Python client scripts in contrib/ one must
also install *python-zmq*, though this is not necessary for daemon
operation.
## Enabling
@ -60,17 +61,19 @@ Currently, the following notifications are supported: @@ -60,17 +61,19 @@ Currently, the following notifications are supported:
-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.
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
$ 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).
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.
@ -78,9 +81,9 @@ ZeroMQ endpoint specifiers for TCP (and others) are documented in the @@ -78,9 +81,9 @@ 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.
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
@ -93,6 +96,6 @@ No authentication or authorization is done on connecting clients; it @@ -93,6 +96,6 @@ 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.
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.

Loading…
Cancel
Save