#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for bitcoinkernel.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	kernel_ValidationInterfaceCallbacks

struct	kernel_NotificationInterfaceCallbacks

struct	kernel_LoggingOptions

struct	kernel_BlockHash

struct	kernel_ByteArray

Macros
#define	BITCOINKERNEL_API

#define	BITCOINKERNEL_WARN_UNUSED_RESULT

#define	BITCOINKERNEL_ARG_NONNULL(...)

Typedefs
typedef struct kernel_Transaction	kernel_Transaction

typedef struct kernel_ScriptPubkey	kernel_ScriptPubkey

typedef struct kernel_TransactionOutput	kernel_TransactionOutput

typedef struct kernel_LoggingConnection	kernel_LoggingConnection

typedef struct kernel_ChainParameters	kernel_ChainParameters

typedef struct kernel_ContextOptions	kernel_ContextOptions

typedef struct kernel_Context	kernel_Context

typedef struct kernel_BlockIndex	kernel_BlockIndex

typedef struct kernel_ChainstateManagerOptions	kernel_ChainstateManagerOptions

typedef struct kernel_ChainstateManager	kernel_ChainstateManager

typedef struct kernel_Block	kernel_Block

typedef struct kernel_BlockPointer	kernel_BlockPointer

typedef struct kernel_BlockValidationState	kernel_BlockValidationState

typedef struct kernel_BlockUndo	kernel_BlockUndo

typedef void(*	kernel_LogCallback) (void user_data, const char message, size_t message_len)

typedef void(*	kernel_NotifyBlockTip) (void user_data, kernel_SynchronizationState state, const kernel_BlockIndex index, double verification_progress)

typedef void(*	kernel_NotifyHeaderTip) (void *user_data, kernel_SynchronizationState state, int64_t height, int64_t timestamp, bool presync)

typedef void(*	kernel_NotifyProgress) (void user_data, const char title, size_t title_len, int progress_percent, bool resume_possible)

typedef void(*	kernel_NotifyWarningSet) (void user_data, kernel_Warning warning, const char message, size_t message_len)

typedef void(*	kernel_NotifyWarningUnset) (void *user_data, kernel_Warning warning)

typedef void(*	kernel_NotifyFlushError) (void user_data, const char message, size_t message_len)

typedef void(*	kernel_NotifyFatalError) (void user_data, const char message, size_t message_len)

typedef void(*	kernel_ValidationInterfaceBlockChecked) (void user_data, const kernel_BlockPointer block, const kernel_BlockValidationState *state)

Enumerations
enum	kernel_SynchronizationState { kernel_INIT_REINDEX , kernel_INIT_DOWNLOAD , kernel_POST_INIT }

enum	kernel_Warning { kernel_UNKNOWN_NEW_RULES_ACTIVATED , kernel_LARGE_WORK_INVALID_CHAIN }

enum	kernel_ValidationMode { kernel_VALIDATION_STATE_VALID = 0 , kernel_VALIDATION_STATE_INVALID , kernel_VALIDATION_STATE_ERROR }

enum	kernel_BlockValidationResult { kernel_BLOCK_RESULT_UNSET = 0 , kernel_BLOCK_CONSENSUS , kernel_BLOCK_CACHED_INVALID , kernel_BLOCK_INVALID_HEADER , kernel_BLOCK_MUTATED , kernel_BLOCK_MISSING_PREV , kernel_BLOCK_INVALID_PREV , kernel_BLOCK_TIME_FUTURE , kernel_BLOCK_HEADER_LOW_WORK }

enum	kernel_LogCategory { kernel_LOG_ALL = 0 , kernel_LOG_BENCH , kernel_LOG_BLOCKSTORAGE , kernel_LOG_COINDB , kernel_LOG_LEVELDB , kernel_LOG_MEMPOOL , kernel_LOG_PRUNE , kernel_LOG_RAND , kernel_LOG_REINDEX , kernel_LOG_VALIDATION , kernel_LOG_KERNEL }

enum	kernel_LogLevel { kernel_LOG_TRACE = 0 , kernel_LOG_DEBUG , kernel_LOG_INFO }

enum	kernel_ScriptVerifyStatus { kernel_SCRIPT_VERIFY_OK = 0 , kernel_SCRIPT_VERIFY_ERROR_TX_INPUT_INDEX , kernel_SCRIPT_VERIFY_ERROR_INVALID_FLAGS , kernel_SCRIPT_VERIFY_ERROR_INVALID_FLAGS_COMBINATION , kernel_SCRIPT_VERIFY_ERROR_SPENT_OUTPUTS_REQUIRED , kernel_SCRIPT_VERIFY_ERROR_SPENT_OUTPUTS_MISMATCH }

enum	kernel_ScriptFlags { kernel_SCRIPT_FLAGS_VERIFY_NONE = 0 , kernel_SCRIPT_FLAGS_VERIFY_P2SH = (1U << 0) , kernel_SCRIPT_FLAGS_VERIFY_DERSIG = (1U << 2) , kernel_SCRIPT_FLAGS_VERIFY_NULLDUMMY = (1U << 4) , kernel_SCRIPT_FLAGS_VERIFY_CHECKLOCKTIMEVERIFY = (1U << 9) , kernel_SCRIPT_FLAGS_VERIFY_CHECKSEQUENCEVERIFY = (1U << 10) , kernel_SCRIPT_FLAGS_VERIFY_WITNESS = (1U << 11) , kernel_SCRIPT_FLAGS_VERIFY_TAPROOT = (1U << 17) , kernel_SCRIPT_FLAGS_VERIFY_ALL }

enum	kernel_ChainType { kernel_CHAIN_TYPE_MAINNET = 0 , kernel_CHAIN_TYPE_TESTNET , kernel_CHAIN_TYPE_TESTNET_4 , kernel_CHAIN_TYPE_SIGNET , kernel_CHAIN_TYPE_REGTEST }

Functions
Transaction
Functions for working with transactions.
BITCOINKERNEL_API kernel_Transaction *	kernel_transaction_create (const unsigned char *raw_transaction, size_t raw_transaction_len)
	Create a new transaction from the serialized data.

BITCOINKERNEL_API void	kernel_transaction_destroy (kernel_Transaction *transaction)

ScriptPubkey
Functions for working with script pubkeys.
BITCOINKERNEL_API kernel_ScriptPubkey *	kernel_script_pubkey_create (const unsigned char *script_pubkey, size_t script_pubkey_len)
	Create a script pubkey from serialized data.

BITCOINKERNEL_API kernel_ByteArray *	kernel_script_pubkey_copy_data (const kernel_ScriptPubkey *script_pubkey)
	Copies the script pubkey data into the returned byte array.

BITCOINKERNEL_API void	kernel_script_pubkey_destroy (kernel_ScriptPubkey *script_pubkey)

TransactionOutput
Functions for working with transaction outputs.
BITCOINKERNEL_API kernel_TransactionOutput *	kernel_transaction_output_create (const kernel_ScriptPubkey *script_pubkey, int64_t amount)
	Create a transaction output from a script pubkey and an amount.

BITCOINKERNEL_API kernel_ScriptPubkey *	kernel_transaction_output_copy_script_pubkey (kernel_TransactionOutput *transaction_output)
	Copies the script pubkey of an output in the returned script pubkey opaque object.

BITCOINKERNEL_API int64_t	kernel_transaction_output_get_amount (kernel_TransactionOutput *transaction_output)
	Gets the amount associated with this transaction output.

BITCOINKERNEL_API void	kernel_transaction_output_destroy (kernel_TransactionOutput *transaction_output)

