Repository: bitcoin/bitcoin
File: src/kernel/bitcoinkernel.h (C/C++)

Code before:
BITCOINKERNEL_API void btck_block_destroy(btck_Block* block);

///@}

/** @name BlockValidationState
 * Functions for working with block validation states.
 */
///@{

/**
 * Create a new btck_BlockValidationState.
 */
BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_create();

/**
 * Returns the validation mode from an opaque btck_BlockValidationState pointer.
 */
BITCOINKERNEL_API btck_ValidationMode btck_block_validation_state_get_validation_mode(
    const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * Returns the validation result from an opaque btck_BlockValidationState pointer.
 */
BITCOINKERNEL_API btck_BlockValidationResult btck_block_validation_state_get_block_validation_result(
    const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Copies the btck_BlockValidationState.
 *
 * @param[in] block_validation_state Non-null.
 * @return                           The copied btck_BlockValidationState.
 */
BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_copy(
    const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * Destroy the btck_BlockValidationState.
 */
BITCOINKERNEL_API void btck_block_validation_state_destroy(
    btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);

///@}

/** @name Chain
 * Functions for working with the chain
 */
///@{

/**
 * @brief Return the height of the tip of the chain.
 *

Review comment (suggestion):
Seems `or null on error` should be dropped, since this cannot return null. 

Code after:
 * @return          The number of transactions in the block.
 */
BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_count_transactions(
    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Get the transaction at the provided index. The returned transaction
 * is not owned and depends on the lifetime of the block.
 *
 * @param[in] block             Non-null.
 * @param[in] transaction_index The index of the transaction to be retrieved.
 * @return                      The transaction.
 */
BITCOINKERNEL_API const btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_transaction_at(
    const btck_Block* block, size_t transaction_index) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Get the btck_BlockHeader from the block.
 *
 * Creates a new btck_BlockHeader object from the block's header data.
 *
 * @param[in] block Non-null btck_Block
 * @return          btck_BlockHeader.
 */
BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_header(
    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Calculate and return the hash of a block.
 *
 * @param[in] block Non-null.
 * @return    The block hash.
 */
BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_hash(
    const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Serializes the block through the passed in callback to bytes.
 * This is consensus serialization that is also used for the P2P network.
 *
 * @param[in] block     Non-null.
 * @param[in] writer    Non-null, callback to a write bytes function.
 * @param[in] user_data Holds a user-defined opaque structure that will be
 *                      passed back through the writer callback.
 * @return              0 on success.
 */
BITCOINKERNEL_API int btck_block_to_bytes(
    const btck_Block* block,
    btck_WriteBytes writer,
    void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);