bitcoinkernel.h

Go to the documentation of this file.

// Copyright (c) 2024-present The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
#ifndef BITCOIN_KERNEL_BITCOINKERNEL_H
#define BITCOIN_KERNEL_BITCOINKERNEL_H
 
#ifndef __cplusplus
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#else
#include <cstddef>
#include <cstdint>
#endif // __cplusplus
 
 
#if !defined(BITCOINKERNEL_GNUC_PREREQ)
#if defined(__GNUC__) && defined(__GNUC_MINOR__)
#define BITCOINKERNEL_GNUC_PREREQ(_maj, _min) \
    ((__GNUC__ << 16) + __GNUC_MINOR__ >= ((_maj) << 16) + (_min))
#else
#define BITCOINKERNEL_GNUC_PREREQ(_maj, _min) 0
#endif
#endif
 
/* Warning attributes */
#if defined(__GNUC__) && BITCOINKERNEL_GNUC_PREREQ(3, 4)
#define BITCOINKERNEL_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
#else
#define BITCOINKERNEL_WARN_UNUSED_RESULT
#endif
#if !defined(BITCOINKERNEL_BUILD) && defined(__GNUC__) && BITCOINKERNEL_GNUC_PREREQ(3, 4)
#define BITCOINKERNEL_ARG_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__)))
#else
#define BITCOINKERNEL_ARG_NONNULL(_x)
#endif
 
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
 
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_BlockManagerOptions kernel_BlockManagerOptions;
 
typedef struct kernel_ChainstateManager kernel_ChainstateManager;
 
typedef struct kernel_ChainstateLoadOptions kernel_ChainstateLoadOptions;
 
typedef struct kernel_Block kernel_Block;
 
typedef struct kernel_BlockPointer kernel_BlockPointer;
 
typedef struct kernel_BlockValidationState kernel_BlockValidationState;
 
typedef struct kernel_ValidationInterface kernel_ValidationInterface;
 
typedef struct kernel_BlockUndo kernel_BlockUndo;
 
typedef enum {
    kernel_INIT_REINDEX,
    kernel_INIT_DOWNLOAD,
    kernel_POST_INIT
} kernel_SynchronizationState;
 
typedef enum {
    kernel_UNKNOWN_NEW_RULES_ACTIVATED,
    kernel_LARGE_WORK_INVALID_CHAIN
} kernel_Warning;
 
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);
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);
 
typedef enum {
    kernel_VALIDATION_STATE_VALID = 0,
    kernel_VALIDATION_STATE_INVALID,
    kernel_VALIDATION_STATE_ERROR,
} kernel_ValidationMode;
 
typedef enum {
    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_CHECKPOINT,      
    kernel_BLOCK_HEADER_LOW_WORK, 
} kernel_BlockValidationResult;
 
typedef struct {
    const void* user_data;                                
    kernel_ValidationInterfaceBlockChecked block_checked; 
} kernel_ValidationInterfaceCallbacks;
 
typedef struct {
    const void* user_data;                   
    kernel_NotifyBlockTip block_tip;         
    kernel_NotifyHeaderTip header_tip;       
    kernel_NotifyProgress progress;          
    kernel_NotifyWarningSet warning_set;     
    kernel_NotifyWarningUnset warning_unset; 
    kernel_NotifyFlushError flush_error;     
    kernel_NotifyFatalError fatal_error;     
} kernel_NotificationInterfaceCallbacks;
 
typedef enum {
    kernel_LOG_ALL = 0,
    kernel_LOG_BENCH,
    kernel_LOG_BLOCKSTORAGE,
    kernel_LOG_COINDB,
    kernel_LOG_LEVELDB,
    kernel_LOG_LOCK,
    kernel_LOG_MEMPOOL,
    kernel_LOG_PRUNE,
    kernel_LOG_RAND,
    kernel_LOG_REINDEX,
    kernel_LOG_VALIDATION,
    kernel_LOG_KERNEL,
} kernel_LogCategory;
 
typedef enum {
    kernel_LOG_INFO = 0,
    kernel_LOG_DEBUG,
    kernel_LOG_TRACE,
} kernel_LogLevel;
 
typedef struct {
    bool log_timestamps;               
    bool log_time_micros;              
    bool log_threadnames;              
    bool log_sourcelocations;          
    bool always_print_category_levels; 
} kernel_LoggingOptions;
 
typedef enum {
    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, 
} kernel_ScriptVerifyStatus;
 
typedef enum
{
    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                 = kernel_SCRIPT_FLAGS_VERIFY_P2SH |
                                                     kernel_SCRIPT_FLAGS_VERIFY_DERSIG |
                                                     kernel_SCRIPT_FLAGS_VERIFY_NULLDUMMY |
                                                     kernel_SCRIPT_FLAGS_VERIFY_CHECKLOCKTIMEVERIFY |
                                                     kernel_SCRIPT_FLAGS_VERIFY_CHECKSEQUENCEVERIFY |
                                                     kernel_SCRIPT_FLAGS_VERIFY_WITNESS |
                                                     kernel_SCRIPT_FLAGS_VERIFY_TAPROOT
} kernel_ScriptFlags;
 
