The C interface to Bitcoin validation components

501
502/**
503 * Options controlling the format of log messages.
504 *
505 * Set fields as non-zero to indicate true.
506 */
507typedef struct {
508    int log_timestamps;               //!< Prepend a timestamp to log messages.
509    int log_time_micros;              //!< Log timestamps in microsecond precision.
510    int log_threadnames;              //!< Prepend the name of the thread to log messages.
511    int log_sourcelocations;          //!< Prepend the source location to log messages.
512    int always_print_category_levels; //!< Prepend the log category and level to log messages.
513} btck_LoggingOptions;
514
515/**
516 * A collection of status codes that may be issued by the script verify function.
517 */
518typedef uint8_t btck_ScriptVerifyStatus;
519#define btck_ScriptVerifyStatus_OK ((btck_ScriptVerifyStatus)(0))
520#define btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION ((btck_ScriptVerifyStatus)(1)) //!< The flags were combined in an invalid way.
521#define btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED ((btck_ScriptVerifyStatus)(2))    //!< The taproot flag was set, so valid spent_outputs have to be provided.
522
523/**
524 * Script verification flags that may be composed with each other.
525 */
526typedef uint32_t btck_ScriptVerificationFlags;
527#define btck_ScriptVerificationFlags_NONE ((btck_ScriptVerificationFlags)(0))
528#define btck_ScriptVerificationFlags_P2SH ((btck_ScriptVerificationFlags)(1U << 0))                 //!< evaluate P2SH (BIP16) subscripts
529#define btck_ScriptVerificationFlags_DERSIG ((btck_ScriptVerificationFlags)(1U << 2))               //!< enforce strict DER (BIP66) compliance
530#define btck_ScriptVerificationFlags_NULLDUMMY ((btck_ScriptVerificationFlags)(1U << 4))            //!< enforce NULLDUMMY (BIP147)
531#define btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY ((btck_ScriptVerificationFlags)(1U << 9))  //!< enable CHECKLOCKTIMEVERIFY (BIP65)
532#define btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY ((btck_ScriptVerificationFlags)(1U << 10)) //!< enable CHECKSEQUENCEVERIFY (BIP112)
533#define btck_ScriptVerificationFlags_WITNESS ((btck_ScriptVerificationFlags)(1U << 11))             //!< enable WITNESS (BIP141)
534#define btck_ScriptVerificationFlags_TAPROOT ((btck_ScriptVerificationFlags)(1U << 17))             //!< enable TAPROOT (BIPs 341 & 342)
535#define btck_ScriptVerificationFlags_ALL ((btck_ScriptVerificationFlags)(btck_ScriptVerificationFlags_P2SH |                \
536                                                                         btck_ScriptVerificationFlags_DERSIG |              \
537                                                                         btck_ScriptVerificationFlags_NULLDUMMY |           \
538                                                                         btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY | \
539                                                                         btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY | \
540                                                                         btck_ScriptVerificationFlags_WITNESS |             \
541                                                                         btck_ScriptVerificationFlags_TAPROOT))
542
543typedef uint8_t btck_ChainType;
544#define btck_ChainType_MAINNET ((btck_ChainType)(0))
545#define btck_ChainType_TESTNET ((btck_ChainType)(1))
546#define btck_ChainType_TESTNET_4 ((btck_ChainType)(2))
547#define btck_ChainType_SIGNET ((btck_ChainType)(3))
548#define btck_ChainType_REGTEST ((btck_ChainType)(4))
549
550/** @name TxValidationState
551 *  Introspection for transaction validation state.
552 */
553///@{
554
555/**
556 * Create a new btck_TxValidationState.
557 */
558BITCOINKERNEL_API btck_TxValidationState* BITCOINKERNEL_WARN_UNUSED_RESULT btck_tx_validation_state_create();
559
560/**
561 * Returns the validation mode from an opaque btck_TxValidationState pointer.
562 */
563BITCOINKERNEL_API btck_ValidationMode btck_tx_validation_state_get_validation_mode(
564    const btck_TxValidationState* state) BITCOINKERNEL_ARG_NONNULL(1);
565
566/**
567 * Returns the validation result from an opaque btck_TxValidationState pointer.
568 *
569 * btck_transaction_check currently produces only btck_TxValidationResult_UNSET
570 * for valid transactions and btck_TxValidationResult_CONSENSUS for invalid
571 * ones. Other values remain exposed for forward compatibility with higher-level
572 * validation entry points.
573 */
574BITCOINKERNEL_API btck_TxValidationResult btck_tx_validation_state_get_tx_validation_result(
575    const btck_TxValidationState* state) BITCOINKERNEL_ARG_NONNULL(1);
576
577/**
578 * Destroy the btck_TxValidationState.
579 */
580BITCOINKERNEL_API void btck_tx_validation_state_destroy(btck_TxValidationState* state);
581
582///@}
583
584/** @name Transaction
585 * Functions for working with transactions.
586 */
587///@{
588
589/**
590 * @brief Create a new transaction from the serialized data.
591 *
592 * @param[in] raw_transaction     Serialized transaction.
593 * @param[in] raw_transaction_len Length of the serialized transaction.
594 * @return                        The transaction, or null on error.
595 */
596BITCOINKERNEL_API btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_create(
597    const void* raw_transaction, size_t raw_transaction_len);
598
599/**
600 * @brief Copy a transaction. Transactions are reference counted, so this just
601 * increments the reference count.
602 *
603 * @param[in] transaction Non-null.
604 * @return                The copied transaction.
605 */
606BITCOINKERNEL_API btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_copy(
607    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
608
609/**
610 * @brief Serializes the transaction through the passed in callback to bytes.
611 * This is consensus serialization that is also used for the P2P network.
612 *
613 * @param[in] transaction Non-null.
614 * @param[in] writer      Non-null, callback to a write bytes function.
615 * @param[in] user_data   Holds a user-defined opaque structure that will be
616 *                        passed back through the writer callback.
617 * @return                0 on success.
618 */
619BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_to_bytes(
620    const btck_Transaction* transaction,
621    btck_WriteBytes writer,
622    void* user_data) BITCOINKERNEL_ARG_NONNULL(1, 2);
623
624/**
625 * @brief Get the number of outputs of a transaction.
626 *
627 * @param[in] transaction Non-null.
628 * @return                The number of outputs.
629 */
630BITCOINKERNEL_API size_t btck_transaction_count_outputs(
631    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
632
633/**
634 * @brief Get the transaction outputs at the provided index. The returned
635 * transaction output is not owned and depends on the lifetime of the
636 * transaction.
637 *
638 * @param[in] transaction  Non-null.
639 * @param[in] output_index The index of the transaction output to be retrieved.
640 * @return                 The transaction output
641 */
642BITCOINKERNEL_API const btck_TransactionOutput* btck_transaction_get_output_at(
643    const btck_Transaction* transaction, size_t output_index) BITCOINKERNEL_ARG_NONNULL(1);
644
645/**
646 * @brief Get the transaction input at the provided index. The returned
647 * transaction input is not owned and depends on the lifetime of the
648 * transaction.
649 *
650 * @param[in] transaction Non-null.
651 * @param[in] input_index The index of the transaction input to be retrieved.
652 * @return                 The transaction input
653 */
654BITCOINKERNEL_API const btck_TransactionInput* btck_transaction_get_input_at(
655    const btck_Transaction* transaction, size_t input_index) BITCOINKERNEL_ARG_NONNULL(1);
656
657/**
658 * @brief Get the number of inputs of a transaction.
659 *
660 * @param[in] transaction Non-null.
661 * @return                The number of inputs.
662 */
663BITCOINKERNEL_API size_t btck_transaction_count_inputs(
664    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
665
666/**
667 * @brief Get a transaction's nLockTime value.
668 *
669 * @param[in] transaction Non-null.
670 * @return                The nLockTime value.
671 */
672BITCOINKERNEL_API uint32_t btck_transaction_get_locktime(
673    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
674
675/**
676 * @brief Get the txid of a transaction. The returned txid is not owned and
677 * depends on the lifetime of the transaction.
678 *
679 * @param[in] transaction Non-null.
680 * @return                The txid.
681 */
682BITCOINKERNEL_API const btck_Txid* btck_transaction_get_txid(
683    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
684
685/**
686 * @brief Run context-free consensus validation on a btck_Transaction.
687 *
688 * Performs basic structural consensus checks (consensus/tx_check::CheckTransaction)
689 * without requiring blockchain state.
690 *
691 * @param[in]  tx               Non-null, the transaction to validate.
692 * @param[out] validation_state Non-null, previously created with
693 *                              btck_tx_validation_state_create.
694 *                              Overwritten in-place with the validation
695 *                              result.
696 * @return                      1 if valid, 0 if invalid.
697 * @note                        Only btck_TxValidationResult_UNSET and
698 *                              btck_TxValidationResult_CONSENSUS are
699 *                              reachable via this function.
700 */
701BITCOINKERNEL_API int btck_transaction_check(
702    const btck_Transaction* tx,
703    btck_TxValidationState* validation_state) BITCOINKERNEL_ARG_NONNULL(1, 2);
704
705/**
706 * Destroy the transaction.
707 */
708BITCOINKERNEL_API void btck_transaction_destroy(btck_Transaction* transaction);
709
710///@}
711
712/** @name PrecomputedTransactionData
713 * Functions for working with precomputed transaction data.
714 */
715///@{
716
717/**
718 * @brief Create precomputed transaction data for script verification.
719 *
720 * @param[in] tx_to             Non-null.
721 * @param[in] spent_outputs     Nullable for non-taproot verification. Points to an array of
722 *                              outputs spent by the transaction.
723 * @param[in] spent_outputs_len Length of the spent_outputs array.
724 * @return                      The precomputed data, or null on error.
725 */
726BITCOINKERNEL_API btck_PrecomputedTransactionData* BITCOINKERNEL_WARN_UNUSED_RESULT btck_precomputed_transaction_data_create(
727    const btck_Transaction* tx_to,
728    const btck_TransactionOutput** spent_outputs, size_t spent_outputs_len) BITCOINKERNEL_ARG_NONNULL(1);
729
730/**
731 * @brief Copy precomputed transaction data.
732 *
733 * @param[in] precomputed_txdata Non-null.
734 * @return                       The copied precomputed transaction data.
735 */
736BITCOINKERNEL_API btck_PrecomputedTransactionData* BITCOINKERNEL_WARN_UNUSED_RESULT btck_precomputed_transaction_data_copy(
737    const btck_PrecomputedTransactionData* precomputed_txdata) BITCOINKERNEL_ARG_NONNULL(1);
738
739/**
740 * Destroy the precomputed transaction data.
741 */
742BITCOINKERNEL_API void btck_precomputed_transaction_data_destroy(btck_PrecomputedTransactionData* precomputed_txdata);
743
744///@}
745
746/** @name ScriptPubkey
747 * Functions for working with script pubkeys.
748 */
749///@{
750