kernel: Add function for setting prune target in ChainstateManagerOptions #36630

pull rahadbhuiya wants to merge 2 commits into bitcoin:master from rahadbhuiya:kernel-prune-target changing 4 files +65 −0

rahadbhuiya commented at 5:28 PM on October 23, 2026: none
Motivation & Background

Currently, the libbitcoinkernel C API does not provide a way to configure block pruning on tck_ChainstateManagerOptions. Even though the underlying ode::BlockManager::Options and ode::ChainstateLoadOptions structures support pruning, libbitcoinkernel callers cannot pass a prune target.

Consequently, trying to open an existing pruned node's data directory fails during ode::LoadChainstate() with: [error] Failed to load chain state from your data directory: You need to rebuild the database using -reindex to go back to unpruned mode. because chainman.m_blockman.m_have_pruned is true while options.prune defaults to false.

Description of Changes
1. C API (src/kernel/bitcoinkernel.h):
  
  Added tck_chainstate_manager_options_set_prune_target(opts, prune_target_bytes).
  
  Exposed tck_PRUNE_TARGET_MANUAL (matching ode::BlockManager::PRUNE_TARGET_MANUAL) for manual pruning (-prune=1).
  
  Exposed tck_MIN_PRUNE_TARGET_BYTES (550 MiB, matching MIN_DISK_SPACE_FOR_BLOCK_FILES).
2. Kernel Implementation (src/kernel/bitcoinkernel.cpp):
  
  Implemented tck_chainstate_manager_options_set_prune_target().
  
  Validates that prune_target_bytes is either 0 (unpruned), tck_PRUNE_TARGET_MANUAL, or >= btck_MIN_PRUNE_TARGET_BYTES.
  
  Sets m_blockman_options.prune_target = prune_target_bytes and m_chainstate_load_options.prune = (prune_target_bytes > 0) under LOCK(opts.m_mutex).
3. C++ Wrapper & Tests:
  
  Added SetPruneTarget() in src/kernel/bitcoinkernel_wrapper.h.
  
  Added boundary tests in src/test/kernel/test_kernel.cpp (verifying rejection of < 550_MiB, acceptance of minimum, manual, and unpruned values).
Fixes #35627.

kernel: Add function for setting prune target in ChainstateManagerOptions

Currently, libbitcoinkernel's C API does not expose any mechanism to
configure the block pruning target on btck_ChainstateManagerOptions,
even though the underlying node::BlockManager::Options and
node::ChainstateLoadOptions fully support pruning. Consequently,
attempting to use libbitcoinkernel with an existing pruned datadir
fails during LoadChainstate() with an error directing the user to
reindex.

Introduce btck_chainstate_manager_options_set_prune_target() to allow
configuring the prune target on btck_ChainstateManagerOptions.

- Disabling pruning is represented by 0 (the default).
- Manual pruning is represented by btck_PRUNE_TARGET_MANUAL (matching
  node::BlockManager::PRUNE_TARGET_MANUAL).
- Automatic pruning requires at least btck_MIN_PRUNE_TARGET_BYTES (550 MiB,
  matching MIN_DISK_SPACE_FOR_BLOCK_FILES).

Setting a non-zero prune target sets opts.m_blockman_options.prune_target
and enables opts.m_chainstate_load_options.prune under the options mutex,
allowing libbitcoinkernel to open and operate on pruned datadirs.

Also adds C++ wrapper method SetPruneTarget() and unit tests validating
boundary behavior in test_kernel.cpp.

Closes #35627.

223e2a3185

DrahtBot added the label Validation on Oct 23, 2026
DrahtBot commented at 5:28 PM on October 23, 2026: contributor


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



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


Reviews

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



Conflicts

Reviewers, this pull request conflicts with the following ones:
- #36598 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36598.svg"></sub> ([Demo] validation: remove AssumeUTXO by l0rinc)
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.
musaHaruna commented at 7:29 PM on October 23, 2026: contributor

Could you revisit the discussion in #35627? This PR exposes automatic pruning through ChainstateManagerOptions, while the storage-interface and application-retention concerns raised in the issue remain unresolved.

The added tests do not exercise the reported problem. They check four setter return values, then reset the target to 0 before constructing the chainstate manager. They therefore do not demonstrate that an existing pruned directory can be opened successfully, or that automatic pruning behaves correctly.
rahadbhuiya commented at 7:44 PM on October 23, 2026: none

Thanks for the thoughtful review and feedback @musaHaruna!

Good catch on the test; resetting the target back to 0 right before constructing ChainMan only verified the option boundary validation rather than exercising ChainstateManager construction in pruned mode. I have updated the test to construct and verify ChainMan with a pruned configuration.

Regarding the broader architectural discussion in #35627: the intent here was to provide the minimal options setter needed to unblock loading existing pruned datadirs (where chainman.m_blockman.m_have_pruned requires options.prune in node::LoadChainstate), while respecting BlockManager's existing manual/target semantics.

However, I completely understand the concern regarding full automatic pruning without application-level prune locks / retention controls in place. Would you recommend scoping this PR down strictly to an explicit compatibility opt-in (e.g. allowing existing pruned storage without exposing automatic disk-target pruning), or how would you prefer we structure this first step?
test: verify ChainMan construction with pruned and unpruned configurations d42579ffb9
maflcko commented at 10:37 AM on October 26, 2026: member

violates https://github.com/bitcoin/bitcoin/blob/master/doc/AI_POLICY.md, quite obviously
maflcko closed this on Oct 26, 2026
rahadbhuiya commented at 10:46 AM on October 26, 2026: none

Understood, apologies for the writeup format.

The patch itself is a small, concrete fix for libbitcoinkernel (#35627): exposing prune_target in btck_ChainstateManagerOptions so that loading an existing pruned datadir doesn't fail on m_have_pruned.

Added unit tests in src/test/kernel/test_kernel.cpp verifying the boundary limits (unpruned, manual, >= 550 MiB).

Happy to reopen whenever @stickies-v or @TheCharlatan have bandwidth to review the kernel API changes.

Contributors

Labels

Linked (view graph)

#35627 kernel: can't work with pruned blocksdir

kernel: Add function for setting prune target in ChainstateManagerOptions #36630

Motivation & Background

Description of Changes

External sites

Reviews

Conflicts