kernel: can't work with pruned blocksdir #35627

Bitcoinkernel is not able to work datadirs created by pruned nodes (see log snippet below) Nor the api exposes a way to prune the blocksdir it manages.

I checked that the internal pruning machinery already exists and did some experimentation to add this feature, but wanted to get some feedback about the api before working on a PR (or review if someone is willing to take this).

A first step would be to inform the chainstate_manager about pruning by setting an option.

BITCOINKERNEL_API int btck_chainstate_manager_options_set_prune(
    btck_ChainstateManagerOptions* chainstate_manager_options,
    uint64_t prune_mode);

First question would be the semantics of the prune_mode argument. In a PoC, I followed Core's -prune cli option semantics (0 = unpruned, 1 = pruned with no target, >= 550 means pruned with a target of that many MiB). Seems simple, but feels awkward.

I would expect the library to automatically prune the blocksdir (e.g. during btck_chainstate_manager_process_block) if the target is set. Still, I think there should be an api for triggering pruning. I thought of:

BITCOINKERNEL_API int btck_chainstate_manager_prune(
    btck_ChainstateManager* chainstate_manager);

BITCOINKERNEL_API int btck_chainstate_manager_prune_to_height(
    btck_ChainstateManager* chainstate_manager, 
    int32_t height);

The former would prune to target (if set) and the latter would prune to height, no matter the target. Maybe an even better functionality for library consumers would be a function to prune specific entries, e.g.:

BITCOINKERNEL_API int btck_chainstate_manager_prune_block_entry_entry(
    btck_ChainstateManager* chainstate_manager,
    const btck_BlockTreeEntry* block_tree_entry);

Finally, it's still not clear to me how to properly test this since there are no functional tests for bitcoinkernel.

<details><summary>Log snippet</summary> <p>

2026-07-01T00:49:34Z Using the 'arm_shani(1way;2way)' SHA256 implementation
2026-07-01T00:49:34Z Script verification uses 0 additional threads
2026-07-01T00:49:34Z Using obfuscation key for blocksdir *.dat files (../datadir-pruned/signet/blocks): '6d7ae47f0b8b49e1'
2026-07-01T00:49:34Z Opening LevelDB in ../datadir-pruned/signet/blocks/index
2026-07-01T00:49:34Z Opened LevelDB successfully
2026-07-01T00:49:34Z Using obfuscation key for ../datadir-pruned/signet/blocks/index: 0000000000000000
2026-07-01T00:49:34Z Using 16 MiB out of 16 MiB requested for signature cache, able to store 524288 elements
2026-07-01T00:49:34Z Using 16 MiB out of 16 MiB requested for script execution cache, able to store 524288 elements
2026-07-01T00:49:34Z Assuming ancestors of block 00000008414aab61092ef93f1aacc54cf9e9f16af29ddad493b908a01ff5c329 have valid signatures.
2026-07-01T00:49:34Z Setting nMinimumChainWork=00000000000000000000000000000000000000000000000000000b463ea0a4b8
2026-07-01T00:49:34Z Loading block index db: last block file = 128
2026-07-01T00:49:34Z Loading block index db: last block file info: CBlockFileInfo(blocks=2009, size=127357639, heights=309098...311171, time=2026-06-16...2026-06-30)
2026-07-01T00:49:34Z Checking all blk files are present...
2026-07-01T00:49:34Z Loading block index db: Block files have previously been pruned
2026-07-01T00:49:34Z [error] Failed to load chain state from your data directory: You need to rebuild the database using -reindex to go back to unpruned mode.  This will redownload the entire blockchain
chainstate_manager_create failed

</p> </details>

I think giving the user tools to manage pruning is the way to go, and would allow them to e.g. implement prune locks (which Bitcoin Core also has) instead of having to rely on bitcoinkernel to do the tracking. Automatic pruning makes that cumbersome.

However, I'm not sure we're currently in a good spot to offer a high quality pruning API. Block storage is not a chainstate concern, so exposing pruning through ChainstateManager does not get me excited. I think we first need to think about and work on separating block storage and chainstate management, and then revisit pruning once we have that separation? Of course, the need for pruning can be a good motivation for moving that work forward.

Of course, the need for pruning can be a good motivation for moving that work forward.

I'm planning to use bitcoinkernel mostly as an (one-shot) ingestor for a database indexer, so pruning is not a concern currently. But if we want to go live, this would be desirable. Moreover, I was exploring the api with @oleonardolima in the context of having a BDK block provider based on bitcoinkernel. A wallet like this probably would benefit from heavily pruning the blocksdir.