The C interface to Bitcoin validation components

751/**
752 * @brief Create a script pubkey from serialized data.
753 * @param[in] script_pubkey     Serialized script pubkey.
754 * @param[in] script_pubkey_len Length of the script pubkey data.
755 * @return                      The script pubkey.
756 */
757BITCOINKERNEL_API btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_create(
758    const void* script_pubkey, size_t script_pubkey_len);
759
760/**
761 * @brief Copy a script pubkey.
762 *
763 * @param[in] script_pubkey Non-null.
764 * @return                  The copied script pubkey.
765 */
766BITCOINKERNEL_API btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_copy(
767    const btck_ScriptPubkey* script_pubkey) BITCOINKERNEL_ARG_NONNULL(1);
768
769/**
770 * @brief Verify if the input at input_index of tx_to spends the script pubkey
771 * under the constraints specified by flags. If the
772 * `btck_ScriptVerificationFlags_WITNESS` flag is set in the flags bitfield, the
773 * amount parameter is used. If the taproot flag is set, the precomputed data
774 * must contain the spent outputs.
775 *
776 * @param[in] script_pubkey      Non-null, script pubkey to be spent.
777 * @param[in] amount             Amount of the script pubkey's associated output. May be zero if
778 *                               the witness flag is not set.
779 * @param[in] tx_to              Non-null, transaction spending the script_pubkey.
780 * @param[in] precomputed_txdata Nullable if the taproot flag is not set. Otherwise, precomputed data
781 *                               for tx_to with the spent outputs must be provided.
782 * @param[in] input_index        Index of the input in tx_to spending the script_pubkey.
783 * @param[in] flags              Bitfield of btck_ScriptVerificationFlags controlling validation constraints.
784 * @param[out] status            Nullable, will be set to an error code if the operation fails, or OK otherwise.
785 * @return                       1 if the script is valid, 0 otherwise.
786 */
787BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_verify(
788    const btck_ScriptPubkey* script_pubkey,
789    int64_t amount,
790    const btck_Transaction* tx_to,
791    const btck_PrecomputedTransactionData* precomputed_txdata,
792    unsigned int input_index,
793    btck_ScriptVerificationFlags flags,
794    btck_ScriptVerifyStatus* status) BITCOINKERNEL_ARG_NONNULL(1, 3);
795
796/**
797 * @brief Serializes the script pubkey through the passed in callback to bytes.
798 *
799 * @param[in] script_pubkey Non-null.
800 * @param[in] writer        Non-null, callback to a write bytes function.
801 * @param[in] user_data     Holds a user-defined opaque structure that will be
802 *                          passed back through the writer callback.
803 * @return                  0 on success.
804 */
805BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_to_bytes(
806    const btck_ScriptPubkey* script_pubkey,
807    btck_WriteBytes writer,
808    void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
809
810/**
811 * Destroy the script pubkey.
812 */
813BITCOINKERNEL_API void btck_script_pubkey_destroy(btck_ScriptPubkey* script_pubkey);
814
815///@}
816
817/** @name TransactionOutput
818 * Functions for working with transaction outputs.
819 */
820///@{
821
822/**
823 * @brief Create a transaction output from a script pubkey and an amount.
824 *
825 * @param[in] script_pubkey Non-null.
826 * @param[in] amount        The amount associated with the script pubkey for this output.
827 * @return                  The transaction output.
828 */
829BITCOINKERNEL_API btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_create(
830    const btck_ScriptPubkey* script_pubkey,
831    int64_t amount) BITCOINKERNEL_ARG_NONNULL(1);
832
833/**
834 * @brief Get the script pubkey of the output. The returned
835 * script pubkey is not owned and depends on the lifetime of the
836 * transaction output.
837 *
838 * @param[in] transaction_output Non-null.
839 * @return                       The script pubkey.
840 */
841BITCOINKERNEL_API const btck_ScriptPubkey* btck_transaction_output_get_script_pubkey(
842    const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1);
843
844/**
845 * @brief Get the amount in the output.
846 *
847 * @param[in] transaction_output Non-null.
848 * @return                       The amount.
849 */
850BITCOINKERNEL_API int64_t btck_transaction_output_get_amount(
851    const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1);
852
853/**
854 *  @brief Copy a transaction output.
855 *
856 *  @param[in] transaction_output Non-null.
857 *  @return                       The copied transaction output.
858 */
859BITCOINKERNEL_API btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_output_copy(
860    const btck_TransactionOutput* transaction_output) BITCOINKERNEL_ARG_NONNULL(1);
861
862/**
863 * Destroy the transaction output.
864 */
865BITCOINKERNEL_API void btck_transaction_output_destroy(btck_TransactionOutput* transaction_output);
866
867///@}
868
869/** @name Logging
870 * Logging-related functions.
871 */
872///@{
873
874/**
875 * @brief This disables the global internal logger. No log messages will be
876 * buffered internally anymore once this is called and the buffer is cleared.
877 * This function should only be called once and is not thread or re-entry safe.
878 * Log messages will be buffered until this function is called, or a logging
879 * connection is created. This must not be called while a logging connection
880 * already exists.
881 */
882BITCOINKERNEL_API void btck_logging_disable();
883
884/**
885 * @brief Set some options for the global internal logger. This changes global
886 * settings and will override settings for all existing @ref
887 * btck_LoggingConnection instances.
888 *
889 * @param[in] options Sets formatting options of the log messages.
890 */
891BITCOINKERNEL_API void btck_logging_set_options(btck_LoggingOptions options);
892
893/**
894 * @brief Set the log level of the global internal logger. This does not
895 * enable the selected categories. Use @ref btck_logging_enable_category to
896 * start logging from a specific, or all categories. This changes a global
897 * setting and will override settings for all existing
898 * @ref btck_LoggingConnection instances.
899 *
900 * @param[in] category If btck_LogCategory_ALL is chosen, sets both the global fallback log level
901 *                     used by all categories that don't have a specific level set, and also
902 *                     sets the log level for messages logged with the btck_LogCategory_ALL category itself.
903 *                     For any other category, sets a category-specific log level that overrides
904 *                     the global fallback for that category only.
905
906 * @param[in] level    Log level at which the log category is set.
907 */
908BITCOINKERNEL_API void btck_logging_set_level_category(btck_LogCategory category, btck_LogLevel level);
909
910/**
911 * @brief Enable a specific log category for the global internal logger. This
912 * changes a global setting and will override settings for all existing @ref
913 * btck_LoggingConnection instances.
914 *
915 * @param[in] category If btck_LogCategory_ALL is chosen, all categories will be enabled.
916 */
917BITCOINKERNEL_API void btck_logging_enable_category(btck_LogCategory category);
918
919/**
920 * @brief Disable a specific log category for the global internal logger. This
921 * changes a global setting and will override settings for all existing @ref
922 * btck_LoggingConnection instances.
923 *
924 * @param[in] category If btck_LogCategory_ALL is chosen, all categories will be disabled.
925 */
926BITCOINKERNEL_API void btck_logging_disable_category(btck_LogCategory category);
927
928/**
929 * @brief Start logging messages through the provided callback. Log messages
930 * produced before this function is first called are buffered and on calling this
931 * function are logged immediately.
932 *
933 * @param[in] log_callback               Non-null, function through which messages will be logged.
934 * @param[in] user_data                  Nullable, holds a user-defined opaque structure. Is passed back
935 *                                       to the user through the callback. If the user_data_destroy_callback
936 *                                       is also defined it is assumed that ownership of the user_data is passed
937 *                                       to the created logging connection.
938 * @param[in] user_data_destroy_callback Nullable, function for freeing the user data.
939 * @return                               A new kernel logging connection, or null on error.
940 */
941BITCOINKERNEL_API btck_LoggingConnection* BITCOINKERNEL_WARN_UNUSED_RESULT btck_logging_connection_create(
942    btck_LogCallback log_callback,
943    void* user_data,
944    btck_DestroyCallback user_data_destroy_callback) BITCOINKERNEL_ARG_NONNULL(1);
945
946/**
947 * Stop logging and destroy the logging connection.
948 */
949BITCOINKERNEL_API void btck_logging_connection_destroy(btck_LoggingConnection* logging_connection);
950
951///@}
952
953/** @name ChainParameters
954 * Functions for working with chain parameters.
955 */
956///@{
957
958/**
959 * @brief Creates a chain parameters struct with default parameters based on the
960 * passed in chain type.
961 *
962 * @param[in] chain_type Controls the chain parameters type created.
963 * @return               An allocated chain parameters opaque struct.
964 */
965BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_create(
966    btck_ChainType chain_type);
967
968/**
969 * @brief Create a signet chain parameters struct with a user-provided
970 * challenge.
971 *
972 * @param[in] challenge     The signet challenge value. Blocks must satisfy it in
973 *                          order to be valid.
974 * @param[in] challenge_len The length of the signet challenge.
975 * @return                  An allocated chain parameters opaque struct.
976 */
977BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_create_signet(
978    const void* challenge, size_t challenge_len);
979
980/**
981 * Copy the chain parameters.
982 */
983BITCOINKERNEL_API btck_ChainParameters* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chain_parameters_copy(
984    const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1);
985
986/**
987 * @brief Get btck_ConsensusParams from btck_ChainParameters. The returned
988 * btck_ConsensusParams pointer is valid only for the lifetime of the
989 * btck_ChainParameters object and must not be destroyed by the caller.
990 *
991 * @param[in] chain_parameters  Non-null.
992 * @return                      The btck_ConsensusParams.
993 */
994BITCOINKERNEL_API const btck_ConsensusParams* btck_chain_parameters_get_consensus_params(
995    const btck_ChainParameters* chain_parameters) BITCOINKERNEL_ARG_NONNULL(1);
996
997/**
998 * Destroy the chain parameters.
999 */
1000BITCOINKERNEL_API void btck_chain_parameters_destroy(btck_ChainParameters* chain_parameters);