Bitcoin Core ZMQ Notifications for Mining and Monitoring

This guide explains Bitcoin Core ZMQ notifications in plain English. It focuses on what the subject is, why it matters and what a beginner should remember.

Four historical notifier types

Core 0.12 exposed hashtx, hashblock, rawtx and rawblock publishers configured with separate command-line or configuration options. Several topics could share one address. Hash bodies used binary bytes rather than printable hexadecimal, while raw topics carried whole serialised transactions or blocks.

PUB and SUB semantics

A subscriber must set a topic prefix or it receives nothing. PUB sockets do not track application acknowledgements and a late or disconnected subscriber misses prior messages. Self-healing reconnection restores the transport but does not replay gaps. Treat the feed as a prompt to query state, never as a complete event ledger.

No authentication

The publisher did not authenticate or authorise connecting clients. Endpoint exposure relied on IPC permissions, loopback binding, firewalling or another protected transport. A subscriber must also distrust data arriving at a configured address because another local process or network actor may be able to impersonate an unprotected publisher.

Reorganisation handling

The historical documentation notes that a tip change notifies the new tip; the subscriber must retrieve and compare the chain from its last known block. A single hashblock event does not state which blocks disconnected. Mining accounting, confirmations and alerts require an explicit active-chain reconciliation loop.

Mining integration boundary

A pool can use notifications to wake template refresh or monitor transactions, but block-template validity still comes from RPC and local consensus validation. Coalescing rapid events can be sensible, while treating every transaction message as a mandatory immediate template rebuild can create load and instability.

Sequence and version drift

Later Core releases expanded ZMQ message framing and sequence support. Consumers must follow the exact release documentation and test body byte order and topic names. A parser that assumes modern framing against a 0.12 publisher, or the reverse, may silently misread payloads.

Failure rehearsal

Start subscribers before and after the publisher, disconnect the network, overflow consumer processing and restart both ends. Create a regtest reorganisation and compare the local cursor with getbestblockhash. Confirm recovery queries close every gap and that alerts distinguish publisher loss from a quiet network.

Conclusion

ZMQ provides fast, low-coupling notification hints, not durable truth. Reliable mining and monitoring consumers persist a cursor, detect gaps, reconcile with a validating node and secure the otherwise unauthenticated endpoint.