Archive Revision as of 20:35, 17 November 2012

https://en.bitcoin.it/w/index.php?title=BIP_0022&oldid=32725

1 files changed, 126 insertions, 88 deletions

diff --git a/bip-0022.mediawiki b/bip-0022.mediawiki
index f03f486..9efc8f0 100644
--- a/bip-0022.mediawiki
+++ b/bip-0022.mediawiki
@@ -1,6 +1,8 @@
+{{bip}}
+
 <pre>
   BIP: 22
-  Title: getmemorypool
+  Title: getblocktemplate - Fundamentals
   Author: Luke Dashjr <luke+bip22@dashjr.org>
   Status: Accepted
   Type: Standards Track
@@ -14,116 +16,130 @@ Instead of sending a simple block header for hashing, the entire block structure
 
 ==Specification==
 
-===JSON-RPC Method: getmemorypool===
+===Block Template Request===
 
-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).
+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#Block Proposal|"proposal"]].
 
-getmemorypool MUST return a JSON Object containing at least the following keys, all of which relate to the block header:
+Block template creation can be influenced by various parameters:
 {| class="wikitable"
+!colspan=4|template request
+|-
 ! Key !! Required !! Type !! Description
 |-
-| bits || {{Yes}} || String || the compressed difficulty in hexadecimal
+| 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#Block Proposal|"proposal"]], [[BIP 0023#Logical Services|"serverlist"]], "workid", and any of the [[BIP 0023#Mutations|mutations]]
 |-
-| curtime || {{Yes}} || Number || the current time as seen by the server (recommended for block time)
+| mode || {{No}} || String || MUST be "template" or omitted
+|}
+
+getblocktemplate MUST return a JSON Object containing the following keys:
+{| class="wikitable"
+!colspan=4| template
 |-
-| height || {{Yes|Should}} || Number || the height of the block we are looking for
+! Key !! Required !! Type !! Description
 |-
-| previousblockhash || {{Yes}} || String || the hash of the previous block, in big-endian converted to hexadecimal
+| bits || {{Yes}} || String || the compressed difficulty in hexadecimal
 |-
-| transactions || {{Yes|Should}} || Array of Strings || Bitcoin transactions encoded in hexadecimal (byte-for-byte), not including coinbase
+| 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
 |-
-| version || {{Yes}} || Number || always 1 (at least for bitcoin)
+| height || {{Yes}} || Number || the height of the block we are looking for
 |-
-| coinbasetxn || {{Patch|or ↓}} || String || hexadecimal byte-for-byte coinbase transaction
+| previousblockhash || {{Yes}} || String || the hash of the previous block, in big-endian hexadecimal
 |-
-| coinbasevalue || {{Patch|or ↑}} || Number || total funds available for the coinbase
+| sigoplimit || {{No}} || Number || number of sigops allowed in blocks
 |-
-| 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.
+| sizelimit || {{No}} || Number || number of bytes allowed in blocks
 |-
-| expires || {{No}} || Number || how many seconds (beginning from when the server sent the response) this work is valid for, at most
+| transactions || {{Yes|Should}} || Array of Objects || Objects containing [[#Transactions Object Format|information for Bitcoin transactions]] (excluding coinbase)
 |-
-| fulltarget || {{No}} || String || the number which full results should be less than, in big-endian hexadecimal (see [[#Mutations|"share/*" mutations]])
+| 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)
 |-
-| longpoll || {{No}} || String || URI for [[#Long Polling|long polling]]
+| 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 inadvertantly expend SIGOPs (which are counted toward limits, despite not being executed).
 |-
-| maxtime || {{No}} || Number || the maximum time allowed
+| coinbasetxn || {{Patch|this or ↓}} || Object || [[#Transactions Object Format|information for coinbase transaction]]
 |-
-| 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)
+| coinbasevalue || {{Patch|this or ↑}} || Number || total funds available for the coinbase (in Satoshis)
 |-
-| mintime || {{No}} || Number || the minimum time allowed
+| workid || {{No}} || String || if provided, this value must be returned with results (see [[#Block Submission|Block Submission]])
+|}
+
+==== Transactions Object Format ====
+
+The Objects listed in the response's "transactions" key contains these keys:
+
+{| class="wikitable"
+!colspan=3|template "transactions" element
 |-
-| mintimeoff || {{No}} || Number || the minimum time allowed (as a moving offset from "curtime")
+! Key !! Type !! Description
 |-
-| mutable || {{No}} || Array of Strings || different manipulations that the server explicitly allows to be made (see [[#Mutations|Mutations]])
+| data || String || transaction data encoded in hexadecimal (byte-for-byte)
 |-
-| noncerange || {{No}} || String || two 32-bit integers, concatenated in big-endian hexadecimal, which represent the valid ranges of nonces the miner may scan
+| 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
 |-
-| 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
+| 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
 |-
-| target || {{No}} || String || the number which valid results must be less than, in big-endian hexadecimal
+| hash || String || hash/id encoded in little-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
+| required || Boolean || if provided and true, this transaction must be in the final block
 |-
-| workid || {{No}} || String or Number || if provided, this value must be returned with results (see [[#JSON-RPC Method: submitblock|"submitblock"]])
+| 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"
-! 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)
+!colspan=3|submitblock parameters (2nd argument)
 |-
-| generation
-| add or remove outputs from the coinbase/generation transaction (implied if "coinbasetxn" omitted)
+! Key !! Type !! Description
 |-
-| 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"
+| 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===
+
+{| class="wikitable"
+! colspan="3" | template request
 |-
-| time/increment
-| change the time header to a value after "time" (implied if "maxtime" or "maxtimeoff" are provided)
+! Key !! Type !! Description
 |-
-| time/decrement
-| change the time header to a value before "time" (implied if "mintime" is provided)
+| capabilities || Array of Strings || miners which support long polling SHOULD provide a list including the String "longpoll"
 |-
-| time
-| modify the time header of the block
+| longpollid || String || "longpollid" of job to monitor for expiration; required and valid only for long poll requests
+|}
+
+{| class="wikitable"
+! colspan="3" | template
 |-
-| transactions/add
-| add other valid transactions to the block
+! Key !! Type !! Description
 |-
-| transactions/remove
-| remove transactions provided by the server
+| longpollid || String || identifier for long poll request; MUST be omitted if the server does not support long polling
 |-
-| transactions
-| add or remove transactions (both of the above; implied if "transactions" omitted from result)
+| longpolluri || String || if provided, an alternate URI to use for long poll requests
 |-
-| 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
+| 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
 |}
 
-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.
 
-==== 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.
+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.
@@ -132,21 +148,33 @@ Upon receiving a completed response:
 
 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.
+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.
+===Optional: Template Tweaking===
 
-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
+|}
 
+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:
 {| class="wikitable"
+!colspan=2| share rejection reasons
+|-
 ! Reason !! Description
 |-
 | bad-cb-flag || the server detected a feature-signifying flag that it does not allow
@@ -186,21 +214,31 @@ Possible reasons a share may be rejected include, but are not limited to:
 | unknown-work || the template or workid could not be identified
 |}
 
-=== 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.
+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.
 
-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.
+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==
 
-* [https://gitorious.org/bitcoin/eloipool Eloipool]
-* [http://luke.dashjr.org/programs/bitcoin/w/bitcoind/luke-jr.git/blobdiff/722d9387be4b267b689d7b7d78daeb7157bd12d8..gmp_bip:/src/bitcoinrpc.cpp bitcoind]
+* [https://gitorious.org/bitcoin/eloipool Eloipool (server)]
+* [http://gitorious.org/bitcoin/libblkmaker libblkmaker (client)]
+* [https://github.com/bitcoin/bitcoin/pull/936/files bitcoind (minimal server)]
+
+==See Also==
+* [[BIP 0023|BIP 23: getblocktemplate - Pooled Mining]]
 
+[[Category:BIP|D]]