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