mining: add reason/debug to `submitSolution` and unify with `submitBlock`

w0xlt commented at 9:40 pm on February 25, 2026: contributor

Built on top of #34644 Preferred to open a separate PR to keep the other one focused on submitBlock.

This PR:

Extracts a shared ProcessBlock helper that wraps ProcessNewBlock with SubmitBlockStateCatcher to capture BlockValidationState
Adds reason and debug output parameters to submitSolution, matching submitBlock
Makes both methods delegate to the same helper, eliminating duplicated logic

mining: add submitBlock IPC method to Mining interface

Add a submitBlock method to the Mining IPC interface, similar to the
submitblock RPC. This accepts a fully assembled block, validates it, and
if accepted as new, processes it into chainstate.

Unlike the submitblock RPC, this method does NOT auto-add the coinbase
witness nonce (via UpdateUncommittedBlockStructures). Since this is a new
interface and SegWit has been active for years, callers must provide a
fully-formed block including the coinbase witness nonce when a witness
commitment is present.

This is needed for Stratum v2 Job Declarator Server (JDS), where accepted
solutions may correspond to jobs not tied to a Bitcoin Core BlockTemplate.
JDS receives PushSolution fields and reconstructs full blocks; without an
IPC submitBlock method, final submission requires the submitblock RPC.

The method returns detailed status (reason/debug strings) matching the
checkBlock pattern, giving callers enough information to handle
validation failures.

6227404059

test: add IPC submitBlock functional test

Test the new Mining.submitBlock IPC method:
- Invalid block (bad version) returns failure with reason
- Valid block (with a real mempool tx) is accepted and propagates
- Duplicate block returns failure with "duplicate" reason
- Witness commitment without coinbase witness nonce is rejected
  (bad-witness-nonce-size), confirming no auto-fix behavior
- submitBlock then submitSolution: duplicate is accepted (submitSolution
  returns true for already-known blocks)
- submitSolution then submitBlock interaction (duplicate)

The test bootstraps a candidate block with createNewBlock(), mutates and
serializes it, then submits it through Mining.submitBlock instead of
BlockTemplate.submitSolution. This exercises the complete-block submission
path and approximates the Sv2 JDS use case.

354538db36

refactor: extract ProcessBlock helper for submitSolution and submitBlock

Move SubmitBlockStateCatcher and the ProcessNewBlock + validation
interface registration logic into a shared ProcessBlock() helper.
Both submitSolution and submitBlock now use this common code path.

No behavior change.

9e12fb4989

mining: add reason and debug output to submitSolution

Add reason and debug output parameters to submitSolution, matching
submitBlock. This relays the specific failure reason (e.g.
"bad-version(...)", "bad-witness-nonce-size", "duplicate") to callers
instead of just a bool.

This is a non-breaking capnp schema change: existing clients that
only read the bool result field continue to work.

15eea58744

refactor: move result handling into ProcessBlock helper

Fold the duplicate/inconclusive/invalid result handling from
submitSolution and submitBlock into the ProcessBlock helper, so
both methods become simple one-line delegations.

No behavior change.

083d5c077b

DrahtBot added the label Mining on Feb 25, 2026

DrahtBot commented at 9:41 pm on February 25, 2026: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Reviews

See the guideline for information on the review process. A summary of reviews will appear here.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#34662 (ci: use LLVM/Clang 22 in tidy job by fanquake)
#34422 (Update libmultiprocess subtree to be more stable with rust IPC client by ryanofsky)
#33922 (mining: add getMemoryLoad() and track template non-mempool memory footprint by Sjors)
#29700 (kernel, refactor: return error status on all fatal errors by ryanofsky)
#29409 (multiprocess: Add capnp wrapper for Chain interface by ryanofsky)
#10102 (Multiprocess bitcoin by ryanofsky)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

LLM Linter (✨ experimental)

Possible places where comparison-specific test macros should replace generic comparisons:

test/functional/interface_ipc_mining.py: “assert len(block.vtx) >= 2, "Block should include at least the coinbase and the mempool tx"” -> use assert_greater_than_or_equal(len(block.vtx), 2, “Block should include at least the coinbase and the mempool tx”)

2026-02-25 21:41:08

w0xlt marked this as a draft on Feb 25, 2026

in src/ipc/capnp/mining.capnp:39 in 083d5c077b

35@@ -35,7 +36,7 @@ interface BlockTemplate $Proxy.wrap("interfaces::BlockTemplate") {
36     getTxSigops @4 (context: Proxy.Context) -> (result: List(Int64));
37     getCoinbaseTx @5 (context: Proxy.Context) -> (result: CoinbaseTx);
38     getCoinbaseMerklePath @6 (context: Proxy.Context) -> (result: List(Data));
39-    submitSolution @7 (context: Proxy.Context, version: UInt32, timestamp: UInt32, nonce: UInt32, coinbase :Data) -> (result: Bool);
40+    submitSolution @7 (context: Proxy.Context, version: UInt32, timestamp: UInt32, nonce: UInt32, coinbase :Data) -> (reason: Text, debug: Text, result: Bool);

Sjors commented at 6:21 pm on February 27, 2026:

For this not to be a breaking change, I suspect the new arguments need to go last?

DrahtBot added the label Needs rebase on Mar 3, 2026

DrahtBot commented at 6:30 pm on March 3, 2026: contributor

🐙 This pull request conflicts with the target branch and needs rebase.

mining: add reason/debug to submitSolution and unify with submitBlock #34672

Reviews

Conflicts

LLM Linter (✨ experimental)

mining: add reason/debug to `submitSolution` and unify with `submitBlock` #34672