Script
Functions for working with scripts.
BITCOINKERNEL_API bool	kernel_verify_script (const kernel_ScriptPubkey script_pubkey, int64_t amount, const kernel_Transaction tx_to, const kernel_TransactionOutput *spent_outputs, size_t spent_outputs_len, unsigned int input_index, unsigned int flags, kernel_ScriptVerifyStatus status) 3)
	Verify if the input at input_index of tx_to spends the script pubkey under the constraints specified by flags. If the `kernel_SCRIPT_FLAGS_VERIFY_WITNESS` flag is set in the flags bitfield, the amount parameter is used. If the taproot flag is set, the spent outputs parameter is used to validate taproot transactions.

Logging
Logging-related functions.
BITCOINKERNEL_API void	kernel_logging_disable ()
	This disables the global internal logger. No log messages will be buffered internally anymore once this is called and the buffer is cleared. This function should only be called once and is not thread or re-entry safe. Log messages will be buffered until this function is called, or a logging connection is created.

BITCOINKERNEL_API void	kernel_logging_set_level_category (const kernel_LogCategory category, kernel_LogLevel level)
	Set the log level of the global internal logger. This does not enable the selected categories. Use kernel_logging_enable_category to start logging from a specific, or all categories. This function is not thread safe. Mutiple calls from different threads are allowed but must be synchronized. This changes a global setting and will override settings for all existing kernel_LoggingConnection instances.

BITCOINKERNEL_API void	kernel_logging_enable_category (const kernel_LogCategory category)
	Enable a specific log category for the global internal logger. This function is not thread safe. Mutiple calls from different threads are allowed but must be synchronized. This changes a global setting and will override settings for all existing kernel_LoggingConnection instances.

BITCOINKERNEL_API void	kernel_logging_disable_category (const kernel_LogCategory category)
	Disable a specific log category for the global internal logger. This function is not thread safe. Mutiple calls from different threads are allowed but must be synchronized. This changes a global setting and will override settings for all existing kernel_LoggingConnection instances.

BITCOINKERNEL_API kernel_LoggingConnection *	kernel_logging_connection_create (kernel_LogCallback callback, const void *user_data, const kernel_LoggingOptions options)
	Start logging messages through the provided callback. Log messages produced before this function is first called are buffered and on calling this function are logged immediately.

BITCOINKERNEL_API void	kernel_logging_connection_destroy (kernel_LoggingConnection *logging_connection)

ChainParameters
Functions for working with chain parameters.
BITCOINKERNEL_API kernel_ChainParameters *	kernel_chain_parameters_create (const kernel_ChainType chain_type)
	Creates a chain parameters struct with default parameters based on the passed in chain type.

BITCOINKERNEL_API void	kernel_chain_parameters_destroy (kernel_ChainParameters *chain_parameters)

ContextOptions
Functions for working with context options.
BITCOINKERNEL_API kernel_ContextOptions *	kernel_context_options_create ()

BITCOINKERNEL_API void	kernel_context_options_set_chainparams (kernel_ContextOptions context_options, const kernel_ChainParameters chain_parameters) 2)
	Sets the chain params for the context options. The context created with the options will be configured for these chain parameters.

BITCOINKERNEL_API void	kernel_context_options_set_notifications (kernel_ContextOptions *context_options, kernel_NotificationInterfaceCallbacks notifications)
	Set the kernel notifications for the context options. The context created with the options will be configured with these notifications.

BITCOINKERNEL_API void	kernel_context_options_set_validation_interface (kernel_ContextOptions *context_options, kernel_ValidationInterfaceCallbacks validation_interface_callbacks)
	Set the validation interface callbacks for the context options. The context created with the options will be configured for these validation interface callbacks. The callbacks will then be triggered from validation events issued by the chainstate manager created from the same context.

BITCOINKERNEL_API void	kernel_context_options_destroy (kernel_ContextOptions *context_options)

Context
Functions for working with contexts.
BITCOINKERNEL_API kernel_Context *	kernel_context_create (const kernel_ContextOptions *context_options)
	Create a new kernel context. If the options have not been previously set, their corresponding fields will be initialized to default values; the context will assume mainnet chain parameters and won't attempt to call the kernel notification callbacks.

BITCOINKERNEL_API bool	kernel_context_interrupt (kernel_Context *context)
	Interrupt can be used to halt long-running validation functions like when reindexing, importing or processing blocks.

BITCOINKERNEL_API void	kernel_context_destroy (kernel_Context *context)

ChainstateManagerOptions
Functions for working with chainstate manager options.
BITCOINKERNEL_API kernel_ChainstateManagerOptions *	kernel_chainstate_manager_options_create (const kernel_Context context, const char data_directory, size_t data_directory_len, const char *blocks_directory, size_t blocks_directory_len) 2)
	Create options for the chainstate manager.

BITCOINKERNEL_API void	kernel_chainstate_manager_options_set_worker_threads_num (kernel_ChainstateManagerOptions *chainstate_manager_options, int worker_threads)
	Set the number of available worker threads used during validation.

BITCOINKERNEL_API bool	kernel_chainstate_manager_options_set_wipe_dbs (kernel_ChainstateManagerOptions *chainstate_manager_options, bool wipe_block_tree_db, bool wipe_chainstate_db)
	Sets wipe db in the options. In combination with calling kernel_chainstate_manager_import_blocks this triggers either a full reindex, or a reindex of just the chainstate database.

BITCOINKERNEL_API void	kernel_chainstate_manager_options_set_block_tree_db_in_memory (kernel_ChainstateManagerOptions *chainstate_manager_options, bool block_tree_db_in_memory)
	Sets block tree db in memory in the options.

BITCOINKERNEL_API void	kernel_chainstate_manager_options_set_chainstate_db_in_memory (kernel_ChainstateManagerOptions *chainstate_manager_options, bool chainstate_db_in_memory)
	Sets chainstate db in memory in the options.

BITCOINKERNEL_API void	kernel_chainstate_manager_options_destroy (kernel_ChainstateManagerOptions *chainstate_manager_options)

ChainstateManager
Functions for chainstate management.
BITCOINKERNEL_API kernel_ChainstateManager *	kernel_chainstate_manager_create (const kernel_Context context, const kernel_ChainstateManagerOptions chainstate_manager_options) 2)
	Create a chainstate manager. This is the main object for many validation tasks as well as for retrieving data from the chain and interacting with its chainstate and indexes. It is only valid for as long as the passed in context also remains in memory.

BITCOINKERNEL_API bool	kernel_chainstate_manager_import_blocks (const kernel_Context context, kernel_ChainstateManager chainstate_manager, const char *block_file_paths, size_t block_file_paths_lens, size_t block_file_paths_len) 2)
	May be called once the kernel_ChainstateManager is instantiated. Triggers the start of a reindex if the option was previously set for the chainstate and block manager. Can also import an array of existing block files selected by the user.

BITCOINKERNEL_API bool	kernel_chainstate_manager_process_block (const kernel_Context context, kernel_ChainstateManager chainstate_manager, kernel_Block block, bool new_block) 2
	Process and validate the passed in block with the chainstate manager. More detailed validation information in case of a failure can also be retrieved through a registered validation interface. If the block fails to validate the `block_checked` callback's 'BlockValidationState' will contain details.

BITCOINKERNEL_API bool BITCOINKERNEL_API void	kernel_chainstate_manager_destroy (kernel_ChainstateManager chainstate_manager, const kernel_Context context)

Block
Functions for working with blocks.
BITCOINKERNEL_API kernel_Block *	kernel_block_read (const kernel_Context context, kernel_ChainstateManager chainstate_manager, const kernel_BlockIndex *block_index) 2
	Reads the block the passed in block index points to from disk and returns it.

