Squashed 'libbitcoinkernel-sys/bitcoin/' changes from 81cec737e68..a755e00a135

a755e00a135 kernel: Fix bitcoin-chainstate for windows
670eb49289e kernel: Add Purpose section to header documentation
06ee1c7336b kernel: Allowing reducing exports
57b20b5a4d9 kernel: Add pure kernel bitcoin-chainstate
7cf58f8c4cb Kernel: Add functions for working with outpoints
64a4564ccb6 kernel: Add block hash type and block tree utility functions to C header
43855d656eb kernel: Add function to read block undo data from disk to C header
e080e80da7d kernel: Add functions to read block from disk to C header
51634ca37ab kernel: Add function for copying block data to C header
5ed5a9724fd kernel: Add functions for the block validation state to C header
38e5c526a86 kernel: Add validation interface to C header
REVERT: 81cec737e68 kernel: Fix bitcoin-chainstate for windows
REVERT: 1826c485ddc kernel: Add Purpose section to header documentation
REVERT: d7e618aa981 kernel: Allowing reducing exports
REVERT: fb7f5241331 kernel: Add pure kernel bitcoin-chainstate
REVERT: dd0bdf279ef Kernel: Add functions for working with outpoints
REVERT: eaa6abfc733 kernel: Add block hash type and block tree utility functions to C header
REVERT: 824ddf2885a kernel: Add function to read block undo data from disk to C header
REVERT: 76cab0768b1 kernel: Add functions to read block from disk to C header
REVERT: e41f6f459a2 kernel: Add function for copying block data to C header
REVERT: 39c647647a2 kernel: Add functions for the block validation state to C header
REVERT: 8a19a9d6070 kernel: Add validation interface to C header

git-subtree-dir: libbitcoinkernel-sys/bitcoin
git-subtree-split: a755e00a13541b3b5a707cf385f1cbec0449c6a9

Author: TheCharlatan

src/kernel/bitcoinkernel.cpp

@@ -363,8 +363,8 @@ class KernelValidationInterface final : public CValidationInterface
     {
         if (m_cbs.pow_valid_block) {
             m_cbs.pow_valid_block(m_cbs.user_data,
-                                  btck_BlockTreeEntry::ref(pindex),
-                                  btck_Block::ref(new std::shared_ptr<const CBlock>{block}));
+                                  btck_Block::ref(new std::shared_ptr<const CBlock>{block}),
+                                  btck_BlockTreeEntry::ref(pindex));
         }
     }
 
@@ -1095,12 +1095,9 @@ int32_t btck_block_tree_entry_get_height(const btck_BlockTreeEntry* entry)
     return btck_BlockTreeEntry::get(entry).nHeight;
 }
 
-btck_BlockHash* btck_block_tree_entry_get_block_hash(const btck_BlockTreeEntry* entry)
+const btck_BlockHash* btck_block_tree_entry_get_block_hash(const btck_BlockTreeEntry* entry)
 {
-    if (btck_BlockTreeEntry::get(entry).phashBlock == nullptr) {
-        return nullptr;
-    }
-    return btck_BlockHash::create(btck_BlockTreeEntry::get(entry).GetBlockHash());
+    return btck_BlockHash::ref(btck_BlockTreeEntry::get(entry).phashBlock);
 }
 
 btck_BlockHash* btck_block_hash_create(const unsigned char block_hash[32])

src/kernel/bitcoinkernel.h

@@ -266,7 +266,7 @@ typedef struct btck_TransactionInput btck_TransactionInput;
 /**
  * Opaque data structure for holding a transaction out point.
  *
- * Holds the transaction id and output index it is pointing to.
+ * Holds the txid and output index it is pointing to.
  */
 typedef struct btck_TransactionOutPoint btck_TransactionOutPoint;
 
