hush3/doc/amqp.md

Block and Transaction Broadcasting With AMQP 1.0 (Experimental Feature)

AMQP is an enterprise-level message queuing protocol for the reliable passing of real-time data and business transactions between applications. AMQP supports both broker and brokerless messaging. AMQP 1.0 is an open standard and has been ratified as ISO/IEC 19464.

The Hush daemon can be configured to act as a trusted "border router", implementing the Hush P2P 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 AMQP 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 AMQP subscriber port in receiving software.

Currently the facility 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.

Because AMQP 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 AMQP feature in Hush requires Qpid Proton version 0.17 or newer, which you will need to install if you are not using the depends system. Typically, it is packaged by distributions as something like libqpid-proton. The C++ wrapper for AMQP is required.

In order to run the example Python client scripts in contrib/ one must also install python-qpid-proton, though this is not necessary for daemon operation.

Enabling

By default, the AMQP feature is automatically compiled in if the necessary prerequisites are found. To disable, use --disable-proton during the configure step of building zcashd:

$ ./configure --disable-proton (other options)

To actually enable operation, one must set the appropriate options on the commandline or in the configuration file.

Usage

AMQP support is currently an experimental feature, so you must pass the option:

-experimentalfeatures

Currently, the following notifications are supported:

-amqppubhashtx=address
-amqppubhashblock=address
-amqppubrawblock=address
-amqppubrawtx=address

The address must be a valid AMQP address, where the same address can be used in more than notification. Note that SSL and SASL addresses are not currently supported.

Launch zcashd like this:

$ zcashd -amqppubhashtx=amqp://127.0.0.1:5672

Or this:

$ zcashd -amqppubhashtx=amqp://127.0.0.1:5672 \
    -amqppubrawtx=amqp://127.0.0.1:5672 \
    -amqppubrawblock=amqp://127.0.0.1:5672 \
    -amqppubhashblock=amqp://127.0.0.1:5672 \
    -debug=amqp

The debug category amqp enables AMQP-related logging.

Each notification has a topic and body, where the header corresponds to the notification type. For instance, for the notification -amqpubhashtx the topic is hashtx (no null terminator) and the body is the hexadecimal transaction hash (32 bytes). This transaction hash and the block hash found in hashblock are in RPC byte order.

These options can also be provided in zcash.conf.

Please see contrib/amqp/amqp_sub.py for a working example of an AMQP server listening for messages.

Remarks

From the perspective of zcashd, the local end of an AMQP link is write-only.

No information is broadcast that wasn't already received from the public P2P network.

No authentication or authorization is done on peers that zcashd connects to; it is assumed that the AMQP link is exposed only to trusted entities, using other means such as firewalling.

TLS support may be added once OpenSSL has been removed from the Hush project and alternative TLS implementations have been evaluated.

SASL support may be added in a future update for secure communication.

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.

At present, zcashd does not try to resend a notification if there was a problem confirming receipt. Support for delivery guarantees such as at-least-once and exactly-once will be added in in a future update.

Currently, zcashd appends an up-counting sequence number to each notification which allows listeners to detect lost notifications.