BITCOINKERNEL_API kernel_Block BITCOINKERNEL_API kernel_Block *	kernel_block_create (const unsigned char *raw_block, size_t raw_block_len)
	Parse a serialized raw block into a new block object.

BITCOINKERNEL_API kernel_BlockHash *	kernel_block_get_hash (kernel_Block *block)
	Calculate and return the hash of a block.

BITCOINKERNEL_API kernel_BlockHash *	kernel_block_pointer_get_hash (const kernel_BlockPointer *block)
	Calculate and return the hash of a block.

BITCOINKERNEL_API kernel_ByteArray *	kernel_block_copy_data (kernel_Block *block)
	Copies block data into the returned byte array.

BITCOINKERNEL_API kernel_ByteArray *	kernel_block_pointer_copy_data (const kernel_BlockPointer *block)
	Copies block data into the returned byte array.

BITCOINKERNEL_API void	kernel_block_destroy (kernel_Block *block)

ByteArray
Functions for working with byte arrays.
BITCOINKERNEL_API void	kernel_byte_array_destroy (kernel_ByteArray *byte_array)

BlockValidationState
Functions for working with block validation states.
BITCOINKERNEL_API kernel_ValidationMode	kernel_block_validation_state_get_validation_mode (const kernel_BlockValidationState *block_validation_state)

BITCOINKERNEL_API kernel_BlockValidationResult	kernel_block_validation_state_get_block_validation_result (const kernel_BlockValidationState *block_validation_state)

BlockIndex
Functions for working with block indexes.
BITCOINKERNEL_API kernel_BlockIndex *	kernel_block_index_get_tip (const kernel_Context context, kernel_ChainstateManager chainstate_manager) 2)
	Get the block index entry of the current chain tip. Once returned, there is no guarantee that it remains in the active chain.

BITCOINKERNEL_API kernel_BlockIndex *	kernel_block_index_get_genesis (const kernel_Context context, kernel_ChainstateManager chainstate_manager) 2)
	Get the block index entry of the genesis block.

BITCOINKERNEL_API kernel_BlockIndex *	kernel_block_index_get_by_hash (const kernel_Context context, kernel_ChainstateManager chainstate_manager, kernel_BlockHash *block_hash) 2
	Retrieve a block index by its block hash.

BITCOINKERNEL_API kernel_BlockIndex BITCOINKERNEL_API kernel_BlockIndex *	kernel_block_index_get_by_height (const kernel_Context context, kernel_ChainstateManager chainstate_manager, int block_height) 2)
	Retrieve a block index by its height in the currently active chain. Once retrieved there is no guarantee that it remains in the active chain.

BITCOINKERNEL_API kernel_BlockIndex *	kernel_block_index_get_next (const kernel_Context context, kernel_ChainstateManager chainstate_manager, const kernel_BlockIndex *block_index) 2
	Return the next block index in the currently active chain, or null if the current block index is the tip, or is not in the currently active chain.

BITCOINKERNEL_API kernel_BlockIndex BITCOINKERNEL_API kernel_BlockIndex *	kernel_block_index_get_previous (const kernel_BlockIndex *block_index)
	Returns the previous block index in the chain, or null if the current block index entry is the genesis block.

BITCOINKERNEL_API int32_t	kernel_block_index_get_height (const kernel_BlockIndex *block_index)
	Return the height of a certain block index.

BITCOINKERNEL_API void	kernel_block_index_destroy (kernel_BlockIndex *block_index)
	Destroy the block index.

BlockUndo
Functions for working with block undo data.
BITCOINKERNEL_API kernel_BlockUndo *	kernel_block_undo_read (const kernel_Context context, kernel_ChainstateManager chainstate_manager, const kernel_BlockIndex *block_index) 2
	Reads the block undo data the passed in block index points to from disk and returns it.

BITCOINKERNEL_API kernel_BlockUndo BITCOINKERNEL_API uint64_t	kernel_block_undo_size (const kernel_BlockUndo *block_undo)
	Returns the number of transactions whose undo data is contained in block undo.

BITCOINKERNEL_API uint64_t	kernel_block_undo_get_transaction_undo_size (const kernel_BlockUndo *block_undo, uint64_t transaction_undo_index)
	Returns the number of previous transaction outputs contained in the transaction undo data.

BITCOINKERNEL_API uint32_t	kernel_block_undo_get_transaction_output_height_by_index (const kernel_BlockUndo *block_undo, uint64_t transaction_undo_index, uint64_t output_index)
	Returns the block height of the block that contains the output at output_index within the transaction undo data at the provided index of the block undo data.

BITCOINKERNEL_API kernel_TransactionOutput *	kernel_block_undo_copy_transaction_output_by_index (const kernel_BlockUndo *block_undo, uint64_t transaction_undo_index, uint64_t output_index)
	Return a transaction output contained in the transaction undo data of a block undo data at a certain index. This value is copied from the underlying data and thus owned entirely by the user.

BITCOINKERNEL_API void	kernel_block_undo_destroy (kernel_BlockUndo *block_undo)

BlockHash
Functions for working with block hashes.
BITCOINKERNEL_API kernel_BlockHash *	kernel_block_index_get_block_hash (const kernel_BlockIndex *block_index)
	Return the block hash associated with a block index.

BITCOINKERNEL_API void	kernel_block_hash_destroy (kernel_BlockHash *block_hash)

Macro Definition Documentation

◆ BITCOINKERNEL_API

#define BITCOINKERNEL_API

◆ BITCOINKERNEL_ARG_NONNULL

#define BITCOINKERNEL_ARG_NONNULL ( ... )

◆ BITCOINKERNEL_WARN_UNUSED_RESULT

#define BITCOINKERNEL_WARN_UNUSED_RESULT

Typedef Documentation

◆ kernel_Block

typedef struct kernel_Block kernel_Block

Opaque data structure for holding a block.

◆ kernel_BlockIndex

typedef struct kernel_BlockIndex kernel_BlockIndex

Opaque data structure for holding a block index pointer.

This is a pointer to an element in the block index currently in memory of the chainstate manager. It is valid for the lifetime of the chainstate manager it was retrieved from.

◆ kernel_BlockPointer

typedef struct kernel_BlockPointer kernel_BlockPointer

Opaque data structure for holding a non-owned block. This is typically a block available to the user through one of the validation callbacks.

◆ kernel_BlockUndo

typedef struct kernel_BlockUndo kernel_BlockUndo

Opaque data structure for holding a block undo struct.

It holds all the previous outputs consumed by all transactions in a specific block. Internally it holds a nested vector. The top level vector has an entry for each transaction in a block (in order of the actual transactions of the block and minus the coinbase transaction). Each entry is in turn a vector of all the previous outputs of a transaction (in order of their corresponding inputs).

◆ kernel_BlockValidationState

typedef struct kernel_BlockValidationState kernel_BlockValidationState

Opaque data structure for holding the state of a block during validation.

Contains information indicating whether validation was successful, and if not which step during block validation failed.

◆ kernel_ChainParameters

typedef struct kernel_ChainParameters kernel_ChainParameters

Opaque data structure for holding the chain parameters.

These are eventually placed into a kernel context through the kernel context options. The parameters describe the properties of a chain, and may be instantiated for either mainnet, testnet, signet, or regtest.

◆ kernel_ChainstateManager

typedef struct kernel_ChainstateManager kernel_ChainstateManager

Opaque data structure for holding a chainstate manager.

