The C interface to Bitcoin validation components

1501///@}
1502
1503/** @name BlockValidationState
1504 * Functions for working with block validation states.
1505 */
1506///@{
1507
1508/**
1509 * Create a new btck_BlockValidationState.
1510 */
1511BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_create();
1512
1513/**
1514 * Returns the validation mode from an opaque btck_BlockValidationState pointer.
1515 */
1516BITCOINKERNEL_API btck_ValidationMode btck_block_validation_state_get_validation_mode(
1517    const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);
1518
1519/**
1520 * Returns the validation result from an opaque btck_BlockValidationState pointer.
1521 */
1522BITCOINKERNEL_API btck_BlockValidationResult btck_block_validation_state_get_block_validation_result(
1523    const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);
1524
1525/**
1526 * @brief Copies the btck_BlockValidationState.
1527 *
1528 * @param[in] block_validation_state Non-null.
1529 * @return                           The copied btck_BlockValidationState.
1530 */
1531BITCOINKERNEL_API btck_BlockValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_validation_state_copy(
1532    const btck_BlockValidationState* block_validation_state) BITCOINKERNEL_ARG_NONNULL(1);
1533
1534/**
1535 * Destroy the btck_BlockValidationState.
1536 */
1537BITCOINKERNEL_API void btck_block_validation_state_destroy(
1538    btck_BlockValidationState* block_validation_state);
1539
1540///@}
1541
1542/** @name Chain
1543 * Functions for working with the chain
1544 */
1545///@{
1546
1547/**
1548 * @brief Return the height of the tip of the chain.
1549 *
1550 * @param[in] chain Non-null.
1551 * @return          The current height.
1552 */
1553BITCOINKERNEL_API int32_t btck_chain_get_height(
1554    const btck_Chain* chain) BITCOINKERNEL_ARG_NONNULL(1);
1555
1556/**
1557 * @brief Retrieve a block tree entry by its height in the currently active chain.
1558 * Once retrieved there is no guarantee that it remains in the active chain.
1559 *
1560 * @param[in] chain        Non-null.
1561 * @param[in] block_height Height in the chain of the to be retrieved block tree entry.
1562 * @return                 The block tree entry at a certain height in the currently active chain, or null
1563 *                         if the height is out of bounds.
1564 */
1565BITCOINKERNEL_API const btck_BlockTreeEntry* btck_chain_get_by_height(
1566    const btck_Chain* chain,
1567    int32_t block_height) BITCOINKERNEL_ARG_NONNULL(1);
1568
1569/**
1570 * @brief Return true if the passed in chain contains the block tree entry.
1571 *
1572 * @param[in] chain            Non-null.
1573 * @param[in] block_tree_entry Non-null.
1574 * @return                     1 if the block_tree_entry is in the chain, 0 otherwise.
1575 *
1576 */
1577BITCOINKERNEL_API int btck_chain_contains(
1578    const btck_Chain* chain,
1579    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2);
1580
1581///@}
1582
1583/** @name BlockSpentOutputs
1584 * Functions for working with block spent outputs.
1585 */
1586///@{
1587
1588/**
1589 * @brief Reads the block spent coins data the passed in block tree entry points to from
1590 * disk and returns it.
1591 *
1592 * @param[in] chainstate_manager Non-null.
1593 * @param[in] block_tree_entry   Non-null.
1594 * @return                       The read out block spent outputs, or null on error.
1595 */
1596BITCOINKERNEL_API btck_BlockSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_read(
1597    const btck_ChainstateManager* chainstate_manager,
1598    const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1, 2);
1599
1600/**
1601 * @brief Copy a block's spent outputs.
1602 *
1603 * @param[in] block_spent_outputs Non-null.
1604 * @return                        The copied block spent outputs.
1605 */
1606BITCOINKERNEL_API btck_BlockSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_spent_outputs_copy(
1607    const btck_BlockSpentOutputs* block_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
1608
1609/**
1610 * @brief Returns the number of transaction spent outputs whose data is contained in
1611 * block spent outputs.
1612 *
1613 * @param[in] block_spent_outputs Non-null.
1614 * @return                        The number of transaction spent outputs data in the block spent outputs.
1615 */
1616BITCOINKERNEL_API size_t btck_block_spent_outputs_count(
1617    const btck_BlockSpentOutputs* block_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
1618
1619/**
1620 * @brief Returns a transaction spent outputs contained in the block spent
1621 * outputs at a certain index. The returned pointer is unowned and only valid
1622 * for the lifetime of block_spent_outputs.
1623 *
1624 * @param[in] block_spent_outputs             Non-null.
1625 * @param[in] transaction_spent_outputs_index The index of the transaction spent outputs within the block spent outputs.
1626 * @return                                    A transaction spent outputs pointer.
1627 */
1628BITCOINKERNEL_API const btck_TransactionSpentOutputs* btck_block_spent_outputs_get_transaction_spent_outputs_at(
1629    const btck_BlockSpentOutputs* block_spent_outputs,
1630    size_t transaction_spent_outputs_index) BITCOINKERNEL_ARG_NONNULL(1);
1631
1632/**
1633 * Destroy the block spent outputs.
1634 */
1635BITCOINKERNEL_API void btck_block_spent_outputs_destroy(btck_BlockSpentOutputs* block_spent_outputs);
1636
1637///@}
1638
1639/** @name TransactionSpentOutputs
1640 * Functions for working with the spent coins of a transaction
1641 */
1642///@{
1643
1644/**
1645 * @brief Copy a transaction's spent outputs.
1646 *
1647 * @param[in] transaction_spent_outputs Non-null.
1648 * @return                              The copied transaction spent outputs.
1649 */
1650BITCOINKERNEL_API btck_TransactionSpentOutputs* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_spent_outputs_copy(
1651    const btck_TransactionSpentOutputs* transaction_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
1652
1653/**
1654 * @brief Returns the number of previous transaction outputs contained in the
1655 * transaction spent outputs data.
1656 *
1657 * @param[in] transaction_spent_outputs Non-null
1658 * @return                              The number of spent transaction outputs for the transaction.
1659 */
1660BITCOINKERNEL_API size_t btck_transaction_spent_outputs_count(
1661    const btck_TransactionSpentOutputs* transaction_spent_outputs) BITCOINKERNEL_ARG_NONNULL(1);
1662
1663/**
1664 * @brief Returns a coin contained in the transaction spent outputs at a
1665 * certain index. The returned pointer is unowned and only valid for the
1666 * lifetime of transaction_spent_outputs.
1667 *
1668 * @param[in] transaction_spent_outputs Non-null.
1669 * @param[in] coin_index                The index of the to be retrieved coin within the
1670 *                                      transaction spent outputs.
1671 * @return                              A coin pointer.
1672 */
1673BITCOINKERNEL_API const btck_Coin* btck_transaction_spent_outputs_get_coin_at(
1674    const btck_TransactionSpentOutputs* transaction_spent_outputs,
1675    size_t coin_index) BITCOINKERNEL_ARG_NONNULL(1);
1676
1677/**
1678 * Destroy the transaction spent outputs.
1679 */
1680BITCOINKERNEL_API void btck_transaction_spent_outputs_destroy(btck_TransactionSpentOutputs* transaction_spent_outputs);
1681
1682///@}
1683
1684/** @name Transaction Input
1685 * Functions for working with transaction inputs.
1686 */
1687///@{
1688
1689/**
1690 * @brief Copy a transaction input.
1691 *
1692 * @param[in] transaction_input Non-null.
1693 * @return                      The copied transaction input.
1694 */
1695BITCOINKERNEL_API btck_TransactionInput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_copy(
1696    const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
1697
1698/**
1699 * @brief Get the transaction out point. The returned transaction out point is
1700 * not owned and depends on the lifetime of the transaction.
1701 *
1702 * @param[in] transaction_input Non-null.
1703 * @return                      The transaction out point.
1704 */
1705BITCOINKERNEL_API const btck_TransactionOutPoint* btck_transaction_input_get_out_point(
1706    const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
1707
1708/**
1709 * @brief Get a transaction input's nSequence value.
1710 *
1711 * @param[in] transaction_input Non-null.
1712 * @return                      The nSequence value.
1713 */
1714BITCOINKERNEL_API uint32_t btck_transaction_input_get_sequence(
1715    const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
1716
1717/**
1718 * @brief Get the witness stack of a transaction input. The returned witness
1719 * stack is not owned and depends on the lifetime of the transaction input.
1720 *
1721 * @param[in] transaction_input Non-null.
1722 * @return                      The witness stack.
1723 */
1724BITCOINKERNEL_API const btck_WitnessStack* btck_transaction_input_get_witness_stack(
1725    const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
1726
1727/**
1728 * @brief Serialize the script sig of a transaction input through the passed
1729 * in callback.
1730 *
1731 * @param[in] transaction_input Non-null.
1732 * @param[in] writer            Non-null, function pointer for writing bytes.
1733 * @param[in] user_data         Nullable, passed back through the writer callback.
1734 * @return                      The return value of the writer.
1735 */
1736BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_get_script_sig(
1737    const btck_TransactionInput* transaction_input,
1738    btck_WriteBytes writer,
1739    void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
1740
1741/**
1742 * Destroy the transaction input.
1743 */
1744BITCOINKERNEL_API void btck_transaction_input_destroy(btck_TransactionInput* transaction_input);
1745
1746///@}
1747
1748/** @name Witness Stack
1749 * Functions for working with witness stacks.
1750 */