From 2312aa10fd4dcf288e55bd8c9d759bcacc0434f4 Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Tue, 27 Jan 2015 18:39:30 -0500 Subject: [PATCH] Dev Docs: Merge RPC and RPC Intro This commit merges the RPC introduction section (h4), "JSON-RPC & bitcoin-cli" into the currently-empty RPC section (h3). To do this, it splits the contents of the file `_includes/ref_core_rpc_intro.md` into the new files `_includes/ref/bitcoin-core/api-intro.md` and `_includes/ref/bitcoin-core/rpcs/intro.md` --- _includes/ref/bitcoin-core/api-intro.md | 98 +++++++++++++++++++ .../bitcoin-core/rpcs/intro.md} | 98 +------------------ en/developer-reference.md | 4 +- 3 files changed, 102 insertions(+), 98 deletions(-) create mode 100644 _includes/ref/bitcoin-core/api-intro.md rename _includes/{ref_core_rpc_intro.md => ref/bitcoin-core/rpcs/intro.md} (61%) diff --git a/_includes/ref/bitcoin-core/api-intro.md b/_includes/ref/bitcoin-core/api-intro.md new file mode 100644 index 00000000..a9befa41 --- /dev/null +++ b/_includes/ref/bitcoin-core/api-intro.md @@ -0,0 +1,98 @@ +{% comment %} +This file is licensed under the MIT License (MIT) available on +http://opensource.org/licenses/MIT. +{% endcomment %} +{% assign filename="_includes/ref/bitcoin-core/api-intro.md" %} + +## Bitcoin Core APIs +{% include helpers/subhead-links.md %} + +### Hash Byte Order +{% include helpers/subhead-links.md %} + +{% 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: + + 5472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc820000000000000000 + +The string 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 +want to get information about block 300,000 using the `getblock` RPC, +you need to reverse the byte order: + + > bitcoin-cli getblock \ + 000000000000000082ccf8f1557c5d40b21edabb18d2d691cfbf87118bac7254 + +(Note: hex representation uses two characters to display each byte of +data, which is why the reversed string looks somewhat mangled.) + +The rational for the reversal is unknown, but it likely stems from +Bitcoin's use of hash digests (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 +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") | +|---------------|---------------------|-----------------| +| Example: SHA256(SHA256(0x00)) | Hash: 1406...539a | Hash: 9a53...0614 | +|---------------|---------------------|-----------------| +| Header Hashes: SHA256(SHA256(block header)) | Used when constructing block headers | Used by RPCs such as `getblock`; widely used in block explorers | +|---------------|---------------------|-----------------| +| Merkle Roots: SHA256(SHA256(TXIDs and merkle rows)) | Used when constructing block headers | Returned by RPCs such as `getblock` | +|---------------|---------------------|-----------------| +| TXIDs: SHA256(SHA256(transaction)) | Used in transaction inputs | Used by RPCs such as `gettransaction` and transaction data parts of `getblock`; widely used in wallet programs | +|---------------|---------------------|-----------------| +| P2PKH Hashes: RIPEMD160(SHA256(pubkey)) | Used in both addresses and pubkey scripts | **N/A:** RPCs use addresses which use internal byte order | +|---------------|---------------------|-----------------| +| P2SH Hashes: RIPEMD160(SHA256(redeem script)) | Used in both addresses and pubkey scripts | **N/A:** RPCs use addresses which use internal byte order | +|---------------|---------------------|-----------------| + +Note: RPCs which return raw results, such as `getrawtransaction` or the +raw mode of `getblock`, always display hashes as they appear in blocks +(internal byte order). + +The code below may help you check byte order by generating hashes +from raw hex. +{% endautocrossref %} + +{% highlight python %} +#!/usr/bin/env python + +from sys import byteorder +from hashlib import sha256 + +## You can put in $data an 80-byte block header to get its header hash, +## or a raw transaction to get its txid +data = "00".decode("hex") +hash = sha256(sha256(data).digest()).digest() + +print "Warning: this code only tested on a little-endian x86_64 arch" +print +print "System byte order:", byteorder +print "Internal-Byte-Order Hash: ", hash.encode('hex_codec') +print "RPC-Byte-Order Hash: ", hash[::-1].encode('hex_codec') +{% endhighlight %} diff --git a/_includes/ref_core_rpc_intro.md b/_includes/ref/bitcoin-core/rpcs/intro.md similarity index 61% rename from _includes/ref_core_rpc_intro.md rename to _includes/ref/bitcoin-core/rpcs/intro.md index 997e4c35..4b891761 100644 --- a/_includes/ref_core_rpc_intro.md +++ b/_includes/ref/bitcoin-core/rpcs/intro.md @@ -2,105 +2,9 @@ This file is licensed under the MIT License (MIT) available on http://opensource.org/licenses/MIT. {% endcomment %} -{% assign filename="_includes/ref_core_rpc_intro.md" %} - -## Bitcoin Core APIs -{% include helpers/subhead-links.md %} - -### Hash Byte Order -{% include helpers/subhead-links.md %} - -{% 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: - - 5472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc820000000000000000 - -The string 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 -want to get information about block 300,000 using the `getblock` RPC, -you need to reverse the byte order: - - > bitcoin-cli getblock \ - 000000000000000082ccf8f1557c5d40b21edabb18d2d691cfbf87118bac7254 - -(Note: hex representation uses two characters to display each byte of -data, which is why the reversed string looks somewhat mangled.) - -The rational for the reversal is unknown, but it likely stems from -Bitcoin's use of hash digests (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 -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") | -|---------------|---------------------|-----------------| -| Example: SHA256(SHA256(0x00)) | Hash: 1406...539a | Hash: 9a53...0614 | -|---------------|---------------------|-----------------| -| Header Hashes: SHA256(SHA256(block header)) | Used when constructing block headers | Used by RPCs such as `getblock`; widely used in block explorers | -|---------------|---------------------|-----------------| -| Merkle Roots: SHA256(SHA256(TXIDs and merkle rows)) | Used when constructing block headers | Returned by RPCs such as `getblock` | -|---------------|---------------------|-----------------| -| TXIDs: SHA256(SHA256(transaction)) | Used in transaction inputs | Used by RPCs such as `gettransaction` and transaction data parts of `getblock`; widely used in wallet programs | -|---------------|---------------------|-----------------| -| P2PKH Hashes: RIPEMD160(SHA256(pubkey)) | Used in both addresses and pubkey scripts | **N/A:** RPCs use addresses which use internal byte order | -|---------------|---------------------|-----------------| -| P2SH Hashes: RIPEMD160(SHA256(redeem script)) | Used in both addresses and pubkey scripts | **N/A:** RPCs use addresses which use internal byte order | -|---------------|---------------------|-----------------| - -Note: RPCs which return raw results, such as `getrawtransaction` or the -raw mode of `getblock`, always display hashes as they appear in blocks -(internal byte order). - -The code below may help you check byte order by generating hashes -from raw hex. -{% endautocrossref %} - -{% highlight python %} -#!/usr/bin/env python - -from sys import byteorder -from hashlib import sha256 - -## You can put in $data an 80-byte block header to get its header hash, -## or a raw transaction to get its txid -data = "00".decode("hex") -hash = sha256(sha256(data).digest()).digest() - -print "Warning: this code only tested on a little-endian x86_64 arch" -print -print "System byte order:", byteorder -print "Internal-Byte-Order Hash: ", hash.encode('hex_codec') -print "RPC-Byte-Order Hash: ", hash[::-1].encode('hex_codec') -{% endhighlight %} +{% assign filename="_includes/ref/bitcoin-core/rpcs/intro.md" %} ### Remote Procedure Calls (RPCs) - - -#### JSON-RPC & bitcoin-cli {% include helpers/subhead-links.md %} {% autocrossref %} diff --git a/en/developer-reference.md b/en/developer-reference.md index dc542405..f1709ca9 100644 --- a/en/developer-reference.md +++ b/en/developer-reference.md @@ -38,7 +38,9 @@ title: "Developer Reference - Bitcoin" {% include ref_p2p_networking.md %} -{% include ref_core_rpc_intro.md %} +{% include ref/bitcoin-core/api-intro.md %} + +{% include ref/bitcoin-core/rpcs/intro.md %} {% include ref/bitcoin-core/rpcs/quick-ref.md %}