The chainstate manager is the central object for doing validation tasks as well as retrieving data from the chain. Internally it is a complex data structure with diverse functionality.

The chainstate manager is only valid for as long as the context with which it was created remains in memory.

Its functionality will be more and more exposed in the future.

◆ kernel_ChainstateManagerOptions

typedef struct kernel_ChainstateManagerOptions kernel_ChainstateManagerOptions

Opaque data structure for holding options for creating a new chainstate manager.

The chainstate manager options are used to set some parameters for the chainstate manager. For now it just holds default options.

◆ kernel_Context

typedef struct kernel_Context kernel_Context

Opaque data structure for holding a kernel context.

The kernel context is used to initialize internal state and hold the chain parameters and callbacks for handling error and validation events. Once other validation objects are instantiated from it, the context needs to be kept in memory for the duration of their lifetimes.

The processing of validation events is done through an internal task runner owned by the context. It passes events through the registered validation interface callbacks.

A constructed context can be safely used from multiple threads.

◆ kernel_ContextOptions

typedef struct kernel_ContextOptions kernel_ContextOptions

Opaque data structure for holding options for creating a new kernel context.

Once a kernel context has been created from these options, they may be destroyed. The options hold the notification callbacks as well as the selected chain type until they are passed to the context. If no options are configured, the context will be instantiated with no callbacks and for mainnet. Their content and scope can be expanded over time.

◆ kernel_LogCallback

typedef void(* kernel_LogCallback) (void *user_data, const char *message, size_t message_len)

Callback function types Function signature for the global logging callback. All bitcoin kernel internal logs will pass through this callback.

◆ kernel_LoggingConnection

typedef struct kernel_LoggingConnection kernel_LoggingConnection

Opaque data structure for holding a logging connection.

The logging connection can be used to manually stop logging.

Messages that were logged before a connection is created are buffered in a 1MB buffer. Logging can alternatively be permanently disabled by calling kernel_logging_disable. Functions changing the logging settings are global (and not thread safe) and change the settings for all existing kernel_LoggingConnection instances.

◆ kernel_NotifyBlockTip

typedef void(* kernel_NotifyBlockTip) (void *user_data, kernel_SynchronizationState state, const kernel_BlockIndex *index, double verification_progress)

Function signatures for the kernel notifications.

◆ kernel_NotifyFatalError

typedef void(* kernel_NotifyFatalError) (void *user_data, const char *message, size_t message_len)

◆ kernel_NotifyFlushError

typedef void(* kernel_NotifyFlushError) (void *user_data, const char *message, size_t message_len)

◆ kernel_NotifyHeaderTip

typedef void(* kernel_NotifyHeaderTip) (void *user_data, kernel_SynchronizationState state, int64_t height, int64_t timestamp, bool presync)

◆ kernel_NotifyProgress

typedef void(* kernel_NotifyProgress) (void *user_data, const char *title, size_t title_len, int progress_percent, bool resume_possible)

◆ kernel_NotifyWarningSet

typedef void(* kernel_NotifyWarningSet) (void *user_data, kernel_Warning warning, const char *message, size_t message_len)

◆ kernel_NotifyWarningUnset

typedef void(* kernel_NotifyWarningUnset) (void *user_data, kernel_Warning warning)

◆ kernel_ScriptPubkey

typedef struct kernel_ScriptPubkey kernel_ScriptPubkey

Opaque data structure for holding a script pubkey.

◆ kernel_Transaction

typedef struct kernel_Transaction kernel_Transaction

Opaque data structure for holding a transaction.

◆ kernel_TransactionOutput

typedef struct kernel_TransactionOutput kernel_TransactionOutput

Opaque data structure for holding a transaction output.

◆ kernel_ValidationInterfaceBlockChecked

typedef void(* kernel_ValidationInterfaceBlockChecked) (void *user_data, const kernel_BlockPointer *block, const kernel_BlockValidationState *state)

Function signatures for the validation interface.

Enumeration Type Documentation

◆ kernel_BlockValidationResult

enum kernel_BlockValidationResult

A granular "reason" why a block was invalid.

Enumerator
kernel_BLOCK_RESULT_UNSET	initial value. Block has not yet been rejected
kernel_BLOCK_CONSENSUS	invalid by consensus rules (excluding any below reasons)
kernel_BLOCK_CACHED_INVALID	this block was cached as being invalid and we didn't store the reason why
kernel_BLOCK_INVALID_HEADER	invalid proof of work or time too old
kernel_BLOCK_MUTATED	the block's data didn't match the data committed to by the PoW
kernel_BLOCK_MISSING_PREV	We don't have the previous block the checked one is built on.
kernel_BLOCK_INVALID_PREV	A block this one builds on is invalid.
kernel_BLOCK_TIME_FUTURE	block timestamp was > 2 hours in the future (or our clock is bad)
kernel_BLOCK_HEADER_LOW_WORK	the block header may be on a too-little-work chain

◆ kernel_ChainType

enum kernel_ChainType

Chain type used for creating chain params.

Enumerator
kernel_CHAIN_TYPE_MAINNET
kernel_CHAIN_TYPE_TESTNET
kernel_CHAIN_TYPE_TESTNET_4
kernel_CHAIN_TYPE_SIGNET
kernel_CHAIN_TYPE_REGTEST

◆ kernel_LogCategory

enum kernel_LogCategory

A collection of logging categories that may be encountered by kernel code.

Enumerator
kernel_LOG_ALL
kernel_LOG_BENCH
kernel_LOG_BLOCKSTORAGE
kernel_LOG_COINDB
kernel_LOG_LEVELDB
kernel_LOG_MEMPOOL
kernel_LOG_PRUNE
kernel_LOG_RAND
kernel_LOG_REINDEX
kernel_LOG_VALIDATION
kernel_LOG_KERNEL

◆ kernel_LogLevel

enum kernel_LogLevel

The level at which logs should be produced.

Enumerator
kernel_LOG_TRACE
kernel_LOG_DEBUG
kernel_LOG_INFO

◆ kernel_ScriptFlags

enum kernel_ScriptFlags

Script verification flags that may be composed with each other.

Enumerator
kernel_SCRIPT_FLAGS_VERIFY_NONE
kernel_SCRIPT_FLAGS_VERIFY_P2SH	evaluate P2SH (BIP16) subscripts
kernel_SCRIPT_FLAGS_VERIFY_DERSIG	enforce strict DER (BIP66) compliance
kernel_SCRIPT_FLAGS_VERIFY_NULLDUMMY	enforce NULLDUMMY (BIP147)
kernel_SCRIPT_FLAGS_VERIFY_CHECKLOCKTIMEVERIFY	enable CHECKLOCKTIMEVERIFY (BIP65)
kernel_SCRIPT_FLAGS_VERIFY_CHECKSEQUENCEVERIFY	enable CHECKSEQUENCEVERIFY (BIP112)
kernel_SCRIPT_FLAGS_VERIFY_WITNESS	enable WITNESS (BIP141)
kernel_SCRIPT_FLAGS_VERIFY_TAPROOT	enable TAPROOT (BIPs 341 & 342)
kernel_SCRIPT_FLAGS_VERIFY_ALL

◆ kernel_ScriptVerifyStatus

enum kernel_ScriptVerifyStatus

A collection of status codes that may be issued by the script verify function.

