kernel: let callers create the block manager #36854

The kernel creates its block storage inside btck_chainstate_manager_create, configures it through the chainstate manager's options and reads blocks through the chainstate manager. Pruning (#35627) needs block storage that the caller can configure, keep and prune directly.

This adds btck_BlockManagerOptions and btck_BlockManager. btck_chainstate_manager_create takes a block manager and keeps a shared reference to it, so either handle can be destroyed first. A block manager can be passed to only one chainstate manager, and a failed creation still uses it up unless the contexts differ. btck_block_read and btck_block_spent_outputs_read take the block manager, and block tree entries are valid for its lifetime, which can be longer than the chainstate manager's.

Changes for callers:

• btck_chainstate_manager_options_create no longer takes a blocks directory.
• btck_chainstate_manager_options_set_wipe_dbs is replaced by btck_block_manager_options_update_wipe_block_tree_db and btck_chainstate_manager_options_update_wipe_chainstate_db. The block tree db is wiped when the block manager is created, and wiping it also wipes the chainstate db, which the old function required anyway.
• btck_chainstate_manager_options_update_block_tree_db_in_memory moves to the block manager options.
• Both options objects take the same total database cache, and each uses its own share.

Based on #36739. Draft until it is merged. Feedback on the API is welcome in the meantime.

<!--e57a25ab6845829454e8d69fc972939a-->

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

<!--006a51241073e994b41acfe9ec718e94-->

External sites

• Code coverage & benchmarks: https://corecheck.dev/bitcoin/bitcoin/pulls/36854
• Ralph review <img src=https://review.fish.foo/assets/bitcoin/bitcoin/36854.png alt="Ralph review status"> https://git.fish.foo/bitcoin/bitcoin/pulls/36854#author-ralph

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

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

<!--5faf32d7da4f0f540f40219e4f7537a3-->

LLM Linter (✨ experimental)

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

• src/test/kernel/test_kernel.cpp: BOOST_CHECK_THROW(BlockManagerOptions(context, data_dir, blocks_dir), std::runtime_error) → Prefer BOOST_CHECK_EXCEPTION with a HasReason predicate that checks the failure message.
• src/test/kernel/test_kernel.cpp: BOOST_CHECK_THROW(ChainstateManagerOptions(context, ""), std::runtime_error) and the null-path equivalent → Prefer BOOST_CHECK_EXCEPTION with a HasReason predicate.
• src/test/kernel/test_kernel.cpp: BOOST_CHECK_THROW(ChainMan(context, chainman_opts, blockman), std::runtime_error) for the context mismatch and already-used block manager → Prefer BOOST_CHECK_EXCEPTION with a HasReason predicate.
• src/test/kernel/test_kernel.cpp: BOOST_CHECK_THROW(blockman.ReadBlockSpentOutputs(tip), std::runtime_error) → Prefer BOOST_CHECK_EXCEPTION with a HasReason predicate.

^{2026-11-13 15:09:15}