From 4b7967bf63022036cf7dfc8f353c3c5dfa817f68 Mon Sep 17 00:00:00 2001
From: Mike C <micro-machine@users.noreply.github.com>
Date: Wed, 9 Mar 2016 23:19:30 -0700
Subject: [PATCH] block header methods w/ examples.
---
knowledge-base/developer-guides/daemon-rpc.md | 137 ++++++++++++++++++
1 file changed, 137 insertions(+)
diff --git a/knowledge-base/developer-guides/daemon-rpc.md b/knowledge-base/developer-guides/daemon-rpc.md
index 00f7ca39..a2099ad1 100644
--- a/knowledge-base/developer-guides/daemon-rpc.md
+++ b/knowledge-base/developer-guides/daemon-rpc.md
@@ -39,12 +39,149 @@ Some methods include parameters, while others do not. Examples of each JSON RPC
### submitblock
+
### getlastblockheader
+Block header information for the most recent block is easily retrieved with this method. No inputs are needed.
+
+Outputs:
+
+* *block_header* - A structure containing block header information.
+ * *depth* - The number of blocks succeeding this block on the blockchain. A larger number means an older block.
+ * *difficulty* - The strength of the Monero network based on mining power.
+ * *hash* - The hash of this block.
+ * *height* - The number of blocks preceding this block on the blockchain.
+ * *major_version* - The major version of the monero protocol at this block height.
+ * *minor_version* - The minor version of the monero protocol at this block height.
+ * *nonce* - a cryptographic random one-time number used in mining a Monero block.
+ * *orphan_status* - Usually `false`. If `true`, this block is not part of the longest chain.
+ * *prev_hash* - The hash of the block immediately preceding this block in the chain.
+ * *reward* - The amount of new atomic units generated in this block and rewarded to the miner. Note: 1 XMR = 1e12 atomic units.
+ * *timestamp* - The time the block was recorded into the blockchain.
+
+In this example, the most recent block (990793 at the time) is returned:
+
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18081/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"getlastblockheader"}' -H 'Content-Type: application/json'
+{
+ "id": "0",
+ "jsonrpc": "2.0",
+ "result": {
+ "block_header": {
+ "depth": 0,
+ "difficulty": 746963928,
+ "hash": "ac0f1e226268d45c99a16202fdcb730d8f7b36ea5e5b4a565b1ba1a8fc252eb0",
+ "height": 990793,
+ "major_version": 1,
+ "minor_version": 1,
+ "nonce": 1550,
+ "orphan_status": false,
+ "prev_hash": "386575e3b0b004ed8d458dbd31bff0fe37b280339937f971e06df33f8589b75c",
+ "reward": 6856609225169,
+ "timestamp": 1457589942
+ },
+ "status": "OK"
+ }
+}
+
+
### getblockheaderbyhash
+Block header information can be retrieved using either a block's hash or height. This method includes a block's hash as an input parameter to retrieve basic information about the block.
+
+Inputs:
+
+* *hash* - The block's sha256 hash.
+
+Outputs:
+
+* *block_header* - A structure containing block header information.
+ * *depth* - The number of blocks succeeding this block on the blockchain. A larger number means an older block.
+ * *difficulty* - The strength of the Monero network based on mining power.
+ * *hash* - The hash of this block.
+ * *height* - The number of blocks preceding this block on the blockchain.
+ * *major_version* - The major version of the monero protocol at this block height.
+ * *minor_version* - The minor version of the monero protocol at this block height.
+ * *nonce* - a cryptographic random one-time number used in mining a Monero block.
+ * *orphan_status* - Usually `false`. If `true`, this block is not part of the longest chain.
+ * *prev_hash* - The hash of the block immediately preceding this block in the chain.
+ * *reward* - The amount of new atomic units generated in this block and rewarded to the miner. Note: 1 XMR = 1e12 atomic units.
+ * *timestamp* - The time the block was recorded into the blockchain.
+
+In this example, block 912345 is looked up by its hash:
+
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18081/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"getblockheaderbyhash","params":{"hash":"e22cf75f39ae720e8b71b3d120a5ac03f0db50bba6379e2850975b4859190bc6"}}' -H 'Content-Type: application/json'
+{
+ "id": "0",
+ "jsonrpc": "2.0",
+ "result": {
+ "block_header": {
+ "depth": 78376,
+ "difficulty": 815625611,
+ "hash": "e22cf75f39ae720e8b71b3d120a5ac03f0db50bba6379e2850975b4859190bc6",
+ "height": 912345,
+ "major_version": 1,
+ "minor_version": 2,
+ "nonce": 1646,
+ "orphan_status": false,
+ "prev_hash": "b61c58b2e0be53fad5ef9d9731a55e8a81d972b8d90ed07c04fd37ca6403ff78",
+ "reward": 7388968946286,
+ "timestamp": 1452793716
+ },
+ "status": "OK"
+ }
+}
+
+
### getblockheaderbyheight
+Similar to `getblockheaderbyhash` above, this method includes a block's height as an input parameter to retrieve basic information about the block.
+
+Inputs:
+
+* *height* - The block's height.
+
+Outputs:
+
+* *block_header* - A structure containing block header information.
+ * *depth* - The number of blocks succeeding this block on the blockchain. A larger number means an older block.
+ * *difficulty* - The strength of the Monero network based on mining power.
+ * *hash* - The hash of this block.
+ * *height* - The number of blocks preceding this block on the blockchain.
+ * *major_version* - The major version of the monero protocol at this block height.
+ * *minor_version* - The minor version of the monero protocol at this block height.
+ * *nonce* - a cryptographic random one-time number used in mining a Monero block.
+ * *orphan_status* - Usually `false`. If `true`, this block is not part of the longest chain.
+ * *prev_hash* - The hash of the block immediately preceding this block in the chain.
+ * *reward* - The amount of new atomic units generated in this block and rewarded to the miner. Note: 1 XMR = 1e12 atomic units.
+ * *timestamp* - The time the block was recorded into the blockchain.
+
+In this example, block 912345 is looked up by its height (notice that the returned information is the save as in the previous example):
+
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18081/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"getblockheaderbyheight","params":{"height":912345}}' -H 'Content-Type: application/json'
+{
+ "id": "0",
+ "jsonrpc": "2.0",
+ "result": {
+ "block_header": {
+ "depth": 78376,
+ "difficulty": 815625611,
+ "hash": "e22cf75f39ae720e8b71b3d120a5ac03f0db50bba6379e2850975b4859190bc6",
+ "height": 912345,
+ "major_version": 1,
+ "minor_version": 2,
+ "nonce": 1646,
+ "orphan_status": false,
+ "prev_hash": "b61c58b2e0be53fad5ef9d9731a55e8a81d972b8d90ed07c04fd37ca6403ff78",
+ "reward": 7388968946286,
+ "timestamp": 1452793716
+ },
+ "status": "OK"
+ }
+}
+
### getblock
### get_connections