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
64 extern "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 */
134 typedef struct btck_Transaction btck_Transaction;
135 136 /**
137 * Opaque data structure for holding a script pubkey.
138 */
139 typedef struct btck_ScriptPubkey btck_ScriptPubkey;
140 141 /**
142 * Opaque data structure for holding a transaction output.
143 */
144 typedef 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 */
157 typedef 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 */
166 typedef 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 */
178 typedef 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 */
194 typedef 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 */
207 typedef 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 */
216 typedef 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 */
227 typedef struct btck_ChainstateManager btck_ChainstateManager;
228 229 /**
230 * Opaque data structure for holding a block.
231 */
232 typedef 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 */
240 typedef struct btck_BlockValidationState btck_BlockValidationState;
241 242 /**
243 * Opaque data structure for holding the Consensus Params.
244 */
245 typedef struct btck_ConsensusParams btck_ConsensusParams;
246 247 /**
248 * Opaque data structure for holding the currently known best-chain associated
249 * with a chainstate.
250 */
251 typedef struct btck_Chain btck_Chain;
252 253 /**
254 * Opaque data structure for holding the state of a transaction during validation.
255 *
256 * Contains information indicating whether validation was successful, and if not
257 * which step during transaction validation failed.
258 */
259 typedef struct btck_TxValidationState btck_TxValidationState;
260 261 /**
262 * Opaque data structure for holding a block's spent outputs.
263 *
264 * Contains all the previous outputs consumed by all transactions in a specific
265 * block. Internally it holds a nested vector. The top level vector has an
266 * entry for each transaction in a block (in order of the actual transactions
267 * of the block and without the coinbase transaction). This is exposed through
268 * @ref btck_TransactionSpentOutputs. Each btck_TransactionSpentOutputs is in
269 * turn a vector of all the previous outputs of a transaction (in order of
270 * their corresponding inputs).
271 */
272 typedef struct btck_BlockSpentOutputs btck_BlockSpentOutputs;
273 274 /**
275 * Opaque data structure for holding a transaction's spent outputs.
276 *
277 * Holds the coins consumed by a certain transaction. Retrieved through the
278 * @ref btck_BlockSpentOutputs. The coins are in the same order as the
279 * transaction's inputs consuming them.
280 */
281 typedef struct btck_TransactionSpentOutputs btck_TransactionSpentOutputs;
282 283 /**
284 * Opaque data structure for holding a coin.
285 *
286 * Holds information on the @ref btck_TransactionOutput held within,
287 * including the height it was spent at and whether it is a coinbase output.
288 */
289 typedef struct btck_Coin btck_Coin;
290 291 /**
292 * Opaque data structure for holding a block hash.
293 *
294 * This is a type-safe identifier for a block.
295 */
296 typedef struct btck_BlockHash btck_BlockHash;
297 298 /**
299 * Opaque data structure for holding a transaction input.
300 *
301 * Holds information on the @ref btck_TransactionOutPoint, @ref btck_WitnessStack and script_sig held within.
302 */
303 typedef struct btck_TransactionInput btck_TransactionInput;
304 305 /**
306 * Opaque data structure for holding a witness stack.
307 *
308 * Holds a sequence of witness stack items.
309 */
310 typedef struct btck_WitnessStack btck_WitnessStack;
311 312 /**
313 * Opaque data structure for holding a transaction out point.
314 *
315 * Holds the txid and output index it is pointing to.
316 */
317 typedef struct btck_TransactionOutPoint btck_TransactionOutPoint;
318 319 /**
320 * Opaque data structure for holding precomputed transaction data.
321 *
322 * Reusable when verifying multiple inputs of the same transaction.
323 * This avoids recomputing transaction hashes for each input.
324 *
325 * Required when verifying a taproot input.
326 */
327 typedef struct btck_PrecomputedTransactionData btck_PrecomputedTransactionData;
328 329 /**
330 * Opaque data structure for holding a btck_Txid.
331 *
332 * This is a type-safe identifier for a transaction.
333 */
334 typedef struct btck_Txid btck_Txid;
335 336 /**
337 * Opaque data structure for holding a btck_BlockHeader.
338 */
339 typedef struct btck_BlockHeader btck_BlockHeader;
340 341 /** Current sync state passed to tip changed callbacks. */
342 typedef uint8_t btck_SynchronizationState;
343 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
344 #define btck_SynchronizationState_INIT_DOWNLOAD ((btck_SynchronizationState)(1))
345 #define btck_SynchronizationState_POST_INIT ((btck_SynchronizationState)(2))
346 347 /** Possible warning types issued by validation. */
348 typedef uint8_t btck_Warning;
349 #define btck_Warning_UNKNOWN_NEW_RULES_ACTIVATED ((btck_Warning)(0))
350 #define btck_Warning_LARGE_WORK_INVALID_CHAIN ((btck_Warning)(1))
351 352 /** Callback function types */
353 354 /**
355 * Function signature for the global logging callback. All bitcoin kernel
356 * internal logs will pass through this callback.
357 */
358 typedef void (*btck_LogCallback)(void* user_data, const char* message, size_t message_len);
359 360 /**
361 * Function signature for freeing user data.
362 */
363 typedef void (*btck_DestroyCallback)(void* user_data);
364 365 /**
366 * Function signatures for the kernel notifications.
367 */
368 typedef void (*btck_NotifyBlockTip)(void* user_data, btck_SynchronizationState state, const btck_BlockTreeEntry* entry, double verification_progress);
369 typedef void (*btck_NotifyHeaderTip)(void* user_data, btck_SynchronizationState state, int64_t height, int64_t timestamp, int presync);
370 typedef void (*btck_NotifyProgress)(void* user_data, const char* title, size_t title_len, int progress_percent, int resume_possible);
371 typedef void (*btck_NotifyWarningSet)(void* user_data, btck_Warning warning, const char* message, size_t message_len);
372 typedef void (*btck_NotifyWarningUnset)(void* user_data, btck_Warning warning);
373 typedef void (*btck_NotifyFlushError)(void* user_data, const char* message, size_t message_len);
374 typedef void (*btck_NotifyFatalError)(void* user_data, const char* message, size_t message_len);
375 376 /**
377 * Function signatures for the validation interface.
378 */
379 typedef void (*btck_ValidationInterfaceBlockChecked)(void* user_data, btck_Block* block, const btck_BlockValidationState* state);
380 typedef void (*btck_ValidationInterfacePoWValidBlock)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
381 typedef void (*btck_ValidationInterfaceBlockConnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
382 typedef void (*btck_ValidationInterfaceBlockDisconnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
383 384 /**
385 * Function signature for serializing data.
386 *
387 * Returns 0 to indicate success.
388 */
389 typedef int (*btck_WriteBytes)(const void* bytes, size_t size, void* userdata);
390 391 /**
392 * Whether a validated data structure is valid, invalid, or an error was
393 * encountered during processing.
394 */
395 typedef uint8_t btck_ValidationMode;
396 #define btck_ValidationMode_VALID ((btck_ValidationMode)(0))
397 #define btck_ValidationMode_INVALID ((btck_ValidationMode)(1))
398 #define btck_ValidationMode_INTERNAL_ERROR ((btck_ValidationMode)(2))
399 400 /**
401 * A granular "reason" why a block was invalid.
402 */
403 typedef uint32_t btck_BlockValidationResult;
404 #define btck_BlockValidationResult_UNSET ((btck_BlockValidationResult)(0)) //!< initial value. Block has not yet been rejected
405 #define btck_BlockValidationResult_CONSENSUS ((btck_BlockValidationResult)(1)) //!< invalid by consensus rules (excluding any below reasons)
406 #define btck_BlockValidationResult_CACHED_INVALID ((btck_BlockValidationResult)(2)) //!< this block was cached as being invalid and we didn't store the reason why
407 #define btck_BlockValidationResult_INVALID_HEADER ((btck_BlockValidationResult)(3)) //!< invalid proof of work or time too old
408 #define btck_BlockValidationResult_MUTATED ((btck_BlockValidationResult)(4)) //!< the block's data didn't match the data committed to by the PoW
409 #define btck_BlockValidationResult_MISSING_PREV ((btck_BlockValidationResult)(5)) //!< We don't have the previous block the checked one is built on
410 #define btck_BlockValidationResult_INVALID_PREV ((btck_BlockValidationResult)(6)) //!< A block this one builds on is invalid
411 #define btck_BlockValidationResult_TIME_FUTURE ((btck_BlockValidationResult)(7)) //!< block timestamp was > 2 hours in the future (or our clock is bad)
412 #define btck_BlockValidationResult_HEADER_LOW_WORK ((btck_BlockValidationResult)(8)) //!< the block header may be on a too-little-work chain
413 414 /**
415 * Indicates the reason why a transaction failed validation. The subset of
416 * values reachable depends on which validation function was used.
417 */
418 typedef uint32_t btck_TxValidationResult;
419 #define btck_TxValidationResult_UNSET ((btck_TxValidationResult)(0)) //!< initial value. Tx has not yet been rejected
420 #define btck_TxValidationResult_CONSENSUS ((btck_TxValidationResult)(1)) //!< invalid by consensus rules
421 #define btck_TxValidationResult_INPUTS_NOT_STANDARD ((btck_TxValidationResult)(2)) //!< inputs (covered by txid) failed policy rules
422 #define btck_TxValidationResult_NOT_STANDARD ((btck_TxValidationResult)(3)) //!< otherwise didn't meet local policy rules
423 #define btck_TxValidationResult_MISSING_INPUTS ((btck_TxValidationResult)(4)) //!< transaction was missing some of its inputs
424 #define btck_TxValidationResult_PREMATURE_SPEND ((btck_TxValidationResult)(5)) //!< transaction spends a coinbase too early, or violates locktime/sequence locks
425 #define btck_TxValidationResult_WITNESS_MUTATED ((btck_TxValidationResult)(6)) //!< witness may have been malleated or is prior to SegWit activation
426 #define btck_TxValidationResult_WITNESS_STRIPPED ((btck_TxValidationResult)(7)) //!< transaction is missing a witness
427 #define btck_TxValidationResult_CONFLICT ((btck_TxValidationResult)(8)) //!< tx already in mempool or conflicts with a tx in the chain
428 #define btck_TxValidationResult_MEMPOOL_POLICY ((btck_TxValidationResult)(9)) //!< violated mempool's fee/size/descendant/RBF/etc limits
429 #define btck_TxValidationResult_NO_MEMPOOL ((btck_TxValidationResult)(10)) //!< this node does not have a mempool so can't validate the transaction
430 #define btck_TxValidationResult_RECONSIDERABLE ((btck_TxValidationResult)(11)) //!< fails some policy, but might be acceptable if submitted in a (different) package
431 #define btck_TxValidationResult_UNKNOWN ((btck_TxValidationResult)(12)) //!< transaction was not validated because package failed
432 433 /**
434 * Holds the validation interface callbacks. The user data pointer may be used
435 * to point to user-defined structures to make processing the validation
436 * callbacks easier. Note that these callbacks block any further validation
437 * execution when they are called.
438 */
439 typedef struct {
440 void* user_data; //!< Holds a user-defined opaque structure that is passed to the validation
441 //!< interface callbacks. If user_data_destroy is also defined ownership of the
442 //!< user_data is passed to the created context options and subsequently context.
443 btck_DestroyCallback user_data_destroy; //!< Frees the provided user data structure.
444 btck_ValidationInterfaceBlockChecked block_checked; //!< Called when a new block has been fully validated. Contains the
445 //!< result of its validation.
446 btck_ValidationInterfacePoWValidBlock pow_valid_block; //!< Called when a new block extends the header chain and has a valid transaction
447 //!< and segwit merkle root.
448 btck_ValidationInterfaceBlockConnected block_connected; //!< Called when a block is valid and has now been connected to the best chain.
449 btck_ValidationInterfaceBlockDisconnected block_disconnected; //!< Called during a re-org when a block has been removed from the best chain.
450 } btck_ValidationInterfaceCallbacks;
451 452 /**
453 * A struct for holding the kernel notification callbacks. The user data
454 * pointer may be used to point to user-defined structures to make processing
455 * the notifications easier.
456 *
457 * If user_data_destroy is provided, the kernel will automatically call this
458 * callback to clean up user_data when the notification interface object is destroyed.
459 * If user_data_destroy is NULL, it is the user's responsibility to ensure that
460 * the user_data outlives the kernel objects. Notifications can
461 * occur even as kernel objects are deleted, so care has to be taken to ensure
462 * safe unwinding.
463 */
464 typedef struct {
465 void* user_data; //!< Holds a user-defined opaque structure that is passed to the notification callbacks.
466 //!< If user_data_destroy is also defined ownership of the user_data is passed to the
467 //!< created context options and subsequently context.
468 btck_DestroyCallback user_data_destroy; //!< Frees the provided user data structure.
469 btck_NotifyBlockTip block_tip; //!< The chain's tip was updated to the provided block entry.
470 btck_NotifyHeaderTip header_tip; //!< A new best block header was added.
471 btck_NotifyProgress progress; //!< Reports on current block synchronization progress.
472 btck_NotifyWarningSet warning_set; //!< A warning issued by the kernel library during validation.
473 btck_NotifyWarningUnset warning_unset; //!< A previous condition leading to the issuance of a warning is no longer given.
474 btck_NotifyFlushError flush_error; //!< An error encountered when flushing data to disk.
475 btck_NotifyFatalError fatal_error; //!< An unrecoverable system error encountered by the library.
476 } btck_NotificationInterfaceCallbacks;
477 478 /**
479 * A collection of logging categories that may be encountered by kernel code.
480 */
481 typedef uint8_t btck_LogCategory;
482 #define btck_LogCategory_ALL ((btck_LogCategory)(0))
483 #define btck_LogCategory_BENCH ((btck_LogCategory)(1))
484 #define btck_LogCategory_BLOCKSTORAGE ((btck_LogCategory)(2))
485 #define btck_LogCategory_COINDB ((btck_LogCategory)(3))
486 #define btck_LogCategory_LEVELDB ((btck_LogCategory)(4))
487 #define btck_LogCategory_MEMPOOL ((btck_LogCategory)(5))
488 #define btck_LogCategory_PRUNE ((btck_LogCategory)(6))
489 #define btck_LogCategory_RAND ((btck_LogCategory)(7))
490 #define btck_LogCategory_REINDEX ((btck_LogCategory)(8))
491 #define btck_LogCategory_VALIDATION ((btck_LogCategory)(9))
492 #define btck_LogCategory_KERNEL ((btck_LogCategory)(10))
493 494 /**
495 * The level at which logs should be produced.
496 */
497 typedef uint8_t btck_LogLevel;
498 #define btck_LogLevel_TRACE ((btck_LogLevel)(0))
499 #define btck_LogLevel_DEBUG ((btck_LogLevel)(1))
500 #define btck_LogLevel_INFO ((btck_LogLevel)(2))
501 502 /**
503 * Options controlling the format of log messages.
504 *
505 * Set fields as non-zero to indicate true.
506 */
507 typedef struct {
508 int log_timestamps; //!< Prepend a timestamp to log messages.
509 int log_time_micros; //!< Log timestamps in microsecond precision.
510 int log_threadnames; //!< Prepend the name of the thread to log messages.
511 int log_sourcelocations; //!< Prepend the source location to log messages.
512 int always_print_category_levels; //!< Prepend the log category and level to log messages.
513 } btck_LoggingOptions;
514 515 /**
516 * A collection of status codes that may be issued by the script verify function.
517 */
518 typedef uint8_t btck_ScriptVerifyStatus;
519 #define btck_ScriptVerifyStatus_OK ((btck_ScriptVerifyStatus)(0))
520 #define btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION ((btck_ScriptVerifyStatus)(1)) //!< The flags were combined in an invalid way.
521 #define btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED ((btck_ScriptVerifyStatus)(2)) //!< The taproot flag was set, so valid spent_outputs have to be provided.
522 523 /**
524 * Script verification flags that may be composed with each other.
525 */
526 typedef uint32_t btck_ScriptVerificationFlags;
527 #define btck_ScriptVerificationFlags_NONE ((btck_ScriptVerificationFlags)(0))
528 #define btck_ScriptVerificationFlags_P2SH ((btck_ScriptVerificationFlags)(1U << 0)) //!< evaluate P2SH (BIP16) subscripts
529 #define btck_ScriptVerificationFlags_DERSIG ((btck_ScriptVerificationFlags)(1U << 2)) //!< enforce strict DER (BIP66) compliance
530 #define btck_ScriptVerificationFlags_NULLDUMMY ((btck_ScriptVerificationFlags)(1U << 4)) //!< enforce NULLDUMMY (BIP147)
531 #define btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY ((btck_ScriptVerificationFlags)(1U << 9)) //!< enable CHECKLOCKTIMEVERIFY (BIP65)
532 #define btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY ((btck_ScriptVerificationFlags)(1U << 10)) //!< enable CHECKSEQUENCEVERIFY (BIP112)
533 #define btck_ScriptVerificationFlags_WITNESS ((btck_ScriptVerificationFlags)(1U << 11)) //!< enable WITNESS (BIP141)
534 #define btck_ScriptVerificationFlags_TAPROOT ((btck_ScriptVerificationFlags)(1U << 17)) //!< enable TAPROOT (BIPs 341 & 342)
535 #define btck_ScriptVerificationFlags_ALL ((btck_ScriptVerificationFlags)(btck_ScriptVerificationFlags_P2SH | \
536 btck_ScriptVerificationFlags_DERSIG | \
537 btck_ScriptVerificationFlags_NULLDUMMY | \
538 btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY | \
539 btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY | \
540 btck_ScriptVerificationFlags_WITNESS | \
541 btck_ScriptVerificationFlags_TAPROOT))
542 543 typedef uint8_t btck_ChainType;
544 #define btck_ChainType_MAINNET ((btck_ChainType)(0))
545 #define btck_ChainType_TESTNET ((btck_ChainType)(1))
546 #define btck_ChainType_TESTNET_4 ((btck_ChainType)(2))
547 #define btck_ChainType_SIGNET ((btck_ChainType)(3))
548 #define btck_ChainType_REGTEST ((btck_ChainType)(4))
549 550 /** @name TxValidationState
551 * Introspection for transaction validation state.
552 */
553 ///@{
554 555 /**
556 * Create a new btck_TxValidationState.
557 */
558 BITCOINKERNEL_API btck_TxValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_tx_validation_state_create();
559 560 /**
561 * Returns the validation mode from an opaque btck_TxValidationState pointer.
562 */
563 BITCOINKERNEL_API btck_ValidationMode btck_tx_validation_state_get_validation_mode(
564 const btck_TxValidationState* state) BITCOINKERNEL_ARG_NONNULL(1);
565 566 /**
567 * Returns the validation result from an opaque btck_TxValidationState pointer.
568 *
569 * btck_transaction_check currently produces only btck_TxValidationResult_UNSET
570 * for valid transactions and btck_TxValidationResult_CONSENSUS for invalid
571 * ones. Other values remain exposed for forward compatibility with higher-level
572 * validation entry points.
573 */
574 BITCOINKERNEL_API btck_TxValidationResult btck_tx_validation_state_get_tx_validation_result(
575 const btck_TxValidationState* state) BITCOINKERNEL_ARG_NONNULL(1);
576 577 /**
578 * Destroy the btck_TxValidationState.
579 */
580 BITCOINKERNEL_API void btck_tx_validation_state_destroy(btck_TxValidationState* state);
581 582 ///@}
583 584 /** @name Transaction
585 * Functions for working with transactions.
586 */
587 ///@{
588 589 /**
590 * @brief Create a new transaction from the serialized data.
591 *
592 * @param[in] raw_transaction Serialized transaction.
593 * @param[in] raw_transaction_len Length of the serialized transaction.
594 * @return The transaction, or null on error.
595 */
596 BITCOINKERNEL_API btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_create(
597 const void* raw_transaction, size_t raw_transaction_len);
598 599 /**
600 * @brief Copy a transaction. Transactions are reference counted, so this just
601 * increments the reference count.
602 *
603 * @param[in] transaction Non-null.
604 * @return The copied transaction.
605 */
606 BITCOINKERNEL_API btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_copy(
607 const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
608 609 /**
610 * @brief Serializes the transaction through the passed in callback to bytes.
611 * This is consensus serialization that is also used for the P2P network.
612 *
613 * @param[in] transaction Non-null.
614 * @param[in] writer Non-null, callback to a write bytes function.
615 * @param[in] user_data Holds a user-defined opaque structure that will be
616 * passed back through the writer callback.
617 * @return 0 on success.
618 */
619 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_to_bytes(
620 const btck_Transaction* transaction,
621 btck_WriteBytes writer,
622 void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
623 624 /**
625 * @brief Get the number of outputs of a transaction.
626 *
627 * @param[in] transaction Non-null.
628 * @return The number of outputs.
629 */
630 BITCOINKERNEL_API size_t btck_transaction_count_outputs(
631 const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
632 633 /**
634 * @brief Get the transaction outputs at the provided index. The returned
635 * transaction output is not owned and depends on the lifetime of the
636 * transaction.
637 *
638 * @param[in] transaction Non-null.
639 * @param[in] output_index The index of the transaction output to be retrieved.
640 * @return The transaction output
641 */
642 BITCOINKERNEL_API const btck_TransactionOutput* btck_transaction_get_output_at(
643 const btck_Transaction* transaction, size_t output_index) BITCOINKERNEL_ARG_NONNULL(1);
644 645 /**
646 * @brief Get the transaction input at the provided index. The returned
647 * transaction input is not owned and depends on the lifetime of the
648 * transaction.
649 *
650 * @param[in] transaction Non-null.
651 * @param[in] input_index The index of the transaction input to be retrieved.
652 * @return The transaction input
653 */
654 BITCOINKERNEL_API const btck_TransactionInput* btck_transaction_get_input_at(
655 const btck_Transaction* transaction, size_t input_index) BITCOINKERNEL_ARG_NONNULL(1);
656 657 /**
658 * @brief Get the number of inputs of a transaction.
659 *
660 * @param[in] transaction Non-null.
661 * @return The number of inputs.
662 */
663 BITCOINKERNEL_API size_t btck_transaction_count_inputs(
664 const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
665 666 /**
667 * @brief Get a transaction's nLockTime value.
668 *
669 * @param[in] transaction Non-null.
670 * @return The nLockTime value.
671 */
672 BITCOINKERNEL_API uint32_t btck_transaction_get_locktime(
673 const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
674 675 /**
676 * @brief Get the txid of a transaction. The returned txid is not owned and
677 * depends on the lifetime of the transaction.
678 *
679 * @param[in] transaction Non-null.
680 * @return The txid.
681 */
682 BITCOINKERNEL_API const btck_Txid* btck_transaction_get_txid(
683 const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
684 685 /**
686 * @brief Run context-free consensus validation on a btck_Transaction.
687 *
688 * Performs basic structural consensus checks (consensus/tx_check::CheckTransaction)
689 * without requiring blockchain state.
690 *
691 * @param[in] tx Non-null, the transaction to validate.
692 * @param[out] validation_state Non-null, previously created with
693 * btck_tx_validation_state_create.
694 * Overwritten in-place with the validation
695 * result.
696 * @return 1 if valid, 0 if invalid.
697 * @note Only btck_TxValidationResult_UNSET and
698 * btck_TxValidationResult_CONSENSUS are
699 * reachable via this function.
700 */
701 BITCOINKERNEL_API int btck_transaction_check(
702 const btck_Transaction* tx,
703 btck_TxValidationState* validation_state) BITCOINKERNEL_ARG_NONNULL(1, 2);
704 705 /**
706 * Destroy the transaction.
707 */
708 BITCOINKERNEL_API void btck_transaction_destroy(btck_Transaction* transaction);
709 710 ///@}
711 712 /** @name PrecomputedTransactionData
713 * Functions for working with precomputed transaction data.
714 */
715 ///@{
716 717 /**
718 * @brief Create precomputed transaction data for script verification.
719 *
720 * @param[in] tx_to Non-null.
721 * @param[in] spent_outputs Nullable for non-taproot verification. Points to an array of
722 * outputs spent by the transaction.
723 * @param[in] spent_outputs_len Length of the spent_outputs array.
724 * @return The precomputed data, or null on error.
725 */
726 BITCOINKERNEL_API btck_PrecomputedTransactionData* BITCOINKERNEL_WARN_UNUSED_RESULT btck_precomputed_transaction_data_create(
727 const btck_Transaction* tx_to,
728 const btck_TransactionOutput** spent_outputs, size_t spent_outputs_len) BITCOINKERNEL_ARG_NONNULL(1);
729 730 /**
731 * @brief Copy precomputed transaction data.
732 *
733 * @param[in] precomputed_txdata Non-null.
734 * @return The copied precomputed transaction data.
735 */
736 BITCOINKERNEL_API btck_PrecomputedTransactionData* BITCOINKERNEL_WARN_UNUSED_RESULT btck_precomputed_transaction_data_copy(
737 const btck_PrecomputedTransactionData* precomputed_txdata) BITCOINKERNEL_ARG_NONNULL(1);
738 739 /**
740 * Destroy the precomputed transaction data.
741 */
742 BITCOINKERNEL_API void btck_precomputed_transaction_data_destroy(btck_PrecomputedTransactionData* precomputed_txdata);
743 744 ///@}
745 746 /** @name ScriptPubkey
747 * Functions for working with script pubkeys.
748 */
749 ///@{
750 751 /**
752 * @brief Create a script pubkey from serialized data.
753 * @param[in] script_pubkey Serialized script pubkey.
754 * @param[in] script_pubkey_len Length of the script pubkey data.
755 * @return The script pubkey.
756 */
757 BITCOINKERNEL_API btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_create(
758 const void* script_pubkey, size_t script_pubkey_len);
759 760 /**
761 * @brief Copy a script pubkey.
762 *
763 * @param[in] script_pubkey Non-null.
764 * @return The copied script pubkey.
765 */
766 BITCOINKERNEL_API btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_copy(
767 const btck_ScriptPubkey* script_pubkey) BITCOINKERNEL_ARG_NONNULL(1);
768 769 /**
770 * @brief Verify if the input at input_index of tx_to spends the script pubkey
771 * under the constraints specified by flags. If the
772 * `btck_ScriptVerificationFlags_WITNESS` flag is set in the flags bitfield, the
773 * amount parameter is used. If the taproot flag is set, the precomputed data
774 * must contain the spent outputs.
775 *
776 * @param[in] script_pubkey Non-null, script pubkey to be spent.
777 * @param[in] amount Amount of the script pubkey's associated output. May be zero if
778 * the witness flag is not set.
779 * @param[in] tx_to Non-null, transaction spending the script_pubkey.
780 * @param[in] precomputed_txdata Nullable if the taproot flag is not set. Otherwise, precomputed data
781 * for tx_to with the spent outputs must be provided.
782 * @param[in] input_index Index of the input in tx_to spending the script_pubkey.
783 * @param[in] flags Bitfield of btck_ScriptVerificationFlags controlling validation constraints.
784 * @param[out] status Nullable, will be set to an error code if the operation fails, or OK otherwise.
785 * @return 1 if the script is valid, 0 otherwise.
786 */
787 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_verify(
788 const btck_ScriptPubkey* script_pubkey,
789 int64_t amount,
790 const btck_Transaction* tx_to,
791 const btck_PrecomputedTransactionData* precomputed_txdata,
792 unsigned int input_index,
793 btck_ScriptVerificationFlags flags,
794 btck_ScriptVerifyStatus* status) BITCOINKERNEL_ARG_NONNULL(1, 3);
795 796 /**
797 * @brief Serializes the script pubkey through the passed in callback to bytes.
798 *
799 * @param[in] script_pubkey Non-null.
800 * @param[in] writer Non-null, callback to a write bytes function.
801 * @param[in] user_data Holds a user-defined opaque structure that will be
802 * passed back through the writer callback.
803 * @return 0 on success.
804 */
805 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_to_bytes(
806 const btck_ScriptPubkey* script_pubkey,
807 btck_WriteBytes writer,
808 void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
809 810 /**
811 * Destroy the script pubkey.
812 */
813 BITCOINKERNEL_API void btck_script_pubkey_destroy(btck_ScriptPubkey* script_pubkey);
814 815 ///@}
816 817 /** @name TransactionOutput
818 * Functions for working with transaction outputs.
819 */
820 ///@{
821 822 /**
823 * @brief Create a transaction output from a script pubkey and an amount.
824 *
825 * @param[in] script_pubkey Non-null.
826 * @param[in] amount The amount associated with the script pubkey for this output.
827 * @return The transaction output.
828 */
829 BITCOINKERNEL_API btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_create(
830 const btck_ScriptPubkey* script_pubkey,
831 int64_t amount) BITCOINKERNEL_ARG_NONNULL(1);
832 833 /**
834 * @brief Get the script pubkey of the output. The returned
835 * script pubkey is not owned and depends on the lifetime of the
836 * transaction output.
837 *
838 * @param[in] transaction_output Non-null.
839 * @return The script pubkey.
840 */
841 BITCOINKERNEL_API const btck_ScriptPubkey* btck_transaction_output_get_script_pubkey(
842 const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1);
843 844 /**
845 * @brief Get the amount in the output.
846 *
847 * @param[in] transaction_output Non-null.
848 * @return The amount.
849 */
850 BITCOINKERNEL_API int64_t btck_transaction_output_get_amount(
851 const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1);
852 853 /**
854 * @brief Copy a transaction output.
855 *
856 * @param[in] transaction_output Non-null.
857 * @return The copied transaction output.
858 */
859 BITCOINKERNEL_API btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_copy(
860 const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1);
861 862 /**
863 * Destroy the transaction output.
864 */
865 BITCOINKERNEL_API void btck_transaction_output_destroy(btck_TransactionOutput* transaction_output);
866 867 ///@}
868 869 /** @name Logging
870 * Logging-related functions.
871 */
872 ///@{
873 874 /**
875 * @brief This disables the global internal logger. No log messages will be
876 * buffered internally anymore once this is called and the buffer is cleared.
877 * This function should only be called once and is not thread or re-entry safe.
878 * Log messages will be buffered until this function is called, or a logging
879 * connection is created. This must not be called while a logging connection
880 * already exists.
881 */
882 BITCOINKERNEL_API void btck_logging_disable();
883 884 /**
885 * @brief Set some options for the global internal logger. This changes global
886 * settings and will override settings for all existing @ref
887 * btck_LoggingConnection instances.
888 *
889 * @param[in] options Sets formatting options of the log messages.
890 */
891 BITCOINKERNEL_API void btck_logging_set_options(btck_LoggingOptions options);
892 893 /**
894 * @brief Set the log level of the global internal logger. This does not
895 * enable the selected categories. Use @ref btck_logging_enable_category to
896 * start logging from a specific, or all categories. This changes a global
897 * setting and will override settings for all existing
898 * @ref btck_LoggingConnection instances.
899 *
900 * @param[in] category If btck_LogCategory_ALL is chosen, sets both the global fallback log level
901 * used by all categories that don't have a specific level set, and also
902 * sets the log level for messages logged with the btck_LogCategory_ALL category itself.
903 * For any other category, sets a category-specific log level that overrides
904 * the global fallback for that category only.
905 906 * @param[in] level Log level at which the log category is set.
907 */
908 BITCOINKERNEL_API void btck_logging_set_level_category(btck_LogCategory category, btck_LogLevel level);
909 910 /**
911 * @brief Enable a specific log category for the global internal logger. This
912 * changes a global setting and will override settings for all existing @ref
913 * btck_LoggingConnection instances.
914 *
915 * @param[in] category If btck_LogCategory_ALL is chosen, all categories will be enabled.
916 */
917 BITCOINKERNEL_API void btck_logging_enable_category(btck_LogCategory category);
918 919 /**
920 * @brief Disable a specific log category for the global internal logger. This
921 * changes a global setting and will override settings for all existing @ref
922 * btck_LoggingConnection instances.
923 *
924 * @param[in] category If btck_LogCategory_ALL is chosen, all categories will be disabled.
925 */
926 BITCOINKERNEL_API void btck_logging_disable_category(btck_LogCategory category);
927 928 /**
929 * @brief Start logging messages through the provided callback. Log messages
930 * produced before this function is first called are buffered and on calling this
931 * function are logged immediately.
932 *
933 * @param[in] log_callback Non-null, function through which messages will be logged.
934 * @param[in] user_data Nullable, holds a user-defined opaque structure. Is passed back
935 * to the user through the callback. If the user_data_destroy_callback
936 * is also defined it is assumed that ownership of the user_data is passed
937 * to the created logging connection.
938 * @param[in] user_data_destroy_callback Nullable, function for freeing the user data.
939 * @return A new kernel logging connection, or null on error.
940 */
941 BITCOINKERNEL_API btck_LoggingConnection* BITCOINKERNEL_WARN_UNUSED_RESULT btck_logging_connection_create(
942 btck_LogCallback log_callback,
943 void* user_data,
944 btck_DestroyCallback user_data_destroy_callback) BITCOINKERNEL_ARG_NONNULL(1);
945 946 /**
947 * Stop logging and destroy the logging connection.
948 */
949 BITCOINKERNEL_API void btck_logging_connection_destroy(btck_LoggingConnection* logging_connection);
950 951 ///@}
952 953 /** @name ChainParameters
954 * Functions for working with chain parameters.
955 */
956 ///@{
957 958 /**
959 * @brief Creates a chain parameters struct with default parameters based on the
960 * passed in chain type.
961 *
962 * @param[in] chain_type Controls the chain parameters type created.
963 * @return An allocated chain parameters opaque struct.
964 */
965 BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_create(
966 btck_ChainType chain_type);
967 968 /**
969 * @brief Create a signet chain parameters struct with a user-provided
970 * challenge.
971 *
972 * @param[in] challenge The signet challenge value. Blocks must satisfy it in
973 * order to be valid.
974 * @param[in] challenge_len The length of the signet challenge.
975 * @return An allocated chain parameters opaque struct.
976 */
977 BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_create_signet(
978 const void* challenge, size_t challenge_len);
979 980 /**
981 * Copy the chain parameters.
982 */
983 BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_copy(
984 const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1);
985 986 /**
987 * @brief Get btck_ConsensusParams from btck_ChainParameters. The returned
988 * btck_ConsensusParams pointer is valid only for the lifetime of the
989 * btck_ChainParameters object and must not be destroyed by the caller.
990 *
991 * @param[in] chain_parameters Non-null.
992 * @return The btck_ConsensusParams.
993 */
994 BITCOINKERNEL_API const btck_ConsensusParams* btck_chain_parameters_get_consensus_params(
995 const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1);
996 997 /**
998 * Destroy the chain parameters.
999 */
1000 BITCOINKERNEL_API void btck_chain_parameters_destroy(btck_ChainParameters* chain_parameters);
1001 1002 ///@}
1003 1004 /** @name ContextOptions
1005 * Functions for working with context options.
1006 */
1007 ///@{
1008 1009 /**
1010 * Creates an empty context options.
1011 */
1012 BITCOINKERNEL_API btck_ContextOptions* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_options_create();
1013 1014 /**
1015 * @brief Sets the chain params for the context options. The context created
1016 * with the options will be configured for these chain parameters.
1017 *
1018 * @param[in] context_options Non-null, previously created by @ref btck_context_options_create.
1019 * @param[in] chain_parameters Is set to the context options.
1020 */
1021 BITCOINKERNEL_API void btck_context_options_set_chainparams(
1022 btck_ContextOptions* context_options,
1023 const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1, 2);
1024 1025 /**
1026 * @brief Set the kernel notifications for the context options. The context
1027 * created with the options will be configured with these notifications.
1028 *
1029 * @param[in] context_options Non-null, previously created by @ref btck_context_options_create.
1030 * @param[in] notifications Is set to the context options.
1031 */
1032 BITCOINKERNEL_API void btck_context_options_set_notifications(
1033 btck_ContextOptions* context_options,
1034 btck_NotificationInterfaceCallbacks notifications) BITCOINKERNEL_ARG_NONNULL(1);
1035 1036 /**
1037 * @brief Set the validation interface callbacks for the context options. The
1038 * context created with the options will be configured for these validation
1039 * interface callbacks. The callbacks will then be triggered from validation
1040 * events issued by the chainstate manager created from the same context.
1041 *
1042 * @param[in] context_options Non-null, previously created with btck_context_options_create.
1043 * @param[in] validation_interface_callbacks The callbacks used for passing validation information to the
1044 * user.
1045 */
1046 BITCOINKERNEL_API void btck_context_options_set_validation_interface(
1047 btck_ContextOptions* context_options,
1048 btck_ValidationInterfaceCallbacks validation_interface_callbacks) BITCOINKERNEL_ARG_NONNULL(1);
1049 1050 /**
1051 * Destroy the context options.
1052 */
1053 BITCOINKERNEL_API void btck_context_options_destroy(btck_ContextOptions* context_options);
1054 1055 ///@}
1056 1057 /** @name Context
1058 * Functions for working with contexts.
1059 */
1060 ///@{
1061 1062 /**
1063 * @brief Create a new kernel context. If the options have not been previously
1064 * set, their corresponding fields will be initialized to default values; the
1065 * context will assume mainnet chain parameters and won't attempt to call the
1066 * kernel notification callbacks.
1067 *
1068 * @param[in] context_options Nullable, created by @ref btck_context_options_create.
1069 * @return The allocated context, or null on error.
1070 */
1071 BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_create(
1072 const btck_ContextOptions* context_options);
1073 1074 /**
1075 * Copy the context.
1076 */
1077 BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_copy(
1078 const btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);
1079 1080 /**
1081 * @brief Interrupt can be used to halt long-running validation functions like
1082 * when reindexing, importing or processing blocks.
1083 *
1084 * @param[in] context Non-null.
1085 * @return 0 if the interrupt was successful, non-zero otherwise.
1086 */
1087 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_interrupt(
1088 btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);
1089 1090 /**
1091 * Destroy the context.
1092 */
1093 BITCOINKERNEL_API void btck_context_destroy(btck_Context* context);
1094 1095 ///@}
1096 1097 /** @name BlockTreeEntry
1098 * Functions for working with block tree entries.
1099 */
1100 ///@{
1101 1102 /**
1103 * @brief Returns the previous block tree entry in the tree, or null if the current
1104 * block tree entry is the genesis block.
1105 *
1106 * @param[in] block_tree_entry Non-null.
1107 * @return The previous block tree entry, or null on error or if the current block tree entry is the genesis block.
1108 */
1109 BITCOINKERNEL_API const btck_BlockTreeEntry* btck_block_tree_entry_get_previous(
1110 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
1111 1112 /**
1113 * @brief Return the btck_BlockHeader associated with this entry.
1114 *
1115 * @param[in] block_tree_entry Non-null.
1116 * @return btck_BlockHeader.
1117 */
1118 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_block_header(
1119 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
1120 1121 /**
1122 * @brief Return the height of a certain block tree entry.
1123 *
1124 * @param[in] block_tree_entry Non-null.
1125 * @return The block height.
1126 */
1127 BITCOINKERNEL_API int32_t btck_block_tree_entry_get_height(
1128 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
1129 1130 /**
1131 * @brief Return the block hash associated with a block tree entry.
1132 *
1133 * @param[in] block_tree_entry Non-null.
1134 * @return The block hash.
1135 */
1136 BITCOINKERNEL_API const btck_BlockHash* btck_block_tree_entry_get_block_hash(
1137 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
1138 1139 /**
1140 * @brief Check if two block tree entries are equal. Two block tree entries are equal when they
1141 * point to the same block.
1142 *
1143 * @param[in] entry1 Non-null.
1144 * @param[in] entry2 Non-null.
1145 * @return 1 if the block tree entries are equal, 0 otherwise.
1146 */
1147 BITCOINKERNEL_API int btck_block_tree_entry_equals(
1148 const btck_BlockTreeEntry* entry1, const btck_BlockTreeEntry* entry2) BITCOINKERNEL_ARG_NONNULL(1, 2);
1149 1150 /**
1151 * @brief Return the ancestor of a btck_BlockTreeEntry at the given height.
1152 *
1153 * @param[in] block_tree_entry Non-null.
1154 * @param[in] height The height of the requested ancestor.
1155 * @return The ancestor at the given height.
1156 */
1157 BITCOINKERNEL_API const btck_BlockTreeEntry* btck_block_tree_entry_get_ancestor(
1158 const btck_BlockTreeEntry* block_tree_entry,
1159 int32_t height) BITCOINKERNEL_ARG_NONNULL(1);
1160 1161 ///@}
1162 1163 /** @name ChainstateManagerOptions
1164 * Functions for working with chainstate manager options.
1165 */
1166 ///@{
1167 1168 /**
1169 * @brief Create options for the chainstate manager.
1170 *
1171 * @param[in] context Non-null, the created options and through it the chainstate manager will
1172 * associate with this kernel context for the duration of their lifetimes.
1173 * @param[in] data_directory Path string of the directory containing the chainstate data. If the directory
1174 * does not exist yet, it will be created.
1175 * @param[in] blocks_directory Path string of the directory containing the block data. If the directory
1176 * does not exist yet, it will be created.
1177 * @return The allocated chainstate manager options, or null on error (e.g. if a path is invalid).
1178 */
1179 BITCOINKERNEL_API btck_ChainstateManagerOptions* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_create(
1180 const btck_Context* context,
1181 const char* data_directory,
1182 size_t data_directory_len,
1183 const char* blocks_directory,
1184 size_t blocks_directory_len) BITCOINKERNEL_ARG_NONNULL(1);
1185 1186 /**
1187 * @brief Set the number of available worker threads used during validation.
1188 *
1189 * @param[in] chainstate_manager_options Non-null, options to be set.
1190 * @param[in] worker_threads The number of worker threads that should be spawned in the thread pool
1191 * used for validation. When set to 0 no parallel verification is done.
1192 * The value range is clamped internally between 0 and 15.
1193 */
1194 BITCOINKERNEL_API void btck_chainstate_manager_options_set_worker_threads_num(
1195 btck_ChainstateManagerOptions* chainstate_manager_options,
1196 int worker_threads) BITCOINKERNEL_ARG_NONNULL(1);
1197 1198 /**
1199 * @brief Sets wipe db in the options. In combination with calling
1200 * @ref btck_chainstate_manager_import_blocks this triggers either a full reindex,
1201 * or a reindex of just the chainstate database.
1202 *
1203 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
1204 * @param[in] wipe_block_tree_db Set wipe block tree db. Should only be 1 if wipe_chainstate_db is 1 too.
1205 * @param[in] wipe_chainstate_db Set wipe chainstate db.
1206 * @return 0 if the set was successful, non-zero if the set failed.
1207 * @note When a wipe is set, the caller must invoke @ref btck_chainstate_manager_import_blocks
1208 * on the resulting chainstate manager before using it for anything else.
1209 */
1210 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_set_wipe_dbs(
1211 btck_ChainstateManagerOptions* chainstate_manager_options,
1212 int wipe_block_tree_db,
1213 int wipe_chainstate_db) BITCOINKERNEL_ARG_NONNULL(1);
1214 1215 /**
1216 * @brief Sets block tree db in memory in the options.
1217 *
1218 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
1219 * @param[in] block_tree_db_in_memory Set block tree db in memory.
1220 */
1221 BITCOINKERNEL_API void btck_chainstate_manager_options_update_block_tree_db_in_memory(
1222 btck_ChainstateManagerOptions* chainstate_manager_options,
1223 int block_tree_db_in_memory) BITCOINKERNEL_ARG_NONNULL(1);
1224 1225 /**
1226 * @brief Sets chainstate db in memory in the options.
1227 *
1228 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
1229 * @param[in] chainstate_db_in_memory Set chainstate db in memory.
1230 */
1231 BITCOINKERNEL_API void btck_chainstate_manager_options_update_chainstate_db_in_memory(
1232 btck_ChainstateManagerOptions* chainstate_manager_options,
1233 int chainstate_db_in_memory) BITCOINKERNEL_ARG_NONNULL(1);
1234 1235 /**
1236 * Destroy the chainstate manager options.
1237 */
1238 BITCOINKERNEL_API void btck_chainstate_manager_options_destroy(btck_ChainstateManagerOptions* chainstate_manager_options);
1239 1240 ///@}
1241 1242 /** @name ChainstateManager
1243 * Functions for chainstate management.
1244 */
1245 ///@{
1246 1247 /**
1248 * @brief Create a chainstate manager. This is the main object for many
1249 * validation tasks as well as for retrieving data from the chain and
1250 * interacting with its chainstate and indexes.
1251 *
1252 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
1253 * @return The allocated chainstate manager, or null on error.
1254 */
1255 BITCOINKERNEL_API btck_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_create(
1256 const btck_ChainstateManagerOptions* chainstate_manager_options) BITCOINKERNEL_ARG_NONNULL(1);
1257 1258 /**
1259 * @brief Get the btck_BlockTreeEntry whose associated btck_BlockHeader has the most
1260 * known cumulative proof of work.
1261 *
1262 * @param[in] chainstate_manager Non-null.
1263 * @return The btck_BlockTreeEntry, or null if no block headers have been loaded.
1264 */
1265 BITCOINKERNEL_API const btck_BlockTreeEntry* btck_chainstate_manager_get_best_entry(
1266 const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);
1267 1268 /**
1269 * @brief Processes and validates the provided btck_BlockHeader.
1270 *
1271 * @param[in] chainstate_manager Non-null.
1272 * @param[in] header Non-null btck_BlockHeader to be validated.
1273 * @return The btck_BlockValidationState containing validation result, or null on error.
1274 */
1275 BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_process_block_header(
1276 btck_ChainstateManager* chainstate_manager,
1277 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1, 2);
1278 1279 /**
1280 * @brief Triggers the start of a reindex if the wipe options were previously
1281 * set for the chainstate manager. Can also import an array of existing block
1282 * files selected by the user.
1283 *
1284 * @param[in] chainstate_manager Non-null.
1285 * @param[in] block_file_paths_data Nullable, array of block files described by their full filesystem paths.
1286 * @param[in] block_file_paths_lens Nullable, array containing the lengths of each of the paths.
1287 * @param[in] block_file_paths_data_len Length of the block_file_paths_data and block_file_paths_len arrays.
1288 * @return 0 if the import blocks call was completed successfully, non-zero otherwise.
1289 */
1290 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_import_blocks(
1291 btck_ChainstateManager* chainstate_manager,
1292 const char** block_file_paths_data, size_t* block_file_paths_lens,
1293 size_t block_file_paths_data_len) BITCOINKERNEL_ARG_NONNULL(1);
1294 1295 /**
1296 * @brief Process and validate the passed in block with the chainstate
1297 * manager. Processing first does checks on the block, and if these passed,
1298 * saves it to disk. It then validates the block against the utxo set. If it is
1299 * valid, the chain is extended with it. The return value is not indicative of
1300 * the block's validity. Detailed information on the validity of the block can
1301 * be retrieved by registering the `block_checked` callback in the validation
1302 * interface.
1303 *
1304 * @param[in] chainstate_manager Non-null.
1305 * @param[in] block Non-null, block to be validated.
1306 *
1307 * @param[out] new_block Nullable, will be set to 1 if this block was not processed before. Note that this means it
1308 * might also not be 1 if processing was attempted before, but the block was found invalid
1309 * before its data was persisted.
1310 * @return 0 if processing the block was successful. Will also return 0 for valid, but duplicate blocks.
1311 */
1312 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_process_block(
1313 btck_ChainstateManager* chainstate_manager,
1314 const btck_Block* block,
1315 int* new_block) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
1316 1317 /**
1318 * @brief Returns the best known currently active chain. Its lifetime is
1319 * dependent on the chainstate manager. It can be thought of as a view on a
1320 * vector of block tree entries that form the best chain. The returned chain
1321 * reference always points to the currently active best chain. However, state
1322 * transitions within the chainstate manager (e.g., processing blocks) will
1323 * update the chain's contents. Data retrieved from this chain is only
1324 * consistent up to the point when new data is processed in the chainstate
1325 * manager. It is the user's responsibility to guard against these
1326 * inconsistencies.
1327 *
1328 * @param[in] chainstate_manager Non-null.
1329 * @return The chain.
1330 */
1331 BITCOINKERNEL_API const btck_Chain* btck_chainstate_manager_get_active_chain(
1332 const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);
1333 1334 /**
1335 * @brief Retrieve a block tree entry by its block hash.
1336 *
1337 * @param[in] chainstate_manager Non-null.
1338 * @param[in] block_hash Non-null.
1339 * @return The block tree entry of the block with the passed in hash, or null if
1340 * the block hash is not found.
1341 */
1342 BITCOINKERNEL_API const btck_BlockTreeEntry* btck_chainstate_manager_get_block_tree_entry_by_hash(
1343 const btck_ChainstateManager* chainstate_manager,
1344 const btck_BlockHash* block_hash) BITCOINKERNEL_ARG_NONNULL(1, 2);
1345 1346 /**
1347 * Destroy the chainstate manager.
1348 */
1349 BITCOINKERNEL_API void btck_chainstate_manager_destroy(btck_ChainstateManager* chainstate_manager);
1350 1351 ///@}
1352 1353 /** @name Block
1354 * Functions for working with blocks.
1355 */
1356 ///@{
1357 1358 /**
1359 * @brief Reads the block the passed in block tree entry points to from disk and
1360 * returns it.
1361 *
1362 * @param[in] chainstate_manager Non-null.
1363 * @param[in] block_tree_entry Non-null.
1364 * @return The read out block, or null on error.
1365 */
1366 BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_read(
1367 const btck_ChainstateManager* chainstate_manager,
1368 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2);
1369 1370 /**
1371 * @brief Parse a serialized raw block into a new block object.
1372 *
1373 * @param[in] raw_block Serialized block.
1374 * @param[in] raw_block_len Length of the serialized block.
1375 * @return The allocated block, or null on error.
1376 */
1377 BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_create(
1378 const void* raw_block, size_t raw_block_len);
1379 1380 /**
1381 * @brief Copy a block. Blocks are reference counted, so this just increments
1382 * the reference count.
1383 *
1384 * @param[in] block Non-null.
1385 * @return The copied block.
1386 */
1387 BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_copy(
1388 const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
1389 1390 /** Bitflags to control context-free block checks (optional). */
1391 typedef uint32_t btck_BlockCheckFlags;
1392 #define btck_BlockCheckFlags_BASE ((btck_BlockCheckFlags)0) //!< run the base context-free block checks only
1393 #define btck_BlockCheckFlags_POW ((btck_BlockCheckFlags)(1U << 0)) //!< run CheckProofOfWork via CheckBlockHeader
1394 #define btck_BlockCheckFlags_MERKLE ((btck_BlockCheckFlags)(1U << 1)) //!< verify merkle root (and mutation detection)
1395 #define btck_BlockCheckFlags_ALL ((btck_BlockCheckFlags)(btck_BlockCheckFlags_POW | btck_BlockCheckFlags_MERKLE)) //!< enable all optional context-free block checks
1396 1397 /**
1398 * @brief Perform context-free validation checks on a btck_Block.
1399 *
1400 * Runs the base context-free block checks (size limits, coinbase structure,
1401 * transaction checks, and sigop limits) using the supplied
1402 * btck_ConsensusParams. The proof-of-work and merkle-root checks are optional
1403 * and can be toggled via @p flags. Note that this does not include any
1404 * transaction script, timestamps, order, or other checks that may require more
1405 * context.
1406 *
1407 * @param[in] block Non-null, btck_Block to validate.
1408 * @param[in] consensus_params Non-null, btck_ConsensusParams for validation.
1409 * @param[in] flags Bitmask of btck_BlockCheckFlags controlling the
1410 * optional POW and merkle-root checks. Use
1411 * btck_BlockCheckFlags_BASE to run only the base
1412 * checks.
1413 * @param[out] validation_state Non-null, previously created with
1414 * btck_block_validation_state_create.
1415 * Overwritten in-place with the validation
1416 * result.
1417 * @return 1 if the btck_Block passed the checks, 0 otherwise.
1418 */
1419 BITCOINKERNEL_API int btck_block_check(
1420 const btck_Block* block,
1421 const btck_ConsensusParams* consensus_params,
1422 btck_BlockCheckFlags flags,
1423 btck_BlockValidationState* validation_state) BITCOINKERNEL_ARG_NONNULL(1, 2, 4);
1424 1425 /**
1426 * @brief Count the number of transactions contained in a block.
1427 *
1428 * @param[in] block Non-null.
1429 * @return The number of transactions in the block.
1430 */
1431 BITCOINKERNEL_API size_t btck_block_count_transactions(
1432 const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
1433 1434 /**
1435 * @brief Get the transaction at the provided index. The returned transaction
1436 * is not owned and depends on the lifetime of the block.
1437 *
1438 * @param[in] block Non-null.
1439 * @param[in] transaction_index The index of the transaction to be retrieved.
1440 * @return The transaction.
1441 */
1442 BITCOINKERNEL_API const btck_Transaction* btck_block_get_transaction_at(
1443 const btck_Block* block, size_t transaction_index) BITCOINKERNEL_ARG_NONNULL(1);
1444 1445 /**
1446 * @brief Get the btck_BlockHeader from the block.
1447 *
1448 * Creates a new btck_BlockHeader object from the block's header data.
1449 *
1450 * @param[in] block Non-null btck_Block
1451 * @return btck_BlockHeader.
1452 */
1453 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_header(
1454 const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
1455 1456 /**
1457 * @brief Calculate and return the hash of a block.
1458 *
1459 * @param[in] block Non-null.
1460 * @return The block hash.
1461 */
1462 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_hash(
1463 const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
1464 1465 /**
1466 * @brief Serializes the block through the passed in callback to bytes.
1467 * This is consensus serialization that is also used for the P2P network.
1468 *
1469 * @param[in] block Non-null.
1470 * @param[in] writer Non-null, callback to a write bytes function.
1471 * @param[in] user_data Holds a user-defined opaque structure that will be
1472 * passed back through the writer callback.
1473 * @return 0 on success.
1474 */
1475 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_to_bytes(
1476 const btck_Block* block,
1477 btck_WriteBytes writer,
1478 void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
1479 1480 /**
1481 * Destroy the block.
1482 */
1483 BITCOINKERNEL_API void btck_block_destroy(btck_Block* block);
1484 1485 ///@}
1486 1487 /** @name BlockValidationState
1488 * Functions for working with block validation states.
1489 */
1490 ///@{
1491 1492 /**
1493 * Create a new btck_BlockValidationState.
1494 */
1495 BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_create();
1496 1497 /**
1498 * Returns the validation mode from an opaque btck_BlockValidationState pointer.
1499 */
1500 BITCOINKERNEL_API btck_ValidationMode btck_block_validation_state_get_validation_mode(
1501 const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);
1502 1503 /**
1504 * Returns the validation result from an opaque btck_BlockValidationState pointer.
1505 */
1506 BITCOINKERNEL_API btck_BlockValidationResult btck_block_validation_state_get_block_validation_result(
1507 const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);
1508 1509 /**
1510 * @brief Copies the btck_BlockValidationState.
1511 *
1512 * @param[in] block_validation_state Non-null.
1513 * @return The copied btck_BlockValidationState.
1514 */
1515 BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_copy(
1516 const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);
1517 1518 /**
1519 * Destroy the btck_BlockValidationState.
1520 */
1521 BITCOINKERNEL_API void btck_block_validation_state_destroy(
1522 btck_BlockValidationState* block_validation_state);
1523 1524 ///@}
1525 1526 /** @name Chain
1527 * Functions for working with the chain
1528 */
1529 ///@{
1530 1531 /**
1532 * @brief Return the height of the tip of the chain.
1533 *
1534 * @param[in] chain Non-null.
1535 * @return The current height.
1536 */
1537 BITCOINKERNEL_API int32_t btck_chain_get_height(
1538 const btck_Chain* chain) BITCOINKERNEL_ARG_NONNULL(1);
1539 1540 /**
1541 * @brief Retrieve a block tree entry by its height in the currently active chain.
1542 * Once retrieved there is no guarantee that it remains in the active chain.
1543 *
1544 * @param[in] chain Non-null.
1545 * @param[in] block_height Height in the chain of the to be retrieved block tree entry.
1546 * @return The block tree entry at a certain height in the currently active chain, or null
1547 * if the height is out of bounds.
1548 */
1549 BITCOINKERNEL_API const btck_BlockTreeEntry* btck_chain_get_by_height(
1550 const btck_Chain* chain,
1551 int32_t block_height) BITCOINKERNEL_ARG_NONNULL(1);
1552 1553 /**
1554 * @brief Return true if the passed in chain contains the block tree entry.
1555 *
1556 * @param[in] chain Non-null.
1557 * @param[in] block_tree_entry Non-null.
1558 * @return 1 if the block_tree_entry is in the chain, 0 otherwise.
1559 *
1560 */
1561 BITCOINKERNEL_API int btck_chain_contains(
1562 const btck_Chain* chain,
1563 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2);
1564 1565 ///@}
1566 1567 /** @name BlockSpentOutputs
1568 * Functions for working with block spent outputs.
1569 */
1570 ///@{
1571 1572 /**
1573 * @brief Reads the block spent coins data the passed in block tree entry points to from
1574 * disk and returns it.
1575 *
1576 * @param[in] chainstate_manager Non-null.
1577 * @param[in] block_tree_entry Non-null.
1578 * @return The read out block spent outputs, or null on error.
1579 */
1580 BITCOINKERNEL_API btck_BlockSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_read(
1581 const btck_ChainstateManager* chainstate_manager,
1582 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2);
1583 1584 /**
1585 * @brief Copy a block's spent outputs.
1586 *
1587 * @param[in] block_spent_outputs Non-null.
1588 * @return The copied block spent outputs.
1589 */
1590 BITCOINKERNEL_API btck_BlockSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_copy(
1591 const btck_BlockSpentOutputs* block_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
1592 1593 /**
1594 * @brief Returns the number of transaction spent outputs whose data is contained in
1595 * block spent outputs.
1596 *
1597 * @param[in] block_spent_outputs Non-null.
1598 * @return The number of transaction spent outputs data in the block spent outputs.
1599 */
1600 BITCOINKERNEL_API size_t btck_block_spent_outputs_count(
1601 const btck_BlockSpentOutputs* block_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
1602 1603 /**
1604 * @brief Returns a transaction spent outputs contained in the block spent
1605 * outputs at a certain index. The returned pointer is unowned and only valid
1606 * for the lifetime of block_spent_outputs.
1607 *
1608 * @param[in] block_spent_outputs Non-null.
1609 * @param[in] transaction_spent_outputs_index The index of the transaction spent outputs within the block spent outputs.
1610 * @return A transaction spent outputs pointer.
1611 */
1612 BITCOINKERNEL_API const btck_TransactionSpentOutputs* btck_block_spent_outputs_get_transaction_spent_outputs_at(
1613 const btck_BlockSpentOutputs* block_spent_outputs,
1614 size_t transaction_spent_outputs_index) BITCOINKERNEL_ARG_NONNULL(1);
1615 1616 /**
1617 * Destroy the block spent outputs.
1618 */
1619 BITCOINKERNEL_API void btck_block_spent_outputs_destroy(btck_BlockSpentOutputs* block_spent_outputs);
1620 1621 ///@}
1622 1623 /** @name TransactionSpentOutputs
1624 * Functions for working with the spent coins of a transaction
1625 */
1626 ///@{
1627 1628 /**
1629 * @brief Copy a transaction's spent outputs.
1630 *
1631 * @param[in] transaction_spent_outputs Non-null.
1632 * @return The copied transaction spent outputs.
1633 */
1634 BITCOINKERNEL_API btck_TransactionSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_spent_outputs_copy(
1635 const btck_TransactionSpentOutputs* transaction_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
1636 1637 /**
1638 * @brief Returns the number of previous transaction outputs contained in the
1639 * transaction spent outputs data.
1640 *
1641 * @param[in] transaction_spent_outputs Non-null
1642 * @return The number of spent transaction outputs for the transaction.
1643 */
1644 BITCOINKERNEL_API size_t btck_transaction_spent_outputs_count(
1645 const btck_TransactionSpentOutputs* transaction_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
1646 1647 /**
1648 * @brief Returns a coin contained in the transaction spent outputs at a
1649 * certain index. The returned pointer is unowned and only valid for the
1650 * lifetime of transaction_spent_outputs.
1651 *
1652 * @param[in] transaction_spent_outputs Non-null.
1653 * @param[in] coin_index The index of the to be retrieved coin within the
1654 * transaction spent outputs.
1655 * @return A coin pointer.
1656 */
1657 BITCOINKERNEL_API const btck_Coin* btck_transaction_spent_outputs_get_coin_at(
1658 const btck_TransactionSpentOutputs* transaction_spent_outputs,
1659 size_t coin_index) BITCOINKERNEL_ARG_NONNULL(1);
1660 1661 /**
1662 * Destroy the transaction spent outputs.
1663 */
1664 BITCOINKERNEL_API void btck_transaction_spent_outputs_destroy(btck_TransactionSpentOutputs* transaction_spent_outputs);
1665 1666 ///@}
1667 1668 /** @name Transaction Input
1669 * Functions for working with transaction inputs.
1670 */
1671 ///@{
1672 1673 /**
1674 * @brief Copy a transaction input.
1675 *
1676 * @param[in] transaction_input Non-null.
1677 * @return The copied transaction input.
1678 */
1679 BITCOINKERNEL_API btck_TransactionInput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_copy(
1680 const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
1681 1682 /**
1683 * @brief Get the transaction out point. The returned transaction out point is
1684 * not owned and depends on the lifetime of the transaction.
1685 *
1686 * @param[in] transaction_input Non-null.
1687 * @return The transaction out point.
1688 */
1689 BITCOINKERNEL_API const btck_TransactionOutPoint* btck_transaction_input_get_out_point(
1690 const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
1691 1692 /**
1693 * @brief Get a transaction input's nSequence value.
1694 *
1695 * @param[in] transaction_input Non-null.
1696 * @return The nSequence value.
1697 */
1698 BITCOINKERNEL_API uint32_t btck_transaction_input_get_sequence(
1699 const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
1700 1701 /**
1702 * @brief Get the witness stack of a transaction input. The returned witness
1703 * stack is not owned and depends on the lifetime of the transaction input.
1704 *
1705 * @param[in] transaction_input Non-null.
1706 * @return The witness stack.
1707 */
1708 BITCOINKERNEL_API const btck_WitnessStack* btck_transaction_input_get_witness_stack(
1709 const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
1710 1711 /**
1712 * @brief Serialize the script sig of a transaction input through the passed
1713 * in callback.
1714 *
1715 * @param[in] transaction_input Non-null.
1716 * @param[in] writer Non-null, function pointer for writing bytes.
1717 * @param[in] user_data Nullable, passed back through the writer callback.
1718 * @return The return value of the writer.
1719 */
1720 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_get_script_sig(
1721 const btck_TransactionInput* transaction_input,
1722 btck_WriteBytes writer,
1723 void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
1724 1725 /**
1726 * Destroy the transaction input.
1727 */
1728 BITCOINKERNEL_API void btck_transaction_input_destroy(btck_TransactionInput* transaction_input);
1729 1730 ///@}
1731 1732 /** @name Witness Stack
1733 * Functions for working with witness stacks.
1734 */
1735 ///@{
1736 1737 /**
1738 * @brief Return the number of items in a witness stack.
1739 *
1740 * @param[in] witness_stack Non-null.
1741 * @return The number of witness stack items.
1742 */
1743 BITCOINKERNEL_API size_t btck_witness_stack_count_items(
1744 const btck_WitnessStack* witness_stack) BITCOINKERNEL_ARG_NONNULL(1);
1745 1746 /**
1747 * @brief Serialize a witness stack item at a given index through the passed in
1748 * callback.
1749 *
1750 * @param[in] witness_stack Non-null.
1751 * @param[in] index Index of the item in the witness stack.
1752 * @param[in] writer Non-null, function pointer for writing bytes.
1753 * @param[in] user_data Nullable, passed back through the writer callback.
1754 * @return The return value of the writer.
1755 * @pre index < btck_witness_stack_count_items(witness_stack)
1756 */
1757 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_witness_stack_get_item_at(
1758 const btck_WitnessStack* witness_stack,
1759 size_t index,
1760 btck_WriteBytes writer,
1761 void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 3);
1762 1763 /**
1764 * @brief Copy a witness stack.
1765 *
1766 * @param[in] witness_stack Non-null.
1767 * @return The copied witness stack.
1768 */
1769 BITCOINKERNEL_API btck_WitnessStack* BITCOINKERNEL_WARN_UNUSED_RESULT btck_witness_stack_copy(
1770 const btck_WitnessStack* witness_stack) BITCOINKERNEL_ARG_NONNULL(1);
1771 1772 /**
1773 * Destroy the witness stack.
1774 */
1775 BITCOINKERNEL_API void btck_witness_stack_destroy(btck_WitnessStack* witness_stack);
1776 1777 ///@}
1778 1779 /** @name Transaction Out Point
1780 * Functions for working with transaction out points.
1781 */
1782 ///@{
1783 1784 /**
1785 * @brief Copy a transaction out point.
1786 *
1787 * @param[in] transaction_out_point Non-null.
1788 * @return The copied transaction out point.
1789 */
1790 BITCOINKERNEL_API btck_TransactionOutPoint* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_copy(
1791 const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
1792 1793 /**
1794 * @brief Get the output position from the transaction out point.
1795 *
1796 * @param[in] transaction_out_point Non-null.
1797 * @return The output index.
1798 */
1799 BITCOINKERNEL_API uint32_t btck_transaction_out_point_get_index(
1800 const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
1801 1802 /**
1803 * @brief Get the txid from the transaction out point. The returned txid is
1804 * not owned and depends on the lifetime of the transaction out point.
1805 *
1806 * @param[in] transaction_out_point Non-null.
1807 * @return The txid.
1808 */
1809 BITCOINKERNEL_API const btck_Txid* btck_transaction_out_point_get_txid(
1810 const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
1811 1812 /**
1813 * Destroy the transaction out point.
1814 */
1815 BITCOINKERNEL_API void btck_transaction_out_point_destroy(btck_TransactionOutPoint* transaction_out_point);
1816 1817 ///@}
1818 1819 /** @name Txid
1820 * Functions for working with txids.
1821 */
1822 ///@{
1823 1824 /**
1825 * @brief Copy a txid.
1826 *
1827 * @param[in] txid Non-null.
1828 * @return The copied txid.
1829 */
1830 BITCOINKERNEL_API btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_txid_copy(
1831 const btck_Txid* txid) BITCOINKERNEL_ARG_NONNULL(1);
1832 1833 /**
1834 * @brief Check if two txids are equal.
1835 *
1836 * @param[in] txid1 Non-null.
1837 * @param[in] txid2 Non-null.
1838 * @return 0 if the txid is not equal.
1839 */
1840 BITCOINKERNEL_API int btck_txid_equals(
1841 const btck_Txid* txid1, const btck_Txid* txid2) BITCOINKERNEL_ARG_NONNULL(1, 2);
1842 1843 /**
1844 * @brief Serializes the txid to bytes.
1845 *
1846 * @param[in] txid Non-null.
1847 * @param[out] output The serialized txid.
1848 */
1849 BITCOINKERNEL_API void btck_txid_to_bytes(
1850 const btck_Txid* txid, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2);
1851 1852 /**
1853 * Destroy the txid.
1854 */
1855 BITCOINKERNEL_API void btck_txid_destroy(btck_Txid* txid);
1856 1857 ///@}
1858 1859 /** @name Coin
1860 * Functions for working with coins.
1861 */
1862 ///@{
1863 1864 /**
1865 * @brief Copy a coin.
1866 *
1867 * @param[in] coin Non-null.
1868 * @return The copied coin.
1869 */
1870 BITCOINKERNEL_API btck_Coin* BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_copy(
1871 const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
1872 1873 /**
1874 * @brief Returns the block height where the transaction that
1875 * created this coin was included in.
1876 *
1877 * @param[in] coin Non-null.
1878 * @return The block height of the coin.
1879 */
1880 BITCOINKERNEL_API uint32_t btck_coin_confirmation_height(
1881 const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
1882 1883 /**
1884 * @brief Returns whether the containing transaction was a coinbase.
1885 *
1886 * @param[in] coin Non-null.
1887 * @return 1 if the coin is a coinbase coin, 0 otherwise.
1888 */
1889 BITCOINKERNEL_API int btck_coin_is_coinbase(
1890 const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
1891 1892 /**
1893 * @brief Return the transaction output of a coin. The returned pointer is
1894 * unowned and only valid for the lifetime of the coin.
1895 *
1896 * @param[in] coin Non-null.
1897 * @return A transaction output pointer.
1898 */
1899 BITCOINKERNEL_API const btck_TransactionOutput* btck_coin_get_output(
1900 const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
1901 1902 /**
1903 * Destroy the coin.
1904 */
1905 BITCOINKERNEL_API void btck_coin_destroy(btck_Coin* coin);
1906 1907 ///@}
1908 1909 /** @name BlockHash
1910 * Functions for working with block hashes.
1911 */
1912 ///@{
1913 1914 /**
1915 * @brief Create a block hash from its raw data.
1916 */
1917 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_create(
1918 const unsigned char block_hash[32]) BITCOINKERNEL_ARG_NONNULL(1);
1919 1920 /**
1921 * @brief Check if two block hashes are equal.
1922 *
1923 * @param[in] hash1 Non-null.
1924 * @param[in] hash2 Non-null.
1925 * @return 0 if the block hashes are not equal.
1926 */
1927 BITCOINKERNEL_API int btck_block_hash_equals(
1928 const btck_BlockHash* hash1, const btck_BlockHash* hash2) BITCOINKERNEL_ARG_NONNULL(1, 2);
1929 1930 /**
1931 * @brief Copy a block hash.
1932 *
1933 * @param[in] block_hash Non-null.
1934 * @return The copied block hash.
1935 */
1936 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_copy(
1937 const btck_BlockHash* block_hash) BITCOINKERNEL_ARG_NONNULL(1);
1938 1939 /**
1940 * @brief Serializes the block hash to bytes.
1941 *
1942 * @param[in] block_hash Non-null.
1943 * @param[in] output The serialized block hash.
1944 */
1945 BITCOINKERNEL_API void btck_block_hash_to_bytes(
1946 const btck_BlockHash* block_hash, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2);
1947 1948 /**
1949 * Destroy the block hash.
1950 */
1951 BITCOINKERNEL_API void btck_block_hash_destroy(btck_BlockHash* block_hash);
1952 1953 ///@}
1954 1955 /**
1956 * @name Block Header
1957 * Functions for working with block headers.
1958 */
1959 ///@{
1960 1961 /**
1962 * @brief Create a btck_BlockHeader from serialized data.
1963 *
1964 * @param[in] raw_block_header Non-null, serialized header data (80 bytes)
1965 * @param[in] raw_block_header_len Length of serialized header (must be 80)
1966 * @return btck_BlockHeader, or null on error.
1967 */
1968 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_create(
1969 const void* raw_block_header, size_t raw_block_header_len) BITCOINKERNEL_ARG_NONNULL(1);
1970 1971 /**
1972 * @brief Copy a btck_BlockHeader.
1973 *
1974 * @param[in] header Non-null btck_BlockHeader.
1975 * @return Copied btck_BlockHeader.
1976 */
1977 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_copy(
1978 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
1979 1980 /**
1981 * @brief Get the btck_BlockHash.
1982 *
1983 * @param[in] header Non-null header
1984 * @return btck_BlockHash.
1985 */
1986 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_get_hash(
1987 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
1988 1989 /**
1990 * @brief Get the previous btck_BlockHash from btck_BlockHeader. The returned hash
1991 * is unowned and only valid for the lifetime of the btck_BlockHeader.
1992 *
1993 * @param[in] header Non-null btck_BlockHeader
1994 * @return Previous btck_BlockHash
1995 */
1996 BITCOINKERNEL_API const btck_BlockHash* btck_block_header_get_prev_hash(
1997 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
1998 1999 /**
2000 * @brief Get the timestamp from btck_BlockHeader.
2001 *
2002 * @param[in] header Non-null btck_BlockHeader
2003 * @return Block timestamp (Unix epoch seconds)
2004 */
2005 BITCOINKERNEL_API uint32_t btck_block_header_get_timestamp(
2006 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
2007 2008 /**
2009 * @brief Get the nBits difficulty target from btck_BlockHeader.
2010 *
2011 * @param[in] header Non-null btck_BlockHeader
2012 * @return Difficulty target (compact format)
2013 */
2014 BITCOINKERNEL_API uint32_t btck_block_header_get_bits(
2015 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
2016 2017 /**
2018 * @brief Get the version from btck_BlockHeader.
2019 *
2020 * @param[in] header Non-null btck_BlockHeader
2021 * @return Block version
2022 */
2023 BITCOINKERNEL_API int32_t btck_block_header_get_version(
2024 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
2025 2026 /**
2027 * @brief Get the nonce from btck_BlockHeader.
2028 *
2029 * @param[in] header Non-null btck_BlockHeader
2030 * @return Nonce
2031 */
2032 BITCOINKERNEL_API uint32_t btck_block_header_get_nonce(
2033 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
2034 2035 /**
2036 * @brief Serializes the btck_BlockHeader to bytes.
2037 * This is consensus serialization that is also used for the P2P network.
2038 *
2039 * @param[in] header Non-null.
2040 * @param[out] output The serialized block header (80 bytes).
2041 * @return 0 on success.
2042 */
2043 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_to_bytes(
2044 const btck_BlockHeader* header, unsigned char output[80]) BITCOINKERNEL_ARG_NONNULL(1, 2);
2045 2046 /**
2047 * Destroy the btck_BlockHeader.
2048 */
2049 BITCOINKERNEL_API void btck_block_header_destroy(btck_BlockHeader* header);
2050 2051 ///@}
2052 2053 #ifdef __cplusplus
2054 } // extern "C"
2055 #endif // __cplusplus
2056 2057 #endif // BITCOIN_KERNEL_BITCOINKERNEL_H
2058