getblocktemplate

In the ordinary mode=template setting, Peter’s program receives information such as the predecessor block, transactions and the permitted reward. This is a proposed assignment, not a block already found. The software must construct coinbase, the special first transaction assigning the reward, and finish assembling the block. The header is a compact summary of the block’s data. The software then searches for a hash, a numerical cryptographic fingerprint of that header, that meets the mining target and provides Proof of Work, evidence of the computational work. getblocktemplate itself takes no payout address and starts no mining-machine calculations. A successful response does not yet mean Peter is mining. [1]

Imagine the node sends data in a form Peter’s program cannot understand. The request therefore declares supported rules in the rules field. Bitcoin Core v29.0, the version checked here, requires segwit, and signet as well for the Signet test network. Among other things, SegWit changes how transaction-verification data is handled. Adding the right word is not enough: the software must actually process it correctly. capabilities announces other interface abilities and does not replace rules. Exact requirements depend on the implementation and version in use. [2]

The data field contains the complete transaction arranged for transfer between programs. This arrangement is called serialization. The bytes, the basic units of this data, are written in hexadecimal using the digits 0–9 and the letters a–f. The response also includes short transaction identifiers. Under the technical specification BIP 145, txid is calculated without witness data, whereas hash includes it. Witness contains items such as signatures proving authorization to spend. The main Merkle root, the combined transaction fingerprint in the block header, uses txid rather than the witness hash. Mixing up these fields is more than a naming mistake: it can produce an incorrect combined fingerprint and invalidate the assembled block. [3]

Peter need not bombard the node with requests asking whether anything has changed. Long polling keeps a request open until the server wants to replace the previous information. The program takes longpollid and sends it back unchanged. The value tells the server which update the program is waiting for. The program must not try to infer a meaning from its characters. BIP 22 calls for a long request timeout. Repeated incomplete or invalid responses require a delay between attempts, not an immediate retry loop. Quiet waiting is therefore not, by itself, an outage. [4]

Even an ordinary repeated request does not guarantee newly selected contents. Bitcoin Core v29.0 keeps a prepared template in a cache. It rebuilds it when the predecessor changes, or when the mempool, the local collection of unconfirmed transactions, has changed and more than five seconds have passed since preparation. It can update the header time separately. Peter may thus receive the same transaction selection again; that does not mean the node is stuck. This version-specific behavior also gives no promise that each call creates a unique mining job. [2]

Peter has changed how he builds a block and wants to catch mistakes before starting an expensive search. In proposal mode he supplies the complete block as hexadecimal in data. Bitcoin Core v29.0 also checks the Merkle root, but does not require valid Proof of Work, the evidence of computational work, to have been found already. If the draft does not build on the last block of the chain the node currently follows, it returns inconclusive-not-best-prevblk. That means a prerequisite for this check is missing; it is not a complete validity assessment. The preliminary check does not broadcast the block either. [2]

Once the software finds the necessary proof of work, it can submit the full block through submitblock. hexdata carries the entire serialized block in hexadecimal, not merely its header or fingerprint. Bitcoin Core 29 documentation specifies null on acceptance and otherwise a textual result under the specification. The optional second parameter, dummy, is ignored; it does not set the reward. Acceptance by a node does not guarantee permanent confirmation: subsequent chain developments may change which branch remains the main one. [5]

A newly started node may not yet have downloaded and verified the history it needs. On mainnet, Bitcoin Core v29.0 refuses to issue a template with no connected peers or during initial synchronization, called IBD (initial block download). This concerns the node’s readiness to work with the current network, not rejection of a particular block. Troubleshooting therefore distinguishes a waiting long poll, an unready node and the outcome of a proposal check. All may look like “I have no new work,” but each calls for a different response. [2]