kernel: doc: document wipe lifecycle and best entry nullability
What the developer wrote
Authored by csjones
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.
What changed, and why it matters
This commit only changes comments in a single header file. It documents that a database wipe must be followed by importing blocks, and that a function can return null when no block headers are loaded. There are no code changes and no security fix.
No action required; this is a documentation-only commit with no security relevance.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff is purely documentation-only in src/kernel/bitcoinkernel.h. It adds a @note to btck_chainstate_manager_options_set_wipe_dbs clarifying the required import_blocks call after a wipe, and updates the @return of btck_chainstate_manager_get_best_entry to mention nullability when no headers are loaded. No logic, API behavior, or security boundary changed.
Changed components
src/kernel/bitcoinkernel.hInspect captured patch +3 / −1
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 577c4c0a..2ad3c8bd 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);
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.