From 2cf136dec4ce16c8a7c47b35c7c9244dfc3b6da8 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Tue, 28 May 2024 10:32:52 +0200
Subject: [PATCH 01/23] 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>
---
 .github/ci-test-each-commit-exec.py           |   2 +
 .github/workflows/ci.yml                      |   6 +-
 CMakeLists.txt                                |   3 +
 ci/test/00_setup_env_mac_cross.sh             |   2 +-
 ci/test/00_setup_env_mac_native.sh            |   2 +-
 ...up_env_native_nowallet_libbitcoinkernel.sh |   2 +-
 ci/test/00_setup_env_win64.sh                 |   2 +-
 src/CMakeLists.txt                            |   3 +
 src/kernel/CMakeLists.txt                     |   7 +
 src/kernel/bitcoinkernel.cpp                  | 248 +++++++++-
 src/kernel/bitcoinkernel.h                    | 340 +++++++++++++
 src/kernel/bitcoinkernel_wrapper.h            | 445 ++++++++++++++++++
 src/test/kernel/CMakeLists.txt                |  16 +
 src/test/kernel/test_kernel.cpp               | 346 ++++++++++++++
 14 files changed, 1415 insertions(+), 9 deletions(-)
 create mode 100644 src/kernel/bitcoinkernel.h
 create mode 100644 src/kernel/bitcoinkernel_wrapper.h
 create mode 100644 src/test/kernel/CMakeLists.txt
 create mode 100644 src/test/kernel/test_kernel.cpp

diff --git a/.github/ci-test-each-commit-exec.py b/.github/ci-test-each-commit-exec.py
index 3b2eaeeb596..959a1579aea 100755
--- a/.github/ci-test-each-commit-exec.py
+++ b/.github/ci-test-each-commit-exec.py
@@ -42,6 +42,8 @@ def main():
         "-DBUILD_BENCH=ON",
         "-DBUILD_FUZZ_BINARY=ON",
         "-DWITH_USDT=ON",
+        "-DBUILD_KERNEL_LIB=ON",
+        "-DBUILD_KERNEL_TEST=ON",
         "-DCMAKE_CXX_FLAGS=-Wno-error=unused-member-function",
     ])
     run(["cmake", "--build", "build", "-j", str(num_procs)])
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a05e8f96486..8370afd88f0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -202,7 +202,7 @@ jobs:
         job-type: [standard, fuzz]
         include:
           - job-type: standard
-            generate-options: '-DBUILD_GUI=ON -DWITH_ZMQ=ON -DBUILD_BENCH=ON -DWERROR=ON'
+            generate-options: '-DBUILD_GUI=ON -DWITH_ZMQ=ON -DBUILD_BENCH=ON -DBUILD_KERNEL_LIB=ON -DWERROR=ON'
             job-name: 'Windows native, VS 2022'
           - job-type: fuzz
             generate-options: '-DVCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON -DVCPKG_MANIFEST_FEATURES="wallet" -DBUILD_GUI=OFF -DBUILD_FOR_FUZZING=ON -DWERROR=ON'
@@ -280,7 +280,7 @@ jobs:
             $exeName = $_.Name
 
             # Skip as they currently do not have manifests
-            if ($exeName -eq "fuzz.exe" -or $exeName -eq "bench_bitcoin.exe" -or $exeName -eq "test_bitcoin-qt.exe") {
+            if ($exeName -eq "fuzz.exe" -or $exeName -eq "bench_bitcoin.exe" -or $exeName -eq "test_bitcoin-qt.exe" -or $exeName -eq "test_kernel.exe") {
               Write-Host "Skipping $exeName (no manifest present)"
               return
             }
@@ -399,7 +399,7 @@ jobs:
             $exeName = $_.Name
 
             # Skip as they currently do not have manifests
-            if ($exeName -eq "fuzz.exe" -or $exeName -eq "bench_bitcoin.exe") {
+            if ($exeName -eq "fuzz.exe" -or $exeName -eq "bench_bitcoin.exe" -or $exeName -eq "test_kernel.exe") {
               Write-Host "Skipping $exeName (no manifest present)"
               return
             }
diff --git a/CMakeLists.txt b/CMakeLists.txt
index c50e2f6d3f8..3749cf7c60e 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -105,6 +105,7 @@ option(BUILD_UTIL "Build bitcoin-util executable." ${BUILD_TESTS})
 
 option(BUILD_UTIL_CHAINSTATE "Build experimental bitcoin-chainstate executable." OFF)
 option(BUILD_KERNEL_LIB "Build experimental bitcoinkernel library." ${BUILD_UTIL_CHAINSTATE})
+option(BUILD_KERNEL_TEST "Build tests for the experimental bitcoinkernel library." ${BUILD_KERNEL_LIB})
 
 option(ENABLE_WALLET "Enable wallet." ON)
 if(ENABLE_WALLET)
@@ -210,6 +211,7 @@ if(BUILD_FOR_FUZZING)
   set(BUILD_UTIL OFF)
   set(BUILD_UTIL_CHAINSTATE OFF)
   set(BUILD_KERNEL_LIB OFF)
+  set(BUILD_KERNEL_TEST OFF)
   set(BUILD_WALLET_TOOL OFF)
   set(BUILD_GUI OFF)
   set(ENABLE_EXTERNAL_SIGNER OFF)
@@ -667,6 +669,7 @@ message("  bitcoin-util ........................ ${BUILD_UTIL}")
 message("  bitcoin-wallet ...................... ${BUILD_WALLET_TOOL}")
 message("  bitcoin-chainstate (experimental) ... ${BUILD_UTIL_CHAINSTATE}")
 message("  libbitcoinkernel (experimental) ..... ${BUILD_KERNEL_LIB}")
+message("  kernel-test (experimental) .......... ${BUILD_KERNEL_TEST}")
 message("Optional features:")
 message("  wallet support ...................... ${ENABLE_WALLET}")
 message("  external signer ..................... ${ENABLE_EXTERNAL_SIGNER}")
diff --git a/ci/test/00_setup_env_mac_cross.sh b/ci/test/00_setup_env_mac_cross.sh
index 027741dab4e..c7de0334721 100755
--- a/ci/test/00_setup_env_mac_cross.sh
+++ b/ci/test/00_setup_env_mac_cross.sh
@@ -17,4 +17,4 @@ export XCODE_BUILD_ID=15A240d
 export RUN_UNIT_TESTS=false
 export RUN_FUNCTIONAL_TESTS=false
 export GOAL="deploy"
-export BITCOIN_CONFIG="-DBUILD_GUI=ON -DREDUCE_EXPORTS=ON"
+export BITCOIN_CONFIG="-DBUILD_GUI=ON -DBUILD_KERNEL_LIB=ON -DREDUCE_EXPORTS=ON"
diff --git a/ci/test/00_setup_env_mac_native.sh b/ci/test/00_setup_env_mac_native.sh
index 41a3bc45877..00770beb901 100755
--- a/ci/test/00_setup_env_mac_native.sh
+++ b/ci/test/00_setup_env_mac_native.sh
@@ -12,7 +12,7 @@ export CONTAINER_NAME="ci_mac_native"  # macos does not use a container, but the
 export PIP_PACKAGES="--break-system-packages zmq"
 export GOAL="install deploy"
 export CMAKE_GENERATOR="Ninja"
-export BITCOIN_CONFIG="-DBUILD_GUI=ON -DWITH_ZMQ=ON -DREDUCE_EXPORTS=ON -DCMAKE_EXE_LINKER_FLAGS='-Wl,-stack_size -Wl,0x80000'"
+export BITCOIN_CONFIG="-DBUILD_GUI=ON -DWITH_ZMQ=ON -DBUILD_KERNEL_LIB=ON -DBUILD_UTIL_CHAINSTATE=ON -DBUILD_KERNEL_TEST=ON -DREDUCE_EXPORTS=ON -DCMAKE_EXE_LINKER_FLAGS='-Wl,-stack_size -Wl,0x80000'"
 export CI_OS_NAME="macos"
 export NO_DEPENDS=1
 export OSX_SDK=""
diff --git a/ci/test/00_setup_env_native_nowallet_libbitcoinkernel.sh b/ci/test/00_setup_env_native_nowallet_libbitcoinkernel.sh
index 58561e55204..b1e0c65e246 100755
--- a/ci/test/00_setup_env_native_nowallet_libbitcoinkernel.sh
+++ b/ci/test/00_setup_env_native_nowallet_libbitcoinkernel.sh
@@ -13,4 +13,4 @@ export PACKAGES="python3-zmq python3-pip clang-16 llvm-16 libc++abi-16-dev libc+
 export PIP_PACKAGES="--break-system-packages pycapnp"
 export DEP_OPTS="NO_WALLET=1 CC=clang-16 CXX='clang++-16 -stdlib=libc++'"
 export GOAL="install"
-export BITCOIN_CONFIG="-DREDUCE_EXPORTS=ON -DBUILD_UTIL_CHAINSTATE=ON -DBUILD_KERNEL_LIB=ON -DBUILD_SHARED_LIBS=ON"
+export BITCOIN_CONFIG="-DREDUCE_EXPORTS=ON -DBUILD_UTIL_CHAINSTATE=ON -DBUILD_KERNEL_LIB=ON -DBUILD_KERNEL_TEST=ON -DBUILD_SHARED_LIBS=ON"
diff --git a/ci/test/00_setup_env_win64.sh b/ci/test/00_setup_env_win64.sh
index f929f34c68f..1ea67230fbe 100755
--- a/ci/test/00_setup_env_win64.sh
+++ b/ci/test/00_setup_env_win64.sh
@@ -13,5 +13,5 @@ export PACKAGES="g++-mingw-w64-x86-64-posix nsis"
 export RUN_UNIT_TESTS=false
 export RUN_FUNCTIONAL_TESTS=false
 export GOAL="deploy"
-export BITCOIN_CONFIG="-DREDUCE_EXPORTS=ON -DBUILD_GUI_TESTS=OFF \
+export BITCOIN_CONFIG="-DREDUCE_EXPORTS=ON -DBUILD_GUI_TESTS=OFF -DBUILD_KERNEL_LIB=ON -DBUILD_KERNEL_TEST=ON \
 -DCMAKE_CXX_FLAGS='-Wno-error=maybe-uninitialized'"
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index bcadd675346..7c7e0fe718a 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -404,6 +404,9 @@ endif()
 
 if(BUILD_KERNEL_LIB)
   add_subdirectory(kernel)
+  if (BUILD_KERNEL_TEST)
+    add_subdirectory(test/kernel)
+  endif()
 endif()
 
 if(BUILD_UTIL_CHAINSTATE)
diff --git a/src/kernel/CMakeLists.txt b/src/kernel/CMakeLists.txt
index c45ce7819e9..7b2f3c7d11f 100644
--- a/src/kernel/CMakeLists.txt
+++ b/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)
diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 9096b6f71de..50608dc37c0 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/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;
+}
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
new file mode 100644
index 00000000000..bb16cd11842
--- /dev/null
+++ b/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
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
new file mode 100644
index 00000000000..d50dee38bc4
--- /dev/null
+++ b/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
diff --git a/src/test/kernel/CMakeLists.txt b/src/test/kernel/CMakeLists.txt
new file mode 100644
index 00000000000..17900bddeb4
--- /dev/null
+++ b/src/test/kernel/CMakeLists.txt
@@ -0,0 +1,16 @@
+add_executable(test_kernel
+    test_kernel.cpp
+)
+
+target_link_libraries(test_kernel
+  PRIVATE
+    core_interface
+    bitcoinkernel
+    Boost::headers
+)
+
+set_target_properties(test_kernel PROPERTIES
+  SKIP_BUILD_RPATH OFF
+)
+
+add_test(NAME test_kernel COMMAND test_kernel)
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
new file mode 100644
index 00000000000..632a01d038e
--- /dev/null
+++ b/src/test/kernel/test_kernel.cpp
@@ -0,0 +1,346 @@
+// 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.
+
+#include <kernel/bitcoinkernel.h>
+#include <kernel/bitcoinkernel_wrapper.h>
+
+#define BOOST_TEST_MODULE Bitcoin Kernel Test Suite
+#include <boost/test/included/unit_test.hpp>
+
+#include <charconv>
+#include <cstdint>
+#include <cstdlib>
+#include <iostream>
+#include <ranges>
+#include <span>
+#include <vector>
+
+using namespace btck;
+
+std::vector<std::byte> hex_string_to_byte_vec(std::string_view hex)
+{
+    std::vector<std::byte> bytes;
+    bytes.reserve(hex.length() / 2);
+
+    for (size_t i{0}; i < hex.length(); i += 2) {
+        uint8_t byte_value;
+        auto [ptr, ec] = std::from_chars(hex.data() + i, hex.data() + i + 2, byte_value, 16);
+
+        if (ec != std::errc{} || ptr != hex.data() + i + 2) {
+            throw std::invalid_argument("Invalid hex character");
+        }
+        bytes.push_back(static_cast<std::byte>(byte_value));
+    }
+    return bytes;
+}
+
+constexpr auto VERIFY_ALL_PRE_SEGWIT{ScriptVerificationFlags::P2SH | ScriptVerificationFlags::DERSIG |
+                                     ScriptVerificationFlags::NULLDUMMY | ScriptVerificationFlags::CHECKLOCKTIMEVERIFY |
+                                     ScriptVerificationFlags::CHECKSEQUENCEVERIFY};
+constexpr auto VERIFY_ALL_PRE_TAPROOT{VERIFY_ALL_PRE_SEGWIT | ScriptVerificationFlags::WITNESS};
+
+void check_equal(std::span<const std::byte> _actual, std::span<const std::byte> _expected, bool equal = true)
+{
+    std::span<const uint8_t> actual{reinterpret_cast<const unsigned char*>(_actual.data()), _actual.size()};
+    std::span<const uint8_t> expected{reinterpret_cast<const unsigned char*>(_expected.data()), _expected.size()};
+    BOOST_CHECK_EQUAL_COLLECTIONS(
+        actual.begin(), actual.end(),
+        expected.begin(), expected.end());
+}
+
+void run_verify_test(
+    const ScriptPubkey& spent_script_pubkey,
+    const Transaction& spending_tx,
+    std::span<TransactionOutput> spent_outputs,
+    int64_t amount,
+    unsigned int input_index,
+    bool taproot)
+{
+    auto status = ScriptVerifyStatus::OK;
+
+    if (taproot) {
+        BOOST_CHECK(spent_script_pubkey.Verify(
+            amount,
+            spending_tx,
+            spent_outputs,
+            input_index,
+            ScriptVerificationFlags::ALL,
+            status));
+        BOOST_CHECK(status == ScriptVerifyStatus::OK);
+    } else {
+        BOOST_CHECK(!spent_script_pubkey.Verify(
+            amount,
+            spending_tx,
+            spent_outputs,
+            input_index,
+            ScriptVerificationFlags::ALL,
+            status));
+        BOOST_CHECK(status == ScriptVerifyStatus::ERROR_SPENT_OUTPUTS_REQUIRED);
+    }
+
+    BOOST_CHECK(spent_script_pubkey.Verify(
+        amount,
+        spending_tx,
+        spent_outputs,
+        input_index,
+        VERIFY_ALL_PRE_TAPROOT,
+        status));
+    BOOST_CHECK(status == ScriptVerifyStatus::OK);
+
+    BOOST_CHECK(spent_script_pubkey.Verify(
+        0,
+        spending_tx,
+        spent_outputs,
+        input_index,
+        VERIFY_ALL_PRE_SEGWIT,
+        status));
+    BOOST_CHECK(status == ScriptVerifyStatus::OK);
+}
+
+template <typename T>
+concept HasToBytes = requires(T t) {
+    { t.ToBytes() } -> std::convertible_to<std::vector<std::byte>>;
+};
+
+template <typename T>
+void CheckHandle(T object, T distinct_object)
+{
+    BOOST_CHECK(object.get() != nullptr);
+    BOOST_CHECK(distinct_object.get() != nullptr);
+    BOOST_CHECK(object.get() != distinct_object.get());
+
+    if constexpr (HasToBytes<T>) {
+        BOOST_CHECK_NE(object.ToBytes().size(), distinct_object.ToBytes().size());
+    }
+
+    // Copy constructor
+    T object2(distinct_object);
+    BOOST_CHECK_NE(distinct_object.get(), object2.get());
+    if constexpr (HasToBytes<T>) {
+        check_equal(distinct_object.ToBytes(), object2.ToBytes());
+    }
+
+    // Copy assignment
+    T object3{distinct_object};
+    object2 = object3;
+    BOOST_CHECK_NE(object3.get(), object2.get());
+    if constexpr (HasToBytes<T>) {
+        check_equal(object3.ToBytes(), object2.ToBytes());
+    }
+
+    // Move constructor
+    auto* original_ptr = object2.get();
+    T object4{std::move(object2)};
+    BOOST_CHECK_EQUAL(object4.get(), original_ptr);
+    BOOST_CHECK_EQUAL(object2.get(), nullptr); // NOLINT(bugprone-use-after-move)
+    if constexpr (HasToBytes<T>) {
+        check_equal(object4.ToBytes(), object3.ToBytes());
+    }
+
+    // Move assignment
+    original_ptr = object4.get();
+    object2 = std::move(object4);
+    BOOST_CHECK_EQUAL(object2.get(), original_ptr);
+    BOOST_CHECK_EQUAL(object4.get(), nullptr); // NOLINT(bugprone-use-after-move)
+    if constexpr (HasToBytes<T>) {
+        check_equal(object2.ToBytes(), object3.ToBytes());
+    }
+}
+
+template <typename RangeType>
+    requires std::ranges::random_access_range<RangeType>
+void CheckRange(const RangeType& range, size_t expected_size)
+{
+    using value_type = std::ranges::range_value_t<RangeType>;
+
+    BOOST_CHECK_EQUAL(range.size(), expected_size);
+    BOOST_CHECK_EQUAL(range.empty(), (expected_size == 0));
+
+    BOOST_CHECK(range.begin() != range.end());
+    BOOST_CHECK_EQUAL(std::distance(range.begin(), range.end()), static_cast<std::ptrdiff_t>(expected_size));
+    BOOST_CHECK(range.cbegin() == range.begin());
+    BOOST_CHECK(range.cend() == range.end());
+
+    for (size_t i = 0; i < range.size(); ++i) {
+        BOOST_CHECK_EQUAL(range[i].get(), (*(range.begin() + i)).get());
+    }
+
+    BOOST_CHECK_NE(range.at(0).get(), range.at(expected_size - 1).get());
+    BOOST_CHECK_THROW(range.at(expected_size), std::out_of_range);
+
+    BOOST_CHECK_EQUAL(range.front().get(), range[0].get());
+    BOOST_CHECK_EQUAL(range.back().get(), range[expected_size - 1].get());
+
+    auto it = range.begin();
+    auto it_copy = it;
+    ++it;
+    BOOST_CHECK(it != it_copy);
+    --it;
+    BOOST_CHECK(it == it_copy);
+    it = range.begin();
+    auto old_it = it++;
+    BOOST_CHECK(old_it == range.begin());
+    BOOST_CHECK(it == range.begin() + 1);
+    old_it = it--;
+    BOOST_CHECK(old_it == range.begin() + 1);
+    BOOST_CHECK(it == range.begin());
+
+    it = range.begin();
+    it += 2;
+    BOOST_CHECK(it == range.begin() + 2);
+    it -= 2;
+    BOOST_CHECK(it == range.begin());
+
+    BOOST_CHECK(range.begin() < range.end());
+    BOOST_CHECK(range.begin() <= range.end());
+    BOOST_CHECK(range.end() > range.begin());
+    BOOST_CHECK(range.end() >= range.begin());
+    BOOST_CHECK(range.begin() == range.begin());
+
+    BOOST_CHECK_EQUAL(range.begin()[0].get(), range[0].get());
+
+    size_t count = 0;
+    for (auto rit = range.end(); rit != range.begin();) {
+        --rit;
+        ++count;
+    }
+    BOOST_CHECK_EQUAL(count, expected_size);
+
+    std::vector<value_type> collected;
+    for (const auto& elem : range) {
+        collected.push_back(elem);
+    }
+    BOOST_CHECK_EQUAL(collected.size(), expected_size);
+
+    BOOST_CHECK_EQUAL(std::ranges::size(range), expected_size);
+
+    it = range.begin();
+    auto it2 = 1 + it;
+    BOOST_CHECK(it2 == it + 1);
+}
+
+BOOST_AUTO_TEST_CASE(btck_transaction_tests)
+{
+    auto tx_data{hex_string_to_byte_vec("02000000013f7cebd65c27431a90bba7f796914fe8cc2ddfc3f2cbd6f7e5f2fc854534da95000000006b483045022100de1ac3bcdfb0332207c4a91f3832bd2c2915840165f876ab47c5f8996b971c3602201c6c053d750fadde599e6f5c4e1963df0f01fc0d97815e8157e3d59fe09ca30d012103699b464d1d8bc9e47d4fb1cdaa89a1c5783d68363c4dbc4b524ed3d857148617feffffff02836d3c01000000001976a914fc25d6d5c94003bf5b0c7b640a248e2c637fcfb088ac7ada8202000000001976a914fbed3d9b11183209a57999d54d59f67c019e756c88ac6acb0700")};
+    auto tx{Transaction{tx_data}};
+    auto tx_data_2{hex_string_to_byte_vec("02000000000101904f4ee5c87d20090b642f116e458cd6693292ad9ece23e72f15fb6c05b956210500000000fdffffff02e2010000000000002251200839a723933b56560487ec4d67dda58f09bae518ffa7e148313c5696ac837d9f10060000000000002251205826bcdae7abfb1c468204170eab00d887b61ab143464a4a09e1450bdc59a3340140f26e7af574e647355830772946356c27e7bbc773c5293688890f58983499581be84de40be7311a14e6d6422605df086620e75adae84ff06b75ce5894de5e994a00000000")};
+    auto tx2{Transaction{tx_data_2}};
+    CheckHandle(tx, tx2);
+
+    BOOST_CHECK_EQUAL(tx.CountOutputs(), 2);
+    BOOST_CHECK_EQUAL(tx.CountInputs(), 1);
+    auto broken_tx_data{std::span<std::byte>{tx_data.begin(), tx_data.begin() + 10}};
+    BOOST_CHECK_THROW(Transaction{broken_tx_data}, std::runtime_error);
+    auto output{tx.GetOutput(tx.CountOutputs() - 1)};
+    BOOST_CHECK_EQUAL(output.Amount(), 42130042);
+    auto script_pubkey{output.GetScriptPubkey()};
+    {
+        auto tx_new{Transaction{tx_data}};
+        // This is safe, because we now use copy assignment
+        TransactionOutput output = tx_new.GetOutput(tx_new.CountOutputs() - 1);
+        ScriptPubkey script = output.GetScriptPubkey();
+
+        TransactionOutputView output2 = tx_new.GetOutput(tx_new.CountOutputs() - 1);
+        BOOST_CHECK_NE(output.get(), output2.get());
+        BOOST_CHECK_EQUAL(output.Amount(), output2.Amount());
+        TransactionOutput output3 = output2;
+        BOOST_CHECK_NE(output3.get(), output2.get());
+        BOOST_CHECK_EQUAL(output3.Amount(), output2.Amount());
+
+        // Non-owned view
+        ScriptPubkeyView script2 = output.GetScriptPubkey();
+        BOOST_CHECK_NE(script.get(), script2.get());
+        check_equal(script.ToBytes(), script2.ToBytes());
+
+        // Non-owned to owned
+        ScriptPubkey script3 = script2;
+        BOOST_CHECK_NE(script3.get(), script2.get());
+        check_equal(script3.ToBytes(), script2.ToBytes());
+    }
+    BOOST_CHECK_EQUAL(output.Amount(), 42130042);
+
+    auto tx_roundtrip{Transaction{tx.ToBytes()}};
+    check_equal(tx_roundtrip.ToBytes(), tx_data);
+
+    // The following code is unsafe, but left here to show limitations of the
+    // API, because we preserve the output view beyond the lifetime of the
+    // transaction. The view type wrapper should make this clear to the user.
+    // auto get_output = [&]() -> TransactionOutputView {
+    //     auto tx{Transaction{tx_data}};
+    //     return tx.GetOutput(0);
+    // };
+    // auto output_new = get_output();
+    // BOOST_CHECK_EQUAL(output_new.Amount(), 20737411);
+
+    int64_t total_amount{0};
+    for (const auto output : tx.Outputs()) {
+        total_amount += output.Amount();
+    }
+    BOOST_CHECK_EQUAL(total_amount, 62867453);
+
+    auto amount = *(tx.Outputs() | std::ranges::views::filter([](const auto& output) {
+                        return output.Amount() == 42130042;
+                    }) |
+                    std::views::transform([](const auto& output) {
+                        return output.Amount();
+                    })).begin();
+    BOOST_REQUIRE(amount);
+    BOOST_CHECK_EQUAL(amount, 42130042);
+
+    CheckRange(tx.Outputs(), tx.CountOutputs());
+
+    ScriptPubkey script_pubkey_roundtrip{script_pubkey.ToBytes()};
+    check_equal(script_pubkey_roundtrip.ToBytes(), script_pubkey.ToBytes());
+}
+
+BOOST_AUTO_TEST_CASE(btck_script_pubkey)
+{
+    auto script_data{hex_string_to_byte_vec("76a9144bfbaf6afb76cc5771bc6404810d1cc041a6933988ac")};
+    std::vector<std::byte> script_data_2 = script_data;
+    script_data_2.push_back(std::byte{0x51});
+    ScriptPubkey script{script_data};
+    ScriptPubkey script2{script_data_2};
+    CheckHandle(script, script2);
+}
+
+BOOST_AUTO_TEST_CASE(btck_transaction_output)
+{
+    ScriptPubkey script{hex_string_to_byte_vec("76a9144bfbaf6afb76cc5771bc6404810d1cc041a6933988ac")};
+    TransactionOutput output{script, 1};
+    TransactionOutput output2{script, 2};
+    CheckHandle(output, output2);
+}
+
+BOOST_AUTO_TEST_CASE(btck_script_verify_tests)
+{
+    // Legacy transaction aca326a724eda9a461c10a876534ecd5ae7b27f10f26c3862fb996f80ea2d45d
+    run_verify_test(
+        /*spent_script_pubkey*/ ScriptPubkey{hex_string_to_byte_vec("76a9144bfbaf6afb76cc5771bc6404810d1cc041a6933988ac")},
+        /*spending_tx*/ Transaction{hex_string_to_byte_vec("02000000013f7cebd65c27431a90bba7f796914fe8cc2ddfc3f2cbd6f7e5f2fc854534da95000000006b483045022100de1ac3bcdfb0332207c4a91f3832bd2c2915840165f876ab47c5f8996b971c3602201c6c053d750fadde599e6f5c4e1963df0f01fc0d97815e8157e3d59fe09ca30d012103699b464d1d8bc9e47d4fb1cdaa89a1c5783d68363c4dbc4b524ed3d857148617feffffff02836d3c01000000001976a914fc25d6d5c94003bf5b0c7b640a248e2c637fcfb088ac7ada8202000000001976a914fbed3d9b11183209a57999d54d59f67c019e756c88ac6acb0700")},
+        /*spent_outputs*/ {},
+        /*amount*/ 0,
+        /*input_index*/ 0,
+        /*is_taproot*/ false);
+
+    // Segwit transaction 1a3e89644985fbbb41e0dcfe176739813542b5937003c46a07de1e3ee7a4a7f3
+    run_verify_test(
+        /*spent_script_pubkey*/ ScriptPubkey{hex_string_to_byte_vec("0020701a8d401c84fb13e6baf169d59684e17abd9fa216c8cc5b9fc63d622ff8c58d")},
+        /*spending_tx*/ Transaction{hex_string_to_byte_vec("010000000001011f97548fbbe7a0db7588a66e18d803d0089315aa7d4cc28360b6ec50ef36718a0100000000ffffffff02df1776000000000017a9146c002a686959067f4866b8fb493ad7970290ab728757d29f0000000000220020701a8d401c84fb13e6baf169d59684e17abd9fa216c8cc5b9fc63d622ff8c58d04004730440220565d170eed95ff95027a69b313758450ba84a01224e1f7f130dda46e94d13f8602207bdd20e307f062594022f12ed5017bbf4a055a06aea91c10110a0e3bb23117fc014730440220647d2dc5b15f60bc37dc42618a370b2a1490293f9e5c8464f53ec4fe1dfe067302203598773895b4b16d37485cbe21b337f4e4b650739880098c592553add7dd4355016952210375e00eb72e29da82b89367947f29ef34afb75e8654f6ea368e0acdfd92976b7c2103a1b26313f430c4b15bb1fdce663207659d8cac749a0e53d70eff01874496feff2103c96d495bfdd5ba4145e3e046fee45e84a8a48ad05bd8dbb395c011a32cf9f88053ae00000000")},
+        /*spent_outputs*/ {},
+        /*amount*/ 18393430,
+        /*input_index*/ 0,
+        /*is_taproot*/ false);
+
+    // Taproot transaction 33e794d097969002ee05d336686fc03c9e15a597c1b9827669460fac98799036
+    auto taproot_spent_script_pubkey{ScriptPubkey{hex_string_to_byte_vec("5120339ce7e165e67d93adb3fef88a6d4beed33f01fa876f05a225242b82a631abc0")}};
+    std::vector<TransactionOutput> spent_outputs;
+    spent_outputs.emplace_back(taproot_spent_script_pubkey, 88480);
+    run_verify_test(
+        /*spent_script_pubkey*/ taproot_spent_script_pubkey,
+        /*spending_tx*/ Transaction{hex_string_to_byte_vec("01000000000101d1f1c1f8cdf6759167b90f52c9ad358a369f95284e841d7a2536cef31c0549580100000000fdffffff020000000000000000316a2f49206c696b65205363686e6f7272207369677320616e6420492063616e6e6f74206c69652e204062697462756734329e06010000000000225120a37c3903c8d0db6512e2b40b0dffa05e5a3ab73603ce8c9c4b7771e5412328f90140a60c383f71bac0ec919b1d7dbc3eb72dd56e7aa99583615564f9f99b8ae4e837b758773a5b2e4c51348854c8389f008e05029db7f464a5ff2e01d5e6e626174affd30a00")},
+        /*spent_outputs*/ spent_outputs,
+        /*amount*/ 88480,
+        /*input_index*/ 0,
+        /*is_taproot*/ true);
+}

From 28d679bad9fda3f180ab0f7d34353e1fa9294d68 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Wed, 29 May 2024 16:13:45 +0200
Subject: [PATCH 02/23] kernel: Add logging to kernel library C header

Exposing logging in the kernel library allows users to follow
operations. Users of the C header can use
`kernel_logging_connection_create(...)` to pass a callback function to
Bitcoin Core's internal logger. Additionally the level and category can
be globally configured.

By default, the logger buffers messages until
`kernel_loggin_connection_create(...)` is called. If the user does not
want any logging messages, it is recommended that
`kernel_disable_logging()` is called, which permanently disables the
logging and any buffering of messages.

Co-authored-by: stringintech <stringintech@gmail.com>
---
 src/kernel/bitcoinkernel.cpp       | 160 +++++++++++++++++++++++++++++
 src/kernel/bitcoinkernel.h         | 147 ++++++++++++++++++++++++++
 src/kernel/bitcoinkernel_wrapper.h |  83 +++++++++++++++
 src/logging.cpp                    |   1 +
 src/logging.h                      |  12 +++
 src/test/kernel/test_kernel.cpp    |  37 +++++++
 6 files changed, 440 insertions(+)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 50608dc37c0..4aa2c176d88 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -8,17 +8,22 @@
 
 #include <consensus/amount.h>
 #include <kernel/context.h>
+#include <kernel/cs_main.h>
+#include <logging.h>
 #include <primitives/transaction.h>
 #include <script/interpreter.h>
 #include <script/script.h>
 #include <serialize.h>
 #include <streams.h>
+#include <tinyformat.h>
 #include <util/translation.h>
 
+#include <cassert>
 #include <cstddef>
 #include <cstring>
 #include <exception>
 #include <functional>
+#include <list>
 #include <span>
 #include <string>
 #include <utility>
@@ -103,11 +108,116 @@ struct Handle {
     }
 };
 
+BCLog::Level get_bclog_level(btck_LogLevel level)
+{
+    switch (level) {
+    case btck_LogLevel_INFO: {
+        return BCLog::Level::Info;
+    }
+    case btck_LogLevel_DEBUG: {
+        return BCLog::Level::Debug;
+    }
+    case btck_LogLevel_TRACE: {
+        return BCLog::Level::Trace;
+    }
+    }
+    assert(false);
+}
+
+BCLog::LogFlags get_bclog_flag(btck_LogCategory category)
+{
+    switch (category) {
+    case btck_LogCategory_BENCH: {
+        return BCLog::LogFlags::BENCH;
+    }
+    case btck_LogCategory_BLOCKSTORAGE: {
+        return BCLog::LogFlags::BLOCKSTORAGE;
+    }
+    case btck_LogCategory_COINDB: {
+        return BCLog::LogFlags::COINDB;
+    }
+    case btck_LogCategory_LEVELDB: {
+        return BCLog::LogFlags::LEVELDB;
+    }
+    case btck_LogCategory_MEMPOOL: {
+        return BCLog::LogFlags::MEMPOOL;
+    }
+    case btck_LogCategory_PRUNE: {
+        return BCLog::LogFlags::PRUNE;
+    }
+    case btck_LogCategory_RAND: {
+        return BCLog::LogFlags::RAND;
+    }
+    case btck_LogCategory_REINDEX: {
+        return BCLog::LogFlags::REINDEX;
+    }
+    case btck_LogCategory_VALIDATION: {
+        return BCLog::LogFlags::VALIDATION;
+    }
+    case btck_LogCategory_KERNEL: {
+        return BCLog::LogFlags::KERNEL;
+    }
+    case btck_LogCategory_ALL: {
+        return BCLog::LogFlags::ALL;
+    }
+    }
+    assert(false);
+}
+
+struct LoggingConnection {
+    std::unique_ptr<std::list<std::function<void(const std::string&)>>::iterator> m_connection;
+    void* m_user_data;
+    std::function<void(void* user_data)> m_deleter;
+
+    LoggingConnection(btck_LogCallback callback, void* user_data, btck_DestroyCallback user_data_destroy_callback)
+    {
+        LOCK(cs_main);
+
+        auto connection{LogInstance().PushBackCallback([callback, user_data](const std::string& str) { callback(user_data, str.c_str(), str.length()); })};
+
+        // Only start logging if we just added the connection.
+        if (LogInstance().NumConnections() == 1 && !LogInstance().StartLogging()) {
+            LogError("Logger start failed.");
+            LogInstance().DeleteCallback(connection);
+            if (user_data && user_data_destroy_callback) {
+                user_data_destroy_callback(user_data);
+            }
+            throw std::runtime_error("Failed to start logging");
+        }
+
+        m_connection = std::make_unique<std::list<std::function<void(const std::string&)>>::iterator>(connection);
+        m_user_data = user_data;
+        m_deleter = user_data_destroy_callback;
+
+        LogDebug(BCLog::KERNEL, "Logger connected.");
+    }
+
+    ~LoggingConnection()
+    {
+        LOCK(cs_main);
+        LogDebug(BCLog::KERNEL, "Logger disconnecting.");
+
+        // Switch back to buffering by calling DisconnectTestLogger if the
+        // connection that we are about to remove is the last one.
+        if (LogInstance().NumConnections() == 1) {
+            LogInstance().DisconnectTestLogger();
+        } else {
+            LogInstance().DeleteCallback(*m_connection);
+        }
+
+        m_connection.reset();
+        if (m_user_data && m_deleter) {
+            m_deleter(m_user_data);
+        }
+    }
+};
+
 } // 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> {};
+struct btck_LoggingConnection : Handle<btck_LoggingConnection, LoggingConnection> {};
 
 btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
 {
@@ -253,3 +363,53 @@ int btck_script_pubkey_verify(const btck_ScriptPubkey* script_pubkey,
                                nullptr);
     return result ? 1 : 0;
 }
+
+
+void btck_logging_set_options(const btck_LoggingOptions options)
+{
+    LOCK(cs_main);
+    LogInstance().m_log_timestamps = options.log_timestamps;
+    LogInstance().m_log_time_micros = options.log_time_micros;
+    LogInstance().m_log_threadnames = options.log_threadnames;
+    LogInstance().m_log_sourcelocations = options.log_sourcelocations;
+    LogInstance().m_always_print_category_level = options.always_print_category_levels;
+}
+
+void btck_logging_set_level_category(btck_LogCategory category, btck_LogLevel level)
+{
+    LOCK(cs_main);
+    if (category == btck_LogCategory_ALL) {
+        LogInstance().SetLogLevel(get_bclog_level(level));
+    }
+
+    LogInstance().AddCategoryLogLevel(get_bclog_flag(category), get_bclog_level(level));
+}
+
+void btck_logging_enable_category(btck_LogCategory category)
+{
+    LogInstance().EnableCategory(get_bclog_flag(category));
+}
+
+void btck_logging_disable_category(btck_LogCategory category)
+{
+    LogInstance().DisableCategory(get_bclog_flag(category));
+}
+
+void btck_logging_disable()
+{
+    LogInstance().DisableLogging();
+}
+
+btck_LoggingConnection* btck_logging_connection_create(btck_LogCallback callback, void* user_data, btck_DestroyCallback user_data_destroy_callback)
+{
+    try {
+        return btck_LoggingConnection::create(callback, user_data, user_data_destroy_callback);
+    } catch (const std::exception&) {
+        return nullptr;
+    }
+}
+
+void btck_logging_connection_destroy(btck_LoggingConnection* connection)
+{
+    delete connection;
+}
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index bb16cd11842..1576b79edd3 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -99,6 +99,69 @@ typedef struct btck_ScriptPubkey btck_ScriptPubkey;
  */
 typedef struct btck_TransactionOutput btck_TransactionOutput;
 
+/**
+ * Opaque data structure for holding a logging connection.
+ *
+ * The logging connection can be used to manually stop logging.
+ *
+ * Messages that were logged before a connection is created are buffered in a
+ * 1MB buffer. Logging can alternatively be permanently disabled by calling
+ * @ref btck_logging_disable. Functions changing the logging settings are
+ * global and change the settings for all existing btck_LoggingConnection
+ * instances.
+ */
+typedef struct btck_LoggingConnection btck_LoggingConnection;
+
+/** Callback function types */
+
+/**
+ * Function signature for the global logging callback. All bitcoin kernel
+ * internal logs will pass through this callback.
+ */
+typedef void (*btck_LogCallback)(void* user_data, const char* message, size_t message_len);
+
+/**
+ * Function signature for freeing user data.
+ */
+typedef void (*btck_DestroyCallback)(void* user_data);
+
+/**
+ * A collection of logging categories that may be encountered by kernel code.
+ */
+typedef uint8_t btck_LogCategory;
+#define btck_LogCategory_ALL ((btck_LogCategory)(0))
+#define btck_LogCategory_BENCH ((btck_LogCategory)(1))
+#define btck_LogCategory_BLOCKSTORAGE ((btck_LogCategory)(2))
+#define btck_LogCategory_COINDB ((btck_LogCategory)(3))
+#define btck_LogCategory_LEVELDB ((btck_LogCategory)(4))
+#define btck_LogCategory_MEMPOOL ((btck_LogCategory)(5))
+#define btck_LogCategory_PRUNE ((btck_LogCategory)(6))
+#define btck_LogCategory_RAND ((btck_LogCategory)(7))
+#define btck_LogCategory_REINDEX ((btck_LogCategory)(8))
+#define btck_LogCategory_VALIDATION ((btck_LogCategory)(9))
+#define btck_LogCategory_KERNEL ((btck_LogCategory)(10))
+
+/**
+ * The level at which logs should be produced.
+ */
+typedef uint8_t btck_LogLevel;
+#define btck_LogLevel_TRACE ((btck_LogLevel)(0))
+#define btck_LogLevel_DEBUG ((btck_LogLevel)(1))
+#define btck_LogLevel_INFO ((btck_LogLevel)(2))
+
+/**
+ * Options controlling the format of log messages.
+ *
+ * Set fields as non-zero to indicate true.
+ */
+typedef struct {
+    int log_timestamps;               //!< Prepend a timestamp to log messages.
+    int log_time_micros;              //!< Log timestamps in microsecond precision.
+    int log_threadnames;              //!< Prepend the name of the thread to log messages.
+    int log_sourcelocations;          //!< Prepend the source location to log messages.
+    int always_print_category_levels; //!< Prepend the log category and level to log messages.
+} btck_LoggingOptions;
+
 /**
  * A collection of status codes that may be issued by the script verify function.
  */
@@ -333,6 +396,90 @@ BITCOINKERNEL_API void btck_transaction_output_destroy(btck_TransactionOutput* t
 
 ///@}
 
+/** @name Logging
+ * Logging-related functions.
+ */
+///@{
+
+/**
+ * @brief This disables the global internal logger. No log messages will be
+ * buffered internally anymore once this is called and the buffer is cleared.
+ * This function should only be called once and is not thread or re-entry safe.
+ * Log messages will be buffered until this function is called, or a logging
+ * connection is created. This must not be called while a logging connection
+ * already exists.
+ */
+BITCOINKERNEL_API void btck_logging_disable();
+
+/**
+ * @brief Set some options for the global internal logger. This changes global
+ * settings and will override settings for all existing @ref
+ * btck_LoggingConnection instances.
+ *
+ * @param[in] options Sets formatting options of the log messages.
+ */
+BITCOINKERNEL_API void btck_logging_set_options(const btck_LoggingOptions options);
+
+/**
+ * @brief Set the log level of the global internal logger. This does not
+ * enable the selected categories. Use @ref btck_logging_enable_category to
+ * start logging from a specific, or all categories. This changes a global
+ * setting and will override settings for all existing
+ * @ref btck_LoggingConnection instances.
+ *
+ * @param[in] category If btck_LogCategory_ALL is chosen, sets both the global fallback log level
+ *                     used by all categories that don't have a specific level set, and also
+ *                     sets the log level for messages logged with the btck_LogCategory_ALL category itself.
+ *                     For any other category, sets a category-specific log level that overrides
+ *                     the global fallback for that category only.
+
+ * @param[in] level    Log level at which the log category is set.
+ */
+BITCOINKERNEL_API void btck_logging_set_level_category(btck_LogCategory category, btck_LogLevel level);
+
+/**
+ * @brief Enable a specific log category for the global internal logger. This
+ * changes a global setting and will override settings for all existing @ref
+ * btck_LoggingConnection instances.
+ *
+ * @param[in] category If btck_LogCategory_ALL is chosen, all categories will be enabled.
+ */
+BITCOINKERNEL_API void btck_logging_enable_category(btck_LogCategory category);
+
+/**
+ * @brief Disable a specific log category for the global internal logger. This
+ * changes a global setting and will override settings for all existing @ref
+ * btck_LoggingConnection instances.
+ *
+ * @param[in] category If btck_LogCategory_ALL is chosen, all categories will be disabled.
+ */
+BITCOINKERNEL_API void btck_logging_disable_category(btck_LogCategory category);
+
+/**
+ * @brief Start logging messages through the provided callback. Log messages
+ * produced before this function is first called are buffered and on calling this
+ * function are logged immediately.
+ *
+ * @param[in] log_callback               Non-null, function through which messages will be logged.
+ * @param[in] user_data                  Nullable, holds a user-defined opaque structure. Is passed back
+ *                                       to the user through the callback. If the user_data_destroy_callback
+ *                                       is also defined it is assumed that ownership of the user_data is passed
+ *                                       to the created logging connection.
+ * @param[in] user_data_destroy_callback Nullable, function for freeing the user data.
+ * @return                               A new kernel logging connection, or null on error.
+ */
+BITCOINKERNEL_API btck_LoggingConnection* BITCOINKERNEL_WARN_UNUSED_RESULT btck_logging_connection_create(
+    btck_LogCallback log_callback,
+    void* user_data,
+    btck_DestroyCallback user_data_destroy_callback) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Stop logging and destroy the logging connection.
+ */
+BITCOINKERNEL_API void btck_logging_connection_destroy(btck_LoggingConnection* logging_connection);
+
+///@}
+
 #ifdef __cplusplus
 } // extern "C"
 #endif // __cplusplus
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index d50dee38bc4..c828e9b3e79 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -11,12 +11,33 @@
 #include <memory>
 #include <span>
 #include <stdexcept>
+#include <string_view>
 #include <type_traits>
 #include <utility>
 #include <vector>
 
 namespace btck {
 
+enum class LogCategory : btck_LogCategory {
+    ALL = btck_LogCategory_ALL,
+    BENCH = btck_LogCategory_BENCH,
+    BLOCKSTORAGE = btck_LogCategory_BLOCKSTORAGE,
+    COINDB = btck_LogCategory_COINDB,
+    LEVELDB = btck_LogCategory_LEVELDB,
+    MEMPOOL = btck_LogCategory_MEMPOOL,
+    PRUNE = btck_LogCategory_PRUNE,
+    RAND = btck_LogCategory_RAND,
+    REINDEX = btck_LogCategory_REINDEX,
+    VALIDATION = btck_LogCategory_VALIDATION,
+    KERNEL = btck_LogCategory_KERNEL
+};
+
+enum class LogLevel : btck_LogLevel {
+    TRACE_LEVEL = btck_LogLevel_TRACE,
+    DEBUG_LEVEL = btck_LogLevel_DEBUG,
+    INFO_LEVEL = btck_LogLevel_INFO
+};
+
 enum class ScriptVerifyStatus : btck_ScriptVerifyStatus {
     OK = btck_ScriptVerifyStatus_OK,
     ERROR_INVALID_FLAGS_COMBINATION = btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION,
@@ -286,6 +307,25 @@ public:
     const CType* get() const { return m_ptr; }
 };
 
+template <typename CType, void (*DestroyFunc)(CType*)>
+class UniqueHandle
+{
+protected:
+    struct Deleter {
+        void operator()(CType* ptr) const noexcept
+        {
+            if (ptr) DestroyFunc(ptr);
+        }
+    };
+    std::unique_ptr<CType, Deleter> m_ptr;
+
+public:
+    explicit UniqueHandle(CType* ptr) : m_ptr{check(ptr)} {}
+
+    CType* get() { return m_ptr.get(); }
+    const CType* get() const { return m_ptr.get(); }
+};
+
 class Transaction;
 class TransactionOutput;
 
@@ -440,6 +480,49 @@ bool ScriptPubkeyApi<Derived>::Verify(int64_t amount,
     return result == 1;
 }
 
+inline void logging_disable()
+{
+    btck_logging_disable();
+}
+
+inline void logging_set_options(const btck_LoggingOptions& logging_options)
+{
+    btck_logging_set_options(logging_options);
+}
+
+inline void logging_set_level_category(LogCategory category, LogLevel level)
+{
+    btck_logging_set_level_category(static_cast<btck_LogCategory>(category), static_cast<btck_LogLevel>(level));
+}
+
+inline void logging_enable_category(LogCategory category)
+{
+    btck_logging_enable_category(static_cast<btck_LogCategory>(category));
+}
+
+inline void logging_disable_category(LogCategory category)
+{
+    btck_logging_disable_category(static_cast<btck_LogCategory>(category));
+}
+
+template <typename T>
+concept Log = requires(T a, std::string_view message) {
+    { a.LogMessage(message) } -> std::same_as<void>;
+};
+
+template <Log T>
+class Logger : UniqueHandle<btck_LoggingConnection, btck_logging_connection_destroy>
+{
+public:
+    Logger(std::unique_ptr<T> log)
+        : UniqueHandle{btck_logging_connection_create(
+              +[](void* user_data, const char* message, size_t message_len) { static_cast<T*>(user_data)->LogMessage({message, message_len}); },
+              log.release(),
+              +[](void* user_data) { delete static_cast<T*>(user_data); })}
+    {
+    }
+};
+
 } // namespace btck
 
 #endif // BITCOIN_KERNEL_BITCOINKERNEL_WRAPPER_H
diff --git a/src/logging.cpp b/src/logging.cpp
index 2ed6835197b..f9d8f980488 100644
--- a/src/logging.cpp
+++ b/src/logging.cpp
@@ -201,6 +201,7 @@ static const std::map<std::string, BCLog::LogFlags, std::less<>> LOG_CATEGORIES_
     {"txreconciliation", BCLog::TXRECONCILIATION},
     {"scan", BCLog::SCAN},
     {"txpackages", BCLog::TXPACKAGES},
+    {"kernel", BCLog::KERNEL},
 };
 
 static const std::unordered_map<BCLog::LogFlags, std::string> LOG_CATEGORIES_BY_FLAG{
diff --git a/src/logging.h b/src/logging.h
index 723aeb790fb..defff61d300 100644
--- a/src/logging.h
+++ b/src/logging.h
@@ -94,6 +94,7 @@ namespace BCLog {
         TXRECONCILIATION = (CategoryMask{1} << 26),
         SCAN        = (CategoryMask{1} << 27),
         TXPACKAGES  = (CategoryMask{1} << 28),
+        KERNEL      = (CategoryMask{1} << 29),
         ALL         = ~NONE,
     };
     enum class Level {
@@ -256,6 +257,12 @@ namespace BCLog {
             m_print_callbacks.erase(it);
         }
 
+        size_t NumConnections()
+        {
+            StdLockGuard scoped_lock(m_cs);
+            return m_print_callbacks.size();
+        }
+
         /** Start logging (and flush all buffered messages) */
         bool StartLogging() EXCLUSIVE_LOCKS_REQUIRED(!m_cs);
         /** Only for testing */
@@ -287,6 +294,11 @@ namespace BCLog {
             StdLockGuard scoped_lock(m_cs);
             m_category_log_levels = levels;
         }
+        void AddCategoryLogLevel(LogFlags category, Level level)
+        {
+            StdLockGuard scoped_lock(m_cs);
+            m_category_log_levels[category] = level;
+        }
         bool SetCategoryLogLevel(std::string_view category_str, std::string_view level_str) EXCLUSIVE_LOCKS_REQUIRED(!m_cs);
 
         Level LogLevel() const { return m_log_level.load(); }
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 632a01d038e..ea7b2c741d2 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -12,8 +12,10 @@
 #include <cstdint>
 #include <cstdlib>
 #include <iostream>
+#include <memory>
 #include <ranges>
 #include <span>
+#include <string_view>
 #include <vector>
 
 using namespace btck;
@@ -49,6 +51,15 @@ void check_equal(std::span<const std::byte> _actual, std::span<const std::byte>
         expected.begin(), expected.end());
 }
 
+class TestLog
+{
+public:
+    void LogMessage(std::string_view message)
+    {
+        std::cout << "kernel: " << message;
+    }
+};
+
 void run_verify_test(
     const ScriptPubkey& spent_script_pubkey,
     const Transaction& spending_tx,
@@ -344,3 +355,29 @@ BOOST_AUTO_TEST_CASE(btck_script_verify_tests)
         /*input_index*/ 0,
         /*is_taproot*/ true);
 }
+
+BOOST_AUTO_TEST_CASE(logging_tests)
+{
+    btck_LoggingOptions logging_options = {
+        .log_timestamps = true,
+        .log_time_micros = true,
+        .log_threadnames = false,
+        .log_sourcelocations = false,
+        .always_print_category_levels = true,
+    };
+
+    logging_set_options(logging_options);
+    logging_set_level_category(LogCategory::BENCH, LogLevel::TRACE_LEVEL);
+    logging_disable_category(LogCategory::BENCH);
+    logging_enable_category(LogCategory::VALIDATION);
+    logging_disable_category(LogCategory::VALIDATION);
+
+    // Check that connecting, connecting another, and then disconnecting and connecting a logger again works.
+    {
+        logging_set_level_category(LogCategory::KERNEL, LogLevel::TRACE_LEVEL);
+        logging_enable_category(LogCategory::KERNEL);
+        Logger logger{std::make_unique<TestLog>()};
+        Logger logger_2{std::make_unique<TestLog>()};
+    }
+    Logger logger{std::make_unique<TestLog>()};
+}

From 337ea860dfda12dac084209027a54fba857e7a89 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Mon, 3 Jun 2024 14:35:47 +0200
Subject: [PATCH 03/23] kernel: Add kernel library context object

The context introduced here holds the objects that will be required for
running validation tasks, such as the chosen chain parameters, callbacks
for validation events, and interrupt handling. These will be used by the
chainstate manager introduced in subsequent commits.

This commit also introduces conventions for defining option objects. A
common pattern throughout the C header will be:
```
options = object_option_create();
object = object_create(options);
```
This allows for more consistent usage of a "builder pattern" for
objects where options can be configured independently from
instantiation.
---
 src/kernel/bitcoinkernel.cpp       | 66 ++++++++++++++++++++++++++
 src/kernel/bitcoinkernel.h         | 74 ++++++++++++++++++++++++++++++
 src/kernel/bitcoinkernel_wrapper.h | 16 +++++++
 src/test/kernel/test_kernel.cpp    | 14 ++++++
 4 files changed, 170 insertions(+)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 4aa2c176d88..8f29ac81636 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -7,8 +7,11 @@
 #include <kernel/bitcoinkernel.h>
 
 #include <consensus/amount.h>
+#include <kernel/chainparams.h>
+#include <kernel/checks.h>
 #include <kernel/context.h>
 #include <kernel/cs_main.h>
+#include <kernel/notifications_interface.h>
 #include <logging.h>
 #include <primitives/transaction.h>
 #include <script/interpreter.h>
@@ -16,6 +19,8 @@
 #include <serialize.h>
 #include <streams.h>
 #include <tinyformat.h>
+#include <util/result.h>
+#include <util/signalinterrupt.h>
 #include <util/translation.h>
 
 #include <cassert>
@@ -24,6 +29,7 @@
 #include <exception>
 #include <functional>
 #include <list>
+#include <memory>
 #include <span>
 #include <string>
 #include <utility>
@@ -212,12 +218,40 @@ struct LoggingConnection {
     }
 };
 
+struct ContextOptions {
+};
+
+class Context
+{
+public:
+    std::unique_ptr<kernel::Context> m_context;
+
+    std::unique_ptr<kernel::Notifications> m_notifications;
+
+    std::unique_ptr<util::SignalInterrupt> m_interrupt;
+
+    std::unique_ptr<const CChainParams> m_chainparams;
+
+    Context(const ContextOptions* options, bool& sane)
+        : m_context{std::make_unique<kernel::Context>()},
+          m_notifications{std::make_unique<kernel::Notifications>()},
+          m_interrupt{std::make_unique<util::SignalInterrupt>()},
+          m_chainparams{CChainParams::Main()}
+    {
+        if (!kernel::SanityChecks(*m_context)) {
+            sane = false;
+        }
+    }
+};
+
 } // 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> {};
 struct btck_LoggingConnection : Handle<btck_LoggingConnection, LoggingConnection> {};
+struct btck_ContextOptions : Handle<btck_ContextOptions, ContextOptions> {};
+struct btck_Context : Handle<btck_Context, std::shared_ptr<const Context>> {};
 
 btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
 {
@@ -413,3 +447,35 @@ void btck_logging_connection_destroy(btck_LoggingConnection* connection)
 {
     delete connection;
 }
+
+btck_ContextOptions* btck_context_options_create()
+{
+    return btck_ContextOptions::create();
+}
+
+void btck_context_options_destroy(btck_ContextOptions* options)
+{
+    delete options;
+}
+
+btck_Context* btck_context_create(const btck_ContextOptions* options)
+{
+    bool sane{true};
+    const ContextOptions* opts = options ? &btck_ContextOptions::get(options) : nullptr;
+    auto context{std::make_shared<const Context>(opts, sane)};
+    if (!sane) {
+        LogError("Kernel context sanity check failed.");
+        return nullptr;
+    }
+    return btck_Context::create(context);
+}
+
+btck_Context* btck_context_copy(const btck_Context* context)
+{
+    return btck_Context::copy(context);
+}
+
+void btck_context_destroy(btck_Context* context)
+{
+    delete context;
+}
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 1576b79edd3..2cf714db164 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -57,6 +57,9 @@ extern "C" {
  * otherwise "context-free" operations. This means that the user is not
  * required to initialize their own context before using the library.
  *
+ * The user should create their own context for passing it to state-rich validation
+ * functions and holding callbacks for kernel events.
+ *
  * @section error Error handling
  *
  * Functions communicate an error through their return types, usually returning
@@ -112,6 +115,30 @@ typedef struct btck_TransactionOutput btck_TransactionOutput;
  */
 typedef struct btck_LoggingConnection btck_LoggingConnection;
 
+/**
+ * Opaque data structure for holding options for creating a new kernel context.
+ *
+ * Once a kernel context has been created from these options, they may be
+ * destroyed. The options hold the notification and validation interface
+ * callbacks as well as the selected chain type until they are passed to the
+ * context. If no options are configured, the context will be instantiated with
+ * no callbacks and for mainnet. Their content and scope can be expanded over
+ * time.
+ */
+typedef struct btck_ContextOptions btck_ContextOptions;
+
+/**
+ * Opaque data structure for holding a kernel context.
+ *
+ * The kernel context is used to initialize internal state and hold the chain
+ * parameters and callbacks for handling error and validation events. Once
+ * other validation objects are instantiated from it, the context is kept in
+ * memory for the duration of their lifetimes.
+ *
+ * A constructed context can be safely used from multiple threads.
+ */
+typedef struct btck_Context btck_Context;
+
 /** Callback function types */
 
 /**
@@ -480,6 +507,53 @@ BITCOINKERNEL_API void btck_logging_connection_destroy(btck_LoggingConnection* l
 
 ///@}
 
+/** @name ContextOptions
+ * Functions for working with context options.
+ */
+///@{
+
+/**
+ * Creates an empty context options.
+ */
+BITCOINKERNEL_API btck_ContextOptions* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_options_create();
+
+/**
+ * Destroy the context options.
+ */
+BITCOINKERNEL_API void btck_context_options_destroy(btck_ContextOptions* context_options);
+
+///@}
+
+/** @name Context
+ * Functions for working with contexts.
+ */
+///@{
+
+/**
+ * @brief Create a new kernel context. If the options have not been previously
+ * set, their corresponding fields will be initialized to default values; the
+ * context will assume mainnet chain parameters and won't attempt to call the
+ * kernel notification callbacks.
+ *
+ * @param[in] context_options Nullable, created by @ref btck_context_options_create.
+ * @return                    The allocated kernel context, or null on error.
+ */
+BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_create(
+    const btck_ContextOptions* context_options);
+
+/**
+ * Copy the context.
+ */
+BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_copy(
+    const btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the context.
+ */
+BITCOINKERNEL_API void btck_context_destroy(btck_Context* context);
+
+///@}
+
 #ifdef __cplusplus
 } // extern "C"
 #endif // __cplusplus
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index c828e9b3e79..070592d8fb8 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -523,6 +523,22 @@ public:
     }
 };
 
+class ContextOptions : public UniqueHandle<btck_ContextOptions, btck_context_options_destroy>
+{
+public:
+    ContextOptions() : UniqueHandle{btck_context_options_create()} {}
+};
+
+class Context : public Handle<btck_Context, btck_context_copy, btck_context_destroy>
+{
+public:
+    Context(ContextOptions& opts)
+        : Handle{btck_context_create(opts.get())} {}
+
+    Context()
+        : Handle{btck_context_create(ContextOptions{}.get())} {}
+};
+
 } // namespace btck
 
 #endif // BITCOIN_KERNEL_BITCOINKERNEL_WRAPPER_H
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index ea7b2c741d2..e349cedbc56 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -381,3 +381,17 @@ BOOST_AUTO_TEST_CASE(logging_tests)
     }
     Logger logger{std::make_unique<TestLog>()};
 }
+
+BOOST_AUTO_TEST_CASE(btck_context_tests)
+{
+    { // test default context
+        Context context{};
+        Context context2{};
+        CheckHandle(context, context2);
+    }
+
+    { // test with context options
+        ContextOptions options{};
+        Context context{options};
+    }
+}

From 9e1bac45852d177cf387314a54053a3f7ec8ce99 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Mon, 3 Jun 2024 14:44:55 +0200
Subject: [PATCH 04/23] kernel: Add chain params context option to C header

As a first option, add the chainparams. For now these can only be
instantiated with default values. In future they may be expanded to take
their own options for regtest and signet configurations.

This commit also introduces a unique pattern for setting the option
values when calling the `*_set(...)` function.
---
 src/kernel/bitcoinkernel.cpp       | 62 +++++++++++++++++++++++++++++-
 src/kernel/bitcoinkernel.h         | 55 ++++++++++++++++++++++++++
 src/kernel/bitcoinkernel_wrapper.h | 20 ++++++++++
 src/test/kernel/test_kernel.cpp    | 11 +++++-
 4 files changed, 145 insertions(+), 3 deletions(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 8f29ac81636..35e03372f6b 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -18,6 +18,7 @@
 #include <script/script.h>
 #include <serialize.h>
 #include <streams.h>
+#include <sync.h>
 #include <tinyformat.h>
 #include <util/result.h>
 #include <util/signalinterrupt.h>
@@ -108,6 +109,11 @@ struct Handle {
         return *reinterpret_cast<const CPP*>(ptr);
     }
 
+    static CPP& get(C* ptr)
+    {
+        return *reinterpret_cast<CPP*>(ptr);
+    }
+
     static void operator delete(void* ptr)
     {
         delete reinterpret_cast<CPP*>(ptr);
@@ -219,6 +225,8 @@ struct LoggingConnection {
 };
 
 struct ContextOptions {
+    mutable Mutex m_mutex;
+    std::unique_ptr<const CChainParams> m_chainparams GUARDED_BY(m_mutex);
 };
 
 class Context
@@ -235,9 +243,19 @@ public:
     Context(const ContextOptions* options, bool& sane)
         : m_context{std::make_unique<kernel::Context>()},
           m_notifications{std::make_unique<kernel::Notifications>()},
-          m_interrupt{std::make_unique<util::SignalInterrupt>()},
-          m_chainparams{CChainParams::Main()}
+          m_interrupt{std::make_unique<util::SignalInterrupt>()}
     {
+        if (options) {
+            LOCK(options->m_mutex);
+            if (options->m_chainparams) {
+                m_chainparams = std::make_unique<const CChainParams>(*options->m_chainparams);
+            }
+        }
+
+        if (!m_chainparams) {
+            m_chainparams = CChainParams::Main();
+        }
+
         if (!kernel::SanityChecks(*m_context)) {
             sane = false;
         }
@@ -252,6 +270,7 @@ struct btck_ScriptPubkey : Handle<btck_ScriptPubkey, CScript> {};
 struct btck_LoggingConnection : Handle<btck_LoggingConnection, LoggingConnection> {};
 struct btck_ContextOptions : Handle<btck_ContextOptions, ContextOptions> {};
 struct btck_Context : Handle<btck_Context, std::shared_ptr<const Context>> {};
+struct btck_ChainParameters : Handle<btck_ChainParameters, CChainParams> {};
 
 btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
 {
@@ -448,11 +467,50 @@ void btck_logging_connection_destroy(btck_LoggingConnection* connection)
     delete connection;
 }
 
+btck_ChainParameters* btck_chain_parameters_create(const btck_ChainType chain_type)
+{
+    switch (chain_type) {
+    case btck_ChainType_MAINNET: {
+        return btck_ChainParameters::ref(const_cast<CChainParams*>(CChainParams::Main().release()));
+    }
+    case btck_ChainType_TESTNET: {
+        return btck_ChainParameters::ref(const_cast<CChainParams*>(CChainParams::TestNet().release()));
+    }
+    case btck_ChainType_TESTNET_4: {
+        return btck_ChainParameters::ref(const_cast<CChainParams*>(CChainParams::TestNet4().release()));
+    }
+    case btck_ChainType_SIGNET: {
+        return btck_ChainParameters::ref(const_cast<CChainParams*>(CChainParams::SigNet({}).release()));
+    }
+    case btck_ChainType_REGTEST: {
+        return btck_ChainParameters::ref(const_cast<CChainParams*>(CChainParams::RegTest({}).release()));
+    }
+    }
+    assert(false);
+}
+
+btck_ChainParameters* btck_chain_parameters_copy(const btck_ChainParameters* chain_parameters)
+{
+    return btck_ChainParameters::copy(chain_parameters);
+}
+
+void btck_chain_parameters_destroy(btck_ChainParameters* chain_parameters)
+{
+    delete chain_parameters;
+}
+
 btck_ContextOptions* btck_context_options_create()
 {
     return btck_ContextOptions::create();
 }
 
+void btck_context_options_set_chainparams(btck_ContextOptions* options, const btck_ChainParameters* chain_parameters)
+{
+    // Copy the chainparams, so the caller can free it again
+    LOCK(btck_ContextOptions::get(options).m_mutex);
+    btck_ContextOptions::get(options).m_chainparams = std::make_unique<const CChainParams>(btck_ChainParameters::get(chain_parameters));
+}
+
 void btck_context_options_destroy(btck_ContextOptions* options)
 {
     delete options;
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 2cf714db164..f901dedd102 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -115,6 +115,15 @@ typedef struct btck_TransactionOutput btck_TransactionOutput;
  */
 typedef struct btck_LoggingConnection btck_LoggingConnection;
 
+/**
+ * Opaque data structure for holding the chain parameters.
+ *
+ * These are eventually placed into a kernel context through the kernel context
+ * options. The parameters describe the properties of a chain, and may be
+ * instantiated for either mainnet, testnet, signet, or regtest.
+ */
+typedef struct btck_ChainParameters btck_ChainParameters;
+
 /**
  * Opaque data structure for holding options for creating a new kernel context.
  *
@@ -217,6 +226,13 @@ typedef uint32_t btck_ScriptVerificationFlags;
                                                                          btck_ScriptVerificationFlags_WITNESS |             \
                                                                          btck_ScriptVerificationFlags_TAPROOT))
 
+typedef uint8_t btck_ChainType;
+#define btck_ChainType_MAINNET ((btck_ChainType)(0))
+#define btck_ChainType_TESTNET ((btck_ChainType)(1))
+#define btck_ChainType_TESTNET_4 ((btck_ChainType)(2))
+#define btck_ChainType_SIGNET ((btck_ChainType)(3))
+#define btck_ChainType_REGTEST ((btck_ChainType)(4))
+
 /**
  * Function signature for serializing data.
  */
@@ -507,6 +523,34 @@ BITCOINKERNEL_API void btck_logging_connection_destroy(btck_LoggingConnection* l
 
 ///@}
 
+/** @name ChainParameters
+ * Functions for working with chain parameters.
+ */
+///@{
+
+/**
+ * @brief Creates a chain parameters struct with default parameters based on the
+ * passed in chain type.
+ *
+ * @param[in] chain_type Controls the chain parameters type created.
+ * @return               An allocated chain parameters opaque struct.
+ */
+BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_create(
+    const btck_ChainType chain_type);
+
+/**
+ * Copy the chain parameters.
+ */
+BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_copy(
+    const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the chain parameters.
+ */
+BITCOINKERNEL_API void btck_chain_parameters_destroy(btck_ChainParameters* chain_parameters);
+
+///@}
+
 /** @name ContextOptions
  * Functions for working with context options.
  */
@@ -517,6 +561,17 @@ BITCOINKERNEL_API void btck_logging_connection_destroy(btck_LoggingConnection* l
  */
 BITCOINKERNEL_API btck_ContextOptions* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_options_create();
 
+/**
+ * @brief Sets the chain params for the context options. The context created
+ * with the options will be configured for these chain parameters.
+ *
+ * @param[in] context_options  Non-null, previously created by @ref btck_context_options_create.
+ * @param[in] chain_parameters Is set to the context options.
+ */
+BITCOINKERNEL_API void btck_context_options_set_chainparams(
+    btck_ContextOptions* context_options,
+    const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
 /**
  * Destroy the context options.
  */
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index 070592d8fb8..b550c3a5333 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -38,6 +38,14 @@ enum class LogLevel : btck_LogLevel {
     INFO_LEVEL = btck_LogLevel_INFO
 };
 
+enum class ChainType : btck_ChainType {
+    MAINNET = btck_ChainType_MAINNET,
+    TESTNET = btck_ChainType_TESTNET,
+    TESTNET_4 = btck_ChainType_TESTNET_4,
+    SIGNET = btck_ChainType_SIGNET,
+    REGTEST = btck_ChainType_REGTEST
+};
+
 enum class ScriptVerifyStatus : btck_ScriptVerifyStatus {
     OK = btck_ScriptVerifyStatus_OK,
     ERROR_INVALID_FLAGS_COMBINATION = btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION,
@@ -523,10 +531,22 @@ public:
     }
 };
 
+class ChainParams : public Handle<btck_ChainParameters, btck_chain_parameters_copy, btck_chain_parameters_destroy>
+{
+public:
+    ChainParams(ChainType chain_type)
+        : Handle{btck_chain_parameters_create(static_cast<btck_ChainType>(chain_type))} {}
+};
+
 class ContextOptions : public UniqueHandle<btck_ContextOptions, btck_context_options_destroy>
 {
 public:
     ContextOptions() : UniqueHandle{btck_context_options_create()} {}
+
+    void SetChainParams(ChainParams& chain_params)
+    {
+        btck_context_options_set_chainparams(get(), chain_params.get());
+    }
 };
 
 class Context : public Handle<btck_Context, btck_context_copy, btck_context_destroy>
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index e349cedbc56..8fc0308c0df 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -390,8 +390,17 @@ BOOST_AUTO_TEST_CASE(btck_context_tests)
         CheckHandle(context, context2);
     }
 
-    { // test with context options
+    { // test with context options, but not options set
         ContextOptions options{};
         Context context{options};
     }
+
+    { // test with context options
+        ContextOptions options{};
+        ChainParams params{ChainType::MAINNET};
+        ChainParams regtest_params{ChainType::REGTEST};
+        CheckHandle(params, regtest_params);
+        options.SetChainParams(params);
+        Context context{options};
+    }
 }

From c62f657ba330572969ab5e86c739712e800bcbcb Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Mon, 3 Jun 2024 14:51:29 +0200
Subject: [PATCH 05/23] kernel: Add notifications context option to C header

The notifications are used for notifying on connected blocks and on
warning and fatal error conditions.

The user of the C header may define callbacks that gets passed to the
internal notification object in the
`kernel_NotificationInterfaceCallbacks` struct.

Each of the callbacks take a `user_data` argument that gets populated
from the `user_data` value in the struct. It can be used to recreate the
structure containing the callbacks on the user's side, or to give the
callbacks additional contextual information.
---
 src/kernel/bitcoinkernel.cpp       | 103 ++++++++++++++++++++++++++++-
 src/kernel/bitcoinkernel.h         |  79 +++++++++++++++++++++-
 src/kernel/bitcoinkernel_wrapper.h |  61 +++++++++++++++++
 src/test/kernel/test_kernel.cpp    |  30 +++++++++
 4 files changed, 270 insertions(+), 3 deletions(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 35e03372f6b..2670287ab4a 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -12,6 +12,7 @@
 #include <kernel/context.h>
 #include <kernel/cs_main.h>
 #include <kernel/notifications_interface.h>
+#include <kernel/warning.h>
 #include <logging.h>
 #include <primitives/transaction.h>
 #include <script/interpreter.h>
@@ -23,6 +24,7 @@
 #include <util/result.h>
 #include <util/signalinterrupt.h>
 #include <util/translation.h>
+#include <validation.h>
 
 #include <cassert>
 #include <cstddef>
@@ -36,6 +38,8 @@
 #include <utility>
 #include <vector>
 
+class CBlockIndex;
+
 // Define G_TRANSLATION_FUN symbol in libbitcoinkernel library so users of the
 // library aren't required to export this symbol
 extern const std::function<std::string(const char*)> G_TRANSLATION_FUN{nullptr};
@@ -120,6 +124,12 @@ struct Handle {
     }
 };
 
+} // namespace
+
+struct btck_BlockTreeEntry: Handle<btck_BlockTreeEntry, CBlockIndex> {};
+
+namespace {
+
 BCLog::Level get_bclog_level(btck_LogLevel level)
 {
     switch (level) {
@@ -176,6 +186,30 @@ BCLog::LogFlags get_bclog_flag(btck_LogCategory category)
     assert(false);
 }
 
+btck_SynchronizationState cast_state(SynchronizationState state)
+{
+    switch (state) {
+    case SynchronizationState::INIT_REINDEX:
+        return btck_SynchronizationState_INIT_REINDEX;
+    case SynchronizationState::INIT_DOWNLOAD:
+        return btck_SynchronizationState_INIT_DOWNLOAD;
+    case SynchronizationState::POST_INIT:
+        return btck_SynchronizationState_POST_INIT;
+    } // no default case, so the compiler can warn about missing cases
+    assert(false);
+}
+
+btck_Warning cast_btck_warning(kernel::Warning warning)
+{
+    switch (warning) {
+    case kernel::Warning::UNKNOWN_NEW_RULES_ACTIVATED:
+        return btck_Warning_UNKNOWN_NEW_RULES_ACTIVATED;
+    case kernel::Warning::LARGE_WORK_INVALID_CHAIN:
+        return btck_Warning_LARGE_WORK_INVALID_CHAIN;
+    } // no default case, so the compiler can warn about missing cases
+    assert(false);
+}
+
 struct LoggingConnection {
     std::unique_ptr<std::list<std::function<void(const std::string&)>>::iterator> m_connection;
     void* m_user_data;
@@ -224,9 +258,61 @@ struct LoggingConnection {
     }
 };
 
+class KernelNotifications final : public kernel::Notifications
+{
+private:
+    btck_NotificationInterfaceCallbacks m_cbs;
+
+public:
+    KernelNotifications(btck_NotificationInterfaceCallbacks cbs)
+        : m_cbs{cbs}
+    {
+    }
+
+    ~KernelNotifications()
+    {
+        if (m_cbs.user_data && m_cbs.user_data_destroy) {
+            m_cbs.user_data_destroy(m_cbs.user_data);
+        }
+        m_cbs.user_data_destroy = nullptr;
+        m_cbs.user_data = nullptr;
+    }
+
+    kernel::InterruptResult blockTip(SynchronizationState state, const CBlockIndex& index, double verification_progress) override
+    {
+        if (m_cbs.block_tip) m_cbs.block_tip(m_cbs.user_data, cast_state(state), btck_BlockTreeEntry::ref(&index), verification_progress);
+        return {};
+    }
+    void headerTip(SynchronizationState state, int64_t height, int64_t timestamp, bool presync) override
+    {
+        if (m_cbs.header_tip) m_cbs.header_tip(m_cbs.user_data, cast_state(state), height, timestamp, presync ? 1 : 0);
+    }
+    void progress(const bilingual_str& title, int progress_percent, bool resume_possible) override
+    {
+        if (m_cbs.progress) m_cbs.progress(m_cbs.user_data, title.original.c_str(), title.original.length(), progress_percent, resume_possible ? 1 : 0);
+    }
+    void warningSet(kernel::Warning id, const bilingual_str& message) override
+    {
+        if (m_cbs.warning_set) m_cbs.warning_set(m_cbs.user_data, cast_btck_warning(id), message.original.c_str(), message.original.length());
+    }
+    void warningUnset(kernel::Warning id) override
+    {
+        if (m_cbs.warning_unset) m_cbs.warning_unset(m_cbs.user_data, cast_btck_warning(id));
+    }
+    void flushError(const bilingual_str& message) override
+    {
+        if (m_cbs.flush_error) m_cbs.flush_error(m_cbs.user_data, message.original.c_str(), message.original.length());
+    }
+    void fatalError(const bilingual_str& message) override
+    {
+        if (m_cbs.fatal_error) m_cbs.fatal_error(m_cbs.user_data, message.original.c_str(), message.original.length());
+    }
+};
+
 struct ContextOptions {
     mutable Mutex m_mutex;
     std::unique_ptr<const CChainParams> m_chainparams GUARDED_BY(m_mutex);
+    std::shared_ptr<KernelNotifications> m_notifications GUARDED_BY(m_mutex);
 };
 
 class Context
@@ -234,7 +320,7 @@ class Context
 public:
     std::unique_ptr<kernel::Context> m_context;
 
-    std::unique_ptr<kernel::Notifications> m_notifications;
+    std::shared_ptr<KernelNotifications> m_notifications;
 
     std::unique_ptr<util::SignalInterrupt> m_interrupt;
 
@@ -242,7 +328,6 @@ public:
 
     Context(const ContextOptions* options, bool& sane)
         : m_context{std::make_unique<kernel::Context>()},
-          m_notifications{std::make_unique<kernel::Notifications>()},
           m_interrupt{std::make_unique<util::SignalInterrupt>()}
     {
         if (options) {
@@ -250,11 +335,18 @@ public:
             if (options->m_chainparams) {
                 m_chainparams = std::make_unique<const CChainParams>(*options->m_chainparams);
             }
+            if (options->m_notifications) {
+                m_notifications = options->m_notifications;
+            }
         }
 
         if (!m_chainparams) {
             m_chainparams = CChainParams::Main();
         }
+        if (!m_notifications) {
+            m_notifications = std::make_shared<KernelNotifications>(btck_NotificationInterfaceCallbacks{
+                nullptr, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr});
+        }
 
         if (!kernel::SanityChecks(*m_context)) {
             sane = false;
@@ -511,6 +603,13 @@ void btck_context_options_set_chainparams(btck_ContextOptions* options, const bt
     btck_ContextOptions::get(options).m_chainparams = std::make_unique<const CChainParams>(btck_ChainParameters::get(chain_parameters));
 }
 
+void btck_context_options_set_notifications(btck_ContextOptions* options, btck_NotificationInterfaceCallbacks notifications)
+{
+    // The KernelNotifications are copy-initialized, so the caller can free them again.
+    LOCK(btck_ContextOptions::get(options).m_mutex);
+    btck_ContextOptions::get(options).m_notifications = std::make_shared<KernelNotifications>(notifications);
+}
+
 void btck_context_options_destroy(btck_ContextOptions* options)
 {
     delete options;
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index f901dedd102..25f39a11d25 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -67,6 +67,11 @@ extern "C" {
  * functions, e.g. for scripts, may communicate more detailed error information
  * through status code out parameters.
  *
+ * The kernel notifications issue callbacks for errors. These are usually
+ * indicative of a system error. If such an error is issued, it is recommended
+ * to halt and tear down the existing kernel objects. Remediating the error may
+ * require system intervention by the user.
+ *
  * @section pointer Pointer and argument conventions
  *
  * The user is responsible for de-allocating the memory owned by pointers
@@ -148,6 +153,30 @@ typedef struct btck_ContextOptions btck_ContextOptions;
  */
 typedef struct btck_Context btck_Context;
 
+/**
+ * Opaque data structure for holding a block tree entry.
+ *
+ * This is a pointer to an element in the block index currently in memory of
+ * the chainstate manager. It is valid for the lifetime of the chainstate
+ * manager it was retrieved from. The entry is part of a tree-like structure
+ * that is maintained internally. Every entry, besides the genesis, points to a
+ * single parent. Multiple entries may share a parent, thus forming a tree.
+ * Each entry corresponds to a single block and may be used to retrieve its
+ * data and validation status.
+ */
+typedef struct btck_BlockTreeEntry btck_BlockTreeEntry;
+
+/** Current sync state passed to tip changed callbacks. */
+typedef uint8_t btck_SynchronizationState;
+#define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
+#define btck_SynchronizationState_INIT_DOWNLOAD ((btck_SynchronizationState)(1))
+#define btck_SynchronizationState_POST_INIT ((btck_SynchronizationState)(2))
+
+/** Possible warning types issued by validation. */
+typedef uint8_t btck_Warning;
+#define btck_Warning_UNKNOWN_NEW_RULES_ACTIVATED ((btck_Warning)(0))
+#define btck_Warning_LARGE_WORK_INVALID_CHAIN ((btck_Warning)(1))
+
 /** Callback function types */
 
 /**
@@ -161,6 +190,43 @@ typedef void (*btck_LogCallback)(void* user_data, const char* message, size_t me
  */
 typedef void (*btck_DestroyCallback)(void* user_data);
 
+/**
+ * Function signatures for the kernel notifications.
+ */
+typedef void (*btck_NotifyBlockTip)(void* user_data, btck_SynchronizationState state, const btck_BlockTreeEntry* entry, double verification_progress);
+typedef void (*btck_NotifyHeaderTip)(void* user_data, btck_SynchronizationState state, int64_t height, int64_t timestamp, int presync);
+typedef void (*btck_NotifyProgress)(void* user_data, const char* title, size_t title_len, int progress_percent, int resume_possible);
+typedef void (*btck_NotifyWarningSet)(void* user_data, btck_Warning warning, const char* message, size_t message_len);
+typedef void (*btck_NotifyWarningUnset)(void* user_data, btck_Warning warning);
+typedef void (*btck_NotifyFlushError)(void* user_data, const char* message, size_t message_len);
+typedef void (*btck_NotifyFatalError)(void* user_data, const char* message, size_t message_len);
+
+/**
+ * A struct for holding the kernel notification callbacks. The user data
+ * pointer may be used to point to user-defined structures to make processing
+ * the notifications easier.
+ *
+ * If user_data_destroy is provided, the kernel will automatically call this
+ * callback to clean up user_data when the notification interface object is destroyed.
+ * If user_data_destroy is NULL, it is the user's responsibility to ensure that
+ * the user_data outlives the kernel objects. Notifications can
+ * occur even as kernel objects are deleted, so care has to be taken to ensure
+ * safe unwinding.
+ */
+typedef struct {
+    void* user_data;                        //!< Holds a user-defined opaque structure that is passed to the notification callbacks.
+                                            //!< If user_data_destroy is also defined ownership of the user_data is passed to the
+                                            //!< created context options and subsequently context.
+    btck_DestroyCallback user_data_destroy; //!< Frees the provided user data structure.
+    btck_NotifyBlockTip block_tip;          //!< The chain's tip was updated to the provided block entry.
+    btck_NotifyHeaderTip header_tip;        //!< A new best block header was added.
+    btck_NotifyProgress progress;           //!< Reports on current block synchronization progress.
+    btck_NotifyWarningSet warning_set;      //!< A warning issued by the kernel library during validation.
+    btck_NotifyWarningUnset warning_unset;  //!< A previous condition leading to the issuance of a warning is no longer given.
+    btck_NotifyFlushError flush_error;      //!< An error encountered when flushing data to disk.
+    btck_NotifyFatalError fatal_error;      //!< A un-recoverable system error encountered by the library.
+} btck_NotificationInterfaceCallbacks;
+
 /**
  * A collection of logging categories that may be encountered by kernel code.
  */
@@ -572,6 +638,17 @@ BITCOINKERNEL_API void btck_context_options_set_chainparams(
     btck_ContextOptions* context_options,
     const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1, 2);
 
+/**
+ * @brief Set the kernel notifications for the context options. The context
+ * created with the options will be configured with these notifications.
+ *
+ * @param[in] context_options Non-null, previously created by @ref btck_context_options_create.
+ * @param[in] notifications   Is set to the context options.
+ */
+BITCOINKERNEL_API void btck_context_options_set_notifications(
+    btck_ContextOptions* context_options,
+    btck_NotificationInterfaceCallbacks notifications) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * Destroy the context options.
  */
@@ -591,7 +668,7 @@ BITCOINKERNEL_API void btck_context_options_destroy(btck_ContextOptions* context
  * kernel notification callbacks.
  *
  * @param[in] context_options Nullable, created by @ref btck_context_options_create.
- * @return                    The allocated kernel context, or null on error.
+ * @return                    The allocated context, or null on error.
  */
 BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_create(
     const btck_ContextOptions* context_options);
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index b550c3a5333..8e30b6ac517 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -46,6 +46,17 @@ enum class ChainType : btck_ChainType {
     REGTEST = btck_ChainType_REGTEST
 };
 
+enum class SynchronizationState : btck_SynchronizationState {
+    INIT_REINDEX = btck_SynchronizationState_INIT_REINDEX,
+    INIT_DOWNLOAD = btck_SynchronizationState_INIT_DOWNLOAD,
+    POST_INIT = btck_SynchronizationState_POST_INIT
+};
+
+enum class Warning : btck_Warning {
+    UNKNOWN_NEW_RULES_ACTIVATED = btck_Warning_UNKNOWN_NEW_RULES_ACTIVATED,
+    LARGE_WORK_INVALID_CHAIN = btck_Warning_LARGE_WORK_INVALID_CHAIN
+};
+
 enum class ScriptVerifyStatus : btck_ScriptVerifyStatus {
     OK = btck_ScriptVerifyStatus_OK,
     ERROR_INVALID_FLAGS_COMBINATION = btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION,
@@ -531,6 +542,35 @@ public:
     }
 };
 
+class BlockTreeEntry : View<btck_BlockTreeEntry>
+{
+public:
+    BlockTreeEntry(const btck_BlockTreeEntry* entry)
+        : View{entry}
+    {
+    }
+};
+
+class KernelNotifications
+{
+public:
+    virtual ~KernelNotifications() = default;
+
+    virtual void BlockTipHandler(SynchronizationState state, BlockTreeEntry entry, double verification_progress) {}
+
+    virtual void HeaderTipHandler(SynchronizationState state, int64_t height, int64_t timestamp, bool presync) {}
+
+    virtual void ProgressHandler(std::string_view title, int progress_percent, bool resume_possible) {}
+
+    virtual void WarningSetHandler(Warning warning, std::string_view message) {}
+
+    virtual void WarningUnsetHandler(Warning warning) {}
+
+    virtual void FlushErrorHandler(std::string_view error) {}
+
+    virtual void FatalErrorHandler(std::string_view error) {}
+};
+
 class ChainParams : public Handle<btck_ChainParameters, btck_chain_parameters_copy, btck_chain_parameters_destroy>
 {
 public:
@@ -547,6 +587,27 @@ public:
     {
         btck_context_options_set_chainparams(get(), chain_params.get());
     }
+
+    template <typename T>
+    void SetNotifications(std::shared_ptr<T> notifications)
+    {
+        static_assert(std::is_base_of_v<KernelNotifications, T>);
+        auto heap_notifications = std::make_unique<std::shared_ptr<T>>(std::move(notifications));
+        using user_type = std::shared_ptr<T>*;
+        btck_context_options_set_notifications(
+            get(),
+            btck_NotificationInterfaceCallbacks{
+                .user_data = heap_notifications.release(),
+                .user_data_destroy = +[](void* user_data) { delete static_cast<user_type>(user_data); },
+                .block_tip = +[](void* user_data, btck_SynchronizationState state, const btck_BlockTreeEntry* entry, double verification_progress) { (*static_cast<user_type>(user_data))->BlockTipHandler(static_cast<SynchronizationState>(state), BlockTreeEntry{entry}, verification_progress); },
+                .header_tip = +[](void* user_data, btck_SynchronizationState state, int64_t height, int64_t timestamp, int presync) { (*static_cast<user_type>(user_data))->HeaderTipHandler(static_cast<SynchronizationState>(state), height, timestamp, presync == 1); },
+                .progress = +[](void* user_data, const char* title, size_t title_len, int progress_percent, int resume_possible) { (*static_cast<user_type>(user_data))->ProgressHandler({title, title_len}, progress_percent, resume_possible == 1); },
+                .warning_set = +[](void* user_data, btck_Warning warning, const char* message, size_t message_len) { (*static_cast<user_type>(user_data))->WarningSetHandler(static_cast<Warning>(warning), {message, message_len}); },
+                .warning_unset = +[](void* user_data, btck_Warning warning) { (*static_cast<user_type>(user_data))->WarningUnsetHandler(static_cast<Warning>(warning)); },
+                .flush_error = +[](void* user_data, const char* error, size_t error_len) { (*static_cast<user_type>(user_data))->FlushErrorHandler({error, error_len}); },
+                .fatal_error = +[](void* user_data, const char* error, size_t error_len) { (*static_cast<user_type>(user_data))->FatalErrorHandler({error, error_len}); },
+            });
+    }
 };
 
 class Context : public Handle<btck_Context, btck_context_copy, btck_context_destroy>
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 8fc0308c0df..ef669cb6732 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -60,6 +60,35 @@ public:
     }
 };
 
+class TestKernelNotifications : public KernelNotifications
+{
+public:
+    void HeaderTipHandler(SynchronizationState state, int64_t height, int64_t timestamp, bool presync) override
+    {
+        BOOST_CHECK_GT(timestamp, 0);
+    }
+
+    void WarningSetHandler(Warning warning, std::string_view message) override
+    {
+        std::cout << "Kernel warning is set: " << message << std::endl;
+    }
+
+    void WarningUnsetHandler(Warning warning) override
+    {
+        std::cout << "Kernel warning was unset." << std::endl;
+    }
+
+    void FlushErrorHandler(std::string_view error) override
+    {
+        std::cout << error << std::endl;
+    }
+
+    void FatalErrorHandler(std::string_view error) override
+    {
+        std::cout << error << std::endl;
+    }
+};
+
 void run_verify_test(
     const ScriptPubkey& spent_script_pubkey,
     const Transaction& spending_tx,
@@ -401,6 +430,7 @@ BOOST_AUTO_TEST_CASE(btck_context_tests)
         ChainParams regtest_params{ChainType::REGTEST};
         CheckHandle(params, regtest_params);
         options.SetChainParams(params);
+        options.SetNotifications(std::make_shared<TestKernelNotifications>());
         Context context{options};
     }
 }

From 65571c36a265ec340343b555d1537c58ab335538 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Tue, 28 May 2024 20:58:48 +0200
Subject: [PATCH 06/23] kernel: Add chainstate manager object to C header

This is the main driver class for anything validation related, so expose
it here.

Creating the chainstate manager options will currently also trigger the
creation of their respectively configured directories.

The chainstate manager and block manager options are consolidated into a
single object. The kernel might eventually introduce a separate block
manager object for the purposes of being a light-weight block store
reader.

The chainstate manager will associate with the context with which it was
created for the duration of its lifetime and it keeps it in memory with
a shared pointer.

The tests now also create dedicated temporary directories. This is
similar to the behaviour in the existing unit test framework.

Co-authored-by: stickies-v <stickies-v@protonmail.com>
---
 src/kernel/bitcoinkernel.cpp       | 87 ++++++++++++++++++++++++++++++
 src/kernel/bitcoinkernel.h         | 72 +++++++++++++++++++++++++
 src/kernel/bitcoinkernel_wrapper.h | 19 +++++++
 src/test/kernel/test_kernel.cpp    | 70 ++++++++++++++++++++++++
 test/lint/test_runner/src/main.rs  |  1 +
 5 files changed, 249 insertions(+)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 2670287ab4a..445ccca94df 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -7,6 +7,7 @@
 #include <kernel/bitcoinkernel.h>
 
 #include <consensus/amount.h>
+#include <kernel/caches.h>
 #include <kernel/chainparams.h>
 #include <kernel/checks.h>
 #include <kernel/context.h>
@@ -14,6 +15,7 @@
 #include <kernel/notifications_interface.h>
 #include <kernel/warning.h>
 #include <logging.h>
+#include <node/blockstorage.h>
 #include <primitives/transaction.h>
 #include <script/interpreter.h>
 #include <script/script.h>
@@ -21,6 +23,7 @@
 #include <streams.h>
 #include <sync.h>
 #include <tinyformat.h>
+#include <util/fs.h>
 #include <util/result.h>
 #include <util/signalinterrupt.h>
 #include <util/translation.h>
@@ -354,6 +357,39 @@ public:
     }
 };
 
+//! Helper struct to wrap the ChainstateManager-related Options
+struct ChainstateManagerOptions {
+    mutable Mutex m_mutex;
+    ChainstateManager::Options m_chainman_options GUARDED_BY(m_mutex);
+    node::BlockManager::Options m_blockman_options GUARDED_BY(m_mutex);
+    std::shared_ptr<const Context> m_context;
+
+    ChainstateManagerOptions(const std::shared_ptr<const Context>& context, const fs::path& data_dir, const fs::path& blocks_dir)
+        : m_chainman_options{ChainstateManager::Options{
+              .chainparams = *context->m_chainparams,
+              .datadir = data_dir,
+              .notifications = *context->m_notifications}},
+          m_blockman_options{node::BlockManager::Options{
+              .chainparams = *context->m_chainparams,
+              .blocks_dir = blocks_dir,
+              .notifications = *context->m_notifications,
+              .block_tree_db_params = DBParams{
+                  .path = data_dir / "blocks" / "index",
+                  .cache_bytes = kernel::CacheSizes{DEFAULT_KERNEL_CACHE}.block_tree_db,
+              }}},
+          m_context{context}
+    {
+    }
+};
+
+struct ChainMan {
+    std::unique_ptr<ChainstateManager> m_chainman;
+    std::shared_ptr<const Context> m_context;
+
+    ChainMan(std::unique_ptr<ChainstateManager> chainman, std::shared_ptr<const Context> context)
+        : m_chainman(std::move(chainman)), m_context(std::move(context)) {}
+};
+
 } // namespace
 
 struct btck_Transaction : Handle<btck_Transaction, std::shared_ptr<const CTransaction>> {};
@@ -363,6 +399,8 @@ struct btck_LoggingConnection : Handle<btck_LoggingConnection, LoggingConnection
 struct btck_ContextOptions : Handle<btck_ContextOptions, ContextOptions> {};
 struct btck_Context : Handle<btck_Context, std::shared_ptr<const Context>> {};
 struct btck_ChainParameters : Handle<btck_ChainParameters, CChainParams> {};
+struct btck_ChainstateManagerOptions : Handle<btck_ChainstateManagerOptions, ChainstateManagerOptions> {};
+struct btck_ChainstateManager : Handle<btck_ChainstateManager, ChainMan> {};
 
 btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
 {
@@ -636,3 +674,52 @@ void btck_context_destroy(btck_Context* context)
 {
     delete context;
 }
+
+btck_ChainstateManagerOptions* btck_chainstate_manager_options_create(const btck_Context* context, const char* data_dir, size_t data_dir_len, const char* blocks_dir, size_t blocks_dir_len)
+{
+    try {
+        fs::path abs_data_dir{fs::absolute(fs::PathFromString({data_dir, data_dir_len}))};
+        fs::create_directories(abs_data_dir);
+        fs::path abs_blocks_dir{fs::absolute(fs::PathFromString({blocks_dir, blocks_dir_len}))};
+        fs::create_directories(abs_blocks_dir);
+        return btck_ChainstateManagerOptions::create(btck_Context::get(context), abs_data_dir, abs_blocks_dir);
+    } catch (const std::exception& e) {
+        LogError("Failed to create chainstate manager options: %s", e.what());
+        return nullptr;
+    }
+}
+
+void btck_chainstate_manager_options_destroy(btck_ChainstateManagerOptions* options)
+{
+    delete options;
+}
+
+btck_ChainstateManager* btck_chainstate_manager_create(
+    const btck_ChainstateManagerOptions* chainman_opts)
+{
+    try {
+        auto& opts{btck_ChainstateManagerOptions::get(chainman_opts)};
+        LOCK(opts.m_mutex);
+        auto& context{opts.m_context};
+        auto chainman{std::make_unique<ChainstateManager>(*context->m_interrupt, opts.m_chainman_options, opts.m_blockman_options)};
+        return btck_ChainstateManager::create(std::move(chainman), context);
+    } catch (const std::exception& e) {
+        LogError("Failed to create chainstate manager: %s", e.what());
+        return nullptr;
+    }
+}
+
+void btck_chainstate_manager_destroy(btck_ChainstateManager* chainman)
+{
+    {
+        LOCK(btck_ChainstateManager::get(chainman).m_chainman->GetMutex());
+        for (Chainstate* chainstate : btck_ChainstateManager::get(chainman).m_chainman->GetAll()) {
+            if (chainstate->CanFlushToDisk()) {
+                chainstate->ForceFlushStateToDisk();
+                chainstate->ResetCoinsViews();
+            }
+        }
+    }
+
+    delete chainman;
+}
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 25f39a11d25..59094aefd61 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -166,6 +166,26 @@ typedef struct btck_Context btck_Context;
  */
 typedef struct btck_BlockTreeEntry btck_BlockTreeEntry;
 
+/**
+ * Opaque data structure for holding options for creating a new chainstate
+ * manager.
+ *
+ * The chainstate manager options are used to set some parameters for the
+ * chainstate manager.
+ */
+typedef struct btck_ChainstateManagerOptions btck_ChainstateManagerOptions;
+
+/**
+ * Opaque data structure for holding a chainstate manager.
+ *
+ * The chainstate manager is the central object for doing validation tasks as
+ * well as retrieving data from the chain. Internally it is a complex data
+ * structure with diverse functionality.
+ *
+ * Its functionality will be more and more exposed in the future.
+ */
+typedef struct btck_ChainstateManager btck_ChainstateManager;
+
 /** Current sync state passed to tip changed callbacks. */
 typedef uint8_t btck_SynchronizationState;
 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
@@ -686,6 +706,58 @@ BITCOINKERNEL_API void btck_context_destroy(btck_Context* context);
 
 ///@}
 
+/** @name ChainstateManagerOptions
+ * Functions for working with chainstate manager options.
+ */
+///@{
+
+/**
+ * @brief Create options for the chainstate manager.
+ *
+ * @param[in] context          Non-null, the created options and through it the chainstate manager will
+                               associate with this kernel context for the duration of their lifetimes.
+ * @param[in] data_directory   Non-null, path string of the directory containing the chainstate data.
+ *                             If the directory does not exist yet, it will be created.
+ * @param[in] blocks_directory Non-null, path string of the directory containing the block data. If
+ *                             the directory does not exist yet, it will be created.
+ * @return                     The allocated chainstate manager options, or null on error.
+ */
+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, 2);
+
+/**
+ * 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. *
+ *
+ * @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);
+
+/**
+ * Destroy the chainstate manager.
+ */
+BITCOINKERNEL_API void btck_chainstate_manager_destroy(btck_ChainstateManager* chainstate_manager);
+
+///@}
+
 #ifdef __cplusplus
 } // extern "C"
 #endif // __cplusplus
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index 8e30b6ac517..7d5c3063c9c 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -11,6 +11,7 @@
 #include <memory>
 #include <span>
 #include <stdexcept>
+#include <string>
 #include <string_view>
 #include <type_traits>
 #include <utility>
@@ -620,6 +621,24 @@ public:
         : Handle{btck_context_create(ContextOptions{}.get())} {}
 };
 
+class ChainstateManagerOptions : public UniqueHandle<btck_ChainstateManagerOptions, btck_chainstate_manager_options_destroy>
+{
+public:
+    ChainstateManagerOptions(const Context& context, const std::string& data_dir, const std::string& blocks_dir)
+        : UniqueHandle{btck_chainstate_manager_options_create(context.get(), data_dir.c_str(), data_dir.length(), blocks_dir.c_str(), blocks_dir.length())}
+    {
+    }
+};
+
+class ChainMan : UniqueHandle<btck_ChainstateManager, btck_chainstate_manager_destroy>
+{
+public:
+    ChainMan(const Context& context, const ChainstateManagerOptions& chainman_opts)
+        : UniqueHandle{btck_chainstate_manager_create(chainman_opts.get())}
+    {
+    }
+};
+
 } // namespace btck
 
 #endif // BITCOIN_KERNEL_BITCOINKERNEL_WRAPPER_H
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index ef669cb6732..bc00e85c2da 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -11,15 +11,36 @@
 #include <charconv>
 #include <cstdint>
 #include <cstdlib>
+#include <filesystem>
 #include <iostream>
 #include <memory>
+#include <random>
 #include <ranges>
 #include <span>
+#include <string>
 #include <string_view>
 #include <vector>
 
 using namespace btck;
 
+std::string random_string(uint32_t length)
+{
+    const std::string chars = "0123456789"
+                              "abcdefghijklmnopqrstuvwxyz"
+                              "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+    static std::random_device rd;
+    static std::default_random_engine dre{rd()};
+    static std::uniform_int_distribution<> distribution(0, chars.size() - 1);
+
+    std::string random;
+    random.reserve(length);
+    for (uint32_t i = 0; i < length; i++) {
+        random += chars[distribution(dre)];
+    }
+    return random;
+}
+
 std::vector<std::byte> hex_string_to_byte_vec(std::string_view hex)
 {
     std::vector<std::byte> bytes;
@@ -60,6 +81,20 @@ public:
     }
 };
 
+struct TestDirectory {
+    std::filesystem::path m_directory;
+    TestDirectory(std::string directory_name)
+        : m_directory{std::filesystem::temp_directory_path() / (directory_name + random_string(16))}
+    {
+        std::filesystem::create_directories(m_directory);
+    }
+
+    ~TestDirectory()
+    {
+        std::filesystem::remove_all(m_directory);
+    }
+};
+
 class TestKernelNotifications : public KernelNotifications
 {
 public:
@@ -434,3 +469,38 @@ BOOST_AUTO_TEST_CASE(btck_context_tests)
         Context context{options};
     }
 }
+
+Context create_context(std::shared_ptr<TestKernelNotifications> notifications, ChainType chain_type)
+{
+    ContextOptions options{};
+    ChainParams params{chain_type};
+    options.SetChainParams(params);
+    options.SetNotifications(notifications);
+    auto context{Context{options}};
+    return context;
+}
+
+BOOST_AUTO_TEST_CASE(btck_chainman_tests)
+{
+    Logger logger{std::make_unique<TestLog>()};
+    auto test_directory{TestDirectory{"chainman_test_bitcoin_kernel"}};
+
+    { // test with default context
+        Context context{};
+        ChainstateManagerOptions chainman_opts{context, test_directory.m_directory.string(), (test_directory.m_directory / "blocks").string()};
+        ChainMan chainman{context, chainman_opts};
+    }
+
+    { // test with default context options
+        ContextOptions options{};
+        Context context{options};
+        ChainstateManagerOptions chainman_opts{context, test_directory.m_directory.string(), (test_directory.m_directory / "blocks").string()};
+        ChainMan chainman{context, chainman_opts};
+    }
+
+    auto notifications{std::make_shared<TestKernelNotifications>()};
+    auto context{create_context(notifications, ChainType::MAINNET)};
+
+    ChainstateManagerOptions chainman_opts{context, test_directory.m_directory.string(), (test_directory.m_directory / "blocks").string()};
+    ChainMan chainman{context, chainman_opts};
+}
diff --git a/test/lint/test_runner/src/main.rs b/test/lint/test_runner/src/main.rs
index ba5aaee793f..53d24ca4960 100644
--- a/test/lint/test_runner/src/main.rs
+++ b/test/lint/test_runner/src/main.rs
@@ -373,6 +373,7 @@ fn lint_std_filesystem() -> LintResult {
             "./src/",
             ":(exclude)src/ipc/libmultiprocess/",
             ":(exclude)src/util/fs.h",
+            ":(exclude)src/test/kernel/test_kernel.cpp",
         ])
         .status()
         .expect("command error")

From e2c1bd3d713ffe0b8eede711e84f64e0fe4ae836 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Sun, 17 Nov 2024 17:36:48 +0100
Subject: [PATCH 07/23] kernel: Add chainstate manager option for setting
 worker threads

Re-use the same pattern used for the context options. This allows users
to set the number of threads used in the validation thread pool.
---
 src/kernel/bitcoinkernel.cpp       |  6 ++++++
 src/kernel/bitcoinkernel.h         | 12 ++++++++++++
 src/kernel/bitcoinkernel_wrapper.h |  5 +++++
 src/test/kernel/test_kernel.cpp    |  1 +
 4 files changed, 24 insertions(+)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 445ccca94df..be0f9808b89 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -689,6 +689,12 @@ btck_ChainstateManagerOptions* btck_chainstate_manager_options_create(const btck
     }
 }
 
+void btck_chainstate_manager_options_set_worker_threads_num(btck_ChainstateManagerOptions* opts, int worker_threads)
+{
+    LOCK(btck_ChainstateManagerOptions::get(opts).m_mutex);
+    btck_ChainstateManagerOptions::get(opts).m_chainman_options.worker_threads_num = worker_threads;
+}
+
 void btck_chainstate_manager_options_destroy(btck_ChainstateManagerOptions* options)
 {
     delete options;
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 59094aefd61..63cad6ad4a5 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -729,6 +729,18 @@ BITCOINKERNEL_API btck_ChainstateManagerOptions* BITCOINKERNEL_WARN_UNUSED_RESUL
     const char* blocks_directory,
     size_t blocks_directory_len) BITCOINKERNEL_ARG_NONNULL(1, 2);
 
+/**
+ * @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);
+
 /**
  * Destroy the chainstate manager options.
  */
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index 7d5c3063c9c..bdd71916a16 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -628,6 +628,11 @@ public:
         : UniqueHandle{btck_chainstate_manager_options_create(context.get(), data_dir.c_str(), data_dir.length(), blocks_dir.c_str(), blocks_dir.length())}
     {
     }
+
+    void SetWorkerThreads(int worker_threads)
+    {
+        btck_chainstate_manager_options_set_worker_threads_num(get(), worker_threads);
+    }
 };
 
 class ChainMan : UniqueHandle<btck_ChainstateManager, btck_chainstate_manager_destroy>
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index bc00e85c2da..4b2dc5dc201 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -502,5 +502,6 @@ BOOST_AUTO_TEST_CASE(btck_chainman_tests)
     auto context{create_context(notifications, ChainType::MAINNET)};
 
     ChainstateManagerOptions chainman_opts{context, test_directory.m_directory.string(), (test_directory.m_directory / "blocks").string()};
+    chainman_opts.SetWorkerThreads(4);
     ChainMan chainman{context, chainman_opts};
 }

From cb1590b05efd090bc2e4be49b5a649f8d248afa0 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Wed, 29 May 2024 13:28:05 +0200
Subject: [PATCH 08/23] kernel: Add chainstate loading when instantiating a
 ChainstateManager

The library will now internally load the chainstate when a new
ChainstateManager is instantiated.

Options for controlling details of loading the chainstate will be added
over the next few commits.
---
 src/kernel/bitcoinkernel.cpp | 42 +++++++++++++++++++++++++++++++-----
 src/kernel/bitcoinkernel.h   |  3 ++-
 2 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index be0f9808b89..8eec1bc721a 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -7,6 +7,7 @@
 #include <kernel/bitcoinkernel.h>
 
 #include <consensus/amount.h>
+#include <consensus/validation.h>
 #include <kernel/caches.h>
 #include <kernel/chainparams.h>
 #include <kernel/checks.h>
@@ -16,6 +17,7 @@
 #include <kernel/warning.h>
 #include <logging.h>
 #include <node/blockstorage.h>
+#include <node/chainstate.h>
 #include <primitives/transaction.h>
 #include <script/interpreter.h>
 #include <script/script.h>
@@ -38,6 +40,7 @@
 #include <memory>
 #include <span>
 #include <string>
+#include <tuple>
 #include <utility>
 #include <vector>
 
@@ -363,6 +366,7 @@ struct ChainstateManagerOptions {
     ChainstateManager::Options m_chainman_options GUARDED_BY(m_mutex);
     node::BlockManager::Options m_blockman_options GUARDED_BY(m_mutex);
     std::shared_ptr<const Context> m_context;
+    node::ChainstateLoadOptions m_chainstate_load_options GUARDED_BY(m_mutex);
 
     ChainstateManagerOptions(const std::shared_ptr<const Context>& context, const fs::path& data_dir, const fs::path& blocks_dir)
         : m_chainman_options{ChainstateManager::Options{
@@ -377,7 +381,7 @@ struct ChainstateManagerOptions {
                   .path = data_dir / "blocks" / "index",
                   .cache_bytes = kernel::CacheSizes{DEFAULT_KERNEL_CACHE}.block_tree_db,
               }}},
-          m_context{context}
+          m_context{context}, m_chainstate_load_options{node::ChainstateLoadOptions{}}
     {
     }
 };
@@ -703,16 +707,44 @@ void btck_chainstate_manager_options_destroy(btck_ChainstateManagerOptions* opti
 btck_ChainstateManager* btck_chainstate_manager_create(
     const btck_ChainstateManagerOptions* chainman_opts)
 {
+    auto& opts{btck_ChainstateManagerOptions::get(chainman_opts)};
+    std::unique_ptr<ChainstateManager> chainman;
     try {
-        auto& opts{btck_ChainstateManagerOptions::get(chainman_opts)};
         LOCK(opts.m_mutex);
-        auto& context{opts.m_context};
-        auto chainman{std::make_unique<ChainstateManager>(*context->m_interrupt, opts.m_chainman_options, opts.m_blockman_options)};
-        return btck_ChainstateManager::create(std::move(chainman), context);
+        chainman = std::make_unique<ChainstateManager>(*opts.m_context->m_interrupt, opts.m_chainman_options, opts.m_blockman_options);
     } catch (const std::exception& e) {
         LogError("Failed to create chainstate manager: %s", e.what());
         return nullptr;
     }
+
+    try {
+        const auto chainstate_load_opts{WITH_LOCK(opts.m_mutex, return opts.m_chainstate_load_options)};
+
+        kernel::CacheSizes cache_sizes{DEFAULT_KERNEL_CACHE};
+        auto [status, chainstate_err]{node::LoadChainstate(*chainman, cache_sizes, chainstate_load_opts)};
+        if (status != node::ChainstateLoadStatus::SUCCESS) {
+            LogError("Failed to load chain state from your data directory: %s", chainstate_err.original);
+            return nullptr;
+        }
+        std::tie(status, chainstate_err) = node::VerifyLoadedChainstate(*chainman, chainstate_load_opts);
+        if (status != node::ChainstateLoadStatus::SUCCESS) {
+            LogError("Failed to verify loaded chain state from your datadir: %s", chainstate_err.original);
+            return nullptr;
+        }
+
+        for (Chainstate* chainstate : WITH_LOCK(chainman->GetMutex(), return chainman->GetAll())) {
+            BlockValidationState state;
+            if (!chainstate->ActivateBestChain(state, nullptr)) {
+                LogError("Failed to connect best block: %s", state.ToString());
+                return nullptr;
+            }
+        }
+    } catch (const std::exception& e) {
+        LogError("Failed to load chainstate: %s", e.what());
+        return nullptr;
+    }
+
+    return btck_ChainstateManager::create(std::move(chainman), opts.m_context);
 }
 
 void btck_chainstate_manager_destroy(btck_ChainstateManager* chainman)
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 63cad6ad4a5..d49e0e5bca3 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -755,7 +755,8 @@ BITCOINKERNEL_API void btck_chainstate_manager_options_destroy(btck_ChainstateMa
 
 /**
  * @brief Create a chainstate manager. This is the main object for many
- * validation tasks as well as for retrieving data from the chain. *
+ * 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.

From ad80abc73df38f94d887a905773c4500ca0c2961 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Mon, 17 Jun 2024 22:50:23 +0200
Subject: [PATCH 09/23] kernel: Add block validation to C header

The added function allows the user process and validate a given block
with the chainstate manager. The *_process_block(...) function does some
preliminary checks on the block before passing it to
`ProcessNewBlock(...)`. These are similar to the checks in the
`submitblock()` rpc.

Richer processing of the block validation result will be made available
in the following commits through the validation interface.

The commits also adds a utility for deserializing a `CBlock`
(`kernel_block_create()`) that may then be passed to the library for
processing.

The tests exercise the function for both mainnet and regtest. The
commit also adds the data of 206 regtest blocks (some blocks also
contain transactions).
---
 src/kernel/bitcoinkernel.cpp       |  56 +++++++-
 src/kernel/bitcoinkernel.h         |  77 +++++++++++
 src/kernel/bitcoinkernel_wrapper.h |  40 ++++++
 src/test/kernel/block_data.h       | 213 +++++++++++++++++++++++++++++
 src/test/kernel/test_kernel.cpp    |  93 +++++++++++++
 5 files changed, 477 insertions(+), 2 deletions(-)
 create mode 100644 src/test/kernel/block_data.h

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 8eec1bc721a..7a08b6c9008 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -6,6 +6,7 @@
 
 #include <kernel/bitcoinkernel.h>
 
+#include <chain.h>
 #include <consensus/amount.h>
 #include <consensus/validation.h>
 #include <kernel/caches.h>
@@ -18,6 +19,7 @@
 #include <logging.h>
 #include <node/blockstorage.h>
 #include <node/chainstate.h>
+#include <primitives/block.h>
 #include <primitives/transaction.h>
 #include <script/interpreter.h>
 #include <script/script.h>
@@ -25,6 +27,7 @@
 #include <streams.h>
 #include <sync.h>
 #include <tinyformat.h>
+#include <uint256.h>
 #include <util/fs.h>
 #include <util/result.h>
 #include <util/signalinterrupt.h>
@@ -44,8 +47,6 @@
 #include <utility>
 #include <vector>
 
-class CBlockIndex;
-
 // Define G_TRANSLATION_FUN symbol in libbitcoinkernel library so users of the
 // library aren't required to export this symbol
 extern const std::function<std::string(const char*)> G_TRANSLATION_FUN{nullptr};
@@ -133,6 +134,7 @@ struct Handle {
 } // namespace
 
 struct btck_BlockTreeEntry: Handle<btck_BlockTreeEntry, CBlockIndex> {};
+struct btck_Block : Handle<btck_Block, std::shared_ptr<const CBlock>> {};
 
 namespace {
 
@@ -761,3 +763,53 @@ void btck_chainstate_manager_destroy(btck_ChainstateManager* chainman)
 
     delete chainman;
 }
+
+btck_Block* btck_block_create(const void* raw_block, size_t raw_block_length)
+{
+    auto block{std::make_shared<CBlock>()};
+
+    DataStream stream{std::span{reinterpret_cast<const std::byte*>(raw_block), raw_block_length}};
+
+    try {
+        stream >> TX_WITH_WITNESS(*block);
+    } catch (...) {
+        LogDebug(BCLog::KERNEL, "Block decode failed.");
+        return nullptr;
+    }
+
+    return btck_Block::create(block);
+}
+
+btck_Block* btck_block_copy(const btck_Block* block)
+{
+    return btck_Block::copy(block);
+}
+
+size_t btck_block_count_transactions(const btck_Block* block)
+{
+    return btck_Block::get(block)->vtx.size();
+}
+
+const btck_Transaction* btck_block_get_transaction_at(const btck_Block* block, size_t index)
+{
+    assert(index < btck_Block::get(block)->vtx.size());
+    return btck_Transaction::ref(&btck_Block::get(block)->vtx[index]);
+}
+
+void btck_block_destroy(btck_Block* block)
+{
+    delete block;
+}
+
+int btck_chainstate_manager_process_block(
+    btck_ChainstateManager* chainman,
+    const btck_Block* block,
+    int* _new_block)
+{
+    bool new_block;
+    auto result = btck_ChainstateManager::get(chainman).m_chainman->ProcessNewBlock(btck_Block::get(block), /*force_processing=*/true, /*min_pow_checked=*/true, /*new_block=*/&new_block);
+    if (_new_block) {
+        *_new_block = new_block ? 1 : 0;
+    }
+    return result ? 0 : -1;
+}
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index d49e0e5bca3..5486c823be3 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -186,6 +186,11 @@ typedef struct btck_ChainstateManagerOptions btck_ChainstateManagerOptions;
  */
 typedef struct btck_ChainstateManager btck_ChainstateManager;
 
+/**
+ * Opaque data structure for holding a block.
+ */
+typedef struct btck_Block btck_Block;
+
 /** Current sync state passed to tip changed callbacks. */
 typedef uint8_t btck_SynchronizationState;
 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
@@ -764,6 +769,26 @@ BITCOINKERNEL_API void btck_chainstate_manager_options_destroy(btck_ChainstateMa
 BITCOINKERNEL_API btck_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_create(
     const btck_ChainstateManagerOptions* chainstate_manager_options) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Process and validate the passed in block with the chainstate
+ * manager. Processing first does checks on the block, and if these passed,
+ * saves it to disk. It then validates the block against the utxo set. If it is
+ * valid, the chain is extended with it. The return value is not indicative of
+ * the block's validity.
+ *
+ * @param[in] chainstate_manager Non-null.
+ * @param[in] block              Non-null, block to be validated.
+ *
+ * @param[out] new_block         Nullable, will be set to 1 if this block was not processed before. Note that this means it
+ *                               might also not be 1 if processing was attempted before, but the block was found invalid
+ *                               before its data was persisted.
+ * @return                       0 if processing the block was successful. Will also return 0 for valid, but duplicate blocks.
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_process_block(
+    btck_ChainstateManager* chainstate_manager,
+    const btck_Block* block,
+    int* new_block) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
+
 /**
  * Destroy the chainstate manager.
  */
@@ -771,6 +796,58 @@ BITCOINKERNEL_API void btck_chainstate_manager_destroy(btck_ChainstateManager* c
 
 ///@}
 
+/** @name Block
+ * Functions for working with blocks.
+ */
+///@{
+
+/**
+ * @brief Parse a serialized raw block into a new block object.
+ *
+ * @param[in] raw_block     Non-null, serialized block.
+ * @param[in] raw_block_len Length of the serialized block.
+ * @return                  The allocated block, or null on error.
+ */
+BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_create(
+    const void* raw_block, size_t raw_block_len) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Copy a block. Blocks are reference counted, so this just increments
+ * the reference count.
+ *
+ * @param[in] block Non-null.
+ * @return          The copied block.
+ */
+BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_copy(
+    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Count the number of transactions contained in a block.
+ *
+ * @param[in] block Non-null.
+ * @return          The number of transactions in the block.
+ */
+BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_count_transactions(
+    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the transaction at the provided index. The returned transaction
+ * is not owned and depends on the lifetime of the block.
+ *
+ * @param[in] block             Non-null.
+ * @param[in] transaction_index The index of the transaction to be retrieved.
+ * @return                      The transaction.
+ */
+BITCOINKERNEL_API const btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_transaction_at(
+    const btck_Block* block, size_t transaction_index) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the block.
+ */
+BITCOINKERNEL_API void btck_block_destroy(btck_Block* block);
+
+///@}
+
 #ifdef __cplusplus
 } // extern "C"
 #endif // __cplusplus
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index bdd71916a16..f0af457d42a 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -464,11 +464,20 @@ public:
     }
 };
 
+class TransactionView : public View<btck_Transaction>, public TransactionApi<TransactionView>
+{
+public:
+    explicit TransactionView(const btck_Transaction* ptr) : View{ptr} {}
+};
+
 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())} {}
+
+    Transaction(const TransactionView& view)
+        : Handle{view} {}
 };
 
 template <typename Derived>
@@ -500,6 +509,29 @@ bool ScriptPubkeyApi<Derived>::Verify(int64_t amount,
     return result == 1;
 }
 
+class Block : public Handle<btck_Block, btck_block_copy, btck_block_destroy>
+{
+public:
+    Block(const std::span<const std::byte> raw_block)
+        : Handle{btck_block_create(raw_block.data(), raw_block.size())}
+    {
+    }
+
+    Block(btck_Block* block) : Handle{block} {}
+
+    size_t CountTransactions() const
+    {
+        return btck_block_count_transactions(get());
+    }
+
+    TransactionView GetTransaction(size_t index) const
+    {
+        return TransactionView{btck_block_get_transaction_at(get(), index)};
+    }
+
+    MAKE_RANGE_METHOD(Transactions, Block, &Block::CountTransactions, &Block::GetTransaction, *this)
+};
+
 inline void logging_disable()
 {
     btck_logging_disable();
@@ -642,6 +674,14 @@ public:
         : UniqueHandle{btck_chainstate_manager_create(chainman_opts.get())}
     {
     }
+
+    bool ProcessBlock(const Block& block, bool* new_block)
+    {
+        int _new_block;
+        int res = btck_chainstate_manager_process_block(get(), block.get(), &_new_block);
+        if (new_block) *new_block = _new_block == 1;
+        return res == 0;
+    }
 };
 
 } // namespace btck
diff --git a/src/test/kernel/block_data.h b/src/test/kernel/block_data.h
new file mode 100644
index 00000000000..45a982c5f17
--- /dev/null
+++ b/src/test/kernel/block_data.h
@@ -0,0 +1,213 @@
+#ifndef BITCOIN_TEST_KERNEL_BLOCK_DATA_H
+#define BITCOIN_TEST_KERNEL_BLOCK_DATA_H
+#include <array>
+#include <string_view>
+inline constexpr std::array<std::string_view, 206> REGTEST_BLOCK_DATA {
+"0000002006226e46111a0b59caaf126043eb5bbf28c34f3a5e332a1fc7b2b73cf188910f295badc0bdd9a2bc0955d12f337491eae4c87ba4660078c0156310284d47c6ff9a242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025100ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020a629da61ccd6c9de14dd22d4dcf06ac4b98828801fb58275af1ed2c89e361b79677daedb5fc7781c5907a88133cd461b4865e9a4881fecfb362304ad1806acf3a7242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025200ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020621716dbbd2d4109ecf95e3ad14f2e205cc2dc52e286e127009b8941d255495a16bb39e1ed66dcf600fd7eabd1b8ee77ec894a77c2eac0dcc3ef2a4400707f56a7242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025300ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000204b272fa0400818325978161031fed250a9d9713471c9b99be3d10e2350bfd632ccf33dfd714ce243a48150fcf6281ac3563de5418112606ee2cc09632f1ea406a8242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025400ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000200e99bd4968d4c5e58887c3a6f1b5e3830eed6aed635a1d7275b0361d9d69c24394c11b2414977058cb5ff828a13c1e28b342bb947c47f8b1fc1c8886c6355e03a8242d66ffff7f200400000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025500ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000206fe9a1ea5c1b6cb5f0a2139cb187ed8c3477378f92838999f107f912de0bf92b4d7385d0a84e58f7f8d8d58e6aecff0928b0c8fc13009ab0faae02650f9726eca8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025600ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000207dd73a995a00c5babb1d3084216e607775a03b985ae25926daad86307b04235713e113fa98f8656fa83b8f91124a8f988ab826138358cbc3a9be9216be0194d8a8242d66ffff7f200600000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025700ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000204f6b4fdd4e99aa10a724cbeddefe323f0042f4a3f6e3bd057fd4bd7a5b3ded6f710365157ed17e65cdfd6e4a0ee0c73cfb582cb14dbb879db7465682fedb6868a9242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025800ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000205b86722a8356305226f236b66d49447b771236d91a768cf9bc0773addfcd1a3e203d91dd647210a031046cfccd099edba94b5cb0203ab1e7c208158c1c04d7eea9242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025900ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020bc72fce0ab3196fd3b49be9cf4669700f9aa66cf257f046dcef175bb78a079219f52575cd5c0c93b5b37cf9377230c0f4dd62069fcc6ddab1a0cf35ec1c440eea9242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025a00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020f9e09a49780b8e3ae1b5e0da63887e81528cede0a052fc0ce7e7fe44ad09ee4b676a90f97480ef4e447335f1b9376c944381fb06d69b778a47248e5760dedf62a9242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025b00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000208bfac22a1b801218b55cbd1a36c86ba707d495b52d968fe24a89ef430c6f9c05419a2754a90f35ebf699288adfc71568252fedf46a2b731c2cc787d55e44e3dea9242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025c00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020da91c8b0a3772de6a794c9bd40cf7c1f8b21fac91f99490e7d995d7d0bd52a4f69ad11d9c347c0bf88430b128b39f27b954ffcd48bc38501eba0a99dffb7969ba9242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025d00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000203956d8b72a0b1c7c1d4368095f6c1db60573c50827830b648ad2d6741d41947c48e9d057ff732602042bb46933568292bd57e76761273b7af178baf926cebe60aa242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025e00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000209c4249925fa49bddcd6f0917f8c6444d899d2d958c65e33da450e25687d46c4a8efcab0bcce7a6b22485598a2eb928092262c95f2ea233beab343044013269ddaa242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff025f00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002057d9cf496a6ad859d1ea07872d5252a23bbb538bc7d1b08c8d9f0974a85e5e02b3db6b3f80920bbe3b22af1be2e9aaadcf80a154efaaffdbe490dfacb4d3a451aa242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff026000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020b6fc1a61f7be52633d0a4b4c4c19f771f10bee3fc56588432391c5e97b776f738ad2ba58d06082ebd00d230f18adc6ff1b93a1d3174ae38a06182420b42fdc3faa242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011100ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d85d1bf880c7990a81b9e0267b68a228b48cb64845a580143e82bd663d0a0978185fd95f0baa50fb47a74aa8cef8c1399c293494b43012d63d964105bf0093fbaa242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011200ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002068ffadd19d0280c45ed8f0b7590dd75fed9c1009e0475d4668a40d2e143bab669b7092044a52f2177565d265abe12345db9fe2547dc3e3cb383b448da633b1b4aa242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011300ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002097dc68fc9d81183e84448af957c1465f569cac8fb65c074c845d64f19bd554104171f67fbd239999b74fdceee35ccc71fc59ef34ae332dfd14552a5d8acb54fcab242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011400ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020fa4af9a0fc0b0e9a0ea56ef4057a1a63e28af0df0899331bb075e539ec56ed679c4c2ad7a53ca7b1f3b7ef31bf7d585f1ad9511bdf22079b91b0037506b12489ab242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011500ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000202d10953dee9089d3920de4d1b7493724d70356df3c857c7d68ad4b2d806ffa4cc7871c5ea175f0eeed32fed65ad39aff543ff56da564b92513d293c81ed49110ab242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011600ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020fb21d2eff50f7ca1bdd3cc0723ea65ee398360126353f003d6cb3ccdedb6280ac6f409e9aa8debfb95a59e6ecb9af657726d9ddcd0bd1f1ac24a8eafb9b94714ab242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011700ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000205f4c345ddef72b4ef5058caeacc0700a66cc39ea3c1a2a18c317648cabf8dc402cc83f2d67a467a8717aa1879c41c5677f480ccbec5a8e8016f1f9ccd56aafc0ab242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011800ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020310433ad6123b7d5d9abb3bbac99aa342bbfd500226fb0716aff55f3699f353f95c43168d3378b7887a2d1a24743cf657c91539d417366f27be40cdc63a601d3ab242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011900ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020bfc0947de2b6ade4585380f94beeaeccef09260f0f1dbb8c7dabad11eb32c97e4b029e0f3109e37889b0eced5a40e1b9194df469883750646d0acb8145a4b287ac242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011a00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000203b8193f8ff6a02b88cd464cffda63591cb1786b15b9e8258f60327f63993da034d96fa8c632da473f2abcd001184d1812709ed52e9c2585308b28743ab7508e1ac242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011b00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000204f79cf2c133c2cc73bd1b961cf050c05151f0eddfcc3697285fb9a7a6ea1a755f6e0ae2538360972f3e0c31d87776219377f2c1652ed388e29dba79997119346ac242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011c00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d9c3964f9739a489aec83b9d91e0491348ddc3496aeaed7d36cc80b4d3df73455c30e26ad3209af4fb1594a0425254b96c1d9bef301b3e144f56019afef54fbeac242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011d00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020b90e7f5b1147bc7acec7273f9a257dce321f9d6cf585f65155e6c59290e6247f65b6adb2f6b7d66e9302a37f0becd2cfc3db5eafdc280085b08a1d087f558109ac242d66ffff7f200400000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011e00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020b22d487dd491c29e60fc3e8ba3dd959c5ff05848a2af269a009a683c1c22c5618eb631e42ba03c2e5b37d623a4c1c32771a7a3b603031767002f9c4c843f1cf9ac242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03011f00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002034685fbc27dee9ddf76106dd351ecf20a89c536d020ae5b8164e53b1de2eef03a9c2bde79aea6556b7ff42c0db3ee63b15b19f036578a40be5e29a4e563dc949ad242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020969d6801100c0cff27957f003d5994bb6fc3e80537273412c2375cbc59edfb1462def50ab47b73e04189b9314b32f18b23c21363bbb1700bde5d6f2da8d7dac7ad242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012100ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002060121e480f5e68740e4ad5e35e43a9af8f3eb909dfe7a80b861af047f3cf2931c46fdbbf4a9811813d7ef66ca70a89a93f377aec9e42f8c7bd13d20dc42ef4e6ad242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012200ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000209aa005700a68ccfdfc158c9be0d62b0ebd757634407c2480c905758f803cf95392df59ab811f3f6a5b3b2fd508b15029971cba8c76ab5aadd215baee41c1ad56ad242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012300ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002011d5aa6137f48aa4a2d029beed939afced99ef19ab01bf0aeab4d88b999cfa513daa30f857b99deb57009b0a2cf5d37180dae06571b8d97deb3877f4e4b488d1ad242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012400ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020596ceadcb769b05d2b7fca9dee997da1a32952c0601a787cb8e23f2d3311976fff761af1a0911827c1fee0c638f4675b54146a3f17ad65f3228b6328a59e572aad242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012500ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020cac001eb2c15d3867146858d9b620735c9943430c966ff7b43bad91e7f45b509420bac972f1288b190117f815de318c305b4882e7bc8e00c3806b456d7bc9706ae242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012600ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000205ff85ba1a9bca61ebaa89e99126a41c976ce9024c9c6ea0c1d97fccb5ecbcd48e4ff003414a88179becf0daefd0565b6648da3fa8b1e9862fb7254d6cbc92b43ae242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012700ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d3e4f3325a799d70e469c418e7fce0f325c52be2ee1c190b84ff5b39d567dd2c4d34d12f298026a275ef66faf05c083d36200208e06ef39df4de88faaf51a8a0ae242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012800ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002005e0364263bb17cb112c7a6b49807abc56766ca9f33fce8e4d4e1a87d2497518814aa83fb0c65f975b273b20c3283dfd5d0d92e0d744627e70e816693704b452ae242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012900ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000209de0116300caca1392ccb3afdbe22c0ba403795c7e68d29b0e032ac720d72b322160702e162edb0da7f535d46fc0e608879a1b6d8a3784f18332c7aa7bad2e9dae242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012a00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002035420343ac819c9d40e6e0bd55957637aed404fa2ed236f78b1d4b61fb277602e40ee1a3a4f5764d49f9b352a2e181ebe4ae767e0058d38fdebaf88e7da4e9e1ae242d66ffff7f200400000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012b00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020ec89afed1c02ee80c9004de715b1a1394474a122b327770b000dcb7c29b7282f1ba36b2e0780bd43225698622c3c48a9ab99dec79445d3e7bc8d5ae8133576ebaf242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012c00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d5d5ff8551565d2217e6f20d0eace67ce50337b42f7168bcac7e87d4156b2446cd3d8d5d7ff930c84a26e685b99c22c60e5a0bbe57001b01e9b4a2a696480a3baf242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012d00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d9ec6348ab3f33d8bb73506326da559802ab477437422a00b3a1199b504bc55bf5425b45c0026fec9c3e2e16e800aa75a220a27848c373ace3c20a18a34fea52af242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012e00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020c5e4baf7aa27a6d5147063ebccb77e381b0a16939d7982507701d3a3b3e88b1ea7660119cb01238504850c2528b3b371cd1f5895da5e620fc0a044836257bf64af242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03012f00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002009254406ac2f1028ea8eb2693b2cdb1fea047cb349d7b270b91ead7af5014e04b71fdcf9152e76b76c1808877df7bb8e379536d46a289fbce9a99b201fd61868af242d66ffff7f200600000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d17eb50ed977c27229578a938313b3d86679668181a4e01732cb52f95c116508f755809aaf681a5c0f7839f65813aa6fc171b2e5dcd87f35b13b49b5639016aeaf242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013100ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020100d4bdda8d6187537d88e810ce2aadf581802775bb74a9acecb6958c75de5251f5b24d57fc19c7f73451a559f0758188af4ab7be72ecb22996be0225b0fb099b0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013200ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020c3333013d49f646c18537154844d37f81871444b3fce3a68f6e165d7095546115937b90ed72637588e4184942469a3ca1bf183fa65b9c2785b4592ea609c8b59b0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013300ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002017e241077f8cd618734503d66c0ce828b7d1add601903160a3ae1531b8ea1e4ce69c66d64563657224548f7ecfd7ed3571fd5f6976205ec806d72f9aad95d352b0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013400ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020fa40c6e3a15a659ef582ad24f4a2c0a1c801978da4b573a528bfb0fb73c3cf121796631d479c9fa6f6bcc0c5c1f0cc91e10ebb56e3b6c2b867c0052d0924432cb0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013500ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020b356e0e5bcd4f6454ed9e6f1adf91b466723b45963b02dcecf2e89c0d1045a24d453cc476a5662964ce6eecddb78efb40e1616223d4c7fd54f6ca84abdc87e02b0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013600ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020ad91fd99ff639b89af585c3b8708062a48ad19660400d204ef099c2d66d1ca57b0349eb1a161d04fc8222cfbc02b8a1ab964abc5744f2cd726b8baaef1abcc4db0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013700ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020bacb69ed2f63b38dd103114bbc24dd9b609f8b6380f1f362a05c3f85f9e6cf102a391905e006fcba723d56c6a3eb27efa4396ede18f9c50e0be90dc1e928f163b1242d66ffff7f200500000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013800ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002024889501a0da6ffd4e6252fd87464b9eb54dbf7b1c759c2ad154152c3d7c5b2e8c3626fb538921b3f59786de9e6ca2487b3a1f5c80a3d9dd82c27a6b1a6eac5ab1242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013900ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002090ea4ed8d0f7b230fd2efa6b5ffb07e5ee1efd59754e7900ff4e24f793c2d926f8481e6e63a795f646f1d06cacdd2d2ce7b176afa589337e869c55e864dfec56b1242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013a00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002079f76972c386a45cbd62d5cd1f577e36b2d37895ea48ad4f25b2aa6c386e483404dfb68e4e8a1716e151c7028c8c0ea9e80e9871c3d7f2e1f22b3a3d719fb2a5b1242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013b00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000203e5fb23077ce93fb1412feb53b3c6cedecfea12edf96aea02a2fdec683564750419ff40c0af3e1f9bd992edf37118f709abc770458bb5f73e64a9068dd6aa285b1242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013c00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000201d517a82a9ae83660d8c57aeefb14b57efaf3b93b22b43735597bd216af66b161ef125e5eb8baa3ad71c6364e0b9fe078e29f1b39091c478abccc05944bf43fcb1242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013d00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000201cf4a4d875525be85ed64be8200b4149ba224652f880f050f155e3dd0f6dcd2d170c26d30263760e6ad9aa8194f9ea6995755a57e0596010faac244c63315c3cb2242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013e00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020fca7eee11cd55953e44151448a37793746c05ace49d1281bb6f27772ed638b2b67f5446d2067d394ab55d0e78e6503e0df4da7137a910a4c06690750156cef79b2242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03013f00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002011ad845546ac709706716ea309ea4b5dc058cd1be347db517f1ae8ae50c9361943aa4fa21fe9f64d97e0ed3d93894339eb6a84e834ad7e075033707b15a09b42b2242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020e78aa3452cf4007ade84710d761445534b0246b2c3b5b00cb88811e001b22e0671dc09c26fa4f6e119dcd72c5c20126f2365a75dfab9689aa1b67e4a95a19ad0b2242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014100ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000203fd33c4ecd968f1c4610e6f6f60e7c0f1af838752ba5366ed32510cb26b3043c14ad22a3591f48182ee74f23a1750f137b135cb9475fb201098f2bb4c2f1fdd9b2242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014200ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d6a39793d31cbfd1af6b33552d9bc2d5e0815877419b6d860a6893b1ebb1c4212bedb144bd378fd4e5d3b8c0be92aae4e95d8ec8618c2fa5b1dd912d8c1d55e0b2242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014300ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020afdcdd52d9eb6de8cd062fda1c9421479edad871ae7c27b99c48ee589e13431a104b8c78e72462da96c7f39aba43f890a86530d4fb56aee3d96c99c242d524c0b3242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014400ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020b63b5fbee3b85e33873d93dcbf1d566c9081d4a63c6eca84fc96bba1c862520b64934cd71d23a22f62b2496bea8c64f064c4931a6ef4b9384b4a5090b8e27612b3242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014500ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000201a2c83dba9834c76997b89f477b345a47a9600cbf30bedcf4b380a0a11bc8132b6f5e54d82ccd88e8bc1dc1124e42ec2f2b1d943572d7f719c55ea48d5805841b3242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014600ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020567483e2c2f091af7cd71d03aafb7b85c5032516ed8318ad970e4db324853b344cec6bada693600b655cf4ffcaee0d2df35f7809ed9958da8345783b52a0d459b3242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014700ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002034b16f266dee682239831dc610d03d10974d8ad400a41fead6be3d03b94acb7cfdf201cf64bc3631fb44b4618cb6720bc1512f6a43eb414c5b1158e0e8505528b3242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014800ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002096977882289042f845b7bb3350a36f55a39cbe0eb0176a52b5c79ba1a1866d28fb87c6e6e90c3bf164a95415a90ca7e2c70742c5d0695a9ed8018c91f81af9d3b3242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014900ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020e7e2590b376f0c6998588a75bf37f0fd0f314baf7e49bce637d3237a171b027cce5b0adb066fd5710c534c446ec42d5ab6ab1881de91f18895a1a73dc00b9490b4242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014a00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020c1df8ae18a085032270a7955b95779b3dc188c2b11d91f35043d5799822bd00e768988e363807504cb4ff2bee0b38767250aeb8e2a783efa9128aed67f9f0330b4242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014b00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000207c4cdc374b98412c61cb0a9ffc15ea2bc2b6c957bd64f30e7da78797a514f014da8d366066fdc30df791b7be1c73f97d762a3d1f1bde06507a39ba65e2216740b4242d66ffff7f200400000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014c00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000208ea0c30cd8e4285b6cecf7a013a9cb1fb5980cfa5361720094c3f46315ddea440201a7e278dc70cc188e58afae9a080f5e982254dc556f22f4f160cbfb2ce9b1b4242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014d00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020b49f1f2813fe4cf60b84013a7a66ee8069fef8fde1589f1bb7491a800ce16d1d94386bf1300a238e3522886fc1804232b1323bf39cd63543be53739e96a67058b4242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014e00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020b9c51fa82b5f3be2527b4f36642f998780ad7424acfddadc457082eb0c51af33d38e3e20e32a812798fb9c16d1ff5978bb6a9700efce13c171e6ca1e4c7c618cb4242d66ffff7f200500000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03014f00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002050877e42ef334dbf296d7655f56d9597ddffa49c2649707819cd908916b316026e0e9f165fb96149dc1cc645ec651d2c487f34cc59b34abdaca55d0bb52448f0b5242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002002eba642217e71e94334723645a3db397f8c83a8b7df5b4c7d12d566dd859014f6c8a924f88f3aaea0dbacb410d9a9d79ddb2b2d84ceee104539ed2663f6ff68b5242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015100ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000201e772bcb91c42f43cb65fa81cc72876b4fd20e59d54ceadb928d3a0d01829824638fdd743a87363f19441bd7d3af1193ec94ee31da28289bc1bfc37ce6292756b5242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015200ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020cb684c4d09354f8d2173240f3e4080b11d814d8d64ab0b851d0dfca5b67c021264c0b4d218b63f9ef8febd0c822d0c609219687d9a1d6ac2c73f50501a4dd89cb5242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015300ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020b776bbe12a01c8d1d9e30a8e4d564074e939af2c88e559cd1bcd88f99943ca33cf0e756cf03b0b23d9b65053e309a7a54a26e4403cd3a3d3d31524a8af1500e3b5242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015400ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000203d36bee9d695e4ec54b8442cb62ec3062cb056d95391fa73b69f4867e88c6b376984a42255079b96908aab4f4bc5175852f3d54001a493d4f7a9d09d4aff0ae3b5242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015500ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020f912ba814881103501d49c3df38e24ff541f6bfc816d4f8bb6db1700edb6cb3db125a06204d5694baf2c13ccaa2f06941adc3ae7d7f2449212644cea8659cc6db6242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015600ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000208b911ff262dce74ee321bf09df07c39930d53a3a10fd83c74ee4ee6eae13a2355e47b7886c2839c9d582d49fdf356a5c298b3f7c879fe4467b01cf7f951620d8b6242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015700ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002012e1e9a299907113c100c34cf54bfaf57a02c0767ee571d0b0d586957b867632b121f1d6fc22dcfa6fd87cc5ac11579cf7f81554536c4e326eadad0ece3cdaa0b6242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015800ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020f4ce3aa3f38aef3c886d517a63a16d47c4392600caa85ff656a0829380d03e32a1a1289f4216d88bb0514d5259b8f03dcd05fbad650bcfa59cb163ff5b698e8bb6242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015900ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020f590ec1e4d4e3ef13a520a71d67175cad4b9a279b0dcccfac471c658c995af0488752ae773a4154022507aed806c7ee50445a92211b02c10ff86070d353ac930b6242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015a00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020fb36f60f0a788d22d25ad7962333e107e142c1e797614555a25b3fabf2a57633ede3caa7569617ffa444d6d4bd3e2dba7e31085b1976f16d94c537c1d3462c0ab6242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015b00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020c4f5c492ba5ee620cbdeced3d2ddd6c6b3cd394bacb1a917774a19048e1ee64732e54ea8502d51b05bca7f981c5ac0f3918dd02dc178206f36957e6daf2a8121b7242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015c00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020cf0e39e15de40d780ac3bb7eb658a2d93d3f6266fae114f919fc343d08374c096c4d12d3e956a95499d46bd5781b02561da3c74cdb7715f0e5c1b649197c7c86b7242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015d00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020ad64f0c519b59ead1dd2447eba48daccb1250ad83f9f1d2a4e687085d099181024529c67ba916443394c23138c7202970750c86f8edbc81e9903a75e509cbc41b7242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015e00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000205a1116da770d72fbda72b39179312f45b3d3fb71e2492de5401715d81216ef0877e24b23c538570850108445173cfba3c5baa6ee6af16f807e7f56b772bb2933b7242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03015f00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000205133fd567593e6d4abd3599c4aafd0231415165f82d29a0a1cf4c43e7fdddb68a371d48b5af5147d8cf8f4489d626985d6420f851bda7e70ccded3f95566ccd9b7242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000208d41770bb44ea7f13f2a4b679dd3af01ffe76ffae2b4c3e26cee308c1b76bd5333a5038cd81caf8e515c5f6cbed94ad8905bad2b17bdfd0327bb1cf41f306accb7242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016100ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000202f33147ca2f755af1d9f2836059620db687b6d97cf85d832c22901aaaadaa42584b88b0732ce3d9f69ab206742b348ee96a6fbc63c288f14795a8221548cde6cb8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016200ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000209aba329a818d2eb01da985e497050eb3d381d104674eefeed2ea14f2531b8716668688a5f4545d86d00bdebb0a007cafc530603c1fbb6d6a9f069a1d5f109fd0b8242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016300ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002071c804f177410c9942f1df0bc891b9ae655082125488df7e5c79574c9ad5a83b8e7509e225f8970ecd5638f968934560a3b99f6a3ec03a5dca7a9db5331ca713b8242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016400ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020617c4698f1f9b2a52fe2182cec78f469324a711cecac03013aaad0089835a916f9126503be1001080102ab122a123a6ccdff5a94017c15a6f14012fbb8a8fd78b8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016500ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020e54649f5adf59dfb18fd1370434cc76ef9a453762b17a435dafb580a19a5b868cb067747f9a355804335084c652f93548867e02050fbcec3c0ccb05657ce666ab8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016600ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002067232d9858897d86a155b92fb94b42353d765f0d2eaa095460a1ce297c3863051e31f463b5077ebdac1295d56461028fec70e8022896c54cd172a1fa685ddaefb8242d66ffff7f200500000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016700ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000202945795c2dd6b0c47c96d8ce65f0083cf20cd5760622b59ee895eff33b8d1a36ec51a1a1a99a971437b3d24f06190608cc2646842e3b3fda0b00df450f59ebb2b9242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016800ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000204a4dfd3ceab29299d0c607c812ab2626cc1a8416870f5acedb9b81bac3807271f400a1a56b15e990c516b29a50a9a3725ffa77ea1661fecd37cea2e74c8d2b9db9242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016900ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020b3bfe4afe33b5e0bbe6f4368e2e2b88a2bae140c03c811e87ce5cca690e3e31406b87a9f1d8a9d7af6214f09167857f20c61c842d9f9231e5399e4336040fb04b9242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016a00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020a32a6b2a892b689df14f7c9c03410d3d3f93170e7e52fde74d044c1e26a1263168b9d32cd7aa7507c31758104cc2615250fd24f3b52cb887666ff6f0ec67e81cb9242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016b00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000208a6eba5ccecfd3497234d5a3e2613432219c17415974089a4bc57e2063a8ef05074c42c456bdf4c1c163f1c5f9449710ec4bdf2a235c8c77b8acb0ecdf13e9c5b9242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016c00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002001acb70779eb9d2ea47e0f4d712f3c53ed5adce6a5648f3424f9fd45c3afe619e4f0e50d89b209a25fca681be53f69ea2be9a77f7f90dab1fedf189630913dc1b9242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016d00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d71e5b9e74a151b78b3a08b892fb6c42413e72678245b69fb336d05d2ce95e2e0a448aa97200b2d8ed8f31df63f6258c37cc4e57f10bf391513646f458830993ba242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016e00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020565de0257565202598c3f694bf1a7016d49a7c6ddeeb114476ec452fda62231928c5aa1ab310a7f56b5f2719f9329b2b4547a19b31a378b52d3583a961f1e961ba242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03016f00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000201b719fad536a1e8d485b159afa8042912824cd38e30bb6e084cb2d267531f578df5ae1d4bd3c57f48af225d738ad22c741af78b77c80b58ba589ed86c214602fba242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020f404df02ce88cd268ed66c9acb0d67468318534f1e27e77d97bd5b60390c9678a5b354db44b69a99df4a92e3c49cce01869df231013ddaaab5e3f1bc03d81294ba242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017100ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020283fce509e2ef4684d5111303f968fe5b3964c6d87ebad2c0f2fd454548149054dbe5c69140bc662c90ede02f18a5558adc0047ff8eacba64aaea4e040ed867dba242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017200ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002093eb737cdd90ca5821280cd71e2bfbdef549c1e6ba380f03fdc1cccac4059b2560035e74a3f897390f93b6ed88250a1c2136ed516feb5a2a47fbed955e98bd47ba242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017300ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020011fc8df4a0c62a841431c4c45f5432ae969288b81af3c1dabc8ee1bc86ef050375c54b2ae535467d9179fd386ee6d9c4b33b16ea12f88f6256526da1636f191bb242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017400ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020885c040fa44740515fbe3102ea30fb4c2baa117e84fec25d9216b011ea36d271c62fc55485223a484f89ea0d4dacf68cc53fbc6af98bf3175338c5db05a4cfc0bb242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017500ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020ef3fdac73d38f9446f5d2a1065dd9020c0269a44b5e35648f44e8b1b86d7c15c8eb10a613be613468b8db3c70fe2871fa67d6526a3b4f11e736922d8278a82c1bb242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017600ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000206ee6d94eebdb0974650cae85c9d4cd035e07031e6918128e7dafb808fb9dc41284653ff9bf84237ad6a84cf6cf9817d3a361d805db6cd3daf7665e92ed00421bbb242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017700ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020a8c7d8435a99871c45680b464b02d8618b23ab0ac3dfeb93926e54ccc91528633dc26cc6c6895abe5dab4a6302cd192f40e9df8404ad4b1425ca7d6c2b5c9c18bb242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017800ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000208880a1808163e847db25da39ea5e8a505d7ce390a3b2dd363b0232ae19896c274ca90749f6d4974ea23a247402d638479a5eacdc3c15a050691acb3fefa44a7fbb242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017900ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000207d58853ff94add55234809e82d5ed08b330ebbbb6f21587f0728e2a164531f735d9bac48f7069d5d36f8a6f39c41dce36c4faa1a0c6531802797bd8a32ae96afbc242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017a00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000203574bd3a510891f0203282179050926b511c020ec1360153e1755b5847c596410acdfca82eec932a8b4d8487b0401ca67e281f007f5ee16a283bb5c848d051e6bc242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017b00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000207e3269b3416c628d055c6f078959b491563acb9fa880e27dee1629579c0a5319ad12cb821d869154d368363e677329729794ad9ae554c1489fd7165feb2942d8bc242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017c00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000206785e999e70d485458ad511b5d2f16bd66595597ffd0b637ec00443bf5facb03c969e25f87b232fc4d256c1e2366052fc7f6ec34924f2d1ce74a9f8391cf13ddbc242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017d00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020f381fa4bcbe9d7e2fd4d1732e3fe21f57d466dafd4bc847a1accaf549ed1ed2a9c6d6d16882a64c72ccca6a0f6ef5094950a2b2ac9de6839b9e4a8dc3f1f5a9ebc242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017e00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002015982b33b232e16e0639402194bfe59ca442fa5eee0908e17375a639e21976492753bcc20325ac44a5f486cd4c417dd469d165fd4edca4f6200845547dfadbdfbc242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff03017f00ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020fdca1940e53d9d932dee8475fe4d22268ddf7c1f75792445fdb1d06c810f8232e7f4422c02d71850c1141da19d6f25f3cde4d98c43a718315b3ae49719b9db69bd242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402800000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d9ecf917131051e0e7b5e58c351d9720bd25eaba552d24bd8c82c6cd71526c0f8b6a35e7520982795e0048f2337b2575a7716cb4902835bf69e2e20fd0c8b8a0bd242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402810000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020e4ac0576eab0dadad615ce687cc92164368a8a024fd6cde8aa6b004d9e5e324d9d55711809456cbdd053aef9ecdaaa6b1ed01843fcd0180a7837593628ff6decbd242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402820000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020e0ea9b2cfff8a497718a1ec66d7257d56214e17fce3bcaf7d7507e6a104e5768af3f25f467a26ab1bcd44c627a61dd7c6143af2847778f9854049cec23d73420bd242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402830000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020a6eb927d1f8a6361f4653f99495cc271c7e9e70f58daa8d54022978e2c59ee2f4f58274192e2e88ee248b835ab8ad410817369c07e1217bb4bcb2f1b17edbf2ebd242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402840000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002051534f847263fcb38cc601f71f2db087f405314e4c9a0bf21bc14c20af62ee28dbf43502bdb7a355fda5697c33f6d0e1ea8a708a101862e690dac25310b766a5bd242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402850000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002039d1000f53fbc4dece3d9637e183ac36a38d67cd14ab9c79a30777b2722db65f6d0e0b35f1f52add619cc15086ca69e3070c2d1c1dc473315d23b1a6d86c82d2be242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402860000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020a594bd4cde746fc3598f9ec0862576190f71348a027f46261d1e04bc84f83e5ba43942886ee1ce5ef626ee17558c2a7a06a2c2d5d5fd3394ffddb331d232177ebe242d66ffff7f200400000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402870000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000204e2d5c0399ebc5c5322f88cd10141451ee5a57522b8ab36036d20d29e38cb31862674f09e5aee7956ee09e346e8b3edb1d818d08a0b24661e3bf5644a4281da9be242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402880000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002088900a6bf9bd6a461d065eeb99ad9dde564952cec1fe60e4bea6d8402861ad7d7b70bc1ad5e7635d58387e0be8dd25734aec644243460381ea1b033785ad9f12be242d66ffff7f200400000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402890000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020528104150f16fb36a4e6bb8c4d6016d856e578cad9c56ac22f85c0f1fdda9c1c718dd079b4d6a3c606ae1e1d154383ed6f817ebe20e3b960f5eafe7700d682b8be242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04028a0000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000205effbbe5e95135f6e92840b4d82f67d28c8a5cce1d05484d17f173f2ce6af77621f128761961890dcf6bd1a80e5917a3638268db765fbb62f1fdd0fa16fef98bbe242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04028b0000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000002028148a9f61d6297295c1226f8768ba16023a99f09f4a954c5423f3cbdea45d2818f9b10a859c938977e0770c9ec1f4a7bc8ddd5967d7b6e16a2c47f86211c5d3bf242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04028c0000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020f7ba22c801cc57274aec68c1a156c14d2b0e158aad723c51322ea6a3bd64605b136c0a30a4b8d8ae9fe01b8d919ecac7f402e2f80c1e8bc810c6ac0bd96079d9bf242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04028d0000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020d3069ec8d092fe171fe9b79495e8e7f24db5a43e8e8305dc07f996d1b1ce656d6b79597cb0a1d85caed7164c876f3ec67519c1a7fd2a4965308e27268cdd6167bf242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04028e0000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000020eef72272a0bb5ce0528e10c290245854e50c789001ac1609622e8f6488ace5373748c28419442c3e60383f1fc14e54d1c681c6681541a68c3e361fbc2fc523cdbf242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04028f0000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000306896592a3ea4dbf8c19e9998be4ffa03827943679a4204712120e3359fdad25c9614019ea5dd11c3d38422f8da66631fed6531ef5fcce927d81ea345b1fc679bbf242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402900000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030523c6ef8cff479608a467a02bca097b2961679f3de0cdfc57228fd95f4c03401fd0ae1181844f2dc4b81fd0866f072a97bce11a7722a2a1fff557abd06a36151bf242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402910000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000003012ac3be42309dd4fbfcc02f207b6d5956561a09aeb4d982a22202f052a96494fbdc972daa895af0e662ac30583a35a82f69f584d9ee665e7ae772e3c785577dcc0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402920000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000303a366155345aa1cef44a5812ce6b2ff9c116fc23110ea771b9217bf2bb75b243c9fc73b65ca6afeabad323d62e01d206811438b3813cf3d7d74f00aad7f696dcc0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402930000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030afc514228a275473b190113664494a28813aaeb666d75ca024d35a07e11f0b6150e67c4abbf2b31ed6be994ee951a5d85fe749604b48215b137542c77340fd5bc0242d66ffff7f200500000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402940000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030ca9cd2fea2556b65b16f8a3dc0df73f0aedfe3e9418c1da993e07a05b94b9b59ad94efec2ddbf4294b649020f9cb94354c589f52629aa96870e4e8f035f2e13ec0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402950000ffffffff0200f2052a010000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030782ca7554e8c8d7a68ec7c434ce41cf62317b392862f8d6359475d2f7636f02d5957028a93c2f78343a408b08780a1a1972734f3c638f413ab118e506057c176c0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402960000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030f3e0a0f98274250e5c5a56ada49bb294014c42f402f6a2a43b70d4fcd2a1047d78abb1f53c713cd9d7b882d90da4c5390a52c76100691cb934d70c268d0f6408c0242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402970000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030bf1e2925ae124de880bdeadbe4f1185e2efa1a260fdc035739edb6eccf765a3c559f1f38c185ec86dec065a565a5bfe3810aa5247fb101f32e19cb8935c61e31c1242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402980000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030f2b1ceae06ded56e1a1111960fdb03c65271cd43cc457e5f57ab3f42f23d721eb7bd2cf81b97147a112fbf47300df0a013fe558d0c2600aae71db8e39ec4a478c1242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402990000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030cbd7bfd6450022971e585d82c23d239822b4bd3da3906928ab19b9f44e5d1b42b7a7cea58cb4b63301e3bd15a9d5d58eeb7fba20a48323b0d9945cc683fe8874c1242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04029a0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000309e52161272efaede1503987717d6bfacd6594d2276683d4c099626e963455320bfebf0b2330ec760e02160572e43603f1e5e69d52af960792eb5a4ed4a9bc977c1242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04029b0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030c103628b91423bf5db4c914aecdd3d4e2c48fb5cb91ebf0cd708ef88c88cc371f81cd2e6fedf8a37b690c5821a11c8d03ef27807a051f5889bc9564468bb30abc1242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04029c0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000301f4dbf901f4f9d926be445a1f695ed3f9848d59b35c7c58832ee5ef494c20d12a3be96b275a338a754506c3065e5cb44f4fd811d2cfd2713cad39a9110666dc8c1242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04029d0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030f928d5d5385bbc2dfb5d47dfa27398852d3c94c44f9aa7450c8f1831f6bb851b25cb218eeadded201e0c24ec3253d76c9b2b1e2db5882f6f3c14e7e846ee9756c2242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04029e0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000305200b0568130df45b7557865de1951b9ba362d3aabd8dc05dde24df270a5d749076caa6557eaa0957a4bd26fb095f2a24953f050435d76225ce8aac830704fe5c2242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff04029f0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000302412fe12a8b1840a603a75b37fdd993cb428cef5b80bbeb43f6f1708bcf27228d1ff6c324e38c591cdce25129abdf3aff8107b2977c6857cfa4156685ea4096ac2242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a00000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030ed743e953e5b7dd2dbaa0cbb66a0522a82d95ba2ff25a106b0e0cea9467ac319fbc639f5973aeaf28baa746a9842cea53ba856f61cd3f8e15bc877c7d2e6bd54c2242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a10000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030c0470068ec5c8b7147f38056f2b86123cd8dfd4e2a31847deed98e6146960d5b97a8de23543b199d5d41a213fa2e7207f13c6b41ee813ed7c4923e6f9d18aeffc2242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a20000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030bb7e921ba07b033b3016a59f0231fdb867055c80a9a64f32c071ff1606e59e4389769b2d99c13d9ecc4dee5a2b526a5f7ec8adcb57b93194b24bd0ae0302dfe0c2242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a30000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000003026a1fc16d183319d97d94cd2a7d08e720680d1b85efa2a1f17ba2768b4d4a74b08f1ae61c9e69a6ca2c7bdab9bce0dd62fb7910ebf9afb4d0a75a2e5ca764978c3242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a40000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030191d904eab263db4f41436d6fe042e19748d348bb607a55408f8666b2fef6f487b8a6baddc9abe0a4b2158dbb8cfa1bc8260f1efb1ea8d1aea5ccaaf96420ce7c3242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a50000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000303192c014b9f2c858461675988e01a7dfe902408257ad8db9467ad5494b0f80327aac980821ff362fb59cca122ba25d35bc825e61f22c09fa6b64f51d89115c6ac3242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a60000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030da309b9a623c525c5e01088abcabf0eae387a70631d69ddd2e2c1eaa366e7d08e1a0044ba616c9ceacc1f39c6e61b14bb43a87be69880f639f67b5a7812d6748c3242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a70000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030c3fc841e455cb7ab8e83c1b45a9230692fc6bf54219e39cc32bbcfe264f21f195eacb3bbfc83ff7a0cec7c88c37e9da4472a4281967559a84ae1fe977c639465c3242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a80000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030cafc627aeb714f3e3cbef65c5b159aed545850b9da4ef99d7f0385da2e913f2bc5c17aab7d0a0bd0324bf7e9e2ef88c63641d620846ffb18cc8e0f925028451ec3242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402a90000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030ef971a009d01509dd152bea0007051559a58c301e9c3dc63535b944a7dcc330eec01b322a6a7ba1396e610c9f4da69779499325463e128822dac6d80bb62b268c4242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402aa0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030297d2fbcc84a9fb61effcf30564b348f2a51cb186e0b1ffd5079e9c3bd1939563f314e6e6b92d1c73edb47b21f8008aa225c8d87f59391d1bfd1f4acdce6f56cc4242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402ab0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000003022cfd9a1068f864ea0ca15f4b661085d383433208076ec04b6df4fcad5ce124bf648be1eb086be6bef7fd65911d9849acf56dd9cf24798e18054ab2088e27eabc4242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402ac0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030972f66a342e8bd2e912aa28056a394e5bf005187001863d8167ea2c059164e2ea64d068a4a72431cd97fa126bddc9e3a6fc6262e131df47328156ba5ee2dc118c4242d66ffff7f200600000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402ad0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030890dfceb5d573e6afb97b8c945a19fd9b6601b992f80015762a528af6626f8411de57cbc0f26848ec7c4541a263b2314a1877dfaaf53a6a0ab03ab0abe4fcf40c4242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402ae0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030e54b3b165ef52498f0d9af5774a688138978efe75480aa01ce606dec5876e217c1c051b9ef4f7c236a2d892bf98e108f1193f7c67e163d748a321c5ac1d9d554c4242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402af0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030b87cbce490f46d3723f498d44df05c6613d44322acab1740e05a1d54bc2e0f44388078387e078f1a0be7317c7fe04d743947c5f3f9e06072a7a8f01f013e4e63c5242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b00000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000003089c4d7eee1aaca1d091f31a4b465a16a450bc95f043a9214674f2564ae04086493e5c1d30bdf998345a6ccbd20201f78dee8972b439b228f02b590ae13b66f98c5242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b10000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030ca6a1ebf54b1f62313cb32e7af2b6469135d8da9577123b62b334eb1ac8fb320367bcf29d785bfedb2cc1fa040c593783d35f7bcf6b70a9d98cedddfbaa61e8cc5242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b20000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000304fe071de37025d5868caf920761986ef0890a3891e053d5452b0852f01bc7a5b2dbe8a30d7a8285ff0e99e3b72237711fd0418d95a44600a4a5b78d8b5a6798cc5242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b30000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030642004a67b3c8fca45516672d59a145e74f3c02608b8da5998c27c8f2b05b43fb396262680ead34a6ba6f5ba19f617606b1701557179c21cfdb3e41f093e9343c5242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b40000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030dfdef61d552422cc6db6a31cb38c74efea160cdc926995461f47fd52faef3b22bbf9c570efdf15b90cd17669c4a8dc9525ee6242025979af18efa0be7d03edc5c5242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b50000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030614dfabfee3a6bc50d775748ac679472f0b1f708815fd172852baf66b7a64a410ecb1ad68cdd78f7240b80d015f922416560eca040398546a74c33106b27c791c6242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b60000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030d1f6ca10190578f7f789b8785fac043da1a06ad81e4055822cf20abdac7bd64fc5874b1816bbcd03595404faaa17564297bb17ef68b81ff29533c67d1b5c5346c6242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b70000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030eb118fc656ccb168532745325675f577f370656ec34e3303864084d4cdc9714b37c8b3a9d2547935a60a2f082d5d666177305c98056991dcedabd6ce41a75e42c6242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b80000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030881184d8fc0997d5e87cd069a1812ffbd938ffd2390885d15e408658e501da596adc753f17f3b1dd6817d1d593b6196e9696bfa90d179cd0d050dad2532d44adc6242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402b90000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000301aa44b363c58124b22d51178e70b86f976f8e94a5ffe9696715056e9b20e0c4914d14ac8da2625d3da070be3d2522164f9e3f34528526955d71565b5fa2a7bedc6242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402ba0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030d5c81f5d6b9188adc202327d5c2769f00e6aafdf01e6910c676e99434d1c413449ea0d2ef2775f6ae5f5673b9db020e44d417e01ad9a691e105f5c9ae2f709b8c6242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402bb0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000003055a4176e66b3e691ced84c0d7184d220a1fc7cf17832a2ed4892e801c713445463ebb3615a6113c2ddfd4e0f5b8fdcb2aae912569d3530f983f57950bbb9ca24c7242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402bc0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000003013a50d5e9a17079b1bcedfb6426bf7c103cdf7ac353d196882dfb0a0f7dcf26d48418e7eccf5663344566ac283e4af41c74f503dd42048e1a731c3ce73c87485c7242d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402bd0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"000000303da965bc08fba52571473532c1ef4cb111e9344145fd7a6065c92d32c4e69079c88b8c63a7bd7ece3410226cda39d0fb5dc4e1b4cb560967f03e12d7f155aafac7242d66ffff7f200100000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402be0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030c8cf32d32cbc1e5fcb6c2b75520618a43dc714a16706d3a48ec68f56e8cc593adc15d4d1680537df08abcf0ac08661fc7ecd0b9267f207d7085a954a6ce2da8cc7242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402bf0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000003004c981c749b4aca574fbeeba545cebc30f91e2b8df3ceb494646b0ecbf3ebb610afe1bfdd7ea9110220eb1f102ad69407d6c44026c4dd4bf9267d730c160d288c7242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c00000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030b0b058777dc496676cf990be016117d99fc5a93226d54b9b4f01bd08ef32736f707f2d27e9384ae46a08956185b5b080911b9eba89dfe48260276d09f910c3fcc7242d66ffff7f200300000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c10000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030ea8cd2974aa0ac6360b960e089a6623b7bdd4152439d05c63bfba1599b64017d4d4173c3e12668297d23cf91d3141ee01292580dfdd70a2e6fa30c4764008f37c8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c20000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030ee8db336dc2ba9f85bad141b115d9ce729ef0cf4e274adbc88947f3533e7ca569e6e65dea6c09c9f5e3c8d098550588cda81f92dc5d7ec04fc9965d97dd1ac6bc8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c30000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030a06a5e0b84c8e72a07ff38dbfe03fb8e7ce1f14f3f2632d4e12f573e6c61c756a7e21a865926b8cde1305c83dfda2e7a01591dae642a4402d2d298406349f39bc8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c40000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030ecceafaf947906cc86bbedb1b9556aba9efcf4f12a19141421c2cfa030d5a17ae1e25e046cf69c4fb9eeb1d07289f46f0cacdf1301619850a3d693935476e819c8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c50000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000003097e27bf8d0148c851ad5c3409a222a741ddcbc5c71f97df87384c3d1e316e46e427060a13cd91b94eb4bb2317db64406657ab250784a67fc783c00a24f3b6fabc8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c60000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"0000003098fff5fab49555cda5da113c679f2da07cc7c5696067c53d84d7bcaa71a5cc351cae4b9e2fd5902a4e0712ee59fd918a3813554eaa3ab06e73c189ae6f22b995c8242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c70000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030a1a12a3a010a3f69123a30427ce886f3d4ca42f9fbf820ebf6b00c2089a0b30ec547103ae3dc470f3a8b999ed75068d150750ac0c549f092c51c9689cb1bc1d2c9242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c80000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030da2688ef7d466cedea6d3737af58fa34de69d022b5d1dc7bc0aaa20112b40a64a99d65b68f1c7f04efc082a98e14576c01427515cbafc1f5c3d31f03ee3bd6a8c9242d66ffff7f200000000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402c90000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030ce6cffae4dfd294aaea39faf38227c96dddbdb4886110e85a1210fdba385394c47701cf5bcc054e5735e889198512b4be2c715af77b490445b78841df7467cd76e252d66ffff7f200000000015020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402ca0000ffffffff0204040395000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9edb28b5f3f52e0b50acdf4d68f04866607c565426ad9cf46532333e47e76c4e599012000000000000000000000000000000000000000000000000000000000000000000000000002000000000101d453cc476a5662964ce6eecddb78efb40e1616223d4c7fd54f6ca84abdc87e020000000000fdffffff0273101024010000001600140b500a01c9926e36f8913967382fd767a48309a200e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf902463043021f1921216d69304c9f523fabd39e12f98dc0c2d9d4598c28494c92b065d25a570220121ae3ff0feb349b7f357bc6bc98163da82ca63f6ae51fcf791ff0c40a068ac701210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc9000000020000000001018efcab0bcce7a6b22485598a2eb928092262c95f2ea233beab343044013269dd0000000000fdffffff02731010240100000016001462eb8d4bafe68555c2989cc1103e1066c9f276ef00e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf902473044022001c31890216ab85af755b4a2f2be55901da8a86ff32bbb7b7c2d126ac284d5f10220440873615edf764d686a4220533b1018e2b062dd0035adfc47833925c6d2863201210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101e40ee1a3a4f5764d49f9b352a2e181ebe4ae767e0058d38fdebaf88e7da4e9e10000000000fdffffff0200e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf9731010240100000016001430fc806efee1bc097ab6d0a7a40edb4fa6c5f875024730440220373c65fc214f2119d55b1fa4005d849271248764bbfa39aa1aef8246f34cd9db0220536563302153be01f6ae6bf5e44833eb6a73938777d555e94ef7ed67b55b39c901210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101a7660119cb01238504850c2528b3b371cd1f5895da5e620fc0a044836257bf640000000000fdffffff0200e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf97310102401000000160014fbc2a67ea3ea1bb1e77a9f198492301cde68808102473044022072fd8ce1b7342ebe2bf42f0b90304260f55ca21c22630a19ad0ac8ede04d42cb02200f00c7e9093ae0c38cd8d5ca52c19bac139205c535959065b77a49eedbcb588601210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101f9126503be1001080102ab122a123a6ccdff5a94017c15a6f14012fbb8a8fd780000000000fdffffff0200e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf97310102401000000160014cf9382f4d7b111dc9a6079a7ec4093579eb1ec4c02473044022043ed9deecd32f4ba5eda9dd6c5b22ca3ddd62b5088ad98cd1243141b40f24a0a02207b7f01853b52f43a5c0adbb9a298f2ada4a7d1c50626a590fdf4b8b814fa8c2801210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101f8481e6e63a795f646f1d06cacdd2d2ce7b176afa589337e869c55e864dfec560000000000fdffffff0273101024010000001600143cc73ce98fa4d14a97d520508ea35321261335c200e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90247304402204783bb9fcb96defb632109c940467a4e1329141252d64337393e1423c021fbf902206346be30e066251f1e47d808889fab87f2cc4a0579c946b1f7e3180d4ff5207f01210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc90000000200000000010188752ae773a4154022507aed806c7ee50445a92211b02c10ff86070d353ac9300000000000fdffffff0273101024010000001600144599ebc57adaa82fce98d5f1f7bc4c5d0941229b00e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90247304402200b7dafde98de409ed4d17123a0d4c7d83f54cc80fa06286f2b0a8745b8e4591c022026e88d230997d26df64f424cbe615d4dce08346bff33b3b41c7e59b462a8695601210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc90000000200000000010104dfb68e4e8a1716e151c7028c8c0ea9e80e9871c3d7f2e1f22b3a3d719fb2a50000000000fdffffff0273101024010000001600147c32dc8f23a36d63db4625642b8c3f357b001a3300e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf902473044022042aceecb3bfce5af639f229767add6cb2170d0bb6e347f4690f5c1780fa83f7a02204f216de36e53bdc083c9a589562eea188dc57b686b61dc7da41ef13ac57a4b5401210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101419ff40c0af3e1f9bd992edf37118f709abc770458bb5f73e64a9068dd6aa2850000000000fdffffff0200e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf97310102401000000160014d6b971b45081c0582490c9f25fda175d1b259daa024730440220766457d5e220650cc2096f88c98008653d60bcff5819afba7da73258b9f29af8022035a7a8114c9c9049ddec62c8cd8667c1a9c001eb3c0e876c4018d9ad1c870c8801210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101a371d48b5af5147d8cf8f4489d626985d6420f851bda7e70ccded3f95566ccd90000000000fdffffff0200e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf973101024010000001600148685fceae319337a6699ef31db3d4491cf92d8fe0247304402206aa124c919ed0b528d63586f6d99c5e3967009eb1d3e1f9afac8060d3512b16c02202d704a606700a63a54dfc9a6ba4b4b00a0cbb4d9c3e0ef8a489d1d4123302d9701210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101f755809aaf681a5c0f7839f65813aa6fc171b2e5dcd87f35b13b49b5639016ae0000000000fdffffff027310102401000000160014dc3e3243ec881764f7f035964d76d8357e79b42b00e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90247304402206443a6518c03098a0bbd70c55da424db5a88a1a8cd80ef62ac82abc9b602008f02202ffba095af191735ca4c21b4ef47452e64444a33c02d0b03eb5a46dce698812b01210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc90000000200000000010177e24b23c538570850108445173cfba3c5baa6ee6af16f807e7f56b772bb29330000000000fdffffff027310102401000000160014b14bdfa016b84feaf1b05bd95e20c0068132b3c700e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90247304402202055189e7da96f886fd7c74a7b54b5c86ac43c6314d2fe632032cceb30a28d4902201561b8e26205aa1f511994e173d66faf0f9f7863a4e0871b0127f8995464c6a101210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc90000000200000000010132e54ea8502d51b05bca7f981c5ac0f3918dd02dc178206f36957e6daf2a81210000000000fdffffff027310102401000000160014003af378d78fa39853a9a1eb44f6eb9191e10e3500e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf902473044022009d2f74ba74478cb0448dae64c2556a201db593cecb3f8d3dc10e6de02c48c2702203cc1ca65ee946cc5f94124ea69e2d6e889023eb9420d5510758ef94d16a3b9d201210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc9000000020000000001012a391905e006fcba723d56c6a3eb27efa4396ede18f9c50e0be90dc1e928f1630000000000fdffffff0273101024010000001600148426ebef3d7b6a7387631e039f5d476d85d8a69300e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf902473044022040b80710239e68e217586fb076c08feb4a561ec2fac44c64ea95fad5b20832480220266c364a85ec127063f75ccf5a8315beaf27b68fe22c253eb354577754bc230a01210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc9000000020000000001018c3626fb538921b3f59786de9e6ca2487b3a1f5c80a3d9dd82c27a6b1a6eac5a0000000000fdffffff027310102401000000160014e5b0f788e3292352bf385cdfe9236227d906feed00e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf902473044022020ca43ccab85b1b847a25d4f51fd393bf4aa691b32e0fc80c91c3f893cb52b21022045de9177f9b686dc458411e5d1a8095e55c7251f55930f261c92c68374f5e9d401210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc9000000020000000001014d96fa8c632da473f2abcd001184d1812709ed52e9c2585308b28743ab7508e10000000000fdffffff0273101024010000001600142e6ce8b48bafa38443ac0a9a049c915a84d07a1d00e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf902473044022070429e86aea4db84db3c3eca4085efd777c36960bbd2f1be679db4f34a148ed3022068a0a3f902092661c0a5b42e7218b7719ec362b7dd48ad95b1c61c1072da858001210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101203d91dd647210a031046cfccd099edba94b5cb0203ab1e7c208158c1c04d7ee0000000000fdffffff0200e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf973101024010000001600142bb1130afbf9c9175db6e825ef21ff6ad967903a0247304402202f128ce7b6ee67bad85e4b1ff7bdc6dbd852dd0468073a0780d35e64e864ca9202203a50a4d0aabe6961696150e6dc2da7053c10a77b42b3dce93d1e168daa9a568d01210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101676a90f97480ef4e447335f1b9376c944381fb06d69b778a47248e5760dedf620000000000fdffffff027310102401000000160014ff27069bfa436a03f277a53da9ebe738cb4058d500e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf902473044022030cfaa5207e6d0a690ed5a2101a067c7e4d1b31f694886b427065c5c971d95a40220646cf63956dcc399c243ff6a207adfd34d4f2e409cd2ec4a48c531e214370c9901210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101295badc0bdd9a2bc0955d12f337491eae4c87ba4660078c0156310284d47c6ff0000000000fdffffff027310102401000000160014c34c2b12f2c5c3e3a061c5be9885e97be3d182ff00e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90247304402201de1a3579f63eacae93d919f6e7c6f388e33fe5228f7468a94070eae3908f1500220630a001126baa496362702eb675c1aa2244c5d6af2f3aadaca41eb09ef55b84001210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc900000002000000000101668688a5f4545d86d00bdebb0a007cafc530603c1fbb6d6a9f069a1d5f109fd00000000000fdffffff0200e1f505000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf97310102401000000160014a060ce2638c54cb65570779a62bd3d80a549967802473044022050d6d5b49102fb93cbb24fb53cf8e19e831a24f71b0877c3050ba2250020e89502201d6f37b61d60d1a0af32b5191887c1c56320cfc0d5bd9c064634a4fec810782e01210300d999684bd123d72074bf26bfaca11775eb371029bf714a60bdd4e976b1cc8fc9000000",
+"000000305e30a8502bdef4fae437335fd1e4cd0861689ba689d79397ec4e810ab28db2704c30745de8c0774b8f96087461dbd6efa19c1386bf15d1e7e305ebabd6c29cb177252d66ffff7f200200000001020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402cb0000ffffffff0200f90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000",
+"00000030e274856b9c7452ea644c991d4f3de0498178315356c2492574117b3df2eecf1cb53ff53c08d6d3ec10c0a948b9dd2b4aae96743fc5d6bf2b1254e4407daaa3175c0f2e66ffff7f200100000002020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402cc0000ffffffff028df90295000000001600141409745405c4e8310a875bcd602db6b9b3dc0cf90000000000000000266a24aa21a9ed2288e46fff34291c301c01e040e7bd468621d70a0078a11e422e616b70d51f4c012000000000000000000000000000000000000000000000000000000000000000000000000002000000000101087b234e0a26aa3265faaa7f7e507fbb01dc61381ded2547fdbefec295186c490100000000fdffffff02e62e1a1e01000000160014b0350ef1d06b91d681e33655611f4fce8b1f95e700e1f5050000000016001490d429043a6a97e1bb6775f702b677e21388a6a502473044022058d8b08b6c1dcf2d1593f8e2df011654b04009290744df42a81e263c1462b5dc02203f345708fb68d7c2c60db765cabb5ef9ad76b15e89212c23b9afa2b2f16ea58f01210225363b30257a7d3a27c4b03d312bc0568a263503107ebbd54b8d24c023c3dc2000000000",
+"0000003075d453e2fcdc9dd1dd0f1081b2e2fbd0400aae4b12412524a4ab6ced869e624a3b211101d7a99e85edd61cdd0a1ee167f2c5015e4296c692f50408c46b3156a356112e66ffff7f200000000004020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402cd0000ffffffff02a7fa029500000000160014eb82059311a807fc289d46a715ea4801608e56620000000000000000266a24aa21a9ed6152997cdf8a1f598b3b281f4c2371ff57f16adee387d2c6f9a1223294abbb860120000000000000000000000000000000000000000000000000000000000000000000000000020000000001010c8276e58415e63f76b5b9aee5dc13e36d2d86c5e6e96b668d9b029368ada71a0000000000fdffffff02594d241801000000160014657419c1c115140663bc9a3e5473704ae22aadeb00e1f50500000000160014cd0ba01721f6481d58acffb9c2c0558adacd9a81024730440220207cb42a792db108f61ab019695c2b5d19d6270046bd85497461c722753ca5f002206f83b571077cb6a683015ecd348eeb09536a6e61675a4062ee2775bc13ff4f6a012103fa84a8e735ee9ed2c56121406c3ab2a4b8c598a1d64ebf7ae8edaaaab8292638cc000000020000000001012c9e15682c8ee78bb37dfda591eafba313354b44dc36a96632623f43429a247e0000000000fdffffff02e62e1a1e01000000160014c975d60bc9d9edf51989e717ebe09cf140a3b19d00e1f505000000001600144c8af96210bc0e193e9b7d40353223485015e2b702473044022023a5dfb9afcb738ee1aca7c2b6893ced1cdf58bd8655b96c157fdea4a498be2702205a3bd361d9d2dc475ccac069f0775ea9dc6cdb630876a6cb79c67b28d550fb53012103fad0c0cdc5e4738ac2dc0d5f300a9d8fd095e1f2bb13291e6daa7cb6691b2780cc0000000200000000010113f36acf4eb116cd89b8709317d87c5a2daf00e5d6cf33c9eb0d9e3d290729ca0100000000fdffffff02e62e1a1e0100000016001479c3e84333847639f90325fd9a86de8dd40256a000e1f50500000000160014d149c03af86d5aa21213db620763ee7534c54ff60247304402201fd84faf54030f6e5df5b8b71f49b4e69dcc6856cd3ccd657f11481bf1a4fc8f022042d5b475f48d2e25a6ee206d7c8441493712d9d262d472c1df2c5b7c7fe9ffb1012102d0a810093c36ca0e815079ae76992d1bf5cf60573bec8b73572b20c89ebc9b45c1000000",
+"0000003055171be9b7f62e719a3d44daa56cf3a8903f66327b6854d57c6d6678d7b4e728c7c67566833f9b6109cb1a5eb50b811d1ae97a1f20c3912eb7d1c5fff72450092ac53866ffff7f200000000002020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402ce0000ffffffff02e8f9029500000000160014eb82059311a807fc289d46a715ea4801608e56620000000000000000266a24aa21a9edcb93aa8dfe2d28219d42caec8a367df5b1e1e4a1e2002bfdf439d83ca53dc08c012000000000000000000000000000000000000000000000000000000000000000000000000002000000000102bbbd77f0d8c5cbc2ccc39f0501828ad4ac3a6a933393876cae5a7e49bd5341230100000000fdffffff94e299c837e0e00644b9123d80c052159443907f663e746be7fe1e6c32c3ee9b0100000000fdffffff0218e0f50500000000225120d7bf24e13daf4d6ce0ac7a34ecefb4122f070a1561e8659d4071c52edb7c1cb300e1f505000000002251207ef15780916ae0f29a0bd34e48e1a0e817e7731b82f3009cfa89c87602cf1b2b02473044022014680d9a963868b03d25f84bd81af87e127f9d7990166dad5e1dd71be8797e3402205f79713b4faaff7184fb25d0976a37970f8d6b23f95d4041180a35aa291fc8dc012102a9dfaeeebad1f7ebca371a6f02e63a8b0de287c1b0608edc259c60583a03496e0247304402201f09ecdb89f311c3ad8b6d89a040a5796f83c9db2597962969392a3d9a5be46d022052243418a89831ca0e5ddd7ae575d787178126d8495f890414ab8b4d2a1b19d80121035368c752d3ee31d9570180a1ba285659af106f9430811ec58e3b86cf26c208f100000000",
+};
+#endif // BITCOIN_TEST_KERNEL_BLOCK_DATA_H
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 4b2dc5dc201..71325390457 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -8,6 +8,8 @@
 #define BOOST_TEST_MODULE Bitcoin Kernel Test Suite
 #include <boost/test/included/unit_test.hpp>
 
+#include <test/kernel/block_data.h>
+
 #include <charconv>
 #include <cstdint>
 #include <cstdlib>
@@ -470,6 +472,15 @@ BOOST_AUTO_TEST_CASE(btck_context_tests)
     }
 }
 
+BOOST_AUTO_TEST_CASE(btck_block)
+{
+    Block block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[0])};
+    Block block_1{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[1])};
+    CheckHandle(block, block_1);
+    Block block_tx{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[205])};
+    CheckRange(block_tx.Transactions(), block_tx.CountTransactions());
+}
+
 Context create_context(std::shared_ptr<TestKernelNotifications> notifications, ChainType chain_type)
 {
     ContextOptions options{};
@@ -505,3 +516,85 @@ BOOST_AUTO_TEST_CASE(btck_chainman_tests)
     chainman_opts.SetWorkerThreads(4);
     ChainMan chainman{context, chainman_opts};
 }
+
+std::unique_ptr<ChainMan> create_chainman(TestDirectory& test_directory,
+                                          Context& context)
+{
+    ChainstateManagerOptions chainman_opts{context, test_directory.m_directory.string(), (test_directory.m_directory / "blocks").string()};
+    auto chainman{std::make_unique<ChainMan>(context, chainman_opts)};
+    return chainman;
+}
+
+BOOST_AUTO_TEST_CASE(btck_chainman_mainnet_tests)
+{
+    auto mainnet_test_directory{TestDirectory{"mainnet_test_bitcoin_kernel"}};
+
+    auto notifications{std::make_shared<TestKernelNotifications>()};
+    auto context{create_context(notifications, ChainType::MAINNET)};
+    auto chainman{create_chainman(mainnet_test_directory, context)};
+
+    {
+        // Process an invalid block
+        auto raw_block = hex_string_to_byte_vec("012300");
+        BOOST_CHECK_THROW(Block{raw_block}, std::runtime_error);
+    }
+    {
+        // Process an empty block
+        auto raw_block = hex_string_to_byte_vec("");
+        BOOST_CHECK_THROW(Block{raw_block}, std::runtime_error);
+    }
+
+    // mainnet block 1
+    auto raw_block = hex_string_to_byte_vec("010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e362990101000000010000000000000000000000000000000000000000000000000000000000000000ffffffff0704ffff001d0104ffffffff0100f2052a0100000043410496b538e853519c726a2c91e61ec11600ae1390813a627c66fb8be7947be63c52da7589379515d4e0a604f8141781e62294721166bf621e73a82cbf2342c858eeac00000000");
+    Block block{raw_block};
+    TransactionView tx{block.GetTransaction(block.CountTransactions() - 1)};
+    BOOST_CHECK_EQUAL(tx.CountInputs(), 1);
+    Transaction tx2 = tx;
+    BOOST_CHECK_EQUAL(tx2.CountInputs(), 1);
+    for (auto transaction : block.Transactions()) {
+        BOOST_CHECK_EQUAL(transaction.CountInputs(), 1);
+    }
+    auto output_counts = *(block.Transactions() | std::views::transform([](const auto& tx) {
+                               return tx.CountOutputs();
+                           })).begin();
+    BOOST_CHECK_EQUAL(output_counts, 1);
+    bool new_block = false;
+    BOOST_CHECK(chainman->ProcessBlock(block, &new_block));
+    BOOST_CHECK(new_block);
+
+    // If we try to validate it again, it should be a duplicate
+    BOOST_CHECK(chainman->ProcessBlock(block, &new_block));
+    BOOST_CHECK(!new_block);
+}
+
+BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
+{
+    auto test_directory{TestDirectory{"regtest_test_bitcoin_kernel"}};
+
+    auto notifications{std::make_shared<TestKernelNotifications>()};
+    auto context{create_context(notifications, ChainType::REGTEST)};
+
+    // Validate 206 regtest blocks in total.
+    // Stop halfway to check that it is possible to continue validating starting
+    // from prior state.
+    const size_t mid{REGTEST_BLOCK_DATA.size() / 2};
+
+    {
+        auto chainman{create_chainman(test_directory, context)};
+        for (size_t i{0}; i < mid; i++) {
+            Block block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[i])};
+            bool new_block{false};
+            BOOST_CHECK(chainman->ProcessBlock(block, &new_block));
+            BOOST_CHECK(new_block);
+        }
+    }
+
+    auto chainman{create_chainman(test_directory, context)};
+
+    for (size_t i{mid}; i < REGTEST_BLOCK_DATA.size(); i++) {
+        Block block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[i])};
+        bool new_block{false};
+        BOOST_CHECK(chainman->ProcessBlock(block, &new_block));
+        BOOST_CHECK(new_block);
+    }
+}

From 070e77732cdb927cc27ddd39c52dec22c5d717a0 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Mon, 17 Jun 2024 22:50:47 +0200
Subject: [PATCH 10/23] kernel: Add options for reindexing in C header

Adds options for wiping the chainstate and block tree indexes to the
chainstate manager options. In combination and once the
`*_import_blocks(...)` function is added in a later commit, this
triggers a reindex. For now, it just wipes the existing data.
---
 src/kernel/bitcoinkernel.cpp       | 13 +++++++++
 src/kernel/bitcoinkernel.h         | 13 +++++++++
 src/kernel/bitcoinkernel_wrapper.h |  5 ++++
 src/test/kernel/test_kernel.cpp    | 46 ++++++++++++++++++++++++++----
 4 files changed, 71 insertions(+), 6 deletions(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 7a08b6c9008..23ae8128227 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -706,6 +706,19 @@ void btck_chainstate_manager_options_destroy(btck_ChainstateManagerOptions* opti
     delete options;
 }
 
+int btck_chainstate_manager_options_set_wipe_dbs(btck_ChainstateManagerOptions* chainman_opts, int wipe_block_tree_db, int wipe_chainstate_db)
+{
+    if (wipe_block_tree_db == 1 && wipe_chainstate_db != 1) {
+        LogError("Wiping the block tree db without also wiping the chainstate db is currently unsupported.");
+        return -1;
+    }
+    auto& opts{btck_ChainstateManagerOptions::get(chainman_opts)};
+    LOCK(opts.m_mutex);
+    opts.m_blockman_options.block_tree_db_params.wipe_data = wipe_block_tree_db == 1;
+    opts.m_chainstate_load_options.wipe_chainstate_db = wipe_chainstate_db == 1;
+    return 0;
+}
+
 btck_ChainstateManager* btck_chainstate_manager_create(
     const btck_ChainstateManagerOptions* chainman_opts)
 {
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 5486c823be3..49995960a17 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -746,6 +746,19 @@ 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.
+ *
+ * @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);
+
 /**
  * Destroy the chainstate manager options.
  */
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index f0af457d42a..15186bbdf39 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -665,6 +665,11 @@ public:
     {
         btck_chainstate_manager_options_set_worker_threads_num(get(), worker_threads);
     }
+
+    bool SetWipeDbs(bool wipe_block_tree, bool wipe_chainstate)
+    {
+        return btck_chainstate_manager_options_set_wipe_dbs(get(), wipe_block_tree, wipe_chainstate) == 0;
+    }
 };
 
 class ChainMan : UniqueHandle<btck_ChainstateManager, btck_chainstate_manager_destroy>
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 71325390457..38879f71bb7 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -514,24 +514,50 @@ BOOST_AUTO_TEST_CASE(btck_chainman_tests)
 
     ChainstateManagerOptions chainman_opts{context, test_directory.m_directory.string(), (test_directory.m_directory / "blocks").string()};
     chainman_opts.SetWorkerThreads(4);
+    BOOST_CHECK(!chainman_opts.SetWipeDbs(/*wipe_block_tree=*/true, /*wipe_chainstate=*/false));
+    BOOST_CHECK(chainman_opts.SetWipeDbs(/*wipe_block_tree=*/true, /*wipe_chainstate=*/true));
+    BOOST_CHECK(chainman_opts.SetWipeDbs(/*wipe_block_tree=*/false, /*wipe_chainstate=*/true));
+    BOOST_CHECK(chainman_opts.SetWipeDbs(/*wipe_block_tree=*/false, /*wipe_chainstate=*/false));
     ChainMan chainman{context, chainman_opts};
 }
 
 std::unique_ptr<ChainMan> create_chainman(TestDirectory& test_directory,
+                                          bool reindex,
+                                          bool wipe_chainstate,
                                           Context& context)
 {
     ChainstateManagerOptions chainman_opts{context, test_directory.m_directory.string(), (test_directory.m_directory / "blocks").string()};
+
+    if (reindex) {
+        chainman_opts.SetWipeDbs(/*wipe_block_tree=*/reindex, /*wipe_chainstate=*/reindex);
+    }
+    if (wipe_chainstate) {
+        chainman_opts.SetWipeDbs(/*wipe_block_tree=*/false, /*wipe_chainstate=*/wipe_chainstate);
+    }
+
     auto chainman{std::make_unique<ChainMan>(context, chainman_opts)};
     return chainman;
 }
 
-BOOST_AUTO_TEST_CASE(btck_chainman_mainnet_tests)
+void chainman_reindex_test(TestDirectory& test_directory)
 {
-    auto mainnet_test_directory{TestDirectory{"mainnet_test_bitcoin_kernel"}};
-
     auto notifications{std::make_shared<TestKernelNotifications>()};
     auto context{create_context(notifications, ChainType::MAINNET)};
-    auto chainman{create_chainman(mainnet_test_directory, context)};
+    auto chainman{create_chainman(test_directory, true, false, context)};
+}
+
+void chainman_reindex_chainstate_test(TestDirectory& test_directory)
+{
+    auto notifications{std::make_shared<TestKernelNotifications>()};
+    auto context{create_context(notifications, ChainType::MAINNET)};
+    auto chainman{create_chainman(test_directory, false, true, context)};
+}
+
+void chainman_mainnet_validation_test(TestDirectory& test_directory)
+{
+    auto notifications{std::make_shared<TestKernelNotifications>()};
+    auto context{create_context(notifications, ChainType::MAINNET)};
+    auto chainman{create_chainman(test_directory, false, false, context)};
 
     {
         // Process an invalid block
@@ -567,6 +593,14 @@ BOOST_AUTO_TEST_CASE(btck_chainman_mainnet_tests)
     BOOST_CHECK(!new_block);
 }
 
+BOOST_AUTO_TEST_CASE(btck_chainman_mainnet_tests)
+{
+    auto test_directory{TestDirectory{"mainnet_test_bitcoin_kernel"}};
+    chainman_mainnet_validation_test(test_directory);
+    chainman_reindex_test(test_directory);
+    chainman_reindex_chainstate_test(test_directory);
+}
+
 BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
 {
     auto test_directory{TestDirectory{"regtest_test_bitcoin_kernel"}};
@@ -580,7 +614,7 @@ BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
     const size_t mid{REGTEST_BLOCK_DATA.size() / 2};
 
     {
-        auto chainman{create_chainman(test_directory, context)};
+        auto chainman{create_chainman(test_directory, false, false, context)};
         for (size_t i{0}; i < mid; i++) {
             Block block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[i])};
             bool new_block{false};
@@ -589,7 +623,7 @@ BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
         }
     }
 
-    auto chainman{create_chainman(test_directory, context)};
+    auto chainman{create_chainman(test_directory, false, false, context)};
 
     for (size_t i{mid}; i < REGTEST_BLOCK_DATA.size(); i++) {
         Block block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[i])};

From a747ca1f516e7ec73758c6017e2eca5635ab2b74 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Sat, 22 Jun 2024 21:08:10 +0200
Subject: [PATCH 11/23] kernel: Add chainstate load options for in-memory dbs
 in C header

This allows a user to run the kernel without creating on-disk files for
the block tree and chainstate indexes. This is potentially useful in
scenarios where the user needs to do some ephemeral validation
operations.

One specific use case is when linearizing the blocks on disk. The block
files store blocks out of order, so a program may utilize the library
and its header to read the blocks with one chainstate manager, and then
write them back in order, and without orphans, with another chainstate
maanger. To save disk resources and if the indexes are not required once
done, it may be beneficial to keep the indexes in memory for the
chainstate manager that writes the blocks back again.
---
 src/kernel/bitcoinkernel.cpp       | 18 ++++++++++++++
 src/kernel/bitcoinkernel.h         | 20 ++++++++++++++++
 src/kernel/bitcoinkernel_wrapper.h | 10 ++++++++
 src/test/kernel/test_kernel.cpp    | 38 ++++++++++++++++++++++++++----
 4 files changed, 81 insertions(+), 5 deletions(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 23ae8128227..5203221d747 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -719,6 +719,24 @@ int btck_chainstate_manager_options_set_wipe_dbs(btck_ChainstateManagerOptions*
     return 0;
 }
 
+void btck_chainstate_manager_options_update_block_tree_db_in_memory(
+    btck_ChainstateManagerOptions* chainman_opts,
+    int block_tree_db_in_memory)
+{
+    auto& opts{btck_ChainstateManagerOptions::get(chainman_opts)};
+    LOCK(opts.m_mutex);
+    opts.m_blockman_options.block_tree_db_params.memory_only = block_tree_db_in_memory == 1;
+}
+
+void btck_chainstate_manager_options_update_chainstate_db_in_memory(
+    btck_ChainstateManagerOptions* chainman_opts,
+    int chainstate_db_in_memory)
+{
+    auto& opts{btck_ChainstateManagerOptions::get(chainman_opts)};
+    LOCK(opts.m_mutex);
+    opts.m_chainstate_load_options.coins_db_in_memory = chainstate_db_in_memory == 1;
+}
+
 btck_ChainstateManager* btck_chainstate_manager_create(
     const btck_ChainstateManagerOptions* chainman_opts)
 {
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 49995960a17..c7c51ae4d6b 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -759,6 +759,26 @@ BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_o
     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(
+    btck_ChainstateManagerOptions* chainstate_manager_options,
+    int chainstate_db_in_memory) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * Destroy the chainstate manager options.
  */
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index 15186bbdf39..c3b3e6905ee 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -670,6 +670,16 @@ public:
     {
         return btck_chainstate_manager_options_set_wipe_dbs(get(), wipe_block_tree, wipe_chainstate) == 0;
     }
+
+    void UpdateBlockTreeDbInMemory(bool block_tree_db_in_memory)
+    {
+        btck_chainstate_manager_options_update_block_tree_db_in_memory(get(), block_tree_db_in_memory);
+    }
+
+    void UpdateChainstateDbInMemory(bool chainstate_db_in_memory)
+    {
+        btck_chainstate_manager_options_update_chainstate_db_in_memory(get(), chainstate_db_in_memory);
+    }
 };
 
 class ChainMan : UniqueHandle<btck_ChainstateManager, btck_chainstate_manager_destroy>
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 38879f71bb7..553d68f502a 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -524,6 +524,8 @@ BOOST_AUTO_TEST_CASE(btck_chainman_tests)
 std::unique_ptr<ChainMan> create_chainman(TestDirectory& test_directory,
                                           bool reindex,
                                           bool wipe_chainstate,
+                                          bool block_tree_db_in_memory,
+                                          bool chainstate_db_in_memory,
                                           Context& context)
 {
     ChainstateManagerOptions chainman_opts{context, test_directory.m_directory.string(), (test_directory.m_directory / "blocks").string()};
@@ -534,6 +536,12 @@ std::unique_ptr<ChainMan> create_chainman(TestDirectory& test_directory,
     if (wipe_chainstate) {
         chainman_opts.SetWipeDbs(/*wipe_block_tree=*/false, /*wipe_chainstate=*/wipe_chainstate);
     }
+    if (block_tree_db_in_memory) {
+        chainman_opts.UpdateBlockTreeDbInMemory(block_tree_db_in_memory);
+    }
+    if (chainstate_db_in_memory) {
+        chainman_opts.UpdateChainstateDbInMemory(chainstate_db_in_memory);
+    }
 
     auto chainman{std::make_unique<ChainMan>(context, chainman_opts)};
     return chainman;
@@ -543,21 +551,21 @@ void chainman_reindex_test(TestDirectory& test_directory)
 {
     auto notifications{std::make_shared<TestKernelNotifications>()};
     auto context{create_context(notifications, ChainType::MAINNET)};
-    auto chainman{create_chainman(test_directory, true, false, context)};
+    auto chainman{create_chainman(test_directory, true, false, false, false, context)};
 }
 
 void chainman_reindex_chainstate_test(TestDirectory& test_directory)
 {
     auto notifications{std::make_shared<TestKernelNotifications>()};
     auto context{create_context(notifications, ChainType::MAINNET)};
-    auto chainman{create_chainman(test_directory, false, true, context)};
+    auto chainman{create_chainman(test_directory, false, true, false, false, context)};
 }
 
 void chainman_mainnet_validation_test(TestDirectory& test_directory)
 {
     auto notifications{std::make_shared<TestKernelNotifications>()};
     auto context{create_context(notifications, ChainType::MAINNET)};
-    auto chainman{create_chainman(test_directory, false, false, context)};
+    auto chainman{create_chainman(test_directory, false, false, false, false, context)};
 
     {
         // Process an invalid block
@@ -601,6 +609,26 @@ BOOST_AUTO_TEST_CASE(btck_chainman_mainnet_tests)
     chainman_reindex_chainstate_test(test_directory);
 }
 
+BOOST_AUTO_TEST_CASE(btck_chainman_in_memory_tests)
+{
+    auto in_memory_test_directory{TestDirectory{"in-memory_test_bitcoin_kernel"}};
+
+    auto notifications{std::make_shared<TestKernelNotifications>()};
+    auto context{create_context(notifications, ChainType::REGTEST)};
+    auto chainman{create_chainman(in_memory_test_directory, false, false, true, true, context)};
+
+    for (auto& raw_block : REGTEST_BLOCK_DATA) {
+        Block block{hex_string_to_byte_vec(raw_block)};
+        bool new_block{false};
+        chainman->ProcessBlock(block, &new_block);
+        BOOST_CHECK(new_block);
+    }
+
+    BOOST_CHECK(std::filesystem::exists(in_memory_test_directory.m_directory / "blocks"));
+    BOOST_CHECK(!std::filesystem::exists(in_memory_test_directory.m_directory / "blocks" / "index"));
+    BOOST_CHECK(!std::filesystem::exists(in_memory_test_directory.m_directory / "chainstate"));
+}
+
 BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
 {
     auto test_directory{TestDirectory{"regtest_test_bitcoin_kernel"}};
@@ -614,7 +642,7 @@ BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
     const size_t mid{REGTEST_BLOCK_DATA.size() / 2};
 
     {
-        auto chainman{create_chainman(test_directory, false, false, context)};
+        auto chainman{create_chainman(test_directory, false, false, false, false, context)};
         for (size_t i{0}; i < mid; i++) {
             Block block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[i])};
             bool new_block{false};
@@ -623,7 +651,7 @@ BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
         }
     }
 
-    auto chainman{create_chainman(test_directory, false, false, context)};
+    auto chainman{create_chainman(test_directory, false, false, false, false, context)};
 
     for (size_t i{mid}; i < REGTEST_BLOCK_DATA.size(); i++) {
         Block block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[i])};

From 1976b13be9c87baa1229b1573bdc8a1da562db0d Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Thu, 30 May 2024 11:22:28 +0200
Subject: [PATCH 12/23] kernel: Add import blocks function to C header

Add `btck_import_blocks` to import block data and rebuild indexes. The
function can either reindex all existing block files if the indexes were
previously wiped through the chainstate manager options, or import
blocks from specified file paths.
---
 src/kernel/bitcoinkernel.cpp       | 18 ++++++++++++++++++
 src/kernel/bitcoinkernel.h         | 20 +++++++++++++++++++-
 src/kernel/bitcoinkernel_wrapper.h | 14 ++++++++++++++
 src/test/kernel/test_kernel.cpp    |  7 +++++++
 4 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 5203221d747..0c5d811db08 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -795,6 +795,24 @@ void btck_chainstate_manager_destroy(btck_ChainstateManager* chainman)
     delete chainman;
 }
 
+int btck_chainstate_manager_import_blocks(btck_ChainstateManager* chainman, const char** block_file_paths_data, size_t* block_file_paths_lens, size_t block_file_paths_data_len)
+{
+    try {
+        std::vector<fs::path> import_files;
+        import_files.reserve(block_file_paths_data_len);
+        for (uint32_t i = 0; i < block_file_paths_data_len; i++) {
+            if (block_file_paths_data[i] != nullptr) {
+                import_files.emplace_back(std::string{block_file_paths_data[i], block_file_paths_lens[i]}.c_str());
+            }
+        }
+        node::ImportBlocks(*btck_ChainstateManager::get(chainman).m_chainman, import_files);
+    } catch (const std::exception& e) {
+        LogError("Failed to import blocks: %s", e.what());
+        return -1;
+    }
+    return 0;
+}
+
 btck_Block* btck_block_create(const void* raw_block, size_t raw_block_length)
 {
     auto block{std::make_shared<CBlock>()};
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index c7c51ae4d6b..651c54c48f1 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -747,7 +747,9 @@ BITCOINKERNEL_API void btck_chainstate_manager_options_set_worker_threads_num(
     int worker_threads) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
- * @brief Sets wipe db in the options.
+ * @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.
@@ -802,6 +804,22 @@ BITCOINKERNEL_API void btck_chainstate_manager_options_destroy(btck_ChainstateMa
 BITCOINKERNEL_API btck_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_create(
     const btck_ChainstateManagerOptions* chainstate_manager_options) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @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.
+ *
+ * @param[in] chainstate_manager        Non-null.
+ * @param[in] block_file_paths_data     Nullable, array of block files described by their full filesystem paths.
+ * @param[in] block_file_paths_lens     Nullable, array containing the lengths of each of the paths.
+ * @param[in] block_file_paths_data_len Length of the block_file_paths_data and block_file_paths_len arrays.
+ * @return                              0 if the import blocks call was completed successfully, non-zero otherwise.
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_import_blocks(
+    btck_ChainstateManager* chainstate_manager,
+    const char** block_file_paths_data, size_t* block_file_paths_lens,
+    size_t block_file_paths_data_len) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * @brief Process and validate the passed in block with the chainstate
  * manager. Processing first does checks on the block, and if these passed,
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index c3b3e6905ee..ff16f5bc042 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -690,6 +690,20 @@ public:
     {
     }
 
+    bool ImportBlocks(const std::span<const std::string> paths)
+    {
+        std::vector<const char*> c_paths;
+        std::vector<size_t> c_paths_lens;
+        c_paths.reserve(paths.size());
+        c_paths_lens.reserve(paths.size());
+        for (const auto& path : paths) {
+            c_paths.push_back(path.c_str());
+            c_paths_lens.push_back(path.length());
+        }
+
+        return btck_chainstate_manager_import_blocks(get(), c_paths.data(), c_paths_lens.data(), c_paths.size()) == 0;
+    }
+
     bool ProcessBlock(const Block& block, bool* new_block)
     {
         int _new_block;
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 553d68f502a..128f3f49fb5 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -552,6 +552,9 @@ void chainman_reindex_test(TestDirectory& test_directory)
     auto notifications{std::make_shared<TestKernelNotifications>()};
     auto context{create_context(notifications, ChainType::MAINNET)};
     auto chainman{create_chainman(test_directory, true, false, false, false, context)};
+
+    std::vector<std::string> import_files;
+    BOOST_CHECK(chainman->ImportBlocks(import_files));
 }
 
 void chainman_reindex_chainstate_test(TestDirectory& test_directory)
@@ -559,6 +562,10 @@ void chainman_reindex_chainstate_test(TestDirectory& test_directory)
     auto notifications{std::make_shared<TestKernelNotifications>()};
     auto context{create_context(notifications, ChainType::MAINNET)};
     auto chainman{create_chainman(test_directory, false, true, false, false, context)};
+
+    std::vector<std::string> import_files;
+    import_files.push_back((test_directory.m_directory / "blocks" / "blk00000.dat").string());
+    BOOST_CHECK(chainman->ImportBlocks(import_files));
 }
 
 void chainman_mainnet_validation_test(TestDirectory& test_directory)

From d27e27758d51bc2aa125dc967691aacc4f3811d3 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Wed, 5 Jun 2024 10:20:40 +0200
Subject: [PATCH 13/23] kernel: Add interrupt function to C header

Calling interrupt can halt long-running functions associated with
objects that were created through the passed-in context.
---
 src/kernel/bitcoinkernel.cpp       |  5 +++++
 src/kernel/bitcoinkernel.h         | 10 ++++++++++
 src/kernel/bitcoinkernel_wrapper.h |  5 +++++
 src/test/kernel/test_kernel.cpp    |  2 ++
 4 files changed, 22 insertions(+)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 0c5d811db08..1c146df0cb0 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -676,6 +676,11 @@ btck_Context* btck_context_copy(const btck_Context* context)
     return btck_Context::copy(context);
 }
 
+int btck_context_interrupt(btck_Context* context)
+{
+    return (*btck_Context::get(context)->m_interrupt)() ? 0 : -1;
+}
+
 void btck_context_destroy(btck_Context* context)
 {
     delete context;
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 651c54c48f1..8d7b2898251 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -704,6 +704,16 @@ BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_cr
 BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_copy(
     const btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Interrupt can be used to halt long-running validation functions like
+ * when reindexing, importing or processing blocks.
+ *
+ * @param[in] context  Non-null.
+ * @return             0 if the interrupt was successful, non-zero otherwise.
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_interrupt(
+    btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * Destroy the context.
  */
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index ff16f5bc042..4c378d3a8fa 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -651,6 +651,11 @@ public:
 
     Context()
         : Handle{btck_context_create(ContextOptions{}.get())} {}
+
+    bool interrupt()
+    {
+        return btck_context_interrupt(get()) == 0;
+    }
 };
 
 class ChainstateManagerOptions : public UniqueHandle<btck_ChainstateManagerOptions, btck_chainstate_manager_options_destroy>
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 128f3f49fb5..cfe3b2d2d4a 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -634,6 +634,8 @@ BOOST_AUTO_TEST_CASE(btck_chainman_in_memory_tests)
     BOOST_CHECK(std::filesystem::exists(in_memory_test_directory.m_directory / "blocks"));
     BOOST_CHECK(!std::filesystem::exists(in_memory_test_directory.m_directory / "blocks" / "index"));
     BOOST_CHECK(!std::filesystem::exists(in_memory_test_directory.m_directory / "chainstate"));
+
+    BOOST_CHECK(context.interrupt());
 }
 
 BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)

From aa262da7bcfa9bf3d0105e6f689eae7c6e95a0e5 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Thu, 30 May 2024 22:59:48 +0200
Subject: [PATCH 14/23] kernel: Add validation interface to C header

This adds the infrastructure required to process validation events. For
now the external validation interface only has support for the
`BlockChecked` , `NewPoWValidBlock`, `BlockConnected`, and
`BlockDisconnected` callback. Support for the other internal
validation interface methods can be added in the future.

The validation interface follows an architecture for defining its
callbacks and ownership that is similar to the notifications.

The task runner is created internally with a context, which itself
internally creates a unique ValidationSignals object. When the user
creates a new chainstate manager the validation signals are internally
passed to the chainstate manager through the context.

A validation interface can register for validation events with a
context. Internally the passed in validation interface is registerd with
the validation signals of a context.

The callbacks block any further validation execution when they are
called. It is up to the user to either multiplex them, or use them
otherwise in a multithreaded mechanism to make processing the validation
events non-blocking.

I.e. for a synchronous mechanism, the user executes instructions
directly at the end of the callback function:

```mermaid
sequenceDiagram
    participant V as Validation
    participant C as Callback
    V->>C: Call callback
    Note over C: Process event (blocks)
    C-->>V: Return
    Note over V: Validation resumes

```

To avoid blocking, the user can submit the data to e.g. a worker thread
or event manager, so processing happens asynchronously:

```mermaid
sequenceDiagram
    participant V as Validation
    participant C as Callback
    participant W as Worker Thread
    V->>C: Call callback
    C->>W: Submit to worker thread
    C-->>V: Return immediately
    Note over V: Validation continues
    Note over W: Process event async
```
---
 src/kernel/bitcoinkernel.cpp       | 85 +++++++++++++++++++++++++++++-
 src/kernel/bitcoinkernel.h         | 60 ++++++++++++++++++++-
 src/kernel/bitcoinkernel_wrapper.h | 46 ++++++++++++++++
 src/test/kernel/test_kernel.cpp    | 32 ++++++++++-
 4 files changed, 219 insertions(+), 4 deletions(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 1c146df0cb0..9c96a1c4900 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -31,8 +31,10 @@
 #include <util/fs.h>
 #include <util/result.h>
 #include <util/signalinterrupt.h>
+#include <util/task_runner.h>
 #include <util/translation.h>
 #include <validation.h>
+#include <validationinterface.h>
 
 #include <cassert>
 #include <cstddef>
@@ -47,6 +49,8 @@
 #include <utility>
 #include <vector>
 
+using util::ImmediateTaskRunner;
+
 // Define G_TRANSLATION_FUN symbol in libbitcoinkernel library so users of the
 // library aren't required to export this symbol
 extern const std::function<std::string(const char*)> G_TRANSLATION_FUN{nullptr};
@@ -135,6 +139,7 @@ struct Handle {
 
 struct btck_BlockTreeEntry: Handle<btck_BlockTreeEntry, CBlockIndex> {};
 struct btck_Block : Handle<btck_Block, std::shared_ptr<const CBlock>> {};
+struct btck_BlockValidationState : Handle<btck_BlockValidationState, BlockValidationState> {};
 
 namespace {
 
@@ -317,10 +322,65 @@ public:
     }
 };
 
+class KernelValidationInterface final : public CValidationInterface
+{
+public:
+    btck_ValidationInterfaceCallbacks m_cbs;
+
+    explicit KernelValidationInterface(const btck_ValidationInterfaceCallbacks vi_cbs) : m_cbs{vi_cbs} {}
+
+    ~KernelValidationInterface()
+    {
+        if (m_cbs.user_data && m_cbs.user_data_destroy) {
+            m_cbs.user_data_destroy(m_cbs.user_data);
+        }
+        m_cbs.user_data = nullptr;
+        m_cbs.user_data_destroy = nullptr;
+    }
+
+protected:
+    void BlockChecked(const std::shared_ptr<const CBlock>& block, const BlockValidationState& stateIn) override
+    {
+        if (m_cbs.block_checked) {
+            m_cbs.block_checked(m_cbs.user_data,
+                                btck_Block::copy(btck_Block::ref(&block)),
+                                btck_BlockValidationState::ref(&stateIn));
+        }
+    }
+
+    void NewPoWValidBlock(const CBlockIndex* pindex, const std::shared_ptr<const CBlock>& block) override
+    {
+        if (m_cbs.pow_valid_block) {
+            m_cbs.pow_valid_block(m_cbs.user_data,
+                                  btck_Block::copy(btck_Block::ref(&block)),
+                                  btck_BlockTreeEntry::ref(pindex));
+        }
+    }
+
+    void BlockConnected(ChainstateRole role, const std::shared_ptr<const CBlock>& block, const CBlockIndex* pindex) override
+    {
+        if (m_cbs.block_connected) {
+            m_cbs.block_connected(m_cbs.user_data,
+                                  btck_Block::copy(btck_Block::ref(&block)),
+                                  btck_BlockTreeEntry::ref(pindex));
+        }
+    }
+
+    void BlockDisconnected(const std::shared_ptr<const CBlock>& block, const CBlockIndex* pindex) override
+    {
+        if (m_cbs.block_disconnected) {
+            m_cbs.block_disconnected(m_cbs.user_data,
+                                     btck_Block::copy(btck_Block::ref(&block)),
+                                     btck_BlockTreeEntry::ref(pindex));
+        }
+    }
+};
+
 struct ContextOptions {
     mutable Mutex m_mutex;
     std::unique_ptr<const CChainParams> m_chainparams GUARDED_BY(m_mutex);
     std::shared_ptr<KernelNotifications> m_notifications GUARDED_BY(m_mutex);
+    std::shared_ptr<KernelValidationInterface> m_validation_interface GUARDED_BY(m_mutex);
 };
 
 class Context
@@ -332,8 +392,12 @@ public:
 
     std::unique_ptr<util::SignalInterrupt> m_interrupt;
 
+    std::unique_ptr<ValidationSignals> m_signals;
+
     std::unique_ptr<const CChainParams> m_chainparams;
 
+    std::shared_ptr<KernelValidationInterface> m_validation_interface;
+
     Context(const ContextOptions* options, bool& sane)
         : m_context{std::make_unique<kernel::Context>()},
           m_interrupt{std::make_unique<util::SignalInterrupt>()}
@@ -346,6 +410,11 @@ public:
             if (options->m_notifications) {
                 m_notifications = options->m_notifications;
             }
+            if (options->m_validation_interface) {
+                m_signals = std::make_unique<ValidationSignals>(std::make_unique<ImmediateTaskRunner>());
+                m_validation_interface = options->m_validation_interface;
+                m_signals->RegisterSharedValidationInterface(m_validation_interface);
+            }
         }
 
         if (!m_chainparams) {
@@ -360,6 +429,13 @@ public:
             sane = false;
         }
     }
+
+    ~Context()
+    {
+        if (m_signals) {
+            m_signals->UnregisterSharedValidationInterface(m_validation_interface);
+        }
+    }
 };
 
 //! Helper struct to wrap the ChainstateManager-related Options
@@ -374,7 +450,8 @@ struct ChainstateManagerOptions {
         : m_chainman_options{ChainstateManager::Options{
               .chainparams = *context->m_chainparams,
               .datadir = data_dir,
-              .notifications = *context->m_notifications}},
+              .notifications = *context->m_notifications,
+              .signals = context->m_signals.get()}},
           m_blockman_options{node::BlockManager::Options{
               .chainparams = *context->m_chainparams,
               .blocks_dir = blocks_dir,
@@ -654,6 +731,12 @@ void btck_context_options_set_notifications(btck_ContextOptions* options, btck_N
     btck_ContextOptions::get(options).m_notifications = std::make_shared<KernelNotifications>(notifications);
 }
 
+void btck_context_options_set_validation_interface(btck_ContextOptions* options, btck_ValidationInterfaceCallbacks vi_cbs)
+{
+    LOCK(btck_ContextOptions::get(options).m_mutex);
+    btck_ContextOptions::get(options).m_validation_interface = std::make_shared<KernelValidationInterface>(vi_cbs);
+}
+
 void btck_context_options_destroy(btck_ContextOptions* options)
 {
     delete options;
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 8d7b2898251..b41ff90e744 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -67,6 +67,9 @@ extern "C" {
  * functions, e.g. for scripts, may communicate more detailed error information
  * through status code out parameters.
  *
+ * Fine-grained validation information is communicated through the validation
+ * interface.
+ *
  * The kernel notifications issue callbacks for errors. These are usually
  * indicative of a system error. If such an error is issued, it is recommended
  * to halt and tear down the existing kernel objects. Remediating the error may
@@ -149,6 +152,10 @@ typedef struct btck_ContextOptions btck_ContextOptions;
  * other validation objects are instantiated from it, the context is kept in
  * memory for the duration of their lifetimes.
  *
+ * The processing of validation events is done through an internal task runner
+ * owned by the context. It passes events through the registered validation
+ * interface callbacks.
+ *
  * A constructed context can be safely used from multiple threads.
  */
 typedef struct btck_Context btck_Context;
@@ -191,6 +198,14 @@ typedef struct btck_ChainstateManager btck_ChainstateManager;
  */
 typedef struct btck_Block btck_Block;
 
+/**
+ * Opaque data structure for holding the state of a block during validation.
+ *
+ * Contains information indicating whether validation was successful, and if not
+ * which step during block validation failed.
+ */
+typedef struct btck_BlockValidationState btck_BlockValidationState;
+
 /** Current sync state passed to tip changed callbacks. */
 typedef uint8_t btck_SynchronizationState;
 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
@@ -226,6 +241,33 @@ typedef void (*btck_NotifyWarningUnset)(void* user_data, btck_Warning warning);
 typedef void (*btck_NotifyFlushError)(void* user_data, const char* message, size_t message_len);
 typedef void (*btck_NotifyFatalError)(void* user_data, const char* message, size_t message_len);
 
+/**
+ * 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, 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);
+
+/**
+ * Holds the validation interface callbacks. The user data pointer may be used
+ * to point to user-defined structures to make processing the validation
+ * callbacks easier. Note that these callbacks block any further validation
+ * execution when they are called.
+ */
+typedef struct {
+    void* user_data;                                              //!< Holds a user-defined opaque structure that is passed to the validation
+                                                                  //!< interface callbacks. If user_data_destroy is also defined ownership of the
+                                                                  //!< user_data is passed to the created context options and subsequently context.
+    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
+                                                                  //!< 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.
+} btck_ValidationInterfaceCallbacks;
+
 /**
  * A struct for holding the kernel notification callbacks. The user data
  * pointer may be used to point to user-defined structures to make processing
@@ -674,6 +716,20 @@ BITCOINKERNEL_API void btck_context_options_set_notifications(
     btck_ContextOptions* context_options,
     btck_NotificationInterfaceCallbacks notifications) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Set the validation interface callbacks for the context options. The
+ * context created with the options will be configured for these validation
+ * interface callbacks. The callbacks will then be triggered from validation
+ * events issued by the chainstate manager created from the same context.
+ *
+ * @param[in] context_options                Non-null, previously created with btck_context_options_create.
+ * @param[in] validation_interface_callbacks The callbacks used for passing validation information to the
+ *                                           user.
+ */
+BITCOINKERNEL_API void btck_context_options_set_validation_interface(
+    btck_ContextOptions* context_options,
+    btck_ValidationInterfaceCallbacks validation_interface_callbacks) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * Destroy the context options.
  */
@@ -835,7 +891,9 @@ BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_i
  * manager. Processing first does checks on the block, and if these passed,
  * saves it to disk. It then validates the block against the utxo set. If it is
  * valid, the chain is extended with it. The return value is not indicative of
- * the block's validity.
+ * the block's validity. Detailed information on the validity of the block can
+ * be retrieved by registering the `block_checked` callback in the validation
+ * interface.
  *
  * @param[in] chainstate_manager Non-null.
  * @param[in] block              Non-null, block to be validated.
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index 4c378d3a8fa..7105f9e95d6 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -604,6 +604,34 @@ public:
     virtual void FatalErrorHandler(std::string_view error) {}
 };
 
+class BlockValidationState
+{
+private:
+    const btck_BlockValidationState* m_state;
+
+public:
+    BlockValidationState(const btck_BlockValidationState* state) : m_state{state} {}
+
+    BlockValidationState(const BlockValidationState&) = delete;
+    BlockValidationState& operator=(const BlockValidationState&) = delete;
+    BlockValidationState(BlockValidationState&&) = delete;
+    BlockValidationState& operator=(BlockValidationState&&) = delete;
+};
+
+class ValidationInterface
+{
+public:
+    virtual ~ValidationInterface() = default;
+
+    virtual void BlockChecked(Block block, const BlockValidationState state) {}
+
+    virtual void PowValidBlock(BlockTreeEntry entry, Block block) {}
+
+    virtual void BlockConnected(Block block, BlockTreeEntry entry) {}
+
+    virtual void BlockDisconnected(Block block, BlockTreeEntry entry) {}
+};
+
 class ChainParams : public Handle<btck_ChainParameters, btck_chain_parameters_copy, btck_chain_parameters_destroy>
 {
 public:
@@ -641,6 +669,24 @@ public:
                 .fatal_error = +[](void* user_data, const char* error, size_t error_len) { (*static_cast<user_type>(user_data))->FatalErrorHandler({error, error_len}); },
             });
     }
+
+    template <typename T>
+    void SetValidationInterface(std::shared_ptr<T> validation_interface)
+    {
+        static_assert(std::is_base_of_v<ValidationInterface, T>);
+        auto heap_vi = std::make_unique<std::shared_ptr<T>>(std::move(validation_interface));
+        using user_type = std::shared_ptr<T>*;
+        btck_context_options_set_validation_interface(
+            get(),
+            btck_ValidationInterfaceCallbacks{
+                .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, 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}); },
+            });
+    }
 };
 
 class Context : public Handle<btck_Context, btck_context_copy, btck_context_destroy>
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index cfe3b2d2d4a..4cf3df7f57e 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -126,6 +126,30 @@ public:
     }
 };
 
+class TestValidationInterface : public ValidationInterface
+{
+public:
+    void BlockChecked(Block block, const BlockValidationState state) override
+    {
+        std::cout << "Block checked." << std::endl;
+    }
+
+    void BlockConnected(Block block, BlockTreeEntry entry) override
+    {
+        std::cout << "Block connected." << std::endl;
+    }
+
+    void PowValidBlock(BlockTreeEntry entry, Block block) override
+    {
+        std::cout << "Block passed pow verification" << std::endl;
+    }
+
+    void BlockDisconnected(Block block, BlockTreeEntry entry) override
+    {
+        std::cout << "Block disconnected." << std::endl;
+    }
+};
+
 void run_verify_test(
     const ScriptPubkey& spent_script_pubkey,
     const Transaction& spending_tx,
@@ -481,12 +505,15 @@ BOOST_AUTO_TEST_CASE(btck_block)
     CheckRange(block_tx.Transactions(), block_tx.CountTransactions());
 }
 
-Context create_context(std::shared_ptr<TestKernelNotifications> notifications, ChainType chain_type)
+Context create_context(std::shared_ptr<TestKernelNotifications> notifications, ChainType chain_type, std::shared_ptr<TestValidationInterface> validation_interface = nullptr)
 {
     ContextOptions options{};
     ChainParams params{chain_type};
     options.SetChainParams(params);
     options.SetNotifications(notifications);
+    if (validation_interface) {
+        options.SetValidationInterface(validation_interface);
+    }
     auto context{Context{options}};
     return context;
 }
@@ -571,7 +598,8 @@ void chainman_reindex_chainstate_test(TestDirectory& test_directory)
 void chainman_mainnet_validation_test(TestDirectory& test_directory)
 {
     auto notifications{std::make_shared<TestKernelNotifications>()};
-    auto context{create_context(notifications, ChainType::MAINNET)};
+    auto validation_interface{std::make_shared<TestValidationInterface>()};
+    auto context{create_context(notifications, ChainType::MAINNET, validation_interface)};
     auto chainman{create_chainman(test_directory, false, false, false, false, context)};
 
     {

From b30e15f4329ab0ee6bb5c4c1d1f6067be364c59e Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Fri, 31 May 2024 13:34:00 +0200
Subject: [PATCH 15/23] kernel: Add functions for the block validation state to
 C header

These allow for the interpretation of the data in a `BlockChecked`
validation interface callback. The validation state passed through
`BlockChecked` is the source of truth for the validity of a block (the
mode). It is
also useful to get richer information in case a block failed to
validate (the result).
---
 src/kernel/bitcoinkernel.cpp       | 34 +++++++++++++++++++++
 src/kernel/bitcoinkernel.h         | 42 ++++++++++++++++++++++++++
 src/kernel/bitcoinkernel_wrapper.h | 28 +++++++++++++++++
 src/test/kernel/test_kernel.cpp    | 48 +++++++++++++++++++++++++++++-
 4 files changed, 151 insertions(+), 1 deletion(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 9c96a1c4900..e115518df81 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -769,6 +769,40 @@ void btck_context_destroy(btck_Context* context)
     delete context;
 }
 
+btck_ValidationMode btck_block_validation_state_get_validation_mode(const btck_BlockValidationState* block_validation_state_)
+{
+    auto& block_validation_state = btck_BlockValidationState::get(block_validation_state_);
+    if (block_validation_state.IsValid()) return btck_ValidationMode_VALID;
+    if (block_validation_state.IsInvalid()) return btck_ValidationMode_INVALID;
+    return btck_ValidationMode_INTERNAL_ERROR;
+}
+
+btck_BlockValidationResult btck_block_validation_state_get_block_validation_result(const btck_BlockValidationState* block_validation_state_)
+{
+    auto& block_validation_state = btck_BlockValidationState::get(block_validation_state_);
+    switch (block_validation_state.GetResult()) {
+    case BlockValidationResult::BLOCK_RESULT_UNSET:
+        return btck_BlockValidationResult_UNSET;
+    case BlockValidationResult::BLOCK_CONSENSUS:
+        return btck_BlockValidationResult_CONSENSUS;
+    case BlockValidationResult::BLOCK_CACHED_INVALID:
+        return btck_BlockValidationResult_CACHED_INVALID;
+    case BlockValidationResult::BLOCK_INVALID_HEADER:
+        return btck_BlockValidationResult_INVALID_HEADER;
+    case BlockValidationResult::BLOCK_MUTATED:
+        return btck_BlockValidationResult_MUTATED;
+    case BlockValidationResult::BLOCK_MISSING_PREV:
+        return btck_BlockValidationResult_MISSING_PREV;
+    case BlockValidationResult::BLOCK_INVALID_PREV:
+        return btck_BlockValidationResult_INVALID_PREV;
+    case BlockValidationResult::BLOCK_TIME_FUTURE:
+        return btck_BlockValidationResult_TIME_FUTURE;
+    case BlockValidationResult::BLOCK_HEADER_LOW_WORK:
+        return btck_BlockValidationResult_HEADER_LOW_WORK;
+    } // no default case, so the compiler can warn about missing cases
+    assert(false);
+}
+
 btck_ChainstateManagerOptions* btck_chainstate_manager_options_create(const btck_Context* context, const char* data_dir, size_t data_dir_len, const char* blocks_dir, size_t blocks_dir_len)
 {
     try {
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index b41ff90e744..e1f99b53151 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -249,6 +249,29 @@ typedef void (*btck_ValidationInterfacePoWValidBlock)(void* user_data, btck_Bloc
 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);
 
+/**
+ * Whether a validated data structure is valid, invalid, or an error was
+ * encountered during processing.
+ */
+typedef uint8_t btck_ValidationMode;
+#define btck_ValidationMode_VALID ((btck_ValidationMode)(0))
+#define btck_ValidationMode_INVALID ((btck_ValidationMode)(1))
+#define btck_ValidationMode_INTERNAL_ERROR ((btck_ValidationMode)(2))
+
+/**
+ * A granular "reason" why a block was invalid.
+ */
+typedef uint32_t btck_BlockValidationResult;
+#define btck_BlockValidationResult_UNSET ((btck_BlockValidationResult)(0))           //!< initial value. Block has not yet been rejected
+#define btck_BlockValidationResult_CONSENSUS ((btck_BlockValidationResult)(1))       //!< invalid by consensus rules (excluding any below reasons)
+#define btck_BlockValidationResult_CACHED_INVALID ((btck_BlockValidationResult)(2))  //!< this block was cached as being invalid and we didn't store the reason why
+#define btck_BlockValidationResult_INVALID_HEADER ((btck_BlockValidationResult)(3))  //!< invalid proof of work or time too old
+#define btck_BlockValidationResult_MUTATED ((btck_BlockValidationResult)(4))         //!< the block's data didn't match the data committed to by the PoW
+#define btck_BlockValidationResult_MISSING_PREV ((btck_BlockValidationResult)(5))    //!< We don't have the previous block the checked one is built on
+#define btck_BlockValidationResult_INVALID_PREV ((btck_BlockValidationResult)(6))    //!< A block this one builds on is invalid
+#define btck_BlockValidationResult_TIME_FUTURE ((btck_BlockValidationResult)(7))     //!< block timestamp was > 2 hours in the future (or our clock is bad)
+#define btck_BlockValidationResult_HEADER_LOW_WORK ((btck_BlockValidationResult)(8)) //!< the block header may be on a too-little-work chain
+
 /**
  * Holds the validation interface callbacks. The user data pointer may be used
  * to point to user-defined structures to make processing the validation
@@ -967,6 +990,25 @@ BITCOINKERNEL_API void btck_block_destroy(btck_Block* block);
 
 ///@}
 
+/** @name BlockValidationState
+ * Functions for working with block validation states.
+ */
+///@{
+
+/**
+ * Returns the validation mode from an opaque block validation state pointer.
+ */
+BITCOINKERNEL_API btck_ValidationMode btck_block_validation_state_get_validation_mode(
+    const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Returns the validation result from an opaque block validation state pointer.
+ */
+BITCOINKERNEL_API btck_BlockValidationResult btck_block_validation_state_get_block_validation_result(
+    const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);
+
+///@}
+
 #ifdef __cplusplus
 } // extern "C"
 #endif // __cplusplus
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index 7105f9e95d6..249f98a3684 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -58,6 +58,24 @@ enum class Warning : btck_Warning {
     LARGE_WORK_INVALID_CHAIN = btck_Warning_LARGE_WORK_INVALID_CHAIN
 };
 
+enum class ValidationMode : btck_ValidationMode {
+    VALID = btck_ValidationMode_VALID,
+    INVALID = btck_ValidationMode_INVALID,
+    INTERNAL_ERROR = btck_ValidationMode_INTERNAL_ERROR
+};
+
+enum class BlockValidationResult : btck_BlockValidationResult {
+    UNSET = btck_BlockValidationResult_UNSET,
+    CONSENSUS = btck_BlockValidationResult_CONSENSUS,
+    CACHED_INVALID = btck_BlockValidationResult_CACHED_INVALID,
+    INVALID_HEADER = btck_BlockValidationResult_INVALID_HEADER,
+    MUTATED = btck_BlockValidationResult_MUTATED,
+    MISSING_PREV = btck_BlockValidationResult_MISSING_PREV,
+    INVALID_PREV = btck_BlockValidationResult_INVALID_PREV,
+    TIME_FUTURE = btck_BlockValidationResult_TIME_FUTURE,
+    HEADER_LOW_WORK = btck_BlockValidationResult_HEADER_LOW_WORK
+};
+
 enum class ScriptVerifyStatus : btck_ScriptVerifyStatus {
     OK = btck_ScriptVerifyStatus_OK,
     ERROR_INVALID_FLAGS_COMBINATION = btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION,
@@ -616,6 +634,16 @@ public:
     BlockValidationState& operator=(const BlockValidationState&) = delete;
     BlockValidationState(BlockValidationState&&) = delete;
     BlockValidationState& operator=(BlockValidationState&&) = delete;
+
+    ValidationMode GetValidationMode() const
+    {
+        return static_cast<ValidationMode>(btck_block_validation_state_get_validation_mode(m_state));
+    }
+
+    BlockValidationResult GetBlockValidationResult() const
+    {
+        return static_cast<BlockValidationResult>(btck_block_validation_state_get_block_validation_result(m_state));
+    }
 };
 
 class ValidationInterface
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 4cf3df7f57e..0e21cc5689f 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -131,7 +131,53 @@ class TestValidationInterface : public ValidationInterface
 public:
     void BlockChecked(Block block, const BlockValidationState state) override
     {
-        std::cout << "Block checked." << std::endl;
+        std::cout << "Block checked: ";
+
+        auto mode{state.GetValidationMode()};
+        switch (mode) {
+        case ValidationMode::VALID: {
+            std::cout << "Valid block" << std::endl;
+            return;
+        }
+        case ValidationMode::INVALID: {
+            std::cout << "Invalid block: ";
+            auto result{state.GetBlockValidationResult()};
+            switch (result) {
+            case BlockValidationResult::UNSET:
+                std::cout << "initial value. Block has not yet been rejected" << std::endl;
+                break;
+            case BlockValidationResult::HEADER_LOW_WORK:
+                std::cout << "the block header may be on a too-little-work chain" << std::endl;
+                break;
+            case BlockValidationResult::CONSENSUS:
+                std::cout << "invalid by consensus rules (excluding any below reasons)" << std::endl;
+                break;
+            case BlockValidationResult::CACHED_INVALID:
+                std::cout << "this block was cached as being invalid and we didn't store the reason why" << std::endl;
+                break;
+            case BlockValidationResult::INVALID_HEADER:
+                std::cout << "invalid proof of work or time too old" << std::endl;
+                break;
+            case BlockValidationResult::MUTATED:
+                std::cout << "the block's data didn't match the data committed to by the PoW" << std::endl;
+                break;
+            case BlockValidationResult::MISSING_PREV:
+                std::cout << "We don't have the previous block the checked one is built on" << std::endl;
+                break;
+            case BlockValidationResult::INVALID_PREV:
+                std::cout << "A block this one builds on is invalid" << std::endl;
+                break;
+            case BlockValidationResult::TIME_FUTURE:
+                std::cout << "block timestamp was > 2 hours in the future (or our clock is bad)" << std::endl;
+                break;
+            }
+            return;
+        }
+        case ValidationMode::INTERNAL_ERROR: {
+            std::cout << "Internal error" << std::endl;
+            return;
+        }
+        }
     }
 
     void BlockConnected(Block block, BlockTreeEntry entry) override

From a263a4caf2311bc31dc2ef1c04dab9517ee0d28f Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Sat, 1 Jun 2024 11:52:52 +0200
Subject: [PATCH 16/23] kernel: Add function for copying block data to C header

This adds a function for streaming bytes into a user-owned data
structure.

Use it in the tests for verifying the implementation of the validation
interface's `BlockChecked` method.
---
 src/kernel/bitcoinkernel.cpp       | 11 +++++++++++
 src/kernel/bitcoinkernel.h         | 25 ++++++++++++++++++++-----
 src/kernel/bitcoinkernel_wrapper.h |  5 +++++
 src/test/kernel/test_kernel.cpp    | 22 +++++++++++++++++++---
 4 files changed, 55 insertions(+), 8 deletions(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index e115518df81..753489373d3 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -967,6 +967,17 @@ const btck_Transaction* btck_block_get_transaction_at(const btck_Block* block, s
     return btck_Transaction::ref(&btck_Block::get(block)->vtx[index]);
 }
 
+int btck_block_to_bytes(const btck_Block* block, btck_WriteBytes writer, void* user_data)
+{
+    try {
+        WriterStream ws{writer, user_data};
+        ws << TX_WITH_WITNESS(*btck_Block::get(block));
+        return 0;
+    } catch (...) {
+        return -1;
+    }
+}
+
 void btck_block_destroy(btck_Block* block)
 {
     delete block;
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index e1f99b53151..62db5daa3d8 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -249,6 +249,11 @@ typedef void (*btck_ValidationInterfacePoWValidBlock)(void* user_data, btck_Bloc
 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);
 
+/**
+ * Function signature for serializing data.
+ */
+typedef int (*btck_WriteBytes)(const void* bytes, size_t size, void* userdata);
+
 /**
  * Whether a validated data structure is valid, invalid, or an error was
  * encountered during processing.
@@ -389,11 +394,6 @@ typedef uint8_t btck_ChainType;
 #define btck_ChainType_SIGNET ((btck_ChainType)(3))
 #define btck_ChainType_REGTEST ((btck_ChainType)(4))
 
-/**
- * Function signature for serializing data.
- */
-typedef int (*btck_WriteBytes)(const void* bytes, size_t size, void* userdata);
-
 /** @name Transaction
  * Functions for working with transactions.
  */
@@ -983,6 +983,21 @@ BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_count_trans
 BITCOINKERNEL_API const btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_transaction_at(
     const btck_Block* block, size_t transaction_index) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Serializes the block through the passed in callback to bytes.
+ * This is consensus serialization that is also used for the P2P network.
+ *
+ * @param[in] block     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_block_to_bytes(
+    const btck_Block* block,
+    btck_WriteBytes writer,
+    void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
 /**
  * Destroy the block.
  */
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index 249f98a3684..53ecee3e460 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -548,6 +548,11 @@ public:
     }
 
     MAKE_RANGE_METHOD(Transactions, Block, &Block::CountTransactions, &Block::GetTransaction, *this)
+
+    std::vector<std::byte> ToBytes() const
+    {
+        return write_bytes(get(), btck_block_to_bytes);
+    }
 };
 
 inline void logging_disable()
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 0e21cc5689f..fcb614c58a9 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -16,6 +16,7 @@
 #include <filesystem>
 #include <iostream>
 #include <memory>
+#include <optional>
 #include <random>
 #include <ranges>
 #include <span>
@@ -129,9 +130,14 @@ public:
 class TestValidationInterface : public ValidationInterface
 {
 public:
+    std::optional<std::vector<std::byte>> m_expected_valid_block = std::nullopt;
+
     void BlockChecked(Block block, const BlockValidationState state) override
     {
-        std::cout << "Block checked: ";
+        if (m_expected_valid_block.has_value()) {
+            auto ser_block{block.ToBytes()};
+            check_equal(m_expected_valid_block.value(), ser_block);
+        }
 
         auto mode{state.GetValidationMode()};
         switch (mode) {
@@ -545,8 +551,8 @@ BOOST_AUTO_TEST_CASE(btck_context_tests)
 BOOST_AUTO_TEST_CASE(btck_block)
 {
     Block block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[0])};
-    Block block_1{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[1])};
-    CheckHandle(block, block_1);
+    Block block_100{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[100])};
+    CheckHandle(block, block_100);
     Block block_tx{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[205])};
     CheckRange(block_tx.Transactions(), block_tx.CountTransactions());
 }
@@ -673,10 +679,20 @@ void chainman_mainnet_validation_test(TestDirectory& test_directory)
                                return tx.CountOutputs();
                            })).begin();
     BOOST_CHECK_EQUAL(output_counts, 1);
+
+    validation_interface->m_expected_valid_block.emplace(raw_block);
+    auto ser_block{block.ToBytes()};
+    check_equal(ser_block, raw_block);
     bool new_block = false;
     BOOST_CHECK(chainman->ProcessBlock(block, &new_block));
     BOOST_CHECK(new_block);
 
+    validation_interface->m_expected_valid_block = std::nullopt;
+    new_block = false;
+    Block invalid_block{hex_string_to_byte_vec(REGTEST_BLOCK_DATA[REGTEST_BLOCK_DATA.size() - 1])};
+    BOOST_CHECK(!chainman->ProcessBlock(invalid_block, &new_block));
+    BOOST_CHECK(!new_block);
+
     // If we try to validate it again, it should be a duplicate
     BOOST_CHECK(chainman->ProcessBlock(block, &new_block));
     BOOST_CHECK(!new_block);

From 09d0f626388a10eed1f264386014665fcae4fa22 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Sat, 1 Jun 2024 13:03:31 +0200
Subject: [PATCH 17/23] kernel: Add functions to read block from disk to C
 header

This adds functions for reading a block from disk with a retrieved block
tree entry. External services that wish to build their own index, or
analyze blocks can use this to retrieve block data.

The block tree can now be traversed from the tip backwards. This is
guaranteed to work, since the chainstate maintains an internal block
tree index in memory and every block (besides the genesis) has an
ancestor.

The user can use this function to iterate through all blocks in the
chain (starting from the tip). The tip is retrieved from a separate
`Chain` object, which allows distinguishing whether entries are
currently in the best chain. Once the block tree entry for the genesis
block is reached a nullptr is returned if the user attempts to get the
previous entry.
---
 src/kernel/bitcoinkernel.cpp       | 38 +++++++++++++++
 src/kernel/bitcoinkernel.h         | 78 ++++++++++++++++++++++++++++++
 src/kernel/bitcoinkernel_wrapper.h | 38 ++++++++++++++-
 src/test/kernel/test_kernel.cpp    | 26 ++++++++++
 4 files changed, 179 insertions(+), 1 deletion(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 753489373d3..21193ce4948 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -484,6 +484,7 @@ struct btck_Context : Handle<btck_Context, std::shared_ptr<const Context>> {};
 struct btck_ChainParameters : Handle<btck_ChainParameters, CChainParams> {};
 struct btck_ChainstateManagerOptions : Handle<btck_ChainstateManagerOptions, ChainstateManagerOptions> {};
 struct btck_ChainstateManager : Handle<btck_ChainstateManager, ChainMan> {};
+struct btck_Chain : Handle<btck_Chain, CChain> {};
 
 btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
 {
@@ -769,6 +770,16 @@ void btck_context_destroy(btck_Context* context)
     delete context;
 }
 
+const btck_BlockTreeEntry* btck_block_tree_entry_get_previous(const btck_BlockTreeEntry* entry)
+{
+    if (!btck_BlockTreeEntry::get(entry).pprev) {
+        LogInfo("Genesis block has no previous.");
+        return nullptr;
+    }
+
+    return btck_BlockTreeEntry::ref(btck_BlockTreeEntry::get(entry).pprev);
+}
+
 btck_ValidationMode btck_block_validation_state_get_validation_mode(const btck_BlockValidationState* block_validation_state_)
 {
     auto& block_validation_state = btck_BlockValidationState::get(block_validation_state_);
@@ -983,6 +994,16 @@ void btck_block_destroy(btck_Block* block)
     delete block;
 }
 
+btck_Block* btck_block_read(const btck_ChainstateManager* chainman, const btck_BlockTreeEntry* entry)
+{
+    auto block{std::make_shared<CBlock>()};
+    if (!btck_ChainstateManager::get(chainman).m_chainman->m_blockman.ReadBlock(*block, btck_BlockTreeEntry::get(entry))) {
+        LogError("Failed to read block.");
+        return nullptr;
+    }
+    return btck_Block::create(block);
+}
+
 int btck_chainstate_manager_process_block(
     btck_ChainstateManager* chainman,
     const btck_Block* block,
@@ -995,3 +1016,20 @@ int btck_chainstate_manager_process_block(
     }
     return result ? 0 : -1;
 }
+
+const btck_Chain* btck_chainstate_manager_get_active_chain(const btck_ChainstateManager* chainman)
+{
+    return btck_Chain::ref(&WITH_LOCK(btck_ChainstateManager::get(chainman).m_chainman->GetMutex(), return btck_ChainstateManager::get(chainman).m_chainman->ActiveChain()));
+}
+
+const btck_BlockTreeEntry* btck_chain_get_tip(const btck_Chain* chain)
+{
+    LOCK(::cs_main);
+    return btck_BlockTreeEntry::ref(btck_Chain::get(chain).Tip());
+}
+
+int btck_chain_get_height(const btck_Chain* chain)
+{
+    LOCK(::cs_main);
+    return btck_Chain::get(chain).Height();
+}
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 62db5daa3d8..e86945147ad 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -206,6 +206,12 @@ typedef struct btck_Block btck_Block;
  */
 typedef struct btck_BlockValidationState btck_BlockValidationState;
 
+/**
+ * Opaque data structure for holding the currently known best-chain associated
+ * with a chainstate.
+ */
+typedef struct btck_Chain btck_Chain;
+
 /** Current sync state passed to tip changed callbacks. */
 typedef uint8_t btck_SynchronizationState;
 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
@@ -800,6 +806,23 @@ BITCOINKERNEL_API void btck_context_destroy(btck_Context* context);
 
 ///@}
 
+/** @name BlockTreeEntry
+ * Functions for working with block tree entries.
+ */
+///@{
+
+/**
+ * @brief Returns the previous block tree entry in the chain, or null if the current
+ * block tree entry is the genesis block.
+ *
+ * @param[in] block_tree_entry Non-null.
+ * @return                     The previous block tree entry, or null on error or if the current block tree entry is the genesis block.
+ */
+BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_previous(
+    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
+
+///@}
+
 /** @name ChainstateManagerOptions
  * Functions for working with chainstate manager options.
  */
@@ -931,6 +954,23 @@ BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_p
     const btck_Block* block,
     int* new_block) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
 
+/**
+ * @brief Returns the best known currently active chain. Its lifetime is
+ * dependent on the chainstate manager. It can be thought of as a view on a
+ * vector of block tree entries that form the best chain. The returned chain
+ * reference always points to the currently active best chain. However, state
+ * transitions within the chainstate manager (e.g., processing blocks) will
+ * update the chain's contents. Data retrieved from this chain is only
+ * consistent up to the point when new data is processed in the chainstate
+ * manager. It is the user's responsibility to guard against these
+ * inconsistencies.
+ *
+ * @param[in] chainstate_manager Non-null.
+ * @return                       The chain.
+ */
+BITCOINKERNEL_API const btck_Chain* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_active_chain(
+    const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * Destroy the chainstate manager.
  */
@@ -943,6 +983,18 @@ BITCOINKERNEL_API void btck_chainstate_manager_destroy(btck_ChainstateManager* c
  */
 ///@{
 
+/**
+ * @brief Reads the block the passed in block tree entry points to from disk and
+ * returns it.
+ *
+ * @param[in] chainstate_manager Non-null.
+ * @param[in] block_tree_entry   Non-null.
+ * @return                       The read out block, or null on error.
+ */
+BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_read(
+    const btck_ChainstateManager* chainstate_manager,
+    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
 /**
  * @brief Parse a serialized raw block into a new block object.
  *
@@ -1024,6 +1076,32 @@ BITCOINKERNEL_API btck_BlockValidationResult btck_block_validation_state_get_blo
 
 ///@}
 
+/** @name Chain
+ * Functions for working with the chain
+ */
+///@{
+
+/**
+ * @brief Get the block tree entry of the current chain tip. Once returned,
+ * there is no guarantee that it remains in the active chain.
+ *
+ * @param[in] chain Non-null.
+ * @return          The block tree entry of the current tip, or null if the chain is empty.
+ */
+BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_get_tip(
+    const btck_Chain* chain) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Return the height of the tip of the chain.
+ *
+ * @param[in] chain Non-null.
+ * @return          The current height.
+ */
+BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_get_height(
+    const btck_Chain* chain) BITCOINKERNEL_ARG_NONNULL(1);
+
+///@}
+
 #ifdef __cplusplus
 } // extern "C"
 #endif // __cplusplus
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index 53ecee3e460..983a5e0737e 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -9,6 +9,7 @@
 
 #include <functional>
 #include <memory>
+#include <optional>
 #include <span>
 #include <stdexcept>
 #include <string>
@@ -598,13 +599,20 @@ public:
     }
 };
 
-class BlockTreeEntry : View<btck_BlockTreeEntry>
+class BlockTreeEntry : public View<btck_BlockTreeEntry>
 {
 public:
     BlockTreeEntry(const btck_BlockTreeEntry* entry)
         : View{entry}
     {
     }
+
+    std::optional<BlockTreeEntry> GetPrevious() const
+    {
+        auto entry{btck_block_tree_entry_get_previous(get())};
+        if (!entry) return std::nullopt;
+        return entry;
+    }
 };
 
 class KernelNotifications
@@ -766,6 +774,22 @@ public:
     }
 };
 
+class ChainView : public View<btck_Chain>
+{
+public:
+    explicit ChainView(const btck_Chain* ptr) : View{ptr} {}
+
+    BlockTreeEntry Tip() const
+    {
+        return btck_chain_get_tip(get());
+    }
+
+    int32_t Height() const
+    {
+        return btck_chain_get_height(get());
+    }
+};
+
 class ChainMan : UniqueHandle<btck_ChainstateManager, btck_chainstate_manager_destroy>
 {
 public:
@@ -795,6 +819,18 @@ public:
         if (new_block) *new_block = _new_block == 1;
         return res == 0;
     }
+
+    ChainView GetChain() const
+    {
+        return ChainView{btck_chainstate_manager_get_active_chain(get())};
+    }
+
+    std::optional<Block> ReadBlock(const BlockTreeEntry& entry) const
+    {
+        auto block{btck_block_read(get(), entry.get())};
+        if (!block) return std::nullopt;
+        return block;
+    }
 };
 
 } // namespace btck
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index fcb614c58a9..29765812931 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -693,6 +693,20 @@ void chainman_mainnet_validation_test(TestDirectory& test_directory)
     BOOST_CHECK(!chainman->ProcessBlock(invalid_block, &new_block));
     BOOST_CHECK(!new_block);
 
+    auto chain{chainman->GetChain()};
+    BOOST_CHECK_EQUAL(chain.Height(), 1);
+    auto tip{chain.Tip()};
+    auto read_block{chainman->ReadBlock(tip)};
+    BOOST_REQUIRE(read_block);
+    check_equal(read_block.value().ToBytes(), raw_block);
+
+    // Check that we can read the previous block
+    auto tip_2{tip.GetPrevious()};
+    auto read_block_2{chainman->ReadBlock(tip_2.value())};
+
+    // It should be an error if we go another block back, since the genesis has no ancestor
+    BOOST_CHECK(!tip_2.value().GetPrevious());
+
     // If we try to validate it again, it should be a duplicate
     BOOST_CHECK(chainman->ProcessBlock(block, &new_block));
     BOOST_CHECK(!new_block);
@@ -758,4 +772,16 @@ BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
         BOOST_CHECK(chainman->ProcessBlock(block, &new_block));
         BOOST_CHECK(new_block);
     }
+
+    auto chain = chainman->GetChain();
+    auto tip = chain.Tip();
+    auto read_block = chainman->ReadBlock(tip).value();
+    check_equal(read_block.ToBytes(), hex_string_to_byte_vec(REGTEST_BLOCK_DATA[REGTEST_BLOCK_DATA.size() - 1]));
+
+    auto tip_2 = tip.GetPrevious().value();
+    auto read_block_2 = chainman->ReadBlock(tip_2).value();
+    check_equal(read_block_2.ToBytes(), hex_string_to_byte_vec(REGTEST_BLOCK_DATA[REGTEST_BLOCK_DATA.size() - 2]));
+
+    std::filesystem::remove_all(test_directory.m_directory / "blocks" / "blk00000.dat");
+    BOOST_CHECK(!chainman->ReadBlock(tip_2));
 }

From f5d5d1213cc4f4ef8bfe335736c665ed7bc3137d Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Sat, 1 Jun 2024 14:47:56 +0200
Subject: [PATCH 18/23] kernel: Add function to read block undo data from disk
 to C header

This adds functions for reading the undo data from disk with a retrieved
block tree entry. The undo data of a block contains all the spent
script pubkeys of all the transactions in a block. For ease of
understanding the undo data is renamed to spent outputs with seperate
data structures exposed for a block's and a transaction's spent outputs.

In normal operations undo data is used during re-orgs. This data might
also be useful for building external indexes, or to scan for silent
payment transactions.

Internally the block undo data contains a vector of transaction undo
data which contains a vector of the coins consumed. The coins are all
int the order of the transaction inputs of the consuming transactions.
Each coin can be used to retrieve a transaction output and in turn a
script pubkey and amount.

This translates to the three-level hierarchy the api provides: Block
spent outputs contain transaction spent outputs, which contain
individual coins. Each coin includes the associated output, the height
of the block is contained in, and whether it is from a coinbase
transaction.
---
 src/kernel/bitcoinkernel.cpp       |  88 ++++++++++++++
 src/kernel/bitcoinkernel.h         | 180 +++++++++++++++++++++++++++++
 src/kernel/bitcoinkernel_wrapper.h | 104 +++++++++++++++++
 src/test/kernel/test_kernel.cpp    |  52 ++++++++-
 4 files changed, 420 insertions(+), 4 deletions(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 21193ce4948..b9c0acc8b4d 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -7,6 +7,7 @@
 #include <kernel/bitcoinkernel.h>
 
 #include <chain.h>
+#include <coins.h>
 #include <consensus/amount.h>
 #include <consensus/validation.h>
 #include <kernel/caches.h>
@@ -28,6 +29,7 @@
 #include <sync.h>
 #include <tinyformat.h>
 #include <uint256.h>
+#include <undo.h>
 #include <util/fs.h>
 #include <util/result.h>
 #include <util/signalinterrupt.h>
@@ -485,6 +487,9 @@ struct btck_ChainParameters : Handle<btck_ChainParameters, CChainParams> {};
 struct btck_ChainstateManagerOptions : Handle<btck_ChainstateManagerOptions, ChainstateManagerOptions> {};
 struct btck_ChainstateManager : Handle<btck_ChainstateManager, ChainMan> {};
 struct btck_Chain : Handle<btck_Chain, CChain> {};
+struct btck_BlockSpentOutputs : Handle<btck_BlockSpentOutputs, std::shared_ptr<CBlockUndo>> {};
+struct btck_TransactionSpentOutputs : Handle<btck_TransactionSpentOutputs, CTxUndo> {};
+struct btck_Coin : Handle<btck_Coin, Coin> {};
 
 btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
 {
@@ -1004,6 +1009,89 @@ btck_Block* btck_block_read(const btck_ChainstateManager* chainman, const btck_B
     return btck_Block::create(block);
 }
 
+btck_BlockSpentOutputs* btck_block_spent_outputs_read(const btck_ChainstateManager* chainman, const btck_BlockTreeEntry* entry)
+{
+    auto block_undo{std::make_shared<CBlockUndo>()};
+    if (btck_BlockTreeEntry::get(entry).nHeight < 1) {
+        LogDebug(BCLog::KERNEL, "The genesis block does not have any spent outputs.");
+        return btck_BlockSpentOutputs::create(block_undo);
+    }
+    if (!btck_ChainstateManager::get(chainman).m_chainman->m_blockman.ReadBlockUndo(*block_undo, btck_BlockTreeEntry::get(entry))) {
+        LogError("Failed to read block spent outputs data.");
+        return nullptr;
+    }
+    return btck_BlockSpentOutputs::create(block_undo);
+}
+
+btck_BlockSpentOutputs* btck_block_spent_outputs_copy(const btck_BlockSpentOutputs* block_spent_outputs)
+{
+    return btck_BlockSpentOutputs::copy(block_spent_outputs);
+}
+
+size_t btck_block_spent_outputs_count(const btck_BlockSpentOutputs* block_spent_outputs)
+{
+    return btck_BlockSpentOutputs::get(block_spent_outputs)->vtxundo.size();
+}
+
+const btck_TransactionSpentOutputs* btck_block_spent_outputs_get_transaction_spent_outputs_at(const btck_BlockSpentOutputs* block_spent_outputs, size_t transaction_index)
+{
+    assert(transaction_index < btck_BlockSpentOutputs::get(block_spent_outputs)->vtxundo.size());
+    const auto* tx_undo{&btck_BlockSpentOutputs::get(block_spent_outputs)->vtxundo.at(transaction_index)};
+    return btck_TransactionSpentOutputs::ref(tx_undo);
+}
+
+void btck_block_spent_outputs_destroy(btck_BlockSpentOutputs* block_spent_outputs)
+{
+    delete block_spent_outputs;
+}
+
+btck_TransactionSpentOutputs* btck_transaction_spent_outputs_copy(const btck_TransactionSpentOutputs* transaction_spent_outputs)
+{
+    return btck_TransactionSpentOutputs::copy(transaction_spent_outputs);
+}
+
+size_t btck_transaction_spent_outputs_count(const btck_TransactionSpentOutputs* transaction_spent_outputs)
+{
+    return btck_TransactionSpentOutputs::get(transaction_spent_outputs).vprevout.size();
+}
+
+void btck_transaction_spent_outputs_destroy(btck_TransactionSpentOutputs* transaction_spent_outputs)
+{
+    delete transaction_spent_outputs;
+}
+
+const btck_Coin* btck_transaction_spent_outputs_get_coin_at(const btck_TransactionSpentOutputs* transaction_spent_outputs, size_t coin_index)
+{
+    assert(coin_index < btck_TransactionSpentOutputs::get(transaction_spent_outputs).vprevout.size());
+    const Coin* coin{&btck_TransactionSpentOutputs::get(transaction_spent_outputs).vprevout.at(coin_index)};
+    return btck_Coin::ref(coin);
+}
+
+btck_Coin* btck_coin_copy(const btck_Coin* coin)
+{
+    return btck_Coin::copy(coin);
+}
+
+uint32_t btck_coin_confirmation_height(const btck_Coin* coin)
+{
+    return btck_Coin::get(coin).nHeight;
+}
+
+int btck_coin_is_coinbase(const btck_Coin* coin)
+{
+    return btck_Coin::get(coin).IsCoinBase() ? 1 : 0;
+}
+
+const btck_TransactionOutput* btck_coin_get_output(const btck_Coin* coin)
+{
+    return btck_TransactionOutput::ref(&btck_Coin::get(coin).out);
+}
+
+void btck_coin_destroy(btck_Coin* coin)
+{
+    delete coin;
+}
+
 int btck_chainstate_manager_process_block(
     btck_ChainstateManager* chainman,
     const btck_Block* block,
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index e86945147ad..b6cfb0dbd3e 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -212,6 +212,36 @@ typedef struct btck_BlockValidationState btck_BlockValidationState;
  */
 typedef struct btck_Chain btck_Chain;
 
+/**
+ * Opaque data structure for holding a block's spent outputs.
+ *
+ * Contains all the previous outputs consumed by all transactions in a specific
+ * block. Internally it holds a nested vector. The top level vector has an
+ * entry for each transaction in a block (in order of the actual transactions
+ * of the block and without the coinbase transaction). This is exposed through
+ * @ref btck_TransactionSpentOutputs. Each btck_TransactionSpentOutputs is in
+ * turn a vector of all the previous outputs of a transaction (in order of
+ * their corresponding inputs).
+ */
+typedef struct btck_BlockSpentOutputs btck_BlockSpentOutputs;
+
+/**
+ * Opaque data structure for holding a transaction's spent outputs.
+ *
+ * Holds the coins consumed by a certain transaction. Retrieved through the
+ * @ref btck_BlockSpentOutputs. The coins are in the same order as the
+ * transaction's inputs consuming them.
+ */
+typedef struct btck_TransactionSpentOutputs btck_TransactionSpentOutputs;
+
+/**
+ * Opaque data structure for holding a coin.
+ *
+ * Holds information on the @ref btck_TransactionOutput held within,
+ * including the height it was spent at and whether it is a coinbase output.
+ */
+typedef struct btck_Coin btck_Coin;
+
 /** Current sync state passed to tip changed callbacks. */
 typedef uint8_t btck_SynchronizationState;
 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
@@ -1102,6 +1132,156 @@ BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_get_height
 
 ///@}
 
+/** @name BlockSpentOutputs
+ * Functions for working with block spent outputs.
+ */
+///@{
+
+/**
+ * @brief Reads the block spent coins data the passed in block tree entry points to from
+ * disk and returns it.
+ *
+ * @param[in] chainstate_manager Non-null.
+ * @param[in] block_tree_entry   Non-null.
+ * @return                       The read out block spent outputs, or null on error.
+ */
+BITCOINKERNEL_API btck_BlockSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_read(
+    const btck_ChainstateManager* chainstate_manager,
+    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Copy a block's spent outputs.
+ *
+ * @param[in] block_spent_outputs Non-null.
+ * @return                        The copied block spent outputs.
+ */
+BITCOINKERNEL_API btck_BlockSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_copy(
+    const btck_BlockSpentOutputs* block_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Returns the number of transaction spent outputs whose data is contained in
+ * block spent outputs.
+ *
+ * @param[in] block_spent_outputs Non-null.
+ * @return                        The number of transaction spent outputs data in the block spent outputs.
+ */
+BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_count(
+    const btck_BlockSpentOutputs* block_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Returns a transaction spent outputs contained in the block spent
+ * outputs at a certain index. The returned pointer is unowned and only valid
+ * for the lifetime of block_spent_outputs.
+ *
+ * @param[in] block_spent_outputs             Non-null.
+ * @param[in] transaction_spent_outputs_index The index of the transaction spent outputs within the block spent outputs.
+ * @return                                    A transaction spent outputs pointer.
+ */
+BITCOINKERNEL_API const btck_TransactionSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_get_transaction_spent_outputs_at(
+    const btck_BlockSpentOutputs* block_spent_outputs,
+    size_t transaction_spent_outputs_index) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the block spent outputs.
+ */
+BITCOINKERNEL_API void btck_block_spent_outputs_destroy(btck_BlockSpentOutputs* block_spent_outputs);
+
+///@}
+
+/** @name TransactionSpentOutputs
+ * Functions for working with the spent coins of a transaction
+ */
+///@{
+
+/**
+ * @brief Copy a transaction's spent outputs.
+ *
+ * @param[in] transaction_spent_outputs Non-null.
+ * @return                              The copied transaction spent outputs.
+ */
+BITCOINKERNEL_API btck_TransactionSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_spent_outputs_copy(
+    const btck_TransactionSpentOutputs* transaction_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Returns the number of previous transaction outputs contained in the
+ * transaction spent outputs data.
+ *
+ * @param[in] transaction_spent_outputs Non-null
+ * @return                              The number of spent transaction outputs for the transaction.
+ */
+BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_spent_outputs_count(
+    const btck_TransactionSpentOutputs* transaction_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Returns a coin contained in the transaction spent outputs at a
+ * certain index. The returned pointer is unowned and only valid for the
+ * lifetime of transaction_spent_outputs.
+ *
+ * @param[in] transaction_spent_outputs Non-null.
+ * @param[in] coin_index                The index of the to be retrieved coin within the
+ *                                      transaction spent outputs.
+ * @return                              A coin pointer.
+ */
+BITCOINKERNEL_API const btck_Coin* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_spent_outputs_get_coin_at(
+    const btck_TransactionSpentOutputs* transaction_spent_outputs,
+    size_t coin_index) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the transaction spent outputs.
+ */
+BITCOINKERNEL_API void btck_transaction_spent_outputs_destroy(btck_TransactionSpentOutputs* transaction_spent_outputs);
+
+///@}
+
+/** @name Coin
+ * Functions for working with coins.
+ */
+///@{
+
+/**
+ * @brief Copy a coin.
+ *
+ * @param[in] coin Non-null.
+ * @return         The copied coin.
+ */
+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.
+ *
+ * @param[in] coin Non-null.
+ * @return         The block height of the coin.
+ */
+BITCOINKERNEL_API uint32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_confirmation_height(
+    const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Returns whether the containing transaction was a coinbase.
+ *
+ * @param[in] coin Non-null.
+ * @return         1 if the coin is a coinbase coin, 0 otherwise.
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_is_coinbase(
+    const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Return the transaction output of a coin. The returned pointer is
+ * unowned and only valid for the lifetime of the coin.
+ *
+ * @param[in] coin Non-null.
+ * @return         A transaction output pointer.
+ */
+BITCOINKERNEL_API const btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_get_output(
+    const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the coin.
+ */
+BITCOINKERNEL_API void btck_coin_destroy(btck_Coin* coin);
+
+///@}
+
 #ifdef __cplusplus
 } // extern "C"
 #endif // __cplusplus
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index 983a5e0737e..d9cacab8428 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -790,6 +790,105 @@ public:
     }
 };
 
+template <typename Derived>
+class CoinApi
+{
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
+
+    friend Derived;
+    CoinApi() = default;
+
+public:
+    uint32_t GetConfirmationHeight() const { return btck_coin_confirmation_height(impl()); }
+
+    bool IsCoinbase() const { return btck_coin_is_coinbase(impl()) == 1; }
+
+    TransactionOutputView GetOutput() const
+    {
+        return TransactionOutputView{btck_coin_get_output(impl())};
+    }
+};
+
+class CoinView : public View<btck_Coin>, public CoinApi<CoinView>
+{
+public:
+    explicit CoinView(const btck_Coin* ptr) : View{ptr} {}
+};
+
+class Coin : public Handle<btck_Coin, btck_coin_copy, btck_coin_destroy>, public CoinApi<Coin>
+{
+public:
+    Coin(btck_Coin* coin) : Handle{coin} {}
+
+    Coin(const CoinView& view) : Handle{view} {}
+};
+
+template <typename Derived>
+class TransactionSpentOutputsApi
+{
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
+
+    friend Derived;
+    TransactionSpentOutputsApi() = default;
+
+public:
+    size_t Count() const
+    {
+        return btck_transaction_spent_outputs_count(impl());
+    }
+
+    CoinView GetCoin(size_t index) const
+    {
+        return CoinView{btck_transaction_spent_outputs_get_coin_at(impl(), index)};
+    }
+
+    MAKE_RANGE_METHOD(Coins, Derived, &TransactionSpentOutputsApi<Derived>::Count, &TransactionSpentOutputsApi<Derived>::GetCoin, *static_cast<const Derived*>(this))
+};
+
+class TransactionSpentOutputsView : public View<btck_TransactionSpentOutputs>, public TransactionSpentOutputsApi<TransactionSpentOutputsView>
+{
+public:
+    explicit TransactionSpentOutputsView(const btck_TransactionSpentOutputs* ptr) : View{ptr} {}
+};
+
+class TransactionSpentOutputs : public Handle<btck_TransactionSpentOutputs, btck_transaction_spent_outputs_copy, btck_transaction_spent_outputs_destroy>,
+                                public TransactionSpentOutputsApi<TransactionSpentOutputs>
+{
+public:
+    TransactionSpentOutputs(btck_TransactionSpentOutputs* transaction_spent_outputs) : Handle{transaction_spent_outputs} {}
+
+    TransactionSpentOutputs(const TransactionSpentOutputsView& view) : Handle{view} {}
+};
+
+class BlockSpentOutputs : public Handle<btck_BlockSpentOutputs, btck_block_spent_outputs_copy, btck_block_spent_outputs_destroy>
+{
+public:
+    BlockSpentOutputs(btck_BlockSpentOutputs* block_spent_outputs)
+        : Handle{block_spent_outputs}
+    {
+    }
+
+    size_t Count() const
+    {
+        return btck_block_spent_outputs_count(get());
+    }
+
+    TransactionSpentOutputsView GetTxSpentOutputs(size_t tx_undo_index) const
+    {
+        return TransactionSpentOutputsView{btck_block_spent_outputs_get_transaction_spent_outputs_at(get(), tx_undo_index)};
+    }
+
+    MAKE_RANGE_METHOD(TxsSpentOutputs, BlockSpentOutputs, &BlockSpentOutputs::Count, &BlockSpentOutputs::GetTxSpentOutputs, *this)
+};
+
 class ChainMan : UniqueHandle<btck_ChainstateManager, btck_chainstate_manager_destroy>
 {
 public:
@@ -831,6 +930,11 @@ public:
         if (!block) return std::nullopt;
         return block;
     }
+
+    BlockSpentOutputs ReadBlockSpentOutputs(const BlockTreeEntry& entry) const
+    {
+        return btck_block_spent_outputs_read(get(), entry.get());
+    }
 };
 
 } // namespace btck
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 29765812931..525c5f9f93b 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -701,11 +701,13 @@ void chainman_mainnet_validation_test(TestDirectory& test_directory)
     check_equal(read_block.value().ToBytes(), raw_block);
 
     // Check that we can read the previous block
-    auto tip_2{tip.GetPrevious()};
-    auto read_block_2{chainman->ReadBlock(tip_2.value())};
+    BlockTreeEntry tip_2{*tip.GetPrevious()};
+    Block read_block_2{*chainman->ReadBlock(tip_2)};
+    BOOST_CHECK_EQUAL(chainman->ReadBlockSpentOutputs(tip_2).Count(), 0);
+    BOOST_CHECK_EQUAL(chainman->ReadBlockSpentOutputs(tip).Count(), 0);
 
     // It should be an error if we go another block back, since the genesis has no ancestor
-    BOOST_CHECK(!tip_2.value().GetPrevious());
+    BOOST_CHECK(!tip_2.GetPrevious());
 
     // If we try to validate it again, it should be a duplicate
     BOOST_CHECK(chainman->ProcessBlock(block, &new_block));
@@ -782,6 +784,48 @@ BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
     auto read_block_2 = chainman->ReadBlock(tip_2).value();
     check_equal(read_block_2.ToBytes(), hex_string_to_byte_vec(REGTEST_BLOCK_DATA[REGTEST_BLOCK_DATA.size() - 2]));
 
+    // Read spent outputs for current tip and its previous block
+    BlockSpentOutputs block_spent_outputs{chainman->ReadBlockSpentOutputs(tip)};
+    BlockSpentOutputs block_spent_outputs_prev{chainman->ReadBlockSpentOutputs(*tip.GetPrevious())};
+    CheckHandle(block_spent_outputs, block_spent_outputs_prev);
+    CheckRange(block_spent_outputs_prev.TxsSpentOutputs(), block_spent_outputs_prev.Count());
+    BOOST_CHECK_EQUAL(block_spent_outputs.Count(), 1);
+
+    // Get transaction spent outputs from the last transaction in the two blocks
+    TransactionSpentOutputsView transaction_spent_outputs{block_spent_outputs.GetTxSpentOutputs(block_spent_outputs.Count() - 1)};
+    TransactionSpentOutputs owned_transaction_spent_outputs{transaction_spent_outputs};
+    TransactionSpentOutputs owned_transaction_spent_outputs_prev{block_spent_outputs_prev.GetTxSpentOutputs(block_spent_outputs_prev.Count() - 1)};
+    CheckHandle(owned_transaction_spent_outputs, owned_transaction_spent_outputs_prev);
+    CheckRange(transaction_spent_outputs.Coins(), transaction_spent_outputs.Count());
+
+    // Get the last coin from the transaction spent outputs
+    CoinView coin{transaction_spent_outputs.GetCoin(transaction_spent_outputs.Count() - 1)};
+    BOOST_CHECK(!coin.IsCoinbase());
+    Coin owned_coin{coin};
+    Coin owned_coin_prev{owned_transaction_spent_outputs_prev.GetCoin(owned_transaction_spent_outputs_prev.Count() - 1)};
+    CheckHandle(owned_coin, owned_coin_prev);
+
+    // Validate coin properties
+    TransactionOutputView output = coin.GetOutput();
+    uint32_t coin_height = coin.GetConfirmationHeight();
+    BOOST_CHECK_EQUAL(coin_height, 205);
+    BOOST_CHECK_EQUAL(output.Amount(), 100000000);
+
+    // Test script pubkey serialization
+    auto script_pubkey = output.GetScriptPubkey();
+    auto script_pubkey_bytes{script_pubkey.ToBytes()};
+    BOOST_CHECK_EQUAL(script_pubkey_bytes.size(), 22);
+    auto round_trip_script_pubkey{ScriptPubkey(script_pubkey_bytes)};
+    BOOST_CHECK_EQUAL(round_trip_script_pubkey.ToBytes().size(), 22);
+
+    for (const auto tx_spent_outputs : block_spent_outputs.TxsSpentOutputs()) {
+        for (const auto coins : tx_spent_outputs.Coins()) {
+            BOOST_CHECK_GT(coins.GetOutput().Amount(), 1);
+        }
+    }
+
     std::filesystem::remove_all(test_directory.m_directory / "blocks" / "blk00000.dat");
-    BOOST_CHECK(!chainman->ReadBlock(tip_2));
+    BOOST_CHECK(!chainman->ReadBlock(tip_2).has_value());
+    std::filesystem::remove_all(test_directory.m_directory / "blocks" / "rev00000.dat");
+    BOOST_CHECK_THROW(chainman->ReadBlockSpentOutputs(tip), std::runtime_error);
 }

From 5eec7fa96aa3042025181c4c4b57263beb869244 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Wed, 5 Jun 2024 22:05:40 +0200
Subject: [PATCH 19/23] kernel: Add block hash type and block tree utility
 functions to C header

Introduce btck_BlockHash as a type-safe identifier for a block. Adds
functions to retrieve block tree entries by hash or height, get block
hashes and heights from entries. access the genesis block, and check if
blocks are in the active chain.
---
 src/kernel/bitcoinkernel.cpp       |  70 ++++++++++++++++
 src/kernel/bitcoinkernel.h         | 128 ++++++++++++++++++++++++++++-
 src/kernel/bitcoinkernel_wrapper.h |  94 +++++++++++++++++++++
 src/test/kernel/test_kernel.cpp    |  73 ++++++++++++++++
 4 files changed, 364 insertions(+), 1 deletion(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index b9c0acc8b4d..531df3c8be8 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -490,6 +490,7 @@ struct btck_Chain : Handle<btck_Chain, CChain> {};
 struct btck_BlockSpentOutputs : Handle<btck_BlockSpentOutputs, std::shared_ptr<CBlockUndo>> {};
 struct btck_TransactionSpentOutputs : Handle<btck_TransactionSpentOutputs, CTxUndo> {};
 struct btck_Coin : Handle<btck_Coin, Coin> {};
+struct btck_BlockHash : Handle<btck_BlockHash, uint256> {};
 
 btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
 {
@@ -918,6 +919,17 @@ btck_ChainstateManager* btck_chainstate_manager_create(
     return btck_ChainstateManager::create(std::move(chainman), opts.m_context);
 }
 
+const btck_BlockTreeEntry* btck_chainstate_manager_get_block_tree_entry_by_hash(const btck_ChainstateManager* chainman, const btck_BlockHash* block_hash)
+{
+    auto block_index = WITH_LOCK(btck_ChainstateManager::get(chainman).m_chainman->GetMutex(),
+                                 return btck_ChainstateManager::get(chainman).m_chainman->m_blockman.LookupBlockIndex(btck_BlockHash::get(block_hash)));
+    if (!block_index) {
+        LogDebug(BCLog::KERNEL, "A block with the given hash is not indexed.");
+        return nullptr;
+    }
+    return btck_BlockTreeEntry::ref(block_index);
+}
+
 void btck_chainstate_manager_destroy(btck_ChainstateManager* chainman)
 {
     {
@@ -994,6 +1006,11 @@ int btck_block_to_bytes(const btck_Block* block, btck_WriteBytes writer, void* u
     }
 }
 
+btck_BlockHash* btck_block_get_hash(const btck_Block* block)
+{
+    return btck_BlockHash::create(btck_Block::get(block)->GetHash());
+}
+
 void btck_block_destroy(btck_Block* block)
 {
     delete block;
@@ -1009,6 +1026,41 @@ btck_Block* btck_block_read(const btck_ChainstateManager* chainman, const btck_B
     return btck_Block::create(block);
 }
 
+int32_t btck_block_tree_entry_get_height(const btck_BlockTreeEntry* entry)
+{
+    return btck_BlockTreeEntry::get(entry).nHeight;
+}
+
+const btck_BlockHash* btck_block_tree_entry_get_block_hash(const btck_BlockTreeEntry* entry)
+{
+    return btck_BlockHash::ref(btck_BlockTreeEntry::get(entry).phashBlock);
+}
+
+btck_BlockHash* btck_block_hash_create(const unsigned char block_hash[32])
+{
+    return btck_BlockHash::create(std::span<const unsigned char>{block_hash, 32});
+}
+
+btck_BlockHash* btck_block_hash_copy(const btck_BlockHash* block_hash)
+{
+    return btck_BlockHash::copy(block_hash);
+}
+
+void btck_block_hash_to_bytes(const btck_BlockHash* block_hash, unsigned char output[32])
+{
+    std::memcpy(output, btck_BlockHash::get(block_hash).begin(), 32);
+}
+
+int btck_block_hash_equals(const btck_BlockHash* hash1, const btck_BlockHash* hash2)
+{
+    return btck_BlockHash::get(hash1) == btck_BlockHash::get(hash2);
+}
+
+void btck_block_hash_destroy(btck_BlockHash* hash)
+{
+    delete hash;
+}
+
 btck_BlockSpentOutputs* btck_block_spent_outputs_read(const btck_ChainstateManager* chainman, const btck_BlockTreeEntry* entry)
 {
     auto block_undo{std::make_shared<CBlockUndo>()};
@@ -1121,3 +1173,21 @@ int btck_chain_get_height(const btck_Chain* chain)
     LOCK(::cs_main);
     return btck_Chain::get(chain).Height();
 }
+
+const btck_BlockTreeEntry* btck_chain_get_genesis(const btck_Chain* chain)
+{
+    LOCK(::cs_main);
+    return btck_BlockTreeEntry::ref(btck_Chain::get(chain).Genesis());
+}
+
+const btck_BlockTreeEntry* btck_chain_get_by_height(const btck_Chain* chain, int height)
+{
+    LOCK(::cs_main);
+    return btck_BlockTreeEntry::ref(btck_Chain::get(chain)[height]);
+}
+
+int btck_chain_contains(const btck_Chain* chain, const btck_BlockTreeEntry* entry)
+{
+    LOCK(::cs_main);
+    return btck_Chain::get(chain).Contains(&btck_BlockTreeEntry::get(entry)) ? 1 : 0;
+}
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index b6cfb0dbd3e..e9283e3da3c 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -242,6 +242,13 @@ typedef struct btck_TransactionSpentOutputs btck_TransactionSpentOutputs;
  */
 typedef struct btck_Coin btck_Coin;
 
+/**
+ * Opaque data structure for holding a block hash.
+ *
+ * This is a type-safe identifier for a block.
+ */
+typedef struct btck_BlockHash btck_BlockHash;
+
 /** Current sync state passed to tip changed callbacks. */
 typedef uint8_t btck_SynchronizationState;
 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
@@ -842,7 +849,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.
@@ -851,6 +858,24 @@ BITCOINKERNEL_API void btck_context_destroy(btck_Context* context);
 BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_previous(
     const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Return the height of a certain block tree entry.
+ *
+ * @param[in] block_tree_entry Non-null.
+ * @return                     The block height.
+ */
+BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_height(
+    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Return the block hash associated with a block tree entry.
+ *
+ * @param[in] block_tree_entry Non-null.
+ * @return                     The 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);
+
 ///@}
 
 /** @name ChainstateManagerOptions
@@ -1001,6 +1026,18 @@ BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_p
 BITCOINKERNEL_API const btck_Chain* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_active_chain(
     const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Retrieve a block tree entry by its block hash.
+ *
+ * @param[in] chainstate_manager Non-null.
+ * @param[in] block_hash         Non-null.
+ * @return                       The block tree entry of the block with the passed in hash, or null if
+ *                               the block hash is not found.
+ */
+BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_block_tree_entry_by_hash(
+    const btck_ChainstateManager* chainstate_manager,
+    const btck_BlockHash* block_hash) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
 /**
  * Destroy the chainstate manager.
  */
@@ -1065,6 +1102,15 @@ BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_count_trans
 BITCOINKERNEL_API const btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_transaction_at(
     const btck_Block* block, size_t transaction_index) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Calculate and return the hash of a block.
+ *
+ * @param[in] block Non-null.
+ * @return    The block hash.
+ */
+BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_hash(
+    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * @brief Serializes the block through the passed in callback to bytes.
  * This is consensus serialization that is also used for the P2P network.
@@ -1130,6 +1176,40 @@ BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT bt
 BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_get_height(
     const btck_Chain* chain) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Get the block tree entry of the genesis block.
+ *
+ * @param[in] chain Non-null.
+ * @return          The block tree entry of the genesis block, or null if the chain is empty.
+ */
+BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_get_genesis(
+    const btck_Chain* chain) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Retrieve a block tree entry by its height in the currently active chain.
+ * Once retrieved there is no guarantee that it remains in the active chain.
+ *
+ * @param[in] chain        Non-null.
+ * @param[in] block_height Height in the chain of the to be retrieved block tree entry.
+ * @return                 The block tree entry at a certain height in the currently active chain, or null
+ *                         if the height is out of bounds.
+ */
+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);
+
+/**
+ * @brief Return true if the passed in chain contains the block tree entry.
+ *
+ * @param[in] chain            Non-null.
+ * @param[in] block_tree_entry Non-null.
+ * @return                     1 if the block_tree_entry is in the chain, 0 otherwise.
+ *
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_contains(
+    const btck_Chain* chain,
+    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
 ///@}
 
 /** @name BlockSpentOutputs
@@ -1282,6 +1362,52 @@ BITCOINKERNEL_API void btck_coin_destroy(btck_Coin* coin);
 
 ///@}
 
+/** @name BlockHash
+ * Functions for working with block hashes.
+ */
+///@{
+
+/**
+ * @brief Create a block hash from its raw data.
+ */
+BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_create(
+    const unsigned char block_hash[32]) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Check if two block hashes are equal.
+ *
+ * @param[in] hash1 Non-null.
+ * @param[in] hash2 Non-null.
+ * @return          0 if the block hashes are not equal.
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_equals(
+    const btck_BlockHash* hash1, const btck_BlockHash* hash2) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Copy a block hash.
+ *
+ * @param[in] block_hash Non-null.
+ * @return               The copied block hash.
+ */
+BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_copy(
+    const btck_BlockHash* block_hash) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Serializes the block hash to bytes.
+ *
+ * @param[in] block_hash     Non-null.
+ * @param[in] output         The serialized block hash.
+ */
+BITCOINKERNEL_API void btck_block_hash_to_bytes(
+    const btck_BlockHash* block_hash, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
+/**
+ * Destroy the block hash.
+ */
+BITCOINKERNEL_API void btck_block_hash_destroy(btck_BlockHash* block_hash);
+
+///@}
+
 #ifdef __cplusplus
 } // extern "C"
 #endif // __cplusplus
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index d9cacab8428..d06878fa6a5 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -7,6 +7,7 @@
 
 #include <kernel/bitcoinkernel.h>
 
+#include <array>
 #include <functional>
 #include <memory>
 #include <optional>
@@ -528,6 +529,53 @@ bool ScriptPubkeyApi<Derived>::Verify(int64_t amount,
     return result == 1;
 }
 
+template <typename Derived>
+class BlockHashApi
+{
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
+
+public:
+    bool operator==(const Derived& other) const
+    {
+        return btck_block_hash_equals(impl(), other.get()) != 0;
+    }
+
+    bool operator!=(const Derived& other) const
+    {
+        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(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:
@@ -550,6 +598,11 @@ public:
 
     MAKE_RANGE_METHOD(Transactions, Block, &Block::CountTransactions, &Block::GetTransaction, *this)
 
+    BlockHash GetHash() const
+    {
+        return BlockHash{btck_block_get_hash(get())};
+    }
+
     std::vector<std::byte> ToBytes() const
     {
         return write_bytes(get(), btck_block_to_bytes);
@@ -613,6 +666,16 @@ public:
         if (!entry) return std::nullopt;
         return entry;
     }
+
+    int32_t GetHeight() const
+    {
+        return btck_block_tree_entry_get_height(get());
+    }
+
+    BlockHashView GetHash() const
+    {
+        return BlockHashView{btck_block_tree_entry_get_block_hash(get())};
+    }
 };
 
 class KernelNotifications
@@ -788,6 +851,30 @@ public:
     {
         return btck_chain_get_height(get());
     }
+
+    int CountEntries() const
+    {
+        return btck_chain_get_height(get()) + 1;
+    }
+
+    BlockTreeEntry Genesis() const
+    {
+        return btck_chain_get_genesis(get());
+    }
+
+    BlockTreeEntry GetByHeight(int 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");
+        return index;
+    }
+
+    bool Contains(BlockTreeEntry& entry) const
+    {
+        return btck_chain_contains(get(), entry.get());
+    }
+
+    MAKE_RANGE_METHOD(Entries, ChainView, &ChainView::CountEntries, &ChainView::GetByHeight, *this)
 };
 
 template <typename Derived>
@@ -924,6 +1011,13 @@ public:
         return ChainView{btck_chainstate_manager_get_active_chain(get())};
     }
 
+    std::optional<BlockTreeEntry> GetBlockTreeEntry(const BlockHash& block_hash) const
+    {
+        auto entry{btck_chainstate_manager_get_block_tree_entry_by_hash(get(), block_hash.get())};
+        if (!entry) return std::nullopt;
+        return entry;
+    }
+
     std::optional<Block> ReadBlock(const BlockTreeEntry& entry) const
     {
         auto block{btck_block_read(get(), entry.get())};
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index 525c5f9f93b..fca76f4fbc1 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -634,6 +634,39 @@ void chainman_reindex_test(TestDirectory& test_directory)
 
     std::vector<std::string> import_files;
     BOOST_CHECK(chainman->ImportBlocks(import_files));
+
+    // Sanity check some block retrievals
+    auto chain{chainman->GetChain()};
+    BOOST_CHECK_THROW(chain.GetByHeight(1000), std::runtime_error);
+    auto genesis_index{chain.Genesis()};
+    BOOST_CHECK(!genesis_index.GetPrevious());
+    auto genesis_block_raw{chainman->ReadBlock(genesis_index).value().ToBytes()};
+    auto first_index{chain.GetByHeight(0)};
+    auto first_block_raw{chainman->ReadBlock(genesis_index).value().ToBytes()};
+    check_equal(genesis_block_raw, first_block_raw);
+    auto height{first_index.GetHeight()};
+    BOOST_CHECK_EQUAL(height, 0);
+
+    auto next_index{chain.GetByHeight(first_index.GetHeight() + 1)};
+    BOOST_CHECK(chain.Contains(next_index));
+    auto next_block_data{chainman->ReadBlock(next_index).value().ToBytes()};
+    auto tip_index{chain.Tip()};
+    auto tip_block_data{chainman->ReadBlock(tip_index).value().ToBytes()};
+    auto second_index{chain.GetByHeight(1)};
+    auto second_block{chainman->ReadBlock(second_index).value()};
+    auto second_block_data{second_block.ToBytes()};
+    auto second_height{second_index.GetHeight()};
+    BOOST_CHECK_EQUAL(second_height, 1);
+    check_equal(next_block_data, tip_block_data);
+    check_equal(next_block_data, second_block_data);
+
+    auto second_hash{second_index.GetHash()};
+    auto another_second_index{chainman->GetBlockTreeEntry(second_hash)};
+    BOOST_CHECK(another_second_index);
+    auto another_second_height{another_second_index->GetHeight()};
+    auto second_block_hash{second_block.GetHash()};
+    check_equal(second_block_hash.ToBytes(), second_hash.ToBytes());
+    BOOST_CHECK_EQUAL(second_height, another_second_height);
 }
 
 void chainman_reindex_chainstate_test(TestDirectory& test_directory)
@@ -722,6 +755,21 @@ BOOST_AUTO_TEST_CASE(btck_chainman_mainnet_tests)
     chainman_reindex_chainstate_test(test_directory);
 }
 
+BOOST_AUTO_TEST_CASE(btck_block_hash_tests)
+{
+    std::array<std::byte, 32> test_hash;
+    std::array<std::byte, 32> test_hash_2;
+    for (int i = 0; i < 32; ++i) {
+        test_hash[i] = static_cast<std::byte>(i);
+        test_hash_2[i] = static_cast<std::byte>(i + 1);
+    }
+    BlockHash block_hash{test_hash};
+    BlockHash block_hash_2{test_hash_2};
+    BOOST_CHECK(block_hash != block_hash_2);
+    BOOST_CHECK(block_hash == block_hash);
+    CheckHandle(block_hash, block_hash_2);
+}
+
 BOOST_AUTO_TEST_CASE(btck_chainman_in_memory_tests)
 {
     auto in_memory_test_directory{TestDirectory{"in-memory_test_bitcoin_kernel"}};
@@ -824,6 +872,31 @@ BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
         }
     }
 
+    CheckRange(chain.Entries(), chain.CountEntries());
+
+    for (const BlockTreeEntry entry : chain.Entries()) {
+        std::optional<Block> block{chainman->ReadBlock(entry)};
+        if (block) {
+            for (const TransactionView transaction : block->Transactions()) {
+                for (const TransactionOutputView output : transaction.Outputs()) {
+                    // skip data carrier outputs
+                    if ((unsigned char)output.GetScriptPubkey().ToBytes()[0] == 0x6a) {
+                        continue;
+                    }
+                    BOOST_CHECK_GT(output.Amount(), 1);
+                }
+            }
+        }
+    }
+
+    int32_t count{0};
+    for (const auto entry : chain.Entries()) {
+        BOOST_CHECK_EQUAL(entry.GetHeight(), count);
+        ++count;
+    }
+    BOOST_CHECK_EQUAL(count, chain.CountEntries());
+
+
     std::filesystem::remove_all(test_directory.m_directory / "blocks" / "blk00000.dat");
     BOOST_CHECK(!chainman->ReadBlock(tip_2).has_value());
     std::filesystem::remove_all(test_directory.m_directory / "blocks" / "rev00000.dat");

From 36ec9a3ea2322adf8d73e711fb17cf2a64f5bcaa Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Fri, 19 Sep 2025 22:14:54 +0200
Subject: [PATCH 20/23] Kernel: Add functions for working with outpoints

This introduces the transaction outpoint, input and id types. This now
allows a user to retrieve a transaction output from a prior transaction
that a transaction outpoint is pointing to by either scanning through
all available transactions, or maintaining a data structure for lookups.

This is exercised in the tests by verifying the script of every
transaction in the test chain.
---
 src/kernel/bitcoinkernel.cpp       |  68 +++++++++++++
 src/kernel/bitcoinkernel.h         | 154 ++++++++++++++++++++++++++++-
 src/kernel/bitcoinkernel_wrapper.h | 125 +++++++++++++++++++++++
 src/test/kernel/test_kernel.cpp    |  71 +++++++++++++
 4 files changed, 417 insertions(+), 1 deletion(-)

diff --git a/src/kernel/bitcoinkernel.cpp b/src/kernel/bitcoinkernel.cpp
index 531df3c8be8..8bba3cf1c0c 100644
--- a/src/kernel/bitcoinkernel.cpp
+++ b/src/kernel/bitcoinkernel.cpp
@@ -491,6 +491,9 @@ struct btck_BlockSpentOutputs : Handle<btck_BlockSpentOutputs, std::shared_ptr<C
 struct btck_TransactionSpentOutputs : Handle<btck_TransactionSpentOutputs, CTxUndo> {};
 struct btck_Coin : Handle<btck_Coin, Coin> {};
 struct btck_BlockHash : Handle<btck_BlockHash, uint256> {};
+struct btck_TransactionInput : Handle<btck_TransactionInput, CTxIn> {};
+struct btck_TransactionOutPoint: Handle<btck_TransactionOutPoint, COutPoint> {};
+struct btck_Txid: Handle<btck_Txid, Txid> {};
 
 btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
 {
@@ -519,6 +522,17 @@ size_t btck_transaction_count_inputs(const btck_Transaction* transaction)
     return btck_Transaction::get(transaction)->vin.size();
 }
 
+const btck_TransactionInput* btck_transaction_get_input_at(const btck_Transaction* transaction, size_t input_index)
+{
+    assert(input_index < btck_Transaction::get(transaction)->vin.size());
+    return btck_TransactionInput::ref(&btck_Transaction::get(transaction)->vin[input_index]);
+}
+
+const btck_Txid* btck_transaction_get_txid(const btck_Transaction* transaction)
+{
+    return btck_Txid::ref(&btck_Transaction::get(transaction)->GetHash());
+}
+
 btck_Transaction* btck_transaction_copy(const btck_Transaction* transaction)
 {
     return btck_Transaction::copy(transaction);
@@ -637,6 +651,60 @@ int btck_script_pubkey_verify(const btck_ScriptPubkey* script_pubkey,
     return result ? 1 : 0;
 }
 
+btck_TransactionInput* btck_transaction_input_copy(const btck_TransactionInput* input)
+{
+    return btck_TransactionInput::copy(input);
+}
+
+const btck_TransactionOutPoint* btck_transaction_input_get_out_point(const btck_TransactionInput* input)
+{
+    return btck_TransactionOutPoint::ref(&btck_TransactionInput::get(input).prevout);
+}
+
+void btck_transaction_input_destroy(btck_TransactionInput* input)
+{
+    delete input;
+}
+
+btck_TransactionOutPoint* btck_transaction_out_point_copy(const btck_TransactionOutPoint* out_point)
+{
+    return btck_TransactionOutPoint::copy(out_point);
+}
+
+uint32_t btck_transaction_out_point_get_index(const btck_TransactionOutPoint* out_point)
+{
+    return btck_TransactionOutPoint::get(out_point).n;
+}
+
+const btck_Txid* btck_transaction_out_point_get_txid(const btck_TransactionOutPoint* out_point)
+{
+    return btck_Txid::ref(&btck_TransactionOutPoint::get(out_point).hash);
+}
+
+void btck_transaction_out_point_destroy(btck_TransactionOutPoint* out_point)
+{
+    delete out_point;
+}
+
+btck_Txid* btck_txid_copy(const btck_Txid* txid)
+{
+    return btck_Txid::copy(txid);
+}
+
+void btck_txid_to_bytes(const btck_Txid* txid, unsigned char output[32])
+{
+    std::memcpy(output, btck_Txid::get(txid).begin(), 32);
+}
+
+int btck_txid_equals(const btck_Txid* txid1, const btck_Txid* txid2)
+{
+    return btck_Txid::get(txid1) == btck_Txid::get(txid2);
+}
+
+void btck_txid_destroy(btck_Txid* txid)
+{
+    delete txid;
+}
 
 void btck_logging_set_options(const btck_LoggingOptions options)
 {
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index e9283e3da3c..14cd8145b11 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -249,6 +249,22 @@ typedef struct btck_Coin btck_Coin;
  */
 typedef struct btck_BlockHash btck_BlockHash;
 
+/**
+ * Opaque data structure for holding a transaction input.
+ *
+ * Holds information on the @ref btck_TransactionOutPoint held within.
+ */
+typedef struct btck_TransactionInput btck_TransactionInput;
+
+/**
+ * Opaque data structure for holding a transaction out point.
+ *
+ * Holds the txid and output index it is pointing to.
+ */
+typedef struct btck_TransactionOutPoint btck_TransactionOutPoint;
+
+typedef struct btck_Txid btck_Txid;
+
 /** Current sync state passed to tip changed callbacks. */
 typedef uint8_t btck_SynchronizationState;
 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
@@ -498,6 +514,18 @@ BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_count
 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 transaction input at the provided index. The returned
+ * transaction input is not owned and depends on the lifetime of the
+ * transaction.
+ *
+ * @param[in] transaction Non-null.
+ * @param[in] input_index The index of the transaction input to be retrieved.
+ * @return                 The transaction input
+ */
+BITCOINKERNEL_API const btck_TransactionInput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_get_input_at(
+    const btck_Transaction* transaction, size_t input_index) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * @brief Get the number of inputs of a transaction.
  *
@@ -507,6 +535,16 @@ BITCOINKERNEL_API const btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT
 BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_count_inputs(
     const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @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.
+ */
+BITCOINKERNEL_API const btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_get_txid(
+    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * Destroy the transaction.
  */
@@ -1313,6 +1351,119 @@ BITCOINKERNEL_API void btck_transaction_spent_outputs_destroy(btck_TransactionSp
 
 ///@}
 
+/** @name Transaction Input
+ * Functions for working with transaction inputs.
+ */
+///@{
+
+/**
+ * @brief Copy a transaction input.
+ *
+ * @param[in] transaction_input Non-null.
+ * @return                      The copied transaction input.
+ */
+BITCOINKERNEL_API btck_TransactionInput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_copy(
+    const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the transaction out point. The returned transaction out point is
+ * not owned and depends on the lifetime of the transaction.
+ *
+ * @param[in] transaction_input Non-null.
+ * @return                      The transaction out point.
+ */
+BITCOINKERNEL_API const btck_TransactionOutPoint* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_get_out_point(
+    const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the transaction input.
+ */
+BITCOINKERNEL_API void btck_transaction_input_destroy(btck_TransactionInput* transaction_input);
+
+///@}
+
+/** @name Transaction Out Point
+ * Functions for working with transaction out points.
+ */
+///@{
+
+/**
+ * @brief Copy a transaction out point.
+ *
+ * @param[in] transaction_out_point Non-null.
+ * @return                          The copied transaction out point.
+ */
+BITCOINKERNEL_API btck_TransactionOutPoint* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_copy(
+    const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the output position from the transaction out point.
+ *
+ * @param[in] transaction_out_point Non-null.
+ * @return                          The output index.
+ */
+BITCOINKERNEL_API uint32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_get_index(
+    const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @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.
+ */
+BITCOINKERNEL_API const btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_get_txid(
+    const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the transaction out point.
+ */
+BITCOINKERNEL_API void btck_transaction_out_point_destroy(btck_TransactionOutPoint* transaction_out_point);
+
+///@}
+
+/** @name Txid
+ * Functions for working with txids.
+ */
+///@{
+
+/**
+ * @brief Copy a txid.
+ *
+ * @param[in] txid Non-null.
+ * @return         The copied txid.
+ */
+BITCOINKERNEL_API btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_txid_copy(
+    const btck_Txid* txid) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Check if two txids are equal.
+ *
+ * @param[in] txid1 Non-null.
+ * @param[in] txid2 Non-null.
+ * @return          0 if the txid is not equal.
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_txid_equals(
+    const btck_Txid* txid1, const btck_Txid* txid2) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Serializes the txid to bytes.
+ *
+ * @param[in] txid    Non-null.
+ * @param[out] output The serialized txid.
+ */
+BITCOINKERNEL_API void btck_txid_to_bytes(
+    const btck_Txid* txid, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
+/**
+ * Destroy the txid.
+ */
+BITCOINKERNEL_API void btck_txid_destroy(btck_Txid* txid);
+
+///@}
+
+///@}
+
 /** @name Coin
  * Functions for working with coins.
  */
@@ -1328,7 +1479,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.
diff --git a/src/kernel/bitcoinkernel_wrapper.h b/src/kernel/bitcoinkernel_wrapper.h
index d06878fa6a5..06a4ccfaa01 100644
--- a/src/kernel/bitcoinkernel_wrapper.h
+++ b/src/kernel/bitcoinkernel_wrapper.h
@@ -451,6 +451,119 @@ public:
         : Handle(view) {}
 };
 
+template <typename Derived>
+class TxidApi
+{
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
+
+    friend Derived;
+    TxidApi() = default;
+
+public:
+    bool operator==(const TxidApi& other) const
+    {
+        return btck_txid_equals(impl(), other.impl()) != 0;
+    }
+
+    bool operator!=(const TxidApi& other) const
+    {
+        return btck_txid_equals(impl(), other.impl()) == 0;
+    }
+
+    std::array<std::byte, 32> ToBytes() const
+    {
+        std::array<std::byte, 32> hash;
+        btck_txid_to_bytes(impl(), reinterpret_cast<unsigned char*>(hash.data()));
+        return hash;
+    }
+};
+
+class TxidView : public View<btck_Txid>, public TxidApi<TxidView>
+{
+public:
+    explicit TxidView(const btck_Txid* ptr) : View{ptr} {}
+};
+
+class Txid : public Handle<btck_Txid, btck_txid_copy, btck_txid_destroy>, public TxidApi<Txid>
+{
+public:
+    Txid(const TxidView& view)
+        : Handle(view) {}
+};
+
+template <typename Derived>
+class OutPointApi
+{
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
+
+    friend Derived;
+    OutPointApi() = default;
+
+public:
+    uint32_t index() const
+    {
+        return btck_transaction_out_point_get_index(impl());
+    }
+
+    TxidView Txid() const
+    {
+        return TxidView{btck_transaction_out_point_get_txid(impl())};
+    }
+};
+
+class OutPointView : public View<btck_TransactionOutPoint>, public OutPointApi<OutPointView>
+{
+public:
+    explicit OutPointView(const btck_TransactionOutPoint* ptr) : View{ptr} {}
+};
+
+class OutPoint : public Handle<btck_TransactionOutPoint, btck_transaction_out_point_copy, btck_transaction_out_point_destroy>, public OutPointApi<OutPoint>
+{
+public:
+    OutPoint(const OutPointView& view)
+        : Handle(view) {}
+};
+
+template <typename Derived>
+class TransactionInputApi
+{
+private:
+    auto impl() const
+    {
+        return static_cast<const Derived*>(this)->get();
+    }
+
+    friend Derived;
+    TransactionInputApi() = default;
+
+public:
+    OutPointView OutPoint() const
+    {
+        return OutPointView{btck_transaction_input_get_out_point(impl())};
+    }
+};
+
+class TransactionInputView : public View<btck_TransactionInput>, public TransactionInputApi<TransactionInputView>
+{
+public:
+    explicit TransactionInputView(const btck_TransactionInput* ptr) : View{ptr} {}
+};
+
+class TransactionInput : public Handle<btck_TransactionInput, btck_transaction_input_copy, btck_transaction_input_destroy>, public TransactionInputApi<TransactionInput>
+{
+public:
+    TransactionInput(const TransactionInputView& view)
+        : Handle(view) {}
+};
+
 template <typename Derived>
 class TransactionApi
 {
@@ -476,8 +589,20 @@ public:
         return TransactionOutputView{btck_transaction_get_output_at(impl(), index)};
     }
 
+    TransactionInputView GetInput(size_t index) const
+    {
+        return TransactionInputView{btck_transaction_get_input_at(impl(), index)};
+    }
+
+    TxidView Txid() const
+    {
+        return TxidView{btck_transaction_get_txid(impl())};
+    }
+
     MAKE_RANGE_METHOD(Outputs, Derived, &TransactionApi<Derived>::CountOutputs, &TransactionApi<Derived>::GetOutput, *static_cast<const Derived*>(this))
 
+    MAKE_RANGE_METHOD(Inputs, Derived, &TransactionApi<Derived>::CountInputs, &TransactionApi<Derived>::GetInput, *static_cast<const Derived*>(this))
+
     std::vector<std::byte> ToBytes() const
     {
         return write_bytes(impl(), btck_transaction_to_bytes);
diff --git a/src/test/kernel/test_kernel.cpp b/src/test/kernel/test_kernel.cpp
index fca76f4fbc1..d9875ee16e0 100644
--- a/src/test/kernel/test_kernel.cpp
+++ b/src/test/kernel/test_kernel.cpp
@@ -14,6 +14,7 @@
 #include <cstdint>
 #include <cstdlib>
 #include <filesystem>
+#include <format>
 #include <iostream>
 #include <memory>
 #include <optional>
@@ -61,6 +62,19 @@ std::vector<std::byte> hex_string_to_byte_vec(std::string_view hex)
     return bytes;
 }
 
+std::string byte_span_to_hex_string_reversed(std::span<const std::byte> bytes)
+{
+    std::ostringstream oss;
+
+    // Iterate in reverse order
+    for (auto it = bytes.rbegin(); it != bytes.rend(); ++it) {
+        oss << std::hex << std::setw(2) << std::setfill('0')
+            << static_cast<unsigned int>(static_cast<uint8_t>(*it));
+    }
+
+    return oss.str();
+}
+
 constexpr auto VERIFY_ALL_PRE_SEGWIT{ScriptVerificationFlags::P2SH | ScriptVerificationFlags::DERSIG |
                                      ScriptVerificationFlags::NULLDUMMY | ScriptVerificationFlags::CHECKLOCKTIMEVERIFY |
                                      ScriptVerificationFlags::CHECKSEQUENCEVERIFY};
@@ -465,6 +479,18 @@ BOOST_AUTO_TEST_CASE(btck_transaction_output)
     CheckHandle(output, output2);
 }
 
+BOOST_AUTO_TEST_CASE(btck_transaction_input)
+{
+    Transaction tx{hex_string_to_byte_vec("020000000248c03e66fd371c7033196ce24298628e59ebefa00363026044e0f35e0325a65d000000006a473044022004893432347f39beaa280e99da595681ddb20fc45010176897e6e055d716dbfa022040a9e46648a5d10c33ef7cee5e6cf4b56bd513eae3ae044f0039824b02d0f44c012102982331a52822fd9b62e9b5d120da1d248558fac3da3a3c51cd7d9c8ad3da760efeffffffb856678c6e4c3c84e39e2ca818807049d6fba274b42af3c6d3f9d4b6513212d2000000006a473044022068bcedc7fe39c9f21ad318df2c2da62c2dc9522a89c28c8420ff9d03d2e6bf7b0220132afd752754e5cb1ea2fd0ed6a38ec666781e34b0e93dc9a08f2457842cf5660121033aeb9c079ea3e08ea03556182ab520ce5c22e6b0cb95cee6435ee17144d860cdfeffffff0260d50b00000000001976a914363cc8d55ea8d0500de728ef6d63804ddddbdc9888ac67040f00000000001976a914c303bdc5064bf9c9a8b507b5496bd0987285707988ac6acb0700")};
+    TransactionInput input_0 = tx.GetInput(0);
+    TransactionInput input_1 = tx.GetInput(1);
+    CheckHandle(input_0, input_1);
+    CheckRange(tx.Inputs(), tx.CountInputs());
+    OutPoint point_0 = input_0.OutPoint();
+    OutPoint point_1 = input_1.OutPoint();
+    CheckHandle(point_0, point_1);
+}
+
 BOOST_AUTO_TEST_CASE(btck_script_verify_tests)
 {
     // Legacy transaction aca326a724eda9a461c10a876534ecd5ae7b27f10f26c3862fb996f80ea2d45d
@@ -702,6 +728,7 @@ void chainman_mainnet_validation_test(TestDirectory& test_directory)
     auto raw_block = hex_string_to_byte_vec("010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e362990101000000010000000000000000000000000000000000000000000000000000000000000000ffffffff0704ffff001d0104ffffffff0100f2052a0100000043410496b538e853519c726a2c91e61ec11600ae1390813a627c66fb8be7947be63c52da7589379515d4e0a604f8141781e62294721166bf621e73a82cbf2342c858eeac00000000");
     Block block{raw_block};
     TransactionView tx{block.GetTransaction(block.CountTransactions() - 1)};
+    BOOST_CHECK_EQUAL(byte_span_to_hex_string_reversed(tx.Txid().ToBytes()), "0e3e2357e806b6cdb1f70b54c3a3a17b6714ee1f0e68bebb44a74b1efd512098");
     BOOST_CHECK_EQUAL(tx.CountInputs(), 1);
     Transaction tx2 = tx;
     BOOST_CHECK_EQUAL(tx2.CountInputs(), 1);
@@ -832,6 +859,50 @@ BOOST_AUTO_TEST_CASE(btck_chainman_regtest_tests)
     auto read_block_2 = chainman->ReadBlock(tip_2).value();
     check_equal(read_block_2.ToBytes(), hex_string_to_byte_vec(REGTEST_BLOCK_DATA[REGTEST_BLOCK_DATA.size() - 2]));
 
+    Txid txid = read_block.Transactions()[0].Txid();
+    Txid txid_2 = read_block_2.Transactions()[0].Txid();
+    BOOST_CHECK(txid != txid_2);
+    BOOST_CHECK(txid == txid);
+    CheckHandle(txid, txid_2);
+
+    auto find_transaction = [&chainman](const TxidView& target_txid) -> std::optional<Transaction> {
+        auto chain = chainman->GetChain();
+        for (const auto block_tree_entry : chain.Entries()) {
+            auto block{chainman->ReadBlock(block_tree_entry)};
+            for (const TransactionView transaction : block->Transactions()) {
+                if (transaction.Txid() == target_txid) {
+                    return Transaction{transaction};
+                }
+            }
+        }
+        return std::nullopt;
+    };
+
+    for (const auto block_tree_entry : chain.Entries()) {
+        auto block{chainman->ReadBlock(block_tree_entry)};
+        for (const auto transaction : block->Transactions()) {
+            std::vector<TransactionInput> inputs;
+            std::vector<TransactionOutput> spent_outputs;
+            for (const auto input : transaction.Inputs()) {
+                OutPointView point = input.OutPoint();
+                if (point.index() == std::numeric_limits<uint32_t>::max()) {
+                    continue;
+                }
+                inputs.emplace_back(input);
+                BOOST_CHECK(point.Txid() != transaction.Txid());
+                std::optional<Transaction> tx = find_transaction(point.Txid());
+                BOOST_CHECK(tx.has_value());
+                BOOST_CHECK(point.Txid() == tx->Txid());
+                spent_outputs.emplace_back(tx->GetOutput(point.index()));
+            }
+            BOOST_CHECK(inputs.size() == spent_outputs.size());
+            ScriptVerifyStatus status = ScriptVerifyStatus::OK;
+            for (size_t i{0}; i < inputs.size(); ++i) {
+                BOOST_CHECK(spent_outputs[i].GetScriptPubkey().Verify(spent_outputs[i].Amount(), transaction, spent_outputs, i, ScriptVerificationFlags::ALL, status));
+            }
+        }
+    }
+
     // Read spent outputs for current tip and its previous block
     BlockSpentOutputs block_spent_outputs{chainman->ReadBlockSpentOutputs(tip)};
     BlockSpentOutputs block_spent_outputs_prev{chainman->ReadBlockSpentOutputs(*tip.GetPrevious())};

From 7990463b1059ba5fc4ebe37fd1105a9e168ae20d Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Fri, 14 Jun 2024 18:33:08 +0200
Subject: [PATCH 21/23] kernel: Add pure kernel bitcoin-chainstate

Re-write the bitcoin-chainstate utility by only using the kernel C++ API
header instead of internal Bitcoin Core code.
---
 .github/workflows/ci.yml          |   5 +-
 src/CMakeLists.txt                |  43 ++--
 src/bitcoin-chainstate.cpp        | 408 +++++++++++++-----------------
 test/lint/test_runner/src/main.rs |   1 +
 4 files changed, 197 insertions(+), 260 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8370afd88f0..6cc7be84688 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -202,7 +202,7 @@ jobs:
         job-type: [standard, fuzz]
         include:
           - job-type: standard
-            generate-options: '-DBUILD_GUI=ON -DWITH_ZMQ=ON -DBUILD_BENCH=ON -DBUILD_KERNEL_LIB=ON -DWERROR=ON'
+            generate-options: '-DBUILD_GUI=ON -DWITH_ZMQ=ON -DBUILD_BENCH=ON -DBUILD_KERNEL_LIB=ON -DBUILD_UTIL_CHAINSTATE=ON -DWERROR=ON'
             job-name: 'Windows native, VS 2022'
           - job-type: fuzz
             generate-options: '-DVCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON -DVCPKG_MANIFEST_FEATURES="wallet" -DBUILD_GUI=OFF -DBUILD_FOR_FUZZING=ON -DWERROR=ON'
@@ -280,7 +280,7 @@ jobs:
             $exeName = $_.Name
 
             # Skip as they currently do not have manifests
-            if ($exeName -eq "fuzz.exe" -or $exeName -eq "bench_bitcoin.exe" -or $exeName -eq "test_bitcoin-qt.exe" -or $exeName -eq "test_kernel.exe") {
+            if ($exeName -eq "fuzz.exe" -or $exeName -eq "bench_bitcoin.exe" -or $exeName -eq "test_bitcoin-qt.exe" -or $exeName -eq "test_kernel.exe" -or $exeName -eq "bitcoin-chainstate.exe") {
               Write-Host "Skipping $exeName (no manifest present)"
               return
             }
@@ -307,6 +307,7 @@ jobs:
           BITCOINTX: '${{ github.workspace }}\build\bin\Release\bitcoin-tx.exe'
           BITCOINUTIL: '${{ github.workspace }}\build\bin\Release\bitcoin-util.exe'
           BITCOINWALLET: '${{ github.workspace }}\build\bin\Release\bitcoin-wallet.exe'
+          BITCOINCHAINSTATE: '${{ github.workspace }}\build\bin\Release\bitcoin-chainstate.exe'
           TEST_RUNNER_EXTRA: ${{ github.event_name != 'pull_request' && '--extended' || '' }}
         run: py -3 test/functional/test_runner.py --jobs $NUMBER_OF_PROCESSORS --ci --quiet --tmpdirprefix="${RUNNER_TEMP}" --combinedlogslen=99999999 --timeout-factor=${TEST_RUNNER_TIMEOUT_FACTOR} ${TEST_RUNNER_EXTRA}
 
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 7c7e0fe718a..aed40610bea 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -407,28 +407,27 @@ if(BUILD_KERNEL_LIB)
   if (BUILD_KERNEL_TEST)
     add_subdirectory(test/kernel)
   endif()
-endif()
-
-if(BUILD_UTIL_CHAINSTATE)
-  add_executable(bitcoin-chainstate
-    bitcoin-chainstate.cpp
-  )
-  add_windows_application_manifest(bitcoin-chainstate)
-  # TODO: The `SKIP_BUILD_RPATH` property setting can be deleted
-  #       in the future after reordering Guix script commands to
-  #       perform binary checks after the installation step.
-  # Relevant discussions:
-  # - https://github.com/hebasto/bitcoin/pull/236#issuecomment-2183120953
-  # - https://github.com/bitcoin/bitcoin/pull/30312#issuecomment-2191235833
-  set_target_properties(bitcoin-chainstate PROPERTIES
-    SKIP_BUILD_RPATH OFF
-  )
-  target_link_libraries(bitcoin-chainstate
-    PRIVATE
-      core_interface
-      bitcoinkernel
-  )
-  install_binary_component(bitcoin-chainstate INTERNAL)
+  if(BUILD_UTIL_CHAINSTATE)
+    add_executable(bitcoin-chainstate
+      bitcoin-chainstate.cpp
+    )
+    add_windows_application_manifest(bitcoin-chainstate)
+    # TODO: The `SKIP_BUILD_RPATH` property setting can be deleted
+    #       in the future after reordering Guix script commands to
+    #       perform binary checks after the installation step.
+    # Relevant discussions:
+    # - https://github.com/hebasto/bitcoin/pull/236#issuecomment-2183120953
+    # - https://github.com/bitcoin/bitcoin/pull/30312#issuecomment-2191235833
+    set_target_properties(bitcoin-chainstate PROPERTIES
+      SKIP_BUILD_RPATH OFF
+    )
+    target_link_libraries(bitcoin-chainstate
+      PRIVATE
+        core_interface
+        bitcoinkernel
+    )
+    install_binary_component(bitcoin-chainstate INTERNAL)
+  endif()
 endif()
 
 
diff --git a/src/bitcoin-chainstate.cpp b/src/bitcoin-chainstate.cpp
index 46e6f06e27f..310ca95c085 100644
--- a/src/bitcoin-chainstate.cpp
+++ b/src/bitcoin-chainstate.cpp
@@ -1,53 +1,135 @@
-// Copyright (c) 2022 The Bitcoin Core developers
-// Distributed under the MIT software license, see the accompanying
-// file COPYING or http://www.opensource.org/licenses/mit-license.php.
-//
-// The bitcoin-chainstate executable serves to surface the dependencies required
-// by a program wishing to use Bitcoin Core's consensus engine as it is right
-// now.
-//
-// DEVELOPER NOTE: Since this is a "demo-only", experimental, etc. executable,
-//                 it may diverge from Bitcoin Core's coding style.
-//
-// It is part of the libbitcoinkernel project.
-
-#include <kernel/chainparams.h>
-#include <kernel/chainstatemanager_opts.h>
-#include <kernel/checks.h>
-#include <kernel/context.h>
-#include <kernel/warning.h>
-
-#include <consensus/validation.h>
-#include <core_io.h>
-#include <kernel/caches.h>
-#include <logging.h>
-#include <node/blockstorage.h>
-#include <node/chainstate.h>
-#include <random.h>
-#include <script/sigcache.h>
-#include <util/chaintype.h>
-#include <util/fs.h>
-#include <util/signalinterrupt.h>
-#include <util/task_runner.h>
-#include <util/translation.h>
-#include <validation.h>
-#include <validationinterface.h>
+#include <kernel/bitcoinkernel_wrapper.h>
 
 #include <cassert>
-#include <cstdint>
-#include <functional>
-#include <iosfwd>
-#include <memory>
+#include <charconv>
+#include <filesystem>
+#include <iostream>
+#include <optional>
 #include <string>
+#include <string_view>
+#include <vector>
+
+using namespace btck;
+
+std::vector<std::byte> hex_string_to_byte_vec(std::string_view hex)
+{
+    std::vector<std::byte> bytes;
+    bytes.reserve(hex.length() / 2);
+
+    for (size_t i{0}; i < hex.length(); i += 2) {
+        uint8_t byte_value;
+        auto [ptr, ec] = std::from_chars(hex.data() + i, hex.data() + i + 2, byte_value, 16);
+
+        if (ec != std::errc{} || ptr != hex.data() + i + 2) {
+            throw std::invalid_argument("Invalid hex character");
+        }
+        bytes.push_back(static_cast<std::byte>(byte_value));
+    }
+    return bytes;
+}
+
+class KernelLog
+{
+public:
+    void LogMessage(std::string_view message)
+    {
+        std::cout << "kernel: " << message;
+    }
+};
+
+class TestValidationInterface : public ValidationInterface
+{
+public:
+    TestValidationInterface() = default;
+
+    std::optional<std::string> m_expected_valid_block = std::nullopt;
+
+    void BlockChecked(const Block block, const BlockValidationState state) override
+    {
+        auto mode{state.GetValidationMode()};
+        switch (mode) {
+        case ValidationMode::VALID: {
+            std::cout << "Valid block" << std::endl;
+            return;
+        }
+        case ValidationMode::INVALID: {
+            std::cout << "Invalid block: ";
+            auto result{state.GetBlockValidationResult()};
+            switch (result) {
+            case BlockValidationResult::UNSET:
+                std::cout << "initial value. Block has not yet been rejected" << std::endl;
+                break;
+            case BlockValidationResult::HEADER_LOW_WORK:
+                std::cout << "the block header may be on a too-little-work chain" << std::endl;
+                break;
+            case BlockValidationResult::CONSENSUS:
+                std::cout << "invalid by consensus rules" << std::endl;
+                break;
+            case BlockValidationResult::CACHED_INVALID:
+                std::cout << "this block was cached as being invalid and we didn't store the reason why" << std::endl;
+                break;
+            case BlockValidationResult::INVALID_HEADER:
+                std::cout << "invalid proof of work or time too old" << std::endl;
+                break;
+            case BlockValidationResult::MUTATED:
+                std::cout << "the block's data didn't match the data committed to by the PoW" << std::endl;
+                break;
+            case BlockValidationResult::MISSING_PREV:
+                std::cout << "We don't have the previous block the checked one is built on" << std::endl;
+                break;
+            case BlockValidationResult::INVALID_PREV:
+                std::cout << "A block this one builds on is invalid" << std::endl;
+                break;
+            case BlockValidationResult::TIME_FUTURE:
+                std::cout << "block timestamp was > 2 hours in the future (or our clock is bad)" << std::endl;
+                break;
+            }
+            return;
+        }
+        case ValidationMode::INTERNAL_ERROR: {
+            std::cout << "Internal error" << std::endl;
+            return;
+        }
+        }
+    }
+};
+
+class TestKernelNotifications : public KernelNotifications
+{
+public:
+    void BlockTipHandler(SynchronizationState, const BlockTreeEntry, double) override
+    {
+        std::cout << "Block tip changed" << std::endl;
+    }
+
+    void ProgressHandler(std::string_view title, int progress_percent, bool resume_possible) override
+    {
+        std::cout << "Made progress: " << title << " " << progress_percent << "%" << std::endl;
+    }
+
+    void WarningSetHandler(Warning warning, std::string_view message) override
+    {
+        std::cout << message << std::endl;
+    }
+
+    void WarningUnsetHandler(Warning warning) override
+    {
+        std::cout << "Warning unset: " << static_cast<std::underlying_type_t<Warning>>(warning) << std::endl;
+    }
+
+    void FlushErrorHandler(std::string_view error) override
+    {
+        std::cout << error << std::endl;
+    }
+
+    void FatalErrorHandler(std::string_view error) override
+    {
+        std::cout << error << std::endl;
+    }
+};
 
 int main(int argc, char* argv[])
 {
-    // We do not enable logging for this app, so explicitly disable it.
-    // To enable logging instead, replace with:
-    //    LogInstance().m_print_to_console = true;
-    //    LogInstance().StartLogging();
-    LogInstance().DisableLogging();
-
     // SETUP: Argument parsing and handling
     if (argc != 2) {
         std::cerr
@@ -58,213 +140,67 @@ int main(int argc, char* argv[])
             << "           BREAK IN FUTURE VERSIONS. DO NOT USE ON YOUR ACTUAL DATADIR." << std::endl;
         return 1;
     }
-    fs::path abs_datadir{fs::absolute(argv[1])};
-    fs::create_directories(abs_datadir);
+    std::filesystem::path abs_datadir{std::filesystem::absolute(argv[1])};
+    std::filesystem::create_directories(abs_datadir);
 
-
-    // SETUP: Context
-    kernel::Context kernel_context{};
-    // We can't use a goto here, but we can use an assert since none of the
-    // things instantiated so far requires running the epilogue to be torn down
-    // properly
-    assert(kernel::SanityChecks(kernel_context));
-
-    ValidationSignals validation_signals{std::make_unique<util::ImmediateTaskRunner>()};
-
-    class KernelNotifications : public kernel::Notifications
-    {
-    public:
-        kernel::InterruptResult blockTip(SynchronizationState, const CBlockIndex&, double) override
-        {
-            std::cout << "Block tip changed" << std::endl;
-            return {};
-        }
-        void headerTip(SynchronizationState, int64_t height, int64_t timestamp, bool presync) override
-        {
-            std::cout << "Header tip changed: " << height << ", " << timestamp << ", " << presync << std::endl;
-        }
-        void progress(const bilingual_str& title, int progress_percent, bool resume_possible) override
-        {
-            std::cout << "Progress: " << title.original << ", " << progress_percent << ", " << resume_possible << std::endl;
-        }
-        void warningSet(kernel::Warning id, const bilingual_str& message) override
-        {
-            std::cout << "Warning " << static_cast<int>(id) << " set: " << message.original << std::endl;
-        }
-        void warningUnset(kernel::Warning id) override
-        {
-            std::cout << "Warning " << static_cast<int>(id) << " unset" << std::endl;
-        }
-        void flushError(const bilingual_str& message) override
-        {
-            std::cerr << "Error flushing block data to disk: " << message.original << std::endl;
-        }
-        void fatalError(const bilingual_str& message) override
-        {
-            std::cerr << "Error: " << message.original << std::endl;
-        }
+    btck_LoggingOptions logging_options = {
+        .log_timestamps = true,
+        .log_time_micros = false,
+        .log_threadnames = false,
+        .log_sourcelocations = false,
+        .always_print_category_levels = true,
     };
-    auto notifications = std::make_unique<KernelNotifications>();
 
-    kernel::CacheSizes cache_sizes{DEFAULT_KERNEL_CACHE};
+    logging_set_options(logging_options);
 
-    // SETUP: Chainstate
-    auto chainparams = CChainParams::Main();
-    const ChainstateManager::Options chainman_opts{
-        .chainparams = *chainparams,
-        .datadir = abs_datadir,
-        .notifications = *notifications,
-        .signals = &validation_signals,
-    };
-    const node::BlockManager::Options blockman_opts{
-        .chainparams = chainman_opts.chainparams,
-        .blocks_dir = abs_datadir / "blocks",
-        .notifications = chainman_opts.notifications,
-        .block_tree_db_params = DBParams{
-            .path = abs_datadir / "blocks" / "index",
-            .cache_bytes = cache_sizes.block_tree_db,
-        },
-    };
-    util::SignalInterrupt interrupt;
-    ChainstateManager chainman{interrupt, chainman_opts, blockman_opts};
+    Logger logger{std::make_unique<KernelLog>()};
 
-    node::ChainstateLoadOptions options;
-    auto [status, error] = node::LoadChainstate(chainman, cache_sizes, options);
-    if (status != node::ChainstateLoadStatus::SUCCESS) {
-        std::cerr << "Failed to load Chain state from your datadir." << std::endl;
-        goto epilogue;
-    } else {
-        std::tie(status, error) = node::VerifyLoadedChainstate(chainman, options);
-        if (status != node::ChainstateLoadStatus::SUCCESS) {
-            std::cerr << "Failed to verify loaded Chain state from your datadir." << std::endl;
-            goto epilogue;
-        }
+    ContextOptions options{};
+    ChainParams params{ChainType::MAINNET};
+    options.SetChainParams(params);
+
+    options.SetNotifications(std::make_shared<TestKernelNotifications>());
+    options.SetValidationInterface(std::make_shared<TestValidationInterface>());
+
+    Context context{options};
+
+    ChainstateManagerOptions chainman_opts{context, abs_datadir.string(), (abs_datadir / "blocks").string()};
+    chainman_opts.SetWorkerThreads(4);
+
+    std::unique_ptr<ChainMan> chainman;
+    try {
+        chainman = std::make_unique<ChainMan>(context, chainman_opts);
+    } catch (std::exception&) {
+        std::cerr << "Failed to instantiate ChainMan, exiting" << std::endl;
+        return 1;
     }
 
-    for (Chainstate* chainstate : WITH_LOCK(::cs_main, return chainman.GetAll())) {
-        BlockValidationState state;
-        if (!chainstate->ActivateBestChain(state, nullptr)) {
-            std::cerr << "Failed to connect best block (" << state.ToString() << ")" << std::endl;
-            goto epilogue;
-        }
-    }
-
-    // Main program logic starts here
-    std::cout
-        << "Hello! I'm going to print out some information about your datadir." << std::endl
-        << "\t"
-        << "Path: " << abs_datadir << std::endl;
-    {
-        LOCK(chainman.GetMutex());
-        std::cout
-        << "\t" << "Blockfiles Indexed: " << std::boolalpha << chainman.m_blockman.m_blockfiles_indexed.load() << std::noboolalpha << std::endl
-        << "\t" << "Snapshot Active: " << std::boolalpha << chainman.IsSnapshotActive() << std::noboolalpha << std::endl
-        << "\t" << "Active Height: " << chainman.ActiveHeight() << std::endl
-        << "\t" << "Active IBD: " << std::boolalpha << chainman.IsInitialBlockDownload() << std::noboolalpha << std::endl;
-        CBlockIndex* tip = chainman.ActiveTip();
-        if (tip) {
-            std::cout << "\t" << tip->ToString() << std::endl;
-        }
-    }
+    std::cout << "Enter the block you want to validate on the next line:" << std::endl;
 
     for (std::string line; std::getline(std::cin, line);) {
         if (line.empty()) {
-            std::cerr << "Empty line found" << std::endl;
-            break;
+            std::cerr << "Empty line found, try again:" << std::endl;
+            continue;
         }
 
-        std::shared_ptr<CBlock> blockptr = std::make_shared<CBlock>();
-        CBlock& block = *blockptr;
-
-        if (!DecodeHexBlk(block, line)) {
-            std::cerr << "Block decode failed" << std::endl;
-            break;
+        auto raw_block{hex_string_to_byte_vec(line)};
+        std::unique_ptr<Block> block;
+        try {
+            block = std::make_unique<Block>(raw_block);
+        } catch (std::exception&) {
+            std::cerr << "Block decode failed, try again:" << std::endl;
+            continue;
         }
 
-        {
-            LOCK(cs_main);
-            const CBlockIndex* pindex = chainman.m_blockman.LookupBlockIndex(block.hashPrevBlock);
-            if (pindex) {
-                chainman.UpdateUncommittedBlockStructures(block, pindex);
-            }
+        bool new_block = false;
+        bool accepted = chainman->ProcessBlock(*block, &new_block);
+        if (accepted) {
+            std::cerr << "Block has not yet been rejected" << std::endl;
+        } else {
+            std::cerr << "Block was not accepted" << std::endl;
         }
-
-        // Adapted from rpc/mining.cpp
-        class submitblock_StateCatcher final : public CValidationInterface
-        {
-        public:
-            uint256 hash;
-            bool found;
-            BlockValidationState state;
-
-            explicit submitblock_StateCatcher(const uint256& hashIn) : hash(hashIn), found(false), state() {}
-
-        protected:
-            void BlockChecked(const std::shared_ptr<const CBlock>& block, const BlockValidationState& stateIn) override
-            {
-                if (block->GetHash() != hash)
-                    return;
-                found = true;
-                state = stateIn;
-            }
-        };
-
-        bool new_block;
-        auto sc = std::make_shared<submitblock_StateCatcher>(block.GetHash());
-        validation_signals.RegisterSharedValidationInterface(sc);
-        bool accepted = chainman.ProcessNewBlock(blockptr, /*force_processing=*/true, /*min_pow_checked=*/true, /*new_block=*/&new_block);
-        validation_signals.UnregisterSharedValidationInterface(sc);
-        if (!new_block && accepted) {
-            std::cerr << "duplicate" << std::endl;
-            break;
-        }
-        if (!sc->found) {
-            std::cerr << "inconclusive" << std::endl;
-            break;
-        }
-        std::cout << sc->state.ToString() << std::endl;
-        switch (sc->state.GetResult()) {
-        case BlockValidationResult::BLOCK_RESULT_UNSET:
-            std::cerr << "initial value. Block has not yet been rejected" << std::endl;
-            break;
-        case BlockValidationResult::BLOCK_HEADER_LOW_WORK:
-            std::cerr << "the block header may be on a too-little-work chain" << std::endl;
-            break;
-        case BlockValidationResult::BLOCK_CONSENSUS:
-            std::cerr << "invalid by consensus rules (excluding any below reasons)" << std::endl;
-            break;
-        case BlockValidationResult::BLOCK_CACHED_INVALID:
-            std::cerr << "this block was cached as being invalid and we didn't store the reason why" << std::endl;
-            break;
-        case BlockValidationResult::BLOCK_INVALID_HEADER:
-            std::cerr << "invalid proof of work or time too old" << std::endl;
-            break;
-        case BlockValidationResult::BLOCK_MUTATED:
-            std::cerr << "the block's data didn't match the data committed to by the PoW" << std::endl;
-            break;
-        case BlockValidationResult::BLOCK_MISSING_PREV:
-            std::cerr << "We don't have the previous block the checked one is built on" << std::endl;
-            break;
-        case BlockValidationResult::BLOCK_INVALID_PREV:
-            std::cerr << "A block this one builds on is invalid" << std::endl;
-            break;
-        case BlockValidationResult::BLOCK_TIME_FUTURE:
-            std::cerr << "block timestamp was > 2 hours in the future (or our clock is bad)" << std::endl;
-            break;
-        }
-    }
-
-epilogue:
-    // Without this precise shutdown sequence, there will be a lot of nullptr
-    // dereferencing and UB.
-    validation_signals.FlushBackgroundCallbacks();
-    {
-        LOCK(cs_main);
-        for (Chainstate* chainstate : chainman.GetAll()) {
-            if (chainstate->CanFlushToDisk()) {
-                chainstate->ForceFlushStateToDisk();
-                chainstate->ResetCoinsViews();
-            }
+        if (!new_block) {
+            std::cerr << "Block is a duplicate" << std::endl;
         }
     }
 }
diff --git a/test/lint/test_runner/src/main.rs b/test/lint/test_runner/src/main.rs
index 53d24ca4960..fc00124ae23 100644
--- a/test/lint/test_runner/src/main.rs
+++ b/test/lint/test_runner/src/main.rs
@@ -374,6 +374,7 @@ fn lint_std_filesystem() -> LintResult {
             ":(exclude)src/ipc/libmultiprocess/",
             ":(exclude)src/util/fs.h",
             ":(exclude)src/test/kernel/test_kernel.cpp",
+            ":(exclude)src/bitcoin-chainstate.cpp",
         ])
         .status()
         .expect("command error")

From 7e9f00bcc1742932e40426dddd906851b46c24d3 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Mon, 28 Jul 2025 16:26:44 +0200
Subject: [PATCH 22/23] kernel: Allowing reducing exports

Now that an API has been defined, remove the override for symbol
visibility of the library. It is now possible to build the library with
reduced exports.
---
 src/kernel/CMakeLists.txt | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/src/kernel/CMakeLists.txt b/src/kernel/CMakeLists.txt
index 7b2f3c7d11f..1db7ead0950 100644
--- a/src/kernel/CMakeLists.txt
+++ b/src/kernel/CMakeLists.txt
@@ -96,16 +96,6 @@ target_link_libraries(bitcoinkernel
 
 target_include_directories(bitcoinkernel PRIVATE $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/src/leveldb/include>)
 
-# libbitcoinkernel requires default symbol visibility, explicitly
-# specify that here so that things still work even when user
-# configures with -DREDUCE_EXPORTS=ON
-#
-# Note this is a quick hack that will be removed as we
-# incrementally define what to export from the library.
-set_target_properties(bitcoinkernel PROPERTIES
-  CXX_VISIBILITY_PRESET default
-)
-
 # Add a convenience libbitcoinkernel target as a synonym for bitcoinkernel.
 add_custom_target(libbitcoinkernel)
 add_dependencies(libbitcoinkernel bitcoinkernel)

From 6c7a34f3b0bd39ef7a1520aac56e12f78e5cc969 Mon Sep 17 00:00:00 2001
From: TheCharlatan <seb.kung@gmail.com>
Date: Wed, 26 Mar 2025 12:09:28 +0100
Subject: [PATCH 23/23] kernel: Add Purpose section to header documentation

---
 src/kernel/bitcoinkernel.h | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 14cd8145b11..99ae2bd67ae 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -48,6 +48,14 @@ extern "C" {
 /**
  * @page remarks Remarks
  *
+ * @section purpose Purpose
+ *
+ * This header currently exposes an API for interacting with parts of Bitcoin
+ * Core's consensus code. Users can validate blocks, iterate the block index,
+ * read block and undo data from disk, and validate scripts. The header is
+ * unversioned and not stable yet. Users should expect breaking changes. It is
+ * also not yet included in releases of Bitcoin Core.
+ *
  * @section context Context
  *
  * The library provides a built-in static constant kernel context. This static