Enumerator
kernel_SCRIPT_VERIFY_OK
kernel_SCRIPT_VERIFY_ERROR_TX_INPUT_INDEX	The provided input index is out of range of the actual number of inputs of the transaction.
kernel_SCRIPT_VERIFY_ERROR_INVALID_FLAGS	The provided bitfield for the flags was invalid.
kernel_SCRIPT_VERIFY_ERROR_INVALID_FLAGS_COMBINATION	The flags very combined in an invalid way.
kernel_SCRIPT_VERIFY_ERROR_SPENT_OUTPUTS_REQUIRED	The taproot flag was set, so valid spent_outputs have to be provided.
kernel_SCRIPT_VERIFY_ERROR_SPENT_OUTPUTS_MISMATCH	The number of spent outputs does not match the number of inputs of the tx.

◆ kernel_SynchronizationState

enum kernel_SynchronizationState

Current sync state passed to tip changed callbacks.

Enumerator
kernel_INIT_REINDEX
kernel_INIT_DOWNLOAD
kernel_POST_INIT

◆ kernel_ValidationMode

enum kernel_ValidationMode

Whether a validated data structure is valid, invalid, or an error was encountered during processing.

Enumerator
kernel_VALIDATION_STATE_VALID
kernel_VALIDATION_STATE_INVALID
kernel_VALIDATION_STATE_ERROR

◆ kernel_Warning

enum kernel_Warning

Possible warning types issued by validation.

Enumerator
kernel_UNKNOWN_NEW_RULES_ACTIVATED
kernel_LARGE_WORK_INVALID_CHAIN

Function Documentation

◆ kernel_block_copy_data()

BITCOINKERNEL_API kernel_ByteArray * kernel_block_copy_data ( kernel_Block * block )

Copies block data into the returned byte array.

Parameters

[in] block Non-null.

Returns: Allocated byte array holding the block data.

◆ kernel_block_create()

BITCOINKERNEL_API kernel_Block BITCOINKERNEL_API kernel_Block * kernel_block_create	(	const unsigned char *	raw_block,
		size_t	raw_block_len
	)

Parse a serialized raw block into a new block object.

Parameters

[in]	raw_block	Non-null, serialized block.
[in]	raw_block_len	Length of the serialized block.

Returns: The allocated block, or null on error.

◆ kernel_block_destroy()

BITCOINKERNEL_API void kernel_block_destroy ( kernel_Block * block )

Destroy the block.

◆ kernel_block_get_hash()

BITCOINKERNEL_API kernel_BlockHash * kernel_block_get_hash ( kernel_Block * block )

Calculate and return the hash of a block.

Parameters

[in] block Non-null.

Returns: The block hash.

◆ kernel_block_hash_destroy()

BITCOINKERNEL_API void kernel_block_hash_destroy ( kernel_BlockHash * block_hash )

Destroy the block hash.

◆ kernel_block_index_destroy()

BITCOINKERNEL_API void kernel_block_index_destroy ( kernel_BlockIndex * block_index )

Destroy the block index.

◆ kernel_block_index_get_block_hash()

BITCOINKERNEL_API kernel_BlockHash * kernel_block_index_get_block_hash ( const kernel_BlockIndex * block_index )

Return the block hash associated with a block index.

Parameters

[in] block_index Non-null.

Returns: The block hash, or null if the block index has no associated hash.

◆ kernel_block_index_get_by_hash()

BITCOINKERNEL_API kernel_BlockIndex * kernel_block_index_get_by_hash	(	const kernel_Context *	context,
		kernel_ChainstateManager *	chainstate_manager,
		kernel_BlockHash *	block_hash
	)

Retrieve a block index by its block hash.

Parameters

[in]	context	Non-null.
[in]	chainstate_manager	Non-null.
[in]	block_hash	Non-null.

Returns: The block index of the block with the passed in hash, or null if the block hash is not found.

◆ kernel_block_index_get_by_height()

BITCOINKERNEL_API kernel_BlockIndex BITCOINKERNEL_API kernel_BlockIndex * kernel_block_index_get_by_height	(	const kernel_Context *	context,
		kernel_ChainstateManager *	chainstate_manager,
		int	block_height
	)

Retrieve a block index by its height in the currently active chain. Once retrieved there is no guarantee that it remains in the active chain.

Parameters

[in]	context	Non-null.
[in]	chainstate_manager	Non-null.
[in]	block_height	Height in the chain of the to be retrieved block index.

Returns: The block index at a certain height in the currently active chain, or null if the height is out of bounds.

◆ kernel_block_index_get_genesis()

BITCOINKERNEL_API kernel_BlockIndex * kernel_block_index_get_genesis	(	const kernel_Context *	context,
		kernel_ChainstateManager *	chainstate_manager
	)

Get the block index entry of the genesis block.

Parameters

[in]	context	Non-null.
[in]	chainstate_manager	Non-null.

Returns: The block index of the genesis block, or null on error.

◆ kernel_block_index_get_height()

BITCOINKERNEL_API int32_t kernel_block_index_get_height ( const kernel_BlockIndex * block_index )

Return the height of a certain block index.

Parameters

[in] block_index Non-null.

Returns: The block height.

◆ kernel_block_index_get_next()

BITCOINKERNEL_API kernel_BlockIndex * kernel_block_index_get_next	(	const kernel_Context *	context,
		kernel_ChainstateManager *	chainstate_manager,
		const kernel_BlockIndex *	block_index
	)

Return the next block index in the currently active chain, or null if the current block index is the tip, or is not in the currently active chain.

Parameters

[in]	context	Non-null.
[in]	block_index	Non-null.
[in]	chainstate_manager	Non-null.

Returns: The next block index in the currently active chain, or null if the block_index is the chain tip.

◆ kernel_block_index_get_previous()

BITCOINKERNEL_API kernel_BlockIndex BITCOINKERNEL_API kernel_BlockIndex * kernel_block_index_get_previous ( const kernel_BlockIndex * block_index )

Returns the previous block index in the chain, or null if the current block index entry is the genesis block.

Parameters

[in] block_index Non-null.

Returns: The previous block index, or null on error or if the current block index is the genesis block.

◆ kernel_block_index_get_tip()

BITCOINKERNEL_API kernel_BlockIndex * kernel_block_index_get_tip	(	const kernel_Context *	context,
		kernel_ChainstateManager *	chainstate_manager
	)

Get the block index entry of the current chain tip. Once returned, there is no guarantee that it remains in the active chain.

Parameters

[in]	context	Non-null.
[in]	chainstate_manager	Non-null.

Returns: The block index of the current tip, or null if the chain is empty.

◆ kernel_block_pointer_copy_data()

BITCOINKERNEL_API kernel_ByteArray * kernel_block_pointer_copy_data ( const kernel_BlockPointer * block )

Copies block data into the returned byte array.

Parameters

[in] block Non-null.

Returns: Allocated byte array holding the block data.

◆ kernel_block_pointer_get_hash()

BITCOINKERNEL_API kernel_BlockHash * kernel_block_pointer_get_hash ( const kernel_BlockPointer * block )

Calculate and return the hash of a block.

Parameters

[in] block Non-null.

Returns: The block hash.

◆ kernel_block_read()

BITCOINKERNEL_API kernel_Block * kernel_block_read	(	const kernel_Context *	context,
		kernel_ChainstateManager *	chainstate_manager,
		const kernel_BlockIndex *	block_index
	)

Reads the block the passed in block index points to from disk and returns it.

Parameters

[in]	context	Non-null.
[in]	chainstate_manager	Non-null.
[in]	block_index	Non-null.

Returns: The read out block, or null on error.

◆ kernel_block_undo_copy_transaction_output_by_index()

BITCOINKERNEL_API kernel_TransactionOutput * kernel_block_undo_copy_transaction_output_by_index	(	const kernel_BlockUndo *	block_undo,
		uint64_t	transaction_undo_index,
		uint64_t	output_index
	)

