Actual details of GetBlockHeaders

_includes/devdoc/dash-core/rpcs/rpcs/getblockheaders.md

@@ -2,13 +2,218 @@
 This file is licensed under the MIT License (MIT) available on
 http://opensource.org/licenses/MIT.
 {% endcomment %}
-{% assign filename="_includes/devdoc/dash-core/rpcs/rpcs/getblockheaders.md" %}#
+{% assign filename="_includes/devdoc/dash-core/rpcs/rpcs/getblockheaders.md" %}
 
 ##### GetBlockHeaders
 {% include helpers/subhead-links.md %}
 
+{% assign summary_getBlockHeaders="returns an array of items with information about the requested number of blockheaders starting from the requested hash." %}
+
 {% autocrossref %}
 
-{% assign summary_getBlockHeaders= %}
+*Added in Dash Core 0.12.1*
+
+The `getblockheaders` RPC {{summary_getBlockHeaders}}
+
+*Parameter #1---header hash*
+
+{% itemplate ntpd1 %}
+- n: "Header Hash"
+  t: "string (hex)"
+  p: "Required<br>(exactly 1)"
+  d: "The hash of the block header to get, encoded as hex in RPC byte order"
+
+{% enditemplate %}
+
+*Parameter #2---number of headers to return*
+
+{% itemplate ntpd1 %}
+- n: "Count"
+  t: "number"
+  p: "Optional<br>(exactly 1)"
+  d: "The number of block headers to get"
+
+{% enditemplate %}
+
+*Parameter #3---JSON or hex output*
+
+{% itemplate ntpd1 %}
+- n: "Verbose"
+  t: "bool"
+  p: "Optional<br>(0 or 1)"
+  d: "Set to `false` to get the block headers in serialized block format; set to `true` (the default) to get the decoded block headers as a JSON object"
+
+{% enditemplate %}
+
+*Result (if format was `false`)---a serialized block header*
+
+{% itemplate ntpd1 %}
+- n: "`result`"
+  t: "array"
+  p: "Required<br>(exactly 1)"
+  d: "The requested block header(s) as a serialized block"
+
+- n: "→<br>`header`"
+  t: "string (hex)"
+  p: "Required<br>(1 or more)"
+  d: "The block header encoded as hex in RPC byte order"
+
+{% enditemplate %}
+
+*Result (if format was `true` or omitted)---a JSON block header*
+
+{% itemplate ntpd1 %}
+- n: "`result`"
+  t: "array"
+  p: "Required<br>(exactly 1)"
+  d: "An array of objects each containing a block header, or JSON `null` if an error occurred"
+
+- n: "→<br>Block Header"
+  t: "object/null"
+  p: "Required<br>(exactly 1)"
+  d: "An object containing a block header"
+
+- n: "→ →<br>`hash`"
+  t: "string (hex)"
+  p: "Required<br>(exactly 1)"
+  d: "The hash of this block's block header encoded as hex in RPC byte order.  This is the same as the hash provided in parameter #1"
+
+- n: "→ →<br>`confirmations`"
+  t: "number (int)"
+  p: "Required<br>(exactly 1)"
+  d: "The number of confirmations the transactions in this block have, starting at 1 when this block is at the tip of the best block chain.  This score will be -1 if the the block is not part of the best block chain"
+
+- n: "→ →<br>`height`"
+  t: "number (int)"
+  p: "Required<br>(exactly 1)"
+  d: "The height of this block on its block chain"
+
+- n: "→ →<br>`version`"
+  t: "number (int)"
+  p: "Required<br>(exactly 1)"
+  d: "This block's version number.  See [block version numbers][section block versions]"
+
+- n: "→ →<br>`merkleroot`"
+  t: "string (hex)"
+  p: "Required<br>(exactly 1)"
+  d: "The merkle root for this block, encoded as hex in RPC byte order"
+
+- n: "→ →<br>`time`"
+  t: "number (int)"
+  p: "Required<br>(exactly 1)"
+  d: "The time of the block"
+
+- n: "→ →<br>`mediantime`"
+  t: "number (int)"
+  p: "Required<br>(exactly 1)"
+  d: "The computed median time of the previous 11 blocks.  Used for validating transaction locktime under BIP113"
+
+- n: "→ →<br>`nonce`"
+  t: "number (int)"
+  p: "Required<br>(exactly 1)"
+  d: "The nonce which was successful at turning this particular block into one that could be added to the best block chain"
+
+- n: "→ →<br>`bits`"
+  t: "string (hex)"
+  p: "Required<br>(exactly 1)"
+  d: "The value of the *nBits* field in the block header, indicating the target threshold this block's header had to pass"
+
+- n: "→ →<br>`difficulty`"
+  t: "number (real)"
+  p: "Required<br>(exactly 1)"
+  d: "The estimated amount of work done to find this block relative to the estimated amount of work done to find block 0"
+
+- n: "→<br>`chainwork`"
+  t: "string (hex)"
+  p: "Required<br>(exactly 1)"
+  d: "The estimated number of block header hashes miners had to check from the genesis block to this block, encoded as big-endian hex"
+
+- n: "→ →<br>`previousblockhash`"
+  t: "string (hex)"
+  p: "Optional<br>(0 or 1)"
+  d: "The hash of the header of the previous block, encoded as hex in RPC byte order.  Not returned for genesis block"
+
+- n: "→ →<br>`nextblockhash`"
+  t: "string (hex)"
+  p: "Optional<br>(0 or 1)"
+  d: "The hash of the next block on the best block chain, if known, encoded as hex in RPC byte order"
+
+{% enditemplate %}
+
+*Example from Dash Core 0.12.2*
+
+Get two block headers in raw hex:
+
+{% highlight bash %}
+dash-cli -testnet getblockheaders \
+            0000000010a16c6fbc6bd5cdc238c2beabcda334e97fde1500d59be4e6fc4b89 \
+            2 false
+{% endhighlight %}
+
+Result (wrapped):
+
+{% highlight text %}
+[
+  "010000207216dc7b7c898ba3fc0b39d1fd16756b97b1e07e3eb5c64d1510a64b0000000\
+   0bb64e58a0be4276bf3e9c366bba960953ef9e47a8f62342476be56a5dfa7a2670276db\
+   59eae1001d0735577e",
+  "01000020894bfce6e49bd50015de7fe934a3cdabbec238c2cdd56bbc6f6ca1100000000\
+   0edb2a018d535de70b0622a3303dc329dcb315e7507d074c0c641501c58d88aa08576db\
+   59c5db001d03cf8986"
+]
+{% endhighlight %}
+
+Get the same two block headers in JSON:
+
+{% highlight bash %}
+dash-cli -testnet getblockheader \
+            00000000eb0af5aec7b673975a22593dc0cc763f71ba8de26292410273437078 \
+            2 true
+{% endhighlight %}
+
+Result:
+
+{% highlight json %}
+[
+  {
+    "hash": "0000000010a16c6fbc6bd5cdc238c2beabcda334e97fde1500d59be4e6fc4b89",
+    "confirmations": 20,
+    "height": 6802,
+    "version": 536870913,
+    "merkleroot": "67a2a7dfa556be762434628f7ae4f93e9560a9bb66c3e9f36b27e40b8ae564bb",
+    "time": 1507554818,
+    "mediantime": 1507554058,
+    "nonce": 2119644423,
+    "bits": "1d00e1ea",
+    "difficulty": 1.1331569664903,
+    "chainwork": "0000000000000000000000000000000000000000000000000000092c7b511197",
+    "previousblockhash": "000000004ba610154dc6b53e7ee0b1976b7516fdd1390bfca38b897c7bdc1672",
+    "nextblockhash": "000000009910885e811230c403e55aac6547d6df04ee671b2e8348524f73cab8"
+  },
+  {
+    "hash": "000000009910885e811230c403e55aac6547d6df04ee671b2e8348524f73cab8",
+    "confirmations": 19,
+    "height": 6803,
+    "version": 536870913,
+    "merkleroot": "a08ad8581c5041c6c074d007755e31cb9d32dc03332a62b070de35d518a0b2ed",
+    "time": 1507554949,
+    "mediantime": 1507554181,
+    "nonce": 2257178371,
+    "bits": "1d00dbc5",
+    "difficulty": 1.164838875953147,
+    "chainwork": "0000000000000000000000000000000000000000000000000000092da5851d38",
+    "previousblockhash": "0000000010a16c6fbc6bd5cdc238c2beabcda334e97fde1500d59be4e6fc4b89",
+    "nextblockhash": "000000004bbb3828db1c4d4491760336cec215087819ab656336f30d4095e3d2"
+  }
+]
+{% endhighlight %}
+
+*See also*
+
+* [GetBlock][rpc getblock]: {{summary_getBlock}}
+* [GetBlockHash][rpc getblockhash]: {{summary_getBlockHash}}
+* [GetBlockHashes][rpc getblockhashes]: {{summary_getBlockHashes}}
+* [GetBlockHeader][rpc getblockheader]: {{summary_getBlockHeader}}
+* [GetBestBlockHash][rpc getbestblockhash]: {{summary_getBestBlockHash}}
 
 {% endautocrossref %}

