From f1902f360bc2c216cb8e502962709b306c9bf4dd Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Fri, 23 Oct 2015 10:03:09 -0400 Subject: [PATCH 1/3] Dev Docs: drop mention of endianness in hash byte order Closes #1061 Closes #1102 --- _includes/devdoc/bitcoin-core/api-intro.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/_includes/devdoc/bitcoin-core/api-intro.md b/_includes/devdoc/bitcoin-core/api-intro.md index 4e30a8d7..083458fb 100644 --- a/_includes/devdoc/bitcoin-core/api-intro.md +++ b/_includes/devdoc/bitcoin-core/api-intro.md @@ -43,20 +43,13 @@ target. Whatever the reason for reversing header hashes, the reversal also extends to other hashes used in RPCs, such as TXIDs and merkle roots. -Off-site documentation such as the Bitcoin Wiki tends to use the terms -big endian and little endian as shown in the table below, but they -aren't always consistent. Worse, these two different ways of -representing a hash digest can confuse anyone who looks at the Bitcoin -Core source code and finds a so-called "big endian" value being stored -in a little-endian data type. - As header hashes and TXIDs are widely used as global identifiers in other Bitcoin software, this reversal of hashes has become the standard way to refer to certain objects. The table below should make clear where each byte order is used. |---------------+---------------------|-----------------| -| Data | Internal Byte Order ("Big Endian") | RPC Byte Order ("Little Endian") | +| Data | Internal Byte Order | RPC Byte Order | |---------------|---------------------|-----------------| | Example: SHA256(SHA256(0x00)) | Hash: 1406...539a | Hash: 9a53...0614 | |---------------|---------------------|-----------------| From 666ed019740e994add4315e27a9e1ceb1e6b85a3 Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Mon, 26 Oct 2015 12:07:23 -0400 Subject: [PATCH 2/3] Dev Docs: update v4 blocks text; mention version bits Closes #1106 --- _includes/devdoc/ref_block_chain.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/_includes/devdoc/ref_block_chain.md b/_includes/devdoc/ref_block_chain.md index 23f6b555..b53341c5 100644 --- a/_includes/devdoc/ref_block_chain.md +++ b/_includes/devdoc/ref_block_chain.md @@ -72,17 +72,21 @@ fe9f0864 ........................... Nonce encoding had previously been non-standard since Bitcoin Core 0.8.0 (February 2012). -* **Version 4** blocks will likely be introduced in the near-future as - specified in draft BIP62. Possible changes include: +* **Version 4** blocks will likely be introduced in the near future as + specified in BIP65. These blocks will support the new + `OP_CHECKLOCKTIMEVERIFY` opcode described in that BIP. - * Reject version 4 blocks that include any version 2 transactions - that don't adhere to any of the version 2 transaction rules. - These rules are not yet described in this documentation; see - BIP62 for details. +The mechanism used for the version 2, 3, and 4 upgrades is commonly +called IsSuperMajority() after the function added to Bitcoin Core to +manage those soft forking changes. See BIP34 for a full description of +this method. - * A soft fork rollout of version 4 blocks identical to the rollout - used for version 3 blocks (described briefly in BIP62 and in more - detail in BIP34). +As of this writing, a newer method called *version bits* is being designed +to manage future soft forking changes, although it's not known whether +version 4 will be the last soft fork to use the IsSuperMajority() +function. Draft BIP9 describes the version bits design as of this +writing, although it is still being actively edited and may +substantially change while in the draft state. {% endautocrossref %} From c23a311057fdd8c43ca4701b47dc1226e2579e37 Mon Sep 17 00:00:00 2001 From: mruddy Date: Fri, 23 Oct 2015 10:05:58 -0400 Subject: [PATCH 3/3] Dev docs: byte ordering and endian clarifications Cherry picked and edited from: 9f1885beae3e1f32b2072be2501fb5d6154ee3d8 --- _includes/devdoc/bitcoin-core/api-intro.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/_includes/devdoc/bitcoin-core/api-intro.md b/_includes/devdoc/bitcoin-core/api-intro.md index 083458fb..2c93275c 100644 --- a/_includes/devdoc/bitcoin-core/api-intro.md +++ b/_includes/devdoc/bitcoin-core/api-intro.md @@ -12,23 +12,23 @@ http://opensource.org/licenses/MIT. {% autocrossref %} -Bitcoin Core RPCs accept and return hashes in the reverse of their -normal byte order. For example, the Unix `sha256sum` command would display the -SHA256(SHA256()) hash of mainnet block 300,000's header as the -following string: +Bitcoin Core RPCs accept and return the byte-wise reverse of computed +SHA-256 hash values. For example, the Unix `sha256sum` command displays the +SHA256(SHA256()) hash of mainnet block 300,000's header as: + > /bin/echo -n '020000007ef055e1674d2e6551dba41cd214debbee34aeb544c7ec670000000000000000d3998963f80c5bab43fe8c26228e98d030edf4dcbe48a666f5c39e2d7a885c9102c86d536c890019593a470d' | xxd -r -p | sha256sum -b | xxd -r -p | sha256sum -b 5472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc820000000000000000 -The string above is also how the hash appears in the +The result above is also how the hash appears in the previous-header-hash part of block 300,001's header: 
020000005472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc82000\
 0000000000000ab0aaa377ca3f49b1545e2ae6b0667a08f42e72d8c24ae\
 237140e28f14f3bb7c6bcc6d536c890019edd83ccf
-However Bitcoin RPCs use the reverse byte order for hashes, so if you +However, Bitcoin Core's RPCs use the byte-wise reverse for hashes, so if you want to get information about block 300,000 using the `getblock` RPC, -you need to reverse the byte order: +you need to reverse the requested hash: > bitcoin-cli getblock \ 000000000000000082ccf8f1557c5d40b21edabb18d2d691cfbf87118bac7254 @@ -37,7 +37,7 @@ you need to reverse the byte order: data, which is why the reversed string looks somewhat mangled.) The rationale for the reversal is unknown, but it likely stems from -Bitcoin's use of hash digests (which are byte arrays in C++) as integers +Bitcoin Core's use of hashes (which are byte arrays in C++) as integers for the purpose of determining whether the hash is below the network target. Whatever the reason for reversing header hashes, the reversal also extends to other hashes used in RPCs, such as TXIDs and merkle