Merge bitcoin/bitcoin#35096: kernel: align height parameters to int32_t in btck API

07b9b13b45 doc: add integer type conventions in btck api remarks (Alexander Wiederin)
ba6287a449 kernel: align height parameters to int32_t in btck API (Alexander Wiederin)

Pull request description:

  Follow-up to https://github.com/bitcoin/bitcoin/pull/34885#discussion_r3093370576

  ### Summary
  Align height-related parameters and return values in the kernel API to use `int32_t`.

  ### Motivation

  The convention in the API is to use fixed-width types like `int32_t` for data values (e.g. heights), and plain `int`/`unsigned int` for boolean-like values and flags. Two functions were not following this:

  - `btck_chain_get_height`: header declared `int32_t` but implementation used `int`
  - `btck_chain_get_by_height`: both header and implementation used plain `int`

  ### Changes

  - `btck_chain_get_height`: align `.cpp` to match header (`int` -> `int32_t`)
  - `btck_chain_get_by_height`: update both header and `.cpp` (`int` -> `int32_t`)
  - `CountEntries` in `bitcoinkernel_wrapper.h`: align return type to `int32_t`
  - `GetByHeight` in `bitcoinkernel_wrapper.h`: align parameter type to `int32_t`
  - Document integer type conventions in the `@page remarks` section of `bitcoinkernel.h`

  *Note: This is technically a breaking change for C consumers who have function pointer declarations matching the old signature. The Rust, Go, Java and Python bindings should not be affected.*

ACKs for top commit:
  musaHaruna:
    Code review ACK [07b9b13](07b9b13b45)
  sedited:
    ACK 07b9b13b45
  stringintech:
    ACK 07b9b13

Tree-SHA512: 1c6c5c3113c82f7c5f07871c1aa996b71191d0b190d000d48774a866fcc08514cdabcc13a9de2fed8b5d824da050258db73d73e6aa0b80d828af1533128fe1cd

src/kernel/bitcoinkernel.cpp

@@ -1352,13 +1352,13 @@ const btck_Chain* btck_chainstate_manager_get_active_chain(const btck_Chainstate
     return btck_Chain::ref(&WITH_LOCK(btck_ChainstateManager::get(chainman).m_chainman->GetMutex(), return btck_ChainstateManager::get(chainman).m_chainman->ActiveChain()));
 }
 
-int btck_chain_get_height(const btck_Chain* chain)
+int32_t btck_chain_get_height(const btck_Chain* chain)
 {
     LOCK(::cs_main);
     return btck_Chain::get(chain).Height();
 }
 
-const btck_BlockTreeEntry* btck_chain_get_by_height(const btck_Chain* chain, int height)
+const btck_BlockTreeEntry* btck_chain_get_by_height(const btck_Chain* chain, int32_t height)
 {
     LOCK(::cs_main);
     return btck_BlockTreeEntry::ref(btck_Chain::get(chain)[height]);

src/kernel/bitcoinkernel.h

@@ -112,6 +112,12 @@ extern "C" {
  * object.
  *
  * Array lengths follow the pointer argument they describe.
+ *
+ * @section types Type conventions
+ *
+ * Fixed-width integer types (e.g. int32_t, uint32_t) are used for data values
+ * such as heights. Plain int and unsigned int are used for boolean-like values
+ * and flags.
  */
 
 /**
@@ -1423,7 +1429,7 @@ BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_get_height
  */
 BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_get_by_height(
     const btck_Chain* chain,
-    int block_height) BITCOINKERNEL_ARG_NONNULL(1);
+    int32_t block_height) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
  * @brief Return true if the passed in chain contains the block tree entry.

src/kernel/bitcoinkernel_wrapper.h

@@ -1122,12 +1122,12 @@ public:
         return btck_chain_get_height(get());
     }
 
-    int CountEntries() const
+    int32_t CountEntries() const
     {
         return btck_chain_get_height(get()) + 1;
     }
 
-    BlockTreeEntry GetByHeight(int height) const
+    BlockTreeEntry GetByHeight(int32_t height) const
     {
         auto index{btck_chain_get_by_height(get(), height)};
         if (!index) throw std::runtime_error("No entry in the chain at the provided height");