BIP 0022: Difference between revisions

From Bitcoin Wiki
Jump to navigation Jump to search
← Older edit
Luke-jr (talk | contribs)
Clerks, Administrators, Editors
3,074 edits
"transactions" hash/obj forms
934 (talk | contribs)
Editors
882 edits
Update BIP text with latest version from https://github.com/bitcoin/bips/blob/b5723035e23896d0/bip-0022.mediawiki
 
(76 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{bip}}
{{bip}}
{{BipMoved|bip-0022.mediawiki}}


<pre>
<pre>
   BIP: 22
   BIP: 22
   Title: getmemorypool
  Layer: API/RPC
   Title: getblocktemplate - Fundamentals
   Author: Luke Dashjr <luke+bip22@dashjr.org>
   Author: Luke Dashjr <luke+bip22@dashjr.org>
   Status: Draft
  Comments-Summary: No comments yet.
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0022
   Status: Final
   Type: Standards Track
   Type: Standards Track
   Created: 28-02-2012
   Created: 2012-02-28
  License: BSD-2-Clause
</pre>
</pre>


Line 15: Line 20:
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.
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==
==Copyright==


===JSON-RPC Method: getmemorypool===
This BIP is licensed under the BSD 2-clause license.


A new JSON-RPC method is defined, called "getmemorypool".
==Specification==
It accepts two arguments, both optional.
If the first argument is provided, and a String, it is interpreted as block data [[#Block Submission|submission]] or proposal;
otherwise, this call is interpreted as a request for a new block template from the server.
The second argument is an Object of request parameters.


===Block Template Request===
===Block Template Request===


If called with a single Object argument, getmemorypool interprets that Object as a set of parameters to build a block template from:
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 the default "template" request or a [[bip-0023.mediawiki#Block Proposal|"proposal"]].
 
Block template creation can be influenced by various parameters:
{| class="wikitable"
{| class="wikitable"
! Key !! Type !! Description
!colspan=4|template request
|-
|-
| longpollid || String || "longpollid" of job to monitor for expiration; required and valid only for [[#Long Polling|long poll requests]]
! Key !! Required !! Type !! Description
|-
|-
| nonces || Number || size of nonce range the miner needs; if not provided, the server SHOULD assume the client requires 2<sup>32</sup>
| capabilities || No || Array of Strings || SHOULD contain a list of the following, to indicate client-side support: [[#Optional: Long Polling|"longpoll"]], "coinbasetxn", "coinbasevalue", [[bip-0023.mediawiki#Block Proposal|"proposal"]], [[bip-0023.mediawiki#Logical Services|"serverlist"]], "workid", and any of the [[bip-0023.mediawiki#Mutations|mutations]]
|-
|-
| tx || String || format of response "transactions" key elements ("hex" per default)
| mode || No || String || MUST be "template" or omitted
|}
|}


getmemorypool MUST return a JSON Object containing the following keys:
getblocktemplate MUST return a JSON Object containing the following keys:
{| class="wikitable"
{| class="wikitable"
!colspan=4| template
|-
! Key !! Required !! Type !! Description
! Key !! Required !! Type !! Description
|-
|-
| bits || {{Yes}} || String || the compressed difficulty in hexadecimal
| bits || Yes || String || the compressed difficulty in hexadecimal
|-
| curtime || {{Yes}} || Number || the current time as seen by the server (recommended for block time)
|-
| height || {{Yes|Should}} || Number || the height of the block we are looking for
|-
| previousblockhash || {{Yes}} || String || the hash of the previous block, in big-endian hexadecimal
|-
| transactions ("hash") || {{Yes|Should}} || Array of Strings || hashes/ids of Bitcoin transactions (excluding coinbase), in little-endian hexadecimal
|-
| transactions ("hex") || {{Yes|Should}} || Array of Strings || data for Bitcoin transactions (excluding coinbase) encoded in hexadecimal (byte-for-byte)
|-
| transactions ("obj") || {{Yes|Should}} || Array of Objects || Objects containing [[#Transactions Object Format|information for Bitcoin transactions]] (excluding coinbase)
|-
| version || {{Yes}} || Number || always 1 (at least for bitcoin)
|-
| coinbasetxn || {{Patch|or ↓}} || See "transactions" || coinbase transaction, in the same format as "transactions" key
|-
| coinbasevalue || {{Patch|or ↑}} || Number || total funds available for the coinbase (in Satoshis)
|-
| coinbaseaux || {{No}} || Object || 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.
|-
|-
| expires || {{No}} || Number || how many seconds (beginning from when the server sent the response) this work is valid for, at most
| curtime || Yes || 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
|-
|-
| fulltarget || {{No}} || String || the number which full results should be less than, in big-endian hexadecimal (see [[#Mutations|"share/*" mutations]])
| height || Yes || Number || the height of the block we are looking for
|-
|-
| longpoll || {{No}} || String || URI for [[#Long Polling|long polling]]
| previousblockhash || Yes || String || the hash of the previous block, in big-endian hexadecimal
|-
|-
| longpollid || {{Patch|if ↑}} || String || unique identifier for [[#Long Polling|long poll request]]
| sigoplimit || No || Number || number of sigops allowed in blocks
|-
|-
| maxtime || {{No}} || Number || the maximum time allowed
| sizelimit || No || Number || number of bytes allowed in blocks
|-
|-
| maxtimeoff || {{No}} || 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)
| transactions || Should || Array of Objects || Objects containing [[#Transactions Object Format|information for Bitcoin transactions]] (excluding coinbase)
|-
|-
| mintime || {{No}} || Number || the minimum time allowed
| version || Yes || Number || always 1 or 2 (at least for bitcoin) - clients MUST understand the implications of the version they use (eg, comply with [[bip-0034.mediawiki|BIP 0034]] for version 2)
|-
|-
| mintimeoff || {{No}} || Number || the minimum time allowed (as a moving offset from "curtime")
| coinbaseaux || No || 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. This does not include the block height, which is required to be included in the scriptSig by [[bip-0034.mediawiki|BIP 0034]]. It is advisable to encode values inside "PUSH" opcodes, so as to not inadvertently expend SIGOPs (which are counted toward limits, despite not being executed).
|-
|-
| mutable || {{No}} || Array of Strings || different manipulations that the server explicitly allows to be made (see [[#Mutations|Mutations]])
| coinbasetxn || this or ↓ || Object || [[#Transactions Object Format|information for coinbase transaction]]
|-
|-
| noncerange || {{No}} || String || two 32-bit integers, concatenated in big-endian hexadecimal, which represent the valid ranges of nonces the miner may scan
| coinbasevalue || this or ↑ || Number || total funds available for the coinbase (in Satoshis)
|-
|-
| submitold || {{No}} || Boolean || only relevant for [[#Long Polling|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
| workid || No || String || if provided, this value must be returned with results (see [[#Block Submission|Block Submission]])
|-
| target || {{No}} || String || the number which valid results must be less than, in big-endian hexadecimal
|-
| txrequired || {{No}} || Number || this many of the first transactions provided must be present in the final block, even if the "transactions/remove" mutation is allowed
|-
| workid || {{No}} || String or Number || if provided, this value must be returned with results (see [[#JSON-RPC Method: submitblock|"submitblock"]])
|}
|}


==== Transactions Object Format ====
==== Transactions Object Format ====


When the "tx" option is provided as "obj", the Objects listed in the response's "transactions" key may contain these keys:
The Objects listed in the response's "transactions" key contains these keys:


{| class="wikitable"
{| class="wikitable"
! Key !! Required !! Type !! Description
!colspan=3|template "transactions" element
|-
|-
| data || {{Yes}} || String || transaction data encoded in hexadecimal (byte-for-byte)
! Key !! Type !! Description
|-
|-
| depends || {{No}} || Array of Numbers || other transactions (by index in "transactions" list) that must be present in the final block if this one is
| data || String || transaction data encoded in hexadecimal (byte-for-byte)
|-
|-
| fee || {{No}} || 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)
| depends || Array of Numbers || other transactions before this one (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
|-
|-
| hash || {{No}} || String || hash/id encoded in little-endian hexadecimal
| 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
|-
|-
| required || {{No}} || Boolean || if provided and true, this transaction must be in the final block, even if the "transactions/remove" mutation is allowed
| hash || String || hash/id encoded in little-endian hexadecimal
|-
|-
| sigops || {{No}} || Number || total number of SigOps, as counted for purposes of block limits
| required || Boolean || if provided and true, this transaction must be in the final block
|-
|-
| sigopsreal || {{No}} || Number || total number of SigOps, as counted by current standard rules
| 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
|}
|}


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


Any of these may be listed in the "mutable" key to signify modifications the miner is allowed to make:
A JSON-RPC method is defined, called "submitblock", to submit potential blocks (or shares).
It accepts two arguments:
the first is always a String of the hex-encoded block data to submit;
the second is an Object of parameters, and is optional if parameters are not needed.


{| class="wikitable"
{| class="wikitable"
! Value !! Significance
!colspan=3|submitblock parameters (2nd argument)
|-
|-
| coinbase/append
! Key !! Type !! Description
| append the provided coinbase scriptSig
|-
|-
| coinbase
| workid || String || if the server provided a workid, it MUST be included with submissions
| provide their own coinbase; if one is provided, it may be replaced or modified (implied if "coinbasetxn" omitted)
|}
 
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===
 
{| class="wikitable"
! colspan="3" | template request
|-
|-
| generation
! Key !! Type !! Description
| add or remove outputs from the coinbase/generation transaction (implied if "coinbasetxn" omitted)
|-
|-
| share/coinbase
| capabilities || Array of Strings || miners which support long polling SHOULD provide a list including the String "longpoll"
| 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
| longpollid || String || "longpollid" of job to monitor for expiration; required and valid only for long poll requests
| 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"
|}
 
{| class="wikitable"
! colspan="3" | template
|-
|-
| share/truncate
! Key !! Type !! Description
| 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
| longpollid || String || identifier for long poll request; MUST be omitted if the server does not support long polling
| add other valid transactions to the block
|-
|-
| transactions/remove
| longpolluri || String || if provided, an alternate URI to use for long poll requests
| remove transactions provided by the server
|-
|-
| transactions
| 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
| 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.
If the server supports long polling, it MUST include a "longpollid" key in block templates, and it MUST be unique for each event:
any given "longpollid" should check for only one condition and not be reused.
For example, a server which has a long poll wakeup only for new blocks might use the previous block hash.
However, clients should not assume the "longpollid" has any specific meaning.
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.


==== 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.
If "longpoll" is provided, a "longpollid" key MUST also be, with a unique identifier used to determine expiration of the current job.
Miners MAY start a request to this long polling URI with a standard JSON-RPC request (in the case of HTTP transport, POST with data) and same authorization.
The miner MUST include the "longpollid" key provided in the parameters to this getmemorypool call.
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".
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 the server sending response headers with "chunked" Transfer-Encoding, only delaying the completion of the final JSON response.
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:
Upon receiving a completed response:
Line 180: Line 158:
If a client receives an incomplete or invalid response, it SHOULD retry the request with an exponential backoff.
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.
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.
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.
In the case of a "Forbidden" response (for example, HTTP 403), a client SHOULD NOT attempt to retry without user intervention.


===Block Submission===
===Optional: Template Tweaking===
When getmemorypool is called with a String as its first argument, it is interpreted as data for a potential block; 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 of parameters for the submission.
The only defined key of this Object is the "workid" provided by the server:
if a "workid" was specified in the template, it must be submitted with the share/block.


If the parameters argument is specified, 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.
{| class="wikitable"
! colspan="3" | 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
|-
| maxversion || Number || highest block version number supported
|}


If the parameters argument is omitted, this method SHOULD return either true (if the share is accepted) or false (if rejected).
For "sigoplimit" and "sizelimit", negative values and zero are offset from the server-determined block maximum.
Clients MUST NOT depend on this boolean response, and servers MAY choose not to implement this paragraph.
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:
Possible reasons a share may be rejected include, but are not limited to:
{| class="wikitable"
{| class="wikitable"
!colspan=2| share rejection reasons
|-
! Reason !! Description
! Reason !! Description
|-
|-
Line 235: Line 224:
|}
|}


=== Known Bugs ===
==Motivation==
This BIP should not be promoted from Draft status until these are addressed:
 
* Longpolling currently assumes URI-based requests, which is not implied by JSON-RPC.
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.
* ''(feel free to add issues here)''
At the same time, new independent node implementations are maturing to the point where they will also be able to support miners.


==Motivation==
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.


There is reasonable concerns about mining currently being too centralized on pools, and the amount of control these pools hold.
What is the purpose of "workid"?
By exposing the details of the block proposals to the miners, they are enabled to audit and possibly modify the block before hashing it.
* 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.


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.
Why should "sigops" be provided for transactions?
* Due to the [[bip-0016.mediawiki|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==
==Reference Implementation==


* [https://gitorious.org/bitcoin/eloipool Eloipool]
* [https://gitorious.org/bitcoin/eloipool Eloipool (server)]
* [http://luke.dashjr.org/programs/bitcoin/w/bitcoind/luke-jr.git/blobdiff/722d9387be4b267b689d7b7d78daeb7157bd12d8..gmp_bip:/src/bitcoinrpc.cpp bitcoind]
* [http://gitorious.org/bitcoin/libblkmaker libblkmaker (client)]
* [https://github.com/bitcoin/bitcoin/pull/936/files bitcoind (minimal server)]


[[Category:BIP|D]]
==See Also==
* [[bip-0023.mediawiki|BIP 23: getblocktemplate - Pooled Mining]]

Latest revision as of 17:58, 24 September 2019

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.

Please do not modify this page. This is a mirror of the BIP from the source Git repository here.

 
  BIP: 22
  Layer: API/RPC
  Title: getblocktemplate - Fundamentals
  Author: Luke Dashjr <luke+bip22@dashjr.org>
  Comments-Summary: No comments yet.
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0022
  Status: Final
  Type: Standards Track
  Created: 2012-02-28
  License: BSD-2-Clause

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.

Copyright

This BIP is licensed under the BSD 2-clause license.

Specification

Block Template Request

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 the default "template" request or a "proposal".

Block template creation can be influenced by various parameters:

template request
Key Required Type Description
capabilities No 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 No String MUST be "template" or omitted

getblocktemplate MUST return a JSON Object containing the following keys:

template
Key Required Type Description
bits Yes String the compressed difficulty in hexadecimal
curtime Yes 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 Yes Number the height of the block we are looking for
previousblockhash Yes String the hash of the previous block, in big-endian hexadecimal
sigoplimit No Number number of sigops allowed in blocks
sizelimit No Number number of bytes allowed in blocks
transactions Should Array of Objects Objects containing information for Bitcoin transactions (excluding coinbase)
version Yes Number always 1 or 2 (at least for bitcoin) - clients MUST understand the implications of the version they use (eg, comply with BIP 0034 for version 2)
coinbaseaux No 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. This does not include the block height, which is required to be included in the scriptSig by BIP 0034. It is advisable to encode values inside "PUSH" opcodes, so as to not inadvertently expend SIGOPs (which are counted toward limits, despite not being executed).
coinbasetxn this or ↓ Object information for coinbase transaction
coinbasevalue this or ↑ Number total funds available for the coinbase (in Satoshis)
workid No 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 before this one (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

A JSON-RPC method is defined, called "submitblock", to submit potential blocks (or shares). It accepts two arguments: the first is always a String of the hex-encoded block data to submit; the second is an Object of parameters, and is optional if parameters are not needed.

submitblock parameters (2nd argument)
Key Type Description
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 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, and it MUST be unique for each event: any given "longpollid" should check for only one condition and not be reused. For example, a server which has a long poll wakeup only for new blocks might use the previous block hash. However, clients should not assume the "longpollid" has any specific meaning. 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
maxversion Number highest block version number supported

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

See Also

Retrieved from "https://en.bitcoin.it/w/index.php?title=BIP_0022&oldid=66781"