|
|
---------------------------------------------
|
|
|
BIP: 23
|
|
|
Title: getblocktemplate - Pooled Mining
|
|
|
Author: Luke Dashjr <luke+bip22@dashjr.org>
|
|
|
Status: Accepted
|
|
|
Type: Standards Track
|
|
|
Created: 2012-02-28
|
|
|
---------------------------------------------
|
|
|
|
|
|
[[abstract]]
|
|
|
Abstract
|
|
|
~~~~~~~~
|
|
|
|
|
|
This BIP describes extensions to the getblocktemplate JSON-RPC call to
|
|
|
enhance pooled mining.
|
|
|
|
|
|
[[specification]]
|
|
|
Specification
|
|
|
~~~~~~~~~~~~~
|
|
|
|
|
|
Note that all sections of this specification are optional extensions on
|
|
|
top of link:BIP 0022[BIP 22].
|
|
|
|
|
|
[[summary-support-levels]]
|
|
|
Summary Support Levels
|
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
Something can be said to have BIP 23 Level 1 support if it implements at
|
|
|
least:
|
|
|
|
|
|
* http://www.ietf.org/rfc/rfc1945.txt[RFC 1945]
|
|
|
* http://json-rpc.org/wiki/specification[JSON-RPC 1.0]
|
|
|
* link:bip-0022.mediawiki[BIP 22 (non-optional sections)]
|
|
|
* bip-0022.mediawiki#Optional:_Long_Polling[BIP 22 Long Polling]
|
|
|
* link:#Basic_Pool_Extensions[BIP 23 Basic Pool Extensions]
|
|
|
* link:#Mutations[BIP 23 Mutation "coinbase/append"]
|
|
|
* link:#Submission_Abbreviation[BIP 23 Submission Abbreviation
|
|
|
"submit/coinbase"]
|
|
|
* link:#Mutations[BIP 23 Mutation "time/increment"] (only required for
|
|
|
servers)
|
|
|
|
|
|
It can be said to have BIP 23 Level 2 support if it also implements:
|
|
|
|
|
|
* link:#Mutations[BIP 23 Mutation "transactions/add"]
|
|
|
* link:#Block_Proposals[BIP 23 Block Proposals]
|
|
|
|
|
|
[[basic-pool-extensions]]
|
|
|
Basic Pool Extensions
|
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|==================================================================
|
|
|
|template request
|
|
|
|Key |Type |Description
|
|
|
|target |String |desired target for block template (may be ignored)
|
|
|
|==================================================================
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|template
|
|
|
|Key |Type |Description
|
|
|
|
|
|
|expires |Number |how many seconds (beginning from when the server sent
|
|
|
the response) this work is valid for, at most
|
|
|
|
|
|
|target |String |the number which valid results must be less than, in
|
|
|
big-endian hexadecimal
|
|
|
|=======================================================================
|
|
|
|
|
|
[[block-proposal]]
|
|
|
Block Proposal
|
|
|
^^^^^^^^^^^^^^
|
|
|
|
|
|
Servers may indicate support for proposing blocks by including a
|
|
|
capability string in their original template:
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|template
|
|
|
|Key |Type |Description
|
|
|
|
|
|
|capabilities |Array of Strings |MAY contain "proposal" to indicate
|
|
|
support for block proposal
|
|
|
|
|
|
|reject-reason |String |Reason the proposal was invalid as-is (only
|
|
|
applicable in response to proposals)
|
|
|
|=======================================================================
|
|
|
|
|
|
If supported, a miner MAY propose a block to the server for general
|
|
|
validation at any point before the job expires. This is accomplished by
|
|
|
calling getblocktemplate with two keys:
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|colspan=3| getblocktemplate parameters
|
|
|
|Key |Type |Description
|
|
|
|
|
|
|data |String |MUST be hex-encoded block data
|
|
|
|
|
|
|mode |String |MUST be "proposal"
|
|
|
|
|
|
|workid |String |if the server provided a workid, it MUST be included
|
|
|
with proposals
|
|
|
|=======================================================================
|
|
|
|
|
|
The block data MUST be validated and checked against the server's usual
|
|
|
acceptance rules (excluding the check for a valid proof-of-work). If it
|
|
|
is found to be in violation of any of these rules, the server MUST
|
|
|
return one of the following:
|
|
|
|
|
|
* Null if it is acceptable as-is, with the same workid (if any) as
|
|
|
provided. Note that this SHOULD NOT invalidate the old template's claim
|
|
|
to the same workid.
|
|
|
* A String giving the reason for the rejection (see
|
|
|
link:bip-0022.mediawiki#appendix-example-rejection-reasons[example
|
|
|
rejection reasons]).
|
|
|
* A "delta" block template (with changes needed); in this case, any
|
|
|
missing keys are assumed to default to those in the proposed block or,
|
|
|
if not applicable, the original block template it was based on. This
|
|
|
template MAY also include a "reject-reason" key with a String of the
|
|
|
reason for rejection.
|
|
|
|
|
|
It is RECOMMENDED that servers which merely need to track the proposed
|
|
|
block for later share/* submissions, return a simple Object of the form:
|
|
|
|
|
|
`{"workid":"new workid"}`
|
|
|
|
|
|
Clients SHOULD assume their proposed block will remain valid if the only
|
|
|
changes they make are to the portion of the coinbase scriptSig they
|
|
|
themselves provided (if any) and the time header. Servers SHOULD NOT
|
|
|
break this assumption without good cause.
|
|
|
|
|
|
[[mutations]]
|
|
|
Mutations
|
|
|
^^^^^^^^^
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|template request
|
|
|
|Key |Type |Description
|
|
|
|
|
|
|nonces |Number |size of nonce range the miner needs; if not provided,
|
|
|
the server SHOULD assume the client requires 2^32^
|
|
|
|=======================================================================
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|colspan=3| template
|
|
|
|Key |Type |Description
|
|
|
|
|
|
|maxtime |Number |the maximum time allowed
|
|
|
|
|
|
|maxtimeoff |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)
|
|
|
|
|
|
|mintime |Number |the minimum time allowed
|
|
|
|
|
|
|mintimeoff |Number |the minimum time allowed (as a moving offset from
|
|
|
"curtime")
|
|
|
|
|
|
|mutable |Array of Strings |different manipulations that the server
|
|
|
explicitly allows to be made
|
|
|
|
|
|
|noncerange |String |two 32-bit integers, concatenated in big-endian
|
|
|
hexadecimal, which represent the valid ranges of nonces the miner may
|
|
|
scan
|
|
|
|=======================================================================
|
|
|
|
|
|
If the block template contains a "mutable" key, it is a list of these to
|
|
|
signify modifications the miner is allowed to make:
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|colspan=2| mutations
|
|
|
|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)
|
|
|
|
|
|
|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 (or "transactions") |add other valid transactions to
|
|
|
the block (implied if "transactions" omitted from result)
|
|
|
|
|
|
|prevblock |use the work with other previous-blocks; this implicitly
|
|
|
allows removing transactions that are no longer valid (but clients
|
|
|
SHOULD attempt to propose removal of any required transactions); it also
|
|
|
implies adjusting "height" as necessary
|
|
|
|
|
|
|version/force |encode the provide block version, even if the miner
|
|
|
doesn't understand it
|
|
|
|
|
|
|version/reduce |use an older block version than the one provided (for
|
|
|
example, if the client does not support the version provided)
|
|
|
|=======================================================================
|
|
|
|
|
|
[[submission-abbreviation]]
|
|
|
Submission Abbreviation
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|colspan=3| template
|
|
|
|Key |Type |Description
|
|
|
|
|
|
|fulltarget |String |the number which full results should be less than,
|
|
|
in big-endian hexadecimal (see "share/*" mutations)
|
|
|
|
|
|
|mutable |Array of Strings |different manipulations that the server
|
|
|
explicitly allows to be made, including abbreviations
|
|
|
|=======================================================================
|
|
|
|
|
|
If the block template contains a "mutable" key, it is a list of these to
|
|
|
signify modifications the miner is allowed to make:
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|colspan=2| abbreviation mutations
|
|
|
|Value |Significance
|
|
|
|
|
|
|submit/hash |each transaction being sent in a request, that the client
|
|
|
is certain the server knows about, may be replaced by its hash in
|
|
|
little-endian hexadecimal, prepended by a ":" character
|
|
|
|
|
|
|submit/coinbase |if the "transactions" provided by the server are used
|
|
|
as-is with no changes, submissions may omit transactions after the
|
|
|
coinbase (transaction count varint remains included with the full number
|
|
|
of transactions)
|
|
|
|
|
|
|submit/truncate |if the "coinbasetxn" and "transactions" provided by
|
|
|
the server are used as-is with no changes, submissions may contain only
|
|
|
the block header; if only the scriptSig of "coinbasetxn" is modified,
|
|
|
the params Object MUST contain a "coinbasesig" key with the content, or
|
|
|
a "coinbaseadd" with appended data (if only appending)
|
|
|
|
|
|
|share/coinbase |same as "submit/coinbase", but only if the block hash
|
|
|
is greater than "fulltarget"
|
|
|
|
|
|
|share/merkle |if the block hash is greater than "fulltarget", the
|
|
|
non-coinbase transactions may be replaced with a merkle chain connecting
|
|
|
it to the root
|
|
|
|
|
|
|share/truncate |same as "submit/truncate", but only if the block hash
|
|
|
is greater than "fulltarget"
|
|
|
|=======================================================================
|
|
|
|
|
|
[[format-of-data-for-merkle-only-shares]]
|
|
|
Format of Data for Merkle-Only Shares
|
|
|
+++++++++++++++++++++++++++++++++++++
|
|
|
|
|
|
The format used for submitting shares with the "share/merkle" mutation
|
|
|
shall be the 80-byte block header, the total number of transactions
|
|
|
encoded in Bitcoin variable length number format, the coinbase
|
|
|
transaction, and then finally the little-endian SHA256 hashes of each
|
|
|
link in the merkle chain connecting it to the merkle root.
|
|
|
|
|
|
[[logical-services]]
|
|
|
Logical Services
|
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|template request
|
|
|
|Key |Type |Description
|
|
|
|
|
|
|capabilities |Array of Strings |miners which support this SHOULD
|
|
|
provide a list including the String "serverlist"
|
|
|
|=======================================================================
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|colspan=3| template
|
|
|
|Key |Type |Description
|
|
|
|
|
|
|serverlist |Array of Objects |list of servers in this single logical
|
|
|
service
|
|
|
|=======================================================================
|
|
|
|
|
|
If the "serverlist" parameter is provided, clients MAY choose to
|
|
|
intelligently treat the server as part of a larger single logical
|
|
|
service.
|
|
|
|
|
|
Each host Object in the Array is comprised of the following fields:
|
|
|
|
|
|
[cols="",options="header",]
|
|
|
|=======================================================================
|
|
|
|colspan=3| serverlist element
|
|
|
|Key |Type |Description
|
|
|
|
|
|
|uri |String |URI of the individual server; if authentication
|
|
|
information is omitted, the same authentication used for this request
|
|
|
MUST be assumed
|
|
|
|
|
|
|avoid |Number |number of seconds to avoid using this server
|
|
|
|
|
|
|priority |Number |an integer priority of this host (default: 0)
|
|
|
|
|
|
|sticky |Number |number of seconds to stick to this server when used
|
|
|
|
|
|
|update |Boolean |whether this server may update the serverlist
|
|
|
(default: true)
|
|
|
|
|
|
|weight |Number |a relative weight for hosts with the same priority
|
|
|
(default: 1)
|
|
|
|=======================================================================
|
|
|
|
|
|
When choosing which actual server to get the next job from, URIs MUST be
|
|
|
tried in order of their "priority" key, lowest Number first. Where the
|
|
|
priority of URIs is the same, they should be chosen from in random
|
|
|
order, weighed by their "weight" key. Work proposals and submissions
|
|
|
MUST be made to the same server that issued the job. Clients MAY attempt
|
|
|
to submit to other servers if, and only if, the original server cannot
|
|
|
be reached. If cross-server share submissions are desired, services
|
|
|
SHOULD instead use the equivalent domain name system (DNS) features
|
|
|
(RFCs http://tools.ietf.org/html/rfc1794[1794] and
|
|
|
http://tools.ietf.org/html/rfc2782[2782]).
|
|
|
|
|
|
Updates to the Logical Service server list may only be made by the
|
|
|
original server, or servers listed with the "update" key missing or
|
|
|
true. Clients MAY choose to advertise serverlist capability to servers
|
|
|
with a false "update" key, but if so, MUST treat the server list
|
|
|
provided as a subset of the current one, only considered in the context
|
|
|
of this server. At least one server with "update" privilege MUST be
|
|
|
attempted at least once daily.
|
|
|
|
|
|
If the "sticky" key is provided, then when that server is used, it
|
|
|
should be used consistently for at least that many seconds, if possible.
|
|
|
|
|
|
A permanent change in server URI MAY be indicated with a simple
|
|
|
"serverlist" parameter:
|
|
|
|
|
|
`"serverlist":[{"uri": "`http://newserver[`http://newserver`]`"}]`
|
|
|
|
|
|
A temporary delegation to another server for 5 minutes MAY be indicated
|
|
|
likewise:
|
|
|
|
|
|
`"serverlist":[{"uri": "", avoid: 300}, {"uri": "`http://newserver[`http://newserver`]`", "update": false}]`
|
|
|
|
|
|
[[motivation]]
|
|
|
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.
|
|
|
|
|
|
To encourage widespread adoption, this BIP should be a complete superset
|
|
|
of the existing centralized getwork protocol, so pools are not required
|
|
|
to make substantial changes to adopt it.
|
|
|
|
|
|
[[rationale]]
|
|
|
Rationale
|
|
|
~~~~~~~~~
|
|
|
|
|
|
Why allow servers to restrict the complete coinbase and nonce range?
|
|
|
|
|
|
* This is necessary to provide a complete superset of JSON-RPC getwork
|
|
|
functionality, so that pools may opt to enable auditing without
|
|
|
significantly changing or increasing the complexity of their share
|
|
|
validation or mining policies.
|
|
|
* Since noncerange is optional (both for getwork and this BIP), neither
|
|
|
clients nor servers are required to support it.
|
|
|
|
|
|
Why specify "time/*" mutations at all?
|
|
|
|
|
|
* In most cases, these are implied by the
|
|
|
mintime/mintimecur/maxtime/maxtimecur keys, but there may be cases that
|
|
|
there are no applicable minimums/maximums.
|
|
|
|
|
|
What is the purpose of the "prevblock" mutation?
|
|
|
|
|
|
* There are often cases where a miner has processed a new block before
|
|
|
the server. If the server allows "prevblock" mutation, the miner may
|
|
|
begin mining on the new block immediately, without waiting for a new
|
|
|
template.
|
|
|
|
|
|
Why must both "mintime"/"maxtime" and "mintimeoff"/"maxtimeoff" keys be
|
|
|
defined?
|
|
|
|
|
|
* In some cases, the limits may be unrelated to the current time (such
|
|
|
as the Bitcoin network itself; the minimum is always a fixed median
|
|
|
time)
|
|
|
* In other cases, the limits may be bounded by other rules (many pools
|
|
|
limit the time header to within 5 minutes of when the share is submitted
|
|
|
to them).
|
|
|
|
|
|
Is "target" really needed?
|
|
|
|
|
|
* Some pools work with lower targets, and should not be expected to
|
|
|
waste bandwidth ignoring shares that don't meet it.
|
|
|
* Required to be a proper superset of getwork.
|
|
|
* As mining hashrates grow, some miners may need the ability to request
|
|
|
a lower target from their pools to be able to manage their bandwidth
|
|
|
use.
|
|
|
|
|
|
What is the purpose of the "hash" transaction list format?
|
|
|
|
|
|
* Non-mining tools may wish to simply get a list of memory pool
|
|
|
transactions.
|
|
|
* Humans may wish to view their current memory pool.
|
|
|
|
|
|
[[reference-implementation]]
|
|
|
Reference Implementation
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
* http://gitorious.org/bitcoin/libblkmaker[libblkmaker]
|
|
|
* https://gitorious.org/bitcoin/eloipool[Eloipool]
|
|
|
* https://github.com/bitcoin/bitcoin/pull/936/files[bitcoind]
|
|
|
|
|
|
[[see-also]]
|
|
|
See Also
|
|
|
~~~~~~~~
|
|
|
|
|
|
* link:bip-0022.mediawiki[BIP 22: getblocktemplate - Fundamentals]
|
|
|
|
