doc/amqp.md

   1 # Block and Transaction Broadcasting With AMQP 1.0 (Experimental Feature)
   2
   3 [AMQP](https://www.amqp.org/) is an enterprise-level message queuing
   4 protocol for the reliable passing of real-time data and business
   5 transactions between applications.  AMQP supports both broker and
   6 brokerless messaging.  AMQP 1.0 is an open standard and has been
   7 ratified as ISO/IEC 19464.
   8
   9 The Zcash daemon can be configured to act as a trusted "border
  10 router", implementing the Zcash P2P protocol and relay, making
  11 consensus decisions, maintaining the local blockchain database,
  12 broadcasting locally generated transactions into the network, and
  13 providing a queryable RPC interface to interact on a polled basis for
  14 requesting blockchain related data. However, there exists only a
  15 limited service to notify external software of events like the arrival
  16 of new blocks or transactions.
  17
  18 The AMQP facility implements a notification interface through a set
  19 of specific notifiers. Currently there are notifiers that publish
  20 blocks and transactions. This read-only facility requires only the
  21 connection of a corresponding AMQP subscriber port in receiving
  22 software.
  23
  24 Currently the facility is not authenticated nor is there any two-way
  25 protocol involvement. Therefore, subscribers should validate the
  26 received data since it may be out of date, incomplete or even invalid.
  27
  28 Because AMQP is message oriented, subscribers receive transactions
  29 and blocks all-at-once and do not need to implement any sort of
  30 buffering or reassembly.
  31
  32 ## Prerequisites
  33
  34 The AMQP feature in Zcash requires [Qpid Proton](https://qpid.apache.org/proton/)
  35 version 0.17 or newer, which you will need to install if you are not
  36 using the depends system. Typically, it is packaged by distributions as
  37 something like *libqpid-proton*. The C++ wrapper for AMQP *is* required.
  38
  39 In order to run the example Python client scripts in contrib/ one must
  40 also install *python-qpid-proton*, though this is not necessary for
  41 daemon operation.
  42
  43 ## Enabling
  44
  45 By default, the AMQP feature is automatically compiled in if the
  46 necessary prerequisites are found.  To disable, use --disable-proton
  47 during the *configure* step of building zcashd:
  48
  49     $ ./configure --disable-proton (other options)
  50
  51 To actually enable operation, one must set the appropriate options on
  52 the commandline or in the configuration file.
  53
  54 ## Usage
  55
  56 AMQP support is currently an experimental feature, so you must pass
  57 the option:
  58
  59     -experimentalfeatures
  60
  61 Currently, the following notifications are supported:
  62
  63     -amqppubhashtx=address
  64     -amqppubhashblock=address
  65     -amqppubrawblock=address
  66     -amqppubrawtx=address
  67
  68 The address must be a valid AMQP address, where the same address can be
  69 used in more than notification.  Note that SSL and SASL addresses are
  70 not currently supported.
  71
  72 Launch zcashd like this:
  73
  74     $ zcashd -amqppubhashtx=amqp://127.0.0.1:5672
  75
  76 Or this:
  77
  78     $ zcashd -amqppubhashtx=amqp://127.0.0.1:5672 \
  79         -amqppubrawtx=amqp://127.0.0.1:5672 \
  80         -amqppubrawblock=amqp://127.0.0.1:5672 \
  81         -amqppubhashblock=amqp://127.0.0.1:5672 \
  82         -debug=amqp
  83
  84 The debug category `amqp` enables AMQP-related logging.
  85
  86 Each notification has a topic and body, where the header corresponds
  87 to the notification type. For instance, for the notification `-amqpubhashtx`
  88 the topic is `hashtx` (no null terminator) and the body is the hexadecimal
  89 transaction hash (32 bytes).  This transaction hash and the block hash
  90 found in `hashblock` are in RPC byte order.
  91
  92 These options can also be provided in zcash.conf.
  93
  94 Please see `contrib/amqp/amqp_sub.py` for a working example of an
  95 AMQP server listening for messages.
  96
  97 ## Remarks
  98
  99 From the perspective of zcashd, the local end of an AMQP link is write-only.
 100
 101 No information is broadcast that wasn't already received from the public
 102 P2P network.
 103
 104 No authentication or authorization is done on peers that zcashd connects
 105 to; it is assumed that the AMQP link is exposed only to trusted entities,
 106 using other means such as firewalling.
 107
 108 TLS support may be added once OpenSSL has been removed from the Zcash
 109 project and alternative TLS implementations have been evaluated.
 110
 111 SASL support may be added in a future update for secure communication.
 112
 113 Note that when the block chain tip changes, a reorganisation may occur
 114 and just the tip will be notified. It is up to the subscriber to
 115 retrieve the chain from the last known block to the new tip.
 116
 117 At present, zcashd does not try to resend a notification if there was
 118 a problem confirming receipt.  Support for delivery guarantees such as
 119 *at-least-once* and *exactly-once* will be added in in a future update.
 120
 121 Currently, zcashd appends an up-counting sequence number to each notification
 122 which allows listeners to detect lost notifications.
 123