Dev Docs: Describe P2P Messages That Request Or Reply With Data

[harding]

P2P Reference Preview: http://dg0.dtrt.org/en/developer-reference#p2p-network
P2P Examples Preview: http://dg0.dtrt.org/en/developer-examples#p2p-network

Adds to the devel reference page detailed documentation on the following messages: block, getblocks, getdata, getheaders, headers, inv, mempool, merkleblock, notfound, and tx.

Adds to the devel examples page an example of requesting and parsing a merkleblock message.

Adds to the devel docs overview pages links to the above two new P2P sections.

Tweaks the autocrossref plugin ignore pattern to not crossref in the middle of a GIF image name; this allows the inclusion of animated GIFs.

Note: I'm working on documenting the remaining P2P messages in a separate branch.

[saivann]

s/for for transactions/for transactions

[saivann]

Small alignment issue, should probably be:
00 ................................. Transaction Count (0x00)

[saivann]

s/verified are valid/verified as valid , maybe?

[saivann]

s/previous set/previously set/ maybe ?

[saivann]

s/after the the/after the/

[saivann]

Feel free to ignore this one or not, it's just a small suggestion, it seems a bit clearer to me when reversing the negation consistently with other sentences:

"Fail if the hash of the merkle root node is not identical to the merkle root in the block header."

[saivann]

To my understanding, given that you need to put a flag when going from the left child to the right child, would it be more accurate to say the following?

"Never put a flag on the list when ascending to a previously processed node"

[harding]

Yes, when descending into the right child, you will need to put a flag on the list. Also, "Never put a flag..." is a correct statement.

However, the current statement looks accurate to me, so I'm not sure that the revised statement is more accurate. I'm guessing something in the current statement looked confusing to you---could you point that out for me? (Is it just that the current statement has the subjunctive clause? "except when...")

[saivann]

Maybe it's just the way I read "descending" (which I interpret as going from the parent to the child, not going edit: from the left node to the right node).

[harding]

Oh, hmm. I guess I conceptualized things the way the animated GIF shows them, with little arrows showing:

1. going down into the left child
2. going back up into the parent
3. going down into the right child

How about if we just s/descend into/begin processing/ in the text so it reads:

Any time you begin processing a node for the first time, a flag should be
appended to the flag list. Never put a flag on the list at any other
time, except when processing is complete to pad out the flag list to a
byte boundary.

If that sounds good to you, I'll probably also see about making the same change in the parsing instructions.

[saivann]

@harding Sounds perfect to me!

[saivann]

I tend to read this one as "begin processing after descending into the right child", in other words, ignore the right node. Would it be clearer to say the following?

...until you find a node with a right child you haven’t processed yet and begin processing again.

[harding]

We already have an "and" in that sentence, so I'm changing the final sentence in that paragraph to: "Descend into that right child and process it."

[saivann]

Make sense, thanks!

[saivann]

If I understand correctly, would it be more accurately phrased this way?

"The header hash of the last header hash being requested; set to all zeroes to request an inv message with all subsequent header hashes (the maximum which will ever be sent as a reply to this message will be 500 header hashes)."

[saivann]

Given that one may need to get the hashes of additional childs, would it be more accurate to say the following?

The hash needs to be computed. Process the child nodes to get its hash, starting with the left child node. Once you have the hashes of the two child nodes, concatenate the two hashes as 64 raw bytes and hash them to get this node’s hash.

[harding]

@saivann Hmm, it feels better to me to use the table to define the conditionals the way you might write a recursive function rather than use it to explain how the function will look as it operates over the tree. For example:

process(node) {
  if (flag==1 && type == "non-txid" ) {
    return(hash(process(left-child) + process(right-child)))
  }
 [...]
}

Although I think describing that descendant nodes may need to be hashed before this node is processed may help people who only read the table, I think the way the current version describes that behavior in detail in one of the following paragraphs allows us to keep the table neat and also be very clear.

Does that make sense?

[saivann]

@harding Ah... right, yes please ignore my comment (sorry!). After reading the text again, I now think your version was appropriate

[saivann]

@harding I've commented on everything that seemed worth reporting. Really amazing work!!!

[harding]

@saivann thank you so much for your review! (I know it was a giant pull request---thanks for taking the time.) All your comments look reasonable to me; I'll start implementing them and comment on any that I discover don't work. Thanks again!

[harding]

Updated text and preview with corrections suggested by @saivann. (Thanks!)

In the absence of critical feedback, I'll merge this pull around 18:00 UTC Sunday.