Difference between revisions of "Getminingcandidate"
Line 1: Line 1:
−
''getminingcandidate'' and ''getblocktemplate'' are Remote Procedure Call (RPC) programs. The RPC calls are located at an SV node and are currently managed and configured through Maestro software, though a number of software packages may perform these tasks.
+
''getminingcandidate'' or GMC is a Remote Procedure Call (RPC) available in the Bitcoin SV node software.
  
−
A node can make a request with either of the above calls for block information:
+
Its purpose is to provide mining software/pools with a suitable block candidate for hashing in order to mine a block. In addition it is greatly decoupled from block size unlike its predecessor [https://wiki.bitcoinsv.io/index.php/GetBlockTemplate_interface GetBlockTemplate], meaning it can scale and support very large block sizes.
−
* The ''getblocktemplate'' returns a full block.
 
−
* The ''getminingcandidate'' program returns the block header.
 
−
The returned data is the block candidate data for mining. It is expressed in the JSON language for data processing.
 
  
−
''getminingcandidate'' returns a mining candidate block to the node which originally requested it.  The node requests a block to mine. ''getminingcandidate'' is the program that obtains a block header to mine.
+
The way it supports blocks of very large sizes is by only providing a minimal set of data required for mining hardware to hash and generate a possible block solution. If a blocksolution is found it can be returned to the node software via the sibling RPC call ''submitminingsolution''.
  
−
The ''getminingcandidate'' program or call is a replacement for ''getblocktemplate'' program.
+
GMCs predecessor ''getblocktemplate'' gave the calling mining software more control, but in order to do this it had to provide a full and complete dataset of the current block and pending transactions in the mempool. A miner trying to mine large blocks must put a lot more strain on both the node software and RPC interface to transmit a record of every transaction that is in the mempool, often resulting in lack of memory and/or performance issues.
−
The replacement requirement arose from the need to process bigger blocks with Merkle tree paths in the block header. The Merkle tree proof in the block header allows for confirmation of transactions rather than reading the transactions as a whole. Consequently there can be more transactions within a block and more efficient external processing of the block.
 
−
 
 
−
===Block header parameters for getminingcandidate===
 
−
<table>
 
−
<tr><td>Parameter</td> <td>Description</td></tr>
 
−
<tr><td>Id</td> <td>Candidate identifier for submitminingsolution</td></tr>
 
−
<tr><td>Prevhash</td> <td>Hash of the previous block (hex string)</td></tr>
 
−
<tr><td>Coinbase</td> <td>Coinbase transaction (optional hex string encoded binary transaction)</td></tr>
 
−
<tr><td>Version</td> <td>Block version</td></tr>
 
−
<tr><td>nBits</td>
 
−
<td>Difficulty given as hex string.</td></tr>
 
−
<tr><td>Time</td> <td>Block time.</td></tr>
 
−
<tr><td>Height</td> <td>Current block height</td></tr>
 
−
<tr><td>merkleProof</td> <td>Merkle branch of the block (list of hex strings)</td></tr>
 
−
</table>
 
−
 
 
−
===Example Block Header in the json format===
 
−
{
 
−
  "id": "0d49aa74-0986-474f-a6eb-5913fbbbba02",
 
−
  "prevhash": "0000000000000000012811f570b3c0ff8cb93c44d707499dc2fcfdd611f38d93",
 
−
  "coinbaseValue": 1251906370,
 
−
  "version": 536870912,
 
−
  "nBits": "1802c73f",
 
−
  "time": 1585156824,
 
−
  "height": 627795,
 
−
  "merkleProof": [
 
−
    "f4cba40673d5573ca1aab2ee8fbd300102767561190cad7aa6211e04223ff6c3",
 
−
    "2d69511004ba72b60a10e6482491d689470b9f8527aff0f550c197d8a2446c45",
 
−
    "6eb9f4ef18f9669db60b21dc52292eba5318d684f7c476bb12da03b6d97d7c4f",
 
−
    "7a69a2fb7b132b36496501357d923ce584f913b37879a1930a10682d284bc2a9",
 
−
    "976089f04a73862fac14d2eec8b3f23aef9167f9804c40ade23c4f385cd92928",
 
−
    "73ec68c1692643e7edd22a34729f4bc8529fed48eca8ac0cd6e8b2929fb44064",
 
−
    "ee59af2b7964c1c0f48cd06b4e4e77c783711746030cc20d46a339f3d9993709",
 
−
    "6c0a33f1a1778ebec5d63172c55edb433ae365dbf7cd37bfa3535c864e9b9ea7",
 
−
    "d59744d6f3548adda90444a44eb16c56022554fdd4a0448632acd36058c96599",
 
−
    "6bd2d6dcdea8dd04345b7b706ba125ed73394be899355cb7b355d258eea20ff5",
 
−
    "3842aadab31a0e3bb5c484d58262f052afbe7f684935bf4d19ed614521e750e5",
 
−
    "91dec854c6f222b9be0cc78bd34b2405e98f34c6d2c7db8f84db6d85a83eb51e",
 
−
    "2b07dc2afdcafa3719c4ef440ef5c5f0c332efa174d23bbb72749680b36575a7"
 
−
  ]
 
−
}
 
−
 
 
−
The Maestro software handles the call to and from the SV node to the ASIC miner. The ASIC miner then performs the hashing process to discover the next suitable block to be placed on the blockchain.
 
−
 
 
−
===UML Sequence Diagram for getminingcandidate===
 
  
 +
GMC removes this issue by only providing the mining software with a merkleproof of included transactions rather than a complete listing, this lowers the amount of data to be produced and transmitted to log2(blocksize).
  
  
 +
When the node software receives a GMC request it will respond with a [https://www.json.org/json-en.html JSON] representation of the current block candidate. A description of this response body is shown below.
  
 +
===Response body of getminingcandidate===
 +
<table>
 +
<tr>
 +
<th align="center">Variable</th>
 +
<th align="center">Description</th>
 +
</tr>
 +
<tr>
 +
<td align="center">[uuid] id</td>
 +
<td align="center">The assigned id from Bitcoind. This must be provided with submitting a potential solution</td>
 +
</tr>
 +
<tr>
 +
<td align="center">[hex string] prevHash</td>
 +
<td align="center">Big Endian hash of the previous block</td>
 +
</tr>
 +
<tr>
 +
<td align="center">[hex string] Coinbase (optional)</td>
 +
<td align="center">Suggested coinbase transaction is provided. Miner is free to supply their own or alter the supplied one. Altering will require parsing and splitting the coinbase in order to splice in/out data as required.  Requires Wallet to be enabled. Only returned when provide_coinbase_tx argument is set to true. Returns error if Wallet is not enabled</td>
 +
</tr>
 +
<tr>
 +
<td align="center">[int32_t] version</td>
 +
<td align="center">The block version</td>
 +
</tr>
 +
<tr>
 +
<td align="center">[int64_t] coinbaseValue</td>
 +
<td align="center">Total funds available for the coinbase tx (in Satoshis)</td>
 +
</tr>
 +
<tr>
 +
<td align="center">[uint32_t] nBits</td>
 +
<td align="center">Compressed hexadecimal difficulty</td>
 +
</tr>
 +
<tr>
 +
<td align="center">[uint32_t] time</td>
 +
<td align="center">Current block time</td>
 +
</tr>
 +
<tr>
 +
<td align="center">[int] height</td>
 +
<td align="center">The candidate block height</td>
 +
</tr>
 +
<tr>
 +
<td align="center">[array] merkleProof</td>
 +
<td align="center">Merkle branch/path for the block, used to calculate the Merkle Root of the block candidate. This is a list of Little-Endian hex strings ordered from top to bottom</td>
 +
</tr>
 +
</table>
  
−
[[File:getmining_rpc_6.png|600px|centre|alt=UML Sequence Diagram for getminingcandidate]]
+
For a more technical breakdown of ''GetMiningCandidate'' and its implementation see the protocol spec at [https://github.com/bitcoin-sv-specs/protocol/blob/master/rpc/GetMiningCandidate.md]

Revision as of 00:14, 26 June 2020

getminingcandidate or GMC is a Remote Procedure Call (RPC) available in the Bitcoin SV node software.

Its purpose is to provide mining software/pools with a suitable block candidate for hashing in order to mine a block. In addition it is greatly decoupled from block size unlike its predecessor GetBlockTemplate, meaning it can scale and support very large block sizes.

The way it supports blocks of very large sizes is by only providing a minimal set of data required for mining hardware to hash and generate a possible block solution. If a blocksolution is found it can be returned to the node software via the sibling RPC call submitminingsolution.

GMCs predecessor getblocktemplate gave the calling mining software more control, but in order to do this it had to provide a full and complete dataset of the current block and pending transactions in the mempool. A miner trying to mine large blocks must put a lot more strain on both the node software and RPC interface to transmit a record of every transaction that is in the mempool, often resulting in lack of memory and/or performance issues.

GMC removes this issue by only providing the mining software with a merkleproof of included transactions rather than a complete listing, this lowers the amount of data to be produced and transmitted to log2(blocksize).


When the node software receives a GMC request it will respond with a JSON representation of the current block candidate. A description of this response body is shown below.

Response body of getminingcandidate

Variable Description
[uuid] id The assigned id from Bitcoind. This must be provided with submitting a potential solution
[hex string] prevHash Big Endian hash of the previous block
[hex string] Coinbase (optional) Suggested coinbase transaction is provided. Miner is free to supply their own or alter the supplied one. Altering will require parsing and splitting the coinbase in order to splice in/out data as required. Requires Wallet to be enabled. Only returned when provide_coinbase_tx argument is set to true. Returns error if Wallet is not enabled
[int32_t] version The block version
[int64_t] coinbaseValue Total funds available for the coinbase tx (in Satoshis)
[uint32_t] nBits Compressed hexadecimal difficulty
[uint32_t] time Current block time
[int] height The candidate block height
[array] merkleProof Merkle branch/path for the block, used to calculate the Merkle Root of the block candidate. This is a list of Little-Endian hex strings ordered from top to bottom

For a more technical breakdown of GetMiningCandidate and its implementation see the protocol spec at [1]

Retrieved from "https://wiki.bitcoinsv.io/index.php?title=Getminingcandidate&oldid=2522"