getblocktemplate is a JSON-RPC method for obtaining candidate-block assembly data or assessing a proposal. This description follows Bitcoin Core 29; implementation-specific behavior does not automatically apply to every server using the protocol.
The default mode is template. The response supplies data to mining software, not a discovered proof of work. This request takes no payout-address parameter; constructing coinbase and searching for a solution are subsequent steps. [Bitcoin Core 29 — getblocktemplate RPC]
Bitcoin Core v29.0 requires segwit in request rules, and signet on the signet network. Writing a string does not replace implementing the relevant rules. The capabilities field describes interface features and cannot replace mandatory rules. [Bitcoin Core v29.0 — Mining RPC implementation]
BIP 145 distinguishes txid excluding witness from hash including witness. The primary Merkle root uses txid, not the witness hash. The data field carries the serialized transaction in hexadecimal; its identifier alone is not its complete bytes. [BIP 145 — SegWit template fields]
The client returns the received longpollid in its next waiting request. BIP 22 says not to assume a particular meaning, so a portable client should not parse it as a format of its own. Long polling needs a long timeout and delays after repeated failures, not a tight retry loop. [BIP 22 — Long polling]
Bitcoin Core v29.0 caches the template: it changes when the predecessor changes, or when the mempool changes more than five seconds after creation. Header time is updated separately. Each call therefore need not include the newest transaction or create independent mining work. [Bitcoin Core v29.0 — Mining RPC implementation]
In proposal mode, data carries the entire candidate block in hexadecimal. Core checks the Merkle root but does not require valid proof of work. inconclusive-not-best-prevblk means the predecessor differs from the current tip; it is not a full assessment of proposal validity. [Bitcoin Core v29.0 — Mining RPC implementation]
submitblock receives the complete block as hexdata, not just a hash. Bitcoin Core 29 returns null on acceptance; otherwise it may return a result string. It ignores optional dummy. Node acceptance does not guarantee permanent confirmation in the active chain. [Bitcoin Core 29 — submitblock RPC]
On mainnet, Bitcoin Core v29.0 refuses to provide a template without connected peers or during initial block download. This describes node readiness, not a particular block’s invalidity. Distinguish these errors from validation rejection reasons and from normally waiting long polling. [Bitcoin Core v29.0 — Mining RPC implementation]
For the clearest picture, read this entry together with Block Template, Mining, Stratum V2, Extranonce. The reverse links also lead from Solo Mining, Job Negotiation.