@@ -311,7 +311,7 @@ typedef void (*btck_NotifyFatalError)(void* user_data, const char* message, size
  * Function signatures for the validation interface.
  */
 typedef void (*btck_ValidationInterfaceBlockChecked)(void* user_data, btck_Block* block, const btck_BlockValidationState* state);
-typedef void (*btck_ValidationInterfacePowValidBlock)(void* user_data, const btck_BlockTreeEntry* entry, btck_Block* block);
+typedef void (*btck_ValidationInterfacePoWValidBlock)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
 typedef void (*btck_ValidationInterfaceBlockConnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
 typedef void (*btck_ValidationInterfaceBlockDisconnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
 
@@ -356,7 +356,7 @@ typedef struct {
     btck_DestroyCallback user_data_destroy;                       //!< Frees the provided user data structure.
     btck_ValidationInterfaceBlockChecked block_checked;           //!< Called when a new block has been fully validated. Contains the
                                                                   //!< result of its validation.
-    btck_ValidationInterfacePowValidBlock pow_valid_block;        //!< Called when a new block extends the header chain and has a valid transaction
+    btck_ValidationInterfacePoWValidBlock pow_valid_block;        //!< Called when a new block extends the header chain and has a valid transaction
                                                                   //!< and segwit merkle root.
     btck_ValidationInterfaceBlockConnected block_connected;       //!< Called when a block is valid and has now been connected to the best chain.
     btck_ValidationInterfaceBlockDisconnected block_disconnected; //!< Called during a re-org when a block has been removed from the best chain.
@@ -539,7 +539,8 @@ BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_count
     const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
- * @brief Get the txid of a transaction.
+ * @brief Get the txid of a transaction. The returned txid is not owned and
+ * depends on the lifetime of the transaction.
  *
  * @param[in] transaction Non-null.
  * @return                The txid.
@@ -879,7 +880,7 @@ BITCOINKERNEL_API void btck_context_destroy(btck_Context* context);
 ///@{
 
 /**
- * @brief Returns the previous block tree entry in the chain, or null if the current
+ * @brief Returns the previous block tree entry in the tree, or null if the current
  * block tree entry is the genesis block.
  *
  * @param[in] block_tree_entry Non-null.
@@ -903,7 +904,7 @@ BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry
  * @param[in] block_tree_entry Non-null.
  * @return                     The block hash.
  */
-BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_block_hash(
+BITCOINKERNEL_API const btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_block_hash(
     const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
 
 ///@}
@@ -1387,7 +1388,7 @@ BITCOINKERNEL_API btck_TransactionOutPoint* BITCOINKERNEL_WARN_UNUSED_RESULT btc
     const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
- * @brief Get the output position from the out point.
+ * @brief Get the output position from the transaction out point.
  *
  * @param[in] transaction_out_point Non-null.
  * @return                          The output index.
@@ -1396,7 +1397,8 @@ BITCOINKERNEL_API uint32_t btck_transaction_out_point_get_index(
     const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
- * @brief Get the txid from the out point.
+ * @brief Get the txid from the transaction out point. The returned txid is
+ * not owned and depends on the lifetime of the transaction out point.
  *
  * @param[in] transaction_out_point Non-null.
  * @return                          The txid.
@@ -1468,7 +1470,8 @@ BITCOINKERNEL_API btck_Coin* BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_copy(
     const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
- * @brief Returns the height of the block that contains the coin's prevout.
+ * @brief Returns the block height where the transaction that
+ * created this coin was included in.
  *
  * @param[in] coin Non-null.
  * @return         The block height of the coin.

src/kernel/bitcoinkernel_wrapper.h

@@ -657,33 +657,53 @@ bool ScriptPubkeyApi<Derived>::Verify(int64_t amount,
     return result == 1;
 }
 
-class BlockHash : public Handle<btck_BlockHash, btck_block_hash_copy, btck_block_hash_destroy>
+template <typename Derived>
+class BlockHashApi
 {
-public:
-    explicit BlockHash(const std::array<std::byte, 32>& hash)
-        : Handle{btck_block_hash_create(reinterpret_cast<const unsigned char*>(hash.data()))} {}
-
-    explicit BlockHash(btck_BlockHash* hash)
-        : Handle{hash} {}
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
 
-    bool operator==(const BlockHash& other) const
+public:
+    bool operator==(const Derived& other) const
     {
-        return btck_block_hash_equals(get(), other.get()) != 0;
+        return btck_block_hash_equals(impl(), other.get()) != 0;
     }
 
-    bool operator!=(const BlockHash& other) const
+    bool operator!=(const Derived& other) const
     {
-        return btck_block_hash_equals(get(), other.get()) == 0;
+        return btck_block_hash_equals(impl(), other.get()) == 0;
     }
 
     std::array<std::byte, 32> ToBytes() const
     {
         std::array<std::byte, 32> hash;
-        btck_block_hash_to_bytes(get(), reinterpret_cast<unsigned char*>(hash.data()));
+        btck_block_hash_to_bytes(impl(), reinterpret_cast<unsigned char*>(hash.data()));
         return hash;
     }
 };
 
+class BlockHashView: public View<btck_BlockHash>, public BlockHashApi<BlockHashView>
+{
+public:
+    explicit BlockHashView(const btck_BlockHash* ptr) : View{ptr} {}
+};
+
+class BlockHash : public Handle<btck_BlockHash, btck_block_hash_copy, btck_block_hash_destroy>, public BlockHashApi<BlockHash>
+{
+public:
+    explicit BlockHash(const std::array<std::byte, 32>& hash)
+        : Handle{btck_block_hash_create(reinterpret_cast<const unsigned char*>(hash.data()))} {}
+
+    explicit BlockHash(btck_BlockHash* hash)
+        : Handle{hash} {}
+
+    BlockHash(const BlockHashView& view)
+        : Handle{view} {}
+};
+
 class Block : public Handle<btck_Block, btck_block_copy, btck_block_destroy>
 {
 public:
@@ -781,9 +801,9 @@ class BlockTreeEntry : public View<btck_BlockTreeEntry>
         return btck_block_tree_entry_get_height(get());
     }
 
-    BlockHash GetHash() const
+    BlockHashView GetHash() const
     {
-        return BlockHash{btck_block_tree_entry_get_block_hash(get())};
+        return BlockHashView{btck_block_tree_entry_get_block_hash(get())};
     }
 
     friend class ChainMan;
@@ -902,7 +922,7 @@ class ContextOptions : UniqueHandle<btck_ContextOptions, btck_context_options_de
                 .user_data = heap_vi.release(),
                 .user_data_destroy = +[](void* user_data) { delete static_cast<user_type>(user_data); },
                 .block_checked = +[](void* user_data, btck_Block* block, const btck_BlockValidationState* state) { (*static_cast<user_type>(user_data))->BlockChecked(Block{block}, BlockValidationState{state}); },
-                .pow_valid_block = +[](void* user_data, const btck_BlockTreeEntry* entry, btck_Block* block) { (*static_cast<user_type>(user_data))->PowValidBlock(BlockTreeEntry{entry}, Block{block}); },
+                .pow_valid_block = +[](void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry) { (*static_cast<user_type>(user_data))->PowValidBlock(BlockTreeEntry{entry}, Block{block}); },
                 .block_connected = +[](void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry) { (*static_cast<user_type>(user_data))->BlockConnected(Block{block}, BlockTreeEntry{entry}); },
                 .block_disconnected = +[](void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry) { (*static_cast<user_type>(user_data))->BlockDisconnected(Block{block}, BlockTreeEntry{entry}); },
             });