Remote peers can use the P2P message gethdrsen to request block headers together with the contents of the coinbase transaction and any miner-info transaction plus proof of their inclusion. Headers with the coinbase and miner-info transactions and proof of inclusion are returned to the requesting peer in P2P message hdrsen. Peers can also request to receive block announcements in form of hdrsen P2P messages. Primary users of this P2P message are SPV clients which may require simplified access to miner ID provided in miner-info transactions.
The P2P message gethdrsen is an extension of the getheaders message.
Specifically, the message hdrsen, which is sent back to the peer from which message gethdrsen was received, contains the same data as headers message with additional fields for the coinbase transaction contents, any miner-info transaction referenced from the coinbase, and Merkle proof of inclusion for the coinbase and miner-info transactions. Message hdrsen may also be sent to announce new blocks if a peer has requested this with message sendhdrsen.
All messages defined in this specification are pure additions to the P2P protocol and do not change the semantics of other messages in any way. Changing the version of P2P protocol is not required. Nodes are encouraged to implement these messages, but are not required to do so. Peers sending them must be prepared to handle this situation (i.e. message may be ignored by node and no response is sent back to the peer).
If a node receives gethdrsen message from a remote peer, it responds with message hdrsen. The message payload is the same as for message getheaders and contains parameters to limit the number of headers that will be returned. The semantics of the parameters used to specify which headers are requested are also the same as for message getheaders. See specification of P2P message getheaders for further details.
The sendhdrsen message is defined as an empty message where pchCommand == "sendhdrsen".
Upon receipt of a sendhdrsen message, the node will be permitted, but not required, to announce new blocks by sending the enriched headers using message hdrsen (defined below) of the new block (along with any other blocks that a node believes a peer might need in order for the block to connect).
This message is intended to have similar semantics as message sendheaders.
Nodes will not announce new blocks by sending enriched headers if any of the following are true:
- New block is not on node's active chain.
- Peer receiving the announcement does not have the header of parent block (as determined by node sending the announcement). In this case new blocks will be announced as if sendhdrsen message was never received (i.e. by sending inv message).
- There are more than 8 blocks to announce. In this case new blocks will be announced as if sendhdrsen message was never received (i.e. by sending inv message).
- Node has received sendheaders/sendcmpct message from peer. If sendheaders/sendcmpct message is received (either before or after sendhdrsen), headers are announced as specified by sendheaders/sendcmpct message. This exception is needed to avoid changing semantics of sendheaders/sendcmpct message, which would require changing the protocol version.
- Size of hdrsen message exceeds limit imposed by maxRecvPayloadLength parameter. In this case new blocks will be announced as if sendhdrsen message was never received (i.e. by sending inv message). This exception is needed to avoid pushing a large amount of data to peers that cannot handle it. Unlike when enriched headers are explicitly requested with gethdrsen, it also applies if there is only a single header to announce. Note that if several headers need to be announced and the size of the corresponding hdrsen message exceeds the size limit but announcing each header separately would not, this cannot be done because messages may arrive out of order. If sendhdrsen message is received more than once from the same peer, it may be treated as a protocol violation.
While nodes may use this message to receive new block announcements via hdrsen message, they are encouraged not to do so as it provides no benefits (nodes can obtain coinbase and miner-info transactions plus their Merkle proofs during block validation) and unnecessarily increases resource usage. Receiving block announcements with enriched headers is primarily intended for SPV clients that do not validate every block.
The hdrsen message returns enriched block headers requested by a gethdrsen message. It is also used to announce new blocks to peers that have requested this with sendhdrsen message.
If a peer receives this message without explicitly requesting it first, it can be ignored. Receiving unrequested hdrsen message should not be treated as protocol violation.
| Field size | Description | Data Type | Comments |
|---|---|---|---|
| 1+ | count | var_int | Number of enriched block headers. May be 0 if no header matches parameters specified in gethdrsen message. No more than 2000 enriched block headers are returned in a single message. Since the contents of the coinbase and miner-info transactions can be large, maximum size of hdrsen message is limited to maximum packet size that was agreed on in protoconf message with maxRecvPayloadLength parameter (value is specified in peer configuration). The number of returned enriched block headers is reduced as needed to stay below this limit, but not below 1. This is so that one header requested by gethdrsen message can be returned even if limit imposed by maxRecvPayloadLength parameter is exceeded. This limit is always honored if message is sent to announce new blocks (i.e. new blocks will not be announced with this message if the size of the message would exceed the limit). |
| ? | enriched block headers | block_header_en[] | List of enriched block headers (see below). |
| Field size | Description | Data Type | Comments |
|---|---|---|---|
| 81+ | all block header fields | various | Same fields as in block header returned by headers message. Note: Value of field txn_count (transaction count) in block header is typically set to 0 if header is not sent as part of block message (e.g. in headers message). Here the value of this field is set to actual transaction count if that information is available (i.e. if the block was already validated). |
| 1 | no more headers | uint8_t | Boolean value indicating if there are more block headers available after the current header. This value only equals true (1) for header of the block that is currently a tip of the active chain as seen by the node that is sending the message. |
| 1 | has coinbase and proof | uint8_t | Boolean value indicating if current block header has additional coinbase data following this field. This value may be equal to false if the message is sent as response to message gethdrsen and the node does not have the required data (e.g. if requested block is not yet fully validated, or if it was already pruned). This value is always true if message is sent to announce new blocks. |
| ? | coinbase txn | uint8_t[] | Serialised coinbase transaction. This field is only present if "has coinbase and proof" field was set to true. |
| ? | coinbase merkle proof | uint8_t[] | Merkle proof in binary format according to standard TS 2020.010-31. This field is only present if "has coinbase and proof" field was set to true. Value of flags field is zero. Fields txOrId and target contain an ID of a coinbase transaction and a block hash, respectively. Value of index field is zero since the proof is for coinbase transaction which is always the first transaction in a block. Value of type field is zero in every node element in nodes field. |
| 1 | has miner-info and proof | uint8_t | Boolean value indicating if current block header has additional miner-info transaction data following this field. |
| ? | miner-info txn | uint8_t[] | Serialised miner-info transaction. This field is only present if "has miner-info and proof" field was set to true. |
| ? | miner-info merkle proof | uint8_t[] | Merkle proof in binary format according to standard TS 2020.010-31. This field is only present if "has miner-info and proof" field was set to true. Value of flags field is zero. Fields txOrId and target contain an ID of a miner-info transaction and a block hash, respectively. Value of index field is the position of the miner-info transaction within the block. Value of type field is zero in every node element in nodes field. |