kernel: doc: document wipe lifecycle and best entry nullability #35304

pull csjones wants to merge 1 commits into bitcoin:master from 21-DOT-DEV:doc-kernel-best-entry-null-after-wipe changing 1 files +3 −1
  1. csjones commented at 9:11 AM on May 16, 2026: none

    Document on btck_chainstate_manager_options_set_wipe_dbs that a wipe must be followed by btck_chainstate_manager_import_blocks before the chainstate manager is used for anything else, as the existing kernel tests already do (specifically the chainman_reindex* kernel tests). Note in the @return of btck_chainstate_manager_get_best_entry that it can return null when no block headers have been loaded.

    Background: I've been working on a bindings project using the libbitcoinkernel and tripped on a SIGSEGV calling the entry accessors on the null pointer returned by get_best_entry after a (true, true) wipe (#35293). The C++ wrapper handles this via btck::check<>, but bindings generated from the C header don't see the wrapper. Adding a nullability documentation hint helps generators produce the correct signature, and the @note on set_wipe_dbs documents the lifecycle that avoids the null in the first place.

    Docs-only change; no tests ran.

  2. DrahtBot added the label Validation on May 16, 2026
  3. DrahtBot commented at 9:11 AM on May 16, 2026: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

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

    <!--006a51241073e994b41acfe9ec718e94-->

    Code Coverage & Benchmarks

    For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35304.

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

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

    <!--5faf32d7da4f0f540f40219e4f7537a3-->

  4. kernel: doc: document wipe lifecycle and best entry nullability
    Document on `btck_chainstate_manager_options_set_wipe_dbs` that a wipe must be followed by `btck_chainstate_manager_import_blocks` before the chainstate manager is used for anything else, as the existing kernel tests already do (e.g. `chainman_reindex_test`).
    
    Note in the `@return` of `btck_chainstate_manager_get_best_entry` that it can return null when no block headers have been loaded.
    
    Refactor the `@return` documentation to fit on a single line.
    6189335f6b
  5. csjones force-pushed on May 16, 2026

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-05-19 06:51 UTC