/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: Describe Serialized Block Header And Block Format #638

Merged
merged 2 commits into from Nov 9, 2014

Conversation

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

harding commented Nov 8, 2014

Preview: http://dg0.dtrt.org/en/developer-reference#block-chain

  • Replace current description of the block header with a better description.
    • Describe the various version numbers.
    • Describe how the merkle root is constructed.
    • Describe how nBits is parsed and how to correctly create it to avoid negative values. See also my discussion with @minium on minium/Bitcoin-Spec#3
  • Describe the serialized block format used to calculate max block size.

Similar to pull #631, this is background documentation about the consensus-covered stuff for the upcoming non-consensus P2P reference section. Specificially, the goal here is to document the header format used in the P2P headers message and the serialized block format used in the P2P blocks message.
@harding
Dev Docs: Describe Serialized Block Header And Block Format 
* Replace current description of the block header with a better
description.

    * Describe the various version numbers.

    * Describe how the merkle root is constructed.

    * Describe how nBits is parsed and how to correctly create it to
      avoid negative values.

* Describe the serialized block format used to calculate max block size.
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
a8f8f75

@saivann saivann and 1 other commented on an outdated diff Nov 8, 2014

View full outdated diff
_includes/ref_block_chain.md
+ sha256(sha256("82501c1178fa0b222c1f3d474ec726b832013f0a532b44bb620cce8624a5feb1169e1e83e930853391bc6f35f605c6754cfead57cf8387639d3b4096c54f18f4".decode("hex")).digest()).digest().encode("hex_codec")
+-->
+
+![Example Merkle Tree Construction](/img/dev/en-merkle-tree-construction.svg)
+
+TXIDs and intermediate hashes are always in internal byte order when they're
+concatenated, and the resulting merkle root is also in internal byte
+order when it's placed in the block header.
+
+{% endautocrossref %}
+
+#### Target nBits
+
+{% autocrossref %}
+
+The target threshold is a 256-bit unsigned integer compared the 256-bit
@saivann

saivann Nov 8, 2014

Contributor

@harding Perhaps I'm missing something, but is there some wrong formulation or missing word in this sentence? I don't get what "compared the..." means in this context.

@harding

harding Nov 8, 2014

Contributor

@saivann How about:

The target threshold is a 256-bit unsigned integer which a header hash must be equal to or below in order for that header to be a valid part of the block chain.

@saivann

saivann Nov 8, 2014

Contributor

@harding Sounds good to me!
@saivann
Contributor

saivann commented Nov 8, 2014

Will read everything tomorrow, but looks awesome at a first glance! Thanks for sharing work and questions with @minium, perhaps both projects can benefit from each other.
@minium

minium commented Nov 8, 2014

@saivann They sure will, I'm already on it!

@saivann saivann commented on an outdated diff Nov 8, 2014

View full outdated diff
_includes/ref_block_chain.md
-As of version 2 blocks, each block consists of four root elements:
+| Bytes | Name | Data Type | Description
+|-------|---------------------|-----------|----------------
+| 4 | version | uint32_t | The [block version][]{:#term-block-version}{:.term} number indicates which set of block validation rules to follow. See the list of block versions below.
+| 32 | previous block hash | char[32] | A SHA256(SHA256()) hash in internal byte order of the previous block's header. This ensures no previous block can be changed without also changing this block's header.
+| 32 | merkle root hash | char[32] | A SHA256(SHA256()) hash in internal byte order. The merkle root is derived from hashes of all transaction included in this block, ensuring none of those transactions can be modified without modifying the header. See the [merkle trees section][section merkle trees] below.
@saivann

saivann Nov 8, 2014

Contributor

s/all transaction included/all transactions included/ ?

@saivann saivann commented on an outdated diff Nov 8, 2014

View full outdated diff
_includes/ref_block_chain.md
-3. An 80-byte block header described in the section below.
+{% highlight text %}
+02000000 .......................... Block version: 2
@saivann

saivann Nov 8, 2014

Contributor

One dot is missing and the result isn't aligned;

02000000 ........................... Block version: 2
@saivann
Contributor

saivann commented Nov 8, 2014

@harding Except the small issues above, LGTM, thanks!

@minium Nice! :)
@harding
Dev Docs: Merkle Tree/nBits Minor Proofreading Edits 
Based on feedback from @saivann (thanks!)
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
63b4d03
@harding
Contributor

harding commented Nov 8, 2014

@saivann thanks for the review! I think commit 63b4d03 addresses all of your feedback; I also updated the preview.

In the absence of critical feedback, this pull will be merged around 22:00 UTC Sunday.

@harding harding merged commit 63b4d03 into bitcoin-dot-org:master Nov 9, 2014

harding added a commit that referenced this pull request Nov 9, 2014

@harding
Merge branch 'serialized-blocks' (pull #638)
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
a50e455

@harding harding deleted the harding:serialized-blocks branch Feb 25, 2015

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