1// Copyright (c) 2024-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_KERNEL_BITCOINKERNEL_H
6#define BITCOIN_KERNEL_BITCOINKERNEL_H
7
8#ifndef __cplusplus
9#include <stddef.h>
10#include <stdint.h>
11#else
12#include <cstddef>
13#include <cstdint>
14#endif // __cplusplus
15
16#ifndef BITCOINKERNEL_API
17    #ifdef BITCOINKERNEL_BUILD
18        #if defined(_WIN32)
19            #define BITCOINKERNEL_API __declspec(dllexport)
20        #else
21            #define BITCOINKERNEL_API __attribute__((visibility("default")))
22        #endif
23    #else
24        #if defined(_WIN32) && !defined(BITCOINKERNEL_STATIC)
25            #define BITCOINKERNEL_API __declspec(dllimport)
26        #else
27            #define BITCOINKERNEL_API
28        #endif
29    #endif
30#endif
31
32/**
33 * BITCOINKERNEL_WARN_UNUSED_RESULT is a compiler attribute used to indicate
34 * that ignoring a function's return value is almost certainly a bug.
35 *
36 * It is used in cases such as a resource leak (e.g. an owning handle returned
37 * by a *_create or *_copy function), or when the returned value is itself an
38 * error/status code. It is not used merely because discarding the result is
39 * wasteful, e.g. on getters or predicates.
40 */
41#if defined(__GNUC__)
42    #define BITCOINKERNEL_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
43#else
44    #define BITCOINKERNEL_WARN_UNUSED_RESULT
45#endif
46
47/**
48 * BITCOINKERNEL_ARG_NONNULL is a compiler attribute used to indicate that
49 * certain pointer arguments to a function are not expected to be null.
50 *
51 * Callers must not pass a null pointer for arguments marked with this attribute,
52 * as doing so may result in undefined behavior. This attribute should only be
53 * used for arguments where a null pointer is unambiguously a programmer error,
54 * such as for opaque handles, and not for pointers to raw input data that might
55 * validly be null (e.g., from an empty std::span or std::string).
56 */
57#if !defined(BITCOINKERNEL_BUILD) && defined(__GNUC__)
58    #define BITCOINKERNEL_ARG_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__)))
59#else
60    #define BITCOINKERNEL_ARG_NONNULL(...)
61#endif
62
63#ifdef __cplusplus
64extern "C" {
65#endif // __cplusplus
66
67/**
68 * @page remarks Remarks
69 *
70 * @section purpose Purpose
71 *
72 * This header currently exposes an API for interacting with parts of Bitcoin
73 * Core's consensus code. Users can validate blocks, iterate the block index,
74 * read block and undo data from disk, and validate scripts. The header is
75 * unversioned and not stable yet. Users should expect breaking changes. It is
76 * also not yet included in releases of Bitcoin Core.
77 *
78 * @section context Context
79 *
80 * The library provides a built-in static constant kernel context. This static
81 * context offers only limited functionality. It detects and self-checks the
82 * correct sha256 implementation, initializes the random number generator and
83 * self-checks the secp256k1 static context. It is used internally for
84 * otherwise "context-free" operations. This means that the user is not
85 * required to initialize their own context before using the library.
86 *
87 * The user should create their own context for passing it to state-rich validation
88 * functions and holding callbacks for kernel events.
89 *
90 * @section error Error handling
91 *
92 * Functions communicate an error through their return types, usually returning
93 * a nullptr or a status code as documented by the returning function.
94 * Additionally, verification functions, e.g. for scripts, may communicate more
95 * detailed error information through status code out parameters.
96 *
97 * Fine-grained validation information is communicated through the validation
98 * interface.
99 *
100 * The kernel notifications issue callbacks for errors. These are usually
101 * indicative of a system error. If such an error is issued, it is recommended
102 * to halt and tear down the existing kernel objects. Remediating the error may
103 * require system intervention by the user.
104 *
105 * @section pointer Pointer and argument conventions
106 *
107 * The user is responsible for de-allocating the memory owned by pointers
108 * returned by functions. Typically pointers returned by *_create(...) functions
109 * can be de-allocated by corresponding *_destroy(...) functions.
110 *
111 * A function that takes pointer arguments makes no assumptions on their
112 * lifetime. Once the function returns the user can safely de-allocate the
113 * passed in arguments.
114 *
115 * Const pointers represent views, and do not transfer ownership. Lifetime
116 * guarantees of these objects are described in the respective documentation.
117 * Ownership of these resources may be taken by copying. They are typically
118 * used for iteration with minimal overhead and require some care by the
119 * programmer that their lifetime is not extended beyond that of the original
120 * object.
121 *
122 * Array lengths follow the pointer argument they describe.
123 *
124 * @section types Type conventions
125 *
126 * Fixed-width integer types (e.g. int32_t, uint32_t) are used for data values
127 * such as heights. Plain int and unsigned int are used for boolean-like values
128 * and flags.
129 */
130
131/**
132 * Opaque data structure for holding a transaction.
133 */
134typedef struct btck_Transaction btck_Transaction;
135
136/**
137 * Opaque data structure for holding a script pubkey.
138 */
139typedef struct btck_ScriptPubkey btck_ScriptPubkey;
140
141/**
142 * Opaque data structure for holding a transaction output.
143 */
144typedef struct btck_TransactionOutput btck_TransactionOutput;
145
146/**
147 * Opaque data structure for holding a logging connection.
148 *
149 * The logging connection can be used to manually stop logging.
150 *
151 * Messages that were logged before a connection is created are buffered in a
152 * 1MB buffer. Logging can alternatively be permanently disabled by calling
153 * @ref btck_logging_disable. Functions changing the logging settings are
154 * global and change the settings for all existing btck_LoggingConnection
155 * instances.
156 */
157typedef struct btck_LoggingConnection btck_LoggingConnection;
158
159/**
160 * Opaque data structure for holding the chain parameters.
161 *
162 * These are eventually placed into a kernel context through the kernel context
163 * options. The parameters describe the properties of a chain, and may be
164 * instantiated for either mainnet, testnet, signet, or regtest.
165 */
166typedef struct btck_ChainParameters btck_ChainParameters;
167
168/**
169 * Opaque data structure for holding options for creating a new kernel context.
170 *
171 * Once a kernel context has been created from these options, they may be
172 * destroyed. The options hold the notification and validation interface
173 * callbacks as well as the selected chain type until they are passed to the
174 * context. If no options are configured, the context will be instantiated with
175 * no callbacks and for mainnet. Their content and scope can be expanded over
176 * time.
177 */
178typedef struct btck_ContextOptions btck_ContextOptions;
179
180/**
181 * Opaque data structure for holding a kernel context.
182 *
183 * The kernel context is used to initialize internal state and hold the chain
184 * parameters and callbacks for handling error and validation events. Once
185 * other validation objects are instantiated from it, the context is kept in
186 * memory for the duration of their lifetimes.
187 *
188 * The processing of validation events is done through an internal task runner
189 * owned by the context. It passes events through the registered validation
190 * interface callbacks.
191 *
192 * A constructed context can be safely used from multiple threads.
193 */
194typedef struct btck_Context btck_Context;
195
196/**
197 * Opaque data structure for holding a block tree entry.
198 *
199 * This is a pointer to an element in the block index currently in memory of
200 * the chainstate manager. It is valid for the lifetime of the chainstate
201 * manager it was retrieved from. The entry is part of a tree-like structure
202 * that is maintained internally. Every entry, besides the genesis, points to a
203 * single parent. Multiple entries may share a parent, thus forming a tree.
204 * Each entry corresponds to a single block and may be used to retrieve its
205 * data and validation status.
206 */
207typedef struct btck_BlockTreeEntry btck_BlockTreeEntry;
208
209/**
210 * Opaque data structure for holding options for creating a new chainstate
211 * manager.
212 *
213 * The chainstate manager options are used to set some parameters for the
214 * chainstate manager.
215 */
216typedef struct btck_ChainstateManagerOptions btck_ChainstateManagerOptions;
217
218/**
219 * Opaque data structure for holding a chainstate manager.
220 *
221 * The chainstate manager is the central object for doing validation tasks as
222 * well as retrieving data from the chain. Internally it is a complex data
223 * structure with diverse functionality.
224 *
225 * Its functionality will be more and more exposed in the future.
226 */
227typedef struct btck_ChainstateManager btck_ChainstateManager;
228
229/**
230 * Opaque data structure for holding a block.
231 */
232typedef struct btck_Block btck_Block;
233
234/**
235 * Opaque data structure for holding the state of a block during validation.
236 *
237 * Contains information indicating whether validation was successful, and if not
238 * which step during block validation failed.
239 */
240typedef struct btck_BlockValidationState btck_BlockValidationState;
241
242/**
243 * Opaque data structure for holding the Consensus Params.
244 */
245typedef struct btck_ConsensusParams btck_ConsensusParams;
246
247/**
248 * Opaque data structure for holding the currently known best-chain associated
249 * with a chainstate.
250 */