diff --git a/_autocrossref.yaml b/_autocrossref.yaml index 9a367d0e..6cfbf9c6 100644 --- a/_autocrossref.yaml +++ b/_autocrossref.yaml @@ -30,6 +30,7 @@ block: block chain: block-chain: block chain block header: +block headers: block header block height: '`block` message': block message '`block` messages': block message @@ -37,6 +38,10 @@ block reward: block time: block version: blocks: block +blocks-first: blocks-first sync +blocks-first sync: +blocks-first IBD: blocks-first sync +bloom filter: broadcast: broadcasts: broadcast broadcasting: @@ -115,6 +120,8 @@ HD protocol: '`headers` messages': headers message high-priority transaction: high-priority transactions high-priority transactions: +IBD: initial block download +initial block download: inputs: input input: intermediate certificate: @@ -187,6 +194,8 @@ op codes: op code '`op_hash160`': op_hash160 '`op_return`': op_return '`op_verify`': op_verify +orphan block: +orphan blocks: orphan block outpoint: outpoints: outpoint outputs: output @@ -216,6 +225,7 @@ pki: '`point()`': point function '`pong` message': pong message '`pong` messages': pong message +previous block header hash: private key: private keys: private key proof of work: @@ -226,6 +236,7 @@ protocol version 106: section protocol versions protocol version 209: section protocol versions protocol version 311: section protocol versions protocol version 31402: section protocol versions +protocol version 31800: section protocol versions protocol version 60000: section protocol versions protocol version 60001: section protocol versions protocol version 60002: section protocol versions @@ -267,10 +278,10 @@ script hash: secp256k1: sequence number: sequence numbers: sequence number -serialized block: section serialized blocks -serialized blocks: section serialized block -serialized transaction: raw transaction format -serialized transactions: raw transaction format +serialized block: +serialized blocks: serialized block +serialized transaction: raw format +serialized transactions: raw format SIGHASH: signature hash '`SIGHASH_ANYONECANPAY`': shacp '`SIGHASH_ALL`': sighash_all @@ -522,6 +533,7 @@ Bitcoin Core 0.1.6: Bitcoin Core 0.2.9: Bitcoin Core 0.3.11: Bitcoin Core 0.3.15: +Bitcoin Core 0.3.18: Bitcoin Core 0.6.0: Bitcoin Core 0.6.1: Bitcoin Core 0.7.0: diff --git a/_includes/guide_block_chain.md b/_includes/guide_block_chain.md index c6523d91..6b99d7ca 100644 --- a/_includes/guide_block_chain.md +++ b/_includes/guide_block_chain.md @@ -181,8 +181,8 @@ the fork stronger than the other side. Assuming a fork only contains valid blocks, normal peers always follow the the most difficult chain to recreate and throw away [stale blocks][stale block]{:#term-stale-block}{:.term} belonging to shorter forks. -(Stale blocks are also sometimes called orphans or orphan blocks, but -those terms are also used for blocks without a known parent block.) +(Stale blocks are also sometimes called orphans or orphan blocks, but +those terms are also used for true orphan blocks without a known parent block.) [Long-term forks][long-term fork]{:#term-long-term-fork}{:.term} are possible if different miners work at cross-purposes, such as some miners diligently working to extend the block chain at the diff --git a/_includes/guide_p2p_network.md b/_includes/guide_p2p_network.md index c4a0a801..ab4a4360 100644 --- a/_includes/guide_p2p_network.md +++ b/_includes/guide_p2p_network.md @@ -140,6 +140,180 @@ In order to maintain a connection with a peer, nodes by default will send a mess {% endautocrossref %} +### Initial Block Download +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +Before a full node can validate unconfirmed transactions and +recently-mined blocks, it must download and validate all blocks from +block 1 (the block after the hardcoded genesis block) to the current tip +of the best block chain. This is the Initial Block Download (IBD) or +initial sync. + +Although the word "initial" implies this method is only used once, it +can also be used any time a large number of blocks need to be +downloaded, such as when a previously-caught-up node has been offline +for a long time. In this case, a node can use the IBD method to download +all the blocks which were produced since the last time it was online. + +Bitcoin Core uses the IBD method any time the last block on its local +best block chain has a block header time more than 24 hours in the past. +Bitcoin Core 0.10.0 will also perform IBD if its local best block chain is +more than 144 blocks lower than its local best headers chain (that is, +the local block chain is more than about 24 hours in the past). + +{% endautocrossref %} + +#### Blocks-First +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +Bitcoin Core (up until version [0.9.3][bitcoin core 0.9.3]) uses a +simple initial block download (IBD) method we'll call *blocks-first*. +The goal is to download the blocks from the best block chain in sequence. + +The first time a node is started, it only has a single block in its +local best block chain---the hardcoded genesis block (block 0). This +node chooses a remote peer, called the sync node, and sends it the +`getblocks` message illustrated below. + +![First GetBlocks Message Sent During IBD](/img/dev/en-ibd-getblocks.svg) + +In the header hashes field of the `getblocks` message, this new node +sends the header hash of the only block it has, the genesis block +(6fe2...0000 in internal byte order). It also sets the stop hash field +to all zeroes to request a maximum-size response. + +Upon receipt of the `getblocks` message, the sync node takes the first +(and only) header hash and searches its local best block chain for a +block with that header hash. It finds that block 0 matches, so it +replies with 500 block inventories (the maximum response to a +`getblocks` message) starting from block 1. It sends these inventories +in the `inv` message illustrated below. + +![First Inv Message Sent During IBD](/img/dev/en-ibd-inv.svg) + +Inventories are unique identifiers for information on the network. Each +inventory contains a type field and the unique identifier for an +instance of the object. For blocks, the unique identifier is a hash of +the block's header. + +The block inventories appear in the `inv` message in the same order they +appear in the block chain, so this first `inv` message contains +inventories for blocks 1 through 501. (For example, the hash of block 1 +is 4860...0000 as seen in the illustration above.) + +The IBD node uses the received inventories to request 128 blocks from +the sync node in the `getdata` message illustrated below. + +![First GetData Message Sent During IBD](/img/dev/en-ibd-getdata.svg) + +It's important to headers-first nodes that the blocks be requested and +sent in order because each block header references the header hash of +the preceeding block. That means the IBD node can't fully validate a +block until its parent block has been received. Blocks that can't be +validated because their parents haven't been received are called orphan +blocks; a subsection below describes them in more detail. + +Upon receipt of the `getdata` message, the sync node replies with each +of the blocks requested. Each block is put into serialized block format +and sent in a separate `block` message. The first `block` message sent +(for block 1) is illustrated below. + +![First Block Message Sent During IBD](/img/dev/en-ibd-block.svg) + +The IBD node downloads each block, validates it, and then requests the +next block it hasn't requested yet, maintaining a queue of up to 128 +blocks to download. When it has requested every block for which it has +an inventory, it sends another `getblocks` message to the sync node +requesting the inventories of up to 500 more blocks. This second +`getblocks` message contains multiple header hashes as illustrated +below: + +![Second GetBlocks Message Sent During IBD](/img/dev/en-ibd-getblocks2.svg) + +Upon receipt of the second `getblocks` message, the sync node takes the +first listed header hash and searches its local best block chain for a +block with that header hash. If it finds a block with that hash, it +replies with 500 block inventories starting with the following block. +But if it doesn't find a block with that hash, it takes the next header +hash from the `getblocks` message and searches its block chain for that +hash. If that hash matches, it will reply with 500 block inventories +starting with the following hash from that point. But, again, if it +doesn't find that hash, it will proceed to check the next hash in the +message (and so on until it runs out of hashes in the message). If the +last hash in the message (besides the stopping hash) doesn't match, it +assumes the only block the two nodes have in common is block 0 and so it +sends an `inv` starting with block 1 (the same `inv` message seen +several illustrations above). + +This repeated search allows the sync node to send useful inventories even if +the IBD node's local block chain forked from the sync node's local block +chain. This fork detection becomes increasingly useful the closer the +IBD node gets to the tip of the block chain. + +When the IBD node receives the second `inv` message, it will request +those blocks using `getdata` messages. The sync node will respond with +`block` messages. Then the IBD node will request more inventories with +another `getblocks` message---and the cycle will repeat until the IBD +node is synced to the tip of the block chain. At that point, the node +will accept blocks sent through the regular block broadcasting described +in a later subsection. + +{% endautocrossref %} + +##### Blocks-First Advantages & Disadvantages +{:.no_toc} +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +The primary advantage of blocks-first IBD is its simplicity. The primary +disadvantage is that the IBD node relies on a single sync node for all +of its downloading. This has several implications: + +* **Speed Limits:** All requests are made to the sync node, so if the + sync node has limited upload bandwidth, the IBD node will have slow + download speeds. Note: if the sync node goes offline, Bitcoin Core + will continue downloading from another node---but it will still only + download from a single sync node at a time. + +* **Download Restarts:** The sync node can send a non-best (but + otherwise valid) block chain to the IBD node. The IBD node won't be + able to identify it as non-best until the initial block download nears + completion, forcing the IBD node to restart its block chain download + over again from a different node. Bitcoin Core ships with several + block chain checkpoints at various block heights selected by + developers to help an IBD node detect that it is being fed an + alternative block chain history---allowing the IBD node to restart + its download earlier in the process. + +* **Disk Fill Attacks:** Closely related to the download restarts, if + the sync node sends a non-best (but otherwise valid) block chain, the + chain will be stored on disk, wasting space and possibly filling up + the disk drive with useless data. + +* **High Memory Use:** Whether maliciously or by accident, the sync node + can send blocks out of order, creating orphan blocks which can't be + validated until their parents have been received and validated. + Orphan blocks are stored in memory while they await validation, + which may lead to high memory use. + +All of these problems are addressed in part or in full by the +headers-first IBD method used in Bitcoin Core 0.10.0. + +**Resources:** The table below summarizes the messages mentioned +throughout this subsection. The links in the message field will take you +to the reference page for that message. + +| **Message** | [`getblocks`][getblocks message] | [`inv`][inv message] | [`getdata`][getdata message] | [`block`][block message] +| **From→To** | IBD→Sync | Sync→IBD | IBD→Sync | Sync→IBD +| **Payload** | One or more header hashes | Up to 500 block inventories (unique identifiers) | One or more block inventories | One serialized block + +{% endautocrossref %} + ### Block Broadcasting {% include helpers/subhead-links.md %} @@ -151,6 +325,31 @@ New blocks are also discovered as miners publish their found blocks, and these m {% endautocrossref %} +#### Orphan Blocks +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +Blocks-first nodes may download orphan blocks---blocks whose previous +block header hash field refers to a block header this node +hasn't seen yet. In other words, orphan blocks have no known parent +(unlike stale blocks, which have known parents but which aren't part of +the best block chain). + +![Difference Between Orphan And Stale Blocks](/img/dev/en-orphan-stale-definition.svg) + +When a blocks-first node downloads an orphan block, it will not validate +it. Instead, it will send a `getblocks` message to the node which sent +the orphan block; the broadcasting node will respond with an `inv` message +containing inventories of any blocks the downloading node is missing (up +to 500); the downloading node will request those blocks with a `getdata` +message; and the broadcasting node will send those blocks with a `block` +message. The downloading node will validate those blocks, and once the +parent of the former orphan block has been validated, it will validate +the former orphan block. + +{% endautocrossref %} + ### Transaction Broadcasting {% include helpers/subhead-links.md %} @@ -179,13 +378,13 @@ unconfirmed transactions tend to slowly disappear from the network as peers restart or as they purge some transactions to make room in memory for others. -Transactions which are mined into blocks that are later orphaned may be +Transactions which are mined into blocks that later become stale blocks may be added back into the memory pool. These re-added transactions may be re-removed from the pool almost immediately if the replacement blocks -include them. This is the case in Bitcoin Core, which removes orphaned +include them. This is the case in Bitcoin Core, which removes stale blocks from the chain one by one, starting with the tip (highest block). As each block is removed, its transactions are added back to the memory -pool. After all of the orphaned blocks are removed, the replacement +pool. After all of the stale blocks are removed, the replacement blocks are added to the chain one by one, ending with the new tip. As each block is added, any transactions it confirms are removed from the memory pool. diff --git a/_includes/ref_block_chain.md b/_includes/ref_block_chain.md index d5ecd548..b69a7779 100644 --- a/_includes/ref_block_chain.md +++ b/_includes/ref_block_chain.md @@ -21,7 +21,7 @@ serialized header format part of the consensus rules. | 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 | [previous block header hash][]{:#term-previous-block-header-hash}{:.term} | 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 the hashes of all transactions included in this block, ensuring that none of those transactions can be modified without modifying the header. See the [merkle trees section][section merkle trees] below. | 4 | time | uint32_t | The [block time][]{:#term-block-time}{:.term} is a Unix epoch time when the miner started hashing the header (according to the miner). Must be greater than or equal to the median time of the previous 11 blocks. Full nodes will not accept blocks with headers more than two hours in the future according to their clock. | 4 | nBits | uint32_t | An encoded version of the target threshold this block's header hash must be less than or equal to. See the nBits format described below. diff --git a/_includes/ref_p2p_networking.md b/_includes/ref_p2p_networking.md index 306a959a..1ab4907a 100644 --- a/_includes/ref_p2p_networking.md +++ b/_includes/ref_p2p_networking.md @@ -71,6 +71,7 @@ please [open an issue][docs issue].) | 60002 | Bitcoin Core 0.7.0
(Sep 2012) | [BIP35][]:
• Added `mempool` message.
• Extended `getdata` message to allow download of memory pool transactions | 60001 | Bitcoin Core 0.6.1
(May 2012) | [BIP31][]:
• Added nonce field to `ping` message
• Added `pong` message | 60000 | Bitcoin Core 0.6.0
(Mar 2012) | [BIP14][]:
• Separated protocol version from Bitcoin Core version +| 31800 | Bitcoin Core 0.3.18
(Dec 2010) | • Added `getheaders` message and `headers` message. | 31402 | Bitcoin Core 0.3.15
(Oct 2010) | • Added time field to `addr` message. | 311 | Bitcoin Core 0.3.11
(Aug 2010) | • Added `alert` message. | 209 | Bitcoin Core 0.2.9
(May 2010) | • Added checksum field to message headers. @@ -146,11 +147,20 @@ one of these unknown types. {% autocrossref %} The `block` message transmits a single serialized block in the format -described in the [serialized blocks section][section serialized blocks]. -See that section for an example hexdump. +described in the [serialized blocks section][serialized block]. +See that section for an example hexdump. It can be sent for two +different reasons: -It is sent in reply to a `getdata` message which had an inventory type of -`MSG_BLOCK` and the header hash of the particular block being requested. +1. **GetData Response:** Nodes will always send it in response to a + `getdata` message that requests the block with an inventory + type of `MSG_BLOCK` (provided the node has that block available for + relay). + +2. **Unsolicited:** Some miners will send unsolicited `block` messages + broadcasting their newly-mined blocks to all of their peers. Many + mining pools do the same thing, although some may be misconfigured to + send the block from multiple nodes, possibly sending the same block + to some peers more than once. {% endautocrossref %} @@ -235,6 +245,8 @@ identical to the `inv` message; only the message header differs. {% autocrossref %} +*Added in protocol version 31800.* + The `getheaders` message requests a `headers` message that provides block headers starting from a particular point in the block chain. It allows a peer which has been disconnected or started for the first time to get @@ -245,15 +257,21 @@ with one minor difference: the `inv` reply to the `getblocks` message will include no more than 500 block header hashes; the `headers` reply to the `getheaders` message will include as many as 2,000 block headers. +{% endautocrossref %} + #### Headers {% include helpers/subhead-links.md %} +{% autocrossref %} + +*Added in protocol version 31800.* + The `headers` message sends one or more block headers to a node which previously requested certain headers with a `getheaders` message. | Bytes | Name | Data Type | Description |----------|---------|------------------|----------------- -| *Varies* | count | compactSize uint | Number of block headers up to a maximum of 2,000. +| *Varies* | count | compactSize uint | Number of block headers up to a maximum of 2,000. Note: headers-first sync assumes the sending node will send the maximum number of headers whenever possible. | *Varies* | headers | block_header | Block headers: each 80-byte block header is in the format described in the [block headers section][block header] with an additional 0x00 suffixed. This 0x00 is called the transaction count, but because the headers message doesn't include any transactions, the transaction count is always zero. The following annotated hexdump shows a `headers` message. (The message diff --git a/_includes/references.md b/_includes/references.md index 89daa26e..44e56198 100644 --- a/_includes/references.md +++ b/_includes/references.md @@ -15,6 +15,7 @@ http://opensource.org/licenses/MIT. [bits]: /en/developer-guide#term-bits "0.000001 bitcoins (100 satoshis)" [block]: /en/developer-guide#term-block "A block of transactions protected by proof of work" [blocks]: /en/developer-guide#term-block "Blocks of transactions protected by proof of work" +[blocks-first sync]: /en/developer-guide#blocks-first "Synchronizing the block chain by downloading each block from a peer and then validating it" [block chain]: /en/developer-guide#block-chain "A chain of blocks with each block linking to the block that preceded; the most-difficult-to-recreate chain is The Block Chain" [block header]: /en/developer-reference#block-headers "An 80-byte header belonging to a single block which is hashed repeatedly to create proof of work" [block height]: /en/developer-guide#term-block-height "The number of chained blocks preceding this block" @@ -22,6 +23,7 @@ http://opensource.org/licenses/MIT. [block reward]: /en/developer-reference#term-block-reward "New satoshis given to a miner for creating one of the first 6,929,999 blocks" [block time]: /en/developer-reference#term-block-time "The time field in the block header" [block version]: /en/developer-reference#term-block-version "The version field in the block header" +[bloom filter]: /en/developer-guide#bloom-filters "A filter used primarily by SPV nodes to request only matching transactions and merkle blocks from full nodes" [broadcast]: /en/developer-guide#transaction-broadcasting "Sending transactions or blocks to all other peers on the Bitcoin network (compare to privately transmitting to a single peer or partner" [broadcasts]: /en/developer-guide#transaction-broadcasting "Sending transactions or blocks to all other peers on the Bitcoin network (compare to privately transmitting to a single peer or partner" [broadcasting]: /en/developer-guide#transaction-broadcasting "Sending transactions or blocks to all other peers on the Bitcoin network (compare to privately transmitting to a single peer or partner)" @@ -67,6 +69,7 @@ http://opensource.org/licenses/MIT. [HD protocol]: /en/developer-guide#term-hd-protocol "The Hierarchical Deterministic (HD) key creation and transfer protocol" [headers message]: /en/developer-reference#headers "A P2P protocol message containing one or more block headers" [high-priority transactions]: /en/developer-guide#term-high-priority-transactions "Transactions which don't pay a transaction fee; only transactions spending long-idle outputs are eligible" +[initial block download]: /en/developer-guide#initial-block-download "The process used by a new node (or long-offline node) to download a large number of blocks to catch up to the tip of the best block chain" [input]: /en/developer-guide#term-input "The input to a transaction linking to the output of a previous transaction which permits spending of satoshis" [inputs]: /en/developer-guide#term-input "The input to a transaction linking to the output of a previous transaction which permits spending of satoshis" [intermediate certificate]: /en/developer-examples#term-intermediate-certificate "A intermediate certificate authority certificate which helps connect a leaf (receiver) certificate to a root certificate authority" @@ -114,6 +117,7 @@ http://opensource.org/licenses/MIT. [op_return]: /en/developer-reference#term-op-return "Operation which terminates the script in failure" [op_verify]: /en/developer-reference#term-op-verify "Operation which terminates the script if the entry below it on the stack is non-true (zero)" [outpoint]: /en/developer-reference#outpoint "The structure used to refer to a particular transaction output, consisting of a 32-byte TXID and a 4-byte output index number (vout)." +[orphan block]: /en/developer-guide#orphan-blocks "Blocks whose parent block has not been processed by the local node; not to be confused with stale blocks" [output]: /en/developer-guide#term-output "The output of a transaction which transfers value to a pubkey script" [output index]: /en/developer-guide#term-output-index "The sequentially-numbered index of outputs in a single transaction starting from 0" [P2PKH]: /en/developer-guide#term-p2pkh "A pubkey script which Pays To PubKey Hashes (P2PKH), allowing spending of satoshis to anyone with a Bitcoin address" @@ -133,6 +137,7 @@ http://opensource.org/licenses/MIT. [PKI]: /en/developer-examples#term-pki "Public Key Infrastructure; usually meant to indicate the X.509 certificate system used for HTTP Secure (https)." [point function]: /en/developer-guide#term-point-function "The ECDSA function used to create a public key from a private key" [pong message]: /en/developer-reference#pong "A P2P network message used to reply to a P2P network ping message" +[previous block header hash]: /en/developer-reference#term-previous-block-header-hash "A field in the block header which contains the SHA256(SHA256()) hash of the previous block's header" [private key]: /en/developer-guide#term-private-key "The private portion of a keypair which can create signatures which other people can verify using the public key" [private keys]: /en/developer-guide#term-private-key "The private portion of a keypair which can create signatures which other people can verify using the public key" [proper money handling]: /en/developer-reference#term-proper-money-handling "Bitcoin amounts need to be correctly processed without introducing rounding errors that could cause monetary loss" @@ -161,8 +166,9 @@ http://opensource.org/licenses/MIT. [RPC byte order]: /en/developer-reference#hash-byte-order "A hash digest displayed with the byte order reversed; used in Bitcoin Core RPCs and other software." [satoshi]: /en/developer-guide#term-satoshi "The smallest unit of Bitcoin value; 0.00000001 bitcoins. Also used generically for any value of bitcoins" [satoshis]: /en/developer-guide#term-satoshi "The smallest unit of Bitcoin value; 0.00000001 bitcoins. Also used generically for any value of bitcoins" -[sequence number]: /en/developer-guide#term-sequence-number "A number intended to allow time locked transactions to be updated before being finalized; not currently used except to disable locktime in a transaction" [script hash]: /en/developer-guide#term-script-hash "The hash of a redeem script used to create a P2SH output" +[sequence number]: /en/developer-guide#term-sequence-number "A number intended to allow time locked transactions to be updated before being finalized; not currently used except to disable locktime in a transaction" +[serialized block]: /en/developer-reference#serialized-blocks "A block in the serialized form used to compute block byte size" [sha_shacp]: /en/developer-guide#term-sighash-all-sighash-anyonecanpay "Signature hash type which allows other people to contribute satoshis without changing the number of satoshis sent nor where they go" [shacp]: /en/developer-guide#term-sighash-anyonecanpay "A signature hash type which modifies the behavior of other signature hash types" [shn_shacp]: /en/developer-guide#term-sighash-none-sighash-anyonecanpay "Signature hash type which allows unfettered modification of a transaction" @@ -177,7 +183,7 @@ http://opensource.org/licenses/MIT. [spv]: /en/developer-guide#simplified-payment-verification-spv "A method for verifying particular transactions were included in blocks without downloading the entire contents of the block chain" [ssl signature]: /en/developer-examples#term-ssl-signature "Signatures created and recognized by major SSL implementations such as OpenSSL" [stack]: /en/developer-guide#term-stack "An evaluation stack used in Bitcoin's script language" -[stale block]: /en/developer-guide#term-stale-block "Blocks which were successfully mined but which aren't included on the current valid block chain" +[stale block]: /en/developer-guide#term-stale-block "Blocks which were successfully mined but which aren't included on the current valid block chain; not to be confused with orphan blocks" [standard script]: /en/developer-guide#standard-transactions "A pubkey script which matches the IsStandard() patterns specified in Bitcoin Core---or a transaction containing only standard outputs. Only standard transactions are mined or broadcast by peers running the default Bitcoin Core software" [start string]: /en/developer-reference#term-start-string "Four defined bytes which start every message in the P2P protocol to allow seeking to the next message" [target]: /en/developer-guide#term-target "The threshold below which a block header hash must be in order for the block to be added to the block chain" @@ -376,8 +382,10 @@ http://opensource.org/licenses/MIT. [Bitcoin Core 0.2.9]: https://github.com/bitcoin/bitcoin/commit/42605ce8bcc9bd01b86491c74fee14de77960868 [Bitcoin Core 0.3.11]: https://github.com/bitcoin/bitcoin/commit/343328c6b8db85e58a1feea85f0d10e62967fa19 [Bitcoin Core 0.3.15]: https://github.com/bitcoin/bitcoin/commit/c891967b6fcab2e8dc4ce0c787312b36c07efa4d +[Bitcoin Core 0.3.18]: https://github.com/bitcoin/bitcoin/commit/82201801336f64ee77851b9eaab9383ee4e442f0 [bitcoin core fee drop commit]: https://github.com/bitcoin/bitcoin/commit/6a4c196dd64da2fd33dc7ae77a8cdd3e4cf0eff1 [Bitcoin Core issue #2381]: https://github.com/bitcoin/bitcoin/issues/2381 +[Bitcoin Core pull #4468]: https://github.com/bitcoin/bitcoin/pull/4468 [Bitcoin Seeder]: https://github.com/sipa/bitcoin-seeder [bitcoin-documentation mailing list]: https://groups.google.com/forum/#!forum/bitcoin-documentation [BitcoinJ]: http://bitcoinj.github.io diff --git a/img/dev/README b/img/dev/README index b4f46554..f5264f4c 100644 --- a/img/dev/README +++ b/img/dev/README @@ -14,7 +14,8 @@ corresponding commands: circo -T svg file.circo -o file.svg neato -T png file.neato -o file.png -Notice: Graphviz can be inconsistent across versions. All of the SVG and +Notice: Graphviz can be inconsistent across versions. +Up until commit ab415e8b6 (2014-12-17), all of the SVG and PNG images here were generated using graphviz version 2.26.3 (20100126.1600) on Debian 7 using the following shell loop: @@ -26,6 +27,11 @@ PNG images here were generated using graphviz version 2.26.3 optipng -o7 ${f/.dot}.png done +Images created after commit ab415e8b6 used Debian Graphviz version +2.38.0-7. This higher version is required to support the HTML bold and +italics tags used in some newer images, and we may come to use some of +its other extra features such as the sides="" parameter. + For improved compatability between Graphviz versions, files created or updated after 6 May 2014 are recommend to include the following code near the top of the file: diff --git a/img/dev/en-ibd-block.dot b/img/dev/en-ibd-block.dot new file mode 100644 index 00000000..565811ba --- /dev/null +++ b/img/dev/en-ibd-block.dot @@ -0,0 +1,48 @@ +digraph { +// This file is licensed under the MIT License (MIT) available on +// http://opensource.org/licenses/MIT. + +size=6.25; +rankdir=LR +splines = "false"; +ranksep = 0.5; +nodesep = 0.1; + +edge [ penwidth = 1.75, fontname="Sans" ] +node [ penwidth = 1.75, shape = "box", fontname="Sans"] +graph [ penwidth = 1.75, fontname="Sans" ] + +ibd -> block:f1 -> sync [dir="back"]; + +ibd [ label = "IBD\nNode", shape="none" ]; +sync [ label = "Sync\nNode", shape="none" ]; + +block [ shape="plaintext", label=< + + + + + + + + + + + + + + + + + + + + + + + + +
Block Message
Message Header
Start String
f9beb4d9		Command
block		Size
215		Checksum
934d270a
Payload
Serialized Block
010000006fe2...58eeac00000000
>]; + +label = "First block message sent to Initial Blocks Download (IBD) node" +} diff --git a/img/dev/en-ibd-block.png b/img/dev/en-ibd-block.png new file mode 100644 index 00000000..c28fa8a7 Binary files /dev/null and b/img/dev/en-ibd-block.png differ diff --git a/img/dev/en-ibd-block.svg b/img/dev/en-ibd-block.svg new file mode 100644 index 00000000..9a7277b8 --- /dev/null +++ b/img/dev/en-ibd-block.svg @@ -0,0 +1,56 @@ + + + + + + +%3 + +First block message sent to Initial Blocks Download (IBD) node + +ibd +IBD +Node + + +block +Block Message +Message Header + +Start String +f9beb4d9 + +Command +block + +Size +215 + +Checksum +934d270a +Payload + +Serialized Block +010000006fe2...58eeac00000000 + + + +ibd->block:f1 + + + + +sync +Sync +Node + + +block:f1->sync + + + + + diff --git a/img/dev/en-ibd-getblocks.dot b/img/dev/en-ibd-getblocks.dot new file mode 100644 index 00000000..547a79c1 --- /dev/null +++ b/img/dev/en-ibd-getblocks.dot @@ -0,0 +1,57 @@ +digraph { +// This file is licensed under the MIT License (MIT) available on +// http://opensource.org/licenses/MIT. + +size=6.25; +rankdir=LR +splines = "false"; +ranksep = 0.4; +nodesep = 0.1; + +edge [ penwidth = 1.75, fontname="Sans" ] +node [ penwidth = 1.75, shape = "box", fontname="Sans"] +graph [ penwidth = 1.75, fontname="Sans" ] + +ibd -> getblocks:f1 -> sync; + +ibd [ label = "IBD\nNode", shape="none" ]; +sync [ label = "Sync\nNode", shape="none" ]; + +getblocks [ shape="plaintext", label=< + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
GetBlocks Message
Message Header
Start String
f9beb4d9		Command
getblocks		Size
69		Checksum
f5fcbcad
Payload
Protocol Version
70002		Header Hash Count
1
Header Hashes (Highest-Height First)
6fe28c0ab6f1b3...d6190000000000
Stopping Hash (Zero Is "No Stop")
00000000000000...00000000000000
>]; + +label = "First getblocks message sent from Initial Blocks Download (IBD) node" +} diff --git a/img/dev/en-ibd-getblocks.png b/img/dev/en-ibd-getblocks.png new file mode 100644 index 00000000..385dd963 Binary files /dev/null and b/img/dev/en-ibd-getblocks.png differ diff --git a/img/dev/en-ibd-getblocks.svg b/img/dev/en-ibd-getblocks.svg new file mode 100644 index 00000000..7558d656 --- /dev/null +++ b/img/dev/en-ibd-getblocks.svg @@ -0,0 +1,65 @@ + + + + + + +%3 + +First getblocks message sent from Initial Blocks Download (IBD) node + +ibd +IBD +Node + + +getblocks +GetBlocks Message +Message Header + +Start String +f9beb4d9 + +Command +getblocks + +Size +69 + +Checksum +f5fcbcad +Payload + +Protocol Version +70002 + +Header Hash Count +1 + +Header Hashes (Highest-Height First) +6fe28c0ab6f1b3...d6190000000000 + +Stopping Hash (Zero Is "No Stop") +00000000000000...00000000000000 + + + +ibd->getblocks:f1 + + + + +sync +Sync +Node + + +getblocks:f1->sync + + + + + diff --git a/img/dev/en-ibd-getblocks2.dot b/img/dev/en-ibd-getblocks2.dot new file mode 100644 index 00000000..c329a6e8 --- /dev/null +++ b/img/dev/en-ibd-getblocks2.dot @@ -0,0 +1,57 @@ +digraph { +// This file is licensed under the MIT License (MIT) available on +// http://opensource.org/licenses/MIT. + +size=6.25; +rankdir=LR +splines = "false"; +ranksep = 0.4; +nodesep = 0.1; + +edge [ penwidth = 1.75, fontname="Sans" ] +node [ penwidth = 1.75, shape = "box", fontname="Sans"] +graph [ penwidth = 1.75, fontname="Sans" ] + +ibd -> getblocks:f1 -> sync; + +ibd [ label = "IBD\nNode", shape="none" ]; +sync [ label = "Sync\nNode", shape="none" ]; + +getblocks [ shape="plaintext", label=< + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
GetBlocks Message
Message Header
Start String
f9beb4d9		Command
getblocks		Size
677		Checksum
52be83ef
Payload
Protocol Version
70002		Header Hash Count
20
Header Hashes (Highest-Height First)
db773c8f3b90ef...64f64f00000000
459f16a1c695d0...f66d8000000000
......18 more header hashes......
Stopping Hash (Zero Is "No Stop")
00000000000000...00000000000000
>]; + +label = "Second getblocks message sent from Initial Blocks Download (IBD) node" +} diff --git a/img/dev/en-ibd-getblocks2.png b/img/dev/en-ibd-getblocks2.png new file mode 100644 index 00000000..93d0d0f3 Binary files /dev/null and b/img/dev/en-ibd-getblocks2.png differ diff --git a/img/dev/en-ibd-getblocks2.svg b/img/dev/en-ibd-getblocks2.svg new file mode 100644 index 00000000..17ee971a --- /dev/null +++ b/img/dev/en-ibd-getblocks2.svg @@ -0,0 +1,67 @@ + + + + + + +%3 + +Second getblocks message sent from Initial Blocks Download (IBD) node + +ibd +IBD +Node + + +getblocks +GetBlocks Message +Message Header + +Start String +f9beb4d9 + +Command +getblocks + +Size +677 + +Checksum +52be83ef +Payload + +Protocol Version +70002 + +Header Hash Count +20 + +Header Hashes (Highest-Height First) +db773c8f3b90ef...64f64f00000000 +459f16a1c695d0...f66d8000000000 +......18 more header hashes...... + +Stopping Hash (Zero Is "No Stop") +00000000000000...00000000000000 + + + +ibd->getblocks:f1 + + + + +sync +Sync +Node + + +getblocks:f1->sync + + + + + diff --git a/img/dev/en-ibd-getdata.dot b/img/dev/en-ibd-getdata.dot new file mode 100644 index 00000000..62aa6ee3 --- /dev/null +++ b/img/dev/en-ibd-getdata.dot @@ -0,0 +1,73 @@ +digraph { +// This file is licensed under the MIT License (MIT) available on +// http://opensource.org/licenses/MIT. + +size=6.25; +rankdir=LR +splines = "false"; +ranksep = 0.2; +nodesep = 0.1; + +edge [ penwidth = 1.75, fontname="Sans" ] +node [ penwidth = 1.75, shape = "box", fontname="Sans"] +graph [ penwidth = 1.75, fontname="Sans" ] + +ibd -> getdata:f1 -> sync; + +ibd [ label = "IBD\nNode", shape="none" ]; +sync [ label = "Sync\nNode", shape="none" ]; + +getdata [ shape="plaintext", label=< + + + + + + + + + + + + + + + + + + + + + + + + + + + +
GetData Message
Message Header
Start String
f9beb4d9		Command
getdata		Size
4609		Checksum
33e41222
Payload
Number Of Objects Requested By Inventory
128
+ + + + + + + + + + + + + + + + + + + + +
Objects Requested (Inventory Entries)
TypeUnique Identifier (For Blocks, A Header Hash)
Block4860eb18bf1b1620...688e9a8300000000
Blockbddd99ccfda39da1...065f626a00000000
...............126 more inventory entries...............
+
>]; + +label = "First getdata message sent from Initial Blocks Download (IBD) node" +} diff --git a/img/dev/en-ibd-getdata.png b/img/dev/en-ibd-getdata.png new file mode 100644 index 00000000..01ee3004 Binary files /dev/null and b/img/dev/en-ibd-getdata.png differ diff --git a/img/dev/en-ibd-getdata.svg b/img/dev/en-ibd-getdata.svg new file mode 100644 index 00000000..cd7f0226 --- /dev/null +++ b/img/dev/en-ibd-getdata.svg @@ -0,0 +1,65 @@ + + + + + + +%3 + +First getdata message sent from Initial Blocks Download (IBD) node + +ibd +IBD +Node + + +getdata +GetData Message +Message Header + +Start String +f9beb4d9 + +Command +getdata + +Size +4609 + +Checksum +33e41222 +Payload + +Number Of Objects Requested By Inventory +128 + +Objects Requested (Inventory Entries) +Type +Unique Identifier (For Blocks, A Header Hash) +Block +4860eb18bf1b1620...688e9a8300000000 +Block +bddd99ccfda39da1...065f626a00000000 +...............126 more inventory entries............... + + + +ibd->getdata:f1 + + + + +sync +Sync +Node + + +getdata:f1->sync + + + + + diff --git a/img/dev/en-ibd-inv.dot b/img/dev/en-ibd-inv.dot new file mode 100644 index 00000000..534e5b8b --- /dev/null +++ b/img/dev/en-ibd-inv.dot @@ -0,0 +1,73 @@ +digraph { +// This file is licensed under the MIT License (MIT) available on +// http://opensource.org/licenses/MIT. + +size=6.25; +rankdir=LR +splines = "false"; +ranksep = 0.2; +nodesep = 0.1; + +edge [ penwidth = 1.75, fontname="Sans" ] +node [ penwidth = 1.75, shape = "box", fontname="Sans"] +graph [ penwidth = 1.75, fontname="Sans" ] + +ibd -> inv:f1 -> sync [ dir = "back" ]; + +ibd [ label = "IBD\nNode", shape="none" ]; +sync [ label = "Sync\nNode", shape="none" ]; + +inv [ shape="plaintext", label=< + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Inv Message
Message Header
Start String
f9beb4d9		Command
inv		Size
18003		Checksum
25173c57
Payload
Number Of Inventories (Max 500 In Reply To GetBlocks)
500
+ + + + + + + + + + + + + + + + + + + + +
Inventory Entries
TypeUnique Identifier (For Blocks, A Header Hash)
block4860eb18bf1b1620...688e9a8300000000
blockbddd99ccfda39da1...065f626a00000000
...............498 more inventory entries...............
+
>]; + +label = "First inv message reply sent to Initial Blocks Download (IBD) node" +} diff --git a/img/dev/en-ibd-inv.png b/img/dev/en-ibd-inv.png new file mode 100644 index 00000000..ba281e21 Binary files /dev/null and b/img/dev/en-ibd-inv.png differ diff --git a/img/dev/en-ibd-inv.svg b/img/dev/en-ibd-inv.svg new file mode 100644 index 00000000..d52bf88c --- /dev/null +++ b/img/dev/en-ibd-inv.svg @@ -0,0 +1,65 @@ + + + + + + +%3 + +First inv message reply sent to Initial Blocks Download (IBD) node + +ibd +IBD +Node + + +inv +Inv Message +Message Header + +Start String +f9beb4d9 + +Command +inv + +Size +18003 + +Checksum +25173c57 +Payload + +Number Of Inventories (Max 500 In Reply To GetBlocks) +500 + +Inventory Entries +Type +Unique Identifier (For Blocks, A Header Hash) +block +4860eb18bf1b1620...688e9a8300000000 +block +bddd99ccfda39da1...065f626a00000000 +...............498 more inventory entries............... + + + +ibd->inv:f1 + + + + +sync +Sync +Node + + +inv:f1->sync + + + + + diff --git a/img/dev/en-orphan-stale-definition.dot b/img/dev/en-orphan-stale-definition.dot new file mode 100644 index 00000000..6de8537c --- /dev/null +++ b/img/dev/en-orphan-stale-definition.dot @@ -0,0 +1,43 @@ +digraph { +// This file is licensed under the MIT License (MIT) available on +// http://opensource.org/licenses/MIT. + +size=6.25; +rankdir=LR +splines = "false"; +ranksep = 0.2; +nodesep = 0.1; + +edge [ penwidth = 1.75, fontname="Sans" ] +node [ penwidth = 1.75, shape = "box", fontname="Sans", ] +graph [ penwidth = 1.75, fontname="Sans" ] + +subgraph cluster_mainchain { +block0 [ label = "1\n←Parent: 0" ]; +block1 [ label = "2\n←Parent: 1" ]; +block2 [ label = "3\n←Parent: 2" ]; + +style = "invis"; +} + +block0 -> block1 -> block2; + +block0 -> block1_1; + +block2 -> block5 [ style = "invis", minlen = 4 ]; + + +block1_1 [ label = "2 (Stale)\n←Parent: 1", style = "filled" ]; + +block5 [ label = "5 (Orphan)\n←Parent: 4", style = "filled" ]; + +subgraph cluster_toplabel { + node [ style = "invis", height = 0, width = 0, label = "" ]; + graph [ penwidth = 0 ]; + a -> b -> c -> d -> e -> f -> g [ style = "invis" ]; + label = "Orphan blocks have no known parent, so they can't be validated" +} + +label = " \nStale blocks are valid but not part of the best block chain" + +} diff --git a/img/dev/en-orphan-stale-definition.png b/img/dev/en-orphan-stale-definition.png new file mode 100644 index 00000000..f84ca701 Binary files /dev/null and b/img/dev/en-orphan-stale-definition.png differ diff --git a/img/dev/en-orphan-stale-definition.svg b/img/dev/en-orphan-stale-definition.svg new file mode 100644 index 00000000..dab784ff --- /dev/null +++ b/img/dev/en-orphan-stale-definition.svg @@ -0,0 +1,80 @@ + + + + + + +_anonymous_0 + + +Stale blocks are valid but not part of the best block chain +cluster_mainchain + +cluster_toplabel + +Orphan blocks have no known parent, so they can't be validated + + +block0 + +1 +←Parent: 0 + + +block1 + +2 +←Parent: 1 + + +block0->block1 + + + + +block1_1 + +2 (Stale) +←Parent: 1 + + +block0->block1_1 + + + + +block2 + +3 +←Parent: 2 + + +block1->block2 + + + + +block5 + +5 (Orphan) +←Parent: 4 + + + + + + + + + + + + + + + + +