/bitcoin.org

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 1 commit into
from

Conversation

Reviewers
No reviews
Assignees
No one assigned
Labels
Dev Docs
Projects
None yet
Milestone
No milestone
3 participants
@harding @gmaxwell @saivann
@harding
Contributor

harding commented Nov 28, 2014

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.
@harding
Contributor

harding commented Nov 29, 2014

Rebased to fix merge conflict and updated preview to match. I suspect I'll need to rebase again when #661 is merged.

@harding harding added the Dev Docs label Nov 30, 2014

@harding
Dev Docs: Document Headers-First (And, By Extension, Blocks-First) 
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 called 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 in
  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.
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
ee57559
@harding
Contributor

harding commented Nov 30, 2014

Rebased to fix merge conflict and updated preview to match.
@gmaxwell
Contributor

gmaxwell commented Nov 30, 2014

@sipa This should have your review.
@harding
Contributor

harding commented Dec 16, 2014

I just started re-reading this after a rebase, and I find the text doesn't flow at all. Since this doesn't have any reviews yet---possibly because of the bad writing---I'm going to close this pull, rephrase, and submit a new pull in a few days.

@harding harding closed this Dec 16, 2014

@saivann
Contributor

saivann commented Dec 16, 2014

@harding FWIW I didn't have time to start looking at any changes in that pull request yet, so as far as I'm concerned, this wasn't the issue :) .

This was referenced Dec 18, 2014

Merged
Merged

@harding harding deleted the harding:initialblockdownload branch Feb 25, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment