getblocktemplate

Back to mining

Changed params/results since v30.2 Changed behavior since v30.2

Summary

If the request parameters include a 'mode' key, that is used to explicitly select between the default 'template' request or a 'proposal'.

Description

If the request parameters include a 'mode' key, that is used to explicitly select between the default 'template' request or a 'proposal'. It returns data needed to construct a block to work on. For full specification, see BIPs 22, 23, 9, and 145: https://github.com/bitcoin/bips/blob/master/bip-0022.mediawiki https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki#getblocktemplate_changes https://github.com/bitcoin/bips/blob/master/bip-0145.mediawiki

Changed behavior since v30.2

Cadence, AuxPoW, and qbit version-rolling semantics diverge from upstream behavior.

Notes

  • Structural diffs may be smaller than the behavioral delta.
  • qbit permissionless templates include versionrollingmask for BIP310 Stratum pool integration; zero disables rolling for non-BIP9 or AuxPoW template versions.

Change Buckets

  • Changed params/results since v30.2
  • Changed behavior since v30.2

Arguments

  • template_request (OBJ, required): Format of the template
  • mode (STR): This must be set to "template", "proposal" (see BIP 23), or omitted
  • capabilities (ARR): A list of strings
    • str (STR): client side supported feature, 'longpoll', 'coinbasevalue', 'proposal', 'serverlist', 'workid'
  • rules (ARR, required): A list of strings
    • segwit (STR, required): (literal) indicates client side segwit support
    • str (STR): other client side supported softfork deployment
  • longpollid (STR): delay processing request until the result would vary significantly from the "longpollid" of a prior template
  • data (STR_HEX): proposed block data to check, encoded in hexadecimal; valid only for mode="proposal"

Results

  • value (NONE): No description.
  • value (STR): According to BIP22
  • value (OBJ): No description.
  • version (NUM): The preferred block version
  • rules (ARR): specific block rules that are to be enforced
    • value (STR): name of a rule the client must understand to some extent; see BIP 9 for format
  • vbavailable (OBJ_DYN): set of pending, supported versionbit (BIP 9) softfork deployments
    • rulename (NUM): identifies the bit number as indicating acceptance and readiness for the named softfork rule
  • capabilities (ARR): No description.
    • value (STR): A supported feature, for example 'proposal'
  • vbrequired (NUM): bit mask of versionbits the server requires set in submissions
  • versionrollingmask (STR_HEX): qbit-recommended BIP310 version-rolling mask for permissionless Stratum work, or 00000000 when version rolling is disabled for this template
  • previousblockhash (STR): The hash of current highest block
  • transactions (ARR): contents of non-coinbase transactions that should be included in the next block
    • value (OBJ): No description.
    • data (STR_HEX): transaction data encoded in hexadecimal (byte-for-byte)
    • txid (STR_HEX): transaction hash excluding witness data, shown in byte-reversed hex
    • hash (STR_HEX): transaction hash including witness data, shown in byte-reversed hex
    • depends (ARR): array of numbers
      • value (NUM): transactions before this one (by 1-based index in 'transactions' list) that must be present in the final block if this one is
    • fee (NUM): 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
    • sigops (NUM): total SigOps cost, as counted for purposes of block limits; if key is not present, sigop cost is unknown and clients MUST NOT assume it is zero
    • weight (NUM): total transaction weight, as counted for purposes of block limits
  • coinbaseaux (OBJ_DYN): data that should be included in the coinbase's scriptSig content
    • key (STR_HEX): values must be in the coinbase (keys may be ignored)
  • coinbasevalue (NUM): maximum allowable input to coinbase transaction, including the generation award and transaction fees (in satoshis)
  • longpollid (STR): an id to include with a request to longpoll on an update to this template
  • target (STR): The hash target
  • mintime (NUM_TIME): The minimum timestamp appropriate for the next block time, expressed in UNIX epoch time. Adjusted for the proposed BIP94 timewarp rule.
  • mutable (ARR): list of ways the block template may be changed
    • value (STR): A way the block template may be changed, e.g. 'time', 'transactions', 'prevblock'
  • noncerange (STR_HEX): A range of valid nonces
  • sigoplimit (NUM): limit of sigops in blocks
  • sizelimit (NUM): limit of block size
  • weightlimit (NUM, optional): limit of block weight
  • curtime (NUM_TIME): current timestamp in UNIX epoch time. Adjusted for the proposed BIP94 timewarp rule.
  • bits (STR): compressed target of next block
  • height (NUM): The height of the next block
  • signet_challenge (STR_HEX, optional): Only on signet
  • default_witness_commitment (STR_HEX, optional): a valid witness commitment for the unmodified block template

Examples

qbit-cli getblocktemplate '{"rules": ["segwit"]}'

curl --user myusername --data-binary '{"jsonrpc": "2.0", "id": "curltest", "method": "getblocktemplate", "params": [{"rules": ["segwit"]}]}' -H 'content-type: application/json' http://127.0.0.1:8352/