From 6189335f6bf732a535ee3bd49271bd4457271a56 Mon Sep 17 00:00:00 2001 From: csjones <637026+csjones@users.noreply.github.com> Date: Sat, 16 May 2026 01:01:51 -0700 Subject: [PATCH] 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. --- src/kernel/bitcoinkernel.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h index 577c4c0a329..2ad3c8bd4cd 100644 --- a/src/kernel/bitcoinkernel.h +++ b/src/kernel/bitcoinkernel.h @@ -1179,6 +1179,8 @@ BITCOINKERNEL_API void btck_chainstate_manager_options_set_worker_threads_num( * @param[in] wipe_block_tree_db Set wipe block tree db. Should only be 1 if wipe_chainstate_db is 1 too. * @param[in] wipe_chainstate_db Set wipe chainstate db. * @return 0 if the set was successful, non-zero if the set failed. + * @note When a wipe is set, the caller must invoke @ref btck_chainstate_manager_import_blocks + * on the resulting chainstate manager before using it for anything else. */ BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_set_wipe_dbs( btck_ChainstateManagerOptions* chainstate_manager_options, @@ -1233,7 +1235,7 @@ BITCOINKERNEL_API btck_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT btck_ * known cumulative proof of work. * * @param[in] chainstate_manager Non-null. - * @return The btck_BlockTreeEntry. + * @return The btck_BlockTreeEntry, or null if no block headers have been loaded. */ BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_best_entry( const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);