bitcoin/bitcoin.org — pull request #660 by harding (2014-11-28 06:32:33+00:00)
Title: Dev Docs: Document Headers-First (And, By Extension, Blocks-First)

Dev Docs: Document Headers-First (And, By Extension, Blocks-First)

Preview (From Initial Block Download to end of Orphan Blocks): http://dg1.dtrt.org/en/developer-guide#initial-block-download

This commit provides a detailed overview of 0.10's headers-first block download method and significantly improves our current documentation of the current block download method, which I've retroactively named "blocks-first" for parallelism.

New And Significantly Revised:

* New Initial Block Download (IBD) section (h3) with separate Blocks-First and Headers-First subsections (h4) using parallel composition.

* 100% rewritten Blocks Broadcasting subsection describing blocks-first relay in much more detail, plus new descriptions of headers-first relay and SPV downloading.

* New Orphan Block subsection (under Blocks Broadcasting) describing orphan blocks and how they're handled differently under blocks-first and headers-first. Also includes a simple illustration of the difference between orphan blocks and stale blocks. Thanks to @luke-jr for his s/orphan block/stale block/ commit a couple months ago---that made this commit much easier.

Edits:

* Cleaned up a couple cases missed by previous s/orphan/stale/ commit because they used past tense (orphaned).

* Mentioned direct RPC changes introduced by headers-first pull in the RPC docs. TODO'd those sections to ensure we provide updated examples once 0.10 is released.

* In P2P reference section, mentioned that a `block` message can be sent unsolicited by miners.

* Mention that `getheaders` and `headers` were added in protocol version 31800.

* Moved a few internal links around and added a few new internal links.

Administrivia:

* Started adding "TODOv0.10" in HTML comments to places that need to be updated when 0.10 is released so that I can easily git grep for that tag later.