kernel: Introduce initial kernel C header API

As a first step, implement the equivalent of what was implemented in the
now deprecated libbitcoinconsensus header. Also add a test binary to
exercise the header and library.

Unlike the deprecated libbitcoinconsensus the kernel library can now use
the hardware-accelerated sha256 implementations thanks for its
statically-initialzed context. The functions kept around for
backwards-compatibility in the libbitcoinconsensus header are not ported
over. As a new header, it should not be burdened by previous
implementations. Also add a new error code for handling invalid flag
combinations, which would otherwise cause a crash.

The macros used in the new C header were adapted from the libsecp256k1
header.

To make use of the C header from C++ code, a C++ header is also
introduced for wrapping the C header. This makes it safer and easier to
use from C++ code.

Co-authored-by: stickies-v <stickies-v@protonmail.com>

src/kernel/CMakeLists.txt

@@ -110,6 +110,11 @@ set_target_properties(bitcoinkernel PROPERTIES
 add_custom_target(libbitcoinkernel)
 add_dependencies(libbitcoinkernel bitcoinkernel)
 
+get_target_property(bitcoinkernel_type bitcoinkernel TYPE)
+if(bitcoinkernel_type STREQUAL "STATIC_LIBRARY")
+  target_compile_definitions(bitcoinkernel PUBLIC BITCOINKERNEL_STATIC)
+endif()
+
 configure_file(${PROJECT_SOURCE_DIR}/libbitcoinkernel.pc.in ${PROJECT_BINARY_DIR}/libbitcoinkernel.pc @ONLY)
 install(FILES ${PROJECT_BINARY_DIR}/libbitcoinkernel.pc DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig" COMPONENT libbitcoinkernel)
 
@@ -124,3 +129,5 @@ install(TARGETS bitcoinkernel
     DESTINATION ${CMAKE_INSTALL_LIBDIR}
     COMPONENT libbitcoinkernel
 )
+
+install(FILES bitcoinkernel.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} COMPONENT libbitcoinkernel)

src/kernel/bitcoinkernel.cpp

@@ -1,11 +1,255 @@
-// Copyright (c) 2022 The Bitcoin Core developers
+// Copyright (c) 2022-present The Bitcoin Core developers
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#define BITCOINKERNEL_BUILD
+
+#include <kernel/bitcoinkernel.h>
+
+#include <consensus/amount.h>
+#include <kernel/context.h>
+#include <primitives/transaction.h>
+#include <script/interpreter.h>
+#include <script/script.h>
+#include <serialize.h>
+#include <streams.h>
 #include <util/translation.h>
 
+#include <cstddef>
+#include <cstring>
+#include <exception>
 #include <functional>
+#include <span>
 #include <string>
+#include <utility>
+#include <vector>
 
 // Define G_TRANSLATION_FUN symbol in libbitcoinkernel library so users of the
 // library aren't required to export this symbol
-extern const TranslateFn G_TRANSLATION_FUN{nullptr};
+extern const std::function<std::string(const char*)> G_TRANSLATION_FUN{nullptr};
+
+static const kernel::Context btck_context_static{};
+
+namespace {
+
+bool is_valid_flag_combination(script_verify_flags flags)
+{
+    if (flags & SCRIPT_VERIFY_CLEANSTACK && ~flags & (SCRIPT_VERIFY_P2SH | SCRIPT_VERIFY_WITNESS)) return false;
+    if (flags & SCRIPT_VERIFY_WITNESS && ~flags & SCRIPT_VERIFY_P2SH) return false;
+    return true;
+}
+
+class WriterStream
+{
+private:
+    btck_WriteBytes m_writer;
+    void* m_user_data;
+
+public:
+    WriterStream(btck_WriteBytes writer, void* user_data)
+        : m_writer{writer}, m_user_data{user_data} {}
+
+    //
+    // Stream subset
+    //
+    void write(std::span<const std::byte> src)
+    {
+        if (m_writer(std::data(src), src.size(), m_user_data) != 0) {
+            throw std::runtime_error("Failed to write serialization data");
+        }
+    }
+
+    template <typename T>
+    WriterStream& operator<<(const T& obj)
+    {
+        ::Serialize(*this, obj);
+        return *this;
+    }
+};
+
+template <typename C, typename CPP>
+struct Handle {
+    static C* ref(CPP* cpp_type)
+    {
+        return reinterpret_cast<C*>(cpp_type);
+    }
+
+    static const C* ref(const CPP* cpp_type)
+    {
+        return reinterpret_cast<const C*>(cpp_type);
+    }
+
+    template <typename... Args>
+    static C* create(Args&&... args)
+    {
+        auto cpp_obj{std::make_unique<CPP>(std::forward<Args>(args)...)};
+        return reinterpret_cast<C*>(cpp_obj.release());
+    }
+
+    static C* copy(const C* ptr)
+    {
+        auto cpp_obj{std::make_unique<CPP>(get(ptr))};
+        return reinterpret_cast<C*>(cpp_obj.release());
+    }
+
+    static const CPP& get(const C* ptr)
+    {
+        return *reinterpret_cast<const CPP*>(ptr);
+    }
+
+    static void operator delete(void* ptr)
+    {
+        delete reinterpret_cast<CPP*>(ptr);
+    }
+};
+
+} // namespace
+
+struct btck_Transaction : Handle<btck_Transaction, std::shared_ptr<const CTransaction>> {};
+struct btck_TransactionOutput : Handle<btck_TransactionOutput, CTxOut> {};
+struct btck_ScriptPubkey : Handle<btck_ScriptPubkey, CScript> {};
+
+btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
+{
+    try {
+        DataStream stream{std::span{reinterpret_cast<const std::byte*>(raw_transaction), raw_transaction_len}};
+        return btck_Transaction::create(std::make_shared<const CTransaction>(deserialize, TX_WITH_WITNESS, stream));
+    } catch (...) {
+        return nullptr;
+    }
+}
+
+size_t btck_transaction_count_outputs(const btck_Transaction* transaction)
+{
+    return btck_Transaction::get(transaction)->vout.size();
+}
+
+const btck_TransactionOutput* btck_transaction_get_output_at(const btck_Transaction* transaction, size_t output_index)
+{
+    const CTransaction& tx = *btck_Transaction::get(transaction);
+    assert(output_index < tx.vout.size());
+    return btck_TransactionOutput::ref(&tx.vout[output_index]);
+}
+
+size_t btck_transaction_count_inputs(const btck_Transaction* transaction)
+{
+    return btck_Transaction::get(transaction)->vin.size();
+}
+
+btck_Transaction* btck_transaction_copy(const btck_Transaction* transaction)
+{
+    return btck_Transaction::copy(transaction);
+}
+
+int btck_transaction_to_bytes(const btck_Transaction* transaction, btck_WriteBytes writer, void* user_data)
+{
+    try {
+        WriterStream ws{writer, user_data};
+        ws << TX_WITH_WITNESS(btck_Transaction::get(transaction));
+        return 0;
+    } catch (...) {
+        return -1;
+    }
+}
+
+void btck_transaction_destroy(btck_Transaction* transaction)
+{
+    delete transaction;
+}
+
+btck_ScriptPubkey* btck_script_pubkey_create(const void* script_pubkey, size_t script_pubkey_len)
+{
+    auto data = std::span{reinterpret_cast<const uint8_t*>(script_pubkey), script_pubkey_len};
+    return btck_ScriptPubkey::create(data.begin(), data.end());
+}
+
+int btck_script_pubkey_to_bytes(const btck_ScriptPubkey* script_pubkey_, btck_WriteBytes writer, void* user_data)
+{
+    const auto& script_pubkey{btck_ScriptPubkey::get(script_pubkey_)};
+    return writer(script_pubkey.data(), script_pubkey.size(), user_data);
+}
+
+btck_ScriptPubkey* btck_script_pubkey_copy(const btck_ScriptPubkey* script_pubkey)
+{
+    return btck_ScriptPubkey::copy(script_pubkey);
+}
+
+void btck_script_pubkey_destroy(btck_ScriptPubkey* script_pubkey)
+{
+    delete script_pubkey;
+}
+
+btck_TransactionOutput* btck_transaction_output_create(const btck_ScriptPubkey* script_pubkey, int64_t amount)
+{
+    return btck_TransactionOutput::create(amount, btck_ScriptPubkey::get(script_pubkey));
+}
+
+btck_TransactionOutput* btck_transaction_output_copy(const btck_TransactionOutput* output)
+{
+    return btck_TransactionOutput::copy(output);
+}
+
+const btck_ScriptPubkey* btck_transaction_output_get_script_pubkey(const btck_TransactionOutput* output)
+{
+    return btck_ScriptPubkey::ref(&btck_TransactionOutput::get(output).scriptPubKey);
+}
+
+int64_t btck_transaction_output_get_amount(const btck_TransactionOutput* output)
+{
+    return btck_TransactionOutput::get(output).nValue;
+}
+
+void btck_transaction_output_destroy(btck_TransactionOutput* output)
+{
+    delete output;
+}
+
+int btck_script_pubkey_verify(const btck_ScriptPubkey* script_pubkey,
+                              const int64_t amount,
+                              const btck_Transaction* tx_to,
+                              const btck_TransactionOutput** spent_outputs_, size_t spent_outputs_len,
+                              const unsigned int input_index,
+                              const btck_ScriptVerificationFlags flags,
+                              btck_ScriptVerifyStatus* status)
+{
+    // Assert that all specified flags are part of the interface before continuing
+    assert((flags & ~btck_ScriptVerificationFlags_ALL) == 0);
+
+    if (!is_valid_flag_combination(script_verify_flags::from_int(flags))) {
+        if (status) *status = btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION;
+        return 0;
+    }
+
+    if (flags & btck_ScriptVerificationFlags_TAPROOT && spent_outputs_ == nullptr) {
+        if (status) *status = btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED;
+        return 0;
+    }
+
+    if (status) *status = btck_ScriptVerifyStatus_OK;
+
+    const CTransaction& tx{*btck_Transaction::get(tx_to)};
+    std::vector<CTxOut> spent_outputs;
+    if (spent_outputs_ != nullptr) {
+        assert(spent_outputs_len == tx.vin.size());
+        spent_outputs.reserve(spent_outputs_len);
+        for (size_t i = 0; i < spent_outputs_len; i++) {
+            const CTxOut& tx_out{btck_TransactionOutput::get(spent_outputs_[i])};
+            spent_outputs.push_back(tx_out);
+        }
+    }
+
+    assert(input_index < tx.vin.size());
+    PrecomputedTransactionData txdata{tx};
+
+    if (spent_outputs_ != nullptr && flags & btck_ScriptVerificationFlags_TAPROOT) {
+        txdata.Init(tx, std::move(spent_outputs));
+    }
+
+    bool result = VerifyScript(tx.vin[input_index].scriptSig,
+                               btck_ScriptPubkey::get(script_pubkey),
+                               &tx.vin[input_index].scriptWitness,
+                               script_verify_flags::from_int(flags),
+                               TransactionSignatureChecker(&tx, input_index, amount, txdata, MissingDataBehavior::FAIL),
+                               nullptr);
+    return result ? 1 : 0;
+}

src/kernel/bitcoinkernel.h

@@ -0,0 +1,340 @@
+// Copyright (c) 2024-present The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#ifndef BITCOIN_KERNEL_BITCOINKERNEL_H
+#define BITCOIN_KERNEL_BITCOINKERNEL_H
+
+#ifndef __cplusplus
+#include <stddef.h>
+#include <stdint.h>
+#else
+#include <cstddef>
+#include <cstdint>
+#endif // __cplusplus
+
+#ifndef BITCOINKERNEL_API
+    #ifdef BITCOINKERNEL_BUILD
+        #if defined(_WIN32)
+            #define BITCOINKERNEL_API __declspec(dllexport)
+        #else
+            #define BITCOINKERNEL_API __attribute__((visibility("default")))
+        #endif
+    #else
+        #if defined(_WIN32) && !defined(BITCOINKERNEL_STATIC)
+            #define BITCOINKERNEL_API __declspec(dllimport)
+        #else
+            #define BITCOINKERNEL_API
+        #endif
+    #endif
+#endif
+
+/* Warning attributes */
+#if defined(__GNUC__)
+    #define BITCOINKERNEL_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
+#else
+    #define BITCOINKERNEL_WARN_UNUSED_RESULT
+#endif
+#if !defined(BITCOINKERNEL_BUILD) && defined(__GNUC__)
+    #define BITCOINKERNEL_ARG_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__)))
+#else
+    #define BITCOINKERNEL_ARG_NONNULL(...)
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+/**
+ * @page remarks Remarks
+ *
+ * @section context Context
+ *
+ * The library provides a built-in static constant kernel context. This static
+ * context offers only limited functionality. It detects and self-checks the
+ * correct sha256 implementation, initializes the random number generator and
+ * self-checks the secp256k1 static context. It is used internally for
+ * otherwise "context-free" operations. This means that the user is not
+ * required to initialize their own context before using the library.
+ *
+ * @section error Error handling
+ *
+ * Functions communicate an error through their return types, usually returning
+ * a nullptr, 0, or false if an error is encountered. Additionally, verification
+ * functions, e.g. for scripts, may communicate more detailed error information
+ * through status code out parameters.
+ *
+ * @section pointer Pointer and argument conventions
+ *
+ * The user is responsible for de-allocating the memory owned by pointers
+ * returned by functions. Typically pointers returned by *_create(...) functions
+ * can be de-allocated by corresponding *_destroy(...) functions.
+ *
+ * A function that takes pointer arguments makes no assumptions on their
+ * lifetime. Once the function returns the user can safely de-allocate the
+ * passed in arguments.
+ *
+ * Const pointers represent views, and do not transfer ownership. Lifetime
+ * guarantees of these objects are described in the respective documentation.
+ * Ownership of these resources may be taken by copying. They are typically
+ * used for iteration with minimal overhead and require some care by the
+ * programmer that their lifetime is not extended beyond that of the original
+ * object.
+ *
+ * Array lengths follow the pointer argument they describe.
+ */
+
+/**
+ * Opaque data structure for holding a transaction.
+ */
+typedef struct btck_Transaction btck_Transaction;
+
+/**
+ * Opaque data structure for holding a script pubkey.
+ */
+typedef struct btck_ScriptPubkey btck_ScriptPubkey;
+
+/**
+ * Opaque data structure for holding a transaction output.
+ */
+typedef struct btck_TransactionOutput btck_TransactionOutput;
+
+/**
+ * A collection of status codes that may be issued by the script verify function.
+ */
+typedef uint8_t btck_ScriptVerifyStatus;
+#define btck_ScriptVerifyStatus_OK ((btck_ScriptVerifyStatus)(0))
+#define btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION ((btck_ScriptVerifyStatus)(1)) //!< The flags were combined in an invalid way.
+#define btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED ((btck_ScriptVerifyStatus)(2))    //!< The taproot flag was set, so valid spent_outputs have to be provided.
+
+/**
+ * Script verification flags that may be composed with each other.
+ */
+typedef uint32_t btck_ScriptVerificationFlags;
+#define btck_ScriptVerificationFlags_NONE ((btck_ScriptVerificationFlags)(0))
+#define btck_ScriptVerificationFlags_P2SH ((btck_ScriptVerificationFlags)(1U << 0))                 //!< evaluate P2SH (BIP16) subscripts
+#define btck_ScriptVerificationFlags_DERSIG ((btck_ScriptVerificationFlags)(1U << 2))               //!< enforce strict DER (BIP66) compliance
+#define btck_ScriptVerificationFlags_NULLDUMMY ((btck_ScriptVerificationFlags)(1U << 4))            //!< enforce NULLDUMMY (BIP147)
+#define btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY ((btck_ScriptVerificationFlags)(1U << 9))  //!< enable CHECKLOCKTIMEVERIFY (BIP65)
+#define btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY ((btck_ScriptVerificationFlags)(1U << 10)) //!< enable CHECKSEQUENCEVERIFY (BIP112)
+#define btck_ScriptVerificationFlags_WITNESS ((btck_ScriptVerificationFlags)(1U << 11))             //!< enable WITNESS (BIP141)
+#define btck_ScriptVerificationFlags_TAPROOT ((btck_ScriptVerificationFlags)(1U << 17))             //!< enable TAPROOT (BIPs 341 & 342)
+#define btck_ScriptVerificationFlags_ALL ((btck_ScriptVerificationFlags)(btck_ScriptVerificationFlags_P2SH |                \
+                                                                         btck_ScriptVerificationFlags_DERSIG |              \
+                                                                         btck_ScriptVerificationFlags_NULLDUMMY |           \
+                                                                         btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY | \
+                                                                         btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY | \
+                                                                         btck_ScriptVerificationFlags_WITNESS |             \
+                                                                         btck_ScriptVerificationFlags_TAPROOT))
+
+/**
+ * Function signature for serializing data.
+ */
+typedef int (*btck_WriteBytes)(const void* bytes, size_t size, void* userdata);
+
+/** @name Transaction
+ * Functions for working with transactions.
+ */
+///@{
+
+/**
+ * @brief Create a new transaction from the serialized data.
+ *
+ * @param[in] raw_transaction     Non-null.
+ * @param[in] raw_transaction_len Length of the serialized transaction.
+ * @return                        The transaction, or null on error.
+ */
+BITCOINKERNEL_API btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_create(
+    const void* raw_transaction, size_t raw_transaction_len) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Copy a transaction. Transactions are reference counted, so this just
+ * increments the reference count.
+ *
+ * @param[in] transaction Non-null.
+ * @return                The copied transaction.
+ */
+BITCOINKERNEL_API btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_copy(
+    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Serializes the transaction through the passed in callback to bytes.
+ * This is consensus serialization that is also used for the P2P network.
+ *
+ * @param[in] transaction Non-null.
+ * @param[in] writer      Non-null, callback to a write bytes function.
+ * @param[in] user_data   Holds a user-defined opaque structure that will be
+ *                        passed back through the writer callback.
+ * @return                0 on success.
+ */
+BITCOINKERNEL_API int btck_transaction_to_bytes(
+    const btck_Transaction* transaction,
+    btck_WriteBytes writer,
+    void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Get the number of outputs of a transaction.
+ *
+ * @param[in] transaction Non-null.
+ * @return                The number of outputs.
+ */
+BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_count_outputs(
+    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the transaction outputs at the provided index. The returned
+ * transaction output is not owned and depends on the lifetime of the
+ * transaction.
+ *
+ * @param[in] transaction  Non-null.
+ * @param[in] output_index The index of the transaction output to be retrieved.
+ * @return                 The transaction output
+ */
+BITCOINKERNEL_API const btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_get_output_at(
+    const btck_Transaction* transaction, size_t output_index) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the number of inputs of a transaction.
+ *
+ * @param[in] transaction Non-null.
+ * @return                The number of inputs.
+ */
+BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_count_inputs(
+    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the transaction.
+ */
+BITCOINKERNEL_API void btck_transaction_destroy(btck_Transaction* transaction);
+
+///@}
+
+/** @name ScriptPubkey
+ * Functions for working with script pubkeys.
+ */
+///@{
+
+/**
+ * @brief Create a script pubkey from serialized data.
+ * @param[in] script_pubkey     Non-null.
+ * @param[in] script_pubkey_len Length of the script pubkey data.
+ * @return                      The script pubkey.
+ */
+BITCOINKERNEL_API btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_create(
+    const void* script_pubkey, size_t script_pubkey_len) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Copy a script pubkey.
+ *
+ * @param[in] script_pubkey Non-null.
+ * @return                  The copied script pubkey.
+ */
+BITCOINKERNEL_API btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_copy(
+    const btck_ScriptPubkey* script_pubkey) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Verify if the input at input_index of tx_to spends the script pubkey
+ * under the constraints specified by flags. If the
+ * `btck_ScriptVerificationFlags_WITNESS` flag is set in the flags bitfield, the
+ * amount parameter is used. If the taproot flag is set, the spent outputs
+ * parameter is used to validate taproot transactions.
+ *
+ * @param[in] script_pubkey     Non-null, script pubkey to be spent.
+ * @param[in] amount            Amount of the script pubkey's associated output. May be zero if
+ *                              the witness flag is not set.
+ * @param[in] tx_to             Non-null, transaction spending the script_pubkey.
+ * @param[in] spent_outputs     Nullable if the taproot flag is not set. Points to an array of
+ *                              outputs spent by the transaction.
+ * @param[in] spent_outputs_len Length of the spent_outputs array.
+ * @param[in] input_index       Index of the input in tx_to spending the script_pubkey.
+ * @param[in] flags             Bitfield of btck_ScriptVerificationFlags controlling validation constraints.
+ * @param[out] status           Nullable, will be set to an error code if the operation fails, or OK otherwise.
+ * @return                      1 if the script is valid, 0 otherwise.
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_verify(
+    const btck_ScriptPubkey* script_pubkey,
+    int64_t amount,
+    const btck_Transaction* tx_to,
+    const btck_TransactionOutput** spent_outputs, size_t spent_outputs_len,
+    unsigned int input_index,
+    unsigned int flags,
+    btck_ScriptVerifyStatus* status) BITCOINKERNEL_ARG_NONNULL(1, 3);
+
+/**
+ * @brief Serializes the script pubkey through the passed in callback to bytes.
+ *
+ * @param[in] script_pubkey Non-null.
+ * @param[in] writer        Non-null, callback to a write bytes function.
+ * @param[in] user_data     Holds a user-defined opaque structure that will be
+ *                          passed back through the writer callback.
+ * @return                  0 on success.
+ */
+BITCOINKERNEL_API int btck_script_pubkey_to_bytes(
+    const btck_ScriptPubkey* script_pubkey,
+    btck_WriteBytes writer,
+    void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
+/**
+ * Destroy the script pubkey.
+ */
+BITCOINKERNEL_API void btck_script_pubkey_destroy(btck_ScriptPubkey* script_pubkey);
+
+///@}
+
+/** @name TransactionOutput
+ * Functions for working with transaction outputs.
+ */
+///@{
+
+/**
+ * @brief Create a transaction output from a script pubkey and an amount.
+ *
+ * @param[in] script_pubkey Non-null.
+ * @param[in] amount        The amount associated with the script pubkey for this output.
+ * @return                  The transaction output.
+ */
+BITCOINKERNEL_API btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_create(
+    const btck_ScriptPubkey* script_pubkey,
+    int64_t amount) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the script pubkey of the output. The returned
+ * script pubkey is not owned and depends on the lifetime of the
+ * transaction output.
+ *
+ * @param[in] transaction_output Non-null.
+ * @return                       The script pubkey.
+ */
+BITCOINKERNEL_API const btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_get_script_pubkey(
+    const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the amount in the output.
+ *
+ * @param[in] transaction_output Non-null.
+ * @return                       The amount.
+ */
+BITCOINKERNEL_API int64_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_get_amount(
+    const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ *  @brief Copy a transaction output.
+ *
+ *  @param[in] transaction_output Non-null.
+ *  @return                       The copied transaction output.
+ */
+BITCOINKERNEL_API btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_copy(
+    const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the transaction output.
+ */
+BITCOINKERNEL_API void btck_transaction_output_destroy(btck_TransactionOutput* transaction_output);
+
+///@}
+
+#ifdef __cplusplus
+} // extern "C"
+#endif // __cplusplus
+
+#endif // BITCOIN_KERNEL_BITCOINKERNEL_H

src/kernel/bitcoinkernel_wrapper.h

@@ -0,0 +1,445 @@
+// Copyright (c) 2024-present The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#ifndef BITCOIN_KERNEL_BITCOINKERNEL_WRAPPER_H
+#define BITCOIN_KERNEL_BITCOINKERNEL_WRAPPER_H
+
+#include <kernel/bitcoinkernel.h>
+
+#include <functional>
+#include <memory>
+#include <span>
+#include <stdexcept>
+#include <type_traits>
+#include <utility>
+#include <vector>
+
+namespace btck {
+
+enum class ScriptVerifyStatus : btck_ScriptVerifyStatus {
+    OK = btck_ScriptVerifyStatus_OK,
+    ERROR_INVALID_FLAGS_COMBINATION = btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION,
+    ERROR_SPENT_OUTPUTS_REQUIRED = btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED,
+};
+
+enum class ScriptVerificationFlags : btck_ScriptVerificationFlags {
+    NONE = btck_ScriptVerificationFlags_NONE,
+    P2SH = btck_ScriptVerificationFlags_P2SH,
+    DERSIG = btck_ScriptVerificationFlags_DERSIG,
+    NULLDUMMY = btck_ScriptVerificationFlags_NULLDUMMY,
+    CHECKLOCKTIMEVERIFY = btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY,
+    CHECKSEQUENCEVERIFY = btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY,
+    WITNESS = btck_ScriptVerificationFlags_WITNESS,
+    TAPROOT = btck_ScriptVerificationFlags_TAPROOT,
+    ALL = btck_ScriptVerificationFlags_ALL
+};
+
+template <typename T>
+struct is_bitmask_enum : std::false_type {
+};
+
+template <>
+struct is_bitmask_enum<ScriptVerificationFlags> : std::true_type {
+};
+
+template <typename T>
+concept BitmaskEnum = is_bitmask_enum<T>::value;
+
+template <BitmaskEnum T>
+constexpr T operator|(T lhs, T rhs)
+{
+    return static_cast<T>(
+        static_cast<std::underlying_type_t<T>>(lhs) | static_cast<std::underlying_type_t<T>>(rhs));
+}
+
+template <BitmaskEnum T>
+constexpr T operator&(T lhs, T rhs)
+{
+    return static_cast<T>(
+        static_cast<std::underlying_type_t<T>>(lhs) & static_cast<std::underlying_type_t<T>>(rhs));
+}
+
+template <BitmaskEnum T>
+constexpr T operator^(T lhs, T rhs)
+{
+    return static_cast<T>(
+        static_cast<std::underlying_type_t<T>>(lhs) ^ static_cast<std::underlying_type_t<T>>(rhs));
+}
+
+template <BitmaskEnum T>
+constexpr T operator~(T value)
+{
+    return static_cast<T>(~static_cast<std::underlying_type_t<T>>(value));
+}
+
+template <BitmaskEnum T>
+constexpr T& operator|=(T& lhs, T rhs)
+{
+    return lhs = lhs | rhs;
+}
+
+template <BitmaskEnum T>
+constexpr T& operator&=(T& lhs, T rhs)
+{
+    return lhs = lhs & rhs;
+}
+
+template <BitmaskEnum T>
+constexpr T& operator^=(T& lhs, T rhs)
+{
+    return lhs = lhs ^ rhs;
+}
+
+template <typename T>
+T check(T ptr)
+{
+    if (ptr == nullptr) {
+        throw std::runtime_error("failed to instantiate btck object");
+    }
+    return ptr;
+}
+
+template <typename Collection, typename ValueType>
+class Iterator
+{
+public:
+    using iterator_category = std::random_access_iterator_tag;
+    using iterator_concept = std::random_access_iterator_tag;
+    using difference_type = std::ptrdiff_t;
+    using value_type = ValueType;
+
+private:
+    const Collection* m_collection;
+    size_t m_idx;
+
+public:
+    Iterator() = default;
+    Iterator(const Collection* ptr) : m_collection{ptr}, m_idx{0} {}
+    Iterator(const Collection* ptr, size_t idx) : m_collection{ptr}, m_idx{idx} {}
+
+    // This is just a view, so return a copy.
+    auto operator*() const { return (*m_collection)[m_idx]; }
+    auto operator->() const { return (*m_collection)[m_idx]; }
+
+    auto& operator++() { m_idx++; return *this; }
+    auto operator++(int) { Iterator tmp = *this; ++(*this); return tmp; }
+
+    auto& operator--() { m_idx--; return *this; }
+    auto operator--(int) { auto temp = *this; --m_idx; return temp; }
+
+    auto& operator+=(difference_type n) { m_idx += n; return *this; }
+    auto& operator-=(difference_type n) { m_idx -= n; return *this; }
+
+    auto operator+(difference_type n) const { return Iterator(m_collection, m_idx + n); }
+    auto operator-(difference_type n) const { return Iterator(m_collection, m_idx - n); }
+
+    auto operator-(const Iterator& other) const { return static_cast<difference_type>(m_idx) - static_cast<difference_type>(other.m_idx); }
+
+    ValueType operator[](difference_type n) const { return (*m_collection)[m_idx + n]; }
+
+    auto operator<=>(const Iterator& other) const { return m_idx <=> other.m_idx; }
+
+    bool operator==(const Iterator& other) const { return m_collection == other.m_collection && m_idx == other.m_idx; }
+
+private:
+    friend Iterator operator+(difference_type n, const Iterator& it) { return it + n; }
+};
+
+template <typename Container, typename SizeFunc, typename GetFunc>
+concept IndexedContainer = requires(const Container& c, SizeFunc size_func, GetFunc get_func, std::size_t i) {
+    { std::invoke(size_func, c) } -> std::convertible_to<std::size_t>;
+    { std::invoke(get_func, c, i) }; // Return type is deduced
+};
+
+template <typename Container, auto SizeFunc, auto GetFunc>
+    requires IndexedContainer<Container, decltype(SizeFunc), decltype(GetFunc)>
+class Range
+{
+public:
+    using value_type = std::invoke_result_t<decltype(GetFunc), const Container&, size_t>;
+    using difference_type = std::ptrdiff_t;
+    using iterator = Iterator<Range, value_type>;
+    using const_iterator = iterator;
+
+private:
+    const Container* m_container;
+
+public:
+    explicit Range(const Container& container) : m_container(&container)
+    {
+        static_assert(std::ranges::random_access_range<Range>);
+    }
+
+    iterator begin() const { return iterator(this, 0); }
+    iterator end() const { return iterator(this, size()); }
+
+    const_iterator cbegin() const { return begin(); }
+    const_iterator cend() const { return end(); }
+
+    size_t size() const { return std::invoke(SizeFunc, *m_container); }
+
+    bool empty() const { return size() == 0; }
+
+    value_type operator[](size_t index) const { return std::invoke(GetFunc, *m_container, index); }
+
+    value_type at(size_t index) const
+    {
+        if (index >= size()) {
+            throw std::out_of_range("Index out of range");
+        }
+        return (*this)[index];
+    }
+
+    value_type front() const { return (*this)[0]; }
+    value_type back() const { return (*this)[size() - 1]; }
+};
+
+#define MAKE_RANGE_METHOD(method_name, ContainerType, SizeFunc, GetFunc, container_expr) \
+    auto method_name() const & { \
+        return Range<ContainerType, SizeFunc, GetFunc>{container_expr}; \
+    } \
+    auto method_name() const && = delete;
+
+template <typename T>
+std::vector<std::byte> write_bytes(const T* object, int (*to_bytes)(const T*, btck_WriteBytes, void*))
+{
+    std::vector<std::byte> bytes;
+    struct UserData {
+        std::vector<std::byte>* bytes;
+        std::exception_ptr exception;
+    };
+    UserData user_data = UserData{.bytes = &bytes, .exception = nullptr};
+
+    constexpr auto const write = +[](const void* buffer, size_t len, void* user_data) -> int {
+        auto& data = *reinterpret_cast<UserData*>(user_data);
+        auto& bytes = *data.bytes;
+        try {
+            auto const* first = static_cast<const std::byte*>(buffer);
+            auto const* last = first + len;
+            bytes.insert(bytes.end(), first, last);
+            return 0;
+        } catch (...) {
+            data.exception = std::current_exception();
+            return -1;
+        }
+    };
+
+    if (to_bytes(object, write, &user_data) != 0) {
+        std::rethrow_exception(user_data.exception);
+    }
+    return bytes;
+}
+
+template <typename CType>
+class View
+{
+protected:
+    const CType* m_ptr;
+
+public:
+    explicit View(const CType* ptr) : m_ptr{check(ptr)} {}
+
+    const CType* get() const { return m_ptr; }
+};
+
+template <typename CType, CType* (*CopyFunc)(const CType*), void (*DestroyFunc)(CType*)>
+class Handle
+{
+protected:
+    CType* m_ptr;
+
+public:
+    explicit Handle(CType* ptr) : m_ptr{check(ptr)} {}
+
+    // Copy constructors
+    Handle(const Handle& other)
+        : m_ptr{check(CopyFunc(other.m_ptr))} {}
+    Handle& operator=(const Handle& other)
+    {
+        if (this != &other) {
+            Handle temp(other);
+            std::swap(m_ptr, temp.m_ptr);
+        }
+        return *this;
+    }
+
+    // Move constructors
+    Handle(Handle&& other) noexcept : m_ptr(other.m_ptr) { other.m_ptr = nullptr; }
+    Handle& operator=(Handle&& other) noexcept
+    {
+        DestroyFunc(m_ptr);
+        m_ptr = std::exchange(other.m_ptr, nullptr);
+        return *this;
+    }
+
+    template <typename ViewType>
+        requires std::derived_from<ViewType, View<CType>>
+    Handle(const ViewType& view)
+        : Handle{CopyFunc(view.get())}
+    {
+    }
+
+    ~Handle() { DestroyFunc(m_ptr); }
+
+    CType* get() { return m_ptr; }
+    const CType* get() const { return m_ptr; }
+};
+
+class Transaction;
+class TransactionOutput;
+
+template <typename Derived>
+class ScriptPubkeyApi
+{
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
+
+    friend Derived;
+    ScriptPubkeyApi() = default;
+
+public:
+    bool Verify(int64_t amount,
+                const Transaction& tx_to,
+                std::span<const TransactionOutput> spent_outputs,
+                unsigned int input_index,
+                ScriptVerificationFlags flags,
+                ScriptVerifyStatus& status) const;
+
+    std::vector<std::byte> ToBytes() const
+    {
+        return write_bytes(impl(), btck_script_pubkey_to_bytes);
+    }
+};
+
+class ScriptPubkeyView : public View<btck_ScriptPubkey>, public ScriptPubkeyApi<ScriptPubkeyView>
+{
+public:
+    explicit ScriptPubkeyView(const btck_ScriptPubkey* ptr) : View{ptr} {}
+};
+
+class ScriptPubkey : public Handle<btck_ScriptPubkey, btck_script_pubkey_copy, btck_script_pubkey_destroy>, public ScriptPubkeyApi<ScriptPubkey>
+{
+public:
+    explicit ScriptPubkey(std::span<const std::byte> raw)
+        : Handle{btck_script_pubkey_create(raw.data(), raw.size())} {}
+
+    ScriptPubkey(const ScriptPubkeyView& view)
+        : Handle(view) {}
+};
+
+template <typename Derived>
+class TransactionOutputApi
+{
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
+
+    friend Derived;
+    TransactionOutputApi() = default;
+
+public:
+    int64_t Amount() const
+    {
+        return btck_transaction_output_get_amount(impl());
+    }
+
+    ScriptPubkeyView GetScriptPubkey() const
+    {
+        return ScriptPubkeyView{btck_transaction_output_get_script_pubkey(impl())};
+    }
+};
+
+class TransactionOutputView : public View<btck_TransactionOutput>, public TransactionOutputApi<TransactionOutputView>
+{
+public:
+    explicit TransactionOutputView(const btck_TransactionOutput* ptr) : View{ptr} {}
+};
+
+class TransactionOutput : public Handle<btck_TransactionOutput, btck_transaction_output_copy, btck_transaction_output_destroy>, public TransactionOutputApi<TransactionOutput>
+{
+public:
+    explicit TransactionOutput(const ScriptPubkey& script_pubkey, int64_t amount)
+        : Handle{btck_transaction_output_create(script_pubkey.get(), amount)} {}
+
+    TransactionOutput(const TransactionOutputView& view)
+        : Handle(view) {}
+};
+
+template <typename Derived>
+class TransactionApi
+{
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
+
+public:
+    size_t CountOutputs() const
+    {
+        return btck_transaction_count_outputs(impl());
+    }
+
+    size_t CountInputs() const
+    {
+        return btck_transaction_count_inputs(impl());
+    }
+
+    TransactionOutputView GetOutput(size_t index) const
+    {
+        return TransactionOutputView{btck_transaction_get_output_at(impl(), index)};
+    }
+
+    MAKE_RANGE_METHOD(Outputs, Derived, &TransactionApi<Derived>::CountOutputs, &TransactionApi<Derived>::GetOutput, *static_cast<const Derived*>(this))
+
+    std::vector<std::byte> ToBytes() const
+    {
+        return write_bytes(impl(), btck_transaction_to_bytes);
+    }
+};
+
+class Transaction : public Handle<btck_Transaction, btck_transaction_copy, btck_transaction_destroy>, public TransactionApi<Transaction>
+{
+public:
+    explicit Transaction(std::span<const std::byte> raw_transaction)
+        : Handle{btck_transaction_create(raw_transaction.data(), raw_transaction.size())} {}
+};
+
+template <typename Derived>
+bool ScriptPubkeyApi<Derived>::Verify(int64_t amount,
+                                      const Transaction& tx_to,
+                                      const std::span<const TransactionOutput> spent_outputs,
+                                      unsigned int input_index,
+                                      ScriptVerificationFlags flags,
+                                      ScriptVerifyStatus& status) const
+{
+    const btck_TransactionOutput** spent_outputs_ptr = nullptr;
+    std::vector<const btck_TransactionOutput*> raw_spent_outputs;
+    if (spent_outputs.size() > 0) {
+        raw_spent_outputs.reserve(spent_outputs.size());
+
+        for (const auto& output : spent_outputs) {
+            raw_spent_outputs.push_back(output.get());
+        }
+        spent_outputs_ptr = raw_spent_outputs.data();
+    }
+    auto result = btck_script_pubkey_verify(
+        impl(),
+        amount,
+        tx_to.get(),
+        spent_outputs_ptr, spent_outputs.size(),
+        input_index,
+        static_cast<btck_ScriptVerificationFlags>(flags),
+        reinterpret_cast<btck_ScriptVerifyStatus*>(&status));
+    return result == 1;
+}
+
+} // namespace btck
+
+#endif // BITCOIN_KERNEL_BITCOINKERNEL_WRAPPER_H