You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

zmq.md 4.3KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106
  1. # Block and Transaction Broadcasting with ZeroMQ
  2. [ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP
  3. connections, inter-process communication, and shared-memory,
  4. providing various message-oriented semantics such as publish/subscribe,
  5. request/reply, and push/pull.
  6. The Bitcoin Core daemon can be configured to act as a trusted "border
  7. router", implementing the bitcoin wire protocol and relay, making
  8. consensus decisions, maintaining the local blockchain database,
  9. broadcasting locally generated transactions into the network, and
  10. providing a queryable RPC interface to interact on a polled basis for
  11. requesting blockchain related data. However, there exists only a
  12. limited service to notify external software of events like the arrival
  13. of new blocks or transactions.
  14. The ZeroMQ facility implements a notification interface through a set
  15. of specific notifiers. Currently there are notifiers that publish
  16. blocks and transactions. This read-only facility requires only the
  17. connection of a corresponding ZeroMQ subscriber port in receiving
  18. software; it is not authenticated nor is there any two-way protocol
  19. involvement. Therefore, subscribers should validate the received data
  20. since it may be out of date, incomplete or even invalid.
  21. ZeroMQ sockets are self-connecting and self-healing; that is,
  22. connections made between two endpoints will be automatically restored
  23. after an outage, and either end may be freely started or stopped in
  24. any order.
  25. Because ZeroMQ is message oriented, subscribers receive transactions
  26. and blocks all-at-once and do not need to implement any sort of
  27. buffering or reassembly.
  28. ## Prerequisites
  29. The ZeroMQ feature in Bitcoin Core requires ZeroMQ API version 4.x or
  30. newer. Typically, it is packaged by distributions as something like
  31. *libzmq3-dev*. The C++ wrapper for ZeroMQ is *not* needed.
  32. In order to run the example Python client scripts in contrib/ one must
  33. also install *python3-zmq*, though this is not necessary for daemon
  34. operation.
  35. ## Enabling
  36. By default, the ZeroMQ feature is automatically compiled in if the
  37. necessary prerequisites are found. To disable, use --disable-zmq
  38. during the *configure* step of building bitcoind:
  39. $ ./configure --disable-zmq (other options)
  40. To actually enable operation, one must set the appropriate options on
  41. the command line or in the configuration file.
  42. ## Usage
  43. Currently, the following notifications are supported:
  44. -zmqpubhashtx=address
  45. -zmqpubhashblock=address
  46. -zmqpubrawblock=address
  47. -zmqpubrawtx=address
  48. The socket type is PUB and the address must be a valid ZeroMQ socket
  49. address. The same address can be used in more than one notification.
  50. For instance:
  51. $ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \
  52. -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw
  53. Each PUB notification has a topic and body, where the header
  54. corresponds to the notification type. For instance, for the
  55. notification `-zmqpubhashtx` the topic is `hashtx` (no null
  56. terminator) and the body is the transaction hash (32
  57. bytes).
  58. These options can also be provided in bitcoin.conf.
  59. ZeroMQ endpoint specifiers for TCP (and others) are documented in the
  60. [ZeroMQ API](http://api.zeromq.org/4-0:_start).
  61. Client side, then, the ZeroMQ subscriber socket must have the
  62. ZMQ_SUBSCRIBE option set to one or either of these prefixes (for
  63. instance, just `hash`); without doing so will result in no messages
  64. arriving. Please see `contrib/zmq/zmq_sub.py` for a working example.
  65. ## Remarks
  66. From the perspective of bitcoind, the ZeroMQ socket is write-only; PUB
  67. sockets don't even have a read function. Thus, there is no state
  68. introduced into bitcoind directly. Furthermore, no information is
  69. broadcast that wasn't already received from the public P2P network.
  70. No authentication or authorization is done on connecting clients; it
  71. is assumed that the ZeroMQ port is exposed only to trusted entities,
  72. using other means such as firewalling.
  73. Note that when the block chain tip changes, a reorganisation may occur
  74. and just the tip will be notified. It is up to the subscriber to
  75. retrieve the chain from the last known block to the new tip.
  76. There are several possibilities that ZMQ notification can get lost
  77. during transmission depending on the communication type your are
  78. using. Bitcoind appends an up-counting sequence number to each
  79. notification which allows listeners to detect lost notifications.