The C interface to Bitcoin validation components

1751///@{
1752
1753/**
1754 * @brief Return the number of items in a witness stack.
1755 *
1756 * @param[in] witness_stack Non-null.
1757 * @return                  The number of witness stack items.
1758 */
1759BITCOINKERNEL_API size_t btck_witness_stack_count_items(
1760    const btck_WitnessStack* witness_stack) BITCOINKERNEL_ARG_NONNULL(1);
1761
1762/**
1763 * @brief Serialize a witness stack item at a given index through the passed in
1764 * callback.
1765 *
1766 * @param[in] witness_stack Non-null.
1767 * @param[in] index         Index of the item in the witness stack.
1768 * @param[in] writer        Non-null, function pointer for writing bytes.
1769 * @param[in] user_data     Nullable, passed back through the writer callback.
1770 * @return                  The return value of the writer.
1771 * @pre                    index < btck_witness_stack_count_items(witness_stack)
1772 */
1773BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_witness_stack_get_item_at(
1774    const btck_WitnessStack* witness_stack,
1775    size_t index,
1776    btck_WriteBytes writer,
1777    void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 3);
1778
1779/**
1780 * @brief Copy a witness stack.
1781 *
1782 * @param[in] witness_stack Non-null.
1783 * @return                  The copied witness stack.
1784 */
1785BITCOINKERNEL_API btck_WitnessStack* BITCOINKERNEL_WARN_UNUSED_RESULT btck_witness_stack_copy(
1786    const btck_WitnessStack* witness_stack) BITCOINKERNEL_ARG_NONNULL(1);
1787
1788/**
1789 * Destroy the witness stack.
1790 */
1791BITCOINKERNEL_API void btck_witness_stack_destroy(btck_WitnessStack* witness_stack);
1792
1793///@}
1794
1795/** @name Transaction Out Point
1796 * Functions for working with transaction out points.
1797 */
1798///@{
1799
1800/**
1801 * @brief Copy a transaction out point.
1802 *
1803 * @param[in] transaction_out_point Non-null.
1804 * @return                          The copied transaction out point.
1805 */
1806BITCOINKERNEL_API btck_TransactionOutPoint* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_copy(
1807    const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
1808
1809/**
1810 * @brief Get the output position from the transaction out point.
1811 *
1812 * @param[in] transaction_out_point Non-null.
1813 * @return                          The output index.
1814 */
1815BITCOINKERNEL_API uint32_t btck_transaction_out_point_get_index(
1816    const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
1817
1818/**
1819 * @brief Get the txid from the transaction out point. The returned txid is
1820 * not owned and depends on the lifetime of the transaction out point.
1821 *
1822 * @param[in] transaction_out_point Non-null.
1823 * @return                          The txid.
1824 */
1825BITCOINKERNEL_API const btck_Txid* btck_transaction_out_point_get_txid(
1826    const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
1827
1828/**
1829 * Destroy the transaction out point.
1830 */
1831BITCOINKERNEL_API void btck_transaction_out_point_destroy(btck_TransactionOutPoint* transaction_out_point);
1832
1833///@}
1834
1835/** @name Txid
1836 * Functions for working with txids.
1837 */
1838///@{
1839
1840/**
1841 * @brief Copy a txid.
1842 *
1843 * @param[in] txid Non-null.
1844 * @return         The copied txid.
1845 */
1846BITCOINKERNEL_API btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_txid_copy(
1847    const btck_Txid* txid) BITCOINKERNEL_ARG_NONNULL(1);
1848
1849/**
1850 * @brief Check if two txids are equal.
1851 *
1852 * @param[in] txid1 Non-null.
1853 * @param[in] txid2 Non-null.
1854 * @return          0 if the txid is not equal.
1855 */
1856BITCOINKERNEL_API int btck_txid_equals(
1857    const btck_Txid* txid1, const btck_Txid* txid2) BITCOINKERNEL_ARG_NONNULL(1, 2);
1858
1859/**
1860 * @brief Serializes the txid to bytes.
1861 *
1862 * @param[in] txid    Non-null.
1863 * @param[out] output The serialized txid.
1864 */
1865BITCOINKERNEL_API void btck_txid_to_bytes(
1866    const btck_Txid* txid, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2);
1867
1868/**
1869 * Destroy the txid.
1870 */
1871BITCOINKERNEL_API void btck_txid_destroy(btck_Txid* txid);
1872
1873///@}
1874
1875/** @name Coin
1876 * Functions for working with coins.
1877 */
1878///@{
1879
1880/**
1881 * @brief Copy a coin.
1882 *
1883 * @param[in] coin Non-null.
1884 * @return         The copied coin.
1885 */
1886BITCOINKERNEL_API btck_Coin* BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_copy(
1887    const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
1888
1889/**
1890 * @brief Returns the block height where the transaction that
1891 * created this coin was included in.
1892 *
1893 * @param[in] coin Non-null.
1894 * @return         The block height of the coin.
1895 */
1896BITCOINKERNEL_API uint32_t btck_coin_confirmation_height(
1897    const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
1898
1899/**
1900 * @brief Returns whether the containing transaction was a coinbase.
1901 *
1902 * @param[in] coin Non-null.
1903 * @return         1 if the coin is a coinbase coin, 0 otherwise.
1904 */
1905BITCOINKERNEL_API int btck_coin_is_coinbase(
1906    const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
1907
1908/**
1909 * @brief Return the transaction output of a coin. The returned pointer is
1910 * unowned and only valid for the lifetime of the coin.
1911 *
1912 * @param[in] coin Non-null.
1913 * @return         A transaction output pointer.
1914 */
1915BITCOINKERNEL_API const btck_TransactionOutput* btck_coin_get_output(
1916    const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
1917
1918/**
1919 * Destroy the coin.
1920 */
1921BITCOINKERNEL_API void btck_coin_destroy(btck_Coin* coin);
1922
1923///@}
1924
1925/** @name BlockHash
1926 * Functions for working with block hashes.
1927 */
1928///@{
1929
1930/**
1931 * @brief Create a block hash from its raw data.
1932 */
1933BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_create(
1934    const unsigned char block_hash[32]) BITCOINKERNEL_ARG_NONNULL(1);
1935
1936/**
1937 * @brief Check if two block hashes are equal.
1938 *
1939 * @param[in] hash1 Non-null.
1940 * @param[in] hash2 Non-null.
1941 * @return          0 if the block hashes are not equal.
1942 */
1943BITCOINKERNEL_API int btck_block_hash_equals(
1944    const btck_BlockHash* hash1, const btck_BlockHash* hash2) BITCOINKERNEL_ARG_NONNULL(1, 2);
1945
1946/**
1947 * @brief Copy a block hash.
1948 *
1949 * @param[in] block_hash Non-null.
1950 * @return               The copied block hash.
1951 */
1952BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_hash_copy(
1953    const btck_BlockHash* block_hash) BITCOINKERNEL_ARG_NONNULL(1);
1954
1955/**
1956 * @brief Serializes the block hash to bytes.
1957 *
1958 * @param[in] block_hash     Non-null.
1959 * @param[in] output         The serialized block hash.
1960 */
1961BITCOINKERNEL_API void btck_block_hash_to_bytes(
1962    const btck_BlockHash* block_hash, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2);
1963
1964/**
1965 * Destroy the block hash.
1966 */
1967BITCOINKERNEL_API void btck_block_hash_destroy(btck_BlockHash* block_hash);
1968
1969///@}
1970
1971/**
1972 * @name Block Header
1973 * Functions for working with block headers.
1974 */
1975///@{
1976
1977/**
1978 * @brief Create a btck_BlockHeader from serialized data.
1979 *
1980 * @param[in] raw_block_header      Non-null, serialized header data (80 bytes)
1981 * @param[in] raw_block_header_len  Length of serialized header (must be 80)
1982 * @return                          btck_BlockHeader, or null on error.
1983 */
1984BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_create(
1985    const void* raw_block_header, size_t raw_block_header_len) BITCOINKERNEL_ARG_NONNULL(1);
1986
1987/**
1988 * @brief Copy a btck_BlockHeader.
1989 *
1990 * @param[in] header    Non-null btck_BlockHeader.
1991 * @return              Copied btck_BlockHeader.
1992 */
1993BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_copy(
1994    const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
1995
1996/**
1997 * @brief Get the btck_BlockHash.
1998 *
1999 * @param[in] header    Non-null header
2000 * @return              btck_BlockHash.