================== Protocol Methods ================== blockchain.block.header ======================= Return the block header at the given height. **Signature** .. function:: blockchain.block.header(height, cp_height=0) .. versionadded:: 1.3 .. versionchanged:: 1.4 *cp_height* parameter added .. versionchanged:: 1.4.1 *height* The height of the block, a non-negative integer. *cp_height* Checkpoint height, a non-negative integer. Ignored if zero, otherwise the following must hold: *height* <= *cp_height* **Result** If *cp_height* is zero, the raw block header as a hexadecimal string. Otherwise a dictionary with the following keys. This provides a proof that the given header is present in the blockchain; presumably the client has the merkle root hard-coded as a checkpoint. * *branch* The merkle branch of *header* up to *root*, deepest pairing first. * *header* The raw block header as a hexadecimal string. Starting with version 1.4.1, AuxPoW data (if present in the original header) is truncated. * *root* The merkle root of all blockchain headers up to and including *cp_height*. **Example Result** With *height* 5 and *cp_height* 0 on the Bitcoin Cash chain: :: "0100000085144a84488ea88d221c8bd6c059da090e88f8a2c99690ee55dbba4e00000000e11c48fecdd9e72510ca84f023370c9a38bf91ac5cae88019bee94d24528526344c36649ffff001d1d03e477" .. _cp_height example: With *cp_height* 8:: { "branch": [ "000000004ebadb55ee9096c9a2f8880e09da59c0d68b1c228da88e48844a1485", "96cbbc84783888e4cc971ae8acf86dd3c1a419370336bb3c634c97695a8c5ac9", "965ac94082cebbcffe458075651e9cc33ce703ab0115c72d9e8b1a9906b2b636", "89e5daa6950b895190716dd26054432b564ccdc2868188ba1da76de8e1dc7591" ], "header": "0100000085144a84488ea88d221c8bd6c059da090e88f8a2c99690ee55dbba4e00000000e11c48fecdd9e72510ca84f023370c9a38bf91ac5cae88019bee94d24528526344c36649ffff001d1d03e477", "root": "e347b1c43fd9b5415bf0d92708db8284b78daf4d0e24f9c3405f45feb85e25db" } blockchain.block.headers ======================== Return a concatenated chunk of block headers from the main chain. **Signature** .. function:: blockchain.block.headers(start_height, count, cp_height=0) .. versionadded:: 1.2 .. versionchanged:: 1.4 *cp_height* parameter added .. versionchanged:: 1.4.1 *start_height* The height of the first header requested, a non-negative integer. *count* The number of headers requested, a non-negative integer. *cp_height* Checkpoint height, a non-negative integer. Ignored if zero, otherwise the following must hold: *start_height* + (*count* - 1) <= *cp_height* **Result** A dictionary with the following members: * *count* The number of headers returned, between zero and the number requested. If the chain has not extended sufficiently far, only the available headers will be returned. If more headers than *max* were requested at most *max* will be returned. * *hex* The binary block headers concatenated together in-order as a hexadecimal string. Starting with version 1.4.1, AuxPoW data (if present in the original header) is truncated if *cp_height* is nonzero. * *max* The maximum number of headers the server will return in a single request. (Recommended to be at least one difficulty retarget period, i.e. 2016) The dictionary additionally has the following keys if *count* and *cp_height* are not zero. This provides a proof that all the given headers are present in the blockchain; presumably the client has the merkle root hard-coded as a checkpoint. * *root* The merkle root of all blockchain headers up to and including *cp_height*. * *branch* The merkle branch of the last returned header up to *root*, deepest pairing first. **Example Response** See :ref:`here ` for an example of *root* and *branch* keys. :: { "count": 2, "hex": "0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299" "max": 2016 } blockchain.estimatefee ====================== Return the estimated transaction fee per kilobyte for a transaction to be confirmed within a certain number of blocks. **Signature** .. function:: blockchain.estimatefee(number) *number* The number of blocks to target for confirmation. **Result** The estimated transaction fee in coin units per kilobyte, as a floating point number. If the daemon does not have enough information to make an estimate, the integer ``-1`` is returned. **Example Result** :: 0.00101079 blockchain.headers.subscribe ============================ Subscribe to receive block headers when a new block is found. **Signature** .. function:: blockchain.headers.subscribe() **Result** The header of the current block chain tip. The result is a dictionary with two members: * *hex* The binary header as a hexadecimal string. * *height* The height of the header, an integer. **Example Result** :: { "height": 520481, "hex": "00000020890208a0ae3a3892aa047c5468725846577cfcd9b512b50000000000000000005dc2b02f2d297a9064ee103036c14d678f9afc7e3d9409cf53fd58b82e938e8ecbeca05a2d2103188ce804c4" } **Notifications** As this is a subscription, the client will receive a notification when a new block is found. The notification's signature is: .. function:: blockchain.headers.subscribe(header) :noindex: * *header* See **Result** above. .. note:: should a new block arrive quickly, perhaps while the server is still processing prior blocks, the server may only notify of the most recent chain tip. The protocol does not guarantee notification of all intermediate block headers. In a similar way the client must be prepared to handle chain reorganisations. Should a re-org happen the new chain tip will not sit directly on top of the prior chain tip. The client must be able to figure out the common ancestor block and request any missing block headers to acquire a consistent view of the chain state. blockchain.relayfee =================== Return the minimum fee a low-priority transaction must pay in order to be accepted to the daemon's memory pool. **Signature** .. function:: blockchain.relayfee() **Result** The fee in whole coin units (BTC, not satoshis for Bitcoin) as a floating point number. **Example Results** :: 1e-05 :: 0.0 blockchain.scripthash.get_balance ================================= Return the confirmed and unconfirmed balances of a :ref:`script hash