The C interface to Bitcoin validation components

251typedef struct btck_Chain btck_Chain;
252
253/**
254 * Opaque data structure for holding the state of a transaction during validation.
255 *
256 * Contains information indicating whether validation was successful, and if not
257 * which step during transaction validation failed.
258 */
259typedef struct btck_TxValidationState btck_TxValidationState;
260
261/**
262 * Opaque data structure for holding a block's spent outputs.
263 *
264 * Contains all the previous outputs consumed by all transactions in a specific
265 * block. Internally it holds a nested vector. The top level vector has an
266 * entry for each transaction in a block (in order of the actual transactions
267 * of the block and without the coinbase transaction). This is exposed through
268 * @ref btck_TransactionSpentOutputs. Each btck_TransactionSpentOutputs is in
269 * turn a vector of all the previous outputs of a transaction (in order of
270 * their corresponding inputs).
271 */
272typedef struct btck_BlockSpentOutputs btck_BlockSpentOutputs;
273
274/**
275 * Opaque data structure for holding a transaction's spent outputs.
276 *
277 * Holds the coins consumed by a certain transaction. Retrieved through the
278 * @ref btck_BlockSpentOutputs. The coins are in the same order as the
279 * transaction's inputs consuming them.
280 */
281typedef struct btck_TransactionSpentOutputs btck_TransactionSpentOutputs;
282
283/**
284 * Opaque data structure for holding a coin.
285 *
286 * Holds information on the @ref btck_TransactionOutput held within,
287 * including the height it was spent at and whether it is a coinbase output.
288 */
289typedef struct btck_Coin btck_Coin;
290
291/**
292 * Opaque data structure for holding a block hash.
293 *
294 * This is a type-safe identifier for a block.
295 */
296typedef struct btck_BlockHash btck_BlockHash;
297
298/**
299 * Opaque data structure for holding a transaction input.
300 *
301 * Holds information on the @ref btck_TransactionOutPoint, @ref btck_WitnessStack and script_sig held within.
302 */
303typedef struct btck_TransactionInput btck_TransactionInput;
304
305/**
306 * Opaque data structure for holding a witness stack.
307 *
308 * Holds a sequence of witness stack items.
309 */
310typedef struct btck_WitnessStack btck_WitnessStack;
311
312/**
313 * Opaque data structure for holding a transaction out point.
314 *
315 * Holds the txid and output index it is pointing to.
316 */
317typedef struct btck_TransactionOutPoint btck_TransactionOutPoint;
318
319/**
320 * Opaque data structure for holding precomputed transaction data.
321 *
322 * Reusable when verifying multiple inputs of the same transaction.
323 * This avoids recomputing transaction hashes for each input.
324 *
325 * Required when verifying a taproot input.
326 */
327typedef struct btck_PrecomputedTransactionData btck_PrecomputedTransactionData;
328
329/**
330 * Opaque data structure for holding a btck_Txid.
331 *
332 * This is a type-safe identifier for a transaction.
333 */
334typedef struct btck_Txid btck_Txid;
335
336/**
337 * Opaque data structure for holding a btck_BlockHeader.
338 */
339typedef struct btck_BlockHeader btck_BlockHeader;
340
341/** Current sync state passed to tip changed callbacks. */
342typedef uint8_t btck_SynchronizationState;
343#define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
344#define btck_SynchronizationState_INIT_DOWNLOAD ((btck_SynchronizationState)(1))
345#define btck_SynchronizationState_POST_INIT ((btck_SynchronizationState)(2))
346
347/** Possible warning types issued by validation. */
348typedef uint8_t btck_Warning;
349#define btck_Warning_UNKNOWN_NEW_RULES_ACTIVATED ((btck_Warning)(0))
350#define btck_Warning_LARGE_WORK_INVALID_CHAIN ((btck_Warning)(1))
351
352/** Callback function types */
353
354/**
355 * Function signature for the global logging callback. All bitcoin kernel
356 * internal logs will pass through this callback.
357 */
358typedef void (*btck_LogCallback)(void* user_data, const char* message, size_t message_len);
359
360/**
361 * Function signature for freeing user data.
362 */
363typedef void (*btck_DestroyCallback)(void* user_data);
364
365/**
366 * Function signatures for the kernel notifications.
367 */
368typedef void (*btck_NotifyBlockTip)(void* user_data, btck_SynchronizationState state, const btck_BlockTreeEntry* entry, double verification_progress);
369typedef void (*btck_NotifyHeaderTip)(void* user_data, btck_SynchronizationState state, int64_t height, int64_t timestamp, int presync);
370typedef void (*btck_NotifyProgress)(void* user_data, const char* title, size_t title_len, int progress_percent, int resume_possible);
371typedef void (*btck_NotifyWarningSet)(void* user_data, btck_Warning warning, const char* message, size_t message_len);
372typedef void (*btck_NotifyWarningUnset)(void* user_data, btck_Warning warning);
373typedef void (*btck_NotifyFlushError)(void* user_data, const char* message, size_t message_len);
374typedef void (*btck_NotifyFatalError)(void* user_data, const char* message, size_t message_len);
375
376/**
377 * Function signatures for the validation interface.
378 */
379typedef void (*btck_ValidationInterfaceBlockChecked)(void* user_data, btck_Block* block, const btck_BlockValidationState* state);
380typedef void (*btck_ValidationInterfacePoWValidBlock)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
381typedef void (*btck_ValidationInterfaceBlockConnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
382typedef void (*btck_ValidationInterfaceBlockDisconnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
383
384/**
385 * Function signature for serializing data.
386 *
387 * Returns 0 to indicate success.
388 */
389typedef int (*btck_WriteBytes)(const void* bytes, size_t size, void* userdata);
390
391/**
392 * Whether a validated data structure is valid, invalid, or an error was
393 * encountered during processing.
394 */
395typedef uint8_t btck_ValidationMode;
396#define btck_ValidationMode_VALID ((btck_ValidationMode)(0))
397#define btck_ValidationMode_INVALID ((btck_ValidationMode)(1))
398#define btck_ValidationMode_INTERNAL_ERROR ((btck_ValidationMode)(2))
399
400/**
401 * A granular "reason" why a block was invalid.
402 */
403typedef uint32_t btck_BlockValidationResult;
404#define btck_BlockValidationResult_UNSET ((btck_BlockValidationResult)(0))           //!< initial value. Block has not yet been rejected
405#define btck_BlockValidationResult_CONSENSUS ((btck_BlockValidationResult)(1))       //!< invalid by consensus rules (excluding any below reasons)
406#define btck_BlockValidationResult_CACHED_INVALID ((btck_BlockValidationResult)(2))  //!< this block was cached as being invalid and we didn't store the reason why
407#define btck_BlockValidationResult_INVALID_HEADER ((btck_BlockValidationResult)(3))  //!< invalid proof of work or time too old
408#define btck_BlockValidationResult_MUTATED ((btck_BlockValidationResult)(4))         //!< the block's data didn't match the data committed to by the PoW
409#define btck_BlockValidationResult_MISSING_PREV ((btck_BlockValidationResult)(5))    //!< We don't have the previous block the checked one is built on
410#define btck_BlockValidationResult_INVALID_PREV ((btck_BlockValidationResult)(6))    //!< A block this one builds on is invalid
411#define btck_BlockValidationResult_TIME_FUTURE ((btck_BlockValidationResult)(7))     //!< block timestamp was > 2 hours in the future (or our clock is bad)
412#define btck_BlockValidationResult_HEADER_LOW_WORK ((btck_BlockValidationResult)(8)) //!< the block header may be on a too-little-work chain
413
414/**
415 * Indicates the reason why a transaction failed validation. The subset of
416 * values reachable depends on which validation function was used.
417 */
418typedef uint32_t btck_TxValidationResult;
419#define btck_TxValidationResult_UNSET               ((btck_TxValidationResult)(0))  //!< initial value. Tx has not yet been rejected
420#define btck_TxValidationResult_CONSENSUS           ((btck_TxValidationResult)(1))  //!< invalid by consensus rules
421#define btck_TxValidationResult_INPUTS_NOT_STANDARD ((btck_TxValidationResult)(2))  //!< inputs (covered by txid) failed policy rules
422#define btck_TxValidationResult_NOT_STANDARD        ((btck_TxValidationResult)(3))  //!< otherwise didn't meet local policy rules
423#define btck_TxValidationResult_MISSING_INPUTS      ((btck_TxValidationResult)(4))  //!< transaction was missing some of its inputs
424#define btck_TxValidationResult_PREMATURE_SPEND     ((btck_TxValidationResult)(5))  //!< transaction spends a coinbase too early, or violates locktime/sequence locks
425#define btck_TxValidationResult_WITNESS_MUTATED     ((btck_TxValidationResult)(6))  //!< witness may have been malleated or is prior to SegWit activation
426#define btck_TxValidationResult_WITNESS_STRIPPED    ((btck_TxValidationResult)(7))  //!< transaction is missing a witness
427#define btck_TxValidationResult_CONFLICT            ((btck_TxValidationResult)(8))  //!< tx already in mempool or conflicts with a tx in the chain
428#define btck_TxValidationResult_MEMPOOL_POLICY      ((btck_TxValidationResult)(9))  //!< violated mempool's fee/size/descendant/RBF/etc limits
429#define btck_TxValidationResult_NO_MEMPOOL          ((btck_TxValidationResult)(10)) //!< this node does not have a mempool so can't validate the transaction
430#define btck_TxValidationResult_RECONSIDERABLE      ((btck_TxValidationResult)(11)) //!< fails some policy, but might be acceptable if submitted in a (different) package
431#define btck_TxValidationResult_UNKNOWN             ((btck_TxValidationResult)(12)) //!< transaction was not validated because package failed
432
433/**
434 * Holds the validation interface callbacks. The user data pointer may be used
435 * to point to user-defined structures to make processing the validation
436 * callbacks easier. Note that these callbacks block any further validation
437 * execution when they are called.
438 */
439typedef struct {
440    void* user_data;                                              //!< Holds a user-defined opaque structure that is passed to the validation
441                                                                  //!< interface callbacks. If user_data_destroy is also defined ownership of the
442                                                                  //!< user_data is passed to the created context options and subsequently context.
443    btck_DestroyCallback user_data_destroy;                       //!< Frees the provided user data structure.
444    btck_ValidationInterfaceBlockChecked block_checked;           //!< Called when a new block has been fully validated. Contains the
445                                                                  //!< result of its validation.
446    btck_ValidationInterfacePoWValidBlock pow_valid_block;        //!< Called when a new block extends the header chain and has a valid transaction
447                                                                  //!< and segwit merkle root.
448    btck_ValidationInterfaceBlockConnected block_connected;       //!< Called when a block is valid and has now been connected to the best chain.
449    btck_ValidationInterfaceBlockDisconnected block_disconnected; //!< Called during a re-org when a block has been removed from the best chain.
450} btck_ValidationInterfaceCallbacks;
451
452/**
453 * A struct for holding the kernel notification callbacks. The user data
454 * pointer may be used to point to user-defined structures to make processing
455 * the notifications easier.
456 *
457 * If user_data_destroy is provided, the kernel will automatically call this
458 * callback to clean up user_data when the notification interface object is destroyed.
459 * If user_data_destroy is NULL, it is the user's responsibility to ensure that
460 * the user_data outlives the kernel objects. Notifications can
461 * occur even as kernel objects are deleted, so care has to be taken to ensure
462 * safe unwinding.
463 */
464typedef struct {
465    void* user_data;                        //!< Holds a user-defined opaque structure that is passed to the notification callbacks.
466                                            //!< If user_data_destroy is also defined ownership of the user_data is passed to the
467                                            //!< created context options and subsequently context.
468    btck_DestroyCallback user_data_destroy; //!< Frees the provided user data structure.
469    btck_NotifyBlockTip block_tip;          //!< The chain's tip was updated to the provided block entry.
470    btck_NotifyHeaderTip header_tip;        //!< A new best block header was added.
471    btck_NotifyProgress progress;           //!< Reports on current block synchronization progress.
472    btck_NotifyWarningSet warning_set;      //!< A warning issued by the kernel library during validation.
473    btck_NotifyWarningUnset warning_unset;  //!< A previous condition leading to the issuance of a warning is no longer given.
474    btck_NotifyFlushError flush_error;      //!< An error encountered when flushing data to disk.
475    btck_NotifyFatalError fatal_error;      //!< An unrecoverable system error encountered by the library.
476} btck_NotificationInterfaceCallbacks;
477
478/**
479 * A collection of logging categories that may be encountered by kernel code.
480 */
481typedef uint8_t btck_LogCategory;
482#define btck_LogCategory_ALL ((btck_LogCategory)(0))
483#define btck_LogCategory_BENCH ((btck_LogCategory)(1))
484#define btck_LogCategory_BLOCKSTORAGE ((btck_LogCategory)(2))
485#define btck_LogCategory_COINDB ((btck_LogCategory)(3))
486#define btck_LogCategory_LEVELDB ((btck_LogCategory)(4))
487#define btck_LogCategory_MEMPOOL ((btck_LogCategory)(5))
488#define btck_LogCategory_PRUNE ((btck_LogCategory)(6))
489#define btck_LogCategory_RAND ((btck_LogCategory)(7))
490#define btck_LogCategory_REINDEX ((btck_LogCategory)(8))
491#define btck_LogCategory_VALIDATION ((btck_LogCategory)(9))
492#define btck_LogCategory_KERNEL ((btck_LogCategory)(10))
493
494/**
495 * The level at which logs should be produced.
496 */
497typedef uint8_t btck_LogLevel;
498#define btck_LogLevel_TRACE ((btck_LogLevel)(0))
499#define btck_LogLevel_DEBUG ((btck_LogLevel)(1))
500#define btck_LogLevel_INFO ((btck_LogLevel)(2))