Return a transaction output contained in the transaction undo data of a block undo data at a certain index. This value is copied from the underlying data and thus owned entirely by the user.

Parameters

[in]	block_undo	Non-null.
[in]	transaction_undo_index	The index of the transaction undo data within the block undo data.
[in]	output_index	The index of the to be retrieved transaction output within the transaction undo data.

Returns: A transaction output pointer, or null if provided indices are out of bounds.

◆ kernel_block_undo_destroy()

BITCOINKERNEL_API void kernel_block_undo_destroy ( kernel_BlockUndo * block_undo )

Destroy the block undo data.

◆ kernel_block_undo_get_transaction_output_height_by_index()

BITCOINKERNEL_API uint32_t kernel_block_undo_get_transaction_output_height_by_index	(	const kernel_BlockUndo *	block_undo,
		uint64_t	transaction_undo_index,
		uint64_t	output_index
	)

Returns the block height of the block that contains the output at output_index within the transaction undo data at the provided index of the block undo data.

Parameters

[in]	block_undo	Non-null.
[in]	transaction_undo_index	The index of the transaction undo data within the block undo data.
[in]	output_index	The index of the targeted transaction output within the transaction undo data.

Returns: The block height of the output, or 0 if provided indices are out of bounds.

◆ kernel_block_undo_get_transaction_undo_size()

BITCOINKERNEL_API uint64_t kernel_block_undo_get_transaction_undo_size	(	const kernel_BlockUndo *	block_undo,
		uint64_t	transaction_undo_index
	)

Returns the number of previous transaction outputs contained in the transaction undo data.

Parameters

[in]	block_undo	Non-null, the block undo data from which tx_undo was retrieved from.
[in]	transaction_undo_index	The index of the transaction undo data within the block undo data.

Returns: The number of previous transaction outputs in the transaction, or 0 if the provided index is out of bounds.

◆ kernel_block_undo_read()

BITCOINKERNEL_API kernel_BlockUndo * kernel_block_undo_read	(	const kernel_Context *	context,
		kernel_ChainstateManager *	chainstate_manager,
		const kernel_BlockIndex *	block_index
	)

Reads the block undo data the passed in block index points to from disk and returns it.

Parameters

[in]	context	Non-null.
[in]	chainstate_manager	Non-null.
[in]	block_index	Non-null.

Returns: The read out block undo data, or null on error.

◆ kernel_block_undo_size()

BITCOINKERNEL_API kernel_BlockUndo BITCOINKERNEL_API uint64_t kernel_block_undo_size ( const kernel_BlockUndo * block_undo )

Returns the number of transactions whose undo data is contained in block undo.

Parameters

[in] block_undo Non-null.

Returns: The number of transaction undo data in the block undo.

◆ kernel_block_validation_state_get_block_validation_result()

BITCOINKERNEL_API kernel_BlockValidationResult kernel_block_validation_state_get_block_validation_result ( const kernel_BlockValidationState * block_validation_state )

Returns the validation result from an opaque block validation state pointer.

◆ kernel_block_validation_state_get_validation_mode()

BITCOINKERNEL_API kernel_ValidationMode kernel_block_validation_state_get_validation_mode ( const kernel_BlockValidationState * block_validation_state )

Returns the validation mode from an opaque block validation state pointer.

◆ kernel_byte_array_destroy()

BITCOINKERNEL_API void kernel_byte_array_destroy ( kernel_ByteArray * byte_array )

A helper function for destroying an existing byte array.

◆ kernel_chain_parameters_create()

BITCOINKERNEL_API kernel_ChainParameters * kernel_chain_parameters_create ( const kernel_ChainType chain_type )

Creates a chain parameters struct with default parameters based on the passed in chain type.

Parameters

[in] chain_type Controls the chain parameters type created.

Returns: An allocated chain parameters opaque struct.

◆ kernel_chain_parameters_destroy()

BITCOINKERNEL_API void kernel_chain_parameters_destroy ( kernel_ChainParameters * chain_parameters )

Destroy the chain parameters.

◆ kernel_chainstate_manager_create()

BITCOINKERNEL_API kernel_ChainstateManager * kernel_chainstate_manager_create	(	const kernel_Context *	context,
		const kernel_ChainstateManagerOptions *	chainstate_manager_options
	)

Create a chainstate manager. This is the main object for many validation tasks as well as for retrieving data from the chain and interacting with its chainstate and indexes. It is only valid for as long as the passed in context also remains in memory.

Parameters

[in]	chainstate_manager_options	Non-null, created by kernel_chainstate_manager_options_create.
[in]	context	Non-null, the created chainstate manager will associate with this kernel context for the duration of its lifetime. The same context needs to be used for later interactions with the chainstate manager.

Returns: The allocated chainstate manager, or null on error.

◆ kernel_chainstate_manager_destroy()

BITCOINKERNEL_API bool BITCOINKERNEL_API void kernel_chainstate_manager_destroy	(	kernel_ChainstateManager *	chainstate_manager,
		const kernel_Context *	context
	)

Destroy the chainstate manager.

◆ kernel_chainstate_manager_import_blocks()

BITCOINKERNEL_API bool kernel_chainstate_manager_import_blocks	(	const kernel_Context *	context,
		kernel_ChainstateManager *	chainstate_manager,
		const char **	block_file_paths,
		size_t *	block_file_paths_lens,
		size_t	block_file_paths_len
	)

May be called once the kernel_ChainstateManager is instantiated. Triggers the start of a reindex if the option was previously set for the chainstate and block manager. Can also import an array of existing block files selected by the user.

Parameters

[in]	context	Non-null.
[in]	chainstate_manager	Non-null.
[in]	block_file_paths	Nullable, array of block files described by their full filesystem paths.
[in]	block_file_paths_len	Length of the block_file_paths array.

Returns: True if the import blocks call was completed successfully.

◆ kernel_chainstate_manager_options_create()

BITCOINKERNEL_API kernel_ChainstateManagerOptions * kernel_chainstate_manager_options_create	(	const kernel_Context *	context,
		const char *	data_directory,
		size_t	data_directory_len,
		const char *	blocks_directory,
		size_t	blocks_directory_len
	)

Create options for the chainstate manager.

Parameters

[in]	context	Non-null, the created options will associate with this kernel context for the duration of their lifetime. The same context needs to be used when instantiating the chainstate manager.
[in]	data_directory	Non-null, path string of the directory containing the chainstate data. If the directory does not exist yet, it will be created.
[in]	blocks_directory	Non-null, path string of the directory containing the block data. If the directory does not exist yet, it will be created.

Returns: The allocated chainstate manager options, or null on error.

◆ kernel_chainstate_manager_options_destroy()

BITCOINKERNEL_API void kernel_chainstate_manager_options_destroy ( kernel_ChainstateManagerOptions * chainstate_manager_options )

Destroy the chainstate manager options.

◆ kernel_chainstate_manager_options_set_block_tree_db_in_memory()

BITCOINKERNEL_API void kernel_chainstate_manager_options_set_block_tree_db_in_memory	(	kernel_ChainstateManagerOptions *	chainstate_manager_options,
		bool	block_tree_db_in_memory
	)

Sets block tree db in memory in the options.

Parameters

[in]	chainstate_manager_options	Non-null, created by kernel_chainstate_manager_options_create.
[in]	block_tree_db_in_memory	Set block tree db in memory.

◆ kernel_chainstate_manager_options_set_chainstate_db_in_memory()

