BIP 0022
BIP: TBD Title: getmemorypool Author: Luke Dashjr <luke+bipgmp@dashjr.org> Status: Draft Type: Standards Track Created: 28-02-2012
Abstract
This BIP describes a new JSON-RPC method for "smart" Bitcoin miners and proxies. Instead of sending a simple block header for hashing, the entire block structure is sent, and left to the miner to (optionally) customize and assemble.
Specification
JSON-RPC Method: getmemorypool
A new JSON-RPC method is defined, called "getmemorypool". It takes no arguments. If arguments are provided, it may wrap the "submitblock" JSON-RPC method (described later), cast to a Boolean return value (true = share accepted).
getmemorypool MUST return a JSON Object containing at least the following keys, all of which relate to the block header:
| Key | Type | Required | Description |
|---|---|---|---|
| bits | String | Yes | the big-endian compressed difficulty in hexadecimal |
| previousblockhash | String | Yes | the hash of the previous block, in little endian converted to hexadecimal |
| time | Number | Yes | the recommended time |
| transactions | Array of Strings | Should | Bitcoin transactions encoded in hexadecimal (byte-for-byte), not including coinbase |
| version | Number | Yes | always 1 (at least for bitcoin) |
| coinbasetxn | String | or ↓ | hexadecimal byte-for-byte coinbase transaction |
| coinbasevalue | Number | or ↑ | total funds available for the coinbase |
| coinbaseaux | Object | No | data that SHOULD or MUST (depending on mutable flags) be included in the coinbase's scriptSig content. Only the values (hexadecimal byte-for-byte) in this Object should be included, not the keys. |
| curtime | Number | No | TODO? |
| expires | Number | No | how many seconds (beginning from when the server sent the response) this work is valid for, at most |
| fulltarget | String | No | the number which full results should be less than, in little-endian hexadecimal (see "share/*" mutations) |
| maxtime | Number | No | the maximum time allowed |
| maxtimeoff | Number | No | the maximum time allowed (as a moving offset from 'time') |
| mintime | Number | No | the minimum time allowed |
| mutable | Array of Strings | No | different manipulations that the server explicitly allows to be made (see later for details) |
| noncerange | String | No | two 32-bit integers, concatenated in big-endian hexadecimal, which represent the valid ranges of nonces the miner may scan |
| target | String | No | the number which valid results must be less than, in little-endian hexadecimal |
| transactionsrequired | Number | No | this many of the first transactions provided must be present in the final block, even if the "transactions/remove" mutation is allowed |
| workid | String or Number | No | if provided, this value must be returned with results (see "submitblock") |
Mutations
Any of these may be listed in the "mutable" key to signify modifications the miner is allowed to make:
| Value | Significance |
|---|---|
| coinbase/append | append the provided coinbase scriptSig |
| coinbase | provide their own coinbase; if one is provided, it may be replaced or modified (default if "coinbasetxn" omitted) |
| generation | add or remove outputs from the coinbase/generation transaction (default if "coinbasetxn" omitted) |
| share/merkle | if the block hash is less than "target", but not less than "fulltarget", only return the block header, coinbase transaction, and merkle tree connecting that transaction to the root (in the form of repeated right-side SHA256 hashes) in "submitblock" |
| share/truncate | if the block hash is less than "target", but not less than "fulltarget", only return the block header in "submitblock" |
| transactions/add | add other valid transactions to the block |
| transactions/remove | remove transactions provided by the server |
| transactions | add or remove transactions (both of the above; default if "transactions" omitted) |
| prevblock | use the work with other previous-blocks; this implicitly allows removing transactions that are no longer valid, unless they are part of the "transactionsrequired" count |
Note that miners are NOT required to implement any of these mutations.
JSON-RPC Method: submitblock
A new JSON-RPC method is defined, called "submitblock". It takes one to two arguments. The first argument is the block data; this may be truncated or merkle-ified depending on the "share/truncate" or "share/merkle" mutations, respectively. The second argument, if provided, is an Object. The only defined key of this Object is the "workid" provided by the server: if a "workid" was specified, it must be submitted with the share/block.
This method MUST return either null (when a share is accepted), a String describing briefly the reason the share was accepted, or an Object of these with a key for each merged-mining chain the share was submitted to.
Possible reasons a share may be rejected include, but are not limited to:
| Reason | Description |
|---|---|
| bad-cb-flag | the server detected a feature-signifying flag that it does not allow |
| bad-cb-length | the coinbase was too long (bitcoin limit is 100 bytes) |
| bad-cb-prefix | the server only allows appending to the coinbase, but it was modified beyond that |
| bad-diffbits | "bits" were changed |
| bad-prevblk | the previous-block is not the one the server intends to build on |
| bad-txnmrklroot | the block header's merkle root did not match the transaction merkle tree |
| bad-txns | the server didn't like something about the transactions in the block |
| bad-version | the version was wrong |
| duplicate | the server already processed this block data |
| high-hash | the block header did not hash to a value lower than the specified target |
| rejected | a generic rejection without details |
| stale-prevblk | the previous-block is no longer the one the server intends to build on |
| stale-work | the work this block was based on is no longer accepted |
| time-invalid | the time was not acceptable |
| time-too-new | the time was too far in the future |
| time-too-old | the time was too far in the past |
| unknown-user | the user submitting the block was not recognized |
| unknown-work | the template or workid could not be identified |
Motivation
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.
There is also a very minor load reduction on the pool server, since it does not need to calculate SHA256 for the block's merkle tree.