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] 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};
+    }
+}