BITCOINKERNEL_API void kernel_chainstate_manager_options_set_chainstate_db_in_memory	(	kernel_ChainstateManagerOptions *	chainstate_manager_options,
		bool	chainstate_db_in_memory
	)

Sets chainstate db in memory in the options.

Parameters

[in]	chainstate_manager_options	Non-null, created by kernel_chainstate_manager_options_create.
[in]	chainstate_db_in_memory	Set chainstate db in memory.

◆ kernel_chainstate_manager_options_set_wipe_dbs()

BITCOINKERNEL_API bool kernel_chainstate_manager_options_set_wipe_dbs	(	kernel_ChainstateManagerOptions *	chainstate_manager_options,
		bool	wipe_block_tree_db,
		bool	wipe_chainstate_db
	)

Sets wipe db in the options. In combination with calling kernel_chainstate_manager_import_blocks this triggers either a full reindex, or a reindex of just the chainstate database.

Parameters

[in]	chainstate_manager_options	Non-null, created by kernel_chainstate_manager_options_create.
[in]	wipe_block_tree_db	Set wipe block tree db. Should only be True if wipe_chainstate_db is True too.
[in]	wipe_chainstate_db	Set wipe chainstate db.

Returns: True if the set was successful, False if the set failed.

◆ kernel_chainstate_manager_options_set_worker_threads_num()

BITCOINKERNEL_API void kernel_chainstate_manager_options_set_worker_threads_num	(	kernel_ChainstateManagerOptions *	chainstate_manager_options,
		int	worker_threads
	)

Set the number of available worker threads used during validation.

Parameters

[in]	chainstate_manager_options	Non-null, options to be set.
[in]	worker_threads	The number of worker threads that should be spawned in the thread pool used for validation. When set to 0 no parallel verification is done. The value range is clamped internally between 0 and 15.

◆ kernel_chainstate_manager_process_block()

BITCOINKERNEL_API bool kernel_chainstate_manager_process_block	(	const kernel_Context *	context,
		kernel_ChainstateManager *	chainstate_manager,
		kernel_Block *	block,
		bool *	new_block
	)

Process and validate the passed in block with the chainstate manager. More detailed validation information in case of a failure can also be retrieved through a registered validation interface. If the block fails to validate the block_checked callback's 'BlockValidationState' will contain details.

Parameters

[in]	context	Non-null.
[in]	chainstate_manager	Non-null.
[in]	block	Non-null, block to be validated.
[out]	new_block	Nullable, will be set to true if this block was not processed before, and false otherwise.

Returns: True if processing the block was successful. Will also return true for valid, but duplicate blocks.

◆ kernel_context_create()

BITCOINKERNEL_API kernel_Context * kernel_context_create ( const kernel_ContextOptions * context_options )

Create a new kernel context. If the options have not been previously set, their corresponding fields will be initialized to default values; the context will assume mainnet chain parameters and won't attempt to call the kernel notification callbacks.

Parameters

[in] context_options Nullable, created by kernel_context_options_create.

Returns: The allocated kernel context, or null on error.

◆ kernel_context_destroy()

BITCOINKERNEL_API void kernel_context_destroy ( kernel_Context * context )

Destroy the context.

◆ kernel_context_interrupt()

BITCOINKERNEL_API bool kernel_context_interrupt ( kernel_Context * context )

Interrupt can be used to halt long-running validation functions like when reindexing, importing or processing blocks.

Parameters

[in] context Non-null.

Returns: True if the interrupt was successful.

◆ kernel_context_options_create()

BITCOINKERNEL_API kernel_ContextOptions * kernel_context_options_create ( )

Creates an empty context options.

◆ kernel_context_options_destroy()

BITCOINKERNEL_API void kernel_context_options_destroy ( kernel_ContextOptions * context_options )

Destroy the context options.

◆ kernel_context_options_set_chainparams()

BITCOINKERNEL_API void kernel_context_options_set_chainparams	(	kernel_ContextOptions *	context_options,
		const kernel_ChainParameters *	chain_parameters
	)

Sets the chain params for the context options. The context created with the options will be configured for these chain parameters.

Parameters

[in]	context_options	Non-null, previously created by kernel_context_options_create.
[in]	chain_parameters	Is set to the context options.

◆ kernel_context_options_set_notifications()

BITCOINKERNEL_API void kernel_context_options_set_notifications	(	kernel_ContextOptions *	context_options,
		kernel_NotificationInterfaceCallbacks	notifications
	)

Set the kernel notifications for the context options. The context created with the options will be configured with these notifications.

Parameters

[in]	context_options	Non-null, previously created by kernel_context_options_create.
[in]	notifications	Is set to the context options.

◆ kernel_context_options_set_validation_interface()

BITCOINKERNEL_API void kernel_context_options_set_validation_interface	(	kernel_ContextOptions *	context_options,
		kernel_ValidationInterfaceCallbacks	validation_interface_callbacks
	)

Set the validation interface callbacks for the context options. The context created with the options will be configured for these validation interface callbacks. The callbacks will then be triggered from validation events issued by the chainstate manager created from the same context.

Parameters

[in]	context_options	Non-null, previously created with kernel_context_options_create.
[in]	validation_interface_callbacks	The callbacks used for passing validation information to the user.

◆ kernel_logging_connection_create()

BITCOINKERNEL_API kernel_LoggingConnection * kernel_logging_connection_create	(	kernel_LogCallback	callback,
		const void *	user_data,
		const kernel_LoggingOptions	options
	)

Start logging messages through the provided callback. Log messages produced before this function is first called are buffered and on calling this function are logged immediately.

Parameters

[in]	callback	Non-null, function through which messages will be logged.
[in]	user_data	Nullable, holds a user-defined opaque structure. Is passed back to the user through the callback.
[in]	options	Sets formatting options of the log messages.

Returns: A new kernel logging connection, or null on error.

◆ kernel_logging_connection_destroy()

BITCOINKERNEL_API void kernel_logging_connection_destroy ( kernel_LoggingConnection * logging_connection )

Stop logging and destroy the logging connection.

◆ kernel_logging_disable()

BITCOINKERNEL_API void kernel_logging_disable ( )

This disables the global internal logger. No log messages will be buffered internally anymore once this is called and the buffer is cleared. This function should only be called once and is not thread or re-entry safe. Log messages will be buffered until this function is called, or a logging connection is created.

◆ kernel_logging_disable_category()

BITCOINKERNEL_API void kernel_logging_disable_category ( const kernel_LogCategory category )

Disable a specific log category for the global internal logger. This function is not thread safe. Mutiple calls from different threads are allowed but must be synchronized. This changes a global setting and will override settings for all existing kernel_LoggingConnection instances.

Parameters

[in] category If kernel_LOG_ALL is chosen, all categories will be disabled.

◆ kernel_logging_enable_category()

BITCOINKERNEL_API void kernel_logging_enable_category ( const kernel_LogCategory category )

Enable a specific log category for the global internal logger. This function is not thread safe. Mutiple calls from different threads are allowed but must be synchronized. This changes a global setting and will override settings for all existing kernel_LoggingConnection instances.

Parameters

[in] category If kernel_LOG_ALL is chosen, all categories will be enabled.

◆ kernel_logging_set_level_category()

BITCOINKERNEL_API void kernel_logging_set_level_category	(	const kernel_LogCategory	category,
		kernel_LogLevel	level
	)

Set the log level of the global internal logger. This does not enable the selected categories. Use kernel_logging_enable_category to start logging from a specific, or all categories. This function is not thread safe. Mutiple calls from different threads are allowed but must be synchronized. This changes a global setting and will override settings for all existing kernel_LoggingConnection instances.

Parameters

