Provide a node-side block template and submission utility (enable stratum v1/v2 mining protocols)

[dsbaars]

Summary

libbitcoin-server has no way to obtain a block template (candidate block) or to submit a solved block from libbitcoin-node, which blocks any working mining interface. The stratum v2 protocol and channel are stubs, and stratum v1 handlers all return not_implemented. The node already scaffolds a template chaser (chaser_template) and even documents a chase::template_ event "handled by [miners]", but nothing usable is exposed: the event carries only a height, the chaser has no accessor, and its construction methods are stubs. This issue requests exposing a template and submission utility from libbitcoin-node so server mining protocols can build jobs and submit blocks instead of reaching into chain state themselves, and tracks the node dependency for stratum mining. It builds on #1075 (the transaction chaser and unconfirmed pool that feed the template).

Background

The node scaffolds a template chaser (include/bitcoin/node/chasers/chaser_template.hpp, described as "Construct template blocks upon modification of the transaction DAG"), but its public surface is only start(). The work sits in a protected do_transaction(transaction_t) stub and handle_chase. There is no getter for the constructed candidate block.

The design intent is already encoded in the chase event bus (include/bitcoin/node/chase.hpp): chase::transaction is "Issued by 'transaction' and handled by 'template'", and chase::template_ is documented as "A candidate block (template) has been created (height_t). Issued by 'template' and handled by [miners]." So the pipeline is:

chaser_transaction --(chase::transaction)--> chaser_template --(chase::template_)--> [miners]

Two gaps prevent a miner (server protocol) from consuming this:

1. chase::template_ carries only a height_t, not the constructed block, and chaser_template_ is a private member of full_node (include/bitcoin/node/full_node.hpp) with no accessor. A subscriber is notified that a template exists but cannot retrieve it.
2. chaser_template itself is a stub, so the DAG-driven assembly (fee selection, coinbase, witness commitment) is not yet implemented. This is the same v4 scaffolding state as the transaction chaser in Provide a node-side transaction validation utility (dedup pool-context/validate_tx across server protocols) #1075, and it depends on that chaser owning a real unconfirmed pool, since an empty pool yields empty templates.

Current gap in libbitcoin-server

The mining interfaces cannot be implemented against the node today:

• include/bitcoin/server/protocols/protocol_stratum_v2.hpp is a stub: start() only calls the base with a // TODO: subscribe to and handle messages, and it is the one protocol with no rpc subclass.
• include/bitcoin/server/channels/channel_stratum_v2.hpp is documented "custom protocol, not implemented".
• src/protocols/stratum_v1/protocol_stratum_v1.cpp handlers all send_code(error::not_implemented).

None of these can proceed without a node-supplied candidate block (coinbase output space, transaction set, merkle branch, target, prev hash) and a way to submit a found block.

Requested change

Provide, from libbitcoin-node, a single owner for block template construction and block submission that server protocols can call to:

1. Obtain the current template for the confirmed tip: the candidate block with its transaction set, coinbase, witness commitment, computed merkle branch, nbits/target, prev_hash, version, min_ntime, height, and total coinbase value (subsidy plus fees).
2. Expose the coinbase-construction seam that stratum needs: the coinbase split into prefix and suffix around the extranonce region, plus a coinbase_output_max_additional_size allowance, so a mining protocol can inject the extranonce and additional outputs (stratum v2 extended channels) without rebuilding the block.
3. Subscribe to template updates driven by tip change and DAG or fee updates: extend chase::template_ to reference the constructed template (a handle or identifier to fetch, or the block itself) rather than only a height, so a miner can pull the new job on notification.
4. Submit a solved block: validate and organize it through the existing chaser_organize path, returning a code (accepted, stale, or invalid), so the mining protocol can respond to a share or block submission.

This gives a single owner for candidate block construction and block submission, mirroring the single-owner approach requested for standalone transaction validation in #1075.

Downstream follow up (libbitcoin-server)

Once available, flesh out protocol_stratum_v2 and channel_stratum_v2 (and protocol_stratum_v1) to build jobs from the node template, serve them over the wire, validate submitted shares against target, and submit solved blocks through the node utility. This is the node half of the stratum work. The transport half (binary framing plus the stratum v2 Noise handshake, which needs ChaCha20-Poly1305, HKDF, and ellswift ECDH added to libbitcoin-system) is tracked separately.

Relationship to #1075

This is the second stage of the same mining pipeline. #1075 covers chaser_transaction (the unconfirmed pool and standalone tx validation); this covers chaser_template (candidate block construction) and block submission, which consume that pool. #1075 can and should land first, because without a real pool the template is empty. Both follow the same pattern: move the logic into a node-side utility beside the chaser that owns it, and let server protocols call through.

Scope decision needed

Whether this issue covers:

• only the read and submit API (a getter over whatever chaser_template currently builds, plus a chaser_organize-backed submit), which unblocks the server mining protocols against the existing scaffolding; or
• also the full chaser_template implementation (DAG-driven fee-optimal selection, coinbase and witness commitment assembly), which depends on the Provide a node-side transaction validation utility (dedup pool-context/validate_tx across server protocols) #1075 pool being real.

Also to decide: whether to shape the API generically (a getblocktemplate-style structure) or tailored to the stratum coinbase prefix and suffix plus extranonce split, and whether to eventually expose this as the Stratum V2 Template Distribution Protocol (node acting as an SV2 Template Provider to external pool software) versus an internal API consumed only by the in-process stratum protocols. The read and submit API can land first regardless of that direction.

[thecodefactory]

This would be great. I believe a focus on mining is tentatively slated for libbitcoin ~v5, but if someone is able to make progress in the meantime ... 🚀

[evoskuil]

Right, a tx pool is explicitly out of scope for v4, which is the primary prerequisite for the template chaser, which is itself the primary prerequisite for public mining interfaces. The mining interface stubs exist to work out the shape of the recent interface design work.