Merge #618: RPC Docs: add 0.17.0

c481e8d RPC Docs: add 0.17.0 (Karel Bilek)

Pull request description:

  It's that time again :D

  Now the diff is a bit bigger (2k lines), with all the new RPC, so I won't paste it here

  https://gist.github.com/karel-3d/e859f4b43f00344c60e948988aa21849

Tree-SHA512: 19a5e7abb0e58cd3048e6409b41a92a962f544c6946d6ad8e2a3cd6aa66d9c4945200946a4ea6687fd81e20c69316378d27f91bd85fdfc696bb938453171d005

_doc/en/0.17.0/index.html

@@ -0,0 +1,8 @@
+---
+name: index
+btcversion: 0.17.0
+btcgroup: index
+permalink: en/doc/0.17.0/
+---
+
+

_doc/en/0.17.0/rpc/blockchain/getbestblockhash.html

@@ -0,0 +1,19 @@
+---
+name: getbestblockhash
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getbestblockhash/
+---
+
+getbestblockhash
+
+Returns the hash of the best (tip) block in the longest blockchain.
+
+Result:
+"hex"      (string) the block hash hex encoded
+
+Examples:
+> bitcoin-cli getbestblockhash 
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getbestblockhash", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+

_doc/en/0.17.0/rpc/blockchain/getblock.html

