Repository: bitcoin/bitcoin
File: src/kernel/bitcoinkernel.h (C/C++)

Code before:
/**
 * Destroy the chainstate manager options.
 */
BITCOINKERNEL_API void btck_chainstate_manager_options_destroy(btck_ChainstateManagerOptions* chainstate_manager_options);

///@}

/** @name ChainstateManager
 * Functions for chainstate management.
 */
///@{

/**
 * @brief Create a chainstate manager. This is the main object for many
 * validation tasks as well as for retrieving data from the chain and
 * interacting with its chainstate and indexes.
 *
 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
 * @return                               The allocated chainstate manager, or null on error.
 */
BITCOINKERNEL_API btck_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_create(
    const btck_ChainstateManagerOptions* chainstate_manager_options) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Get the block tree entry whose associated block header has the most
 * known cumulative proof of work.
 *
 * @param[in] chainstate_manager Non-null.
 * @return                       The block tree entry.
 */
BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_best_entry(
    const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Processes and validates the provided block header.
 *
 * @param[in] chainstate_manager        Non-null.
 * @param[in] header                    Non-null header to be validated.
 * @param[out] block_validation_state   The result of the header validation.
 * @return                              0 if header processing completed successfully, non-zero on error.
 */
BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_process_block_header(
    btck_ChainstateManager* chainstate_manager,
    const btck_BlockHeader* header,
    btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);

/**
 * @brief Triggers the start of a reindex if the wipe options were previously
 * set for the chainstate manager. Can also import an array of existing block
 * files selected by the user.
 *

Review comment (suggestion):
Some cases that using the opaque struct name might be better (there might be others):

<details>
<summary>diff</summary>

```diff
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -1049,20 +1049,20 @@ BITCOINKERNEL_API btck_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT btck_
     const btck_ChainstateManagerOptions* chainstate_manager_options) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
- * @brief Get the block tree entry whose associated block header has the most
+ * @brief Get the btck_BlockTreeEntry whose associated block header has the most
  * known cumulative proof of work.
  *
  * @param[in] chainstate_manager Non-null.
- * @return                       The block tree entry.
+ * @return                       btck_BlockTreeEntry.
  */
 BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_best_entry(
     const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
- * @brief Processes and validates the provided block header.
+ * @brief Processes and validates the provided btck_BlockHeader.
  *
  * @param[in] chainstate_manager        Non-null.
- * @param[in] header                    Non-null header to be validated.
+ * @param[in] header                    Non-null btck_BlockHeader to be validated.
  * @param[out] block_validation_state   The result of the header validation.
  * @return                              0 if header processing completed successfully, non-zero on error.
  */
@@ -1203,12 +1203,12 @@ BITCOINKERNEL_API const btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_
     const btck_Block* block, size_t transaction_index) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
- * @brief Get the header from the block.
+ * @brief Get the btck_BlockHeader from the block.
  *
  * Creates a new block header object from the block's header data.
  *
- * @param[in] block Non-null block
- * @return          Block header, or null on error.
+ * @param[in] block Non-null btck_Block.
+ * @return          btck_BlockHeader, or null on error.
  */
 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_header(
     const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
@@ -1645,7 +1645,7 @@ BITCOINKERNEL_API void btck_block_hash_destroy(btck_BlockHash* block_hash);
  *
  * @param[in] raw_block_header      Non-null, serialized header data (80 bytes)
  * @param[in] raw_block_header_len  Length of serialized header (must be 80)
- * @return                          Block Header, or null on error.
+ * @return                          btck_BlockHeader, or null on error.
  */
 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_create(
     const void* raw_block_header, size_t raw_block_header_len) BITCOINKERNEL_ARG_NONNULL(1);
@@ -1662,8 +1662,8 @@ BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_
 /**
  * @brief Get the btck_BlockHash.
  *
- * @param[in] header    Non-null header
- * @return              Block hash.
+ * @param[in] header    Non-null btck_BlockHeader.
+ * @return              btck_BlockHash.
  */
 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_get_hash(
     const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);


```

</details>

Code after:
BITCOINKERNEL_API btck_ChainstateManagerOptions* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_create(
    const btck_Context* context,
    const char* data_directory,
    size_t data_directory_len,
    const char* blocks_directory,
    size_t blocks_directory_len) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Set the number of available worker threads used during validation.
 *
 * @param[in] chainstate_manager_options Non-null, options to be set.
 * @param[in] worker_threads             The number of worker threads that should be spawned in the thread pool
 *                                       used for validation. When set to 0 no parallel verification is done.
 *                                       The value range is clamped internally between 0 and 15.
 */
BITCOINKERNEL_API void btck_chainstate_manager_options_set_worker_threads_num(
    btck_ChainstateManagerOptions* chainstate_manager_options,
    int worker_threads) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Sets wipe db in the options. In combination with calling
 * @ref btck_chainstate_manager_import_blocks this triggers either a full reindex,
 * or a reindex of just the chainstate database.
 *
 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
 * @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.
 */
BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_set_wipe_dbs(
    btck_ChainstateManagerOptions* chainstate_manager_options,
    int wipe_block_tree_db,
    int wipe_chainstate_db) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Sets block tree db in memory in the options.
 *
 * @param[in] chainstate_manager_options   Non-null, created by @ref btck_chainstate_manager_options_create.
 * @param[in] block_tree_db_in_memory      Set block tree db in memory.
 */
BITCOINKERNEL_API void btck_chainstate_manager_options_update_block_tree_db_in_memory(
    btck_ChainstateManagerOptions* chainstate_manager_options,
    int block_tree_db_in_memory) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Sets chainstate db in memory in the options.
 *
 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
 * @param[in] chainstate_db_in_memory    Set chainstate db in memory.
 */
BITCOINKERNEL_API void btck_chainstate_manager_options_update_chainstate_db_in_memory(