diff --git a/_includes/guide_intro.md b/_includes/guide_intro.md index 90663ee4..cd99ac8d 100644 --- a/_includes/guide_intro.md +++ b/_includes/guide_intro.md @@ -6,7 +6,8 @@ http://opensource.org/licenses/MIT. {% autocrossref %} The Developer Guide aims to provide the information you need to understand -Bitcoin and start building Bitcoin-based applications. To make the best use of +Bitcoin and start building Bitcoin-based applications, but it is [not a +specification][]. To make the best use of this documentation, you may want to install the current version of Bitcoin Core, either from [source][core git] or from a [pre-compiled executable][core executable]. diff --git a/_includes/guide_p2p_network.md b/_includes/guide_p2p_network.md index 62f04841..c4a0a801 100644 --- a/_includes/guide_p2p_network.md +++ b/_includes/guide_p2p_network.md @@ -226,6 +226,7 @@ These messages are aggressively broadcast using the `alert` message, being sent These messages are signed by a specific ECDSA private key that only a small number of developers control. -**Resource:** More details about the structure of messages and a complete list of message types can be found at the [Protocol Specification](https://en.bitcoin.it/wiki/Protocol_specification) page of the Bitcoin Wiki. +**Resource:** More details about the structure of messages and a complete list of message types can be found in +the [P2P reference section][section P2P reference]. {% endautocrossref %} diff --git a/_includes/ref_intro.md b/_includes/ref_intro.md index 150a1195..16cbc8ae 100644 --- a/_includes/ref_intro.md +++ b/_includes/ref_intro.md @@ -5,8 +5,9 @@ http://opensource.org/licenses/MIT. {% autocrossref %} -The Developer Reference aims to provide specifications and API information -to help you start building Bitcoin-based applications. To make the best use of +The Developer Reference aims to provide technical details and API information +to help you start building Bitcoin-based applications, but it is [not a +specification][]. To make the best use of this documentation, you may want to install the current version of Bitcoin Core, either from [source][core git] or from a [pre-compiled executable][core executable]. @@ -23,3 +24,43 @@ links will be shown in blue. If you hover over a cross-reference link, a brief definition of the term will be displayed in a tooltip. {% endautocrossref %} + +#### Not A Specification +{:.no_toc} + +{% autocrossref %} + +The Bitcoin.org Developer Documentation describes how Bitcoin works to +help educate new Bitcoin developers, but it is not a specification---and +it never will be. + +Bitcoin security depends on consensus. Should your program diverge from +consensus, its security is weakened or destroyed. The cause of the +divergence doesn't matter: it could be a bug in your program, it could +be an [error in this documentation][errors in docs] which you +implemented as described, or it could be you do everything right but the +majority software on the network [behaves unexpectedly][v0.8 chain +fork]. The specific cause will not matter to the users of your software +whose wealth is lost. + +The only correct specification of consensus behavior is the actual +program behavior of the majority software on the network. As that +behavior is subject to arbitrary inputs in a large variety +of unique environments, it cannot ever be fully documented here or +anywhere else. + +However, the Bitcoin Core developers are working on making their +consensus code portable so other implementations can use it. Bitcoin +Core 0.10 will provide `libbitcoinconsensus`, a first attempt at +exporting some consensus code. Future versions of Bitcoin Core will +likely provide consensus code that is more complete, more portable, and +more consistent in diverse environments. + +In addition, we also warn you that this documentation has not been +extensively reviewed by Bitcoin experts and so likely contains numerous +errors. At the bottom of the menu on the left, you will find links that +allow you to report an issue or to edit the documentation on GitHub. +Please use those links if you find any errors or important missing +information. + +{% endautocrossref %} diff --git a/_includes/ref_p2p_networking.md b/_includes/ref_p2p_networking.md index 27c688b9..88d99aee 100644 --- a/_includes/ref_p2p_networking.md +++ b/_includes/ref_p2p_networking.md @@ -9,8 +9,8 @@ http://opensource.org/licenses/MIT. {% autocrossref %} -This section describes the Bitcoin P2P network protocol (but it is not a -specification). It does not describe the discontinued direct [IP-to-IP +This section describes the Bitcoin P2P network protocol (but it is [not a +specification][]). It does not describe the discontinued direct [IP-to-IP payment protocol][], the [BIP70 payment protocol][payment protocol], the [GetBlockTemplate mining protocol][section getblocktemplate], or any network protocol never implemented in an official version of Bitcoin Core. diff --git a/_includes/references.md b/_includes/references.md index 47e2f9d5..b16dbc3e 100644 --- a/_includes/references.md +++ b/_includes/references.md @@ -300,6 +300,7 @@ http://opensource.org/licenses/MIT. [locktime parsing rules]: /en/developer-guide#locktime_parsing_rules [Merge Avoidance subsection]: /en/developer-guide#merge-avoidance [micropayment channel]: /en/developer-guide#term-micropayment-channel +[not a specification]: /en/developer-reference#not-a-specification [raw transaction format]: /en/developer-reference#raw-transaction-format [RPC]: /en/developer-reference#remote-procedure-calls-rpcs [RPCs]: /en/developer-reference#remote-procedure-calls-rpcs @@ -309,12 +310,14 @@ http://opensource.org/licenses/MIT. [section hash byte order]: /en/developer-reference#hash-byte-order [section merkle trees]: /en/developer-reference#merkle-trees [section merkleblock example]: /en/developer-examples#parsing-a-merkleblock +[section p2p reference]: /en/developer-reference#p2p-network [section protocol versions]: /en/developer-reference#protocol-versions [section serialized blocks]: /en/developer-reference#serialized-blocks [section simple raw transaction]: /en/developer-examples#simple-raw-transaction [section verifying payment]: /en/developer-guide#verifying-payment [signature script modification warning]: /en/developer-reference#signature_script_modification_warning [transaction object format]: /en/developer-reference#term-transaction-object-format +[v0.8 chain fork]: /en/alert/2013-03-11-chain-fork [Verification subsection]: /en/developer-guide#verifying-payment [X509Certificates]: /en/developer-examples#term-x509certificates @@ -371,6 +374,7 @@ http://opensource.org/licenses/MIT. [ECDSA]: https://en.wikipedia.org/wiki/Elliptic_Curve_DSA [Electrum server]: https://github.com/spesmilo/electrum-server [Eloipool]: https://gitorious.org/bitcoin/eloipool +[errors in docs]: https://github.com/bitcoin/bitcoin.org/issues?q=is%3Aissue+label%3A%22Dev+Docs%22 [forum tech support]: https://bitcointalk.org/index.php?board=4.0 [high-speed block relay network]: https://www.mail-archive.com/bitcoin-development@lists.sourceforge.net/msg03189.html [HMAC-SHA512]: https://en.wikipedia.org/wiki/HMAC diff --git a/en/developer-documentation.md b/en/developer-documentation.md index ee0c5697..7ea5c3cf 100644 --- a/en/developer-documentation.md +++ b/en/developer-documentation.md @@ -14,7 +14,7 @@ title: "Developer Documentation - Bitcoin"
Find technical specifications and API documentation.
+Find technical details and API documentation.