From 0fcbcead269d33a2a22346259535f512a0b100e8 Mon Sep 17 00:00:00 2001
From: Yeji Han <yeji.hvn@gmail.com>
Date: Tue, 3 Mar 2026 13:55:44 +0900
Subject: [PATCH 1/2] Expose ScriptError codes from kernel verification API

---
 .github/workflows/ci.yml                      |   4 +-
 .../bitcoin/src/kernel/bitcoinkernel.cpp      |   8 +-
 .../bitcoin/src/kernel/bitcoinkernel.h        |  73 +++-
 src/core/mod.rs                               |   2 +-
 src/core/verify.rs                            | 374 +++++++++++++++++-
 src/ffi/constants.rs                          |  58 ++-
 src/lib.rs                                    |   7 +-
 tests/test.rs                                 |  85 +++-
 8 files changed, 581 insertions(+), 30 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0c31c320..0f904a1a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -36,7 +36,7 @@ jobs:
         cargo build --all-features
 
     - name: Run tests with MSRV
-      run: cargo test --all-features
+      run: cargo test --all-features -- --test-threads=1
 
   build:
     name: Build and Test
@@ -102,7 +102,7 @@ jobs:
 
     - name: Run tests with Valgrind
       run: |
-        find target/debug/deps -type f -executable -name "test-*" -not -name "*.so" -not -name "*.d" | xargs -I {} valgrind --leak-check=full --show-leak-kinds=all  --errors-for-leak-kinds=definite --suppressions=valgrind.supp --error-exitcode=1 {}
+        find target/debug/deps -type f -executable -name "test-*" -not -name "*.so" -not -name "*.d" | xargs -I {} valgrind --leak-check=full --show-leak-kinds=all  --errors-for-leak-kinds=definite --suppressions=valgrind.supp --error-exitcode=1 {} --test-threads=1
 
   windows-build:
     name: Build and Test on Windows
diff --git a/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.cpp b/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.cpp
index 092ee537..31cfae4b 100644
--- a/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.cpp
+++ b/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.cpp
@@ -24,6 +24,7 @@
 #include <script/debug.h>
 #include <script/interpreter.h>
 #include <script/script.h>
+#include <script/script_error.h>
 #include <serialize.h>
 #include <streams.h>
 #include <sync.h>
@@ -653,7 +654,8 @@ int btck_script_pubkey_verify(const btck_ScriptPubkey* script_pubkey,
                               const btck_PrecomputedTransactionData* precomputed_txdata,
                               const unsigned int input_index,
                               const btck_ScriptVerificationFlags flags,
-                              btck_ScriptVerifyStatus* status)
+                              btck_ScriptVerifyStatus* status,
+                              btck_ScriptError* script_error)
 {
     // Assert that all specified flags are part of the interface before continuing
     assert((flags & ~btck_ScriptVerificationFlags_ALL) == 0);
@@ -675,12 +677,14 @@ int btck_script_pubkey_verify(const btck_ScriptPubkey* script_pubkey,
 
     if (status) *status = btck_ScriptVerifyStatus_OK;
 
+    ScriptError serror;
     bool result = VerifyScript(tx.vin[input_index].scriptSig,
                                btck_ScriptPubkey::get(script_pubkey),
                                &tx.vin[input_index].scriptWitness,
                                script_verify_flags::from_int(flags),
                                TransactionSignatureChecker(&tx, input_index, amount, txdata, MissingDataBehavior::FAIL),
-                               nullptr);
+                               &serror);
+    if (script_error) *script_error = static_cast<btck_ScriptError>(serror);
     return result ? 1 : 0;
 }
 
diff --git a/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.h b/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.h
index 8a250809..c372c32e 100644
--- a/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.h
+++ b/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.h
@@ -465,6 +465,75 @@ typedef uint8_t btck_ScriptVerifyStatus;
 #define btck_ScriptVerifyStatus_ERROR_INVALID_FLAGS_COMBINATION ((btck_ScriptVerifyStatus)(1)) //!< The flags were combined in an invalid way.
 #define btck_ScriptVerifyStatus_ERROR_SPENT_OUTPUTS_REQUIRED ((btck_ScriptVerifyStatus)(2))    //!< The taproot flag was set, so valid spent_outputs have to be provided.
 
+/**
+ * Script error codes returned by the script interpreter.
+ * Values match the C++ ScriptError_t enum in script_error.h.
+ */
+typedef uint8_t btck_ScriptError;
+#define btck_ScriptError_OK                                       ((btck_ScriptError)(0))
+#define btck_ScriptError_UNKNOWN                                  ((btck_ScriptError)(1))
+#define btck_ScriptError_EVAL_FALSE                               ((btck_ScriptError)(2))
+#define btck_ScriptError_OP_RETURN                                ((btck_ScriptError)(3))
+/* Max sizes */
+#define btck_ScriptError_SCRIPT_SIZE                              ((btck_ScriptError)(4))
+#define btck_ScriptError_PUSH_SIZE                                ((btck_ScriptError)(5))
+#define btck_ScriptError_OP_COUNT                                 ((btck_ScriptError)(6))
+#define btck_ScriptError_STACK_SIZE                               ((btck_ScriptError)(7))
+#define btck_ScriptError_SIG_COUNT                                ((btck_ScriptError)(8))
+#define btck_ScriptError_PUBKEY_COUNT                             ((btck_ScriptError)(9))
+/* Failed verify operations */
+#define btck_ScriptError_VERIFY                                   ((btck_ScriptError)(10))
+#define btck_ScriptError_EQUALVERIFY                              ((btck_ScriptError)(11))
+#define btck_ScriptError_CHECKMULTISIGVERIFY                      ((btck_ScriptError)(12))
+#define btck_ScriptError_CHECKSIGVERIFY                           ((btck_ScriptError)(13))
+#define btck_ScriptError_NUMEQUALVERIFY                           ((btck_ScriptError)(14))
+/* Logical/Format/Canonical errors */
+#define btck_ScriptError_BAD_OPCODE                               ((btck_ScriptError)(15))
+#define btck_ScriptError_DISABLED_OPCODE                          ((btck_ScriptError)(16))
+#define btck_ScriptError_INVALID_STACK_OPERATION                  ((btck_ScriptError)(17))
+#define btck_ScriptError_INVALID_ALTSTACK_OPERATION               ((btck_ScriptError)(18))
+#define btck_ScriptError_UNBALANCED_CONDITIONAL                   ((btck_ScriptError)(19))
+/* CHECKLOCKTIMEVERIFY and CHECKSEQUENCEVERIFY */
+#define btck_ScriptError_NEGATIVE_LOCKTIME                        ((btck_ScriptError)(20))
+#define btck_ScriptError_UNSATISFIED_LOCKTIME                     ((btck_ScriptError)(21))
+/* Malleability */
+#define btck_ScriptError_SIG_HASHTYPE                             ((btck_ScriptError)(22))
+#define btck_ScriptError_SIG_DER                                  ((btck_ScriptError)(23))
+#define btck_ScriptError_MINIMALDATA                              ((btck_ScriptError)(24))
+#define btck_ScriptError_SIG_PUSHONLY                             ((btck_ScriptError)(25))
+#define btck_ScriptError_SIG_HIGH_S                               ((btck_ScriptError)(26))
+#define btck_ScriptError_SIG_NULLDUMMY                            ((btck_ScriptError)(27))
+#define btck_ScriptError_PUBKEYTYPE                               ((btck_ScriptError)(28))
+#define btck_ScriptError_CLEANSTACK                               ((btck_ScriptError)(29))
+#define btck_ScriptError_MINIMALIF                                ((btck_ScriptError)(30))
+#define btck_ScriptError_SIG_NULLFAIL                             ((btck_ScriptError)(31))
+/* Softfork safeness */
+#define btck_ScriptError_DISCOURAGE_UPGRADABLE_NOPS               ((btck_ScriptError)(32))
+#define btck_ScriptError_DISCOURAGE_UPGRADABLE_WITNESS_PROGRAM    ((btck_ScriptError)(33))
+#define btck_ScriptError_DISCOURAGE_UPGRADABLE_TAPROOT_VERSION    ((btck_ScriptError)(34))
+#define btck_ScriptError_DISCOURAGE_OP_SUCCESS                    ((btck_ScriptError)(35))
+#define btck_ScriptError_DISCOURAGE_UPGRADABLE_PUBKEYTYPE         ((btck_ScriptError)(36))
+/* Segregated witness */
+#define btck_ScriptError_WITNESS_PROGRAM_WRONG_LENGTH             ((btck_ScriptError)(37))
+#define btck_ScriptError_WITNESS_PROGRAM_WITNESS_EMPTY            ((btck_ScriptError)(38))
+#define btck_ScriptError_WITNESS_PROGRAM_MISMATCH                 ((btck_ScriptError)(39))
+#define btck_ScriptError_WITNESS_MALLEATED                        ((btck_ScriptError)(40))
+#define btck_ScriptError_WITNESS_MALLEATED_P2SH                   ((btck_ScriptError)(41))
+#define btck_ScriptError_WITNESS_UNEXPECTED                       ((btck_ScriptError)(42))
+#define btck_ScriptError_WITNESS_PUBKEYTYPE                       ((btck_ScriptError)(43))
+/* Taproot */
+#define btck_ScriptError_SCHNORR_SIG_SIZE                         ((btck_ScriptError)(44))
+#define btck_ScriptError_SCHNORR_SIG_HASHTYPE                     ((btck_ScriptError)(45))
+#define btck_ScriptError_SCHNORR_SIG                              ((btck_ScriptError)(46))
+#define btck_ScriptError_TAPROOT_WRONG_CONTROL_SIZE               ((btck_ScriptError)(47))
+#define btck_ScriptError_TAPSCRIPT_VALIDATION_WEIGHT              ((btck_ScriptError)(48))
+#define btck_ScriptError_TAPSCRIPT_CHECKMULTISIG                  ((btck_ScriptError)(49))
+#define btck_ScriptError_TAPSCRIPT_MINIMALIF                      ((btck_ScriptError)(50))
+#define btck_ScriptError_TAPSCRIPT_EMPTY_PUBKEY                   ((btck_ScriptError)(51))
+/* Constant scriptCode */
+#define btck_ScriptError_OP_CODESEPARATOR                         ((btck_ScriptError)(52))
+#define btck_ScriptError_SIG_FINDANDDELETE                        ((btck_ScriptError)(53))
+
 /**
  * Script verification flags that may be composed with each other.
  */
