diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/README.md | 3 | ||||
-rw-r--r-- | doc/build-unix.md | 11 | ||||
-rw-r--r-- | doc/gitian-building.md | 4 | ||||
-rw-r--r-- | doc/release-notes.md | 10 | ||||
-rw-r--r-- | doc/translation_process.md | 2 | ||||
-rw-r--r-- | doc/zmq.md | 53 |
6 files changed, 50 insertions, 33 deletions
diff --git a/doc/README.md b/doc/README.md index 7b0c39d383..3e3f4a294f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -64,7 +64,8 @@ The Bitcoin repo's [root README](https://github.com/bitcoin/bitcoin/blob/master/ ### Resources * Discuss on the [BitcoinTalk](https://bitcointalk.org/) forums, in the [Development & Technical Discussion board](https://bitcointalk.org/index.php?board=6.0). -* Discuss on [#bitcoin-dev](http://webchat.freenode.net/?channels=bitcoin) on Freenode. If you don't have an IRC client use [webchat here](http://webchat.freenode.net/?channels=bitcoin-dev). +* Discuss project-specific development on #bitcoin-core-dev on Freenode. If you don't have an IRC client use [webchat here](http://webchat.freenode.net/?channels=bitcoin-core-dev). +* Discuss general Bitcoin development on #bitcoin-dev on Freenode. If you don't have an IRC client use [webchat here](http://webchat.freenode.net/?channels=bitcoin-dev). ### Miscellaneous - [Assets Attribution](assets-attribution.md) diff --git a/doc/build-unix.md b/doc/build-unix.md index 5c5103575e..a9a0028c4a 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -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. (for OpenBSD specific instructions, see [build-openbsd.md](build-openbsd.md)) @@ -46,6 +46,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*. @@ -61,7 +62,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 @@ -83,6 +84,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 ----------------------------------------- @@ -231,4 +237,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`. - diff --git a/doc/gitian-building.md b/doc/gitian-building.md index b434ae8a5b..265fbd586d 100644 --- a/doc/gitian-building.md +++ b/doc/gitian-building.md @@ -74,11 +74,11 @@ In the VirtualBox GUI click "Create" and choose the following parameters in the - File location and size: at least 40GB; as low as 20GB *may* be possible, but better to err on the safe side - Click `Create` -Get the [Debian 8.1 net installer](http://cdimage.debian.org/debian-cd/8.1.0/amd64/iso-cd/debian-8.1.0-amd64-netinst.iso) (a more recent minor version should also work, see also [Debian Network installation](https://www.debian.org/CD/netinst/)). +Get the [Debian 8.x net installer](http://cdimage.debian.org/debian-cd/8.2.0/amd64/iso-cd/debian-8.2.0-amd64-netinst.iso) (a more recent minor version should also work, see also [Debian Network installation](https://www.debian.org/CD/netinst/)). This DVD image can be validated using a SHA256 hashing tool, for example on Unixy OSes by entering the following in a terminal: - echo "5d0a1f804d73aee73eee7efbb38456390558094fd19894a573f1514ca44347e0 debian-8.1.0-amd64-netinst.iso" | sha256sum -c + echo "d393d17ac6b3113c81186e545c416a00f28ed6e05774284bb5e8f0df39fcbcb9 debian-8.2.0-amd64-netinst.iso" | sha256sum -c # (must return OK) After creating the VM, we need to configure it. diff --git a/doc/release-notes.md b/doc/release-notes.md index 85cdabc7e3..70623a3939 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -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. - 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. diff --git a/doc/translation_process.md b/doc/translation_process.md index 3653e53021..b06975e1d8 100644 --- a/doc/translation_process.md +++ b/doc/translation_process.md @@ -106,6 +106,6 @@ To create a new language template, you will need to edit the languages manifest **Note:** that the language translation file **must end in `.qm`** (the compiled extension), and not `.ts`. ### Questions and general assistance -The Bitcoin-Core translation maintainers include *tcatm, seone, Diapolo, wumpus and luke-jr*.You can find them, and others, in the Freenode IRC chatroom - `irc.freenode.net #bitcoin-dev`. +The Bitcoin-Core translation maintainers include *tcatm, seone, Diapolo, wumpus and luke-jr*. You can find them, and others, in the Freenode IRC chatroom - `irc.freenode.net #bitcoin-core-dev`. If you are a translator, you should also subscribe to the mailing list, https://groups.google.com/forum/#!forum/bitcoin-translators. Announcements will be posted during application pre-releases to notify translators to check for updates. diff --git a/doc/zmq.md b/doc/zmq.md index fd04f6d9f0..358d29d046 100644 --- a/doc/zmq.md +++ b/doc/zmq.md @@ -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 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. ## 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: -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 [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 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. |