#35300 mining: add precious option to IPC block submission

Adds an optional `precious` parameter to the Mining IPC `submitBlock` and `BlockTemplate.submitSolution` methods so external miners can submit and prioritize a block against competing equal-work tips in a single call. To support this atomically, `PreciousBlock` in validation is updated to execute under `m_chainstate_mutex` without releasing the lock and reports whether the block was successfully connected to the active chain. The change also introduces new Cap'n Proto interface ordinals and deprecates the prior method signatures with explicit error responses.

Problem: External mining clients communicating over IPC cannot prioritize a mined block over a same-work competing block in one operation; they must make a subsequent `preciousblock` RPC call. This multi-call sequence requires extra round-trips and introduces race conditions with concurrent chain activations.

Evidence of importance:

• PR description: '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.'
• Commit 64e5010615: 'Hold m_chainstate_mutex while marking a block precious, activating the best chain, and capturing whether the block is in the active chain... Return this status through the connected output so mining submissions can inspect the result without racing another chain activation.'

Scope: Touches Cap'n Proto IPC interface definitions, introducing new method IDs and stubbing deprecated ones with exceptions. Includes a test refactoring moving proof-of-work grinding loops across multiple test suites into a shared `GrindBlock` helper.

Risk of a mistake: medium (validation, rpc_api, other). Modifies locking and execution flow in chainstate activation and PreciousBlock, which could cause deadlocks or improper chain tip selection if locking guarantees fail.

Changed since the previous assessment: No substantial functional or architectural changes; the scope and implementation remain consistent with the earlier version.

Paused · Waiting on author

Open objections from enirox001 with no author reply for 9 days; review would repeat what has been asked.

Waiting on (from the thread read):

• author: answer enirox001's question regarding downstream client demand and review the suggested check simplification 2026-10-23

Strong

substantive support, no open objection (Sjors, pablomartin4btc, johnnyasantoss, ViniciusCestarii, 0xB10C, enirox001)

Thread notes: Added enirox001 to participants with a Concept ACK, a code simplification suggestion, and a question regarding downstream client demand to justify IPC compatibility costs.

Objections, suggestions, and questions:

Support:

• Sjors (member) (Concept ACK, 2026-07-24) [read]: rational for miners to prefer their own block for p2p relay, though noted game-theoretic caveats around building on it
• pablomartin4btc (member) (Concept ACK, 2026-07-24): allows IPC mining clients atomically submit and prefer a same-work block in one go instead of a separate preciousblock RPC call
• johnnyasantoss (none) (Concept ACK, 2026-09-25): unlikely to lose reward from working on a template on top of your own past work; intuitively precious=true makes a lot of sense
• ViniciusCestarii (contributor) (Concept ACK, 2026-09-25): odds of finding the next block are the same on either side, only the payout differs: 2 blocks on your own tip vs 1 on the other
• 0xB10C (member) (2026-09-29): agrees that mining on your own block maximizes winnings since you can win both blocks with unchanged odds of finding the next block
• enirox001 (contributor) (Concept ACK, 2026-10-23) [read: Mining.submitBlock, BlockTemplate.submitSolution]: allows an IPC mining client to submit a block and request that it be preferred over a competing same-work block in one call

Participants:

• Sjors (member, objection, 5 statements 2026-05-16 to 2026-07-24): Concept ACK on IPC precious submission, but objected to duplicate return status behavior
• pablomartin4btc (member, support, 5 statements 2026-07-24 to 2026-07-24): Concept ACK, noting atomic block submission and preference in one IPC call
• ViniciusCestarii (contributor, support, 1 statements 2026-09-25 to 2026-09-25): Concept ACK, argued that mining odds are unchanged while payout is higher when preferring own tip
• johnnyasantoss (none, support, 1 statements 2026-09-25 to 2026-09-25): Concept ACK, argued that working on a template atop own past work is rational and unlikely to lose rewards
• 0xB10C (member, support, 1 statements 2026-09-29 to 2026-09-29): agreed that mining on own block maximizes payout without changing chances of finding next block
• enirox001 (contributor, support, 2 statements 2026-10-23 to 2026-10-23): Concept ACK, asked about downstream use cases to justify IPC ordinal compatibility costs, and suggested simplifying inconclusive checks

541 lines under test/bench/ci.

• src/test/miner_tests.cpp +267/-15
• test/functional/interface_ipc_mining.py +189/-2
• src/node/block_template_manager.cpp +49/-22
• src/interfaces/mining.h +34/-7
• doc/release-notes-35300.md +28/-0
• src/validation.cpp +18/-7
• src/test/util/mining.cpp +11/-9
• src/validation.h +14/-3
• src/test/headers_sync_chainwork_tests.cpp +2/-11
• src/ipc/capnp/mining.capnp +8/-2
• src/node/interfaces.cpp +4/-4
• src/test/blockencodings_tests.cpp +4/-4
• src/test/util/mining.h +7/-0
• src/node/block_template_manager.h +4/-2
• src/test/fuzz/util.h +2/-4
• src/test/validation_block_tests.cpp +2/-4
• src/rpc/blockchain.cpp +4/-1
• src/test/peerman_tests.cpp +2/-2
• src/test/util/setup_common.cpp +2/-2

The short text the ranking pass compares across PRs.

This pull request adds an optional precious argument to the IPC Mining submitBlock and submitSolution interfaces. External mining software can now submit a block and prioritize it against equal-work tips in a single call instead of issuing a subsequent preciousblock RPC. To prevent activation race conditions, validation's PreciousBlock now holds the chainstate mutex throughout reorg evaluation and reports whether the block connected. The PR also deprecates older Cap'n Proto interface ordinals with explicit client update errors and deduplicates test proof-of-work grinding.

P2 · new feature

Adds atomic block preference on submission for external miners using IPC, eliminating round-trips and race conditions against competing equal-work chain tips. Downstream miners currently must make a separate preciousblock RPC call and risk racing concurrent chain activations.

Membership: Labeled Mining; updates interfaces::Mining, block template management, and mining IPC block submission.

Factors: security/stability 1, bug 0, performance 1, user value 2, leverage 1