[in]	category	If kernel_LOG_ALL is chosen, all messages at the specified level will be logged. Otherwise only messages from the specified category will be logged at the specified level and above.
[in]	level	Log level at which the log category is set.

◆ kernel_script_pubkey_copy_data()

BITCOINKERNEL_API kernel_ByteArray * kernel_script_pubkey_copy_data ( const kernel_ScriptPubkey * script_pubkey )

Copies the script pubkey data into the returned byte array.

Parameters

[in] script_pubkey Non-null.

Returns: The serialized script pubkey data.

◆ kernel_script_pubkey_create()

BITCOINKERNEL_API kernel_ScriptPubkey * kernel_script_pubkey_create	(	const unsigned char *	script_pubkey,
		size_t	script_pubkey_len
	)

Create a script pubkey from serialized data.

Parameters

[in]	script_pubkey	Non-null.
[in]	script_pubkey_len	Length of the script pubkey data.

Returns: The script pubkey.

◆ kernel_script_pubkey_destroy()

BITCOINKERNEL_API void kernel_script_pubkey_destroy ( kernel_ScriptPubkey * script_pubkey )

Destroy the script pubkey.

◆ kernel_transaction_create()

BITCOINKERNEL_API kernel_Transaction * kernel_transaction_create	(	const unsigned char *	raw_transaction,
		size_t	raw_transaction_len
	)

Create a new transaction from the serialized data.

Parameters

[in]	raw_transaction	Non-null.
[in]	raw_transaction_len	Length of the serialized transaction.

Returns: The transaction, or null on error.

◆ kernel_transaction_destroy()

BITCOINKERNEL_API void kernel_transaction_destroy ( kernel_Transaction * transaction )

Destroy the transaction.

◆ kernel_transaction_output_copy_script_pubkey()

BITCOINKERNEL_API kernel_ScriptPubkey * kernel_transaction_output_copy_script_pubkey ( kernel_TransactionOutput * transaction_output )

Copies the script pubkey of an output in the returned script pubkey opaque object.

Parameters

[in] transaction_output Non-null.

Returns: The data for the output's script pubkey.

◆ kernel_transaction_output_create()

BITCOINKERNEL_API kernel_TransactionOutput * kernel_transaction_output_create	(	const kernel_ScriptPubkey *	script_pubkey,
		int64_t	amount
	)

Create a transaction output from a script pubkey and an amount.

Parameters

[in]	script_pubkey	Non-null.
[in]	amount	The amount associated with the script pubkey for this output.

Returns: The transaction output.

◆ kernel_transaction_output_destroy()

BITCOINKERNEL_API void kernel_transaction_output_destroy ( kernel_TransactionOutput * transaction_output )

Destroy the transaction output.

◆ kernel_transaction_output_get_amount()

BITCOINKERNEL_API int64_t kernel_transaction_output_get_amount ( kernel_TransactionOutput * transaction_output )

Gets the amount associated with this transaction output.

Parameters

[in] transaction_output Non-null.

Returns: The amount.

◆ kernel_verify_script()

BITCOINKERNEL_API bool kernel_verify_script	(	const kernel_ScriptPubkey *	script_pubkey,
		int64_t	amount,
		const kernel_Transaction *	tx_to,
		const kernel_TransactionOutput **	spent_outputs,
		size_t	spent_outputs_len,
		unsigned int	input_index,
		unsigned int	flags,
		kernel_ScriptVerifyStatus *	status
	)

Verify if the input at input_index of tx_to spends the script pubkey under the constraints specified by flags. If the kernel_SCRIPT_FLAGS_VERIFY_WITNESS flag is set in the flags bitfield, the amount parameter is used. If the taproot flag is set, the spent outputs parameter is used to validate taproot transactions.

Parameters

[in]	script_pubkey	Non-null, script pubkey to be spent.
[in]	amount	Amount of the script pubkey's associated output. May be zero if the witness flag is not set.
[in]	tx_to	Non-null, transaction spending the script_pubkey.
[in]	spent_outputs	Nullable if the taproot flag is not set. Points to an array of outputs spent by the transaction.
[in]	spent_outputs_len	Length of the spent_outputs array.
[in]	input_index	Index of the input in tx_to spending the script_pubkey.
[in]	flags	Bitfield of kernel_ScriptFlags controlling validation constraints.
[out]	status	Nullable, will be set to an error code if the operation fails. Should be set to kernel_SCRIPT_VERIFY_OK.

Returns: True if the script is valid.

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ BITCOINKERNEL_API

◆ BITCOINKERNEL_ARG_NONNULL

◆ BITCOINKERNEL_WARN_UNUSED_RESULT

Typedef Documentation

◆ kernel_Block

◆ kernel_BlockIndex

◆ kernel_BlockPointer

◆ kernel_BlockUndo

◆ kernel_BlockValidationState

◆ kernel_ChainParameters

◆ kernel_ChainstateManager

◆ kernel_ChainstateManagerOptions

◆ kernel_Context

◆ kernel_ContextOptions

◆ kernel_LogCallback

◆ kernel_LoggingConnection

◆ kernel_NotifyBlockTip

◆ kernel_NotifyFatalError

◆ kernel_NotifyFlushError

◆ kernel_NotifyHeaderTip

◆ kernel_NotifyProgress

◆ kernel_NotifyWarningSet

◆ kernel_NotifyWarningUnset

◆ kernel_ScriptPubkey

◆ kernel_Transaction

◆ kernel_TransactionOutput

◆ kernel_ValidationInterfaceBlockChecked

Enumeration Type Documentation

◆ kernel_BlockValidationResult

◆ kernel_ChainType

◆ kernel_LogCategory

◆ kernel_LogLevel

◆ kernel_ScriptFlags

◆ kernel_ScriptVerifyStatus

◆ kernel_SynchronizationState

◆ kernel_ValidationMode

◆ kernel_Warning

Function Documentation

◆ kernel_block_copy_data()

◆ kernel_block_create()

◆ kernel_block_destroy()

◆ kernel_block_get_hash()

◆ kernel_block_hash_destroy()

◆ kernel_block_index_destroy()

◆ kernel_block_index_get_block_hash()

◆ kernel_block_index_get_by_hash()

◆ kernel_block_index_get_by_height()

◆ kernel_block_index_get_genesis()

◆ kernel_block_index_get_height()

◆ kernel_block_index_get_next()

◆ kernel_block_index_get_previous()

◆ kernel_block_index_get_tip()

◆ kernel_block_pointer_copy_data()

◆ kernel_block_pointer_get_hash()

◆ kernel_block_read()

◆ kernel_block_undo_copy_transaction_output_by_index()

◆ kernel_block_undo_destroy()

◆ kernel_block_undo_get_transaction_output_height_by_index()

◆ kernel_block_undo_get_transaction_undo_size()

◆ kernel_block_undo_read()

◆ kernel_block_undo_size()

◆ kernel_block_validation_state_get_block_validation_result()

◆ kernel_block_validation_state_get_validation_mode()

◆ kernel_byte_array_destroy()

◆ kernel_chain_parameters_create()

◆ kernel_chain_parameters_destroy()

◆ kernel_chainstate_manager_create()

◆ kernel_chainstate_manager_destroy()

◆ kernel_chainstate_manager_import_blocks()

◆ kernel_chainstate_manager_options_create()

◆ kernel_chainstate_manager_options_destroy()

◆ kernel_chainstate_manager_options_set_block_tree_db_in_memory()

◆ kernel_chainstate_manager_options_set_chainstate_db_in_memory()

◆ kernel_chainstate_manager_options_set_wipe_dbs()