Bitcoin Kernel
C header for interacting with the Bitcoin Kernel library.
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs
bitcoinkernel.h File Reference
#include <stddef.h>
#include <stdint.h>
Include dependency graph for bitcoinkernel.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  btck_ValidationInterfaceCallbacks
 
struct  btck_NotificationInterfaceCallbacks
 
struct  btck_LoggingOptions
 
struct  btck_BlockHash
 

Macros

#define BITCOINKERNEL_API
 
#define BITCOINKERNEL_WARN_UNUSED_RESULT
 
#define BITCOINKERNEL_ARG_NONNULL(...)
 
#define btck_SynchronizationState_INIT_REINDEX   ((btck_SynchronizationState)(0))
 
#define btck_SynchronizationState_INIT_DOWNLOAD   ((btck_SynchronizationState)(1))
 
#define btck_SynchronizationState_POST_INIT   ((btck_SynchronizationState)(2))
 
#define btck_Warning_UNKNOWN_NEW_RULES_ACTIVATED   ((btck_Warning)(0))
 
#define btck_Warning_LARGE_WORK_INVALID_CHAIN   ((btck_Warning)(1))
 
#define btck_ValidationMode_VALID   ((btck_ValidationMode)(0))
 
#define btck_ValidationMode_INVALID   ((btck_ValidationMode)(1))
 
#define btck_ValidationMode_INTERNAL_ERROR   ((btck_ValidationMode)(2))
 
#define btck_BlockValidationResult_UNSET   ((btck_BlockValidationResult)(0))
 initial value. Block has not yet been rejected
 
#define btck_BlockValidationResult_CONSENSUS   ((btck_BlockValidationResult)(1))
 invalid by consensus rules (excluding any below reasons)
 
#define btck_BlockValidationResult_CACHED_INVALID   ((btck_BlockValidationResult)(2))
 this block was cached as being invalid and we didn't store the reason why
 
#define btck_BlockValidationResult_INVALID_HEADER   ((btck_BlockValidationResult)(3))
 invalid proof of work or time too old
 
#define btck_BlockValidationResult_MUTATED   ((btck_BlockValidationResult)(4))
 the block's data didn't match the data committed to by the PoW
 
#define btck_BlockValidationResult_MISSING_PREV   ((btck_BlockValidationResult)(5))
 We don't have the previous block the checked one is built on.
 
#define btck_BlockValidationResult_INVALID_PREV   ((btck_BlockValidationResult)(6))
 A block this one builds on is invalid.
 
#define btck_BlockValidationResult_TIME_FUTURE   ((btck_BlockValidationResult)(7))
 block timestamp was > 2 hours in the future (or our clock is bad)
 
#define btck_BlockValidationResult_HEADER_LOW_WORK   ((btck_BlockValidationResult)(8))
 the block header may be on a too-little-work chain
 
#define btck_LogCategory_ALL   ((btck_LogCategory)(0))
 
#define btck_LogCategory_BENCH   ((btck_LogCategory)(1))
 
#define btck_LogCategory_BLOCKSTORAGE   ((btck_LogCategory)(2))
 
#define btck_LogCategory_COINDB   ((btck_LogCategory)(3))
 
#define btck_LogCategory_LEVELDB   ((btck_LogCategory)(4))
 
#define btck_LogCategory_MEMPOOL   ((btck_LogCategory)(5))
 
#define btck_LogCategory_PRUNE   ((btck_LogCategory)(6))
 
#define btck_LogCategory_RAND   ((btck_LogCategory)(7))
 
#define btck_LogCategory_REINDEX   ((btck_LogCategory)(8))
 
#define btck_LogCategory_VALIDATION   ((btck_LogCategory)(9))
 
#define btck_LogCategory_KERNEL   ((btck_LogCategory)(10))
 
#define btck_LogLevel_TRACE   ((btck_LogLevel)(0))
 
#define btck_LogLevel_DEBUG   ((btck_LogLevel)(1))
 
#define btck_LogLevel_INFO   ((btck_LogLevel)(2))
 
#define btck_ScriptVerifyStatus_SCRIPT_VERIFY_OK   ((btck_ScriptVerifyStatus)(0))
 
#define btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION   ((btck_ScriptVerifyStatus)(2))
 The flags very combined in an invalid way.
 
#define btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED   ((btck_ScriptVerifyStatus)(3))
 The taproot flag was set, so valid spent_outputs have to be provided.
 
#define btck_ScriptVerificationFlags_NONE   ((btck_ScriptVerificationFlags)(0))
 
#define btck_ScriptVerificationFlags_P2SH   ((btck_ScriptVerificationFlags)(1U << 0))
 evaluate P2SH (BIP16) subscripts
 
#define btck_ScriptVerificationFlags_DERSIG   ((btck_ScriptVerificationFlags)(1U << 2))
 enforce strict DER (BIP66) compliance
 
#define btck_ScriptVerificationFlags_NULLDUMMY   ((btck_ScriptVerificationFlags)(1U << 4))
 enforce NULLDUMMY (BIP147)
 
#define btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY   ((btck_ScriptVerificationFlags)(1U << 9))
 enable CHECKLOCKTIMEVERIFY (BIP65)
 
#define btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY   ((btck_ScriptVerificationFlags)(1U << 10))
 enable CHECKSEQUENCEVERIFY (BIP112)
 
#define btck_ScriptVerificationFlags_WITNESS   ((btck_ScriptVerificationFlags)(1U << 11))
 enable WITNESS (BIP141)
 
#define btck_ScriptVerificationFlags_TAPROOT   ((btck_ScriptVerificationFlags)(1U << 17))
 enable TAPROOT (BIPs 341 & 342)
 
#define btck_ScriptVerificationFlags_ALL
 
#define btck_ChainType_MAINNET   ((btck_ChainType)(0))
 
#define btck_ChainType_TESTNET   ((btck_ChainType)(1))
 
#define btck_ChainType_TESTNET_4   ((btck_ChainType)(2))
 
#define btck_ChainType_SIGNET   ((btck_ChainType)(3))
 
#define btck_ChainType_REGTEST   ((btck_ChainType)(4))
 

Typedefs

typedef struct btck_Transaction btck_Transaction
 
typedef struct btck_ScriptPubkey btck_ScriptPubkey
 
typedef struct btck_TransactionOutput btck_TransactionOutput
 
typedef struct btck_LoggingConnection btck_LoggingConnection
 
typedef struct btck_ChainParameters btck_ChainParameters
 
typedef struct btck_ContextOptions btck_ContextOptions
 
typedef struct btck_Context btck_Context
 
typedef struct btck_BlockTreeEntry btck_BlockTreeEntry
 
typedef struct btck_ChainstateManagerOptions btck_ChainstateManagerOptions
 
typedef struct btck_ChainstateManager btck_ChainstateManager
 
typedef struct btck_Block btck_Block
 
typedef struct btck_BlockValidationState btck_BlockValidationState
 
typedef struct btck_Chain btck_Chain
 
typedef struct btck_BlockSpentOutputs btck_BlockSpentOutputs
 
typedef struct btck_TransactionSpentOutputs btck_TransactionSpentOutputs
 
typedef struct btck_Coin btck_Coin
 
typedef uint8_t btck_SynchronizationState
 
typedef uint8_t btck_Warning
 
typedef void(* btck_LogCallback) (void *user_data, const char *message, size_t message_len)
 
typedef void(* btck_DestroyCallback) (void *user_data)
 
typedef void(* btck_NotifyBlockTip) (void *user_data, btck_SynchronizationState state, btck_BlockTreeEntry *entry, double verification_progress)
 
typedef void(* btck_NotifyHeaderTip) (void *user_data, btck_SynchronizationState state, int64_t height, int64_t timestamp, int presync)
 
