Glossary / Developer reference
MSG_BLOCK
- Definition
- MSG_BLOCK is inventory type 2, the code a node puts in a getdata message to ask a peer for one complete block by its hash.
Four bytes of type tag decide which of several block formats arrives. Type 2 means the original one: an 80 byte header followed by every transaction in full, with witness data stripped out, up to the four million weight units a block may hold. A node catching up with the chain sends thousands of these requests and very little else.
How it works
MSG_BLOCK is a number rather than a message, and it carries meaning only inside the 36 byte entries that inv and getdata messages are built from.
An entry is a four byte type followed by a 32 byte hash, and the type tells the receiver what the hash names. Sending getdata with a type 2 entry says: I have this block's hash, send me the block. The peer answers with one block message, or with notfound if it cannot supply it. A pruned node returns notfound for anything it has already deleted, which is why a pruned peer is no use to somebody syncing from scratch.
Type 2 on its own now means something narrower than it once did. Since segregated witness activated in 2017, a block requested this way comes back in the old serialization with witness data removed, which was necessary so older software could still be served. Any node that means to validate the block needs those witnesses, so it sets the 0x40000000 bit and asks for the witness variant instead. Between two modern peers the plain code shows up mainly in requests from software nobody has updated.
Announcement moved on as well. BIP130 introduced direct header announcement, and since Bitcoin Core 0.12.0 a new block is normally announced with a headers message rather than an inv, so this type code now lives mostly on the requesting side of the conversation.
Bitcoin Core will not race ahead without limit while downloading. It keeps a window of 1,024 blocks past the last one it has validated, so a single stalling peer cannot leave the node holding an unbounded queue of blocks it has no way to connect.
Where you see it
Block requests dominate a node's traffic exactly once, during its first sync, and then almost never again.
The chain passed 840,000 blocks at the halving on April 20, 2024 and grows by roughly 144 blocks a day, so a machine starting fresh fetches close to a million of them before it is current. You can watch that with getpeerinfo, which counts bytes per message type for every peer, or in the log with -debug=net. Once the node reaches the tip those counters go quiet and compact block traffic takes over.
MSG_BLOCK vs MSG_CMPCT_BLOCK
MSG_BLOCK and MSG_CMPCT_BLOCK differ in where they are allowed as much as in what they fetch. Type 2 is legal in an inv and in a getdata, may be sent to any peer without prior arrangement, and works for a block of any age. Type 4 is legal only in a getdata, may only be sent to a peer that has already offered compact blocks with a sendcmpct message, and in Bitcoin Core is served only for the five most recent blocks. Ask for anything deeper with type 4 and a full block message comes back anyway.