Request: Get Headers ("getheaders")
Request a sequence of block headers.
Message Format
| Field | Length | Format | Description |
|---|---|---|---|
| locator | variable | vector of 32 byte block hash identifiers | identifies the location of the desired headers |
| stop at hash | 32 bytes | bytes | stop providing headers at this hash |
Locator
The locator is an array of block hash identifiers whose purpose is to communicate a position in a blockchain that may be forked from the blockchain that the receiver sees as having the most work. It does so by providing a series of block hash identifiers ranging from the desired height to the genesis block. The locator solves both major currency forks and minor forks caused by near-simultaneous block discovery.
The first hash in the locator is the parent of the desired identifiers. Subsequent elements are ancestors of previous elements, chosen by the client. A common strategy is to provide M direct ancestors and then make the M+Nth element the 2^Nth ancestor, finishing with the genesis block. This results in an amount of data that is approximately the log of the length of the chain (C++).
The response will begin at the child of the first hash in the locator list that matches a block hash identifier held by the responder. If no hashes match, the response will begin at block height 1 (child of the genesis block).
If the locator has no entries, the locator is ignored (see Stop At Hash).
A locator MUST NOT contain more than 101 hashes; Bitcoin Cash Node disconnects peers that send a larger locator.
Use a valid locator whose first element is your chain tip and a zero "Stop At Hash" to request up to 2000 headers that extend your chain tip.
Stop At Hash
If a non-empty locator is provided, when constructing a response message, the sender will stop at the provided hash; the header with this hash is included in the reply. If the hash is never encountered, the sender will stop after 2000 headers are included in the reply.
If the locator is empty, the response includes only the header identified by this field (note it includes this hash, which differs from the behavior of the locator). In this case, if this hash is not found in the blockchain, the request is silently ignored.
Use an empty locator and a valid block hash identifier to request the header of a specific block.
Initial Block Download
A node that is still in initial block download may ignore getheaders requests. Bitcoin Cash Node does so for all peers except those with the noban permission.