typedef enum {
    kernel_CHAIN_TYPE_MAINNET = 0,
    kernel_CHAIN_TYPE_TESTNET,
    kernel_CHAIN_TYPE_TESTNET_4,
    kernel_CHAIN_TYPE_SIGNET,
    kernel_CHAIN_TYPE_REGTEST,
} kernel_ChainType;
 
typedef struct {
    unsigned char hash[32];
} kernel_BlockHash;
 
typedef struct {
    unsigned char* data;
    size_t size;
} kernel_ByteArray;
 
 
kernel_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_transaction_create(
    const unsigned char* raw_transaction, size_t raw_transaction_len
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_transaction_destroy(kernel_Transaction* transaction);
 
 
 
kernel_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_script_pubkey_create(
    const unsigned char* script_pubkey, size_t script_pubkey_len
) BITCOINKERNEL_ARG_NONNULL(1);
 
kernel_ByteArray* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_copy_script_pubkey_data(
        const kernel_ScriptPubkey* script_pubkey
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_script_pubkey_destroy(kernel_ScriptPubkey* script_pubkey);
 
 
 
kernel_TransactionOutput* kernel_transaction_output_create(
    const kernel_ScriptPubkey* script_pubkey,
    int64_t amount
) BITCOINKERNEL_ARG_NONNULL(1);
 
kernel_ScriptPubkey* kernel_copy_script_pubkey_from_output(kernel_TransactionOutput* transaction_output
) BITCOINKERNEL_ARG_NONNULL(1);
 
int64_t kernel_get_transaction_output_amount(kernel_TransactionOutput* transaction_output
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_transaction_output_destroy(kernel_TransactionOutput* transaction_output);
 
 
 
bool BITCOINKERNEL_WARN_UNUSED_RESULT 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
) BITCOINKERNEL_ARG_NONNULL(1, 3);
 
 
 
void kernel_disable_logging();
 
bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_add_log_level_category(const kernel_LogCategory category, kernel_LogLevel level);
 
bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_enable_log_category(const kernel_LogCategory category);
 
bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_disable_log_category(const kernel_LogCategory category);
 
kernel_LoggingConnection* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_logging_connection_create(
    kernel_LogCallback callback,
    const void* user_data,
    const kernel_LoggingOptions options
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_logging_connection_destroy(kernel_LoggingConnection* logging_connection);
 
 
 
const kernel_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chain_parameters_create(
    const kernel_ChainType chain_type);
 
void kernel_chain_parameters_destroy(const kernel_ChainParameters* chain_parameters);
 
 
 
kernel_ContextOptions* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_context_options_create();
 
void kernel_context_options_set_chainparams(
    kernel_ContextOptions* context_options,
    const kernel_ChainParameters* chain_parameters
) BITCOINKERNEL_ARG_NONNULL(1, 2);
 
void kernel_context_options_set_notifications(
    kernel_ContextOptions* context_options,
    kernel_NotificationInterfaceCallbacks notifications
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_context_options_set_validation_interface(
    kernel_ContextOptions* context_options,
    kernel_ValidationInterfaceCallbacks validation_interface_callbacks
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_context_options_destroy(kernel_ContextOptions* context_options);
 
 
 
kernel_Context* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_context_create(
    const kernel_ContextOptions* context_options);
 
bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_context_interrupt(
    kernel_Context* context
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_context_destroy(kernel_Context* context);
 
 
 
kernel_ChainstateManagerOptions* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chainstate_manager_options_create(
    const kernel_Context* context,
    const char* data_directory,
    size_t data_directory_len
) BITCOINKERNEL_ARG_NONNULL(1, 2);
 
void kernel_chainstate_manager_options_set_worker_threads_num(
        kernel_ChainstateManagerOptions* chainstate_manager_options,
        int worker_threads
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_chainstate_manager_options_destroy(kernel_ChainstateManagerOptions* chainstate_manager_options);
 
 
 
kernel_BlockManagerOptions* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_block_manager_options_create(
    const kernel_Context* context,
    const char* blocks_directory,
    size_t blocks_directory_len
) BITCOINKERNEL_ARG_NONNULL(1, 2);
 
void kernel_block_manager_options_destroy(kernel_BlockManagerOptions* block_manager_options);
 
 
 
kernel_ChainstateLoadOptions* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chainstate_load_options_create();
 
void kernel_chainstate_load_options_set_wipe_block_tree_db(
    kernel_ChainstateLoadOptions* chainstate_load_options,
    bool wipe_block_tree_db
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_chainstate_load_options_set_wipe_chainstate_db(
    kernel_ChainstateLoadOptions* chainstate_load_options,
    bool wipe_chainstate_db
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_chainstate_load_options_set_block_tree_db_in_memory(
    kernel_ChainstateLoadOptions* chainstate_load_options,
    bool block_tree_db_in_memory
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_chainstate_load_options_set_chainstate_db_in_memory(
    kernel_ChainstateLoadOptions* chainstate_load_options,
    bool chainstate_db_in_memory
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_chainstate_load_options_destroy(kernel_ChainstateLoadOptions* chainstate_load_options);
 
 
 
kernel_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chainstate_manager_create(
    const kernel_Context* context,
    const kernel_ChainstateManagerOptions* chainstate_manager_options,
    const kernel_BlockManagerOptions* block_manager_options,
    const kernel_ChainstateLoadOptions* chainstate_load_options
) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
 
bool kernel_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
) BITCOINKERNEL_ARG_NONNULL(1, 2);
 
bool BITCOINKERNEL_WARN_UNUSED_RESULT kernel_chainstate_manager_process_block(
    const kernel_Context* context,
    kernel_ChainstateManager* chainstate_manager,
    kernel_Block* block,
    bool* new_block
) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
 
void kernel_chainstate_manager_destroy(kernel_ChainstateManager* chainstate_manager, const kernel_Context* context);
 
 
 
kernel_Block* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_read_block_from_disk(
    const kernel_Context* context,
    kernel_ChainstateManager* chainstate_manager,
    const kernel_BlockIndex* block_index
) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
 
kernel_Block* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_block_create(
    const unsigned char* raw_block, size_t raw_block_len
) BITCOINKERNEL_ARG_NONNULL(1);
 
kernel_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_block_get_hash(
    kernel_Block* block
) BITCOINKERNEL_ARG_NONNULL(1);
 
kernel_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_block_pointer_get_hash(
    const kernel_BlockPointer* block
) BITCOINKERNEL_ARG_NONNULL(1);
 
kernel_ByteArray* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_copy_block_data(
    kernel_Block* block
) BITCOINKERNEL_ARG_NONNULL(1);
 
kernel_ByteArray* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_copy_block_pointer_data(
    const kernel_BlockPointer* block
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_block_destroy(kernel_Block* block);
 
 
 
void kernel_byte_array_destroy(kernel_ByteArray* byte_array);
 
 
 
kernel_ValidationMode kernel_get_validation_mode_from_block_validation_state(
    const kernel_BlockValidationState* block_validation_state
) BITCOINKERNEL_ARG_NONNULL(1);
 
kernel_BlockValidationResult kernel_get_block_validation_result_from_block_validation_state(
    const kernel_BlockValidationState* block_validation_state
) BITCOINKERNEL_ARG_NONNULL(1);
 
 
 
kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_block_index_from_tip(
    const kernel_Context* context,
    kernel_ChainstateManager* chainstate_manager
) BITCOINKERNEL_ARG_NONNULL(1, 2);
 
kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_block_index_from_genesis(
    const kernel_Context* context,
    kernel_ChainstateManager* chainstate_manager
) BITCOINKERNEL_ARG_NONNULL(1, 2);
 
kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_block_index_from_hash(
    const kernel_Context* context,
    kernel_ChainstateManager* chainstate_manager,
    kernel_BlockHash* block_hash
) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
 
kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_block_index_from_height(
    const kernel_Context* context,
    kernel_ChainstateManager* chainstate_manager,
    int block_height
) BITCOINKERNEL_ARG_NONNULL(1, 2);
 
kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_next_block_index(
    const kernel_Context* context,
    kernel_ChainstateManager* chainstate_manager,
    const kernel_BlockIndex* block_index
) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
 
kernel_BlockIndex* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_previous_block_index(
    const kernel_BlockIndex* block_index
) BITCOINKERNEL_ARG_NONNULL(1);
 
int32_t BITCOINKERNEL_WARN_UNUSED_RESULT kernel_block_index_get_height(
    const kernel_BlockIndex* block_index
) BITCOINKERNEL_ARG_NONNULL(1);
 
 
void kernel_block_index_destroy(kernel_BlockIndex* block_index);
 
 
 
kernel_BlockUndo* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_read_block_undo_from_disk(
    const kernel_Context* context,
    kernel_ChainstateManager* chainstate_manager,
    const kernel_BlockIndex* block_index
) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
 
uint64_t BITCOINKERNEL_WARN_UNUSED_RESULT kernel_block_undo_size(
    const kernel_BlockUndo* block_undo
) BITCOINKERNEL_ARG_NONNULL(1);
 
uint64_t BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_transaction_undo_size(
    const kernel_BlockUndo* block_undo,
    uint64_t transaction_undo_index
) BITCOINKERNEL_ARG_NONNULL(1);
 
kernel_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_get_undo_output_by_index(
    const kernel_BlockUndo* block_undo,
    uint64_t transaction_undo_index,
    uint64_t output_index
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_block_undo_destroy(kernel_BlockUndo* block_undo);
 
 
 
kernel_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT kernel_block_index_get_block_hash(
    const kernel_BlockIndex* block_index
) BITCOINKERNEL_ARG_NONNULL(1);
 
void kernel_block_hash_destroy(kernel_BlockHash* block_hash);
 
 
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
 
#endif // BITCOIN_KERNEL_BITCOINKERNEL_H