Skip to content

mining: add precious option to IPC block submission#35300

Draft
w0xlt wants to merge 6 commits into
bitcoin:masterfrom
w0xlt:ipc-submit-block-precious
Draft

mining: add precious option to IPC block submission#35300
w0xlt wants to merge 6 commits into
bitcoin:masterfrom
w0xlt:ipc-submit-block-precious

Conversation

@w0xlt

@w0xlt w0xlt commented May 16, 2026

Copy link
Copy Markdown
Contributor

This PR adds a precious flag to the IPC Mining submitBlock and submitSolution methods, as suggested in #34644 (comment). 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.

w0xlt added 3 commits May 15, 2026 11:14
@w0xlt
refactor: introduce SubmitBlock helper
86dd815 
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.
@w0xlt
mining: add submitBlock IPC method to Mining interface
3d568cd 
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.
@w0xlt
test: add IPC submitBlock functional test
a4ffb68 
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.
@DrahtBot

DrahtBot commented May 16, 2026 •
edited
Loading

Copy link
Copy Markdown
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 w0xlt marked this pull request as draft May 16, 2026 03:23
w0xlt added 3 commits May 15, 2026 21:01
@w0xlt
mining: add precious IPC block submission option
52a4bac 
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.
@w0xlt
test: cover precious mining submissions
de70a8a 
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.
@w0xlt
test: cover precious IPC mining submissions
a02e97d 
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.
@w0xlt w0xlt force-pushed the ipc-submit-block-precious branch from 4573232 to a02e97d Compare May 16, 2026 04:02
@DrahtBot

DrahtBot commented May 16, 2026

Copy link
Copy Markdown
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).

Hints

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.

@w0xlt w0xlt mentioned this pull request May 16, 2026
Merged
@Sjors

Sjors commented May 16, 2026

Copy link
Copy Markdown
Member

Maybe do this after #34672?

This was referenced May 17, 2026
Draft
Merged
Merged
Merged
Merged
Draft
Closed
Draft
@DrahtBot

DrahtBot commented May 17, 2026

Copy link
Copy Markdown
Contributor

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

@Sjors Sjors mentioned this pull request May 19, 2026
Open
13 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

Mining Needs rebase

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@w0xlt @DrahtBot @Sjors