From c23a311057fdd8c43ca4701b47dc1226e2579e37 Mon Sep 17 00:00:00 2001 From: mruddy Date: Fri, 23 Oct 2015 10:05:58 -0400 Subject: [PATCH] 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