mining: add precious option to IPC block submission #35300

w0xlt commented at 3:23 AM on May 16, 2026: contributor

This PR adds a precious flag to the IPC Mining submitBlock and submitSolution methods, as suggested in #34644 (review). Built on top #34644.

With this change, IPC mining clients can submit and prefer a block in one IPC call, instead of submitting it over IPC and then using the preciousblock RPC separately.

By default, same-work side blocks keep the existing behavior: submitBlock reports duplicate/inconclusive cases as failure with a reason, while submitSolution continues to return true when ProcessNewBlock accepts or already knows the block.

Includes unit and IPC functional coverage for default behavior, precious reorgs, active-tip no-op submissions, and invalid-block rejection.

refactor: introduce SubmitBlock helper

Introduce a SubmitBlock() helper in node/miner.cpp that wraps ProcessNewBlock submission and captures validation state through the BlockChecked callback.

Route submitSolution through the helper before adding any new IPC method.

No behavior change.

86dd8152dd

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.

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.

3d568cdd4a

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)

Build candidate blocks from BlockTemplate data in the existing coinbase and
submission test, then exercise checkBlock(), submitSolution(), and
submitBlock() against those candidates. submitBlock() uses an isolated IPC
node for cases that would otherwise affect the main submitSolution() and
checkBlock() assertions.

a4ffb68e85

DrahtBot added the label Mining on May 16, 2026

DrahtBot commented at 3:23 AM on May 16, 2026: contributor

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

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35300.

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:

#35081 (consensus: soft fork on testnet4 that fixes the min difficulty blocks exploit by batmanbytes)
#34860 (mining: always pad scriptSig at low heights, drop include_dummy_extranonce by Sjors)
#34806 (refactor: logging: Various API improvements by ajtowns)
#34020 (mining: add getTransactions(ByWitnessID) IPC methods by Sjors)
#33966 (refactor: disentangle miner startup defaults from runtime options by Sjors)
#33922 (mining: add getMemoryLoad() and track template non-mempool memory footprint by Sjors)
#33421 (node: add BlockTemplateCache by ismaelsadeeq)
#29700 (kernel, refactor: return error status on all fatal errors 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 named args for integral literals may be used (e.g. func(x, /*named_arg=*/0) in C++, and func(x, named_arg=0) in Python):

stale_template.submitSolution(ctx, side_solution_block.nVersion, side_solution_block.nTime, side_solution_block.nNonce, side_solution_coinbase.serialize(), False) in test/functional/interface_ipc_mining.py
stale_template.submitSolution(ctx, side_solution_block.nVersion, side_solution_block.nTime, side_solution_block.nNonce, side_solution_coinbase.serialize(), True) in test/functional/interface_ipc_mining.py

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" -> recommend assert_greater_than_or_equal(len(block.vtx), 2)

2026-05-16 04:02:34

w0xlt marked this as a draft on May 16, 2026

mining: add precious IPC block submission option

Thread a precious flag through the Mining IPC submitBlock and submitSolution methods so callers can prefer an already-known same-work block, matching preciousblock-style behavior while preserving the default duplicate handling.

52a4baca81

test: cover precious mining submissions

Add regtest unit coverage for the Mining interface precious flag, checking default duplicate and inconclusive behavior as well as submitBlock and submitSolution preferring a same-work side block when precious is set.

de70a8add4

test: cover precious IPC mining submissions

Extend the IPC mining functional test to exercise the new precious argument for submitBlock and submitSolution, including default same-work side-block behavior and precious reorg behavior.

a02e97d9a2

w0xlt force-pushed on May 16, 2026

DrahtBot added the label CI failed on May 16, 2026

DrahtBot commented at 4:02 AM on May 16, 2026: contributor

🚧 At least one of the CI tasks failed. Task test ancestor commits: https://github.com/bitcoin/bitcoin/actions/runs/25951528963/job/76290253269 LLM reason (✨ experimental): CI failed due to a C++ build error: src/node/miner.cpp would not compile (clang: passing CBlockIndex* where const CBlockIndex& is required in chainman.ActiveChain().Contains).

<details><summary>Hints</summary>

Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.
A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.
An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

</details>

DrahtBot removed the label CI failed on May 16, 2026

Sjors commented at 9:39 AM on May 16, 2026: member

Maybe do this after #34672?

DrahtBot added the label Needs rebase on May 17, 2026

DrahtBot commented at 6:04 PM on May 17, 2026: contributor

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