@@ -0,0 +1,60 @@
+---
+name: getblock
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getblock/
+---
+
+getblock "blockhash" ( verbosity ) 
+
+If verbosity is 0, returns a string that is serialized, hex-encoded data for block 'hash'.
+If verbosity is 1, returns an Object with information about block <hash>.
+If verbosity is 2, returns an Object with information about block <hash> and information about each transaction. 
+
+Arguments:
+1. "blockhash"          (string, required) The block hash
+2. verbosity              (numeric, optional, default=1) 0 for hex encoded data, 1 for a json object, and 2 for json object with transaction data
+
+Result (for verbosity = 0):
+"data"             (string) A string that is serialized, hex-encoded data for block 'hash'.
+
+Result (for verbosity = 1):
+{
+  "hash" : "hash",     (string) the block hash (same as provided)
+  "confirmations" : n,   (numeric) The number of confirmations, or -1 if the block is not on the main chain
+  "size" : n,            (numeric) The block size
+  "strippedsize" : n,    (numeric) The block size excluding witness data
+  "weight" : n           (numeric) The block weight as defined in BIP 141
+  "height" : n,          (numeric) The block height or index
+  "version" : n,         (numeric) The block version
+  "versionHex" : "00000000", (string) The block version formatted in hexadecimal
+  "merkleroot" : "xxxx", (string) The merkle root
+  "tx" : [               (array of string) The transaction ids
+     "transactionid"     (string) The transaction id
+     ,...
+  ],
+  "time" : ttt,          (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)
+  "mediantime" : ttt,    (numeric) The median block time in seconds since epoch (Jan 1 1970 GMT)
+  "nonce" : n,           (numeric) The nonce
+  "bits" : "1d00ffff", (string) The bits
+  "difficulty" : x.xxx,  (numeric) The difficulty
+  "chainwork" : "xxxx",  (string) Expected number of hashes required to produce the chain up to this block (in hex)
+  "nTx" : n,             (numeric) The number of transactions in the block.
+  "previousblockhash" : "hash",  (string) The hash of the previous block
+  "nextblockhash" : "hash"       (string) The hash of the next block
+}
+
+Result (for verbosity = 2):
+{
+  ...,                     Same output as verbosity = 1.
+  "tx" : [               (array of Objects) The transactions in the format of the getrawtransaction RPC. Different from verbosity = 1 "tx" result.
+         ,...
+  ],
+  ,...                     Same output as verbosity = 1.
+}
+
+Examples:
+> bitcoin-cli getblock "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblock", "params": ["00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+

_doc/en/0.17.0/rpc/blockchain/getblockchaininfo.html

@@ -0,0 +1,59 @@
+---
+name: getblockchaininfo
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getblockchaininfo/
+---
+
+getblockchaininfo
+Returns an object containing various state info regarding blockchain processing.
+
+Result:
+{
+  "chain": "xxxx",              (string) current network name as defined in BIP70 (main, test, regtest)
+  "blocks": xxxxxx,             (numeric) the current number of blocks processed in the server
+  "headers": xxxxxx,            (numeric) the current number of headers we have validated
+  "bestblockhash": "...",       (string) the hash of the currently best block
+  "difficulty": xxxxxx,         (numeric) the current difficulty
+  "mediantime": xxxxxx,         (numeric) median time for the current best block
+  "verificationprogress": xxxx, (numeric) estimate of verification progress [0..1]
+  "initialblockdownload": xxxx, (bool) (debug information) estimate of whether this node is in Initial Block Download mode.
+  "chainwork": "xxxx"           (string) total amount of work in active chain, in hexadecimal
+  "size_on_disk": xxxxxx,       (numeric) the estimated size of the block and undo files on disk
+  "pruned": xx,                 (boolean) if the blocks are subject to pruning
+  "pruneheight": xxxxxx,        (numeric) lowest-height complete block stored (only present if pruning is enabled)
+  "automatic_pruning": xx,      (boolean) whether automatic pruning is enabled (only present if pruning is enabled)
+  "prune_target_size": xxxxxx,  (numeric) the target size used by pruning (only present if automatic pruning is enabled)
+  "softforks": [                (array) status of softforks in progress
+     {
+        "id": "xxxx",           (string) name of softfork
+        "version": xx,          (numeric) block version
+        "reject": {             (object) progress toward rejecting pre-softfork blocks
+           "status": xx,        (boolean) true if threshold reached
+        },
+     }, ...
+  ],
+  "bip9_softforks": {           (object) status of BIP9 softforks in progress
+     "xxxx" : {                 (string) name of the softfork
+        "status": "xxxx",       (string) one of "defined", "started", "locked_in", "active", "failed"
+        "bit": xx,              (numeric) the bit (0-28) in the block version field used to signal this softfork (only for "started" status)
+        "startTime": xx,        (numeric) the minimum median time past of a block at which the bit gains its meaning
+        "timeout": xx,          (numeric) the median time past of a block at which the deployment is considered failed if not yet locked in
+        "since": xx,            (numeric) height of the first block to which the status applies
+        "statistics": {         (object) numeric statistics about BIP9 signalling for a softfork (only for "started" status)
+           "period": xx,        (numeric) the length in blocks of the BIP9 signalling period 
+           "threshold": xx,     (numeric) the number of blocks with the version bit set required to activate the feature 
+           "elapsed": xx,       (numeric) the number of blocks elapsed since the beginning of the current period 
+           "count": xx,         (numeric) the number of blocks with the version bit set in the current period 
+           "possible": xx       (boolean) returns false if there are not enough blocks left in this period to pass activation threshold 
+        }
+     }
+  }
+  "warnings" : "...",           (string) any network and blockchain warnings.
+}
+
+Examples:
+> bitcoin-cli getblockchaininfo 
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockchaininfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+

_doc/en/0.17.0/rpc/blockchain/getblockcount.html

@@ -0,0 +1,19 @@
+---
+name: getblockcount
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getblockcount/
+---
+
+getblockcount
+
+Returns the number of blocks in the longest blockchain.
+
+Result:
+n    (numeric) The current block count
+
+Examples:
+> bitcoin-cli getblockcount 
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockcount", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+

_doc/en/0.17.0/rpc/blockchain/getblockhash.html

@@ -0,0 +1,22 @@
+---
+name: getblockhash
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getblockhash/
+---
+
+getblockhash height
+
+Returns hash of block in best-block-chain at height provided.
+
+Arguments:
+1. height         (numeric, required) The height index
+
+Result:
+"hash"         (string) The block hash
+
+Examples:
+> bitcoin-cli getblockhash 1000
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockhash", "params": [1000] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+

_doc/en/0.17.0/rpc/blockchain/getblockheader.html

@@ -0,0 +1,43 @@
+---
+name: getblockheader
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getblockheader/
+---
+
+getblockheader "hash" ( verbose )
+
+If verbose is false, returns a string that is serialized, hex-encoded data for blockheader 'hash'.
+If verbose is true, returns an Object with information about blockheader <hash>.
+
+Arguments:
+1. "hash"          (string, required) The block hash
+2. verbose           (boolean, optional, default=true) true for a json object, false for the hex encoded data
+
+Result (for verbose = true):
+{
+  "hash" : "hash",     (string) the block hash (same as provided)
+  "confirmations" : n,   (numeric) The number of confirmations, or -1 if the block is not on the main chain
+  "height" : n,          (numeric) The block height or index
+  "version" : n,         (numeric) The block version
+  "versionHex" : "00000000", (string) The block version formatted in hexadecimal
+  "merkleroot" : "xxxx", (string) The merkle root
+  "time" : ttt,          (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)
+  "mediantime" : ttt,    (numeric) The median block time in seconds since epoch (Jan 1 1970 GMT)
+  "nonce" : n,           (numeric) The nonce
+  "bits" : "1d00ffff", (string) The bits
+  "difficulty" : x.xxx,  (numeric) The difficulty
+  "chainwork" : "0000...1f3"     (string) Expected number of hashes required to produce the current chain (in hex)
+  "nTx" : n,             (numeric) The number of transactions in the block.
+  "previousblockhash" : "hash",  (string) The hash of the previous block
+  "nextblockhash" : "hash",      (string) The hash of the next block
+}
+
+Result (for verbose=false):
+"data"             (string) A string that is serialized, hex-encoded data for block 'hash'.
+
+Examples:
+> bitcoin-cli getblockheader "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockheader", "params": ["00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+

_doc/en/0.17.0/rpc/blockchain/getblockstats.html

@@ -0,0 +1,66 @@
+---
+name: getblockstats
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getblockstats/
+---
+
+getblockstats hash_or_height ( stats )
+
+Compute per block statistics for a given window. All amounts are in satoshis.
+It won't work for some heights with pruning.
+It won't work without -txindex for utxo_size_inc, *fee or *feerate stats.
+
+Arguments:
+1. "hash_or_height"     (string or numeric, required) The block hash or height of the target block
+2. "stats"              (array,  optional) Values to plot, by default all values (see result below)
+    [
+      "height",         (string, optional) Selected statistic
+      "time",           (string, optional) Selected statistic
+      ,...
+    ]
+
+Result:
+{                           (json object)
+  "avgfee": xxxxx,          (numeric) Average fee in the block
+  "avgfeerate": xxxxx,      (numeric) Average feerate (in satoshis per virtual byte)
+  "avgtxsize": xxxxx,       (numeric) Average transaction size
+  "blockhash": xxxxx,       (string) The block hash (to check for potential reorgs)
+  "feerate_percentiles": [  (array of numeric) Feerates at the 10th, 25th, 50th, 75th, and 90th percentile weight unit (in satoshis per virtual byte)
+      "10th_percentile_feerate",      (numeric) The 10th percentile feerate
+      "25th_percentile_feerate",      (numeric) The 25th percentile feerate
+      "50th_percentile_feerate",      (numeric) The 50th percentile feerate
+      "75th_percentile_feerate",      (numeric) The 75th percentile feerate
+      "90th_percentile_feerate",      (numeric) The 90th percentile feerate
+  ],
+  "height": xxxxx,          (numeric) The height of the block
+  "ins": xxxxx,             (numeric) The number of inputs (excluding coinbase)
+  "maxfee": xxxxx,          (numeric) Maximum fee in the block
+  "maxfeerate": xxxxx,      (numeric) Maximum feerate (in satoshis per virtual byte)
+  "maxtxsize": xxxxx,       (numeric) Maximum transaction size
+  "medianfee": xxxxx,       (numeric) Truncated median fee in the block
+  "mediantime": xxxxx,      (numeric) The block median time past
+  "mediantxsize": xxxxx,    (numeric) Truncated median transaction size
+  "minfee": xxxxx,          (numeric) Minimum fee in the block
+  "minfeerate": xxxxx,      (numeric) Minimum feerate (in satoshis per virtual byte)
+  "mintxsize": xxxxx,       (numeric) Minimum transaction size
+  "outs": xxxxx,            (numeric) The number of outputs
+  "subsidy": xxxxx,         (numeric) The block subsidy
+  "swtotal_size": xxxxx,    (numeric) Total size of all segwit transactions
+  "swtotal_weight": xxxxx,  (numeric) Total weight of all segwit transactions divided by segwit scale factor (4)
+  "swtxs": xxxxx,           (numeric) The number of segwit transactions
+  "time": xxxxx,            (numeric) The block time
+  "total_out": xxxxx,       (numeric) Total amount in all outputs (excluding coinbase and thus reward [ie subsidy + totalfee])
+  "total_size": xxxxx,      (numeric) Total size of all non-coinbase transactions
+  "total_weight": xxxxx,    (numeric) Total weight of all non-coinbase transactions divided by segwit scale factor (4)
+  "totalfee": xxxxx,        (numeric) The fee total
+  "txs": xxxxx,             (numeric) The number of transactions (excluding coinbase)
+  "utxo_increase": xxxxx,   (numeric) The increase/decrease in the number of unspent outputs
+  "utxo_size_inc": xxxxx,   (numeric) The increase/decrease in size for the utxo index (not discounting op_return and similar)
+}
+
+Examples:
+> bitcoin-cli getblockstats 1000 '["minfeerate","avgfeerate"]'
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockstats", "params": [1000 '["minfeerate","avgfeerate"]'] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+

_doc/en/0.17.0/rpc/blockchain/getchaintips.html

@@ -0,0 +1,37 @@
+---
+name: getchaintips
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getchaintips/
+---
+
+getchaintips
+Return information about all known tips in the block tree, including the main chain as well as orphaned branches.
+
+Result:
+[
+  {
+    "height": xxxx,         (numeric) height of the chain tip
+    "hash": "xxxx",         (string) block hash of the tip
+    "branchlen": 0          (numeric) zero for main chain
+    "status": "active"      (string) "active" for the main chain
+  },
+  {
+    "height": xxxx,
+    "hash": "xxxx",
+    "branchlen": 1          (numeric) length of branch connecting the tip to the main chain
+    "status": "xxxx"        (string) status of the chain (active, valid-fork, valid-headers, headers-only, invalid)
+  }
+]
+Possible values for status:
+1.  "invalid"               This branch contains at least one invalid block
+2.  "headers-only"          Not all blocks for this branch are available, but the headers are valid
+3.  "valid-headers"         All blocks are available for this branch, but they were never fully validated
+4.  "valid-fork"            This branch is not part of the active chain, but is fully validated
+5.  "active"                This is the tip of the active main chain, which is certainly valid
+
+Examples:
+> bitcoin-cli getchaintips 
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getchaintips", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+

_doc/en/0.17.0/rpc/blockchain/getchaintxstats.html

@@ -0,0 +1,31 @@
+---
+name: getchaintxstats
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getchaintxstats/
+---
+
+getchaintxstats ( nblocks blockhash )
+
+Compute statistics about the total number and rate of transactions in the chain.
+
+Arguments:
+1. nblocks      (numeric, optional) Size of the window in number of blocks (default: one month).
+2. "blockhash"  (string, optional) The hash of the block that ends the window.
+
+Result:
+{
+  "time": xxxxx,                         (numeric) The timestamp for the final block in the window in UNIX format.
+  "txcount": xxxxx,                      (numeric) The total number of transactions in the chain up to that point.
+  "window_final_block_hash": "...",      (string) The hash of the final block in the window.
+  "window_block_count": xxxxx,           (numeric) Size of the window in number of blocks.
+  "window_tx_count": xxxxx,              (numeric) The number of transactions in the window. Only returned if "window_block_count" is > 0.
+  "window_interval": xxxxx,              (numeric) The elapsed time in the window in seconds. Only returned if "window_block_count" is > 0.
+  "txrate": x.xx,                        (numeric) The average rate of transactions per second in the window. Only returned if "window_interval" is > 0.
+}
+
+Examples:
+> bitcoin-cli getchaintxstats 
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getchaintxstats", "params": [2016] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+

_doc/en/0.17.0/rpc/blockchain/getdifficulty.html

@@ -0,0 +1,19 @@
+---
+name: getdifficulty
+btcversion: 0.17.0
+btcgroup: blockchain
+permalink: en/doc/0.17.0/rpc/blockchain/getdifficulty/
+---
+
+getdifficulty
+
+Returns the proof-of-work difficulty as a multiple of the minimum difficulty.
+
+Result:
+n.nnn       (numeric) the proof-of-work difficulty as a multiple of the minimum difficulty.
+
+Examples:
+> bitcoin-cli getdifficulty 
+> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getdifficulty", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
+
+