Changeset View
Changeset View
Standalone View
Standalone View
doc/zmq.md
Show First 20 Lines • Show All 56 Lines • ▼ Show 20 Lines | |||||
## Usage | ## Usage | ||||
Currently, the following notifications are supported: | Currently, the following notifications are supported: | ||||
-zmqpubhashtx=address | -zmqpubhashtx=address | ||||
-zmqpubhashblock=address | -zmqpubhashblock=address | ||||
-zmqpubrawblock=address | -zmqpubrawblock=address | ||||
-zmqpubrawtx=address | -zmqpubrawtx=address | ||||
-zmqpubsequence=address | |||||
The socket type is PUB and the address must be a valid ZeroMQ socket | 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. | address. The same address can be used in more than one notification. | ||||
The option to set the PUB socket's outbound message high water mark | The option to set the PUB socket's outbound message high water mark | ||||
(SNDHWM) may be set individually for each notification: | (SNDHWM) may be set individually for each notification: | ||||
-zmqpubhashtxhwm=n | -zmqpubhashtxhwm=n | ||||
-zmqpubhashblockhwm=n | -zmqpubhashblockhwm=n | ||||
-zmqpubrawblockhwm=n | -zmqpubrawblockhwm=n | ||||
-zmqpubrawtxhwm=n | -zmqpubrawtxhwm=n | ||||
-zmqpubsequencehwm=address | |||||
The high water mark value must be an integer greater than or equal to 0. | The high water mark value must be an integer greater than or equal to 0. | ||||
For instance: | For instance: | ||||
$ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \ | $ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \ | ||||
-zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw \ | -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw \ | ||||
-zmqpubhashtxhwm=10000 | -zmqpubhashtxhwm=10000 | ||||
Each PUB notification has a topic and body, where the header | Each PUB notification has a topic and body, where the header | ||||
corresponds to the notification type. For instance, for the | corresponds to the notification type. For instance, for the | ||||
notification `-zmqpubhashtx` the topic is `hashtx` (no null | notification `-zmqpubhashtx` the topic is `hashtx` (no null | ||||
terminator) and the body is the transaction hash (32 | terminator) and the body is the transaction hash (32 | ||||
bytes). | bytes) for all but `sequence` topic. For `sequence`, the body | ||||
is structured as the following based on the type of message: | |||||
<32-byte hash>C : Blockhash connected | |||||
<32-byte hash>D : Blockhash disconnected | |||||
<32-byte hash>R<8-byte LE uint> : Transactionhash removed from mempool for non-block inclusion reason | |||||
<32-byte hash>A<8-byte LE uint> : Transactionhash added mempool | |||||
Where the 8-byte uints correspond to the mempool sequence number. | |||||
These options can also be provided in bitcoin.conf. | These options can also be provided in bitcoin.conf. | ||||
ZeroMQ endpoint specifiers for TCP (and others) are documented in the | ZeroMQ endpoint specifiers for TCP (and others) are documented in the | ||||
[ZeroMQ API](http://api.zeromq.org/4-0:_start). | [ZeroMQ API](http://api.zeromq.org/4-0:_start). | ||||
Client side, then, the ZeroMQ subscriber socket must have the | Client side, then, the ZeroMQ subscriber socket must have the | ||||
ZMQ_SUBSCRIBE option set to one or either of these prefixes (for | ZMQ_SUBSCRIBE option set to one or either of these prefixes (for | ||||
Show All 20 Lines | |||||
sockets don't even have a read function. Thus, there is no state | sockets don't even have a read function. Thus, there is no state | ||||
introduced into bitcoind directly. Furthermore, no information is | introduced into bitcoind directly. Furthermore, no information is | ||||
broadcast that wasn't already received from the public P2P network. | broadcast that wasn't already received from the public P2P network. | ||||
No authentication or authorization is done on connecting clients; it | No authentication or authorization is done on connecting clients; it | ||||
is assumed that the ZeroMQ port is exposed only to trusted entities, | is assumed that the ZeroMQ port is exposed only to trusted entities, | ||||
using other means such as firewalling. | using other means such as firewalling. | ||||
Note that when the block chain tip changes, a reorganisation may occur | Note that for `*block` topics, when the block chain tip changes, | ||||
and just the tip will be notified. It is up to the subscriber to | a reorganisation may occur and just the tip will be notified. | ||||
retrieve the chain from the last known block to the new tip. Also note | It is up to the subscriber to retrieve the chain from the last known | ||||
that no notification occurs if the tip was in the active chain - this | block to the new tip. Also note that no notification will occur if the tip | ||||
is the case after calling invalidateblock RPC. | was in the active chain--as would be the case after calling invalidateblock RPC. | ||||
In contrast, the `sequence` topic publishes all block connections and | |||||
disconnections. | |||||
There are several possibilities that ZMQ notification can get lost | There are several possibilities that ZMQ notification can get lost | ||||
during transmission depending on the communication type you are | during transmission depending on the communication type you are | ||||
using. Bitcoind appends an up-counting sequence number to each | using. Bitcoind appends an up-counting sequence number to each | ||||
notification which allows listeners to detect lost notifications. | notification which allows listeners to detect lost notifications. | ||||
The `sequence` topic refers specifically to the mempool sequence | |||||
number, which is also published along with all mempool events. This | |||||
is a different sequence value than in ZMQ itself in order to allow a total | |||||
ordering of mempool events to be constructed. |