bitcoinkernel.h
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 /* Warning attributes */ 33 #if defined(__GNUC__) 34 #define BITCOINKERNEL_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__)) 35 #else 36 #define BITCOINKERNEL_WARN_UNUSED_RESULT 37 #endif 38 39 /** 40 * BITCOINKERNEL_ARG_NONNULL is a compiler attribute used to indicate that 41 * certain pointer arguments to a function are not expected to be null. 42 * 43 * Callers must not pass a null pointer for arguments marked with this attribute, 44 * as doing so may result in undefined behavior. This attribute should only be 45 * used for arguments where a null pointer is unambiguously a programmer error, 46 * such as for opaque handles, and not for pointers to raw input data that might 47 * validly be null (e.g., from an empty std::span or std::string). 48 */ 49 #if !defined(BITCOINKERNEL_BUILD) && defined(__GNUC__) 50 #define BITCOINKERNEL_ARG_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__))) 51 #else 52 #define BITCOINKERNEL_ARG_NONNULL(...) 53 #endif 54 55 #ifdef __cplusplus 56 extern "C" { 57 #endif // __cplusplus 58 59 /** 60 * @page remarks Remarks 61 * 62 * @section purpose Purpose 63 * 64 * This header currently exposes an API for interacting with parts of Bitcoin 65 * Core's consensus code. Users can validate blocks, iterate the block index, 66 * read block and undo data from disk, and validate scripts. The header is 67 * unversioned and not stable yet. Users should expect breaking changes. It is 68 * also not yet included in releases of Bitcoin Core. 69 * 70 * @section context Context 71 * 72 * The library provides a built-in static constant kernel context. This static 73 * context offers only limited functionality. It detects and self-checks the 74 * correct sha256 implementation, initializes the random number generator and 75 * self-checks the secp256k1 static context. It is used internally for 76 * otherwise "context-free" operations. This means that the user is not 77 * required to initialize their own context before using the library. 78 * 79 * The user should create their own context for passing it to state-rich validation 80 * functions and holding callbacks for kernel events. 81 * 82 * @section error Error handling 83 * 84 * Functions communicate an error through their return types, usually returning 85 * a nullptr or a status code as documented by the returning function. 86 * Additionally, verification functions, e.g. for scripts, may communicate more 87 * detailed error information through status code out parameters. 88 * 89 * Fine-grained validation information is communicated through the validation 90 * interface. 91 * 92 * The kernel notifications issue callbacks for errors. These are usually 93 * indicative of a system error. If such an error is issued, it is recommended 94 * to halt and tear down the existing kernel objects. Remediating the error may 95 * require system intervention by the user. 96 * 97 * @section pointer Pointer and argument conventions 98 * 99 * The user is responsible for de-allocating the memory owned by pointers 100 * returned by functions. Typically pointers returned by *_create(...) functions 101 * can be de-allocated by corresponding *_destroy(...) functions. 102 * 103 * A function that takes pointer arguments makes no assumptions on their 104 * lifetime. Once the function returns the user can safely de-allocate the 105 * passed in arguments. 106 * 107 * Const pointers represent views, and do not transfer ownership. Lifetime 108 * guarantees of these objects are described in the respective documentation. 109 * Ownership of these resources may be taken by copying. They are typically 110 * used for iteration with minimal overhead and require some care by the 111 * programmer that their lifetime is not extended beyond that of the original 112 * object. 113 * 114 * Array lengths follow the pointer argument they describe. 115 */ 116 117 /** 118 * Opaque data structure for holding a transaction. 119 */ 120 typedef struct btck_Transaction btck_Transaction; 121 122 /** 123 * Opaque data structure for holding a script pubkey. 124 */ 125 typedef struct btck_ScriptPubkey btck_ScriptPubkey; 126 127 /** 128 * Opaque data structure for holding a transaction output. 129 */ 130 typedef struct btck_TransactionOutput btck_TransactionOutput; 131 132 /** 133 * Opaque data structure for holding a logging connection. 134 * 135 * The logging connection can be used to manually stop logging. 136 * 137 * Messages that were logged before a connection is created are buffered in a 138 * 1MB buffer. Logging can alternatively be permanently disabled by calling 139 * @ref btck_logging_disable. Functions changing the logging settings are 140 * global and change the settings for all existing btck_LoggingConnection 141 * instances. 142 */ 143 typedef struct btck_LoggingConnection btck_LoggingConnection; 144 145 /** 146 * Opaque data structure for holding the chain parameters. 147 * 148 * These are eventually placed into a kernel context through the kernel context 149 * options. The parameters describe the properties of a chain, and may be 150 * instantiated for either mainnet, testnet, signet, or regtest. 151 */ 152 typedef struct btck_ChainParameters btck_ChainParameters; 153 154 /** 155 * Opaque data structure for holding options for creating a new kernel context. 156 * 157 * Once a kernel context has been created from these options, they may be 158 * destroyed. The options hold the notification and validation interface 159 * callbacks as well as the selected chain type until they are passed to the 160 * context. If no options are configured, the context will be instantiated with 161 * no callbacks and for mainnet. Their content and scope can be expanded over 162 * time. 163 */ 164 typedef struct btck_ContextOptions btck_ContextOptions; 165 166 /** 167 * Opaque data structure for holding a kernel context. 168 * 169 * The kernel context is used to initialize internal state and hold the chain 170 * parameters and callbacks for handling error and validation events. Once 171 * other validation objects are instantiated from it, the context is kept in 172 * memory for the duration of their lifetimes. 173 * 174 * The processing of validation events is done through an internal task runner 175 * owned by the context. It passes events through the registered validation 176 * interface callbacks. 177 * 178 * A constructed context can be safely used from multiple threads. 179 */ 180 typedef struct btck_Context btck_Context; 181 182 /** 183 * Opaque data structure for holding a block tree entry. 184 * 185 * This is a pointer to an element in the block index currently in memory of 186 * the chainstate manager. It is valid for the lifetime of the chainstate 187 * manager it was retrieved from. The entry is part of a tree-like structure 188 * that is maintained internally. Every entry, besides the genesis, points to a 189 * single parent. Multiple entries may share a parent, thus forming a tree. 190 * Each entry corresponds to a single block and may be used to retrieve its 191 * data and validation status. 192 */ 193 typedef struct btck_BlockTreeEntry btck_BlockTreeEntry; 194 195 /** 196 * Opaque data structure for holding options for creating a new chainstate 197 * manager. 198 * 199 * The chainstate manager options are used to set some parameters for the 200 * chainstate manager. 201 */ 202 typedef struct btck_ChainstateManagerOptions btck_ChainstateManagerOptions; 203 204 /** 205 * Opaque data structure for holding a chainstate manager. 206 * 207 * The chainstate manager is the central object for doing validation tasks as 208 * well as retrieving data from the chain. Internally it is a complex data 209 * structure with diverse functionality. 210 * 211 * Its functionality will be more and more exposed in the future. 212 */ 213 typedef struct btck_ChainstateManager btck_ChainstateManager; 214 215 /** 216 * Opaque data structure for holding a block. 217 */ 218 typedef struct btck_Block btck_Block; 219 220 /** 221 * Opaque data structure for holding the state of a block during validation. 222 * 223 * Contains information indicating whether validation was successful, and if not 224 * which step during block validation failed. 225 */ 226 typedef struct btck_BlockValidationState btck_BlockValidationState; 227 228 /** 229 * Opaque data structure for holding the currently known best-chain associated 230 * with a chainstate. 231 */ 232 typedef struct btck_Chain btck_Chain; 233 234 /** 235 * Opaque data structure for holding a block's spent outputs. 236 * 237 * Contains all the previous outputs consumed by all transactions in a specific 238 * block. Internally it holds a nested vector. The top level vector has an 239 * entry for each transaction in a block (in order of the actual transactions 240 * of the block and without the coinbase transaction). This is exposed through 241 * @ref btck_TransactionSpentOutputs. Each btck_TransactionSpentOutputs is in 242 * turn a vector of all the previous outputs of a transaction (in order of 243 * their corresponding inputs). 244 */ 245 typedef struct btck_BlockSpentOutputs btck_BlockSpentOutputs; 246 247 /** 248 * Opaque data structure for holding a transaction's spent outputs. 249 * 250 * Holds the coins consumed by a certain transaction. Retrieved through the 251 * @ref btck_BlockSpentOutputs. The coins are in the same order as the 252 * transaction's inputs consuming them. 253 */ 254 typedef struct btck_TransactionSpentOutputs btck_TransactionSpentOutputs; 255 256 /** 257 * Opaque data structure for holding a coin. 258 * 259 * Holds information on the @ref btck_TransactionOutput held within, 260 * including the height it was spent at and whether it is a coinbase output. 261 */ 262 typedef struct btck_Coin btck_Coin; 263 264 /** 265 * Opaque data structure for holding a block hash. 266 * 267 * This is a type-safe identifier for a block. 268 */ 269 typedef struct btck_BlockHash btck_BlockHash; 270 271 /** 272 * Opaque data structure for holding a transaction input. 273 * 274 * Holds information on the @ref btck_TransactionOutPoint held within. 275 */ 276 typedef struct btck_TransactionInput btck_TransactionInput; 277 278 /** 279 * Opaque data structure for holding a transaction out point. 280 * 281 * Holds the txid and output index it is pointing to. 282 */ 283 typedef struct btck_TransactionOutPoint btck_TransactionOutPoint; 284 285 /** 286 * Opaque data structure for holding precomputed transaction data. 287 * 288 * Reusable when verifying multiple inputs of the same transaction. 289 * This avoids recomputing transaction hashes for each input. 290 * 291 * Required when verifying a taproot input. 292 */ 293 typedef struct btck_PrecomputedTransactionData btck_PrecomputedTransactionData; 294 295 /** 296 * Opaque data structure for holding a btck_Txid. 297 * 298 * This is a type-safe identifier for a transaction. 299 */ 300 typedef struct btck_Txid btck_Txid; 301 302 /** 303 * Opaque data structure for holding a btck_BlockHeader. 304 */ 305 typedef struct btck_BlockHeader btck_BlockHeader; 306 307 /** Current sync state passed to tip changed callbacks. */ 308 typedef uint8_t btck_SynchronizationState; 309 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0)) 310 #define btck_SynchronizationState_INIT_DOWNLOAD ((btck_SynchronizationState)(1)) 311 #define btck_SynchronizationState_POST_INIT ((btck_SynchronizationState)(2)) 312 313 /** Possible warning types issued by validation. */ 314 typedef uint8_t btck_Warning; 315 #define btck_Warning_UNKNOWN_NEW_RULES_ACTIVATED ((btck_Warning)(0)) 316 #define btck_Warning_LARGE_WORK_INVALID_CHAIN ((btck_Warning)(1)) 317 318 /** Callback function types */ 319 320 /** 321 * Function signature for the global logging callback. All bitcoin kernel 322 * internal logs will pass through this callback. 323 */ 324 typedef void (*btck_LogCallback)(void* user_data, const char* message, size_t message_len); 325 326 /** 327 * Function signature for freeing user data. 328 */ 329 typedef void (*btck_DestroyCallback)(void* user_data); 330 331 /** 332 * Function signatures for the kernel notifications. 333 */ 334 typedef void (*btck_NotifyBlockTip)(void* user_data, btck_SynchronizationState state, const btck_BlockTreeEntry* entry, double verification_progress); 335 typedef void (*btck_NotifyHeaderTip)(void* user_data, btck_SynchronizationState state, int64_t height, int64_t timestamp, int presync); 336 typedef void (*btck_NotifyProgress)(void* user_data, const char* title, size_t title_len, int progress_percent, int resume_possible); 337 typedef void (*btck_NotifyWarningSet)(void* user_data, btck_Warning warning, const char* message, size_t message_len); 338 typedef void (*btck_NotifyWarningUnset)(void* user_data, btck_Warning warning); 339 typedef void (*btck_NotifyFlushError)(void* user_data, const char* message, size_t message_len); 340 typedef void (*btck_NotifyFatalError)(void* user_data, const char* message, size_t message_len); 341 342 /** 343 * Function signatures for the validation interface. 344 */ 345 typedef void (*btck_ValidationInterfaceBlockChecked)(void* user_data, btck_Block* block, const btck_BlockValidationState* state); 346 typedef void (*btck_ValidationInterfacePoWValidBlock)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry); 347 typedef void (*btck_ValidationInterfaceBlockConnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry); 348 typedef void (*btck_ValidationInterfaceBlockDisconnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry); 349 350 /** 351 * Function signature for serializing data. 352 */ 353 typedef int (*btck_WriteBytes)(const void* bytes, size_t size, void* userdata); 354 355 /** 356 * Whether a validated data structure is valid, invalid, or an error was 357 * encountered during processing. 358 */ 359 typedef uint8_t btck_ValidationMode; 360 #define btck_ValidationMode_VALID ((btck_ValidationMode)(0)) 361 #define btck_ValidationMode_INVALID ((btck_ValidationMode)(1)) 362 #define btck_ValidationMode_INTERNAL_ERROR ((btck_ValidationMode)(2)) 363 364 /** 365 * A granular "reason" why a block was invalid. 366 */ 367 typedef uint32_t btck_BlockValidationResult; 368 #define btck_BlockValidationResult_UNSET ((btck_BlockValidationResult)(0)) //!< initial value. Block has not yet been rejected 369 #define btck_BlockValidationResult_CONSENSUS ((btck_BlockValidationResult)(1)) //!< invalid by consensus rules (excluding any below reasons) 370 #define btck_BlockValidationResult_CACHED_INVALID ((btck_BlockValidationResult)(2)) //!< this block was cached as being invalid and we didn't store the reason why 371 #define btck_BlockValidationResult_INVALID_HEADER ((btck_BlockValidationResult)(3)) //!< invalid proof of work or time too old 372 #define btck_BlockValidationResult_MUTATED ((btck_BlockValidationResult)(4)) //!< the block's data didn't match the data committed to by the PoW 373 #define btck_BlockValidationResult_MISSING_PREV ((btck_BlockValidationResult)(5)) //!< We don't have the previous block the checked one is built on 374 #define btck_BlockValidationResult_INVALID_PREV ((btck_BlockValidationResult)(6)) //!< A block this one builds on is invalid 375 #define btck_BlockValidationResult_TIME_FUTURE ((btck_BlockValidationResult)(7)) //!< block timestamp was > 2 hours in the future (or our clock is bad) 376 #define btck_BlockValidationResult_HEADER_LOW_WORK ((btck_BlockValidationResult)(8)) //!< the block header may be on a too-little-work chain 377 378 /** 379 * Holds the validation interface callbacks. The user data pointer may be used 380 * to point to user-defined structures to make processing the validation 381 * callbacks easier. Note that these callbacks block any further validation 382 * execution when they are called. 383 */ 384 typedef struct { 385 void* user_data; //!< Holds a user-defined opaque structure that is passed to the validation 386 //!< interface callbacks. If user_data_destroy is also defined ownership of the 387 //!< user_data is passed to the created context options and subsequently context. 388 btck_DestroyCallback user_data_destroy; //!< Frees the provided user data structure. 389 btck_ValidationInterfaceBlockChecked block_checked; //!< Called when a new block has been fully validated. Contains the 390 //!< result of its validation. 391 btck_ValidationInterfacePoWValidBlock pow_valid_block; //!< Called when a new block extends the header chain and has a valid transaction 392 //!< and segwit merkle root. 393 btck_ValidationInterfaceBlockConnected block_connected; //!< Called when a block is valid and has now been connected to the best chain. 394 btck_ValidationInterfaceBlockDisconnected block_disconnected; //!< Called during a re-org when a block has been removed from the best chain. 395 } btck_ValidationInterfaceCallbacks; 396 397 /** 398 * A struct for holding the kernel notification callbacks. The user data 399 * pointer may be used to point to user-defined structures to make processing 400 * the notifications easier. 401 * 402 * If user_data_destroy is provided, the kernel will automatically call this 403 * callback to clean up user_data when the notification interface object is destroyed. 404 * If user_data_destroy is NULL, it is the user's responsibility to ensure that 405 * the user_data outlives the kernel objects. Notifications can 406 * occur even as kernel objects are deleted, so care has to be taken to ensure 407 * safe unwinding. 408 */ 409 typedef struct { 410 void* user_data; //!< Holds a user-defined opaque structure that is passed to the notification callbacks. 411 //!< If user_data_destroy is also defined ownership of the user_data is passed to the 412 //!< created context options and subsequently context. 413 btck_DestroyCallback user_data_destroy; //!< Frees the provided user data structure. 414 btck_NotifyBlockTip block_tip; //!< The chain's tip was updated to the provided block entry. 415 btck_NotifyHeaderTip header_tip; //!< A new best block header was added. 416 btck_NotifyProgress progress; //!< Reports on current block synchronization progress. 417 btck_NotifyWarningSet warning_set; //!< A warning issued by the kernel library during validation. 418 btck_NotifyWarningUnset warning_unset; //!< A previous condition leading to the issuance of a warning is no longer given. 419 btck_NotifyFlushError flush_error; //!< An error encountered when flushing data to disk. 420 btck_NotifyFatalError fatal_error; //!< An unrecoverable system error encountered by the library. 421 } btck_NotificationInterfaceCallbacks; 422 423 /** 424 * A collection of logging categories that may be encountered by kernel code. 425 */ 426 typedef uint8_t btck_LogCategory; 427 #define btck_LogCategory_ALL ((btck_LogCategory)(0)) 428 #define btck_LogCategory_BENCH ((btck_LogCategory)(1)) 429 #define btck_LogCategory_BLOCKSTORAGE ((btck_LogCategory)(2)) 430 #define btck_LogCategory_COINDB ((btck_LogCategory)(3)) 431 #define btck_LogCategory_LEVELDB ((btck_LogCategory)(4)) 432 #define btck_LogCategory_MEMPOOL ((btck_LogCategory)(5)) 433 #define btck_LogCategory_PRUNE ((btck_LogCategory)(6)) 434 #define btck_LogCategory_RAND ((btck_LogCategory)(7)) 435 #define btck_LogCategory_REINDEX ((btck_LogCategory)(8)) 436 #define btck_LogCategory_VALIDATION ((btck_LogCategory)(9)) 437 #define btck_LogCategory_KERNEL ((btck_LogCategory)(10)) 438 439 /** 440 * The level at which logs should be produced. 441 */ 442 typedef uint8_t btck_LogLevel; 443 #define btck_LogLevel_TRACE ((btck_LogLevel)(0)) 444 #define btck_LogLevel_DEBUG ((btck_LogLevel)(1)) 445 #define btck_LogLevel_INFO ((btck_LogLevel)(2)) 446 447 /** 448 * Options controlling the format of log messages. 449 * 450 * Set fields as non-zero to indicate true. 451 */ 452 typedef struct { 453 int log_timestamps; //!< Prepend a timestamp to log messages. 454 int log_time_micros; //!< Log timestamps in microsecond precision. 455 int log_threadnames; //!< Prepend the name of the thread to log messages. 456 int log_sourcelocations; //!< Prepend the source location to log messages. 457 int always_print_category_levels; //!< Prepend the log category and level to log messages. 458 } btck_LoggingOptions; 459 460 /** 461 * A collection of status codes that may be issued by the script verify function. 462 */ 463 typedef uint8_t btck_ScriptVerifyStatus; 464 #define btck_ScriptVerifyStatus_OK ((btck_ScriptVerifyStatus)(0)) 465 #define btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION ((btck_ScriptVerifyStatus)(1)) //!< The flags were combined in an invalid way. 466 #define btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED ((btck_ScriptVerifyStatus)(2)) //!< The taproot flag was set, so valid spent_outputs have to be provided. 467 468 /** 469 * Script verification flags that may be composed with each other. 470 */ 471 typedef uint32_t btck_ScriptVerificationFlags; 472 #define btck_ScriptVerificationFlags_NONE ((btck_ScriptVerificationFlags)(0)) 473 #define btck_ScriptVerificationFlags_P2SH ((btck_ScriptVerificationFlags)(1U << 0)) //!< evaluate P2SH (BIP16) subscripts 474 #define btck_ScriptVerificationFlags_DERSIG ((btck_ScriptVerificationFlags)(1U << 2)) //!< enforce strict DER (BIP66) compliance 475 #define btck_ScriptVerificationFlags_NULLDUMMY ((btck_ScriptVerificationFlags)(1U << 4)) //!< enforce NULLDUMMY (BIP147) 476 #define btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY ((btck_ScriptVerificationFlags)(1U << 9)) //!< enable CHECKLOCKTIMEVERIFY (BIP65) 477 #define btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY ((btck_ScriptVerificationFlags)(1U << 10)) //!< enable CHECKSEQUENCEVERIFY (BIP112) 478 #define btck_ScriptVerificationFlags_WITNESS ((btck_ScriptVerificationFlags)(1U << 11)) //!< enable WITNESS (BIP141) 479 #define btck_ScriptVerificationFlags_TAPROOT ((btck_ScriptVerificationFlags)(1U << 17)) //!< enable TAPROOT (BIPs 341 & 342) 480 #define btck_ScriptVerificationFlags_ALL ((btck_ScriptVerificationFlags)(btck_ScriptVerificationFlags_P2SH | \ 481 btck_ScriptVerificationFlags_DERSIG | \ 482 btck_ScriptVerificationFlags_NULLDUMMY | \ 483 btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY | \ 484 btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY | \ 485 btck_ScriptVerificationFlags_WITNESS | \ 486 btck_ScriptVerificationFlags_TAPROOT)) 487 488 typedef uint8_t btck_ChainType; 489 #define btck_ChainType_MAINNET ((btck_ChainType)(0)) 490 #define btck_ChainType_TESTNET ((btck_ChainType)(1)) 491 #define btck_ChainType_TESTNET_4 ((btck_ChainType)(2)) 492 #define btck_ChainType_SIGNET ((btck_ChainType)(3)) 493 #define btck_ChainType_REGTEST ((btck_ChainType)(4)) 494 495 /** @name Transaction 496 * Functions for working with transactions. 497 */ 498 ///@{ 499 500 /** 501 * @brief Create a new transaction from the serialized data. 502 * 503 * @param[in] raw_transaction Serialized transaction. 504 * @param[in] raw_transaction_len Length of the serialized transaction. 505 * @return The transaction, or null on error. 506 */ 507 BITCOINKERNEL_API btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_create( 508 const void* raw_transaction, size_t raw_transaction_len); 509 510 /** 511 * @brief Copy a transaction. Transactions are reference counted, so this just 512 * increments the reference count. 513 * 514 * @param[in] transaction Non-null. 515 * @return The copied transaction. 516 */ 517 BITCOINKERNEL_API btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_copy( 518 const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1); 519 520 /** 521 * @brief Serializes the transaction through the passed in callback to bytes. 522 * This is consensus serialization that is also used for the P2P network. 523 * 524 * @param[in] transaction Non-null. 525 * @param[in] writer Non-null, callback to a write bytes function. 526 * @param[in] user_data Holds a user-defined opaque structure that will be 527 * passed back through the writer callback. 528 * @return 0 on success. 529 */ 530 BITCOINKERNEL_API int btck_transaction_to_bytes( 531 const btck_Transaction* transaction, 532 btck_WriteBytes writer, 533 void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2); 534 535 /** 536 * @brief Get the number of outputs of a transaction. 537 * 538 * @param[in] transaction Non-null. 539 * @return The number of outputs. 540 */ 541 BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_count_outputs( 542 const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1); 543 544 /** 545 * @brief Get the transaction outputs at the provided index. The returned 546 * transaction output is not owned and depends on the lifetime of the 547 * transaction. 548 * 549 * @param[in] transaction Non-null. 550 * @param[in] output_index The index of the transaction output to be retrieved. 551 * @return The transaction output 552 */ 553 BITCOINKERNEL_API const btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_get_output_at( 554 const btck_Transaction* transaction, size_t output_index) BITCOINKERNEL_ARG_NONNULL(1); 555 556 /** 557 * @brief Get the transaction input at the provided index. The returned 558 * transaction input is not owned and depends on the lifetime of the 559 * transaction. 560 * 561 * @param[in] transaction Non-null. 562 * @param[in] input_index The index of the transaction input to be retrieved. 563 * @return The transaction input 564 */ 565 BITCOINKERNEL_API const btck_TransactionInput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_get_input_at( 566 const btck_Transaction* transaction, size_t input_index) BITCOINKERNEL_ARG_NONNULL(1); 567 568 /** 569 * @brief Get the number of inputs of a transaction. 570 * 571 * @param[in] transaction Non-null. 572 * @return The number of inputs. 573 */ 574 BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_count_inputs( 575 const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1); 576 577 /** 578 * @brief Get the txid of a transaction. The returned txid is not owned and 579 * depends on the lifetime of the transaction. 580 * 581 * @param[in] transaction Non-null. 582 * @return The txid. 583 */ 584 BITCOINKERNEL_API const btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_get_txid( 585 const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1); 586 587 /** 588 * Destroy the transaction. 589 */ 590 BITCOINKERNEL_API void btck_transaction_destroy(btck_Transaction* transaction); 591 592 ///@} 593 594 /** @name PrecomputedTransactionData 595 * Functions for working with precomputed transaction data. 596 */ 597 ///@{ 598 599 /** 600 * @brief Create precomputed transaction data for script verification. 601 * 602 * @param[in] tx_to Non-null. 603 * @param[in] spent_outputs Nullable for non-taproot verification. Points to an array of 604 * outputs spent by the transaction. 605 * @param[in] spent_outputs_len Length of the spent_outputs array. 606 * @return The precomputed data, or null on error. 607 */ 608 BITCOINKERNEL_API btck_PrecomputedTransactionData* BITCOINKERNEL_WARN_UNUSED_RESULT btck_precomputed_transaction_data_create( 609 const btck_Transaction* tx_to, 610 const btck_TransactionOutput** spent_outputs, size_t spent_outputs_len) BITCOINKERNEL_ARG_NONNULL(1); 611 612 /** 613 * @brief Copy precomputed transaction data. 614 * 615 * @param[in] precomputed_txdata Non-null. 616 * @return The copied precomputed transaction data. 617 */ 618 BITCOINKERNEL_API btck_PrecomputedTransactionData* BITCOINKERNEL_WARN_UNUSED_RESULT btck_precomputed_transaction_data_copy( 619 const btck_PrecomputedTransactionData* precomputed_txdata) BITCOINKERNEL_ARG_NONNULL(1); 620 621 /** 622 * Destroy the precomputed transaction data. 623 */ 624 BITCOINKERNEL_API void btck_precomputed_transaction_data_destroy(btck_PrecomputedTransactionData* precomputed_txdata); 625 626 ///@} 627 628 /** @name ScriptPubkey 629 * Functions for working with script pubkeys. 630 */ 631 ///@{ 632 633 /** 634 * @brief Create a script pubkey from serialized data. 635 * @param[in] script_pubkey Serialized script pubkey. 636 * @param[in] script_pubkey_len Length of the script pubkey data. 637 * @return The script pubkey. 638 */ 639 BITCOINKERNEL_API btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_create( 640 const void* script_pubkey, size_t script_pubkey_len); 641 642 /** 643 * @brief Copy a script pubkey. 644 * 645 * @param[in] script_pubkey Non-null. 646 * @return The copied script pubkey. 647 */ 648 BITCOINKERNEL_API btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_copy( 649 const btck_ScriptPubkey* script_pubkey) BITCOINKERNEL_ARG_NONNULL(1); 650 651 /** 652 * @brief Verify if the input at input_index of tx_to spends the script pubkey 653 * under the constraints specified by flags. If the 654 * `btck_ScriptVerificationFlags_WITNESS` flag is set in the flags bitfield, the 655 * amount parameter is used. If the taproot flag is set, the precomputed data 656 * must contain the spent outputs. 657 * 658 * @param[in] script_pubkey Non-null, script pubkey to be spent. 659 * @param[in] amount Amount of the script pubkey's associated output. May be zero if 660 * the witness flag is not set. 661 * @param[in] tx_to Non-null, transaction spending the script_pubkey. 662 * @param[in] precomputed_txdata Nullable if the taproot flag is not set. Otherwise, precomputed data 663 * for tx_to with the spent outputs must be provided. 664 * @param[in] input_index Index of the input in tx_to spending the script_pubkey. 665 * @param[in] flags Bitfield of btck_ScriptVerificationFlags controlling validation constraints. 666 * @param[out] status Nullable, will be set to an error code if the operation fails, or OK otherwise. 667 * @return 1 if the script is valid, 0 otherwise. 668 */ 669 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_verify( 670 const btck_ScriptPubkey* script_pubkey, 671 int64_t amount, 672 const btck_Transaction* tx_to, 673 const btck_PrecomputedTransactionData* precomputed_txdata, 674 unsigned int input_index, 675 btck_ScriptVerificationFlags flags, 676 btck_ScriptVerifyStatus* status) BITCOINKERNEL_ARG_NONNULL(1, 3); 677 678 /** 679 * @brief Serializes the script pubkey through the passed in callback to bytes. 680 * 681 * @param[in] script_pubkey Non-null. 682 * @param[in] writer Non-null, callback to a write bytes function. 683 * @param[in] user_data Holds a user-defined opaque structure that will be 684 * passed back through the writer callback. 685 * @return 0 on success. 686 */ 687 BITCOINKERNEL_API int btck_script_pubkey_to_bytes( 688 const btck_ScriptPubkey* script_pubkey, 689 btck_WriteBytes writer, 690 void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2); 691 692 /** 693 * Destroy the script pubkey. 694 */ 695 BITCOINKERNEL_API void btck_script_pubkey_destroy(btck_ScriptPubkey* script_pubkey); 696 697 ///@} 698 699 /** @name TransactionOutput 700 * Functions for working with transaction outputs. 701 */ 702 ///@{ 703 704 /** 705 * @brief Create a transaction output from a script pubkey and an amount. 706 * 707 * @param[in] script_pubkey Non-null. 708 * @param[in] amount The amount associated with the script pubkey for this output. 709 * @return The transaction output. 710 */ 711 BITCOINKERNEL_API btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_create( 712 const btck_ScriptPubkey* script_pubkey, 713 int64_t amount) BITCOINKERNEL_ARG_NONNULL(1); 714 715 /** 716 * @brief Get the script pubkey of the output. The returned 717 * script pubkey is not owned and depends on the lifetime of the 718 * transaction output. 719 * 720 * @param[in] transaction_output Non-null. 721 * @return The script pubkey. 722 */ 723 BITCOINKERNEL_API const btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_get_script_pubkey( 724 const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1); 725 726 /** 727 * @brief Get the amount in the output. 728 * 729 * @param[in] transaction_output Non-null. 730 * @return The amount. 731 */ 732 BITCOINKERNEL_API int64_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_get_amount( 733 const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1); 734 735 /** 736 * @brief Copy a transaction output. 737 * 738 * @param[in] transaction_output Non-null. 739 * @return The copied transaction output. 740 */ 741 BITCOINKERNEL_API btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_copy( 742 const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1); 743 744 /** 745 * Destroy the transaction output. 746 */ 747 BITCOINKERNEL_API void btck_transaction_output_destroy(btck_TransactionOutput* transaction_output); 748 749 ///@} 750 751 /** @name Logging 752 * Logging-related functions. 753 */ 754 ///@{ 755 756 /** 757 * @brief This disables the global internal logger. No log messages will be 758 * buffered internally anymore once this is called and the buffer is cleared. 759 * This function should only be called once and is not thread or re-entry safe. 760 * Log messages will be buffered until this function is called, or a logging 761 * connection is created. This must not be called while a logging connection 762 * already exists. 763 */ 764 BITCOINKERNEL_API void btck_logging_disable(); 765 766 /** 767 * @brief Set some options for the global internal logger. This changes global 768 * settings and will override settings for all existing @ref 769 * btck_LoggingConnection instances. 770 * 771 * @param[in] options Sets formatting options of the log messages. 772 */ 773 BITCOINKERNEL_API void btck_logging_set_options(btck_LoggingOptions options); 774 775 /** 776 * @brief Set the log level of the global internal logger. This does not 777 * enable the selected categories. Use @ref btck_logging_enable_category to 778 * start logging from a specific, or all categories. This changes a global 779 * setting and will override settings for all existing 780 * @ref btck_LoggingConnection instances. 781 * 782 * @param[in] category If btck_LogCategory_ALL is chosen, sets both the global fallback log level 783 * used by all categories that don't have a specific level set, and also 784 * sets the log level for messages logged with the btck_LogCategory_ALL category itself. 785 * For any other category, sets a category-specific log level that overrides 786 * the global fallback for that category only. 787 788 * @param[in] level Log level at which the log category is set. 789 */ 790 BITCOINKERNEL_API void btck_logging_set_level_category(btck_LogCategory category, btck_LogLevel level); 791 792 /** 793 * @brief Enable a specific log category for the global internal logger. This 794 * changes a global setting and will override settings for all existing @ref 795 * btck_LoggingConnection instances. 796 * 797 * @param[in] category If btck_LogCategory_ALL is chosen, all categories will be enabled. 798 */ 799 BITCOINKERNEL_API void btck_logging_enable_category(btck_LogCategory category); 800 801 /** 802 * @brief Disable a specific log category for the global internal logger. This 803 * changes a global setting and will override settings for all existing @ref 804 * btck_LoggingConnection instances. 805 * 806 * @param[in] category If btck_LogCategory_ALL is chosen, all categories will be disabled. 807 */ 808 BITCOINKERNEL_API void btck_logging_disable_category(btck_LogCategory category); 809 810 /** 811 * @brief Start logging messages through the provided callback. Log messages 812 * produced before this function is first called are buffered and on calling this 813 * function are logged immediately. 814 * 815 * @param[in] log_callback Non-null, function through which messages will be logged. 816 * @param[in] user_data Nullable, holds a user-defined opaque structure. Is passed back 817 * to the user through the callback. If the user_data_destroy_callback 818 * is also defined it is assumed that ownership of the user_data is passed 819 * to the created logging connection. 820 * @param[in] user_data_destroy_callback Nullable, function for freeing the user data. 821 * @return A new kernel logging connection, or null on error. 822 */ 823 BITCOINKERNEL_API btck_LoggingConnection* BITCOINKERNEL_WARN_UNUSED_RESULT btck_logging_connection_create( 824 btck_LogCallback log_callback, 825 void* user_data, 826 btck_DestroyCallback user_data_destroy_callback) BITCOINKERNEL_ARG_NONNULL(1); 827 828 /** 829 * Stop logging and destroy the logging connection. 830 */ 831 BITCOINKERNEL_API void btck_logging_connection_destroy(btck_LoggingConnection* logging_connection); 832 833 ///@} 834 835 /** @name ChainParameters 836 * Functions for working with chain parameters. 837 */ 838 ///@{ 839 840 /** 841 * @brief Creates a chain parameters struct with default parameters based on the 842 * passed in chain type. 843 * 844 * @param[in] chain_type Controls the chain parameters type created. 845 * @return An allocated chain parameters opaque struct. 846 */ 847 BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_create( 848 btck_ChainType chain_type); 849 850 /** 851 * Copy the chain parameters. 852 */ 853 BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_copy( 854 const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1); 855 856 /** 857 * Destroy the chain parameters. 858 */ 859 BITCOINKERNEL_API void btck_chain_parameters_destroy(btck_ChainParameters* chain_parameters); 860 861 ///@} 862 863 /** @name ContextOptions 864 * Functions for working with context options. 865 */ 866 ///@{ 867 868 /** 869 * Creates an empty context options. 870 */ 871 BITCOINKERNEL_API btck_ContextOptions* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_options_create(); 872 873 /** 874 * @brief Sets the chain params for the context options. The context created 875 * with the options will be configured for these chain parameters. 876 * 877 * @param[in] context_options Non-null, previously created by @ref btck_context_options_create. 878 * @param[in] chain_parameters Is set to the context options. 879 */ 880 BITCOINKERNEL_API void btck_context_options_set_chainparams( 881 btck_ContextOptions* context_options, 882 const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1, 2); 883 884 /** 885 * @brief Set the kernel notifications for the context options. The context 886 * created with the options will be configured with these notifications. 887 * 888 * @param[in] context_options Non-null, previously created by @ref btck_context_options_create. 889 * @param[in] notifications Is set to the context options. 890 */ 891 BITCOINKERNEL_API void btck_context_options_set_notifications( 892 btck_ContextOptions* context_options, 893 btck_NotificationInterfaceCallbacks notifications) BITCOINKERNEL_ARG_NONNULL(1); 894 895 /** 896 * @brief Set the validation interface callbacks for the context options. The 897 * context created with the options will be configured for these validation 898 * interface callbacks. The callbacks will then be triggered from validation 899 * events issued by the chainstate manager created from the same context. 900 * 901 * @param[in] context_options Non-null, previously created with btck_context_options_create. 902 * @param[in] validation_interface_callbacks The callbacks used for passing validation information to the 903 * user. 904 */ 905 BITCOINKERNEL_API void btck_context_options_set_validation_interface( 906 btck_ContextOptions* context_options, 907 btck_ValidationInterfaceCallbacks validation_interface_callbacks) BITCOINKERNEL_ARG_NONNULL(1); 908 909 /** 910 * Destroy the context options. 911 */ 912 BITCOINKERNEL_API void btck_context_options_destroy(btck_ContextOptions* context_options); 913 914 ///@} 915 916 /** @name Context 917 * Functions for working with contexts. 918 */ 919 ///@{ 920 921 /** 922 * @brief Create a new kernel context. If the options have not been previously 923 * set, their corresponding fields will be initialized to default values; the 924 * context will assume mainnet chain parameters and won't attempt to call the 925 * kernel notification callbacks. 926 * 927 * @param[in] context_options Nullable, created by @ref btck_context_options_create. 928 * @return The allocated context, or null on error. 929 */ 930 BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_create( 931 const btck_ContextOptions* context_options); 932 933 /** 934 * Copy the context. 935 */ 936 BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_copy( 937 const btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1); 938 939 /** 940 * @brief Interrupt can be used to halt long-running validation functions like 941 * when reindexing, importing or processing blocks. 942 * 943 * @param[in] context Non-null. 944 * @return 0 if the interrupt was successful, non-zero otherwise. 945 */ 946 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_interrupt( 947 btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1); 948 949 /** 950 * Destroy the context. 951 */ 952 BITCOINKERNEL_API void btck_context_destroy(btck_Context* context); 953 954 ///@} 955 956 /** @name BlockTreeEntry 957 * Functions for working with block tree entries. 958 */ 959 ///@{ 960 961 /** 962 * @brief Returns the previous block tree entry in the tree, or null if the current 963 * block tree entry is the genesis block. 964 * 965 * @param[in] block_tree_entry Non-null. 966 * @return The previous block tree entry, or null on error or if the current block tree entry is the genesis block. 967 */ 968 BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_previous( 969 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1); 970 971 /** 972 * @brief Return the btck_BlockHeader associated with this entry. 973 * 974 * @param[in] block_tree_entry Non-null. 975 * @return btck_BlockHeader. 976 */ 977 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_block_header( 978 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1); 979 980 /** 981 * @brief Return the height of a certain block tree entry. 982 * 983 * @param[in] block_tree_entry Non-null. 984 * @return The block height. 985 */ 986 BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_height( 987 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1); 988 989 /** 990 * @brief Return the block hash associated with a block tree entry. 991 * 992 * @param[in] block_tree_entry Non-null. 993 * @return The block hash. 994 */ 995 BITCOINKERNEL_API const btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_block_hash( 996 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1); 997 998 /** 999 * @brief Check if two block tree entries are equal. Two block tree entries are equal when they 1000 * point to the same block. 1001 * 1002 * @param[in] entry1 Non-null. 1003 * @param[in] entry2 Non-null. 1004 * @return 1 if the block tree entries are equal, 0 otherwise. 1005 */ 1006 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_equals( 1007 const btck_BlockTreeEntry* entry1, const btck_BlockTreeEntry* entry2) BITCOINKERNEL_ARG_NONNULL(1, 2); 1008 1009 ///@} 1010 1011 /** @name ChainstateManagerOptions 1012 * Functions for working with chainstate manager options. 1013 */ 1014 ///@{ 1015 1016 /** 1017 * @brief Create options for the chainstate manager. 1018 * 1019 * @param[in] context Non-null, the created options and through it the chainstate manager will 1020 * associate with this kernel context for the duration of their lifetimes. 1021 * @param[in] data_directory Non-null, non-empty path string of the directory containing the 1022 * chainstate data. If the directory does not exist yet, it will be 1023 * created. 1024 * @param[in] blocks_directory Non-null, non-empty path string of the directory containing the block 1025 * data. If the directory does not exist yet, it will be created. 1026 * @return The allocated chainstate manager options, or null on error. 1027 */ 1028 BITCOINKERNEL_API btck_ChainstateManagerOptions* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_create( 1029 const btck_Context* context, 1030 const char* data_directory, 1031 size_t data_directory_len, 1032 const char* blocks_directory, 1033 size_t blocks_directory_len) BITCOINKERNEL_ARG_NONNULL(1); 1034 1035 /** 1036 * @brief Set the number of available worker threads used during validation. 1037 * 1038 * @param[in] chainstate_manager_options Non-null, options to be set. 1039 * @param[in] worker_threads The number of worker threads that should be spawned in the thread pool 1040 * used for validation. When set to 0 no parallel verification is done. 1041 * The value range is clamped internally between 0 and 15. 1042 */ 1043 BITCOINKERNEL_API void btck_chainstate_manager_options_set_worker_threads_num( 1044 btck_ChainstateManagerOptions* chainstate_manager_options, 1045 int worker_threads) BITCOINKERNEL_ARG_NONNULL(1); 1046 1047 /** 1048 * @brief Sets wipe db in the options. In combination with calling 1049 * @ref btck_chainstate_manager_import_blocks this triggers either a full reindex, 1050 * or a reindex of just the chainstate database. 1051 * 1052 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create. 1053 * @param[in] wipe_block_tree_db Set wipe block tree db. Should only be 1 if wipe_chainstate_db is 1 too. 1054 * @param[in] wipe_chainstate_db Set wipe chainstate db. 1055 * @return 0 if the set was successful, non-zero if the set failed. 1056 */ 1057 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_set_wipe_dbs( 1058 btck_ChainstateManagerOptions* chainstate_manager_options, 1059 int wipe_block_tree_db, 1060 int wipe_chainstate_db) BITCOINKERNEL_ARG_NONNULL(1); 1061 1062 /** 1063 * @brief Sets block tree db in memory in the options. 1064 * 1065 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create. 1066 * @param[in] block_tree_db_in_memory Set block tree db in memory. 1067 */ 1068 BITCOINKERNEL_API void btck_chainstate_manager_options_update_block_tree_db_in_memory( 1069 btck_ChainstateManagerOptions* chainstate_manager_options, 1070 int block_tree_db_in_memory) BITCOINKERNEL_ARG_NONNULL(1); 1071 1072 /** 1073 * @brief Sets chainstate db in memory in the options. 1074 * 1075 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create. 1076 * @param[in] chainstate_db_in_memory Set chainstate db in memory. 1077 */ 1078 BITCOINKERNEL_API void btck_chainstate_manager_options_update_chainstate_db_in_memory( 1079 btck_ChainstateManagerOptions* chainstate_manager_options, 1080 int chainstate_db_in_memory) BITCOINKERNEL_ARG_NONNULL(1); 1081 1082 /** 1083 * Destroy the chainstate manager options. 1084 */ 1085 BITCOINKERNEL_API void btck_chainstate_manager_options_destroy(btck_ChainstateManagerOptions* chainstate_manager_options); 1086 1087 ///@} 1088 1089 /** @name ChainstateManager 1090 * Functions for chainstate management. 1091 */ 1092 ///@{ 1093 1094 /** 1095 * @brief Create a chainstate manager. This is the main object for many 1096 * validation tasks as well as for retrieving data from the chain and 1097 * interacting with its chainstate and indexes. 1098 * 1099 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create. 1100 * @return The allocated chainstate manager, or null on error. 1101 */ 1102 BITCOINKERNEL_API btck_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_create( 1103 const btck_ChainstateManagerOptions* chainstate_manager_options) BITCOINKERNEL_ARG_NONNULL(1); 1104 1105 /** 1106 * @brief Get the btck_BlockTreeEntry whose associated btck_BlockHeader has the most 1107 * known cumulative proof of work. 1108 * 1109 * @param[in] chainstate_manager Non-null. 1110 * @return The btck_BlockTreeEntry. 1111 */ 1112 BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_best_entry( 1113 const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1); 1114 1115 /** 1116 * @brief Processes and validates the provided btck_BlockHeader. 1117 * 1118 * @param[in] chainstate_manager Non-null. 1119 * @param[in] header Non-null btck_BlockHeader to be validated. 1120 * @param[out] block_validation_state The result of the btck_BlockHeader validation. 1121 * @return 0 if btck_BlockHeader processing completed successfully, non-zero on error. 1122 */ 1123 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_process_block_header( 1124 btck_ChainstateManager* chainstate_manager, 1125 const btck_BlockHeader* header, 1126 btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1, 2, 3); 1127 1128 /** 1129 * @brief Triggers the start of a reindex if the wipe options were previously 1130 * set for the chainstate manager. Can also import an array of existing block 1131 * files selected by the user. 1132 * 1133 * @param[in] chainstate_manager Non-null. 1134 * @param[in] block_file_paths_data Nullable, array of block files described by their full filesystem paths. 1135 * @param[in] block_file_paths_lens Nullable, array containing the lengths of each of the paths. 1136 * @param[in] block_file_paths_data_len Length of the block_file_paths_data and block_file_paths_len arrays. 1137 * @return 0 if the import blocks call was completed successfully, non-zero otherwise. 1138 */ 1139 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_import_blocks( 1140 btck_ChainstateManager* chainstate_manager, 1141 const char** block_file_paths_data, size_t* block_file_paths_lens, 1142 size_t block_file_paths_data_len) BITCOINKERNEL_ARG_NONNULL(1); 1143 1144 /** 1145 * @brief Process and validate the passed in block with the chainstate 1146 * manager. Processing first does checks on the block, and if these passed, 1147 * saves it to disk. It then validates the block against the utxo set. If it is 1148 * valid, the chain is extended with it. The return value is not indicative of 1149 * the block's validity. Detailed information on the validity of the block can 1150 * be retrieved by registering the `block_checked` callback in the validation 1151 * interface. 1152 * 1153 * @param[in] chainstate_manager Non-null. 1154 * @param[in] block Non-null, block to be validated. 1155 * 1156 * @param[out] new_block Nullable, will be set to 1 if this block was not processed before. Note that this means it 1157 * might also not be 1 if processing was attempted before, but the block was found invalid 1158 * before its data was persisted. 1159 * @return 0 if processing the block was successful. Will also return 0 for valid, but duplicate blocks. 1160 */ 1161 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_process_block( 1162 btck_ChainstateManager* chainstate_manager, 1163 const btck_Block* block, 1164 int* new_block) BITCOINKERNEL_ARG_NONNULL(1, 2, 3); 1165 1166 /** 1167 * @brief Returns the best known currently active chain. Its lifetime is 1168 * dependent on the chainstate manager. It can be thought of as a view on a 1169 * vector of block tree entries that form the best chain. The returned chain 1170 * reference always points to the currently active best chain. However, state 1171 * transitions within the chainstate manager (e.g., processing blocks) will 1172 * update the chain's contents. Data retrieved from this chain is only 1173 * consistent up to the point when new data is processed in the chainstate 1174 * manager. It is the user's responsibility to guard against these 1175 * inconsistencies. 1176 * 1177 * @param[in] chainstate_manager Non-null. 1178 * @return The chain. 1179 */ 1180 BITCOINKERNEL_API const btck_Chain* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_active_chain( 1181 const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1); 1182 1183 /** 1184 * @brief Retrieve a block tree entry by its block hash. 1185 * 1186 * @param[in] chainstate_manager Non-null. 1187 * @param[in] block_hash Non-null. 1188 * @return The block tree entry of the block with the passed in hash, or null if 1189 * the block hash is not found. 1190 */ 1191 BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_block_tree_entry_by_hash( 1192 const btck_ChainstateManager* chainstate_manager, 1193 const btck_BlockHash* block_hash) BITCOINKERNEL_ARG_NONNULL(1, 2); 1194 1195 /** 1196 * Destroy the chainstate manager. 1197 */ 1198 BITCOINKERNEL_API void btck_chainstate_manager_destroy(btck_ChainstateManager* chainstate_manager); 1199 1200 ///@} 1201 1202 /** @name Block 1203 * Functions for working with blocks. 1204 */ 1205 ///@{ 1206 1207 /** 1208 * @brief Reads the block the passed in block tree entry points to from disk and 1209 * returns it. 1210 * 1211 * @param[in] chainstate_manager Non-null. 1212 * @param[in] block_tree_entry Non-null. 1213 * @return The read out block, or null on error. 1214 */ 1215 BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_read( 1216 const btck_ChainstateManager* chainstate_manager, 1217 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2); 1218 1219 /** 1220 * @brief Parse a serialized raw block into a new block object. 1221 * 1222 * @param[in] raw_block Serialized block. 1223 * @param[in] raw_block_len Length of the serialized block. 1224 * @return The allocated block, or null on error. 1225 */ 1226 BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_create( 1227 const void* raw_block, size_t raw_block_len); 1228 1229 /** 1230 * @brief Copy a block. Blocks are reference counted, so this just increments 1231 * the reference count. 1232 * 1233 * @param[in] block Non-null. 1234 * @return The copied block. 1235 */ 1236 BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_copy( 1237 const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1); 1238 1239 /** 1240 * @brief Count the number of transactions contained in a block. 1241 * 1242 * @param[in] block Non-null. 1243 * @return The number of transactions in the block. 1244 */ 1245 BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_count_transactions( 1246 const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1); 1247 1248 /** 1249 * @brief Get the transaction at the provided index. The returned transaction 1250 * is not owned and depends on the lifetime of the block. 1251 * 1252 * @param[in] block Non-null. 1253 * @param[in] transaction_index The index of the transaction to be retrieved. 1254 * @return The transaction. 1255 */ 1256 BITCOINKERNEL_API const btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_transaction_at( 1257 const btck_Block* block, size_t transaction_index) BITCOINKERNEL_ARG_NONNULL(1); 1258 1259 /** 1260 * @brief Get the btck_BlockHeader from the block. 1261 * 1262 * Creates a new btck_BlockHeader object from the block's header data. 1263 * 1264 * @param[in] block Non-null btck_Block 1265 * @return btck_BlockHeader. 1266 */ 1267 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_header( 1268 const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1); 1269 1270 /** 1271 * @brief Calculate and return the hash of a block. 1272 * 1273 * @param[in] block Non-null. 1274 * @return The block hash. 1275 */ 1276 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_hash( 1277 const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1); 1278 1279 /** 1280 * @brief Serializes the block through the passed in callback to bytes. 1281 * This is consensus serialization that is also used for the P2P network. 1282 * 1283 * @param[in] block Non-null. 1284 * @param[in] writer Non-null, callback to a write bytes function. 1285 * @param[in] user_data Holds a user-defined opaque structure that will be 1286 * passed back through the writer callback. 1287 * @return 0 on success. 1288 */ 1289 BITCOINKERNEL_API int btck_block_to_bytes( 1290 const btck_Block* block, 1291 btck_WriteBytes writer, 1292 void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2); 1293 1294 /** 1295 * Destroy the block. 1296 */ 1297 BITCOINKERNEL_API void btck_block_destroy(btck_Block* block); 1298 1299 ///@} 1300 1301 /** @name BlockValidationState 1302 * Functions for working with block validation states. 1303 */ 1304 ///@{ 1305 1306 /** 1307 * Create a new btck_BlockValidationState. 1308 */ 1309 BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_create(); 1310 1311 /** 1312 * Returns the validation mode from an opaque btck_BlockValidationState pointer. 1313 */ 1314 BITCOINKERNEL_API btck_ValidationMode btck_block_validation_state_get_validation_mode( 1315 const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1); 1316 1317 /** 1318 * Returns the validation result from an opaque btck_BlockValidationState pointer. 1319 */ 1320 BITCOINKERNEL_API btck_BlockValidationResult btck_block_validation_state_get_block_validation_result( 1321 const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1); 1322 1323 /** 1324 * @brief Copies the btck_BlockValidationState. 1325 * 1326 * @param[in] block_validation_state Non-null. 1327 * @return The copied btck_BlockValidationState. 1328 */ 1329 BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_copy( 1330 const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1); 1331 1332 /** 1333 * Destroy the btck_BlockValidationState. 1334 */ 1335 BITCOINKERNEL_API void btck_block_validation_state_destroy( 1336 btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1); 1337 1338 ///@} 1339 1340 /** @name Chain 1341 * Functions for working with the chain 1342 */ 1343 ///@{ 1344 1345 /** 1346 * @brief Return the height of the tip of the chain. 1347 * 1348 * @param[in] chain Non-null. 1349 * @return The current height. 1350 */ 1351 BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_get_height( 1352 const btck_Chain* chain) BITCOINKERNEL_ARG_NONNULL(1); 1353 1354 /** 1355 * @brief Retrieve a block tree entry by its height in the currently active chain. 1356 * Once retrieved there is no guarantee that it remains in the active chain. 1357 * 1358 * @param[in] chain Non-null. 1359 * @param[in] block_height Height in the chain of the to be retrieved block tree entry. 1360 * @return The block tree entry at a certain height in the currently active chain, or null 1361 * if the height is out of bounds. 1362 */ 1363 BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_get_by_height( 1364 const btck_Chain* chain, 1365 int block_height) BITCOINKERNEL_ARG_NONNULL(1); 1366 1367 /** 1368 * @brief Return true if the passed in chain contains the block tree entry. 1369 * 1370 * @param[in] chain Non-null. 1371 * @param[in] block_tree_entry Non-null. 1372 * @return 1 if the block_tree_entry is in the chain, 0 otherwise. 1373 * 1374 */ 1375 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_contains( 1376 const btck_Chain* chain, 1377 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2); 1378 1379 ///@} 1380 1381 /** @name BlockSpentOutputs 1382 * Functions for working with block spent outputs. 1383 */ 1384 ///@{ 1385 1386 /** 1387 * @brief Reads the block spent coins data the passed in block tree entry points to from 1388 * disk and returns it. 1389 * 1390 * @param[in] chainstate_manager Non-null. 1391 * @param[in] block_tree_entry Non-null. 1392 * @return The read out block spent outputs, or null on error. 1393 */ 1394 BITCOINKERNEL_API btck_BlockSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_read( 1395 const btck_ChainstateManager* chainstate_manager, 1396 const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2); 1397 1398 /** 1399 * @brief Copy a block's spent outputs. 1400 * 1401 * @param[in] block_spent_outputs Non-null. 1402 * @return The copied block spent outputs. 1403 */ 1404 BITCOINKERNEL_API btck_BlockSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_copy( 1405 const btck_BlockSpentOutputs* block_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1); 1406 1407 /** 1408 * @brief Returns the number of transaction spent outputs whose data is contained in 1409 * block spent outputs. 1410 * 1411 * @param[in] block_spent_outputs Non-null. 1412 * @return The number of transaction spent outputs data in the block spent outputs. 1413 */ 1414 BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_count( 1415 const btck_BlockSpentOutputs* block_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1); 1416 1417 /** 1418 * @brief Returns a transaction spent outputs contained in the block spent 1419 * outputs at a certain index. The returned pointer is unowned and only valid 1420 * for the lifetime of block_spent_outputs. 1421 * 1422 * @param[in] block_spent_outputs Non-null. 1423 * @param[in] transaction_spent_outputs_index The index of the transaction spent outputs within the block spent outputs. 1424 * @return A transaction spent outputs pointer. 1425 */ 1426 BITCOINKERNEL_API const btck_TransactionSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_get_transaction_spent_outputs_at( 1427 const btck_BlockSpentOutputs* block_spent_outputs, 1428 size_t transaction_spent_outputs_index) BITCOINKERNEL_ARG_NONNULL(1); 1429 1430 /** 1431 * Destroy the block spent outputs. 1432 */ 1433 BITCOINKERNEL_API void btck_block_spent_outputs_destroy(btck_BlockSpentOutputs* block_spent_outputs); 1434 1435 ///@} 1436 1437 /** @name TransactionSpentOutputs 1438 * Functions for working with the spent coins of a transaction 1439 */ 1440 ///@{ 1441 1442 /** 1443 * @brief Copy a transaction's spent outputs. 1444 * 1445 * @param[in] transaction_spent_outputs Non-null. 1446 * @return The copied transaction spent outputs. 1447 */ 1448 BITCOINKERNEL_API btck_TransactionSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_spent_outputs_copy( 1449 const btck_TransactionSpentOutputs* transaction_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1); 1450 1451 /** 1452 * @brief Returns the number of previous transaction outputs contained in the 1453 * transaction spent outputs data. 1454 * 1455 * @param[in] transaction_spent_outputs Non-null 1456 * @return The number of spent transaction outputs for the transaction. 1457 */ 1458 BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_spent_outputs_count( 1459 const btck_TransactionSpentOutputs* transaction_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1); 1460 1461 /** 1462 * @brief Returns a coin contained in the transaction spent outputs at a 1463 * certain index. The returned pointer is unowned and only valid for the 1464 * lifetime of transaction_spent_outputs. 1465 * 1466 * @param[in] transaction_spent_outputs Non-null. 1467 * @param[in] coin_index The index of the to be retrieved coin within the 1468 * transaction spent outputs. 1469 * @return A coin pointer. 1470 */ 1471 BITCOINKERNEL_API const btck_Coin* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_spent_outputs_get_coin_at( 1472 const btck_TransactionSpentOutputs* transaction_spent_outputs, 1473 size_t coin_index) BITCOINKERNEL_ARG_NONNULL(1); 1474 1475 /** 1476 * Destroy the transaction spent outputs. 1477 */ 1478 BITCOINKERNEL_API void btck_transaction_spent_outputs_destroy(btck_TransactionSpentOutputs* transaction_spent_outputs); 1479 1480 ///@} 1481 1482 /** @name Transaction Input 1483 * Functions for working with transaction inputs. 1484 */ 1485 ///@{ 1486 1487 /** 1488 * @brief Copy a transaction input. 1489 * 1490 * @param[in] transaction_input Non-null. 1491 * @return The copied transaction input. 1492 */ 1493 BITCOINKERNEL_API btck_TransactionInput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_copy( 1494 const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1); 1495 1496 /** 1497 * @brief Get the transaction out point. The returned transaction out point is 1498 * not owned and depends on the lifetime of the transaction. 1499 * 1500 * @param[in] transaction_input Non-null. 1501 * @return The transaction out point. 1502 */ 1503 BITCOINKERNEL_API const btck_TransactionOutPoint* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_get_out_point( 1504 const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1); 1505 1506 /** 1507 * Destroy the transaction input. 1508 */ 1509 BITCOINKERNEL_API void btck_transaction_input_destroy(btck_TransactionInput* transaction_input); 1510 1511 ///@} 1512 1513 /** @name Transaction Out Point 1514 * Functions for working with transaction out points. 1515 */ 1516 ///@{ 1517 1518 /** 1519 * @brief Copy a transaction out point. 1520 * 1521 * @param[in] transaction_out_point Non-null. 1522 * @return The copied transaction out point. 1523 */ 1524 BITCOINKERNEL_API btck_TransactionOutPoint* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_copy( 1525 const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1); 1526 1527 /** 1528 * @brief Get the output position from the transaction out point. 1529 * 1530 * @param[in] transaction_out_point Non-null. 1531 * @return The output index. 1532 */ 1533 BITCOINKERNEL_API uint32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_get_index( 1534 const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1); 1535 1536 /** 1537 * @brief Get the txid from the transaction out point. The returned txid is 1538 * not owned and depends on the lifetime of the transaction out point. 1539 * 1540 * @param[in] transaction_out_point Non-null. 1541 * @return The txid. 1542 */ 1543 BITCOINKERNEL_API const btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_get_txid( 1544 const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1); 1545 1546 /** 1547 * Destroy the transaction out point. 1548 */ 1549 BITCOINKERNEL_API void btck_transaction_out_point_destroy(btck_TransactionOutPoint* transaction_out_point); 1550 1551 ///@} 1552 1553 /** @name Txid 1554 * Functions for working with txids. 1555 */ 1556 ///@{ 1557 1558 /** 1559 * @brief Copy a txid. 1560 * 1561 * @param[in] txid Non-null. 1562 * @return The copied txid. 1563 */ 1564 BITCOINKERNEL_API btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_txid_copy( 1565 const btck_Txid* txid) BITCOINKERNEL_ARG_NONNULL(1); 1566 1567 /** 1568 * @brief Check if two txids are equal. 1569 * 1570 * @param[in] txid1 Non-null. 1571 * @param[in] txid2 Non-null. 1572 * @return 0 if the txid is not equal. 1573 */ 1574 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_txid_equals( 1575 const btck_Txid* txid1, const btck_Txid* txid2) BITCOINKERNEL_ARG_NONNULL(1, 2); 1576 1577 /** 1578 * @brief Serializes the txid to bytes. 1579 * 1580 * @param[in] txid Non-null. 1581 * @param[out] output The serialized txid. 1582 */ 1583 BITCOINKERNEL_API void btck_txid_to_bytes( 1584 const btck_Txid* txid, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2); 1585 1586 /** 1587 * Destroy the txid. 1588 */ 1589 BITCOINKERNEL_API void btck_txid_destroy(btck_Txid* txid); 1590 1591 ///@} 1592 1593 ///@} 1594 1595 /** @name Coin 1596 * Functions for working with coins. 1597 */ 1598 ///@{ 1599 1600 /** 1601 * @brief Copy a coin. 1602 * 1603 * @param[in] coin Non-null. 1604 * @return The copied coin. 1605 */ 1606 BITCOINKERNEL_API btck_Coin* BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_copy( 1607 const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1); 1608 1609 /** 1610 * @brief Returns the block height where the transaction that 1611 * created this coin was included in. 1612 * 1613 * @param[in] coin Non-null. 1614 * @return The block height of the coin. 1615 */ 1616 BITCOINKERNEL_API uint32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_confirmation_height( 1617 const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1); 1618 1619 /** 1620 * @brief Returns whether the containing transaction was a coinbase. 1621 * 1622 * @param[in] coin Non-null. 1623 * @return 1 if the coin is a coinbase coin, 0 otherwise. 1624 */ 1625 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_is_coinbase( 1626 const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1); 1627 1628 /** 1629 * @brief Return the transaction output of a coin. The returned pointer is 1630 * unowned and only valid for the lifetime of the coin. 1631 * 1632 * @param[in] coin Non-null. 1633 * @return A transaction output pointer. 1634 */ 1635 BITCOINKERNEL_API const btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_get_output( 1636 const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1); 1637 1638 /** 1639 * Destroy the coin. 1640 */ 1641 BITCOINKERNEL_API void btck_coin_destroy(btck_Coin* coin); 1642 1643 ///@} 1644 1645 /** @name BlockHash 1646 * Functions for working with block hashes. 1647 */ 1648 ///@{ 1649 1650 /** 1651 * @brief Create a block hash from its raw data. 1652 */ 1653 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_create( 1654 const unsigned char block_hash[32]) BITCOINKERNEL_ARG_NONNULL(1); 1655 1656 /** 1657 * @brief Check if two block hashes are equal. 1658 * 1659 * @param[in] hash1 Non-null. 1660 * @param[in] hash2 Non-null. 1661 * @return 0 if the block hashes are not equal. 1662 */ 1663 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_equals( 1664 const btck_BlockHash* hash1, const btck_BlockHash* hash2) BITCOINKERNEL_ARG_NONNULL(1, 2); 1665 1666 /** 1667 * @brief Copy a block hash. 1668 * 1669 * @param[in] block_hash Non-null. 1670 * @return The copied block hash. 1671 */ 1672 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_copy( 1673 const btck_BlockHash* block_hash) BITCOINKERNEL_ARG_NONNULL(1); 1674 1675 /** 1676 * @brief Serializes the block hash to bytes. 1677 * 1678 * @param[in] block_hash Non-null. 1679 * @param[in] output The serialized block hash. 1680 */ 1681 BITCOINKERNEL_API void btck_block_hash_to_bytes( 1682 const btck_BlockHash* block_hash, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2); 1683 1684 /** 1685 * Destroy the block hash. 1686 */ 1687 BITCOINKERNEL_API void btck_block_hash_destroy(btck_BlockHash* block_hash); 1688 1689 ///@} 1690 1691 /** 1692 * @name Block Header 1693 * Functions for working with block headers. 1694 */ 1695 ///@{ 1696 1697 /** 1698 * @brief Create a btck_BlockHeader from serialized data. 1699 * 1700 * @param[in] raw_block_header Non-null, serialized header data (80 bytes) 1701 * @param[in] raw_block_header_len Length of serialized header (must be 80) 1702 * @return btck_BlockHeader, or null on error. 1703 */ 1704 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_create( 1705 const void* raw_block_header, size_t raw_block_header_len); 1706 1707 /** 1708 * @brief Copy a btck_BlockHeader. 1709 * 1710 * @param[in] header Non-null btck_BlockHeader. 1711 * @return Copied btck_BlockHeader. 1712 */ 1713 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_copy( 1714 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1); 1715 1716 /** 1717 * @brief Get the btck_BlockHash. 1718 * 1719 * @param[in] header Non-null header 1720 * @return btck_BlockHash. 1721 */ 1722 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_get_hash( 1723 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1); 1724 1725 /** 1726 * @brief Get the previous btck_BlockHash from btck_BlockHeader. The returned hash 1727 * is unowned and only valid for the lifetime of the btck_BlockHeader. 1728 * 1729 * @param[in] header Non-null btck_BlockHeader 1730 * @return Previous btck_BlockHash 1731 */ 1732 BITCOINKERNEL_API const btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_get_prev_hash( 1733 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1); 1734 1735 /** 1736 * @brief Get the timestamp from btck_BlockHeader. 1737 * 1738 * @param[in] header Non-null btck_BlockHeader 1739 * @return Block timestamp (Unix epoch seconds) 1740 */ 1741 BITCOINKERNEL_API uint32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_get_timestamp( 1742 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1); 1743 1744 /** 1745 * @brief Get the nBits difficulty target from btck_BlockHeader. 1746 * 1747 * @param[in] header Non-null btck_BlockHeader 1748 * @return Difficulty target (compact format) 1749 */ 1750 BITCOINKERNEL_API uint32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_get_bits( 1751 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1); 1752 1753 /** 1754 * @brief Get the version from btck_BlockHeader. 1755 * 1756 * @param[in] header Non-null btck_BlockHeader 1757 * @return Block version 1758 */ 1759 BITCOINKERNEL_API int32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_get_version( 1760 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1); 1761 1762 /** 1763 * @brief Get the nonce from btck_BlockHeader. 1764 * 1765 * @param[in] header Non-null btck_BlockHeader 1766 * @return Nonce 1767 */ 1768 BITCOINKERNEL_API uint32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_get_nonce( 1769 const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1); 1770 1771 /** 1772 * Destroy the btck_BlockHeader. 1773 */ 1774 BITCOINKERNEL_API void btck_block_header_destroy(btck_BlockHeader* header); 1775 1776 ///@} 1777 1778 #ifdef __cplusplus 1779 } // extern "C" 1780 #endif // __cplusplus 1781 1782 #endif // BITCOIN_KERNEL_BITCOINKERNEL_H