The C interface to Bitcoin validation components

1251/**
1252 * Destroy the chainstate manager options.
1253 */
1254BITCOINKERNEL_API void btck_chainstate_manager_options_destroy(btck_ChainstateManagerOptions* chainstate_manager_options);
1255
1256///@}
1257
1258/** @name ChainstateManager
1259 * Functions for chainstate management.
1260 */
1261///@{
1262
1263/**
1264 * @brief Create a chainstate manager. This is the main object for many
1265 * validation tasks as well as for retrieving data from the chain and
1266 * interacting with its chainstate and indexes.
1267 *
1268 * @param[in] chainstate_manager_options Non-null, created by @ref btck_chainstate_manager_options_create.
1269 * @return                               The allocated chainstate manager, or null on error.
1270 */
1271BITCOINKERNEL_API btck_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_create(
1272    const btck_ChainstateManagerOptions* chainstate_manager_options) BITCOINKERNEL_ARG_NONNULL(1);
1273
1274/**
1275 * @brief Get the btck_BlockTreeEntry whose associated btck_BlockHeader has the most
1276 * known cumulative proof of work.
1277 *
1278 * @param[in] chainstate_manager Non-null.
1279 * @return                       The btck_BlockTreeEntry, or null if no block headers have been loaded.
1280 */
1281BITCOINKERNEL_API const btck_BlockTreeEntry* btck_chainstate_manager_get_best_entry(
1282    const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);
1283
1284/**
1285 * @brief Processes and validates the provided btck_BlockHeader.
1286 *
1287 * @param[in] chainstate_manager        Non-null.
1288 * @param[in] header                    Non-null btck_BlockHeader to be validated.
1289 * @return                              The btck_BlockValidationState containing validation result, or null on error.
1290 */
1291BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_process_block_header(
1292    btck_ChainstateManager* chainstate_manager,
1293    const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1, 2);
1294
1295/**
1296 * @brief Triggers the start of a reindex if the wipe options were previously
1297 * set for the chainstate manager. Can also import an array of existing block
1298 * files selected by the user.
1299 *
1300 * @param[in] chainstate_manager        Non-null.
1301 * @param[in] block_file_paths_data     Nullable, array of block files described by their full filesystem paths.
1302 * @param[in] block_file_paths_lens     Nullable, array containing the lengths of each of the paths.
1303 * @param[in] block_file_paths_data_len Length of the block_file_paths_data and block_file_paths_len arrays.
1304 * @return                              0 if the import blocks call was completed successfully, non-zero otherwise.
1305 */
1306BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_import_blocks(
1307    btck_ChainstateManager* chainstate_manager,
1308    const char** block_file_paths_data, size_t* block_file_paths_lens,
1309    size_t block_file_paths_data_len) BITCOINKERNEL_ARG_NONNULL(1);
1310
1311/**
1312 * @brief Process and validate the passed in block with the chainstate
1313 * manager. Processing first does checks on the block, and if these passed,
1314 * saves it to disk. It then validates the block against the utxo set. If it is
1315 * valid, the chain is extended with it. The return value is not indicative of
1316 * the block's validity. Detailed information on the validity of the block can
1317 * be retrieved by registering the `block_checked` callback in the validation
1318 * interface.
1319 *
1320 * @param[in] chainstate_manager Non-null.
1321 * @param[in] block              Non-null, block to be validated.
1322 *
1323 * @param[out] new_block         Nullable, will be set to 1 if this block was not processed before. Note that this means it
1324 *                               might also not be 1 if processing was attempted before, but the block was found invalid
1325 *                               before its data was persisted.
1326 * @return                       0 if processing the block was successful. Will also return 0 for valid, but duplicate blocks.
1327 */
1328BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_process_block(
1329    btck_ChainstateManager* chainstate_manager,
1330    const btck_Block* block,
1331    int* new_block) BITCOINKERNEL_ARG_NONNULL(1, 2, 3);
1332
1333/**
1334 * @brief Returns the best known currently active chain. Its lifetime is
1335 * dependent on the chainstate manager. It can be thought of as a view on a
1336 * vector of block tree entries that form the best chain. The returned chain
1337 * reference always points to the currently active best chain. However, state
1338 * transitions within the chainstate manager (e.g., processing blocks) will
1339 * update the chain's contents. Data retrieved from this chain is only
1340 * consistent up to the point when new data is processed in the chainstate
1341 * manager. It is the user's responsibility to guard against these
1342 * inconsistencies.
1343 *
1344 * @param[in] chainstate_manager Non-null.
1345 * @return                       The chain.
1346 */
1347BITCOINKERNEL_API const btck_Chain* btck_chainstate_manager_get_active_chain(
1348    const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);
1349
1350/**
1351 * @brief Retrieve a block tree entry by its block hash.
1352 *
1353 * @param[in] chainstate_manager Non-null.
1354 * @param[in] block_hash         Non-null.
1355 * @return                       The block tree entry of the block with the passed in hash, or null if
1356 *                               the block hash is not found.
1357 */
1358BITCOINKERNEL_API const btck_BlockTreeEntry* btck_chainstate_manager_get_block_tree_entry_by_hash(
1359    const btck_ChainstateManager* chainstate_manager,
1360    const btck_BlockHash* block_hash) BITCOINKERNEL_ARG_NONNULL(1, 2);
1361
1362/**
1363 * Destroy the chainstate manager.
1364 */
1365BITCOINKERNEL_API void btck_chainstate_manager_destroy(btck_ChainstateManager* chainstate_manager);
1366
1367///@}
1368
1369/** @name Block
1370 * Functions for working with blocks.
1371 */
1372///@{
1373
1374/**
1375 * @brief Reads the block the passed in block tree entry points to from disk and
1376 * returns it.
1377 *
1378 * @param[in] chainstate_manager Non-null.
1379 * @param[in] block_tree_entry   Non-null.
1380 * @return                       The read out block, or null on error.
1381 */
1382BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_read(
1383    const btck_ChainstateManager* chainstate_manager,
1384    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2);
1385
1386/**
1387 * @brief Parse a serialized raw block into a new block object.
1388 *
1389 * @param[in] raw_block     Serialized block.
1390 * @param[in] raw_block_len Length of the serialized block.
1391 * @return                  The allocated block, or null on error.
1392 */
1393BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_create(
1394    const void* raw_block, size_t raw_block_len);
1395
1396/**
1397 * @brief Copy a block. Blocks are reference counted, so this just increments
1398 * the reference count.
1399 *
1400 * @param[in] block Non-null.
1401 * @return          The copied block.
1402 */
1403BITCOINKERNEL_API btck_Block* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_copy(
1404    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
1405
1406/** Bitflags to control context-free block checks (optional). */
1407typedef uint32_t btck_BlockCheckFlags;
1408#define btck_BlockCheckFlags_BASE   ((btck_BlockCheckFlags)0)                                                        //!< run the base context-free block checks only
1409#define btck_BlockCheckFlags_POW    ((btck_BlockCheckFlags)(1U << 0))                                                //!< run CheckProofOfWork via CheckBlockHeader
1410#define btck_BlockCheckFlags_MERKLE ((btck_BlockCheckFlags)(1U << 1))                                                //!< verify merkle root (and mutation detection)
1411#define btck_BlockCheckFlags_ALL    ((btck_BlockCheckFlags)(btck_BlockCheckFlags_POW | btck_BlockCheckFlags_MERKLE)) //!< enable all optional context-free block checks
1412
1413/**
1414 * @brief Perform context-free validation checks on a btck_Block.
1415 *
1416 * Runs the base context-free block checks (size limits, coinbase structure,
1417 * transaction checks, and sigop limits) using the supplied
1418 * btck_ConsensusParams. The proof-of-work and merkle-root checks are optional
1419 * and can be toggled via @p flags. Note that this does not include any
1420 * transaction script, timestamps, order, or other checks that may require more
1421 * context.
1422 *
1423 * @param[in]     block             Non-null, btck_Block to validate.
1424 * @param[in]     consensus_params  Non-null, btck_ConsensusParams for validation.
1425 * @param[in]     flags             Bitmask of btck_BlockCheckFlags controlling the
1426 *                                  optional POW and merkle-root checks. Use
1427 *                                  btck_BlockCheckFlags_BASE to run only the base
1428 *                                  checks.
1429 * @param[out]    validation_state  Non-null, previously created with
1430 *                                  btck_block_validation_state_create.
1431 *                                  Overwritten in-place with the validation
1432 *                                  result.
1433 * @return                          1 if the btck_Block passed the checks, 0 otherwise.
1434 */
1435BITCOINKERNEL_API int btck_block_check(
1436    const btck_Block* block,
1437    const btck_ConsensusParams* consensus_params,
1438    btck_BlockCheckFlags flags,
1439    btck_BlockValidationState* validation_state) BITCOINKERNEL_ARG_NONNULL(1, 2, 4);
1440
1441/**
1442 * @brief Count the number of transactions contained in a block.
1443 *
1444 * @param[in] block Non-null.
1445 * @return          The number of transactions in the block.
1446 */
1447BITCOINKERNEL_API size_t btck_block_count_transactions(
1448    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
1449
1450/**
1451 * @brief Get the transaction at the provided index. The returned transaction
1452 * is not owned and depends on the lifetime of the block.
1453 *
1454 * @param[in] block             Non-null.
1455 * @param[in] transaction_index The index of the transaction to be retrieved.
1456 * @return                      The transaction.
1457 */
1458BITCOINKERNEL_API const btck_Transaction* btck_block_get_transaction_at(
1459    const btck_Block* block, size_t transaction_index) BITCOINKERNEL_ARG_NONNULL(1);
1460
1461/**
1462 * @brief Get the btck_BlockHeader from the block.
1463 *
1464 * Creates a new btck_BlockHeader object from the block's header data.
1465 *
1466 * @param[in] block Non-null btck_Block
1467 * @return          btck_BlockHeader.
1468 */
1469BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_header(
1470    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
1471
1472/**
1473 * @brief Calculate and return the hash of a block.
1474 *
1475 * @param[in] block Non-null.
1476 * @return    The block hash.
1477 */
1478BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_hash(
1479    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
1480
1481/**
1482 * @brief Serializes the block through the passed in callback to bytes.
1483 * This is consensus serialization that is also used for the P2P network.
1484 *
1485 * @param[in] block     Non-null.
1486 * @param[in] writer    Non-null, callback to a write bytes function.
1487 * @param[in] user_data Holds a user-defined opaque structure that will be
1488 *                      passed back through the writer callback.
1489 * @return              0 on success.
1490 */
1491BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_to_bytes(
1492    const btck_Block* block,
1493    btck_WriteBytes writer,
1494    void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
1495
1496/**
1497 * Destroy the block.
1498 */
1499BITCOINKERNEL_API void btck_block_destroy(btck_Block* block);
1500