BIP: 22 Title: getmemorypool Author: Luke Dashjr Status: Accepted 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: {| class="wikitable"
| ! Key !! Required !! Type !! Description |
|---|
| bits |
| - |
| curtime |
| - |
| height |
| - |
| previousblockhash |
| - |
| transactions |
| - |
| version |
| - |
| coinbasetxn |
| - |
| coinbasevalue |
| - |
| coinbaseaux |
| - |
| expires |
| - |
| fulltarget |
| - |
| longpoll |
| - |
| maxtime |
| - |
| maxtimeoff |
| - |
| mintime |
| - |
| mintimeoff |
| - |
| mutable |
| - |
| noncerange |
| - |
| submitold |
| - |
| target |
| - |
| txrequired |
| - |
| workid |
| } |
====Mutations====
Any of these may be listed in the "mutable" key to signify modifications the miner is allowed to make:
{| class="wikitable"
| ! 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) |
| - |
| share/coinbase |
| if the block hash is less than "target", but not less than "fulltarget", only return the block header and coinbase transaction, but only if the other transactions are unmodified from those proposed in the getmemorypool job |
| - |
| 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" |
| - |
| 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 |
| add other valid transactions to the block |
| - |
| transactions/remove |
| remove transactions provided by the server |
| - |
| transactions |
| add or remove transactions (both of the above; implied if "transactions" omitted from result) |
| - |
| prevblock |
| use the work with other previous-blocks; this implicitly allows removing transactions that are no longer valid, unless they are part of the "txrequired" count; it also implies adjusting "height" as necessary |
| } |
Note that miners are NOT required to implement any of these mutations.
==== Long Polling ==== If the server supports long polling, it SHOULD include the "longpoll" key with a relative or absolute URI. The absolute URI MAY specify a different port than the original connection. Miners MAY start a request to this long polling URI with a standard JSON-RPC request (POST with data) and same basic authorization. This request SHOULD NOT be processed nor answered by the server until it wishes to replace the current block data. Clients SHOULD make this request with a very long request timeout and MUST accept the server sending response headers with "chunked" Transfer-Encoding delaying the completion of the final JSON response.
Upon receiving a completed response:
- Only if "submitold" is provided and false, the client MAY discard the results of past operations and MUST begin working on the new work immediately.
- The client SHOULD begin working on the new work received as soon as possible, if not immediately.
- The client SHOULD make a new request to the same long polling URI.
If a client receives an incomplete or invalid response, it SHOULD retry the request with an exponential backoff. Clients MAY implement this backoff with limitations (such as maximum backoff time) or any algorithm as deemed suitable. It is however forbidden to simply retry immediately with no delay after more than one failure. In the case of a "Forbidden" response (for example, HTTP 403), a client SHOULD NOT attempt to retry without user intervention.
===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 rejected, 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: {| class="wikitable"
| ! Reason !! Description |
|---|
| bad-cb-flag |
| - |
| bad-cb-length |
| - |
| bad-cb-prefix |
| - |
| bad-diffbits |
| - |
| bad-prevblk |
| - |
| bad-txnmrklroot |
| - |
| bad-txns |
| - |
| bad-version |
| - |
| duplicate |
| - |
| high-hash |
| - |
| rejected |
| - |
| stale-prevblk |
| - |
| stale-work |
| - |
| time-invalid |
| - |
| time-too-new |
| - |
| time-too-old |
| - |
| unknown-user |
| - |
| unknown-work |
| } |
=== Known Bugs === This BIP should not be promoted from Draft status until these are addressed:
- Noncerange might not be possible to support for all workers, so a way to signal support is needed
- Longpolling currently assumes URI-based requests, which is not implied by JSON-RPC.
- ''(feel free to add issues here)''
==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.
==Reference Implementation==