doc: Fix and clarify description of ZMQ message format #31862

1. 
   jirijakes commented at 7:32 am on February 14, 2025: none

   This change stresses that all ZMQ messages share the same structure and that they differ only in the format of the bodies. Previously this was not clear.

   Further it removes the notion of endianness of 32-byte hashes, as it is misleading, and replaces it with the term ‘reversed byte order’ (as opposed to natural or normal byte order).

   Additionally, it states that ZMQ 32-byte hashes are in the same format as in RPC. Previously it incorrectly stated that the two were in different formats.

   Fixes #31856.

2. 
   DrahtBot commented at 7:32 am on February 14, 2025: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/31862.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   Concept ACK	l0rinc

   If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

3. DrahtBot added the label Docs on Feb 14, 2025
4. 
   l0rinc commented at 4:53 pm on February 14, 2025: contributor

   Concept ACK
5. jirijakes marked this as a draft on Feb 20, 2025
6. 
   jirijakes commented at 3:21 am on February 20, 2025: none

   Switched to draft because I found another thing to fix in this PR. Will get to it within a day.
7. jirijakes force-pushed on Feb 21, 2025
8. jirijakes renamed this:
   doc: Fix description of byte order of hashes in ZMQ documentation
   doc: Fix and clarify description of ZMQ message format
   on Feb 21, 2025
9. jirijakes marked this as ready for review on Feb 21, 2025
10. 
    jirijakes commented at 1:57 am on February 21, 2025: none

    Ready for review again.

    When trying to use ZMQ, I realized that the description of sequence was not clear about the format of the message. Therefore I expanded this PR to also clarify that.

    This PR now:

    • clarifies that all messages share the same structure (three parts)
    • adds that sequence numbers are distinct for each topic
    • replaces endianness of 32-byte hashes with their byte order
    • puts note about byte order before specification of body formats
    • from descriptions of topics removes information that feels redundant

    Note that source code diff is not too useful, rendered one is clearer.

11. doc: Fix and clarify description of ZMQ message format

    This change stresses that all ZMQ messages share the same structure
    and that they differ only in the format of the bodies. Previously this
    was not clear.
    
    Further it removes the notion of endianness of 32-byte hashes,
    as it is misleading, and replaces it with the term 'reversed byte
    order' (as opposed to natural or normal byte order).
    
    Additionally, it states that ZMQ 32-byte hashes are in the same format
    as in RPC. Previously it incorrectly stated that the two were in
    different formats.

    33098172ef
12. jirijakes force-pushed on Feb 21, 2025

Contributors
jirijakes DrahtBot l0rinc

Labels
Docs