typedef void(* btck_NotifyProgress) (void *user_data, const char *title, size_t title_len, int progress_percent, int resume_possible)
 
typedef void(* btck_NotifyWarningSet) (void *user_data, btck_Warning warning, const char *message, size_t message_len)
 
typedef void(* btck_NotifyWarningUnset) (void *user_data, btck_Warning warning)
 
typedef void(* btck_NotifyFlushError) (void *user_data, const char *message, size_t message_len)
 
typedef void(* btck_NotifyFatalError) (void *user_data, const char *message, size_t message_len)
 
typedef void(* btck_ValidationInterfaceBlockChecked) (void *user_data, btck_Block *block, const btck_BlockValidationState *state)
 
typedef int(* btck_WriteBytes) (const void *bytes, size_t size, void *userdata)
 
typedef uint8_t btck_ValidationMode
 
typedef uint32_t btck_BlockValidationResult
 
typedef uint8_t btck_LogCategory
 
typedef uint8_t btck_LogLevel
 
typedef uint8_t btck_ScriptVerifyStatus
 
typedef uint32_t btck_ScriptVerificationFlags
 
typedef uint8_t btck_ChainType
 

Functions

Transaction

Functions for working with transactions.

BITCOINKERNEL_API btck_Transactionbtck_transaction_create (const void *raw_transaction, size_t raw_transaction_len)
 Create a new transaction from the serialized data.
 
BITCOINKERNEL_API btck_Transactionbtck_transaction_copy (const btck_Transaction *transaction)
 Copy a transaction. Transactions are reference counted, so this just increments the reference count.
 
BITCOINKERNEL_API int btck_transaction_to_bytes (const btck_Transaction *transaction, btck_WriteBytes writer, void *user_data) 2)
 
BITCOINKERNEL_API size_t btck_transaction_count_outputs (const btck_Transaction *transaction)
 Get the number of outputs of a transaction.
 
BITCOINKERNEL_API const btck_TransactionOutputbtck_transaction_get_output_at (const btck_Transaction *transaction, size_t output_index)
 Get the transaction outputs at the provided index. The returned transaction output is not owned and depends on the lifetime of the transaction.
 
BITCOINKERNEL_API size_t btck_transaction_count_inputs (const btck_Transaction *transaction)
 Get the number of inputs of a transaction.
 
BITCOINKERNEL_API void btck_transaction_destroy (btck_Transaction *transaction)
 
ScriptPubkey

Functions for working with script pubkeys.

BITCOINKERNEL_API btck_ScriptPubkeybtck_script_pubkey_create (const void *script_pubkey, size_t script_pubkey_len)
 Create a script pubkey from serialized data.
 
BITCOINKERNEL_API btck_ScriptPubkeybtck_script_pubkey_copy (const btck_ScriptPubkey *script_pubkey)
 Copy a script pubkey.
 
BITCOINKERNEL_API int btck_script_pubkey_verify (const btck_ScriptPubkey *script_pubkey, int64_t amount, const btck_Transaction *tx_to, const btck_TransactionOutput **spent_outputs, size_t spent_outputs_len, unsigned int input_index, unsigned int flags, btck_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 btck_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.
 
BITCOINKERNEL_API int btck_script_pubkey_to_bytes (const btck_ScriptPubkey *script_pubkey, btck_WriteBytes writer, void *user_data) 2)
 
BITCOINKERNEL_API void btck_script_pubkey_destroy (btck_ScriptPubkey *script_pubkey)
 
TransactionOutput

Functions for working with transaction outputs.

BITCOINKERNEL_API btck_TransactionOutputbtck_transaction_output_create (const btck_ScriptPubkey *script_pubkey, int64_t amount)
 Create a transaction output from a script pubkey and an amount.
 
BITCOINKERNEL_API const btck_ScriptPubkeybtck_transaction_output_get_script_pubkey (const btck_TransactionOutput *transaction_output)
 Get the script pubkey of the output. The returned script pubkey is not owned and depends on the lifetime of the transaction output.
 
BITCOINKERNEL_API int64_t btck_transaction_output_get_amount (const btck_TransactionOutput *transaction_output)
 Get the amount in the output.
 
BITCOINKERNEL_API btck_TransactionOutputbtck_transaction_output_copy (const btck_TransactionOutput *transaction_output)
 Copy a transaction output.
 
BITCOINKERNEL_API void btck_transaction_output_destroy (btck_TransactionOutput *transaction_output)
 
Logging

Logging-related functions.

BITCOINKERNEL_API void btck_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 btck_logging_set_level_category (btck_LogCategory category, btck_LogLevel level)
 Set the log level of the global internal logger. This does not enable the selected categories. Use btck_logging_enable_category to start logging from a specific, or all categories. This function is not thread safe. Multiple calls from different threads are allowed but must be synchronized. This changes a global setting and will override settings for all existing btck_LoggingConnection instances.
 
BITCOINKERNEL_API void btck_logging_enable_category (btck_LogCategory category)
 Enable a specific log category for the global internal logger. This function is not thread safe. Multiple calls from different threads are allowed but must be synchronized. This changes a global setting and will override settings for all existing btck_LoggingConnection instances.
 
BITCOINKERNEL_API void btck_logging_disable_category (btck_LogCategory category)
 Disable a specific log category for the global internal logger. This function is not thread safe. Multiple calls from different threads are allowed but must be synchronized. This changes a global setting and will override settings for all existing btck_LoggingConnection instances.
 