@@ -664,6 +733,7 @@ BITCOINKERNEL_API btck_ScriptPubkey* BITCOINKERNEL_WARN_UNUSED_RESULT btck_scrip
  * @param[in] input_index        Index of the input in tx_to spending the script_pubkey.
  * @param[in] flags              Bitfield of btck_ScriptVerificationFlags controlling validation constraints.
  * @param[out] status            Nullable, will be set to an error code if the operation fails, or OK otherwise.
+ * @param[out] script_error      Nullable, will be set to the specific script error code on verification failure.
  * @return                       1 if the script is valid, 0 otherwise.
  */
 BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_verify(
@@ -673,7 +743,8 @@ BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_script_pubkey_verify
     const btck_PrecomputedTransactionData* precomputed_txdata,
     unsigned int input_index,
     btck_ScriptVerificationFlags flags,
-    btck_ScriptVerifyStatus* status) BITCOINKERNEL_ARG_NONNULL(1, 3);
+    btck_ScriptVerifyStatus* status,
+    btck_ScriptError* script_error) BITCOINKERNEL_ARG_NONNULL(1, 3);
 
 /**
  * @brief Serializes the script pubkey through the passed in callback to bytes.
diff --git a/src/core/mod.rs b/src/core/mod.rs
index 6a96227c..f6114e78 100644
--- a/src/core/mod.rs
+++ b/src/core/mod.rs
@@ -23,7 +23,7 @@ pub use block::{
 pub use script::ScriptPubkeyExt;
 pub use transaction::{TransactionExt, TxInExt, TxOutExt, TxOutPointExt, TxidExt};
 
-pub use verify::{verify, PrecomputedTransactionData, ScriptVerifyError};
+pub use verify::{verify, PrecomputedTransactionData, ScriptError, ScriptVerifyError};
 
 pub mod verify_flags {
     pub use super::verify::{
diff --git a/src/core/verify.rs b/src/core/verify.rs
index 9843493c..8db41460 100644
--- a/src/core/verify.rs
+++ b/src/core/verify.rs
@@ -108,7 +108,7 @@
 //! ## Handling verification errors
 //!
 //! ```no_run
-//! # use bitcoinkernel::{prelude::*, PrecomputedTransactionData, Transaction, verify, VERIFY_ALL, KernelError, ScriptVerifyError};
+//! # use bitcoinkernel::{prelude::*, PrecomputedTransactionData, Transaction, verify, VERIFY_ALL, KernelError, ScriptVerifyError, ScriptError};
 //! # let spending_tx_bytes = vec![];
 //! # let prev_tx_bytes = vec![];
 //! # let spending_tx = Transaction::new(&spending_tx_bytes).unwrap();
@@ -134,8 +134,8 @@
 //!     Err(KernelError::ScriptVerify(ScriptVerifyError::InvalidFlagsCombination)) => {
 //!         println!("Invalid combination of verification flags");
 //!     }
-//!     Err(KernelError::ScriptVerify(ScriptVerifyError::Invalid)) => {
-//!         println!("Script verification failed - invalid script");
+//!     Err(KernelError::ScriptVerify(ScriptVerifyError::Script(e))) => {
+//!         println!("Script verification failed: {}", e);
 //!     }
 //!     Err(e) => {
 //!         println!("Other error: {}", e);
@@ -154,8 +154,8 @@ use std::{
 };
 
 use libbitcoinkernel_sys::{
-    btck_PrecomputedTransactionData, btck_ScriptVerificationFlags, btck_ScriptVerifyStatus,
-    btck_TransactionOutput, btck_precomputed_transaction_data_copy,
+    btck_PrecomputedTransactionData, btck_ScriptError, btck_ScriptVerificationFlags,
+    btck_ScriptVerifyStatus, btck_TransactionOutput, btck_precomputed_transaction_data_copy,
     btck_precomputed_transaction_data_create, btck_precomputed_transaction_data_destroy,
     btck_script_pubkey_verify,
 };
@@ -163,7 +163,34 @@ use libbitcoinkernel_sys::{
 use crate::{
     c_helpers,
     ffi::{
-        sealed::AsPtr, BTCK_SCRIPT_VERIFICATION_FLAGS_ALL,
+        sealed::AsPtr, BTCK_SCRIPT_ERROR_BAD_OPCODE, BTCK_SCRIPT_ERROR_CHECKMULTISIGVERIFY,
+        BTCK_SCRIPT_ERROR_CHECKSIGVERIFY, BTCK_SCRIPT_ERROR_CLEANSTACK,
+        BTCK_SCRIPT_ERROR_DISABLED_OPCODE, BTCK_SCRIPT_ERROR_DISCOURAGE_OP_SUCCESS,
+        BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_NOPS,
+        BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_PUBKEYTYPE,
+        BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_TAPROOT_VERSION,
+        BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_WITNESS_PROGRAM, BTCK_SCRIPT_ERROR_EQUALVERIFY,
+        BTCK_SCRIPT_ERROR_EVAL_FALSE, BTCK_SCRIPT_ERROR_INVALID_ALTSTACK_OPERATION,
+        BTCK_SCRIPT_ERROR_INVALID_STACK_OPERATION, BTCK_SCRIPT_ERROR_MINIMALDATA,
+        BTCK_SCRIPT_ERROR_MINIMALIF, BTCK_SCRIPT_ERROR_NEGATIVE_LOCKTIME,
+        BTCK_SCRIPT_ERROR_NUMEQUALVERIFY, BTCK_SCRIPT_ERROR_OK, BTCK_SCRIPT_ERROR_OP_CODESEPARATOR,
+        BTCK_SCRIPT_ERROR_OP_COUNT, BTCK_SCRIPT_ERROR_OP_RETURN, BTCK_SCRIPT_ERROR_PUBKEYTYPE,
+        BTCK_SCRIPT_ERROR_PUBKEY_COUNT, BTCK_SCRIPT_ERROR_PUSH_SIZE, BTCK_SCRIPT_ERROR_SCHNORR_SIG,
+        BTCK_SCRIPT_ERROR_SCHNORR_SIG_HASHTYPE, BTCK_SCRIPT_ERROR_SCHNORR_SIG_SIZE,
+        BTCK_SCRIPT_ERROR_SCRIPT_SIZE, BTCK_SCRIPT_ERROR_SIG_COUNT, BTCK_SCRIPT_ERROR_SIG_DER,
+        BTCK_SCRIPT_ERROR_SIG_FINDANDDELETE, BTCK_SCRIPT_ERROR_SIG_HASHTYPE,
+        BTCK_SCRIPT_ERROR_SIG_HIGH_S, BTCK_SCRIPT_ERROR_SIG_NULLDUMMY,
+        BTCK_SCRIPT_ERROR_SIG_NULLFAIL, BTCK_SCRIPT_ERROR_SIG_PUSHONLY,
+        BTCK_SCRIPT_ERROR_STACK_SIZE, BTCK_SCRIPT_ERROR_TAPROOT_WRONG_CONTROL_SIZE,
+        BTCK_SCRIPT_ERROR_TAPSCRIPT_CHECKMULTISIG, BTCK_SCRIPT_ERROR_TAPSCRIPT_EMPTY_PUBKEY,
+        BTCK_SCRIPT_ERROR_TAPSCRIPT_MINIMALIF, BTCK_SCRIPT_ERROR_TAPSCRIPT_VALIDATION_WEIGHT,
+        BTCK_SCRIPT_ERROR_UNBALANCED_CONDITIONAL, BTCK_SCRIPT_ERROR_UNKNOWN,
+        BTCK_SCRIPT_ERROR_UNSATISFIED_LOCKTIME, BTCK_SCRIPT_ERROR_VERIFY,
+        BTCK_SCRIPT_ERROR_WITNESS_MALLEATED, BTCK_SCRIPT_ERROR_WITNESS_MALLEATED_P2SH,
+        BTCK_SCRIPT_ERROR_WITNESS_PROGRAM_MISMATCH,
+        BTCK_SCRIPT_ERROR_WITNESS_PROGRAM_WITNESS_EMPTY,
+        BTCK_SCRIPT_ERROR_WITNESS_PROGRAM_WRONG_LENGTH, BTCK_SCRIPT_ERROR_WITNESS_PUBKEYTYPE,
+        BTCK_SCRIPT_ERROR_WITNESS_UNEXPECTED, BTCK_SCRIPT_VERIFICATION_FLAGS_ALL,
         BTCK_SCRIPT_VERIFICATION_FLAGS_CHECKLOCKTIMEVERIFY,
         BTCK_SCRIPT_VERIFICATION_FLAGS_CHECKSEQUENCEVERIFY, BTCK_SCRIPT_VERIFICATION_FLAGS_DERSIG,
         BTCK_SCRIPT_VERIFICATION_FLAGS_NONE, BTCK_SCRIPT_VERIFICATION_FLAGS_NULLDUMMY,
@@ -338,8 +365,9 @@ unsafe impl Sync for PrecomputedTransactionData {}
 ///   combination of flags
 /// * `Err(KernelError::ScriptVerify(ScriptVerifyError::SpentOutputsRequired))` - Spent outputs
 ///   are required for this script type but were not provided
-/// * `Err(KernelError::ScriptVerify(ScriptVerifyError::Invalid))` - Script verification failed;
-///   the input does not properly satisfy the output's spending conditions
+/// * `Err(KernelError::ScriptVerify(ScriptVerifyError::Script(..)))` - Script verification failed;
+///   the input does not properly satisfy the output's spending conditions. The inner
+///   [`ScriptError`] indicates the specific reason for failure.
 ///
 /// # Examples
 ///
@@ -413,6 +441,7 @@ pub fn verify(
 
     let kernel_amount = amount.unwrap_or_default();
     let mut status = ScriptVerifyStatus::Ok.into();
+    let mut script_error: btck_ScriptError = BTCK_SCRIPT_ERROR_OK;
 
     let ret = unsafe {
         btck_script_pubkey_verify(
@@ -423,6 +452,7 @@ pub fn verify(
             input_index as u32,
             kernel_flags,
             &mut status,
+            &mut script_error,
         )
     };
 
@@ -438,7 +468,10 @@ pub fn verify(
             ScriptVerifyStatus::ErrorSpentOutputsRequired => {
                 ScriptVerifyError::SpentOutputsRequired
             }
-            _ => ScriptVerifyError::Invalid,
+            _ => {
+                let se = ScriptError::try_from(script_error).unwrap_or(ScriptError::Unknown);
+                ScriptVerifyError::Script(se)
+            }
         };
         Err(KernelError::ScriptVerify(err))
     } else {
@@ -499,6 +532,312 @@ impl From<btck_ScriptVerifyStatus> for ScriptVerifyStatus {
     }
 }
 
+/// Specific error codes from Bitcoin script execution.
+///
+/// These correspond to the script interpreter's error taxonomy and indicate
+/// exactly why a script failed verification. Values match the C++
+/// `ScriptError_t` enum in `script_error.h`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ScriptError {
+    /// Unknown error from the script interpreter (C++ `SCRIPT_ERR_UNKNOWN_ERROR`).
+    Unknown,
+    /// Script finished with false/empty top stack element.
+    EvalFalse,
+    /// OP_RETURN was encountered.
+    OpReturn,
+    /// Script exceeds maximum size.
+    ScriptSize,
+    /// Push value exceeds size limit.
+    PushSize,
+    /// Opcode count exceeded.
+    OpCount,
+    /// Stack size limit exceeded.
+    StackSize,
+    /// Signature count negative or exceeds pubkey count.
+    SigCount,
+    /// Pubkey count negative or limit exceeded.
+    PubkeyCount,
+    /// OP_VERIFY failed.
+    Verify,
+    /// OP_EQUALVERIFY failed.
+    EqualVerify,
+    /// OP_CHECKMULTISIGVERIFY failed.
+    CheckMultisigVerify,
+    /// OP_CHECKSIGVERIFY failed.
+    CheckSigVerify,
+    /// OP_NUMEQUALVERIFY failed.
+    NumEqualVerify,
+    /// Opcode missing or not understood.
+    BadOpcode,
+    /// Disabled opcode encountered.
+    DisabledOpcode,
+    /// Invalid stack operation for current stack size.
+    InvalidStackOperation,
+    /// Invalid altstack operation for current altstack size.
+    InvalidAltstackOperation,
+    /// Unbalanced OP_IF/OP_ELSE/OP_ENDIF.
+    UnbalancedConditional,
+    /// Negative locktime.
+    NegativeLocktime,
+    /// Locktime requirement not satisfied.
+    UnsatisfiedLocktime,
+    /// Signature hash type missing or not understood.
+    SigHashtype,
+    /// Non-canonical DER signature.
+    SigDer,
+    /// Data push larger than necessary.
+    MinimalData,
+    /// Non-push operators in scriptSig.
+    SigPushOnly,
+    /// Non-canonical signature: S value unnecessarily high.
+    SigHighS,
+    /// Dummy CHECKMULTISIG argument must be zero.
+    SigNullDummy,
+    /// Public key is neither compressed nor uncompressed.
+    PubkeyType,
+    /// Stack must contain exactly one element after execution.
+    CleanStack,
+    /// OP_IF/NOTIF argument must be minimal.
+    MinimalIf,
+    /// Signature must be zero for failed CHECK(MULTI)SIG.
+    SigNullFail,
+    /// NOPx reserved for soft-fork upgrades.
+    DiscourageUpgradableNops,
+    /// Witness version reserved for soft-fork upgrades.
+    DiscourageUpgradableWitnessProgram,
+    /// Taproot version reserved for soft-fork upgrades.
+    DiscourageUpgradableTaprootVersion,
+    /// OP_SUCCESSx reserved for soft-fork upgrades.
+    DiscourageOpSuccess,
+    /// Public key version reserved for soft-fork upgrades.
+    DiscourageUpgradablePubkeyType,
+    /// Witness program has incorrect length.
+    WitnessProgramWrongLength,
+    /// Witness program was passed an empty witness.
+    WitnessProgramWitnessEmpty,
+    /// Witness program hash mismatch.
+    WitnessProgramMismatch,
+    /// Witness requires empty scriptSig.
+    WitnessMalleated,
+    /// Witness requires only-redeemscript scriptSig.
+    WitnessMalleatedP2sh,
+    /// Witness provided for non-witness script.
+    WitnessUnexpected,
+    /// Using non-compressed keys in segwit.
+    WitnessPubkeyType,
+    /// Invalid Schnorr signature size.
+    SchnorrSigSize,
+    /// Invalid Schnorr signature hash type.
+    SchnorrSigHashtype,
+    /// Invalid Schnorr signature.
+    SchnorrSig,
+    /// Invalid Taproot control block size.
+    TaprootWrongControlSize,
+    /// Too much signature validation relative to witness weight.
+    TapscriptValidationWeight,
+    /// OP_CHECKMULTISIG(VERIFY) not available in tapscript.
+    TapscriptCheckMultisig,
+    /// OP_IF/NOTIF argument must be minimal in tapscript.
+    TapscriptMinimalIf,
+    /// Empty public key in tapscript.
+    TapscriptEmptyPubkey,
+    /// OP_CODESEPARATOR in non-witness script.
+    OpCodeseparator,
+    /// Signature found in scriptCode.
+    SigFindAndDelete,
+}
+
+impl Display for ScriptError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            ScriptError::Unknown => write!(f, "unknown error"),
+            ScriptError::EvalFalse => write!(
+                f,
+                "Script evaluated without error but finished with a false/empty top stack element"
+            ),
+            ScriptError::OpReturn => write!(f, "OP_RETURN was encountered"),
+            ScriptError::ScriptSize => write!(f, "Script is too big"),
+            ScriptError::PushSize => write!(f, "Push value size limit exceeded"),
+            ScriptError::OpCount => write!(f, "Operation limit exceeded"),
+            ScriptError::StackSize => write!(f, "Stack size limit exceeded"),
+            ScriptError::SigCount => {
+                write!(f, "Signature count negative or greater than pubkey count")
+            }
+            ScriptError::PubkeyCount => write!(f, "Pubkey count negative or limit exceeded"),
+            ScriptError::Verify => write!(f, "Script failed an OP_VERIFY operation"),
+            ScriptError::EqualVerify => write!(f, "Script failed an OP_EQUALVERIFY operation"),
+            ScriptError::CheckMultisigVerify => {
+                write!(f, "Script failed an OP_CHECKMULTISIGVERIFY operation")
+            }
+            ScriptError::CheckSigVerify => {
+                write!(f, "Script failed an OP_CHECKSIGVERIFY operation")
+            }
+            ScriptError::NumEqualVerify => {
+                write!(f, "Script failed an OP_NUMEQUALVERIFY operation")
+            }
+            ScriptError::BadOpcode => write!(f, "Opcode missing or not understood"),
+            ScriptError::DisabledOpcode => write!(f, "Attempted to use a disabled opcode"),
+            ScriptError::InvalidStackOperation => {
+                write!(f, "Operation not valid with the current stack size")
+            }
+            ScriptError::InvalidAltstackOperation => {
+                write!(f, "Operation not valid with the current altstack size")
+            }
+            ScriptError::UnbalancedConditional => write!(f, "Invalid OP_IF construction"),
+            ScriptError::NegativeLocktime => write!(f, "Negative locktime"),
+            ScriptError::UnsatisfiedLocktime => write!(f, "Locktime requirement not satisfied"),
+            ScriptError::SigHashtype => write!(f, "Signature hash type missing or not understood"),
+            ScriptError::SigDer => write!(f, "Non-canonical DER signature"),
+            ScriptError::MinimalData => write!(f, "Data push larger than necessary"),
+            ScriptError::SigPushOnly => write!(f, "Only push operators allowed in signatures"),
+            ScriptError::SigHighS => {
+                write!(f, "Non-canonical signature: S value is unnecessarily high")
+            }
+            ScriptError::SigNullDummy => write!(f, "Dummy CHECKMULTISIG argument must be zero"),
+            ScriptError::PubkeyType => {
+                write!(f, "Public key is neither compressed or uncompressed")
+            }
+            ScriptError::CleanStack => write!(f, "Stack size must be exactly one after execution"),
+            ScriptError::MinimalIf => write!(f, "OP_IF/NOTIF argument must be minimal"),
+            ScriptError::SigNullFail => write!(
+                f,
+                "Signature must be zero for failed CHECK(MULTI)SIG operation"
+            ),
+            ScriptError::DiscourageUpgradableNops => {
+                write!(f, "NOPx reserved for soft-fork upgrades")
+            }
+            ScriptError::DiscourageUpgradableWitnessProgram => {
+                write!(f, "Witness version reserved for soft-fork upgrades")
+            }
+            ScriptError::DiscourageUpgradableTaprootVersion => {
+                write!(f, "Taproot version reserved for soft-fork upgrades")
+            }
+            ScriptError::DiscourageOpSuccess => {
+                write!(f, "OP_SUCCESSx reserved for soft-fork upgrades")
+            }
+            ScriptError::DiscourageUpgradablePubkeyType => {
+                write!(f, "Public key version reserved for soft-fork upgrades")
+            }
+            ScriptError::WitnessProgramWrongLength => {
+                write!(f, "Witness program has incorrect length")
+            }
+            ScriptError::WitnessProgramWitnessEmpty => {
+                write!(f, "Witness program was passed an empty witness")
+            }
+            ScriptError::WitnessProgramMismatch => write!(f, "Witness program hash mismatch"),
+            ScriptError::WitnessMalleated => write!(f, "Witness requires empty scriptSig"),
+            ScriptError::WitnessMalleatedP2sh => {
+                write!(f, "Witness requires only-redeemscript scriptSig")
+            }
+            ScriptError::WitnessUnexpected => write!(f, "Witness provided for non-witness script"),
+            ScriptError::WitnessPubkeyType => write!(f, "Using non-compressed keys in segwit"),
+            ScriptError::SchnorrSigSize => write!(f, "Invalid Schnorr signature size"),
+            ScriptError::SchnorrSigHashtype => write!(f, "Invalid Schnorr signature hash type"),
+            ScriptError::SchnorrSig => write!(f, "Invalid Schnorr signature"),
+            ScriptError::TaprootWrongControlSize => write!(f, "Invalid Taproot control block size"),
+            ScriptError::TapscriptValidationWeight => write!(
+                f,
+                "Too much signature validation relative to witness weight"
+            ),
+            ScriptError::TapscriptCheckMultisig => {
+                write!(f, "OP_CHECKMULTISIG(VERIFY) is not available in tapscript")
+            }
+            ScriptError::TapscriptMinimalIf => {
+                write!(f, "OP_IF/NOTIF argument must be minimal in tapscript")
+            }
+            ScriptError::TapscriptEmptyPubkey => write!(f, "Empty public key in tapscript"),
+            ScriptError::OpCodeseparator => {
+                write!(f, "Using OP_CODESEPARATOR in non-witness script")
+            }
+            ScriptError::SigFindAndDelete => write!(f, "Signature is found in scriptCode"),
+        }
+    }
+}
+
+impl Error for ScriptError {}
+
+impl TryFrom<btck_ScriptError> for ScriptError {
+    type Error = btck_ScriptError;
+
+    fn try_from(value: btck_ScriptError) -> Result<Self, Self::Error> {
+        match value {
+            BTCK_SCRIPT_ERROR_OK => Err(value), // OK is not an error
+            BTCK_SCRIPT_ERROR_UNKNOWN => Ok(ScriptError::Unknown),
+            BTCK_SCRIPT_ERROR_EVAL_FALSE => Ok(ScriptError::EvalFalse),
+            BTCK_SCRIPT_ERROR_OP_RETURN => Ok(ScriptError::OpReturn),
+            BTCK_SCRIPT_ERROR_SCRIPT_SIZE => Ok(ScriptError::ScriptSize),
+            BTCK_SCRIPT_ERROR_PUSH_SIZE => Ok(ScriptError::PushSize),
+            BTCK_SCRIPT_ERROR_OP_COUNT => Ok(ScriptError::OpCount),
+            BTCK_SCRIPT_ERROR_STACK_SIZE => Ok(ScriptError::StackSize),
+            BTCK_SCRIPT_ERROR_SIG_COUNT => Ok(ScriptError::SigCount),
+            BTCK_SCRIPT_ERROR_PUBKEY_COUNT => Ok(ScriptError::PubkeyCount),
+            BTCK_SCRIPT_ERROR_VERIFY => Ok(ScriptError::Verify),
+            BTCK_SCRIPT_ERROR_EQUALVERIFY => Ok(ScriptError::EqualVerify),
+            BTCK_SCRIPT_ERROR_CHECKMULTISIGVERIFY => Ok(ScriptError::CheckMultisigVerify),
+            BTCK_SCRIPT_ERROR_CHECKSIGVERIFY => Ok(ScriptError::CheckSigVerify),
+            BTCK_SCRIPT_ERROR_NUMEQUALVERIFY => Ok(ScriptError::NumEqualVerify),
+            BTCK_SCRIPT_ERROR_BAD_OPCODE => Ok(ScriptError::BadOpcode),
+            BTCK_SCRIPT_ERROR_DISABLED_OPCODE => Ok(ScriptError::DisabledOpcode),
+            BTCK_SCRIPT_ERROR_INVALID_STACK_OPERATION => Ok(ScriptError::InvalidStackOperation),
+            BTCK_SCRIPT_ERROR_INVALID_ALTSTACK_OPERATION => {
+                Ok(ScriptError::InvalidAltstackOperation)
+            }
+            BTCK_SCRIPT_ERROR_UNBALANCED_CONDITIONAL => Ok(ScriptError::UnbalancedConditional),
+            BTCK_SCRIPT_ERROR_NEGATIVE_LOCKTIME => Ok(ScriptError::NegativeLocktime),
+            BTCK_SCRIPT_ERROR_UNSATISFIED_LOCKTIME => Ok(ScriptError::UnsatisfiedLocktime),
+            BTCK_SCRIPT_ERROR_SIG_HASHTYPE => Ok(ScriptError::SigHashtype),
+            BTCK_SCRIPT_ERROR_SIG_DER => Ok(ScriptError::SigDer),
+            BTCK_SCRIPT_ERROR_MINIMALDATA => Ok(ScriptError::MinimalData),
+            BTCK_SCRIPT_ERROR_SIG_PUSHONLY => Ok(ScriptError::SigPushOnly),
+            BTCK_SCRIPT_ERROR_SIG_HIGH_S => Ok(ScriptError::SigHighS),
+            BTCK_SCRIPT_ERROR_SIG_NULLDUMMY => Ok(ScriptError::SigNullDummy),
+            BTCK_SCRIPT_ERROR_PUBKEYTYPE => Ok(ScriptError::PubkeyType),
+            BTCK_SCRIPT_ERROR_CLEANSTACK => Ok(ScriptError::CleanStack),
+            BTCK_SCRIPT_ERROR_MINIMALIF => Ok(ScriptError::MinimalIf),
+            BTCK_SCRIPT_ERROR_SIG_NULLFAIL => Ok(ScriptError::SigNullFail),
+            BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_NOPS => {
+                Ok(ScriptError::DiscourageUpgradableNops)
+            }
+            BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_WITNESS_PROGRAM => {
+                Ok(ScriptError::DiscourageUpgradableWitnessProgram)
+            }
+            BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_TAPROOT_VERSION => {
+                Ok(ScriptError::DiscourageUpgradableTaprootVersion)
+            }
+            BTCK_SCRIPT_ERROR_DISCOURAGE_OP_SUCCESS => Ok(ScriptError::DiscourageOpSuccess),
+            BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_PUBKEYTYPE => {
+                Ok(ScriptError::DiscourageUpgradablePubkeyType)
+            }
+            BTCK_SCRIPT_ERROR_WITNESS_PROGRAM_WRONG_LENGTH => {
+                Ok(ScriptError::WitnessProgramWrongLength)
+            }
+            BTCK_SCRIPT_ERROR_WITNESS_PROGRAM_WITNESS_EMPTY => {
+                Ok(ScriptError::WitnessProgramWitnessEmpty)
+            }
+            BTCK_SCRIPT_ERROR_WITNESS_PROGRAM_MISMATCH => Ok(ScriptError::WitnessProgramMismatch),
+            BTCK_SCRIPT_ERROR_WITNESS_MALLEATED => Ok(ScriptError::WitnessMalleated),
+            BTCK_SCRIPT_ERROR_WITNESS_MALLEATED_P2SH => Ok(ScriptError::WitnessMalleatedP2sh),
+            BTCK_SCRIPT_ERROR_WITNESS_UNEXPECTED => Ok(ScriptError::WitnessUnexpected),
+            BTCK_SCRIPT_ERROR_WITNESS_PUBKEYTYPE => Ok(ScriptError::WitnessPubkeyType),
+            BTCK_SCRIPT_ERROR_SCHNORR_SIG_SIZE => Ok(ScriptError::SchnorrSigSize),
+            BTCK_SCRIPT_ERROR_SCHNORR_SIG_HASHTYPE => Ok(ScriptError::SchnorrSigHashtype),
+            BTCK_SCRIPT_ERROR_SCHNORR_SIG => Ok(ScriptError::SchnorrSig),
+            BTCK_SCRIPT_ERROR_TAPROOT_WRONG_CONTROL_SIZE => {
+                Ok(ScriptError::TaprootWrongControlSize)
+            }
+            BTCK_SCRIPT_ERROR_TAPSCRIPT_VALIDATION_WEIGHT => {
+                Ok(ScriptError::TapscriptValidationWeight)
+            }
+            BTCK_SCRIPT_ERROR_TAPSCRIPT_CHECKMULTISIG => Ok(ScriptError::TapscriptCheckMultisig),
+            BTCK_SCRIPT_ERROR_TAPSCRIPT_MINIMALIF => Ok(ScriptError::TapscriptMinimalIf),
+            BTCK_SCRIPT_ERROR_TAPSCRIPT_EMPTY_PUBKEY => Ok(ScriptError::TapscriptEmptyPubkey),
+            BTCK_SCRIPT_ERROR_OP_CODESEPARATOR => Ok(ScriptError::OpCodeseparator),
+            BTCK_SCRIPT_ERROR_SIG_FINDANDDELETE => Ok(ScriptError::SigFindAndDelete),
+            _ => Err(value),
+        }
+    }
+}
+
 /// Errors that can occur during script verification.
 ///
 /// These errors represent both configuration problems (incorrect parameters)
@@ -526,8 +865,8 @@ pub enum ScriptVerifyError {
     /// Spent outputs are required but were not provided.
     SpentOutputsRequired,
 
-    /// Script verification failed.
-    Invalid,
+    /// Script execution failed with a specific error.
+    Script(ScriptError),
 }
 
 impl Display for ScriptVerifyError {
@@ -541,12 +880,19 @@ impl Display for ScriptVerifyError {
             ScriptVerifyError::SpentOutputsRequired => {
                 write!(f, "Spent outputs required for verification")
             }
-            ScriptVerifyError::Invalid => write!(f, "Script verification failed"),
+            ScriptVerifyError::Script(e) => write!(f, "Script verification failed: {}", e),
         }
     }
 }
 
-impl Error for ScriptVerifyError {}
+impl Error for ScriptVerifyError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            ScriptVerifyError::Script(e) => Some(e),
+            _ => None,
+        }
+    }
+}
 
 #[cfg(test)]
 mod tests {
@@ -691,7 +1037,7 @@ mod tests {
             ScriptVerifyError::InvalidFlags,
             ScriptVerifyError::InvalidFlagsCombination,
             ScriptVerifyError::SpentOutputsRequired,
-            ScriptVerifyError::Invalid,
+            ScriptVerifyError::Script(ScriptError::EvalFalse),
         ];
 
         for err in errors {
diff --git a/src/ffi/constants.rs b/src/ffi/constants.rs
index 74e2e5b4..885895fe 100644
--- a/src/ffi/constants.rs
+++ b/src/ffi/constants.rs
@@ -1,5 +1,5 @@
 use crate::{
-    btck_BlockValidationResult, btck_ChainType, btck_LogCategory, btck_LogLevel,
+    btck_BlockValidationResult, btck_ChainType, btck_LogCategory, btck_LogLevel, btck_ScriptError,
     btck_ScriptVerificationFlags, btck_ScriptVerifyStatus, btck_SynchronizationState,
     btck_ValidationMode, btck_Warning,
 };
@@ -72,6 +72,62 @@ pub const BTCK_SCRIPT_VERIFICATION_FLAGS_ALL: btck_ScriptVerificationFlags =
         | BTCK_SCRIPT_VERIFICATION_FLAGS_WITNESS
         | BTCK_SCRIPT_VERIFICATION_FLAGS_TAPROOT;
 
+// Script Error Codes
+pub const BTCK_SCRIPT_ERROR_OK: btck_ScriptError = 0;
+pub const BTCK_SCRIPT_ERROR_UNKNOWN: btck_ScriptError = 1;
+pub const BTCK_SCRIPT_ERROR_EVAL_FALSE: btck_ScriptError = 2;
+pub const BTCK_SCRIPT_ERROR_OP_RETURN: btck_ScriptError = 3;
+pub const BTCK_SCRIPT_ERROR_SCRIPT_SIZE: btck_ScriptError = 4;
+pub const BTCK_SCRIPT_ERROR_PUSH_SIZE: btck_ScriptError = 5;
+pub const BTCK_SCRIPT_ERROR_OP_COUNT: btck_ScriptError = 6;
+pub const BTCK_SCRIPT_ERROR_STACK_SIZE: btck_ScriptError = 7;
+pub const BTCK_SCRIPT_ERROR_SIG_COUNT: btck_ScriptError = 8;
+pub const BTCK_SCRIPT_ERROR_PUBKEY_COUNT: btck_ScriptError = 9;
+pub const BTCK_SCRIPT_ERROR_VERIFY: btck_ScriptError = 10;
+pub const BTCK_SCRIPT_ERROR_EQUALVERIFY: btck_ScriptError = 11;
+pub const BTCK_SCRIPT_ERROR_CHECKMULTISIGVERIFY: btck_ScriptError = 12;
+pub const BTCK_SCRIPT_ERROR_CHECKSIGVERIFY: btck_ScriptError = 13;
+pub const BTCK_SCRIPT_ERROR_NUMEQUALVERIFY: btck_ScriptError = 14;
+pub const BTCK_SCRIPT_ERROR_BAD_OPCODE: btck_ScriptError = 15;
+pub const BTCK_SCRIPT_ERROR_DISABLED_OPCODE: btck_ScriptError = 16;
+pub const BTCK_SCRIPT_ERROR_INVALID_STACK_OPERATION: btck_ScriptError = 17;
+pub const BTCK_SCRIPT_ERROR_INVALID_ALTSTACK_OPERATION: btck_ScriptError = 18;
+pub const BTCK_SCRIPT_ERROR_UNBALANCED_CONDITIONAL: btck_ScriptError = 19;
+pub const BTCK_SCRIPT_ERROR_NEGATIVE_LOCKTIME: btck_ScriptError = 20;
+pub const BTCK_SCRIPT_ERROR_UNSATISFIED_LOCKTIME: btck_ScriptError = 21;
+pub const BTCK_SCRIPT_ERROR_SIG_HASHTYPE: btck_ScriptError = 22;
+pub const BTCK_SCRIPT_ERROR_SIG_DER: btck_ScriptError = 23;
+pub const BTCK_SCRIPT_ERROR_MINIMALDATA: btck_ScriptError = 24;
+pub const BTCK_SCRIPT_ERROR_SIG_PUSHONLY: btck_ScriptError = 25;
+pub const BTCK_SCRIPT_ERROR_SIG_HIGH_S: btck_ScriptError = 26;
+pub const BTCK_SCRIPT_ERROR_SIG_NULLDUMMY: btck_ScriptError = 27;
+pub const BTCK_SCRIPT_ERROR_PUBKEYTYPE: btck_ScriptError = 28;
+pub const BTCK_SCRIPT_ERROR_CLEANSTACK: btck_ScriptError = 29;
+pub const BTCK_SCRIPT_ERROR_MINIMALIF: btck_ScriptError = 30;
+pub const BTCK_SCRIPT_ERROR_SIG_NULLFAIL: btck_ScriptError = 31;
+pub const BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_NOPS: btck_ScriptError = 32;
+pub const BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_WITNESS_PROGRAM: btck_ScriptError = 33;
+pub const BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_TAPROOT_VERSION: btck_ScriptError = 34;
+pub const BTCK_SCRIPT_ERROR_DISCOURAGE_OP_SUCCESS: btck_ScriptError = 35;
+pub const BTCK_SCRIPT_ERROR_DISCOURAGE_UPGRADABLE_PUBKEYTYPE: btck_ScriptError = 36;
+pub const BTCK_SCRIPT_ERROR_WITNESS_PROGRAM_WRONG_LENGTH: btck_ScriptError = 37;
+pub const BTCK_SCRIPT_ERROR_WITNESS_PROGRAM_WITNESS_EMPTY: btck_ScriptError = 38;
+pub const BTCK_SCRIPT_ERROR_WITNESS_PROGRAM_MISMATCH: btck_ScriptError = 39;
+pub const BTCK_SCRIPT_ERROR_WITNESS_MALLEATED: btck_ScriptError = 40;
+pub const BTCK_SCRIPT_ERROR_WITNESS_MALLEATED_P2SH: btck_ScriptError = 41;
+pub const BTCK_SCRIPT_ERROR_WITNESS_UNEXPECTED: btck_ScriptError = 42;
+pub const BTCK_SCRIPT_ERROR_WITNESS_PUBKEYTYPE: btck_ScriptError = 43;
+pub const BTCK_SCRIPT_ERROR_SCHNORR_SIG_SIZE: btck_ScriptError = 44;
+pub const BTCK_SCRIPT_ERROR_SCHNORR_SIG_HASHTYPE: btck_ScriptError = 45;
+pub const BTCK_SCRIPT_ERROR_SCHNORR_SIG: btck_ScriptError = 46;
+pub const BTCK_SCRIPT_ERROR_TAPROOT_WRONG_CONTROL_SIZE: btck_ScriptError = 47;
+pub const BTCK_SCRIPT_ERROR_TAPSCRIPT_VALIDATION_WEIGHT: btck_ScriptError = 48;
+pub const BTCK_SCRIPT_ERROR_TAPSCRIPT_CHECKMULTISIG: btck_ScriptError = 49;
+pub const BTCK_SCRIPT_ERROR_TAPSCRIPT_MINIMALIF: btck_ScriptError = 50;
+pub const BTCK_SCRIPT_ERROR_TAPSCRIPT_EMPTY_PUBKEY: btck_ScriptError = 51;
+pub const BTCK_SCRIPT_ERROR_OP_CODESEPARATOR: btck_ScriptError = 52;
+pub const BTCK_SCRIPT_ERROR_SIG_FINDANDDELETE: btck_ScriptError = 53;
+
 // Chain types
 pub const BTCK_CHAIN_TYPE_MAINNET: btck_ChainType = 0;
 pub const BTCK_CHAIN_TYPE_TESTNET: btck_ChainType = 1;
diff --git a/src/lib.rs b/src/lib.rs
index 38710d06..b42ddf63 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -295,9 +295,10 @@ impl std::error::Error for KernelError {
 
 pub use crate::core::{
     verify, Block, BlockHash, BlockHeader, BlockSpentOutputs, BlockSpentOutputsRef, BlockTreeEntry,
-    Coin, CoinRef, PrecomputedTransactionData, ScriptPubkey, ScriptPubkeyRef, ScriptVerifyError,
-    Transaction, TransactionRef, TransactionSpentOutputs, TransactionSpentOutputsRef, TxIn,
-    TxInRef, TxOut, TxOutPoint, TxOutPointRef, TxOutRef, Txid, TxidRef,
+    Coin, CoinRef, PrecomputedTransactionData, ScriptError, ScriptPubkey, ScriptPubkeyRef,
+    ScriptVerifyError, Transaction, TransactionRef, TransactionSpentOutputs,
+    TransactionSpentOutputsRef, TxIn, TxInRef, TxOut, TxOutPoint, TxOutPointRef, TxOutRef, Txid,
+    TxidRef,
 };
 
 pub use crate::log::{disable_logging, Log, LogCategory, LogLevel, Logger};
diff --git a/tests/test.rs b/tests/test.rs
index 2b18b407..6183ccf6 100644
--- a/tests/test.rs
+++ b/tests/test.rs
@@ -6,7 +6,7 @@ mod tests {
         prelude::*, verify, Block, BlockHash, BlockHeader, BlockSpentOutputs, BlockTreeEntry,
         BlockValidationStateRef, ChainParams, ChainType, ChainstateManager,
         ChainstateManagerBuilder, Coin, Context, ContextBuilder, KernelError, Log, Logger,
-        PrecomputedTransactionData, ScriptPubkey, ScriptVerifyError, Transaction,
+        PrecomputedTransactionData, ScriptError, ScriptPubkey, ScriptVerifyError, Transaction,
         TransactionSpentOutputs, TxIn, TxOut, ValidationMode, VERIFY_ALL, VERIFY_ALL_PRE_TAPROOT,
         VERIFY_TAPROOT, VERIFY_WITNESS,
     };
@@ -243,7 +243,77 @@ mod tests {
     }
 
     #[test]
-    fn script_verify_test() {
+    fn test_script_error_codes() {
+        let p2pkh_tx = "02000000013f7cebd65c27431a90bba7f796914fe8cc2ddfc3f2cbd6f7e5f2fc854534da95000000006b483045022100de1ac3bcdfb0332207c4a91f3832bd2c2915840165f876ab47c5f8996b971c3602201c6c053d750fadde599e6f5c4e1963df0f01fc0d97815e8157e3d59fe09ca30d012103699b464d1d8bc9e47d4fb1cdaa89a1c5783d68363c4dbc4b524ed3d857148617feffffff02836d3c01000000001976a914fc25d6d5c94003bf5b0c7b640a248e2c637fcfb088ac7ada8202000000001976a914fbed3d9b11183209a57999d54d59f67c019e756c88ac6acb0700";
+
+        // OP_RETURN (0x6a) → OpReturn
+        assert!(matches!(
+            verify_test("6a", p2pkh_tx, 0, 0, vec![], VERIFY_ALL_PRE_TAPROOT),
+            Err(KernelError::ScriptVerify(ScriptVerifyError::Script(
+                ScriptError::OpReturn
+            )))
+        ));
+
+        // OP_0 (0x00) pushes empty bytes → top of stack is false → EvalFalse
+        assert!(matches!(
+            verify_test("00", p2pkh_tx, 0, 0, vec![], VERIFY_ALL_PRE_TAPROOT),
+            Err(KernelError::ScriptVerify(ScriptVerifyError::Script(
+                ScriptError::EvalFalse
+            )))
+        ));
+
+        // OP_EQUALVERIFY (0x88) pops sig and pubkey, they differ → EqualVerify
+        assert!(matches!(
+            verify_test("88", p2pkh_tx, 0, 0, vec![], VERIFY_ALL_PRE_TAPROOT),
+            Err(KernelError::ScriptVerify(ScriptVerifyError::Script(
+                ScriptError::EqualVerify
+            )))
+        ));
+
+        // OP_IF (0x63) without OP_ENDIF → UnbalancedConditional
+        assert!(matches!(
+            verify_test("63", p2pkh_tx, 0, 0, vec![], VERIFY_ALL_PRE_TAPROOT),
+            Err(KernelError::ScriptVerify(ScriptVerifyError::Script(
+                ScriptError::UnbalancedConditional
+            )))
+        ));
+
+        // OP_DROP OP_DROP OP_DROP (0x75 0x75 0x75): scriptSig pushes 2 items,
+        // third OP_DROP has nothing to pop → InvalidStackOperation
+        assert!(matches!(
+            verify_test("757575", p2pkh_tx, 0, 0, vec![], VERIFY_ALL_PRE_TAPROOT),
+            Err(KernelError::ScriptVerify(ScriptVerifyError::Script(
+                ScriptError::InvalidStackOperation
+            )))
+        ));
+
+        // OP_2MUL (0x8d) is a disabled opcode → DisabledOpcode
+        assert!(matches!(
+            verify_test("8d", p2pkh_tx, 0, 0, vec![], VERIFY_ALL_PRE_TAPROOT),
+            Err(KernelError::ScriptVerify(ScriptVerifyError::Script(
+                ScriptError::DisabledOpcode
+            )))
+        ));
+
+        // P2PKH with wrong pubkey hash: OP_DUP OP_HASH160 <20 zero bytes> OP_EQUALVERIFY OP_CHECKSIG
+        // Hash won't match the actual pubkey → EqualVerify
+        assert!(matches!(
+            verify_test(
+                "76a914000000000000000000000000000000000000000088ac",
+                p2pkh_tx,
+                0,
+                0,
+                vec![],
+                VERIFY_ALL_PRE_TAPROOT
+            ),
+            Err(KernelError::ScriptVerify(ScriptVerifyError::Script(
+                ScriptError::EqualVerify
+            )))
+        ));
+    }
+
+    #[test]
+    fn test_script_verify() {
         // a random old-style transaction from the blockchain
         verify_test (
             "76a9144bfbaf6afb76cc5771bc6404810d1cc041a6933988ac",
@@ -265,19 +335,22 @@ mod tests {
             18393430 , 0, vec![], VERIFY_ALL_PRE_TAPROOT
         ).unwrap();
 
-        // a random old-style transaction from the blockchain - WITH WRONG SIGNATURE for the address
+        // a random old-style transaction from the blockchain - WITH BAD OPCODE replacing OP_CHECKSIG
+        // scriptPubkey ends with 0xff instead of 0xac (OP_CHECKSIG), so EQUALVERIFY passes
+        // (correct pubkey hash) but then 0xff is an undefined opcode → BadOpcode
         assert!(matches!(verify_test(
             "76a9144bfbaf6afb76cc5771bc6404810d1cc041a6933988ff",
             "02000000013f7cebd65c27431a90bba7f796914fe8cc2ddfc3f2cbd6f7e5f2fc854534da95000000006b483045022100de1ac3bcdfb0332207c4a91f3832bd2c2915840165f876ab47c5f8996b971c3602201c6c053d750fadde599e6f5c4e1963df0f01fc0d97815e8157e3d59fe09ca30d012103699b464d1d8bc9e47d4fb1cdaa89a1c5783d68363c4dbc4b524ed3d857148617feffffff02836d3c01000000001976a914fc25d6d5c94003bf5b0c7b640a248e2c637fcfb088ac7ada8202000000001976a914fbed3d9b11183209a57999d54d59f67c019e756c88ac6acb0700",
             0, 0 , vec![], VERIFY_ALL_PRE_TAPROOT
-        ), Err(KernelError::ScriptVerify(ScriptVerifyError::Invalid))));
+        ), Err(KernelError::ScriptVerify(ScriptVerifyError::Script(ScriptError::BadOpcode)))));
 
-        // a random segwit transaction from the blockchain using native segwit - WITH WRONG SEGWIT
+        // a random segwit transaction from the blockchain using native segwit - WITH WRONG WITNESS HASH
+        // Last byte of witness program changed (c58d → c58f), so hash doesn't match → WitnessProgramMismatch
         assert!(matches!(verify_test(
             "0020701a8d401c84fb13e6baf169d59684e17abd9fa216c8cc5b9fc63d622ff8c58f",
             "010000000001011f97548fbbe7a0db7588a66e18d803d0089315aa7d4cc28360b6ec50ef36718a0100000000ffffffff02df1776000000000017a9146c002a686959067f4866b8fb493ad7970290ab728757d29f0000000000220020701a8d401c84fb13e6baf169d59684e17abd9fa216c8cc5b9fc63d622ff8c58d04004730440220565d170eed95ff95027a69b313758450ba84a01224e1f7f130dda46e94d13f8602207bdd20e307f062594022f12ed5017bbf4a055a06aea91c10110a0e3bb23117fc014730440220647d2dc5b15f60bc37dc42618a370b2a1490293f9e5c8464f53ec4fe1dfe067302203598773895b4b16d37485cbe21b337f4e4b650739880098c592553add7dd4355016952210375e00eb72e29da82b89367947f29ef34afb75e8654f6ea368e0acdfd92976b7c2103a1b26313f430c4b15bb1fdce663207659d8cac749a0e53d70eff01874496feff2103c96d495bfdd5ba4145e3e046fee45e84a8a48ad05bd8dbb395c011a32cf9f88053ae00000000",
             18393430 , 0, vec![], VERIFY_ALL_PRE_TAPROOT
-        ), Err(KernelError::ScriptVerify(ScriptVerifyError::Invalid))));
+        ), Err(KernelError::ScriptVerify(ScriptVerifyError::Script(ScriptError::WitnessProgramMismatch)))));
 
         // a random taproot transaction
         let spent = "5120339ce7e165e67d93adb3fef88a6d4beed33f01fa876f05a225242b82a631abc0";

From a633c0d477bf547069390ea2da388b63b5e59050 Mon Sep 17 00:00:00 2001
From: Yeji Han <yeji.hvn@gmail.com>
Date: Thu, 5 Mar 2026 13:42:53 +0900
Subject: [PATCH 2/2] script_debug: expose decoded opcode and op_count in
 callback

---
 examples/src/script_debug.rs                  | 45 +++++++++++++------
 .../bitcoin/src/kernel/bitcoinkernel.cpp      |  6 ++-
 .../bitcoin/src/kernel/bitcoinkernel.h        |  2 +
 .../bitcoin/src/script/debug.cpp              |  5 ++-
 .../bitcoin/src/script/debug.h                | 10 ++---
 .../bitcoin/src/script/interpreter.cpp        |  8 ++--
 src/core/script_debug.rs                      |  7 +++
 tests/test.rs                                 | 31 +++++++++++++
 8 files changed, 90 insertions(+), 24 deletions(-)

diff --git a/examples/src/script_debug.rs b/examples/src/script_debug.rs
index 3520d238..6aa7c300 100644
--- a/examples/src/script_debug.rs
+++ b/examples/src/script_debug.rs
@@ -6,43 +6,62 @@ use bitcoinkernel::{
 
 fn main() {
     let _debugger = ScriptDebugger::new(|frame| {
-        println!("\nMain Stack ({} items, top last):", frame.stack.len());
-        if frame.stack.is_empty() {
-            println!("  <empty>");
-        } else {
+        let opcode_name = match frame.opcode {
+            0x00 => "OP_0",
+            0x76 => "OP_DUP",
+            0xa9 => "OP_HASH160",
+            0x87 => "OP_EQUAL",
+            0x88 => "OP_EQUALVERIFY",
+            0xac => "OP_CHECKSIG",
+            0xff => "END",
+            op if op <= 0x4b => "DATA_PUSH",
+            _ => "OTHER",
+        };
+        println!(
+            "\n[step {}] opcode=0x{:02x} ({}) op_count={} f_exec={} stack_depth={}",
+            frame.opcode_pos,
+            frame.opcode,
+            opcode_name,
+            frame.op_count,
+            frame.f_exec,
+            frame.stack.len(),
+        );
+
+        if !frame.stack.is_empty() {
+            println!("  Stack:");
             for (i, item) in frame.stack.iter().enumerate() {
                 if item.is_empty() {
-                    println!("  {}: <empty>", i);
+                    println!("    {}: <empty>", i);
                 } else {
-                    println!("  {}: 0x{}", i, hex::encode(item));
+                    println!("    {}: 0x{}", i, hex::encode(item));
                 }
             }
         }
 
         if !frame.altstack.is_empty() {
-            println!("\nAlt Stack ({} items, top last):", frame.altstack.len());
+            println!("  Altstack:");
             for (i, item) in frame.altstack.iter().enumerate() {
                 if item.is_empty() {
-                    println!("  {}: <empty>", i);
+                    println!("    {}: <empty>", i);
                 } else {
-                    println!("  {}: 0x{}", i, hex::encode(item));
+                    println!("    {}: 0x{}", i, hex::encode(item));
                 }
             }
         }
 
         let script = Script::from_bytes(&frame.script);
-        println!("Script (f_exec={}):", frame.f_exec);
+        println!("  Script:");
         for (i, op) in script.instructions().enumerate() {
             match op {
                 Ok(instruction) => {
                     if i as u32 == frame.opcode_pos {
-                        print!("  > ");
+                        print!("    > ");
                     } else {
-                        print!("    ");
+                        print!("      ");
                     }
                     println!("{:?}", instruction);
                 }
-                Err(e) => println!("    Error decoding instruction: {}", e),
+                Err(e) => println!("      Error decoding instruction: {}", e),
             }
         }
     })
diff --git a/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.cpp b/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.cpp
index 31cfae4b..a9da8290 100644
--- a/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.cpp
+++ b/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.cpp
@@ -1407,7 +1407,9 @@ void btck_register_script_debug_callback(void* user_data, btck_ScriptDebugCallba
                             const CScript& script,
                             uint32_t opcode_pos,
                             std::span<const std::vector<unsigned char>> altstack,
-                            bool fExec) {
+                            bool fExec,
+                            uint8_t opcode,
+                            int nOpCount) {
         std::vector<const unsigned char*> stack_ptrs;
         std::vector<size_t> stack_sizes;
         stack_ptrs.reserve(stack.size());
@@ -1437,6 +1439,8 @@ void btck_register_script_debug_callback(void* user_data, btck_ScriptDebugCallba
         state.altstack_item_sizes = altstack_sizes.data();
         state.altstack_size = altstack.size();
         state.f_exec = fExec ? 1 : 0;
+        state.opcode = opcode;
+        state.op_count = nOpCount;
 
         callback(user_data, &state);
     };
diff --git a/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.h b/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.h
index c372c32e..6a033342 100644
--- a/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.h
+++ b/libbitcoinkernel-sys/bitcoin/src/kernel/bitcoinkernel.h
@@ -1865,6 +1865,8 @@ typedef struct {
     const size_t* altstack_item_sizes;
     size_t altstack_size;
     int f_exec;
+    uint8_t opcode;
+    int op_count;
 } btck_ScriptDebugState;
 
 /**
diff --git a/libbitcoinkernel-sys/bitcoin/src/script/debug.cpp b/libbitcoinkernel-sys/bitcoin/src/script/debug.cpp
index f49c3b11..c798da76 100644
--- a/libbitcoinkernel-sys/bitcoin/src/script/debug.cpp
+++ b/libbitcoinkernel-sys/bitcoin/src/script/debug.cpp
@@ -11,10 +11,11 @@
 static std::mutex g_script_debug_mutex;
 static DebugScriptCallback g_script_debug_callback{nullptr};
 
-void DebugScript(std::span<const std::vector<unsigned char>> stack, const CScript& script, uint32_t opcode_pos, std::span<const std::vector<unsigned char>> altstack, bool fExec)
+void DebugScript(std::span<const std::vector<unsigned char>> stack, const CScript& script, uint32_t opcode_pos, std::span<const std::vector<unsigned char>> altstack, bool fExec, uint8_t opcode, int nOpCount)
 {
     std::lock_guard<std::mutex> lock(g_script_debug_mutex);
-    if (g_script_debug_callback) g_script_debug_callback(stack, script, opcode_pos, altstack, fExec);
+    if (g_script_debug_callback)
+        g_script_debug_callback(stack, script, opcode_pos, altstack, fExec, opcode, nOpCount);
 }
 
 void RegisterDebugScriptCallback(DebugScriptCallback func)
diff --git a/libbitcoinkernel-sys/bitcoin/src/script/debug.h b/libbitcoinkernel-sys/bitcoin/src/script/debug.h
index c656220d..67390ecd 100644
--- a/libbitcoinkernel-sys/bitcoin/src/script/debug.h
+++ b/libbitcoinkernel-sys/bitcoin/src/script/debug.h
@@ -11,17 +11,17 @@
 #include <span>
 #include <vector>
 
-using DebugScriptCallback = std::function<void(std::span<const std::vector<unsigned char>>, const CScript&, uint32_t, std::span<const std::vector<unsigned char>>, bool)>;
+using DebugScriptCallback = std::function<void(std::span<const std::vector<unsigned char>>, const CScript&, uint32_t, std::span<const std::vector<unsigned char>>, bool, uint8_t, int)>;
 
-void DebugScript(std::span<const std::vector<unsigned char>> stack, const CScript& script, uint32_t opcode_pos, std::span<const std::vector<unsigned char>> altstack, bool fExec);
+void DebugScript(std::span<const std::vector<unsigned char>> stack, const CScript& script, uint32_t opcode_pos, std::span<const std::vector<unsigned char>> altstack, bool fExec, uint8_t opcode, int nOpCount);
 
 void RegisterDebugScriptCallback(DebugScriptCallback func);
 
 #ifdef ENABLE_SCRIPT_DEBUG
-#define DEBUG_SCRIPT(stack, script, opcode_pos, altstack, fExec) \
-    DebugScript(stack, script, opcode_pos, altstack, fExec);
+#define DEBUG_SCRIPT(stack, script, opcode_pos, altstack, fExec, opcode, nOpCount) \
+    DebugScript(stack, script, opcode_pos, altstack, fExec, opcode, nOpCount);
 #else
-#define DEBUG_SCRIPT(stack, script, opcode_pos, altstack, fExec)
+#define DEBUG_SCRIPT(stack, script, opcode_pos, altstack, fExec, opcode, nOpCount)
 #endif // ENABLE_SCRIPT_DEBUG
 
 #endif // BITCOIN_SCRIPT_DEBUG_H
diff --git a/libbitcoinkernel-sys/bitcoin/src/script/interpreter.cpp b/libbitcoinkernel-sys/bitcoin/src/script/interpreter.cpp
index 0f4fa693..b5b2145e 100644
--- a/libbitcoinkernel-sys/bitcoin/src/script/interpreter.cpp
+++ b/libbitcoinkernel-sys/bitcoin/src/script/interpreter.cpp
@@ -421,7 +421,7 @@ bool EvalScript(std::vector<std::vector<unsigned char> >& stack, const CScript&
     CScript::const_iterator pc = script.begin();
     CScript::const_iterator pend = script.end();
     CScript::const_iterator pbegincodehash = script.begin();
-    opcodetype opcode;
+    opcodetype opcode = OP_INVALIDOPCODE;
     valtype vchPushValue;
     ConditionStack vfExec;
     std::vector<valtype> altstack;
@@ -439,7 +439,6 @@ bool EvalScript(std::vector<std::vector<unsigned char> >& stack, const CScript&
     {
         for (; pc < pend; ++opcode_pos) {
             bool fExec = vfExec.all_true();
-            DEBUG_SCRIPT(stack, script, opcode_pos, altstack, fExec);
 
             //
             // Read instruction
@@ -456,6 +455,8 @@ bool EvalScript(std::vector<std::vector<unsigned char> >& stack, const CScript&
                 }
             }
 
+            DEBUG_SCRIPT(stack, script, opcode_pos, altstack, fExec, static_cast<uint8_t>(opcode), nOpCount);
+
             if (opcode == OP_CAT ||
                 opcode == OP_SUBSTR ||
                 opcode == OP_LEFT ||
@@ -1230,7 +1231,8 @@ bool EvalScript(std::vector<std::vector<unsigned char> >& stack, const CScript&
         return set_error(serror, SCRIPT_ERR_UNKNOWN_ERROR);
     }
 
-    DEBUG_SCRIPT(stack, script, opcode_pos, altstack, vfExec.all_true());
+    opcode = OP_INVALIDOPCODE;
+    DEBUG_SCRIPT(stack, script, opcode_pos, altstack, vfExec.all_true(), static_cast<uint8_t>(opcode), nOpCount);
 
     if (!vfExec.empty())
         return set_error(serror, SCRIPT_ERR_UNBALANCED_CONDITIONAL);
diff --git a/src/core/script_debug.rs b/src/core/script_debug.rs
index 17b1be3a..a15396e0 100644
--- a/src/core/script_debug.rs
+++ b/src/core/script_debug.rs
@@ -24,6 +24,11 @@ pub struct ScriptDebugFrame {
     pub opcode_pos: u32,
     /// Whether the current branch is being executed (`true` = active, `false` = inside a false IF).
     pub f_exec: bool,
+    /// Decoded opcode value for the current instruction.
+    /// `0xff` (`OP_INVALIDOPCODE`) on the final callback or for empty scripts.
+    pub opcode: u8,
+    /// Cumulative count of non-push opcodes executed so far (tracks the 201-op limit).
+    pub op_count: u32,
 }
 
 /// Guard that keeps a script debug callback registered.
@@ -105,6 +110,8 @@ unsafe extern "C" fn trampoline(
             script,
             opcode_pos: state.opcode_pos,
             f_exec: state.f_exec != 0,
+            opcode: state.opcode,
+            op_count: state.op_count as u32,
         };
 
         let closure = unsafe { &mut **(user_data as *mut Box<dyn FnMut(ScriptDebugFrame)>) };
diff --git a/tests/test.rs b/tests/test.rs
index 6183ccf6..2d6207d7 100644
--- a/tests/test.rs
+++ b/tests/test.rs
@@ -705,6 +705,37 @@ mod tests {
             );
             assert!(!frame.script.is_empty(), "script bytes should be non-empty");
         }
+
+        // The P2PKH scriptPubKey is 76a914...88ac which starts with OP_DUP (0x76).
+        let p2pkh_script =
+            hex::decode("76a9144bfbaf6afb76cc5771bc6404810d1cc041a6933988ac").unwrap();
+        let p2pkh_frames: Vec<_> = collected
+            .iter()
+            .filter(|f| f.script == p2pkh_script && f.opcode != 0xff)
+            .collect();
+        assert!(
+            !p2pkh_frames.is_empty(),
+            "should have P2PKH scriptPubKey frames"
+        );
+        assert_eq!(
+            p2pkh_frames[0].opcode, 0x76,
+            "first P2PKH opcode should be OP_DUP"
+        );
+
+        // op_count should be monotonically non-decreasing within a script
+        assert!(
+            p2pkh_frames
+                .windows(2)
+                .all(|w| w[1].op_count >= w[0].op_count),
+            "op_count should be monotonically non-decreasing"
+        );
+
+        // The final frame (opcode == 0xff) should exist
+        let final_frames: Vec<_> = collected.iter().filter(|f| f.opcode == 0xff).collect();
+        assert!(
+            !final_frames.is_empty(),
+            "should have final callback frame(s) with opcode 0xff"
+        );
     }
 
     /// Multiple threads race to register a debugger — at most one should be active at a time.