The C interface to Bitcoin validation components

1001
1002///@}
1003
1004/** @name ContextOptions
1005 * Functions for working with context options.
1006 */
1007///@{
1008
1009/**
1010 * Creates an empty context options.
1011 */
1012BITCOINKERNEL_API btck_ContextOptions* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_options_create();
1013
1014/**
1015 * @brief Sets the chain params for the context options. The context created
1016 * with the options will be configured for these chain parameters.
1017 *
1018 * @param[in] context_options  Non-null, previously created by @ref btck_context_options_create.
1019 * @param[in] chain_parameters Is set to the context options.
1020 */
1021BITCOINKERNEL_API void btck_context_options_set_chainparams(
1022    btck_ContextOptions* context_options,
1023    const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1, 2);
1024
1025/**
1026 * @brief Set the kernel notifications for the context options. The context
1027 * created with the options will be configured with these notifications.
1028 *
1029 * @param[in] context_options Non-null, previously created by @ref btck_context_options_create.
1030 * @param[in] notifications   Is set to the context options.
1031 */
1032BITCOINKERNEL_API void btck_context_options_set_notifications(
1033    btck_ContextOptions* context_options,
1034    btck_NotificationInterfaceCallbacks notifications) BITCOINKERNEL_ARG_NONNULL(1);
1035
1036/**
1037 * @brief Set the validation interface callbacks for the context options. The
1038 * context created with the options will be configured for these validation
1039 * interface callbacks. The callbacks will then be triggered from validation
1040 * events issued by the chainstate manager created from the same context.
1041 *
1042 * @param[in] context_options                Non-null, previously created with btck_context_options_create.
1043 * @param[in] validation_interface_callbacks The callbacks used for passing validation information to the
1044 *                                           user.
1045 */
1046BITCOINKERNEL_API void btck_context_options_set_validation_interface(
1047    btck_ContextOptions* context_options,
1048    btck_ValidationInterfaceCallbacks validation_interface_callbacks) BITCOINKERNEL_ARG_NONNULL(1);
1049
1050/**
1051 * Destroy the context options.
1052 */
1053BITCOINKERNEL_API void btck_context_options_destroy(btck_ContextOptions* context_options);
1054
1055///@}
1056
1057/** @name Context
1058 * Functions for working with contexts.
1059 */
1060///@{
1061
1062/**
1063 * @brief Create a new kernel context. If the options have not been previously
1064 * set, their corresponding fields will be initialized to default values; the
1065 * context will assume mainnet chain parameters and won't attempt to call the
1066 * kernel notification callbacks.
1067 *
1068 * @param[in] context_options Nullable, created by @ref btck_context_options_create.
1069 * @return                    The allocated context, or null on error.
1070 */
1071BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_create(
1072    const btck_ContextOptions* context_options);
1073
1074/**
1075 * Copy the context.
1076 */
1077BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_copy(
1078    const btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);
1079
1080/**
1081 * @brief Interrupt can be used to halt long-running validation functions like
1082 * when reindexing, importing or processing blocks.
1083 *
1084 * @param[in] context  Non-null.
1085 * @return             0 if the interrupt was successful, non-zero otherwise.
1086 */
1087BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_interrupt(
1088    btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);
1089
1090/**
1091 * Destroy the context.
1092 */
1093BITCOINKERNEL_API void btck_context_destroy(btck_Context* context);
1094
1095///@}
1096
1097/** @name BlockTreeEntry
1098 * Functions for working with block tree entries.
1099 */
1100///@{
1101
1102/**
1103 * @brief Returns the previous block tree entry in the tree, or null if the current
1104 * block tree entry is the genesis block.
1105 *
1106 * @param[in] block_tree_entry Non-null.
1107 * @return                     The previous block tree entry, or null on error or if the current block tree entry is the genesis block.
1108 */
1109BITCOINKERNEL_API const btck_BlockTreeEntry* btck_block_tree_entry_get_previous(
1110    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
1111
1112/**
1113 * @brief Return the btck_BlockHeader associated with this entry.
1114 *
1115 * @param[in] block_tree_entry Non-null.
1116 * @return                     btck_BlockHeader.
1117 */
1118BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_block_header(
1119    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
1120
1121/**
1122 * @brief Return the height of a certain block tree entry.
1123 *
1124 * @param[in] block_tree_entry Non-null.
1125 * @return                     The block height.
1126 */
1127BITCOINKERNEL_API int32_t btck_block_tree_entry_get_height(
1128    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
1129
1130/**
1131 * @brief Return the block hash associated with a block tree entry.
1132 *
1133 * @param[in] block_tree_entry Non-null.
1134 * @return                     The block hash.
1135 */
1136BITCOINKERNEL_API const btck_BlockHash* btck_block_tree_entry_get_block_hash(
1137    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
1138
1139/**
1140 * @brief Check if two block tree entries are equal. Two block tree entries are equal when they
1141 * point to the same block.
1142 *
1143 * @param[in] entry1 Non-null.
1144 * @param[in] entry2 Non-null.
1145 * @return           1 if the block tree entries are equal, 0 otherwise.
1146 */
1147BITCOINKERNEL_API int btck_block_tree_entry_equals(
1148    const btck_BlockTreeEntry* entry1, const btck_BlockTreeEntry* entry2) BITCOINKERNEL_ARG_NONNULL(1, 2);
1149
1150/**
1151 * @brief Return the ancestor of a btck_BlockTreeEntry at the given height.
1152 *
1153 * @param[in] block_tree_entry Non-null.
1154 * @param[in] height           The height of the requested ancestor.
1155 * @return                     The ancestor at the given height.
1156 */
1157BITCOINKERNEL_API const btck_BlockTreeEntry* btck_block_tree_entry_get_ancestor(
1158    const btck_BlockTreeEntry* block_tree_entry,
1159    int32_t height) BITCOINKERNEL_ARG_NONNULL(1);
1160
1161///@}
1162
1163/** @name ChainstateManagerOptions
1164 * Functions for working with chainstate manager options.
1165 */
1166///@{
1167
1168/**
1169 * @brief Create options for the chainstate manager.
1170 *
1171 * @param[in] context          Non-null, the created options and through it the chainstate manager will
1172 *                             associate with this kernel context for the duration of their lifetimes.
1173 * @param[in] data_directory   Path string of the directory containing the chainstate data. If the directory
1174 *                             does not exist yet, it will be created.
1175 * @param[in] blocks_directory Path string of the directory containing the block data. If the directory
1176 *                             does not exist yet, it will be created.
1177 * @return                     The allocated chainstate manager options, or null on error (e.g. if a path is invalid).
1178 */
1179BITCOINKERNEL_API btck_ChainstateManagerOptions* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_create(
1180    const btck_Context* context,
1181    const char* data_directory,
1182    size_t data_directory_len,
1183    const char* blocks_directory,
1184    size_t blocks_directory_len) BITCOINKERNEL_ARG_NONNULL(1);
1185
1186/**
1187 * @brief Set the number of available worker threads used during validation.
1188 *
1189 * @param[in] chainstate_manager_options Non-null, options to be set.
1190 * @param[in] worker_threads             The number of worker threads that should be spawned in the thread pool
1191 *                                       used for validation. When set to 0 no parallel verification is done.
1192 *                                       The value range is clamped internally between 0 and 15.
1193 */
1194BITCOINKERNEL_API void btck_chainstate_manager_options_set_worker_threads_num(
1195    btck_ChainstateManagerOptions* chainstate_manager_options,
1196    int worker_threads) BITCOINKERNEL_ARG_NONNULL(1);
1197
1198/**
1199 * @brief Set the total database cache used by the chainstate manager.
1200 *
1201 * The total cache is split internally between the block tree database,
1202 * chainstate database, and in-memory coins cache. If this function is not
1203 * called, the total cache defaults to 450 MiB.
1204 *
1205 * @param[in] chainstate_manager_options Non-null, options to be set.
1206 * @param[in] database_cache_bytes       The total database cache size in bytes. Values below 4 MiB are rejected.
1207 *                                       On 32-bit systems, values above 1 GiB are also rejected.
1208 * @return                               0 if the set was successful, non-zero if the set failed.
1209 */
1210BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_set_database_cache_bytes(
1211    btck_ChainstateManagerOptions* chainstate_manager_options,
1212    uint64_t database_cache_bytes) BITCOINKERNEL_ARG_NONNULL(1);
1213
1214/**
1215 * @brief Sets wipe db in the options. In combination with calling
1216 * @ref btck_chainstate_manager_import_blocks this triggers either a full reindex,
1217 * or a reindex of just the chainstate database.
1218 *
1219 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
1220 * @param[in] wipe_block_tree_db         Set wipe block tree db. Should only be 1 if wipe_chainstate_db is 1 too.
1221 * @param[in] wipe_chainstate_db         Set wipe chainstate db.
1222 * @return                               0 if the set was successful, non-zero if the set failed.
1223 * @note                                 When a wipe is set, the caller must invoke @ref btck_chainstate_manager_import_blocks
1224 *                                       on the resulting chainstate manager before using it for anything else.
1225 */
1226BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_set_wipe_dbs(
1227    btck_ChainstateManagerOptions* chainstate_manager_options,
1228    int wipe_block_tree_db,
1229    int wipe_chainstate_db) BITCOINKERNEL_ARG_NONNULL(1);
1230
1231/**
1232 * @brief Sets block tree db in memory in the options.
1233 *
1234 * @param[in] chainstate_manager_options   Non-null, created by @ref btck_chainstate_manager_options_create.
1235 * @param[in] block_tree_db_in_memory      Set block tree db in memory.
1236 */
1237BITCOINKERNEL_API void btck_chainstate_manager_options_update_block_tree_db_in_memory(
1238    btck_ChainstateManagerOptions* chainstate_manager_options,
1239    int block_tree_db_in_memory) BITCOINKERNEL_ARG_NONNULL(1);
1240
1241/**
1242 * @brief Sets chainstate db in memory in the options.
1243 *
1244 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
1245 * @param[in] chainstate_db_in_memory    Set chainstate db in memory.
1246 */
1247BITCOINKERNEL_API void btck_chainstate_manager_options_update_chainstate_db_in_memory(
1248    btck_ChainstateManagerOptions* chainstate_manager_options,
1249    int chainstate_db_in_memory) BITCOINKERNEL_ARG_NONNULL(1);
1250