BITCOINKERNEL_API btck_LoggingConnectionbtck_logging_connection_create (btck_LogCallback log_callback, void *user_data, btck_DestroyCallback user_data_destroy_callback, const btck_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 btck_logging_connection_destroy (btck_LoggingConnection *logging_connection)
 
ChainParameters

Functions for working with chain parameters.

BITCOINKERNEL_API btck_ChainParametersbtck_chain_parameters_create (const btck_ChainType chain_type)
 Creates a chain parameters struct with default parameters based on the passed in chain type.
 
BITCOINKERNEL_API btck_ChainParametersbtck_chain_parameters_copy (const btck_ChainParameters *chain_parameters)
 
BITCOINKERNEL_API void btck_chain_parameters_destroy (btck_ChainParameters *chain_parameters)
 
ContextOptions

Functions for working with context options.

BITCOINKERNEL_API btck_ContextOptionsbtck_context_options_create ()
 
BITCOINKERNEL_API void btck_context_options_set_chainparams (btck_ContextOptions *context_options, const btck_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 btck_context_options_set_notifications (btck_ContextOptions *context_options, btck_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 btck_context_options_set_validation_interface (btck_ContextOptions *context_options, btck_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 btck_context_options_destroy (btck_ContextOptions *context_options)
 
Context

Functions for working with contexts.

BITCOINKERNEL_API btck_Contextbtck_context_create (const btck_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 btck_Contextbtck_context_copy (const btck_Context *context)
 
BITCOINKERNEL_API int btck_context_interrupt (btck_Context *context)
 Interrupt can be used to halt long-running validation functions like when reindexing, importing or processing blocks.
 
BITCOINKERNEL_API void btck_context_destroy (btck_Context *context)
 
BlockTreeEntry

Functions for working with block tree entries.

BITCOINKERNEL_API btck_BlockTreeEntrybtck_block_tree_entry_get_previous (const btck_BlockTreeEntry *block_tree_entry)
 Returns the previous block tree entry in the chain, or null if the current block tree entry is the genesis block.
 
BITCOINKERNEL_API int32_t btck_block_tree_entry_get_height (const btck_BlockTreeEntry *block_tree_entry)
 Return the height of a certain block tree entry.
 
BITCOINKERNEL_API void btck_block_tree_entry_destroy (btck_BlockTreeEntry *block_tree_entry)
 Destroy the block tree entry.
 
ChainstateManagerOptions

Functions for working with chainstate manager options.

BITCOINKERNEL_API btck_ChainstateManagerOptionsbtck_chainstate_manager_options_create (const btck_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 btck_chainstate_manager_options_set_worker_threads_num (btck_ChainstateManagerOptions *chainstate_manager_options, int worker_threads)
 Set the number of available worker threads used during validation.
 
BITCOINKERNEL_API int btck_chainstate_manager_options_set_wipe_dbs (btck_ChainstateManagerOptions *chainstate_manager_options, int wipe_block_tree_db, int wipe_chainstate_db)
 Sets wipe db in the options. In combination with calling btck_chainstate_manager_import_blocks this triggers either a full reindex, or a reindex of just the chainstate database.
 
BITCOINKERNEL_API void btck_chainstate_manager_options_set_block_tree_db_in_memory (btck_ChainstateManagerOptions *chainstate_manager_options, int block_tree_db_in_memory)
 Sets block tree db in memory in the options.
 
BITCOINKERNEL_API void btck_chainstate_manager_options_set_chainstate_db_in_memory (btck_ChainstateManagerOptions *chainstate_manager_options, int chainstate_db_in_memory)
 Sets chainstate db in memory in the options.
 
BITCOINKERNEL_API void btck_chainstate_manager_options_destroy (btck_ChainstateManagerOptions *chainstate_manager_options)
 
ChainstateManager

Functions for chainstate management.

BITCOINKERNEL_API btck_ChainstateManagerbtck_chainstate_manager_create (const btck_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.
 
BITCOINKERNEL_API int btck_chainstate_manager_import_blocks (btck_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 btck_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 int btck_chainstate_manager_process_block (btck_ChainstateManager *chainstate_manager, const btck_Block *block, int *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 int BITCOINKERNEL_API const btck_Chainbtck_chainstate_manager_get_active_chain (const btck_ChainstateManager *chainstate_manager)
 Returns the best known currently active chain. Its lifetime is dependent on the chainstate manager and state transitions within the chainstate manager, e.g. when processing blocks, will also change the chain. Data retrieved from this chain is only consistent up to the point when new data is processed in the chainstate manager. It is the user's responsibility to guard against these inconsistencies.
 
BITCOINKERNEL_API btck_BlockTreeEntrybtck_chainstate_manager_get_block_tree_entry_by_hash (const btck_ChainstateManager *chainstate_manager, const btck_BlockHash *block_hash) 2)
 Retrieve a block tree entry by its block hash.
 
BITCOINKERNEL_API void btck_chainstate_manager_destroy (btck_ChainstateManager *chainstate_manager)
 
Block

Functions for working with blocks.

BITCOINKERNEL_API btck_Blockbtck_block_read (const btck_ChainstateManager *chainstate_manager, const btck_BlockTreeEntry *block_tree_entry) 2)
 Reads the block the passed in block index points to from disk and returns it.
 
BITCOINKERNEL_API btck_Blockbtck_block_create (const void *raw_block, size_t raw_block_len)
 Parse a serialized raw block into a new block object.
 
BITCOINKERNEL_API btck_Blockbtck_block_copy (const btck_Block *block)
 Copy a block. Blocks are reference counted, so this just increments the reference count.
 
BITCOINKERNEL_API size_t btck_block_count_transactions (const btck_Block *block)
 Count the number of transactions contained in a block.
 
BITCOINKERNEL_API const btck_Transactionbtck_block_get_transaction_at (const btck_Block *block, size_t transaction_index)
 Get the transaction at the provided index. The returned transaction is not owned and depends on the lifetime of the block.
 
BITCOINKERNEL_API btck_BlockHashbtck_block_get_hash (const btck_Block *block)
 
BITCOINKERNEL_API int btck_block_to_bytes (const btck_Block *block, btck_WriteBytes writer, void *user_data) 2)
 
BITCOINKERNEL_API void btck_block_destroy (btck_Block *block)
 
BlockValidationState

Functions for working with block validation states.

BITCOINKERNEL_API btck_ValidationMode btck_block_validation_state_get_validation_mode (const btck_BlockValidationState *block_validation_state)
 
BITCOINKERNEL_API btck_BlockValidationResult btck_block_validation_state_get_block_validation_result (const btck_BlockValidationState *block_validation_state)
 
Chain

Functions for working with the chain

BITCOINKERNEL_API btck_BlockTreeEntrybtck_chain_get_tip (const btck_Chain *chain)
 Get the block tree entry of the current chain tip. Once returned, there is no guarantee that it remains in the active chain.
 
BITCOINKERNEL_API btck_BlockTreeEntrybtck_chain_get_genesis (const btck_Chain *chain)
 
BITCOINKERNEL_API btck_BlockTreeEntrybtck_chain_get_by_height (const btck_Chain *chain, int block_height)
 Retrieve a block tree entry by its height in the currently active chain. Once retrieved there is no guarantee that it remains in the active chain.
 
BITCOINKERNEL_API int btck_chain_contains (const btck_Chain *chain, const btck_BlockTreeEntry *block_tree_entry) 2)
 Return true if the passed in chain contains the block tree entry.
 
BITCOINKERNEL_API void btck_chain_destroy (btck_Chain *chain)
 Destroy the chain.
 
BlockSpentOutputs

Functions for working with block spent outputs.

BITCOINKERNEL_API btck_BlockSpentOutputsbtck_block_spent_outputs_read (const btck_ChainstateManager *chainstate_manager, const btck_BlockTreeEntry *block_tree_entry) 2)
 Reads the block spent coins data the passed in block tree entry points to from disk and returns it.
 
BITCOINKERNEL_API btck_BlockSpentOutputsbtck_block_spent_outputs_copy (const btck_BlockSpentOutputs *block_spent_outputs)
 Copy a block's spent outputs.
 
BITCOINKERNEL_API size_t btck_block_spent_outputs_count (const btck_BlockSpentOutputs *block_spent_outputs)
 Returns the number of transaction spent outputs whose data is contained in block spent outputs.
 
BITCOINKERNEL_API const btck_TransactionSpentOutputsbtck_block_spent_outputs_get_transaction_spent_outputs_at (const btck_BlockSpentOutputs *block_spent_outputs, size_t transaction_spent_outputs_index)
 Returns a transaction spent outputs contained in the block spent outputs at a certain index. The returned pointer is unowned and only valid for the lifetime of block_spent_outputs.
 
BITCOINKERNEL_API void btck_block_spent_outputs_destroy (btck_BlockSpentOutputs *block_spent_outputs)
 
TransactionSpentOutputs

Functions for working with the spent coins of a transaction

BITCOINKERNEL_API btck_TransactionSpentOutputsbtck_transaction_spent_outputs_copy (const btck_TransactionSpentOutputs *transaction_spent_outputs)
 Copy a transaction's spent outputs.
 
BITCOINKERNEL_API size_t btck_transaction_spent_outputs_count (const btck_TransactionSpentOutputs *transaction_spent_outputs)
 Returns the number of previous transaction outputs contained in the transaction spent outputs data.
 
BITCOINKERNEL_API const btck_Coinbtck_transaction_spent_outputs_get_coin_at (const btck_TransactionSpentOutputs *transaction_spent_outputs, size_t coin_index)
 Returns a coin contained in the transaction spent outputs at a certain index. The returned pointer is unowned and only valid for the lifetime of transaction_spent_outputs.
 
BITCOINKERNEL_API void btck_transaction_spent_outputs_destroy (btck_TransactionSpentOutputs *transaction_spent_outputs)
 
Coin

Functions for working with coins.

BITCOINKERNEL_API btck_Coinbtck_coin_copy (const btck_Coin *coin)
 Copy a coin.
 
BITCOINKERNEL_API uint32_t btck_coin_confirmation_height (const btck_Coin *coin)
 Returns the height of the block that contains the coin's prevout.
 
BITCOINKERNEL_API int btck_coin_is_coinbase (const btck_Coin *coin)
 Returns whether the containing transaction was a coinbase.
 
BITCOINKERNEL_API const btck_TransactionOutputbtck_coin_get_output (const btck_Coin *coin)
 Return the transaction output of a coin. The returned pointer is unowned and only valid for the lifetime of the coin.
 
BITCOINKERNEL_API void btck_coin_destroy (btck_Coin *coin)
 
BlockHash

Functions for working with block hashes.

BITCOINKERNEL_API btck_BlockHashbtck_block_tree_entry_get_block_hash (const btck_BlockTreeEntry *block_tree_entry)
 Return the block hash associated with a block tree entry.
 
BITCOINKERNEL_API void btck_block_hash_destroy (btck_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

◆ btck_BlockValidationResult_CACHED_INVALID

#define btck_BlockValidationResult_CACHED_INVALID   ((btck_BlockValidationResult)(2))

this block was cached as being invalid and we didn't store the reason why

◆ btck_BlockValidationResult_CONSENSUS

#define btck_BlockValidationResult_CONSENSUS   ((btck_BlockValidationResult)(1))

invalid by consensus rules (excluding any below reasons)

◆ btck_BlockValidationResult_HEADER_LOW_WORK

#define btck_BlockValidationResult_HEADER_LOW_WORK   ((btck_BlockValidationResult)(8))

the block header may be on a too-little-work chain

◆ btck_BlockValidationResult_INVALID_HEADER

#define btck_BlockValidationResult_INVALID_HEADER   ((btck_BlockValidationResult)(3))

invalid proof of work or time too old

◆ btck_BlockValidationResult_INVALID_PREV

#define btck_BlockValidationResult_INVALID_PREV   ((btck_BlockValidationResult)(6))

A block this one builds on is invalid.

◆ btck_BlockValidationResult_MISSING_PREV

#define btck_BlockValidationResult_MISSING_PREV   ((btck_BlockValidationResult)(5))

We don't have the previous block the checked one is built on.

◆ btck_BlockValidationResult_MUTATED

#define btck_BlockValidationResult_MUTATED   ((btck_BlockValidationResult)(4))

the block's data didn't match the data committed to by the PoW

◆ btck_BlockValidationResult_TIME_FUTURE

#define btck_BlockValidationResult_TIME_FUTURE   ((btck_BlockValidationResult)(7))

block timestamp was > 2 hours in the future (or our clock is bad)

◆ btck_BlockValidationResult_UNSET

#define btck_BlockValidationResult_UNSET   ((btck_BlockValidationResult)(0))

initial value. Block has not yet been rejected

◆ btck_ChainType_MAINNET

#define btck_ChainType_MAINNET   ((btck_ChainType)(0))

◆ btck_ChainType_REGTEST

#define btck_ChainType_REGTEST   ((btck_ChainType)(4))

◆ btck_ChainType_SIGNET

#define btck_ChainType_SIGNET   ((btck_ChainType)(3))

◆ btck_ChainType_TESTNET

#define btck_ChainType_TESTNET   ((btck_ChainType)(1))

◆ btck_ChainType_TESTNET_4

#define btck_ChainType_TESTNET_4   ((btck_ChainType)(2))

◆ btck_LogCategory_ALL

#define btck_LogCategory_ALL   ((btck_LogCategory)(0))

◆ btck_LogCategory_BENCH

#define btck_LogCategory_BENCH   ((btck_LogCategory)(1))

◆ btck_LogCategory_BLOCKSTORAGE

#define btck_LogCategory_BLOCKSTORAGE   ((btck_LogCategory)(2))

◆ btck_LogCategory_COINDB

#define btck_LogCategory_COINDB   ((btck_LogCategory)(3))

◆ btck_LogCategory_KERNEL

#define btck_LogCategory_KERNEL   ((btck_LogCategory)(10))

◆ btck_LogCategory_LEVELDB

#define btck_LogCategory_LEVELDB   ((btck_LogCategory)(4))

◆ btck_LogCategory_MEMPOOL

#define btck_LogCategory_MEMPOOL   ((btck_LogCategory)(5))

◆ btck_LogCategory_PRUNE

#define btck_LogCategory_PRUNE   ((btck_LogCategory)(6))

◆ btck_LogCategory_RAND

#define btck_LogCategory_RAND   ((btck_LogCategory)(7))

◆ btck_LogCategory_REINDEX

#define btck_LogCategory_REINDEX   ((btck_LogCategory)(8))

◆ btck_LogCategory_VALIDATION

#define btck_LogCategory_VALIDATION   ((btck_LogCategory)(9))

◆ btck_LogLevel_DEBUG

#define btck_LogLevel_DEBUG   ((btck_LogLevel)(1))

◆ btck_LogLevel_INFO

#define btck_LogLevel_INFO   ((btck_LogLevel)(2))

◆ btck_LogLevel_TRACE

#define btck_LogLevel_TRACE   ((btck_LogLevel)(0))

◆ btck_ScriptVerificationFlags_ALL

#define btck_ScriptVerificationFlags_ALL
Value:
#define btck_ScriptVerificationFlags_P2SH
evaluate P2SH (BIP16) subscripts
Definition bitcoinkernel.h:411
#define btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY
enable CHECKLOCKTIMEVERIFY (BIP65)
Definition bitcoinkernel.h:414
#define btck_ScriptVerificationFlags_TAPROOT
enable TAPROOT (BIPs 341 & 342)
Definition bitcoinkernel.h:417
#define btck_ScriptVerificationFlags_WITNESS
enable WITNESS (BIP141)
Definition bitcoinkernel.h:416
uint32_t btck_ScriptVerificationFlags
Definition bitcoinkernel.h:409
#define btck_ScriptVerificationFlags_NULLDUMMY
enforce NULLDUMMY (BIP147)
Definition bitcoinkernel.h:413
#define btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY
enable CHECKSEQUENCEVERIFY (BIP112)
Definition bitcoinkernel.h:415
#define btck_ScriptVerificationFlags_DERSIG
enforce strict DER (BIP66) compliance
Definition bitcoinkernel.h:412

◆ btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY

#define btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY   ((btck_ScriptVerificationFlags)(1U << 9))

enable CHECKLOCKTIMEVERIFY (BIP65)

◆ btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY

#define btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY   ((btck_ScriptVerificationFlags)(1U << 10))

enable CHECKSEQUENCEVERIFY (BIP112)

◆ btck_ScriptVerificationFlags_DERSIG

#define btck_ScriptVerificationFlags_DERSIG   ((btck_ScriptVerificationFlags)(1U << 2))

enforce strict DER (BIP66) compliance

◆ btck_ScriptVerificationFlags_NONE

#define btck_ScriptVerificationFlags_NONE   ((btck_ScriptVerificationFlags)(0))

◆ btck_ScriptVerificationFlags_NULLDUMMY

#define btck_ScriptVerificationFlags_NULLDUMMY   ((btck_ScriptVerificationFlags)(1U << 4))

enforce NULLDUMMY (BIP147)

◆ btck_ScriptVerificationFlags_P2SH

#define btck_ScriptVerificationFlags_P2SH   ((btck_ScriptVerificationFlags)(1U << 0))

evaluate P2SH (BIP16) subscripts

◆ btck_ScriptVerificationFlags_TAPROOT

#define btck_ScriptVerificationFlags_TAPROOT   ((btck_ScriptVerificationFlags)(1U << 17))

enable TAPROOT (BIPs 341 & 342)

◆ btck_ScriptVerificationFlags_WITNESS

#define btck_ScriptVerificationFlags_WITNESS   ((btck_ScriptVerificationFlags)(1U << 11))

enable WITNESS (BIP141)

◆ btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION

#define btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION   ((btck_ScriptVerifyStatus)(2))

The flags very combined in an invalid way.

◆ btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED

#define btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED   ((btck_ScriptVerifyStatus)(3))

The taproot flag was set, so valid spent_outputs have to be provided.

◆ btck_ScriptVerifyStatus_SCRIPT_VERIFY_OK

#define btck_ScriptVerifyStatus_SCRIPT_VERIFY_OK   ((btck_ScriptVerifyStatus)(0))

◆ btck_SynchronizationState_INIT_DOWNLOAD

#define btck_SynchronizationState_INIT_DOWNLOAD   ((btck_SynchronizationState)(1))

◆ btck_SynchronizationState_INIT_REINDEX

#define btck_SynchronizationState_INIT_REINDEX   ((btck_SynchronizationState)(0))

◆ btck_SynchronizationState_POST_INIT

#define btck_SynchronizationState_POST_INIT   ((btck_SynchronizationState)(2))

◆ btck_ValidationMode_INTERNAL_ERROR

#define btck_ValidationMode_INTERNAL_ERROR   ((btck_ValidationMode)(2))

◆ btck_ValidationMode_INVALID

#define btck_ValidationMode_INVALID   ((btck_ValidationMode)(1))

◆ btck_ValidationMode_VALID

#define btck_ValidationMode_VALID   ((btck_ValidationMode)(0))

◆ btck_Warning_LARGE_WORK_INVALID_CHAIN

#define btck_Warning_LARGE_WORK_INVALID_CHAIN   ((btck_Warning)(1))

◆ btck_Warning_UNKNOWN_NEW_RULES_ACTIVATED

#define btck_Warning_UNKNOWN_NEW_RULES_ACTIVATED   ((btck_Warning)(0))

Typedef Documentation

◆ btck_Block

typedef struct btck_Block btck_Block

Opaque data structure for holding a block.

◆ btck_BlockSpentOutputs

Opaque data structure for holding a block's spent outputs.

Contains 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 without the coinbase transaction). This is exposed through btck_TransactionSpentOutputs. Each btck_TransactionSpentOutputs is in turn a vector of all the previous outputs of a transaction (in order of their corresponding inputs).

◆ btck_BlockTreeEntry

Opaque data structure for holding a block tree entry.

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. The entry is part of a tree-like structure that is maintained internally. Every entry, besides the genesis, points to a single parent. Multiple entries may share a parent, thus forming a tree. Each entry corresponds to a single block and may be used to retrieve its data and validation status.

◆ btck_BlockValidationResult

typedef uint32_t btck_BlockValidationResult

A granular "reason" why a block was invalid.

◆ btck_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.

◆ btck_Chain

typedef struct btck_Chain btck_Chain

Opaque data structure for holding the currently known best-chain associated with a chainstate.

◆ btck_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.

◆ btck_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.

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

◆ btck_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.

◆ btck_ChainType

typedef uint8_t btck_ChainType

◆ btck_Coin

typedef struct btck_Coin btck_Coin

Opaque data structure for holding a coin.

Holds information on the btck_TransactionOutput held within, including the height it was spent at and whether it is a coinbase output.

◆ btck_Context

typedef struct btck_Context btck_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 is 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.

◆ btck_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.

◆ btck_DestroyCallback

typedef void(* btck_DestroyCallback) (void *user_data)

Function signature for freeing user data.

◆ btck_LogCallback

typedef void(* btck_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.

◆ btck_LogCategory

typedef uint8_t btck_LogCategory

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

◆ btck_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 btck_logging_disable. Functions changing the logging settings are global (and not thread safe) and change the settings for all existing btck_LoggingConnection instances.

◆ btck_LogLevel

typedef uint8_t btck_LogLevel

The level at which logs should be produced.

◆ btck_NotifyBlockTip

typedef void(* btck_NotifyBlockTip) (void *user_data, btck_SynchronizationState state, btck_BlockTreeEntry *entry, double verification_progress)

Function signatures for the kernel notifications.

◆ btck_NotifyFatalError

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

◆ btck_NotifyFlushError

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

◆ btck_NotifyHeaderTip

typedef void(* btck_NotifyHeaderTip) (void *user_data, btck_SynchronizationState state, int64_t height, int64_t timestamp, int presync)

◆ btck_NotifyProgress

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

◆ btck_NotifyWarningSet

typedef void(* btck_NotifyWarningSet) (void *user_data, btck_Warning warning, const char *message, size_t message_len)

◆ btck_NotifyWarningUnset

typedef void(* btck_NotifyWarningUnset) (void *user_data, btck_Warning warning)

◆ btck_ScriptPubkey

Opaque data structure for holding a script pubkey.

◆ btck_ScriptVerificationFlags

typedef uint32_t btck_ScriptVerificationFlags

Script verification flags that may be composed with each other.

◆ btck_ScriptVerifyStatus

typedef uint8_t btck_ScriptVerifyStatus

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

◆ btck_SynchronizationState

typedef uint8_t btck_SynchronizationState

Current sync state passed to tip changed callbacks.

◆ btck_Transaction

Opaque data structure for holding a transaction.

◆ btck_TransactionOutput

Opaque data structure for holding a transaction output.

◆ btck_TransactionSpentOutputs

Opaque data structure for holding a transaction's spent outputs.

Holds the coins consumed by a certain transaction. Retrieved through the btck_BlockSpentOutputs. The coins are in the same order as the transaction's inputs consuming them.

◆ btck_ValidationInterfaceBlockChecked

typedef void(* btck_ValidationInterfaceBlockChecked) (void *user_data, btck_Block *block, const btck_BlockValidationState *state)

Function signatures for the validation interface.

◆ btck_ValidationMode

typedef uint8_t btck_ValidationMode

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

◆ btck_Warning

typedef uint8_t btck_Warning

Possible warning types issued by validation.

◆ btck_WriteBytes

typedef int(* btck_WriteBytes) (const void *bytes, size_t size, void *userdata)

Function signature for serializing data.

Function Documentation

◆ btck_block_copy()

BITCOINKERNEL_API btck_Block * btck_block_copy ( const btck_Block block)

Copy a block. Blocks are reference counted, so this just increments the reference count.

Parameters
[in]blockNon-null.
Returns
The copied block.

◆ btck_block_count_transactions()

BITCOINKERNEL_API size_t btck_block_count_transactions ( const btck_Block block)

Count the number of transactions contained in a block.

Parameters
[in]blockNon-null.
Returns
The number of transactions in the block.

◆ btck_block_create()

BITCOINKERNEL_API btck_Block * btck_block_create ( const void *  raw_block,
size_t  raw_block_len 
)

Parse a serialized raw block into a new block object.

Parameters
[in]raw_blockNon-null, serialized block.
[in]raw_block_lenLength of the serialized block.
Returns
The allocated block, or null on error.

◆ btck_block_destroy()

BITCOINKERNEL_API void btck_block_destroy ( btck_Block block)

Destroy the block.

◆ btck_block_get_hash()

BITCOINKERNEL_API btck_BlockHash * btck_block_get_hash ( const btck_Block block)

◆ btck_block_get_transaction_at()

BITCOINKERNEL_API const btck_Transaction * btck_block_get_transaction_at ( const btck_Block block,
size_t  transaction_index 
)

Get the transaction at the provided index. The returned transaction is not owned and depends on the lifetime of the block.

Parameters
[in]blockNon-null.
[in]transaction_indexThe index of the transaction to be retrieved.
Returns
The transaction.

◆ btck_block_hash_destroy()

BITCOINKERNEL_API void btck_block_hash_destroy ( btck_BlockHash block_hash)

Destroy the block hash.

◆ btck_block_read()

BITCOINKERNEL_API btck_Block * btck_block_read ( const btck_ChainstateManager chainstate_manager,
const btck_BlockTreeEntry block_tree_entry 
)

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

Parameters
[in]chainstate_managerNon-null.
[in]block_tree_entryNon-null.
Returns
The read out block, or null on error.

◆ btck_block_spent_outputs_copy()

BITCOINKERNEL_API btck_BlockSpentOutputs * btck_block_spent_outputs_copy ( const btck_BlockSpentOutputs block_spent_outputs)

Copy a block's spent outputs.

Parameters
[in]block_spent_outputsNon-null.
Returns
The copied block spent outputs.

◆ btck_block_spent_outputs_count()

BITCOINKERNEL_API size_t btck_block_spent_outputs_count ( const btck_BlockSpentOutputs block_spent_outputs)

Returns the number of transaction spent outputs whose data is contained in block spent outputs.

Parameters
[in]block_spent_outputsNon-null.
Returns
The number of transaction spent outputs data in the block spent outputs.

◆ btck_block_spent_outputs_destroy()

BITCOINKERNEL_API void btck_block_spent_outputs_destroy ( btck_BlockSpentOutputs block_spent_outputs)

Destroy the block spent outputs.

◆ btck_block_spent_outputs_get_transaction_spent_outputs_at()

BITCOINKERNEL_API const btck_TransactionSpentOutputs * btck_block_spent_outputs_get_transaction_spent_outputs_at ( const btck_BlockSpentOutputs block_spent_outputs,
size_t  transaction_spent_outputs_index 
)

Returns a transaction spent outputs contained in the block spent outputs at a certain index. The returned pointer is unowned and only valid for the lifetime of block_spent_outputs.

Parameters
[in]block_spent_outputsNon-null.
[in]transaction_spent_outputs_indexThe index of the transaction spent outputs within the block spent outputs.
Returns
A transaction spent outputs pointer.

◆ btck_block_spent_outputs_read()

BITCOINKERNEL_API btck_BlockSpentOutputs * btck_block_spent_outputs_read ( const btck_ChainstateManager chainstate_manager,
const btck_BlockTreeEntry block_tree_entry 
)

Reads the block spent coins data the passed in block tree entry points to from disk and returns it.

Parameters
[in]chainstate_managerNon-null.
[in]block_tree_entryNon-null.
Returns
The read out block spent outputs, or null on error.

◆ btck_block_to_bytes()

BITCOINKERNEL_API int btck_block_to_bytes ( const btck_Block block,
btck_WriteBytes  writer,
void *  user_data 
)

◆ btck_block_tree_entry_destroy()

BITCOINKERNEL_API void btck_block_tree_entry_destroy ( btck_BlockTreeEntry block_tree_entry)

Destroy the block tree entry.

◆ btck_block_tree_entry_get_block_hash()

BITCOINKERNEL_API btck_BlockHash * btck_block_tree_entry_get_block_hash ( const btck_BlockTreeEntry block_tree_entry)

Return the block hash associated with a block tree entry.

Parameters
[in]block_tree_entryNon-null.
Returns
The block hash.

◆ btck_block_tree_entry_get_height()

BITCOINKERNEL_API int32_t btck_block_tree_entry_get_height ( const btck_BlockTreeEntry block_tree_entry)

Return the height of a certain block tree entry.

Parameters
[in]block_tree_entryNon-null.
Returns
The block height.

◆ btck_block_tree_entry_get_previous()

BITCOINKERNEL_API btck_BlockTreeEntry * btck_block_tree_entry_get_previous ( const btck_BlockTreeEntry block_tree_entry)

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

Parameters
[in]block_tree_entryNon-null.
Returns
The previous block tree entry, or null on error or if the current block tree entry is the genesis block.

◆ btck_block_validation_state_get_block_validation_result()

BITCOINKERNEL_API btck_BlockValidationResult btck_block_validation_state_get_block_validation_result ( const btck_BlockValidationState block_validation_state)

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

◆ btck_block_validation_state_get_validation_mode()

BITCOINKERNEL_API btck_ValidationMode btck_block_validation_state_get_validation_mode ( const btck_BlockValidationState block_validation_state)

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

◆ btck_chain_contains()

BITCOINKERNEL_API int btck_chain_contains ( const btck_Chain chain,
const btck_BlockTreeEntry block_tree_entry 
)

Return true if the passed in chain contains the block tree entry.

Parameters
[in]chainNon-null.
[in]block_tree_entryNon-null.
Returns
1 if the block_tree_entry is in the chain, 0 otherwise.

◆ btck_chain_destroy()

BITCOINKERNEL_API void btck_chain_destroy ( btck_Chain chain)

Destroy the chain.

◆ btck_chain_get_by_height()

BITCOINKERNEL_API btck_BlockTreeEntry * btck_chain_get_by_height ( const btck_Chain chain,
int  block_height 
)

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

Parameters
[in]chainNon-null.
[in]block_heightHeight in the chain of the to be retrieved block tree entry.
Returns
The block tree entry at a certain height in the currently active chain.

◆ btck_chain_get_genesis()

BITCOINKERNEL_API btck_BlockTreeEntry * btck_chain_get_genesis ( const btck_Chain chain)

◆ btck_chain_get_tip()

BITCOINKERNEL_API btck_BlockTreeEntry * btck_chain_get_tip ( const btck_Chain chain)

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

Parameters
[in]chainNon-null.
Returns
The block tree entry of the current tip, or null if the chain is empty.

◆ btck_chain_parameters_copy()

BITCOINKERNEL_API btck_ChainParameters * btck_chain_parameters_copy ( const btck_ChainParameters chain_parameters)

Copy the chain parameters.

◆ btck_chain_parameters_create()

BITCOINKERNEL_API btck_ChainParameters * btck_chain_parameters_create ( const btck_ChainType  chain_type)

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

Parameters
[in]chain_typeControls the chain parameters type created.
Returns
An allocated chain parameters opaque struct.

◆ btck_chain_parameters_destroy()

BITCOINKERNEL_API void btck_chain_parameters_destroy ( btck_ChainParameters chain_parameters)

Destroy the chain parameters.

◆ btck_chainstate_manager_create()

BITCOINKERNEL_API btck_ChainstateManager * btck_chainstate_manager_create ( const btck_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.

Parameters
[in]chainstate_manager_optionsNon-null, created by btck_chainstate_manager_options_create.
Returns
The allocated chainstate manager, or null on error.

◆ btck_chainstate_manager_destroy()

BITCOINKERNEL_API void btck_chainstate_manager_destroy ( btck_ChainstateManager chainstate_manager)

Destroy the chainstate manager.

◆ btck_chainstate_manager_get_active_chain()

BITCOINKERNEL_API int BITCOINKERNEL_API const btck_Chain * btck_chainstate_manager_get_active_chain ( const btck_ChainstateManager chainstate_manager)

Returns the best known currently active chain. Its lifetime is dependent on the chainstate manager and state transitions within the chainstate manager, e.g. when processing blocks, will also change the chain. Data retrieved from this chain is only consistent up to the point when new data is processed in the chainstate manager. It is the user's responsibility to guard against these inconsistencies.

Parameters
[in]chainstate_managerNon-null.
Returns
The chain.

◆ btck_chainstate_manager_get_block_tree_entry_by_hash()

BITCOINKERNEL_API btck_BlockTreeEntry * btck_chainstate_manager_get_block_tree_entry_by_hash ( const btck_ChainstateManager chainstate_manager,
const btck_BlockHash block_hash 
)

Retrieve a block tree entry by its block hash.

Parameters
[in]chainstate_managerNon-null.
[in]block_hashNon-null.
Returns
The block tree entry of the block with the passed in hash, or null if the block hash is not found.

◆ btck_chainstate_manager_import_blocks()

BITCOINKERNEL_API int btck_chainstate_manager_import_blocks ( btck_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 btck_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]chainstate_managerNon-null.
[in]block_file_pathsNullable, array of block files described by their full filesystem paths.
[in]block_file_paths_lenLength of the block_file_paths array.
Returns
0 if the import blocks call was completed successfully, non-zero otherwise.

◆ btck_chainstate_manager_options_create()

BITCOINKERNEL_API btck_ChainstateManagerOptions * btck_chainstate_manager_options_create ( const btck_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]contextNon-null, the created options and through it the chainstate manager will associate with this kernel context for the duration of their lifetimes.
[in]data_directoryNon-null, path string of the directory containing the chainstate data. If the directory does not exist yet, it will be created.
[in]blocks_directoryNon-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.

◆ btck_chainstate_manager_options_destroy()

BITCOINKERNEL_API void btck_chainstate_manager_options_destroy ( btck_ChainstateManagerOptions chainstate_manager_options)

Destroy the chainstate manager options.

◆ btck_chainstate_manager_options_set_block_tree_db_in_memory()

BITCOINKERNEL_API void btck_chainstate_manager_options_set_block_tree_db_in_memory ( btck_ChainstateManagerOptions chainstate_manager_options,
int  block_tree_db_in_memory 
)

Sets block tree db in memory in the options.

Parameters
[in]chainstate_manager_optionsNon-null, created by btck_chainstate_manager_options_create.
[in]block_tree_db_in_memorySet block tree db in memory.

◆ btck_chainstate_manager_options_set_chainstate_db_in_memory()

BITCOINKERNEL_API void btck_chainstate_manager_options_set_chainstate_db_in_memory ( btck_ChainstateManagerOptions chainstate_manager_options,
int  chainstate_db_in_memory 
)

Sets chainstate db in memory in the options.

Parameters
[in]chainstate_manager_optionsNon-null, created by btck_chainstate_manager_options_create.
[in]chainstate_db_in_memorySet chainstate db in memory.

◆ btck_chainstate_manager_options_set_wipe_dbs()

BITCOINKERNEL_API int btck_chainstate_manager_options_set_wipe_dbs ( btck_ChainstateManagerOptions chainstate_manager_options,
int  wipe_block_tree_db,
int  wipe_chainstate_db 
)

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

Parameters
[in]chainstate_manager_optionsNon-null, created by btck_chainstate_manager_options_create.
[in]wipe_block_tree_dbSet wipe block tree db. Should only be 1 if wipe_chainstate_db is 1 too.
[in]wipe_chainstate_dbSet wipe chainstate db.
Returns
0 if the set was successful, non-zero if the set failed.

◆ btck_chainstate_manager_options_set_worker_threads_num()

BITCOINKERNEL_API void btck_chainstate_manager_options_set_worker_threads_num ( btck_ChainstateManagerOptions chainstate_manager_options,
int  worker_threads 
)

Set the number of available worker threads used during validation.

Parameters
[in]chainstate_manager_optionsNon-null, options to be set.
[in]worker_threadsThe 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.

◆ btck_chainstate_manager_process_block()

BITCOINKERNEL_API int btck_chainstate_manager_process_block ( btck_ChainstateManager chainstate_manager,
const btck_Block block,
int *  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]chainstate_managerNon-null.
[in]blockNon-null, block to be validated.
[out]new_blockNullable, will be set to 1 if this block was not processed before.
Returns
0 if processing the block was successful. Will also return 0 for valid, but duplicate blocks.

◆ btck_coin_confirmation_height()

BITCOINKERNEL_API uint32_t btck_coin_confirmation_height ( const btck_Coin coin)

Returns the height of the block that contains the coin's prevout.

Parameters
[in]coinNon-null.
Returns
The block height of the coin.

◆ btck_coin_copy()

BITCOINKERNEL_API btck_Coin * btck_coin_copy ( const btck_Coin coin)

Copy a coin.

Parameters
[in]coinNon-null.
Returns
The copied coin.

◆ btck_coin_destroy()

BITCOINKERNEL_API void btck_coin_destroy ( btck_Coin coin)

Destroy the coin.

◆ btck_coin_get_output()

BITCOINKERNEL_API const btck_TransactionOutput * btck_coin_get_output ( const btck_Coin coin)

Return the transaction output of a coin. The returned pointer is unowned and only valid for the lifetime of the coin.

Parameters
[in]coinNon-null.
Returns
A transaction output pointer.

◆ btck_coin_is_coinbase()

BITCOINKERNEL_API int btck_coin_is_coinbase ( const btck_Coin coin)

Returns whether the containing transaction was a coinbase.

Parameters
[in]coinNon-null.
Returns
1 if the coin is a coinbase coin, 0 otherwise.

◆ btck_context_copy()

BITCOINKERNEL_API btck_Context * btck_context_copy ( const btck_Context context)

Copy the context.

◆ btck_context_create()

BITCOINKERNEL_API btck_Context * btck_context_create ( const btck_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_optionsNullable, created by btck_context_options_create.
Returns
The allocated context, or null on error.

◆ btck_context_destroy()

BITCOINKERNEL_API void btck_context_destroy ( btck_Context context)

Destroy the context.

◆ btck_context_interrupt()

BITCOINKERNEL_API int btck_context_interrupt ( btck_Context context)

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

Parameters
[in]contextNon-null.
Returns
0 if the interrupt was successfully, non-zero otherwise.

◆ btck_context_options_create()

BITCOINKERNEL_API btck_ContextOptions * btck_context_options_create ( )

Creates an empty context options.

◆ btck_context_options_destroy()

BITCOINKERNEL_API void btck_context_options_destroy ( btck_ContextOptions context_options)

Destroy the context options.

◆ btck_context_options_set_chainparams()

BITCOINKERNEL_API void btck_context_options_set_chainparams ( btck_ContextOptions context_options,
const btck_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_optionsNon-null, previously created by btck_context_options_create.
[in]chain_parametersIs set to the context options.

◆ btck_context_options_set_notifications()

BITCOINKERNEL_API void btck_context_options_set_notifications ( btck_ContextOptions context_options,
btck_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_optionsNon-null, previously created by btck_context_options_create.
[in]notificationsIs set to the context options.

◆ btck_context_options_set_validation_interface()

BITCOINKERNEL_API void btck_context_options_set_validation_interface ( btck_ContextOptions context_options,
btck_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_optionsNon-null, previously created with btck_context_options_create.
[in]validation_interface_callbacksThe callbacks used for passing validation information to the user.

◆ btck_logging_connection_create()

BITCOINKERNEL_API btck_LoggingConnection * btck_logging_connection_create ( btck_LogCallback  log_callback,
void *  user_data,
btck_DestroyCallback  user_data_destroy_callback,
const btck_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]log_callbackNon-null, function through which messages will be logged.
[in]user_dataNullable, holds a user-defined opaque structure. Is passed back to the user through the callback. If the user_data_destroy_callback is also defined it is assumed that ownership of the user_data is passed to the created logging connection.
[in]user_data_destroy_callbackNullable, function for freeing the user data.
[in]optionsSets formatting options of the log messages.
Returns
A new kernel logging connection, or null on error.

◆ btck_logging_connection_destroy()

BITCOINKERNEL_API void btck_logging_connection_destroy ( btck_LoggingConnection logging_connection)

Stop logging and destroy the logging connection.

◆ btck_logging_disable()

BITCOINKERNEL_API void btck_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.

◆ btck_logging_disable_category()

BITCOINKERNEL_API void btck_logging_disable_category ( btck_LogCategory  category)

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

Parameters
[in]categoryIf btck_LOG_ALL is chosen, all categories will be disabled.

◆ btck_logging_enable_category()

BITCOINKERNEL_API void btck_logging_enable_category ( btck_LogCategory  category)

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

Parameters
[in]categoryIf btck_LOG_ALL is chosen, all categories will be enabled.

◆ btck_logging_set_level_category()

BITCOINKERNEL_API void btck_logging_set_level_category ( btck_LogCategory  category,
btck_LogLevel  level 
)

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

Parameters
[in]categoryIf btck_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]levelLog level at which the log category is set.

◆ btck_script_pubkey_copy()

BITCOINKERNEL_API btck_ScriptPubkey * btck_script_pubkey_copy ( const btck_ScriptPubkey script_pubkey)

Copy a script pubkey.

Parameters
[in]script_pubkeyNon-null.
Returns
The copied script pubkey.

◆ btck_script_pubkey_create()

BITCOINKERNEL_API btck_ScriptPubkey * btck_script_pubkey_create ( const void *  script_pubkey,
size_t  script_pubkey_len 
)

Create a script pubkey from serialized data.

Parameters
[in]script_pubkeyNon-null.
[in]script_pubkey_lenLength of the script pubkey data.
Returns
The script pubkey.

◆ btck_script_pubkey_destroy()

BITCOINKERNEL_API void btck_script_pubkey_destroy ( btck_ScriptPubkey script_pubkey)

Destroy the script pubkey.

◆ btck_script_pubkey_to_bytes()

BITCOINKERNEL_API int btck_script_pubkey_to_bytes ( const btck_ScriptPubkey script_pubkey,
btck_WriteBytes  writer,
void *  user_data 
)

◆ btck_script_pubkey_verify()

BITCOINKERNEL_API int btck_script_pubkey_verify ( const btck_ScriptPubkey script_pubkey,
int64_t  amount,
const btck_Transaction tx_to,
const btck_TransactionOutput **  spent_outputs,
size_t  spent_outputs_len,
unsigned int  input_index,
unsigned int  flags,
btck_ScriptVerifyStatus status 
)

Verify if the input at input_index of tx_to spends the script pubkey under the constraints specified by flags. If the btck_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_pubkeyNon-null, script pubkey to be spent.
[in]amountAmount of the script pubkey's associated output. May be zero if the witness flag is not set.
[in]tx_toNon-null, transaction spending the script_pubkey.
[in]spent_outputsNullable if the taproot flag is not set. Points to an array of outputs spent by the transaction.
[in]spent_outputs_lenLength of the spent_outputs array.
[in]input_indexIndex of the input in tx_to spending the script_pubkey.
[in]flagsBitfield of btck_ScriptFlags controlling validation constraints.
[out]statusNullable, will be set to an error code if the operation fails. Should be set to btck_SCRIPT_VERIFY_OK.
Returns
1 if the script is valid, 0 otherwise.

◆ btck_transaction_copy()

BITCOINKERNEL_API btck_Transaction * btck_transaction_copy ( const btck_Transaction transaction)

Copy a transaction. Transactions are reference counted, so this just increments the reference count.

Parameters
[in]transactionNon-null.
Returns
The copied transaction.

◆ btck_transaction_count_inputs()

BITCOINKERNEL_API size_t btck_transaction_count_inputs ( const btck_Transaction transaction)

Get the number of inputs of a transaction.

Parameters
[in]transactionNon-null.
Returns
The number of inputs.

◆ btck_transaction_count_outputs()

BITCOINKERNEL_API size_t btck_transaction_count_outputs ( const btck_Transaction transaction)

Get the number of outputs of a transaction.

Parameters
[in]transactionNon-null.
Returns
The number of outputs.

◆ btck_transaction_create()

BITCOINKERNEL_API btck_Transaction * btck_transaction_create ( const void *  raw_transaction,
size_t  raw_transaction_len 
)

Create a new transaction from the serialized data.

Parameters
[in]raw_transactionNon-null.
[in]raw_transaction_lenLength of the serialized transaction.
Returns
The transaction, or null on error.

◆ btck_transaction_destroy()

BITCOINKERNEL_API void btck_transaction_destroy ( btck_Transaction transaction)

Destroy the transaction.

◆ btck_transaction_get_output_at()

BITCOINKERNEL_API const btck_TransactionOutput * btck_transaction_get_output_at ( const btck_Transaction transaction,
size_t  output_index 
)

Get the transaction outputs at the provided index. The returned transaction output is not owned and depends on the lifetime of the transaction.

Parameters
[in]transactionNon-null.
[in]output_indexThe index of the transaction to be retrieved.
Returns
The transaction output

◆ btck_transaction_output_copy()

BITCOINKERNEL_API btck_TransactionOutput * btck_transaction_output_copy ( const btck_TransactionOutput transaction_output)

Copy a transaction output.

Parameters
[in]transaction_outputNon-null.
Returns
The copied transaction output.

◆ btck_transaction_output_create()

BITCOINKERNEL_API btck_TransactionOutput * btck_transaction_output_create ( const btck_ScriptPubkey script_pubkey,
int64_t  amount 
)

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

Parameters
[in]script_pubkeyNon-null.
[in]amountThe amount associated with the script pubkey for this output.
Returns
The transaction output.

◆ btck_transaction_output_destroy()

BITCOINKERNEL_API void btck_transaction_output_destroy ( btck_TransactionOutput transaction_output)

Destroy the transaction output.

◆ btck_transaction_output_get_amount()

BITCOINKERNEL_API int64_t btck_transaction_output_get_amount ( const btck_TransactionOutput transaction_output)

Get the amount in the output.

Parameters
[in]transaction_outputNon-null.
Returns
The amount.

◆ btck_transaction_output_get_script_pubkey()

BITCOINKERNEL_API const btck_ScriptPubkey * btck_transaction_output_get_script_pubkey ( const btck_TransactionOutput transaction_output)

Get the script pubkey of the output. The returned script pubkey is not owned and depends on the lifetime of the transaction output.

Parameters
[in]transaction_outputNon-null.
Returns
The script pubkey.

◆ btck_transaction_spent_outputs_copy()

BITCOINKERNEL_API btck_TransactionSpentOutputs * btck_transaction_spent_outputs_copy ( const btck_TransactionSpentOutputs transaction_spent_outputs)

Copy a transaction's spent outputs.

Parameters
[in]transaction_spent_outputsNon-null.
Returns
The copied transaction spent outputs.

◆ btck_transaction_spent_outputs_count()

BITCOINKERNEL_API size_t btck_transaction_spent_outputs_count ( const btck_TransactionSpentOutputs transaction_spent_outputs)

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

Parameters
[in]transaction_spent_outputsNon-null
Returns
The number of spent transaction outputs for the transaction.

◆ btck_transaction_spent_outputs_destroy()

BITCOINKERNEL_API void btck_transaction_spent_outputs_destroy ( btck_TransactionSpentOutputs transaction_spent_outputs)

Destroy the transaction spent outputs.

◆ btck_transaction_spent_outputs_get_coin_at()

BITCOINKERNEL_API const btck_Coin * btck_transaction_spent_outputs_get_coin_at ( const btck_TransactionSpentOutputs transaction_spent_outputs,
size_t  coin_index 
)

Returns a coin contained in the transaction spent outputs at a certain index. The returned pointer is unowned and only valid for the lifetime of transaction_spent_outputs.

Parameters
[in]transaction_spent_outputsNon-null.
[in]coin_indexThe index of the to be retrieved coin within the transaction spent outputs.
Returns
A coin pointer.

◆ btck_transaction_to_bytes()

BITCOINKERNEL_API int btck_transaction_to_bytes ( const btck_Transaction transaction,
btck_WriteBytes  writer,
void *  user_data 
)