BIP 0022

This page describes a BIP (Bitcoin Improvement Proposal). Please see BIP 2 for more information about BIPs and creating them. Please do not just create a wiki page.

  BIP: 22
  Title: getblocktemplate - Fundamentals
  Author: Luke Dashjr <luke+bip22@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: getblocktemplate

A JSON-RPC method is defined, called "getblocktemplate". It accepts exactly one argument, which MUST be an Object of request parameters. If the request parameters include a "mode" key, that is used to explicitly select between "template", "proposal", and "submit" calls. Otherwise, it defaults to a submission if there is a "data" key (including the String-type argument mentioned above), and a template request if not.

Block Template Request

Block template creation can be influenced by various parameters:

template request
Key	Type	Description
capabilities	Array of Strings	SHOULD contain a list of the following, to indicate client-side support: "longpoll", "coinbasetxn", "coinbasevalue", "proposal", "serverlist", "workid", and any of the mutations
mode	String	MUST be "template" or omitted

getblocktemplate MUST return a JSON Object containing the following keys:

template
Key	Type	Description
bits	String	the compressed difficulty in hexadecimal
curtime	Number	the current time as seen by the server (recommended for block time) - note this is not necessarily the system clock, and must fall within the mintime/maxtime rules
height	Number	the height of the block we are looking for
previousblockhash	String	the hash of the previous block, in big-endian hexadecimal
sigoplimit	Number	number of sigops allowed in blocks
sizelimit	Number	number of bytes allowed in blocks
transactions	Array of Objects	Objects containing information for Bitcoin transactions (excluding coinbase)
version	Number	always 1 or 2 (at least for bitcoin) - if 2, clients MUST comply with BIP 0034
coinbaseaux	Object	data that SHOULD be included in the coinbase's scriptSig content. Only the values (hexadecimal byte-for-byte) in this Object should be included, not the keys.
coinbasetxn	String or Object	coinbase transaction, format specified by "tx:cb" parameter
coinbasevalue	Number	total funds available for the coinbase (in Satoshis)
workid	String	if provided, this value must be returned with results (see Block Submission)

Transactions Object Format

The Objects listed in the response's "transactions" key contains these keys:

template "transactions" element
Key	Type	Description
data	String	transaction data encoded in hexadecimal (byte-for-byte)
depends	Array of Numbers	other transactions (by 1-based index in "transactions" list) that must be present in the final block if this one is; if key is not present, dependencies are unknown and clients MUST NOT assume there aren't any
fee	Number	difference in value between transaction inputs and outputs (in Satoshis); for coinbase transactions, this is a negative Number of the total collected block fees (ie, not including the block subsidy); if key is not present, fee is unknown and clients MUST NOT assume there isn't one
hash	String	hash/id encoded in little-endian hexadecimal
required	Boolean	if provided and true, this transaction must be in the final block
sigops	Number	total number of SigOps, as counted for purposes of block limits; if key is not present, sigop count is unknown and clients MUST NOT assume there aren't any

Only the "data" key is required, but servers should provide the others if they are known.

Block Submission

When getblocktemplate is called with a "data" key, and "mode" either set to "submit" or omitted, it is interpreted as a potential block (or share).

getblocktemplate parameters
Key	Type	Description
data	String	MUST be hex-encoded block data
mode	String	MUST be "submit" or omitted
workid	String	if the server provided a workid, it MUST be included with submissions

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.

Optional: Long Polling

template request
Key	Type	Description
capabilities	Array of Strings	miners which support long polling SHOULD provide a list including the String "longpoll"
longpollid	String	"longpollid" of job to monitor for expiration; required and valid only for long poll requests

template
Key	Type	Description
longpollid	String	unique identifier for long poll request; MUST be omitted if the server does not support long polling
longpolluri	String	if provided, an alternate URI to use for long poll requests
submitold	Boolean	only relevant for long poll responses: indicates if work received prior to this response remains potentially valid (default) and should have its shares submitted; if false, the miner may wish to discard its share queue

If the server supports long polling, it MUST include a "longpollid" key in block templates. It MAY supply the "longpolluri" key with a relative or absolute URI, which MAY specify a completely different resource than the original connection, including port number. If "longpolluri" is provided by the server, clients MUST only attempt to use that URI for longpoll requests.

Clients MAY start a longpoll request with a standard JSON-RPC request (in the case of HTTP transport, POST with data) and same authorization, setting the "longpollid" parameter in the request to the value provided by the server.

This request SHOULD NOT be processed nor answered by the server until it wishes to replace the current block data as identified by the "longpollid". Clients SHOULD make this request with a very long request timeout and MUST accept servers sending a partial response in advance (such as HTTP headers with "chunked" Transfer-Encoding), and only delaying the completion of the final JSON response until processing.

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.

Optional: Template Tweaking

template request
Key	Type	Description
sigoplimit	Number or Boolean	maximum number of sigops to include in template
sizelimit	Number or Boolean	maximum number of bytes to use for the entire block

For "sigoplimit" and "sizelimit", negative values and zero are offset from the server-determined block maximum. If a Boolean is provided and true, the default limit is used; if false, the server is instructed not to use any limits on returned template. Servers SHOULD respect these desired maximums, but are NOT required to: clients SHOULD check that the returned template satisfies their requirements appropriately.

Appendix: Example Rejection Reasons

Possible reasons a share may be rejected include, but are not limited to:

share rejection reasons
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

bitcoind's JSON-RPC server can no longer support the load of generating the work required to productively mine Bitcoin, and external software specializing in work generation has become necessary. At the same time, new independent node implementations are maturing to the point where they will also be able to support miners.

A common standard for communicating block construction details is necessary to ensure compatibility between the full nodes and work generation software.

Rationale

Why not just deal with transactions as hashes (txids)?

• Servers might not have access to the transaction database, or miners may wish to include transactions not broadcast to the network as a whole.
• Miners may opt not to do full transaction verification, and may not have access to the transaction database on their end.

What is the purpose of "workid"?

• If servers allow all mutations, it may be hard to identify which job it is based on. While it may be possible to verify the submission by its content, it is much easier to compare it to the job issued. It is very easy for the miner to keep track of this. Therefore, using a "workid" is a very cheap solution to enable more mutations.

Why should "sigops" be provided for transactions?

• Due to the BIP 0016 changes regarding rules on block sigops, it is impossible to count sigops from the transactions themselves (the sigops in the scriptCheck must also be included in the count).

Reference Implementation

• Eloipool
• bitcoind

See Also

• BIP 23: getblocktemplate - Pooled Mining