#35300 mining: add precious option to IPC block submission

• Let external mining software atomically submit and prefer a locally mined same-work block over IPC
• Avoid race conditions from issuing a separate preciousblock RPC call

This PR adds an optional `precious` argument to `Mining.submitBlock` and `BlockTemplate.submitSolution` in the IPC mining interface. It allows external mining clients to submit a block and trigger `PreciousBlock` preference atomically. To support this safely, `Chainstate::ActivateBestChain_` is extracted as a lock-held helper and `Chainstate::PreciousBlock` is modified to report whether the block was connected before releasing `m_chainstate_mutex`.

Problem: Currently, external mining software submitting blocks over IPC must make a separate `preciousblock` RPC call to prefer a competing block with identical work, which introduces a race condition against concurrent chain activations.

P3 · new feature

• P3 because miners can atomically prefer a same-work block without coordinating across separate calls
• Worthwhile convenience for IPC mining setups but does not affect template generation performance

P3 because it adds an optional feature to IPC block submission. As pablomartin4btc noted, it 'allows IPC mining clients atomically submit and prefer a same-work block in one go instead of a separate preciousblock RPC call'. While helpful for Stratum v2 template providers, it is an incremental API enhancement.

Membership: Modifies interfaces::Mining, src/node/miner.cpp, and IPC block submission handling.

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

P3 · new feature

• P3 because mining clients no longer need a parallel RPC session just to handle precious blocks
• Incremental addition to the mining interface without broader architectural impact

P3 because it updates the IPC mining protocol schema to support the precious flag on submitBlock and submitSolution, improving process-separated mining interfaces.

Membership: Changes src/ipc/capnp/mining.capnp and adds IPC functional test coverage.

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

P3 · cleanup

• P4 because the chain activation refactor only serves callers that already hold the chainstate lock
• Internal adjustment that does not change consensus safety or validation throughput

P3 because it refactors Chainstate locking helpers. As commit 42d48e7760 explains, it moves 'the lock-held body of ActivateBestChain() into an internal helper without changing behavior. This allows callers that already hold m_chainstate_mutex to run activation without releasing and reacquiring it'.

Membership: Modifies Chainstate::PreciousBlock locking and extracts ActivateBestChain_ in src/validation.cpp.

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

• Needs rebase against current master due to merge conflicts
• Author has been silent since July 2026

The PR has merge conflicts with master and has been inactive for over 50 days.

Author status: silent since 2026-07-24

Open concerns:

• Sjors questioned whether activating an already-known duplicate block should return success or continue returning 'duplicate'

• Concept approval for handling precious blocks directly over IPC (Sjors, pablomartin4btc)
• Questions whether duplicate status should still be returned if precious is requested (Sjors)
• Recommends splitting and reorganizing the oversized unit test (Sjors)
• Considers the internal chain activation refactoring a clean prerequisite (pablomartin4btc)

Mild: Concept ACKs from Sjors and pablomartin4btc, but Sjors's comment on duplicate return semantics remains unanswered.

Reviewers favor the feature for IPC mining clients, but Sjors raised a nonblocking interface concern regarding whether duplicate return status should be suppressed when precious is true, which has received no author reply.

• 2026-07-24 Sjors: 'Concept ACK' and 'mmm, I don't think `precious` should change the behavior if the block is duplicate, so just return `duplicate`?'
• 2026-07-24 pablomartin4btc: 'Concept ACK. Adding precious=true to submitBlock and submitSolution, allows IPC mining clients atomically submit and prefer a same-work block in one go...'

Objections:

Support:

• pablomartin4btc: Allows IPC mining clients to atomically submit and prefer a same-work block in one go instead of a separate preciousblock RPC call
• Sjors: Concept ACK for preferring miner's own block during p2p relay, though noted game-theoretic caveats

Participants: Sjors (objection), pablomartin4btc (support)

State derived from the lists: nonblocking objection open (Sjors)

Review verdicts (DrahtBot): 0

• Concept ACK: Sjors, pablomartin4btc

481 lines under test/bench/ci.

• src/test/miner_tests.cpp +252/-11
• test/functional/interface_ipc_mining.py +146/-2
• src/node/miner.cpp +47/-23
• src/validation.cpp +18/-7
• src/interfaces/mining.h +15/-8
• doc/release-notes-35300.md +20/-0
• src/test/util/mining.cpp +10/-8
• src/validation.h +14/-3
• src/test/headers_sync_chainwork_tests.cpp +2/-11
• src/node/interfaces.cpp +4/-4
• src/test/blockencodings_tests.cpp +4/-4
• src/test/util/mining.h +7/-0
• src/test/fuzz/util.h +2/-4
• src/test/validation_block_tests.cpp +2/-4
• src/node/miner.h +3/-2
• src/ipc/capnp/mining.capnp +2/-2
• src/test/blockfilter_index_tests.cpp +2/-2
• src/test/peerman_tests.cpp +2/-2
• src/test/util/setup_common.cpp +2/-2
• src/rpc/blockchain.cpp +2/-1

PR 35300 adds an optional precious argument to the IPC Mining submitBlock and submitSolution interfaces. This allows IPC mining clients like Stratum v2 template providers to prefer same-work side blocks in a single atomic submission without calling the preciousblock RPC separately. To achieve this, it extracts an ActivateBestChain_ lock-held helper and updates Chainstate::PreciousBlock to return connection status while holding m_chainstate_mutex. Reviewers gave Concept ACKs, though Sjors raised an unaddressed question about duplicate return semantics. The PR is currently in draft and needs a rebase.