_includes/helpers/summaries.md

@@ -23,11 +23,11 @@ This file is licensed under the terms of its source texts{%endcomment%}
 {% assign summary_getAccount="returns the name of the account associated with the given address." %}
 {% assign summary_getAccountAddress="returns the current Bitcoin address for receiving payments to this account. If the account doesn't exist, it creates both the account and a new address for receiving payment.  Once a payment has been received to an address, future calls to this RPC for the same account will return a different address." %}
 {% assign summary_getAddedNodeInfo="returns information about the given added node, or all added nodes (except onetry nodes). Only nodes which have been manually added using the `addnode` RPC will have their information displayed." %}
-{% assign summary_getAddressBalance="returns the balance for address(es) (requires addressindex to be enabled)." %}
-{% assign summary_getAddressDeltas="returns all changes for an address (requires addressindex to be enabled)." %}
-{% assign summary_getAddressMempool="returns all mempool deltas for an address (requires addressindex to be enabled)." %}
-{% assign summary_getAddressTxids="returns the txids for an address(es) (requires addressindex to be enabled)" %}
-{% assign summary_getAddressUtxos="returns all unspent outputs for an address (requires addressindex to be enabled)" %}
+{% assign summary_getAddressBalance="returns the balance for address(es) (requires `addressindex` to be enabled)." %}
+{% assign summary_getAddressDeltas="returns all changes for an address (requires `addressindex` to be enabled)." %}
+{% assign summary_getAddressMempool="returns all mempool deltas for an address (requires `addressindex` to be enabled)." %}
+{% assign summary_getAddressTxids="returns the txids for an address(es) (requires `addressindex` to be enabled)" %}
+{% assign summary_getAddressUtxos="returns all unspent outputs for an address (requires `addressindex` to be enabled)" %}
 {% assign summary_getAddressesByAccount="returns a list of every address assigned to a particular account." %}
 {% assign summary_getBalance="gets the balance in decimal bitcoins across all accounts or for a particular account." %}
 {% assign summary_getBestBlockHash="returns the header hash of the most recent block on the best block chain." %}