0023 - Final - Standards - Feb. 28, 2012
BIP: 23 Layer: API/RPC Title: getblocktemplate - Pooled Mining Author: Luke Dashjr <[email protected]> Comments-Summary: No comments yet. Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0023 Status: Final Type: Standards Track Created: 2012-02-28 License: BSD-2-Clause
This BIP describes extensions to the getblocktemplate JSON-RPC call to enhance pooled mining.
This BIP is licensed under the BSD 2-clause license.
Note that all sections of this specification are optional extensions on top of [[bip-0022.mediawiki|BIP 22]].
Something can be said to have BIP 23 Level 1 support if it implements at least:
It can be said to have BIP 23 Level 2 support if it also implements:
| template request | ||
|---|---|---|
| Key | Type | Description |
| target | String | desired target for block template (may be ignored) |
| template | ||
|---|---|---|
| Key | Type | Description |
| expires | Number | how many seconds (beginning from when the server sent the response) this work is valid for, at most |
| target | String | the number which valid results must be less than, in big-endian hexadecimal |
Servers may indicate support for proposing blocks by including a capability string in their original template:
| template | ||
|---|---|---|
| Key | Type | Description |
| capabilities | Array of Strings | MAY contain "proposal" to indicate support for block proposal |
| reject-reason | String | Reason the proposal was invalid as-is (only applicable in response to proposals) |
If supported, a miner MAY propose a block to the server for general validation at any point before the job expires. This is accomplished by calling getblocktemplate with two keys:
| getblocktemplate parameters | ||
|---|---|---|
| Key | Type | Description |
| data | String | MUST be hex-encoded block data |
| mode | String | MUST be "proposal" |
| workid | String | if the server provided a workid, it MUST be included with proposals |
The block data MUST be validated and checked against the server's usual acceptance rules (excluding the check for a valid proof-of-work). If it is found to be in violation of any of these rules, the server MUST return one of the following:
It is RECOMMENDED that servers which merely need to track the proposed block for later share/* submissions, return a simple Object of the form:
{"workid":"new workid"}
Clients SHOULD assume their proposed block will remain valid if the only changes they make are to the portion of the coinbase scriptSig they themselves provided (if any) and the time header. Servers SHOULD NOT break this assumption without good cause.
| template request | ||
|---|---|---|
| Key | Type | Description |
| nonces | Number | size of nonce range the miner needs; if not provided, the server SHOULD assume the client requires 232 |
| template | ||
|---|---|---|
| Key | Type | Description |
| maxtime | Number | the maximum time allowed |
| maxtimeoff | Number | the maximum time allowed (as a moving offset from "curtime" - every second, the actual maxtime is incremented by 1; for example, "maxtimeoff":0 means "time" may be incremented by 1 every second) |
| mintime | Number | the minimum time allowed |
| mintimeoff | Number | the minimum time allowed (as a moving offset from "curtime") |
| mutable | Array of Strings | different manipulations that the server explicitly allows to be made |
| noncerange | String | two 32-bit integers, concatenated in big-endian hexadecimal, which represent the valid ranges of nonces the miner may scan |
If the block template contains a "mutable" key, it is a list of these to signify modifications the miner is allowed to make:
| mutations | |
|---|---|
| Value | Significance |
| coinbase/append | append the provided coinbase scriptSig |
| coinbase | provide their own coinbase; if one is provided, it may be replaced or modified (implied if "coinbasetxn" omitted) |
| generation | add or remove outputs from the coinbase/generation transaction (implied if "coinbasetxn" omitted) |
| time/increment | change the time header to a value after "time" (implied if "maxtime" or "maxtimeoff" are provided) |
| time/decrement | change the time header to a value before "time" (implied if "mintime" is provided) |
| time | modify the time header of the block |
| transactions/add (or "transactions") | add other valid transactions to the block (implied if "transactions" omitted from result) |
| prevblock | use the work with other previous-blocks; this implicitly allows removing transactions that are no longer valid (but clients SHOULD attempt to propose removal of any required transactions); it also implies adjusting "height" as necessary |
| version/force | encode the provide block version, even if the miner doesn't understand it |
| version/reduce | use an older block version than the one provided (for example, if the client does not support the version provided) |
| template | ||
|---|---|---|
| Key | Type | Description |
| fulltarget | String | the number which full results should be less than, in big-endian hexadecimal (see "share/*" mutations) |
| mutable | Array of Strings | different manipulations that the server explicitly allows to be made, including abbreviations |
If the block template contains a "mutable" key, it is a list of these to signify modifications the miner is allowed to make:
| abbreviation mutations | |
|---|---|
| Value | Significance |
| submit/hash | each transaction being sent in a request, that the client is certain the server knows about, may be replaced by its hash in little-endian hexadecimal, prepended by a ":" character |
| submit/coinbase | if the "transactions" provided by the server are used as-is with no changes, submissions may omit transactions after the coinbase (transaction count varint remains included with the full number of transactions) |
| submit/truncate | if the "coinbasetxn" and "transactions" provided by the server are used as-is with no changes, submissions may contain only the block header; if only the scriptSig of "coinbasetxn" is modified, the params Object MUST contain a "coinbasesig" key with the content, or a "coinbaseadd" with appended data (if only appending) |
| share/coinbase | same as "submit/coinbase", but only if the block hash is greater than "fulltarget" |
| share/merkle | if the block hash is greater than "fulltarget", the non-coinbase transactions may be replaced with a merkle chain connecting it to the root |
| share/truncate | same as "submit/truncate", but only if the block hash is greater than "fulltarget" |
The format used for submitting shares with the "share/merkle" mutation shall be the 80-byte block header, the total number of transactions encoded in Bitcoin variable length number format, the coinbase transaction, and then finally the little-endian SHA256 hashes of each link in the merkle chain connecting it to the merkle root.
| template request | ||
|---|---|---|
| Key | Type | Description |
| capabilities | Array of Strings | miners which support this SHOULD provide a list including the String "serverlist" |
| template | ||
|---|---|---|
| Key | Type | Description |
| serverlist | Array of Objects | list of servers in this single logical service |
If the "serverlist" parameter is provided, clients MAY choose to intelligently treat the server as part of a larger single logical service.
Each host Object in the Array is comprised of the following fields:
| serverlist element | ||
|---|---|---|
| Key | Type | Description |
| uri | String | URI of the individual server; if authentication information is omitted, the same authentication used for this request MUST be assumed |
| avoid | Number | number of seconds to avoid using this server |
| priority | Number | an integer priority of this host (default: 0) |
| sticky | Number | number of seconds to stick to this server when used |
| update | Boolean | whether this server may update the serverlist (default: true) |
| weight | Number | a relative weight for hosts with the same priority (default: 1) |
When choosing which actual server to get the next job from, URIs MUST be tried in order of their "priority" key, lowest Number first. Where the priority of URIs is the same, they should be chosen from in random order, weighed by their "weight" key. Work proposals and submissions MUST be made to the same server that issued the job. Clients MAY attempt to submit to other servers if, and only if, the original server cannot be reached. If cross-server share submissions are desired, services SHOULD instead use the equivalent domain name system (DNS) features (RFCs 1794 and 2782).
Updates to the Logical Service server list may only be made by the original server, or servers listed with the "update" key missing or true. Clients MAY choose to advertise serverlist capability to servers with a false "update" key, but if so, MUST treat the server list provided as a subset of the current one, only considered in the context of this server. At least one server with "update" privilege MUST be attempted at least once daily.
If the "sticky" key is provided, then when that server is used, it should be used consistently for at least that many seconds, if possible.
A permanent change in server URI MAY be indicated with a simple "serverlist" parameter:
"serverlist":[{"uri": "http://newserver"}]
A temporary delegation to another server for 5 minutes MAY be indicated likewise:
"serverlist":[{"uri": "", avoid: 300}, {"uri": "http://newserver", "update": false}]
There is reasonable concerns about mining currently being too centralized on pools, and the amount of control these pools hold. By exposing the details of the block proposals to the miners, they are enabled to audit and possibly modify the block before hashing it.
To encourage widespread adoption, this BIP should be a complete superset of the existing centralized getwork protocol, so pools are not required to make substantial changes to adopt it.
Why allow servers to restrict the complete coinbase and nonce range?
Why specify "time/*" mutations at all?
What is the purpose of the "prevblock" mutation?
Why must both "mintime"/"maxtime" and "mintimeoff"/"maxtimeoff" keys be defined?
Is "target" really needed?
What is the purpose of the "hash" transaction list format?