From 221e604ca9e3dba2e2e5b0a77d0e16ded8d55ff0 Mon Sep 17 00:00:00 2001
From: Antoine Poinsot <mail@antoinep.com>
Date: Mon, 8 Dec 2025 11:56:01 -0500
Subject: [PATCH 1/5] binana: add OP_TEMPLATEHASH

---
 src/binana/templatehash.json             | 9 +++++++++
 test/functional/test_framework/script.py | 5 ++++-
 2 files changed, 13 insertions(+), 1 deletion(-)
 create mode 100644 src/binana/templatehash.json

diff --git a/src/binana/templatehash.json b/src/binana/templatehash.json
new file mode 100644
index 000000000000..ae29f8f00f7d
--- /dev/null
+++ b/src/binana/templatehash.json
@@ -0,0 +1,9 @@
+{
+    "binana": [2026, 1, 0],
+    "deployment": "TEMPLATEHASH",
+    "scriptverify": true,
+    "scriptverify_discourage": true,
+    "opcodes": {
+        "TEMPLATEHASH": "0xce"
+    }
+}
diff --git a/test/functional/test_framework/script.py b/test/functional/test_framework/script.py
index 0a33838b1276..f83f24798e02 100644
--- a/test/functional/test_framework/script.py
+++ b/test/functional/test_framework/script.py
@@ -256,6 +256,8 @@ def __new__(cls, n):
 
 OP_CHECKSIGFROMSTACK = CScriptOp(0xcc)
 OP_INTERNALKEY = CScriptOp(0xcb)
+# BIP xx opcode (Tapscript-only, formerly OP_SUCCESS187)
+OP_TEMPLATEHASH = CScriptOp(0xce)
 
 OP_INVALIDOPCODE = CScriptOp(0xff)
 
@@ -372,6 +374,7 @@ def __new__(cls, n):
     OP_NOP9: 'OP_NOP9',
     OP_NOP10: 'OP_NOP10',
     OP_CHECKSIGADD: 'OP_CHECKSIGADD',
+    OP_TEMPLATEHASH: 'OP_TEMPLATEHASH',
     OP_INVALIDOPCODE: 'OP_INVALIDOPCODE',
 })
 
@@ -969,7 +972,7 @@ def taproot_construct(pubkey, scripts=None, *, keyver=None, treat_internal_as_in
     return TaprootInfo(CScript([OP_1, tweaked]), pubkey, negated + 0, tweak, leaves, h, tweaked, keyver)
 
 def is_op_success(o):
-    if o in [OP_CAT, OP_CHECKSIGFROMSTACK, OP_INTERNALKEY]:
+    if o in [OP_CAT, OP_CHECKSIGFROMSTACK, OP_INTERNALKEY, OP_TEMPLATEHASH]:
         return False
 
     return o == 0x50 or o == 0x62 or o == 0x89 or o == 0x8a or o == 0x8d or o == 0x8e or (o >= 0x7e and o <= 0x81) or (o >= 0x83 and o <= 0x86) or (o >= 0x95 and o <= 0x99) or (o >= 0xbb and o <= 0xfe)

From 21e6fd8f58fec400f434e0a92813067a672c58f7 Mon Sep 17 00:00:00 2001
From: Antoine Poinsot <darosior@protonmail.com>
Date: Tue, 10 Jun 2025 17:25:39 -0400
Subject: [PATCH 2/5] script: implement OP_TEMPLATEHASH

This introduces a new Script operation exclusively available in Tapscript context: OP_TEMPLATEHASH.
This operation pushes the hash of the spending transaction on the stack. See BIP 446 for details.

This operation is introduced as replacing OP_SUCCESS206 (0xce).

Co-Authored-By: Greg Sanders <gsanders87@gmail.com>
---
 src/script/interpreter.cpp | 37 +++++++++++++++++++++++++++++++++++++
 src/script/interpreter.h   | 11 +++++++++++
 2 files changed, 48 insertions(+)

diff --git a/src/script/interpreter.cpp b/src/script/interpreter.cpp
index 0617c424cbbd..be2eafc6f8a0 100644
--- a/src/script/interpreter.cpp
+++ b/src/script/interpreter.cpp
@@ -1377,6 +1377,20 @@ bool EvalScript(std::vector<std::vector<unsigned char> >& stack, const CScript&
                     break;
                 }
 
+                case OP_TEMPLATEHASH:
+                {
+                    // OP_TEMPLATEHASH is only available in Tapscript. Note this is the exact same error
+                    // returned in the default case, which would be the one hit by OP_SUCCESS187 before
+                    // the introduction of OP_TEMPLATEHASH.
+                    if (sigversion == SigVersion::BASE || sigversion == SigVersion::WITNESS_V0) {
+                        return set_error(serror, SCRIPT_ERR_BAD_OPCODE);
+                    }
+
+                    const uint256 template_hash{checker.GetTemplateHash(execdata)};
+                    stack.emplace_back(template_hash.begin(), template_hash.end());
+                }
+                break;
+
                 default:
                     return set_error(serror, SCRIPT_ERR_BAD_OPCODE);
             }
@@ -1698,6 +1712,7 @@ template PrecomputedTransactionData::PrecomputedTransactionData(const CMutableTr
 const HashWriter HASHER_TAPSIGHASH{TaggedHash("TapSighash")};
 const HashWriter HASHER_TAPLEAF{TaggedHash("TapLeaf")};
 const HashWriter HASHER_TAPBRANCH{TaggedHash("TapBranch")};
+const HashWriter HASHER_TEMPLATEHASH{TaggedHash("TemplateHash")};
 
 static bool HandleMissingData(MissingDataBehavior mdb)
 {
@@ -2098,6 +2113,28 @@ bool GenericTransactionSignatureChecker<T>::CheckDefaultCheckTemplateVerifyHash(
         return HandleMissingData(m_mdb);
     }
 }
+
+template<class T>
+uint256 GenericTransactionSignatureChecker<T>::GetTemplateHash(ScriptExecutionData& execdata) const
+{
+    assert(txdata && txdata->m_bip341_taproot_ready);
+    assert(execdata.m_annex_init);
+
+    HashWriter ss{HASHER_TEMPLATEHASH};
+    ss << txTo->version;
+    ss << txTo->nLockTime;
+    ss << txdata->m_sequences_single_hash;
+    ss << txdata->m_outputs_single_hash;
+    const uint8_t annex_present = (execdata.m_annex_present ? 1 : 0);
+    ss << annex_present;
+    ss << nIn;
+    if (execdata.m_annex_present) {
+        ss << execdata.m_annex_hash;
+    }
+
+    return ss.GetSHA256();
+}
+
 // explicit instantiation
 template class GenericTransactionSignatureChecker<CTransaction>;
 template class GenericTransactionSignatureChecker<CMutableTransaction>;
diff --git a/src/script/interpreter.h b/src/script/interpreter.h
index e334ed445fcc..7b06316d4feb 100644
--- a/src/script/interpreter.h
+++ b/src/script/interpreter.h
@@ -335,6 +335,11 @@ class BaseSignatureChecker
         return false;
     }
 
+    virtual uint256 GetTemplateHash(ScriptExecutionData& execdata) const
+    {
+        return {};
+    }
+
     virtual ~BaseSignatureChecker() = default;
 };
 
@@ -373,6 +378,7 @@ class GenericTransactionSignatureChecker : public BaseSignatureChecker
     bool CheckLockTime(const CScriptNum& nLockTime) const override;
     bool CheckSequence(const CScriptNum& nSequence) const override;
     bool CheckDefaultCheckTemplateVerifyHash(const Span<const unsigned char>& hash) const override;
+    uint256 GetTemplateHash(ScriptExecutionData& execdata) const override;
 };
 
 using TransactionSignatureChecker = GenericTransactionSignatureChecker<CTransaction>;
@@ -404,6 +410,11 @@ class DeferringSignatureChecker : public BaseSignatureChecker
     {
         return m_checker.CheckSequence(nSequence);
     }
+
+    uint256 GetTemplateHash(ScriptExecutionData& execdata) const override
+    {
+        return m_checker.GetTemplateHash(execdata);
+    }
 };
 
 /** Compute the BIP341 tapleaf hash from leaf version & script. */

From 33192a8014669b80158cbcaceaecba2a8705f6d6 Mon Sep 17 00:00:00 2001
From: Antoine Poinsot <darosior@protonmail.com>
Date: Wed, 11 Jun 2025 15:56:14 -0400
Subject: [PATCH 3/5] qa: unit tests to sanity check OP_TEMPLATEHASH

Sanity check the template hash by using it to commit to the transaction that must spend an output.
Malleating committed fields must lead to a consensus failure, and changing non-committed fields is
fine.

We also add the option to generate test vectors from this unit test.
---
 src/test/script_tests.cpp | 286 ++++++++++++++++++++++++++++++++++++++
 src/test/util/script.h    |  39 ++++++
 2 files changed, 325 insertions(+)

diff --git a/src/test/script_tests.cpp b/src/test/script_tests.cpp
index feaf56bacb4f..e1b910a0170e 100644
--- a/src/test/script_tests.cpp
+++ b/src/test/script_tests.cpp
@@ -10,6 +10,7 @@
 #include <core_io.h>
 #include <deploymentinfo.h>
 #include <key.h>
+#include <policy/policy.h>
 #include <rpc/util.h>
 #include <script/script.h>
 #include <script/script_error.h>
@@ -20,6 +21,7 @@
 #include <streams.h>
 #include <test/util/json.h>
 #include <test/util/random.h>
+#include <test/util/script.h>
 #include <test/util/setup_common.h>
 #include <test/util/transaction_utils.h>
 #include <util/fs.h>
@@ -1838,4 +1840,288 @@ BOOST_AUTO_TEST_CASE(cat_dup_test)
     }
 }
 
+/** A test vector for OP_TEMPLATEHASH. */
+struct TemplateHashTestCase
+{
+    //! The transaction being validated.
+    const CTransaction spending_tx;
+    //! The outputs spent by the transaction being validated.
+    const std::vector<CTxOut> spent_outputs;
+    //! The index of the transaction input being validated.
+    const uint32_t input_index;
+    //! Whether script validation is expected to succeed.
+    const bool valid;
+    //! Description of the test vector.
+    const std::string comment;
+
+    explicit TemplateHashTestCase(std::vector<CTxOut> spent_txos, CTransaction tx, uint32_t idx, bool val, std::string com):
+        spending_tx{std::move(tx)}, spent_outputs{std::move(spent_txos)}, input_index{idx}, valid{val}, comment{std::move(com)} {}
+
+    UniValue GetJson() const
+    {
+        UniValue json{UniValue::VOBJ}, spent_txos{UniValue::VARR};
+        for (const auto& txo: spent_outputs) {
+            DataStream ssTxo;
+            ssTxo << txo;
+            spent_txos.push_back(HexStr(ssTxo));
+        }
+        json.pushKV("spent_outputs", std::move(spent_txos));
+        json.pushKV("spending_tx", EncodeHexTx(spending_tx));
+        json.pushKV("input_index", input_index);
+        json.pushKV("valid", valid);
+        json.pushKV("comment", comment);
+        return json;
+    }
+};
+
+/** Shorthand for making a copy of a vector. **/
+template<typename T>
+static std::vector<T> Clone(std::vector<T>& vec)
+{
+    return std::vector<T>{vec};
+}
+
+/** Run script validation for provided tx and input index. Check it succeeds/fails according to provided validity status. **/
+static void CheckTemplateMatch(const CMutableTransaction& tx, std::vector<CTxOut> spent_outputs, unsigned in_index,
+                               bool is_valid, std::vector<TemplateHashTestCase>& cases, std::string comment)
+{
+    Assert(tx.vin.size() == spent_outputs.size() && in_index < tx.vin.size());
+    constexpr auto FLAGS{MANDATORY_SCRIPT_VERIFY_FLAGS | SCRIPT_VERIFY_TEMPLATEHASH};
+    constexpr CAmount dummy_am{0}; // We never check signatures.
+    constexpr auto dummy_mdb{MissingDataBehavior::ASSERT_FAIL};
+    const auto spent_spk{spent_outputs[in_index].scriptPubKey};
+
+    // Record for test vector generation.
+    cases.emplace_back(spent_outputs, CTransaction{tx}, in_index, is_valid, comment);
+
+    // Perform script validation with the provided inputs.
+    PrecomputedTransactionData precomp;
+    precomp.Init(tx, std::move(spent_outputs));
+    const auto checker{GenericTransactionSignatureChecker(&tx, in_index, dummy_am, precomp, dummy_mdb)};
+    ScriptError err;
+    bool res{VerifyScript(tx.vin[in_index].scriptSig, spent_spk, &tx.vin[in_index].scriptWitness, FLAGS, checker, &err)};
+
+    // Check script validation result, if not valid make sure the failure is the one expected for `<hash> OP_TEMPLATEHASH OP_EQUAL`.
+    BOOST_CHECK_MESSAGE(res == is_valid, std::string{"Script validation unexpectedly "} + (res ? "succeeded" : "failed") + ": " + comment);
+    if (!is_valid) {
+        BOOST_CHECK_MESSAGE(err == ScriptError::SCRIPT_ERR_EVAL_FALSE, std::string{"Unexpected error for '"} + comment + "': " + ScriptErrorString(err));
+    }
+}
+
+/** Sanity check next-transaction commitments using OP_TEMPLATEHASH. */
+BOOST_AUTO_TEST_CASE(templatehash)
+{
+    // Record the various cases exercised in this test to optionally generate vectors at the end.
+    std::vector<TemplateHashTestCase> test_cases;
+
+    // The transaction whose template hash is to be checked.
+    CMutableTransaction tx;
+    tx.vin = {
+        CTxIn{*Txid::FromHex("0437cd7f8525ceed2324359c2d0ba26006d92d856a9c20fa0241106ee5a597c9"), 21},
+        CTxIn{*Txid::FromHex("f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16"), 12}
+    };
+    tx.vout.emplace_back(424242, ScriptFromHex("001482074bdf6ce32b071dd120a17cf99cbc01ad3080"));
+
+    // Construct the script to be spent, checking the (valid) hash of this transaction.
+    const uint256 vanilla_hash{GetTemplateHash(tx, 0)};
+    const auto leaf_script{CScript() << vanilla_hash << OP_TEMPLATEHASH << OP_EQUAL};
+    TaprootBuilder builder;
+    builder.Add(0, leaf_script, TAPROOT_LEAF_TAPSCRIPT);
+    builder.Finalize(XOnlyPubKey::NUMS_H);
+    const CScript spent_spk{GetScriptForDestination(builder.GetOutput())};
+
+    // Outputs spent by the transaction whose template hash is to be checked.
+    CTxOut dummy_txo{1'085'986, ScriptFromHex("76a914079ded3e3befdab0757fe0e8842aeffc0ff2160288ac")};
+    std::vector<CTxOut> spent_outputs{{CTxOut{424243, spent_spk}, dummy_txo}};
+
+    // Construct the witness data for the transaction.
+    const auto spend_data{builder.GetSpendData()};
+    const auto control_blocks{spend_data.scripts.begin()->second};
+    const auto& cb{*control_blocks.begin()};
+    tx.vin[0].scriptWitness.stack.emplace_back(leaf_script.begin(), leaf_script.end());
+    tx.vin[0].scriptWitness.stack.emplace_back(cb.begin(), cb.end());
+
+    // Script validation must pass when we use the right hash for the right input.
+    {
+        CheckTemplateMatch(tx, Clone(spent_outputs), 0, /*is_valid=*/true, test_cases, std::string{"Template hash matches. Input index matches."});
+    }
+
+    // Script validation must pass when we use the right hash for the wrong input.
+    {
+        // Swap the two inputs and corresponding spent utxos.
+        CMutableTransaction tx2{tx};
+        std::swap(tx2.vin[0], tx2.vin[1]);
+        auto spent_outputs2{spent_outputs};
+        std::swap(spent_outputs2[0], spent_outputs2[1]);
+
+        CheckTemplateMatch(tx2, std::move(spent_outputs2), 1, /*is_valid=*/false, test_cases, std::string{"Template hash matches. Input index mismatches."});
+    }
+
+    // Script validation must fail if any committed field is malleated in the transaction.
+    // Version:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.version = 42;
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/false, test_cases, std::string{"Template hash mismatches: incorrect transaction version."});
+    }
+    // Locktime:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.nLockTime = 42;
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/false, test_cases, std::string{"Template hash mismatches: incorrect transaction locktime."});
+    }
+    // Output value:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.vout[0].nValue++;
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/false, test_cases, std::string{"Template hash mismatches: incorrect output value."});
+    }
+    // Output script:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.vout[0].scriptPubKey = ScriptFromHex("001482074bdf6ce32b071dd120a17cf99cbc01ad3081");
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/false, test_cases, std::string{"Template hash mismatches: incorrect output script."});
+    }
+    // This input's sequence:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.vin[0].nSequence = 42;
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/false, test_cases, std::string{"Template hash mismatches: incorrect sequence in spending input."});
+    }
+    // Another input's sequence:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.vin[1].nSequence = 42;
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/false, test_cases, std::string{"Template hash mismatches: incorrect sequence in another input."});
+    }
+    // This input's annex:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.vin[0].scriptWitness.stack.push_back({ANNEX_TAG, 0});
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/false, test_cases, std::string{"Template hash mismatches: spending input contains annex but none was committed."});
+    }
+
+    // Script validation must succeed if a non-committed transaction field is malleated.
+    // Another input's annex:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.vin[1].scriptWitness.stack.push_back({ANNEX_TAG, 'd', 'u', 'm', 'm', 'y'});
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/true, test_cases, std::string{"Template hash matches with malleated annex for another input."});
+    }
+    // Another input's scriptsig:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.vin[1].scriptSig.resize(1);
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/true, test_cases, std::string{"Template hash matches with malleated scriptSig for another input."});
+    }
+    // This input's prevout:
+    COutPoint dummy_op{*Txid::FromHex("27c4d937dca276fb2b61e579902e8a876fd5b5abc17590410ced02d5a9f8e483"), 42};
+    {
+        CMutableTransaction tx2{tx};
+        tx2.vin[0].prevout = dummy_op;
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/true, test_cases, std::string{"Template hash matches with malleated prevout for spending input."});
+    }
+    // Another input's prevout:
+    {
+        CMutableTransaction tx2{tx};
+        tx2.vin[1].prevout = dummy_op;
+        CheckTemplateMatch(tx2, Clone(spent_outputs), 0, /*is_valid=*/true, test_cases, std::string{"Template hash matches with malleated prevout for another input."});
+    }
+    // Spent output's value:
+    {
+        std::vector<CTxOut> spent_outputs2(spent_outputs);
+        ++spent_outputs2[0].nValue;
+        CheckTemplateMatch(tx, std::move(spent_outputs2), 0, /*is_valid=*/true, test_cases, std::string{"Template hash matches with malleated value for corresponding spent output."});
+    }
+    // Other spent output's value:
+    {
+        std::vector<CTxOut> spent_outputs2(spent_outputs);
+        ++spent_outputs2[1].nValue;
+        CheckTemplateMatch(tx, std::move(spent_outputs2), 0, /*is_valid=*/true, test_cases, std::string{"Template hash matches with malleated value for other spent output."});
+    }
+    // Other spent output's scriptpubkey:
+    {
+        std::vector<CTxOut> spent_outputs2(spent_outputs);
+        spent_outputs2[1].scriptPubKey = ScriptFromHex("0014266a4832c001885db26e853ef1d1dde840f7dbaf");
+        CheckTemplateMatch(tx, std::move(spent_outputs2), 0, /*is_valid=*/true, test_cases, std::string{"Template hash matches with malleated scriptpubkey for other spent output."});
+    }
+
+    // Same transaction but different hash
+    {
+        CMutableTransaction tx2{tx};
+        auto spent_outputs2{spent_outputs};
+
+        // Re-build the scriptpubkey with a leaf script containing the check against a dummy hash instead.
+        std::vector<uint8_t> dummy_hash(32);
+        const auto leaf_script2{CScript() << dummy_hash << OP_TEMPLATEHASH << OP_EQUAL};
+        TaprootBuilder builder2;
+        builder2.Add(0, leaf_script2, TAPROOT_LEAF_TAPSCRIPT);
+        builder2.Finalize(XOnlyPubKey::NUMS_H);
+        spent_outputs2[0].scriptPubKey = GetScriptForDestination(builder2.GetOutput());
+
+        // Re-build the spending transaction's witness.
+        const auto spend_data{builder2.GetSpendData()};
+        const auto control_blocks{spend_data.scripts.begin()->second};
+        const auto& cb{*control_blocks.begin()};
+        tx2.vin[0].scriptWitness.stack.clear();
+        tx2.vin[0].scriptWitness.stack.emplace_back(leaf_script2.begin(), leaf_script2.end());
+        tx2.vin[0].scriptWitness.stack.emplace_back(cb.begin(), cb.end());
+
+        // Verification must fail, the hash does not correspond to this transaction.
+        CheckTemplateMatch(tx2, std::move(spent_outputs2), 0, /*is_valid=*/false, test_cases, std::string{"Template hash mismatches: spending a script with a different committed hash."});
+    }
+
+    // We can also commit to a transaction which contains an annex.
+    {
+        CMutableTransaction tx2{tx};
+        auto spent_outputs2{spent_outputs};
+
+        // Set an annex to the transaction.
+        std::vector<uint8_t> annex{ANNEX_TAG, 'd', 'a', 't', 'a'};
+        tx2.vin[0].scriptWitness.stack.push_back(annex);
+
+        // Sanity check this transaction isn't valid according to our previous commitment (but don't
+        // record it, as this error already was above).
+        std::vector<TemplateHashTestCase> dummy_cases;
+        CheckTemplateMatch(tx2, Clone(spent_outputs2), 0, /*is_valid=*/false, dummy_cases, std::string{});
+
+        // Re-build the scriptpubkey with a leaf script containing the template hash committing to the annex.
+        const uint256 hash_with_annex{GetTemplateHash(tx2, 0)};
+        const auto leaf_script2{CScript() << hash_with_annex << OP_TEMPLATEHASH << OP_EQUAL};
+        TaprootBuilder builder2;
+        builder2.Add(0, leaf_script2, TAPROOT_LEAF_TAPSCRIPT);
+        builder2.Finalize(XOnlyPubKey::NUMS_H);
+        spent_outputs2[0].scriptPubKey = GetScriptForDestination(builder2.GetOutput());
+
+        // Re-build the spending transaction's witness.
+        const auto spend_data{builder2.GetSpendData()};
+        const auto control_blocks{spend_data.scripts.begin()->second};
+        const auto& cb{*control_blocks.begin()};
+        tx2.vin[0].scriptWitness.stack.clear();
+        tx2.vin[0].scriptWitness.stack.emplace_back(leaf_script2.begin(), leaf_script2.end());
+        tx2.vin[0].scriptWitness.stack.emplace_back(cb.begin(), cb.end());
+        tx2.vin[0].scriptWitness.stack.emplace_back(annex.begin(), annex.end());
+
+        // Verification must pass if the commitment is for the transaction with this annex.
+        CheckTemplateMatch(tx2, Clone(spent_outputs2), 0, /*is_valid=*/true, test_cases, std::string{"Template hash matches in the presence of an annex."});
+
+        // But must fail for a transaction with another annex.
+        std::vector<uint8_t> other_annex{ANNEX_TAG, 'J', 'P', 'E', 'G'};
+        tx2.vin[0].scriptWitness.stack.back() = other_annex;
+        CheckTemplateMatch(tx2, std::move(spent_outputs2), 0, /*is_valid=*/false, test_cases, std::string{"Template hash mismatches: spending with a different annex than that committed."});
+    }
+
+    // Optionally dump test vectors as JSON. Uncomment UPDATE_JSON_TESTS at the top of this file to use.
+#ifdef UPDATE_JSON_TESTS
+    UniValue json_cases{UniValue::VARR};
+    for (const auto& test_case: test_cases) {
+        json_cases.push_back(test_case.GetJson());
+    }
+    const auto json_str{JSONPrettyPrint(json_cases)};
+    FILE* file = fsbridge::fopen("templatehash_tests.json.gen", "w");
+    fputs(json_str.c_str(), file);
+    fclose(file);
+#endif
+}
+
 BOOST_AUTO_TEST_SUITE_END()
diff --git a/src/test/util/script.h b/src/test/util/script.h
index 2f11fa797f21..e77d7f1211f0 100644
--- a/src/test/util/script.h
+++ b/src/test/util/script.h
@@ -6,8 +6,10 @@
 #define BITCOIN_TEST_UTIL_SCRIPT_H
 
 #include <crypto/sha256.h>
+#include <script/interpreter.h>
 #include <script/script.h>
 #include <script/verify_flags.h>
+#include <util/check.h>
 
 static const std::vector<uint8_t> WITNESS_STACK_ELEM_OP_TRUE{uint8_t{OP_TRUE}};
 static const CScript P2WSH_OP_TRUE{
@@ -34,4 +36,41 @@ static const std::vector<std::vector<uint8_t>> P2WSH_EMPTY_TWO_STACK{{static_cas
 /** Flags that are not forbidden by an assert in script validation */
 bool IsValidFlagCombination(script_verify_flags flags);
 
+/** Helper to compute the template hash of a transaction as computed by OP_TEMPLATEHASH. */
+template<class T>
+uint256 GetTemplateHash(const T& tx, unsigned int in_index, std::vector<uint8_t>* out_annex = nullptr)
+{
+    Assert(in_index < tx.vin.size());
+
+    // Initialize the precomputed fields used in computing the template hash.
+    PrecomputedTransactionData precomp;
+    {
+        std::vector<CTxOut> dummy_spent(tx.vin.size());
+        precomp.Init(tx, std::move(dummy_spent), /*force=*/true);
+    }
+    Assert(precomp.m_bip341_taproot_ready);
+
+    // Detect the presence of an annex at the specified input.
+    ScriptExecutionData execdata;
+    execdata.m_annex_present = false;
+    const auto& stack{tx.vin[in_index].scriptWitness.stack};
+    if (!stack.empty()) {
+        const auto& top_elem{tx.vin[in_index].scriptWitness.stack.back()};
+        execdata.m_annex_present = !top_elem.empty() && top_elem[0] == ANNEX_TAG;
+        if (execdata.m_annex_present) {
+            execdata.m_annex_hash = (HashWriter{} << top_elem).GetSHA256();
+            if (out_annex) {
+                *out_annex = top_elem;
+            }
+        }
+    }
+    execdata.m_annex_init = true;
+
+    // Compute the template hash.
+    const CAmount dummy_am{0};
+    const auto dummy_mdb{MissingDataBehavior::ASSERT_FAIL};
+    const auto checker{GenericTransactionSignatureChecker(&tx, in_index, dummy_am, precomp, dummy_mdb)};
+    return checker.GetTemplateHash(execdata);
+}
+
 #endif // BITCOIN_TEST_UTIL_SCRIPT_H

From b6b35c6cde6c932894daf6d01ea76dba490ed898 Mon Sep 17 00:00:00 2001
From: Antoine Poinsot <darosior@protonmail.com>
Date: Wed, 11 Jun 2025 10:41:48 -0400
Subject: [PATCH 4/5] fuzz: add two fuzz targets for OP_TEMPLATEHASH

We introduce one specialized target focused on exercising the new `GetTemplateHash()` logic
introduced for OP_TEMPLATEHASH, and one broader fuzz target which exercises using OP_TEMPLATEHASH
on a variety of transactions while asserting invariants.
---
 src/test/fuzz/CMakeLists.txt   |   1 +
 src/test/fuzz/templatehash.cpp | 189 +++++++++++++++++++++++++++++++++
 2 files changed, 190 insertions(+)
 create mode 100644 src/test/fuzz/templatehash.cpp

diff --git a/src/test/fuzz/CMakeLists.txt b/src/test/fuzz/CMakeLists.txt
index 79420b485d42..69b7c9c2e567 100644
--- a/src/test/fuzz/CMakeLists.txt
+++ b/src/test/fuzz/CMakeLists.txt
@@ -119,6 +119,7 @@ add_executable(fuzz
   string.cpp
   strprintf.cpp
   system.cpp
+  templatehash.cpp
   timeoffsets.cpp
   torcontrol.cpp
   transaction.cpp
diff --git a/src/test/fuzz/templatehash.cpp b/src/test/fuzz/templatehash.cpp
new file mode 100644
index 000000000000..4588ca0ea457
--- /dev/null
+++ b/src/test/fuzz/templatehash.cpp
@@ -0,0 +1,189 @@
+// Copyright (c) 2009-present The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#include <addresstype.h>
+#include <consensus/amount.h>
+#include <policy/policy.h>
+#include <primitives/transaction.h>
+#include <script/interpreter.h>
+#include <script/script.h>
+#include <script/signingprovider.h>
+#include <test/fuzz/FuzzedDataProvider.h>
+#include <test/fuzz/fuzz.h>
+#include <test/fuzz/util.h>
+#include <test/util/script.h>
+
+//! Maximum number of inputs and outputs in transactions consumed from fuzzer.
+static constexpr int MAX_TX_IN_OUT{10'000};
+//! Verification flags to set for script validation.
+static constexpr auto VERIFY_FLAGS{MANDATORY_SCRIPT_VERIFY_FLAGS | SCRIPT_VERIFY_TEMPLATEHASH};
+
+static bool VerifyTemplateCheck(const CMutableTransaction& tx, unsigned int in_index,
+                                std::vector<CTxOut> spent_outputs, const CScript& spent_spk)
+{
+    constexpr auto mdb{MissingDataBehavior::ASSERT_FAIL};
+    constexpr CAmount dummy_am{0}; // We never check signatures.
+    PrecomputedTransactionData precomp;
+    precomp.Init(tx, std::move(spent_outputs));
+    const auto checker{GenericTransactionSignatureChecker(&tx, in_index, dummy_am, precomp, mdb)};
+    return VerifyScript(tx.vin[in_index].scriptSig, spent_spk, &tx.vin[in_index].scriptWitness, VERIFY_FLAGS, checker);
+}
+
+/** Target specialized on the new logic introduced for OP_TEMPLATEHASH. */
+FUZZ_TARGET(gettemplatehash)
+{
+    FuzzedDataProvider provider(buffer.data(), buffer.size());
+
+    // First get the transaction for which to generate the template hash. It's unnecessary to
+    // get the fuzzer to try to find a valid deserialization, as only the version+locktime is
+    // used by GetTemplateHash().
+    CMutableTransaction tx;
+    tx.version = provider.ConsumeIntegral<uint32_t>();
+    tx.nLockTime = provider.ConsumeIntegral<uint32_t>();
+
+    // Manually set the precomputed values used in the template hash.
+    PrecomputedTransactionData precomp{tx};
+    precomp.m_sequences_single_hash = ConsumeUInt256(provider);
+    precomp.m_outputs_single_hash = ConsumeUInt256(provider);
+    precomp.m_bip341_taproot_ready = true;
+
+    // Sometimes commit to the annex too.
+    ScriptExecutionData execdata;
+    execdata.m_annex_present = provider.ConsumeBool();
+    if (execdata.m_annex_present) {
+        execdata.m_annex_hash = ConsumeUInt256(provider);
+    }
+    execdata.m_annex_init = true;
+
+    // Finally, exercise the GetTemplateHash() function.
+    const auto in_index{provider.ConsumeIntegral<unsigned>()};
+    const CAmount dummy_am{0};
+    const auto dummy_mdb{MissingDataBehavior::ASSERT_FAIL};
+    const auto checker{GenericTransactionSignatureChecker(&tx, in_index, dummy_am, precomp, dummy_mdb)};
+    (void)checker.GetTemplateHash(execdata);
+}
+
+/** Broader target which exercises the commit-to-spending transaction use case of OP_TEMPLATEHASH for
+ * various fuzzer-provided transactions and asserts invariants. */
+FUZZ_TARGET(spendtemplatehash)
+{
+    FuzzedDataProvider provider(buffer.data(), buffer.size());
+
+    // Compute the template hash for a fuzzer-provided transaction and input index.
+    std::vector<uint8_t> annex;
+    auto tx{ConsumeTransaction(provider, {}, MAX_TX_IN_OUT, MAX_TX_IN_OUT)};
+    if (tx.vin.empty()) return;
+    const auto in_index{provider.ConsumeIntegralInRange<unsigned int>(0, tx.vin.size() - 1)};
+    const auto template_hash{GetTemplateHash(tx, in_index, &annex)};
+
+    // Construct the output script committing to this template hash.
+    const auto leaf_script{CScript() << template_hash << OP_TEMPLATEHASH << OP_EQUAL};
+    TaprootBuilder builder;
+    builder.Add(0, leaf_script, TAPROOT_LEAF_TAPSCRIPT);
+    builder.Finalize(XOnlyPubKey::NUMS_H);
+    const CScript spent_spk{GetScriptForDestination(builder.GetOutput())};
+
+    // Set the witness for this transaction input.
+    const auto spend_data{builder.GetSpendData()};
+    const auto control_blocks{spend_data.scripts.begin()->second};
+    const auto& cb{*control_blocks.begin()};
+    tx.vin[in_index].scriptWitness.stack.clear();
+    tx.vin[in_index].scriptWitness.stack.emplace_back(leaf_script.begin(), leaf_script.end());
+    tx.vin[in_index].scriptWitness.stack.emplace_back(cb.begin(), cb.end());
+    if (!annex.empty()) {
+        tx.vin[in_index].scriptWitness.stack.emplace_back(annex);  // NOTE: a good way to test the target is to comment out this line
+    }
+
+    // Get the vector of spent outputs from the fuzzer. No spent output are taken into account in
+    // computing the template hash. Therefore the specific values of the other spent outputs can
+    // be set freely. However the spent output referred to by the input being verified must be
+    // correctly set to a Taproot scriptpubkey for bip341 subfields to be precomputed.
+    std::vector<CTxOut> spent_outputs(tx.vin.size());
+    for (unsigned i{0}; i < spent_outputs.size(); ++i) {
+        spent_outputs[i].scriptPubKey = i == in_index ? spent_spk : ConsumeScript(provider);
+        spent_outputs[i].nValue = ConsumeMoney(provider);
+    }
+
+    // Run script validation for this transaction input. It must pass.
+    tx.vin[in_index].scriptSig.clear(); // witness requires empty scriptSig
+    Assert(VerifyTemplateCheck(tx, in_index, std::vector<CTxOut>(spent_outputs), spent_spk));
+
+    // Malleate a field of the spending transaction and assert whether it invalidates the spend.
+    CallOneOf(
+        provider,
+        // Changing version will invalidate template hash.
+        [&] {
+            const auto prev_version{tx.version};
+            tx.version = provider.ConsumeIntegral<uint32_t>();
+            const bool version_changed{tx.version != prev_version};
+            Assert(VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk) == !version_changed);
+        },
+        // Changing locktime will invalidate template hash.
+        [&] {
+            const auto prev_locktime{tx.nLockTime};
+            tx.nLockTime = provider.ConsumeIntegral<uint32_t>();
+            const bool locktime_changed{tx.nLockTime != prev_locktime};
+            Assert(VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk) == !locktime_changed);
+        },
+        // Changing the sequence of any input will invalidate template hash.
+        [&] {
+            const auto i{provider.ConsumeIntegralInRange<size_t>(0, tx.vin.size() - 1)};
+            const auto prev_sequence{tx.vin[i].nSequence};
+            tx.vin[i].nSequence = provider.ConsumeIntegral<uint32_t>();
+            const bool seq_changed{tx.vin[i].nSequence != prev_sequence};
+            Assert(VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk) == !seq_changed);
+        },
+        // Changing the prevout of any input will not invalidate template hash.
+        [&] {
+            const auto i{provider.ConsumeIntegralInRange<size_t>(0, tx.vin.size() - 1)};
+            tx.vin[i].prevout.hash = Txid::FromUint256(ConsumeUInt256(provider));
+            tx.vin[i].prevout.n = provider.ConsumeIntegral<uint32_t>();
+            Assert(VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk));
+        },
+        // Changing the scriptSig of an input will only make Script validation fail if it malleates
+        // that of the input being validated (because Segwit mandates empty scriptSig).
+        [&] {
+            const auto i{provider.ConsumeIntegralInRange<size_t>(0, tx.vin.size() - 1)};
+            tx.vin[i].scriptSig = ConsumeScript(provider);
+            Assert(VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk) == tx.vin[in_index].scriptSig.empty());
+        },
+        // Changing the annex of the spending input will invalidate template hash. Changing the
+        // witness of any other input will not invalidate template hash.
+        [&] {
+            const auto i{provider.ConsumeIntegralInRange<size_t>(0, tx.vin.size() - 1)};
+            if (i == in_index) {
+                // Don't necessarily create a well-formatted annex.
+                auto new_annex{ConsumeRandomLengthByteVector(provider)};
+                const bool expect_failure{annex.empty() || annex != new_annex};
+                if (annex.empty()) {
+                    tx.vin[i].scriptWitness.stack.emplace_back();
+                }
+                tx.vin[i].scriptWitness.stack.back() = std::move(new_annex);
+                Assert(VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk) == !expect_failure);
+            } else {
+                tx.vin[i].scriptWitness = ConsumeScriptWitness(provider);
+                Assert(VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk));
+            }
+        },
+        // Changing the value of any output will invalidate template hash.
+        [&] {
+            if (tx.vout.empty()) return;
+            const auto i{provider.ConsumeIntegralInRange<size_t>(0, tx.vout.size() - 1)};
+            const auto prev_value{tx.vout[i].nValue};
+            tx.vout[i].nValue = provider.ConsumeIntegral<CAmount>();
+            const bool value_changed{tx.vout[i].nValue != prev_value};
+            Assert(VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk) == !value_changed);
+        },
+        // Changing the scriptPubKey of any output will invalidate template hash.
+        [&] {
+            if (tx.vout.empty()) return;
+            const auto i{provider.ConsumeIntegralInRange<size_t>(0, tx.vout.size() - 1)};
+            const auto prev_spk{tx.vout[i].scriptPubKey};
+            tx.vout[i].scriptPubKey = ConsumeScript(provider);
+            const bool spk_changed{tx.vout[i].scriptPubKey != prev_spk};
+            Assert(VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk) == !spk_changed);
+        }
+        // TODO: check that adding/removing inputs/outputs invalidates template hash.
+    );
+}

From e2c3e679e240df20040db0fa195825323dcb013c Mon Sep 17 00:00:00 2001
From: Greg Sanders <gsanders87@gmail.com>
Date: Fri, 13 Jun 2025 13:26:52 -0400
Subject: [PATCH 5/5] qa: functional test coverage of OP_TEMPLATEHASH

This leverages the extensive feature_taproot.py test framework to generate coverage for the numerous
scenarii and mutations exercised there.

Additionally, a separate feature_templatehash.py functional test is introduced for end-to-end
testing of the commit-to-next-transaction use case, which does not fit nicely into the
feature_taproot.py framework (assumes input independence).
---
 test/functional/feature_taproot.py       | 124 ++++++++++++-
 test/functional/feature_templatehash.py  | 215 +++++++++++++++++++++++
 test/functional/test_framework/script.py |  15 ++
 test/functional/test_runner.py           |   1 +
 4 files changed, 348 insertions(+), 7 deletions(-)
 create mode 100755 test/functional/feature_templatehash.py

diff --git a/test/functional/feature_taproot.py b/test/functional/feature_taproot.py
index e2887560986b..bd103aad09f4 100755
--- a/test/functional/feature_taproot.py
+++ b/test/functional/feature_taproot.py
@@ -74,7 +74,9 @@
     OP_NOTIF,
     OP_PUSHDATA1,
     OP_RETURN,
+    OP_SIZE,
     OP_SWAP,
+    OP_TEMPLATEHASH,
     OP_TUCK,
     OP_VERIFY,
     SIGHASH_DEFAULT,
@@ -87,6 +89,7 @@
     SegwitV0SignatureMsg,
     TaggedHash,
     TaprootSignatureMsg,
+    TemplateMsg,
     is_op_success,
     taproot_construct,
 )
@@ -282,6 +285,18 @@ def default_sighash(ctx):
         else:
             return hash256(msg)
 
+def default_templatehash_message(ctx):
+    """Default expression for "template_hash_msg"."""
+    tx = get(ctx, "tx")
+    idx = get(ctx, "idx")
+    annex = get(ctx, "annex")
+    return TemplateMsg(tx, idx, annex=annex)
+
+def default_templatehash(ctx):
+    """Default expression for "template_hash": the tagged hash of the digest."""
+    msg = get(ctx, "template_hash_msg")
+    return TaggedHash("TemplateHash", msg)
+
 def default_tweak(ctx):
     """Default expression for "tweak": None if a leaf is specified, tap[0] otherwise."""
     if get(ctx, "leaf") is None:
@@ -416,6 +431,10 @@ def default_scriptsig(ctx):
     "sigmsg": default_sigmsg,
     # The sighash value (32 bytes)
     "sighash": default_sighash,
+    # The template msg value (preimage of template_hash)
+    "template_hash_msg": default_templatehash_message,
+    # The template_hash value (32 bytes)
+    "template_hash": default_templatehash,
     # The information about the chosen script path spend (TaprootLeafInfo object).
     "tapleaf": default_tapleaf,
     # The script to push, and include in the sighash, for a taproot script path spend.
@@ -651,6 +670,9 @@ def byte_popper(expr):
 ERR_NO_SUCCESS = {"err_msg": "Script evaluated without error but finished with a false/empty top stack element"}
 ERR_EMPTY_WITNESS = {"err_msg": "Witness program was passed an empty witness"}
 ERR_CHECKSIGVERIFY = {"err_msg": "Script failed an OP_CHECKSIGVERIFY operation"}
+ERR_EVAL_FALSE = {"err_msg": "Script evaluated without error but finished with a false/empty top stack element"}
+ERR_BAD_OPCODE = {"err_msg": "Opcode missing or not understood"}
+ERR_EQUALVERIFY = {"err_msg": "Script failed an OP_EQUALVERIFY operation"}
 
 VALID_SIGHASHES_ECDSA = [
     SIGHASH_ALL,
@@ -1286,7 +1308,7 @@ def predict_sigops_ratio(n, dummy_size):
                     add_spender(spenders, "legacy/pk-wrongkey", hashtype=hashtype, p2sh=p2sh, witv0=witv0, standard=standard, script=key_to_p2pk_script(pubkey1), **SINGLE_SIG, key=eckey1, failure={"key": eckey2}, sigops_weight=4-3*witv0, **ERR_NO_SUCCESS)
                     add_spender(spenders, "legacy/pkh-sighashflip", hashtype=hashtype, p2sh=p2sh, witv0=witv0, standard=standard, pkh=pubkey1, key=eckey1, **SIGHASH_BITFLIP, sigops_weight=4-3*witv0, **ERR_NO_SUCCESS)
 
-    # Verify that OP_CHECKSIGADD wasn't accidentally added to pre-taproot validation logic.
+    # Verify that OP_CHECKSIGADD, OP_CSFS, OP_IK and OP_TEMPLATEHASH weren't accidentally added to pre-taproot validation logic.
     for p2sh in [False, True]:
         for witv0 in [False, True]:
             for hashtype in VALID_SIGHASHES_ECDSA + [random.randrange(0x04, 0x80), random.randrange(0x84, 0x100)]:
@@ -1298,6 +1320,7 @@ def predict_sigops_ratio(n, dummy_size):
             # so we use arb non-0 byte push via valid pubkey
             add_spender(spenders, "compat/nocsfs", p2sh=p2sh, witv0=witv0, standard=p2sh or witv0, script=CScript([OP_IF, b'', b'', pubs[0], OP_CHECKSIGFROMSTACK, OP_DROP, OP_ENDIF]), inputs=[pubs[0], b''], failure={"inputs": [pubs[0], pubs[0]]}, **ERR_UNDECODABLE)
             add_spender(spenders, "compat/noik", p2sh=p2sh, witv0=witv0, standard=p2sh or witv0, script=CScript([OP_IF, OP_INTERNALKEY, OP_RETURN, OP_ENDIF]), inputs=[pubs[0], b''], failure={"inputs": [pubs[0], pubs[0]]}, **ERR_UNDECODABLE)
+            add_spender(spenders, "compat/noth", p2sh=p2sh, witv0=witv0, standard=p2sh or witv0, script=CScript([OP_IF, OP_TEMPLATEHASH, OP_ENDIF, OP_1]), inputs=[b''], failure={"inputs": [b'\x01']}, **ERR_BAD_OPCODE)
 
     # == sighash caching tests ==
 
@@ -1425,6 +1448,28 @@ def bip349_ik_spenders_nonstandard():
 
     return spenders
 
+
+def templatehash_spenders_nonstandard():
+    """Spenders for testing that pre-active TEMPLATEHASH usage is discouraged"""
+
+    spenders = []
+
+    sec = generate_privkey()
+    pub, _ = compute_xonly_pubkey(sec)
+    scripts = [
+        ("basic", CScript([OP_TEMPLATEHASH])),
+        ("emptystack", CScript([OP_TEMPLATEHASH, OP_DROP])),
+    ]
+    tap = taproot_construct(pub, scripts)
+
+    # Valid but non-standard until activation
+    add_spender(spenders, "discouraged_template/basic", tap=tap, leaf="basic", standard=False)
+    # This will fail after activation
+    add_spender(spenders, "discouraged_template/emptystack", tap=tap, leaf="emptystack", standard=False)
+
+    return spenders
+
+
 def bip348_csfs_spenders():
     secs = [generate_privkey() for _ in range(2)]
     pubs = [compute_xonly_pubkey(sec)[0] for sec in secs]
@@ -1486,6 +1531,64 @@ def bip348_csfs_spenders():
 
     return spenders
 
+
+def templatehash_spenders_active():
+    """Spenders for testing that post-active TEMPLATEHASH usage is enforced"""
+
+    spenders = []
+
+    sec = generate_privkey()
+    pub, _ = compute_xonly_pubkey(sec)
+    scripts = [
+        ("basic", CScript([OP_TEMPLATEHASH])),
+        ("emptystack", CScript([OP_TEMPLATEHASH, OP_DROP])),
+        ("2stack", CScript([OP_TEMPLATEHASH, OP_1])),
+        ("equality", CScript([OP_TEMPLATEHASH, OP_EQUAL])),
+        ("32bytes", CScript([OP_TEMPLATEHASH, OP_SIZE, 0x20, OP_EQUALVERIFY])),
+        ("wrongbytes", CScript([OP_TEMPLATEHASH, OP_SIZE, 0x21, OP_EQUALVERIFY])),
+        ("doublegood", CScript([OP_TEMPLATEHASH, OP_TEMPLATEHASH, OP_EQUAL])),
+    ]
+    tap = taproot_construct(pub, scripts)
+
+    add_spender(spenders, "template/basic", tap=tap, leaf="basic", failure={"leaf": "emptystack"}, **ERR_CLEANSTACK)
+    add_spender(spenders, "template/2stack", tap=tap, leaf="basic", failure={"leaf": "2stack"}, **ERR_CLEANSTACK)
+    add_spender(spenders, "template/32bytes", tap=tap, leaf="32bytes", failure={"leaf": "wrongbytes"}, **ERR_EQUALVERIFY)
+    add_spender(spenders, "template/doublegood", tap=tap, leaf="doublegood", failure={"inputs": [random.randbytes(1)]}, **ERR_CLEANSTACK)
+
+    TEMPLATEHASH_BITFLIP = {"failure": {"template_hash": bitflipper(default_templatehash)}}
+    TEMPLATEHASH_POP_BYTE = {"failure": {"template_hash": byte_popper(default_templatehash)}}
+    TEMPLATEHASH_ADD_ZERO = {"failure": {"template_hash": zero_appender(default_templatehash)}}
+
+    # Test various 31/32/33-byte pushes with mutations
+    for i, mutator in enumerate([TEMPLATEHASH_BITFLIP, TEMPLATEHASH_POP_BYTE, TEMPLATEHASH_ADD_ZERO]):
+        add_spender(spenders, f"template/equality_{i}", tap=tap, leaf="equality", inputs=[getter("template_hash")], **mutator, **ERR_EVAL_FALSE)
+
+    # Test random other lengths
+    for i in range(256):
+        if i == 32:
+            continue
+        wrongsize_template_hash = random.randbytes(i)
+        add_spender(spenders, f"template/equality_rand_{i}", tap=tap, leaf="equality", inputs=[getter("template_hash")], failure={"inputs": [wrongsize_template_hash]}, **ERR_EVAL_FALSE)
+
+    # Test annex commitment
+    for i in range(32):
+        # No annex commitment
+        add_spender(spenders, f"template/equality_annex_none_{i}", tap=tap, leaf="equality", inputs=[getter("template_hash")], failure={"template_hash": override(default_templatehash, annex=bytes([ANNEX_TAG]) + random.randbytes(i))}, **ERR_EVAL_FALSE)
+
+        # Annex committed, compared to none
+        add_spender(spenders, f"template/equality_annex_{i}", tap=tap, leaf="equality", standard=False, annex=bytes([ANNEX_TAG]) + random.randbytes(i), inputs=[getter("template_hash")], failure={"template_hash": override(default_templatehash, annex=None)}, **ERR_EVAL_FALSE)
+
+        # Both have annex, no collision allowed
+        if i > 0:
+            annex = bytes([ANNEX_TAG]) + random.randbytes(i)
+            wrong_annex = None
+            while wrong_annex is None or wrong_annex == annex:
+                wrong_annex = bytes([ANNEX_TAG]) + random.randbytes(i)
+            add_spender(spenders, f"template/equality_annex_mismatch_{i}", tap=tap, leaf="equality", annex=annex, standard=False, inputs=[getter("template_hash")], failure={"template_hash": override(default_templatehash, annex=wrong_annex)}, **ERR_EVAL_FALSE)
+
+    return spenders
+
+
 # Consensus validation flags to use in dumps for tests with "legacy/" or "inactive/" prefix.
 LEGACY_FLAGS = "P2SH,DERSIG,CHECKLOCKTIMEVERIFY,CHECKSEQUENCEVERIFY,WITNESS,NULLDUMMY"
 # Consensus validation flags to use in dumps for all other tests.
@@ -1544,7 +1647,8 @@ def skip_test_if_missing_module(self):
     def set_test_params(self):
         self.num_nodes = 1
         self.extra_args = [["-vbparams=checksigfromstack:0:3999999999",
-                            "-vbparams=internalkey:0:3999999999"]]
+                            "-vbparams=internalkey:0:3999999999",
+                            "-vbparams=templatehash:0:3999999999"]]
         self.setup_clean_chain = True
 
     def block_submit(self, node, txs, msg, err_msg, cb_pubkey=None, fees=0, sigops_weight=0, witness=False, accept=False):
@@ -2018,20 +2122,24 @@ def pr(node):
     def run_test(self):
         self.gen_test_vectors()
 
-        self.log.info("CSFS and IK Pre-activation tests...")
+        self.log.info("CSFS, IK and TEMPLATEHASH Pre-activation tests...")
         assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["checksigfromstack"]["heretical"]["status"],"defined")
         assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["internalkey"]["heretical"]["status"],"defined")
+        assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["heretical"]["status"], "defined")
         self.generate(self.nodes[0], 144)
         assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["checksigfromstack"]["heretical"]["status"],"started")
         assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["internalkey"]["heretical"]["status"],"started")
+        assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["heretical"]["status"], "started")
         signal_ver_csfs = int(self.nodes[0].getdeploymentinfo()["deployments"]["checksigfromstack"]["heretical"]["signal_activate"], 16)
         signal_ver_ik = int(self.nodes[0].getdeploymentinfo()["deployments"]["internalkey"]["heretical"]["signal_activate"], 16)
+        signal_ver_th = int(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["heretical"]["signal_activate"], 16)
 
-        self.test_spenders(self.nodes[0], bip348_csfs_spenders_nonstandard() + bip349_ik_spenders_nonstandard(), input_counts=[1, 2])
+        nonstd_spenders = bip348_csfs_spenders_nonstandard() + bip349_ik_spenders_nonstandard() + templatehash_spenders_nonstandard()
+        self.test_spenders(self.nodes[0], nonstd_spenders, input_counts=[1, 2])
 
-        self.log.info("Activating CSFS and IK")
+        self.log.info("Activating CSFS, IK and TEMPLATEHASH")
         now = self.nodes[0].getblock(self.nodes[0].getbestblockhash())["time"]
-        for signal in [signal_ver_csfs, signal_ver_ik]:
+        for signal in [signal_ver_csfs, signal_ver_ik, signal_ver_th]:
             coinbase_tx = create_coinbase(self.nodes[0].getblockcount() + 1)
             block = create_block(hashprev=int(self.nodes[0].getbestblockhash(), 16), ntime=now, coinbase=coinbase_tx, version=signal)
             block.solve()
@@ -2040,9 +2148,11 @@ def run_test(self):
         self.generate(self.nodes[0], 288)
         assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["checksigfromstack"]["heretical"]["status"],"active")
         assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["internalkey"]["heretical"]["status"],"active")
+        assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["heretical"]["status"], "active")
 
         self.log.info("Post-activation tests...")
-        consensus_spenders = spenders_taproot_active() + bip348_csfs_spenders() + spenders_internalkey_active()
+
+        consensus_spenders = spenders_taproot_active() + bip348_csfs_spenders() + spenders_internalkey_active() + templatehash_spenders_active()
         self.test_spenders(self.nodes[0], consensus_spenders, input_counts=[1, 2, 2, 2, 2, 3])
         # Run each test twice; once in isolation, and once combined with others. Testing in isolation
         # means that the standardness is verified in every test (as combined transactions are only standard
diff --git a/test/functional/feature_templatehash.py b/test/functional/feature_templatehash.py
new file mode 100755
index 000000000000..0fbafe1e5478
--- /dev/null
+++ b/test/functional/feature_templatehash.py
@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-present The Bitcoin Core developers
+# Distributed under the MIT software license, see the accompanying
+# file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Test OP_TEMPLATEHASH committed hash spends and mutations. See feature_taproot.py for more coverage"""
+
+from test_framework.blocktools import create_block, create_coinbase
+from test_framework.key import (
+    generate_privkey,
+    compute_xonly_pubkey,
+)
+from test_framework.messages import (
+    COutPoint,
+    CTransaction,
+    CTxIn,
+    CTxInWitness,
+    CTxOut,
+    msg_tx,
+    SEQUENCE_FINAL,
+)
+from test_framework.p2p import (
+    P2PInterface,
+)
+from test_framework.script import (
+    ANNEX_TAG,
+    CScript,
+    OP_EQUAL,
+    OP_RETURN,
+    OP_TEMPLATEHASH,
+    TaggedHash,
+    taproot_construct,
+    TemplateMsg,
+)
+from test_framework.test_framework import BitcoinTestFramework
+from test_framework.util import (
+    assert_equal,
+    assert_raises_rpc_error,
+)
+from test_framework.wallet import (
+    MiniWallet,
+)
+
+
+def get_template_hash(txTo, input_index=0, annex=None):
+    return TaggedHash("TemplateHash", TemplateMsg(txTo, input_index, annex))
+
+
+class TemplateHashTest(BitcoinTestFramework):
+    def set_test_params(self):
+        self.setup_clean_chain = True
+        self.num_nodes = 1
+        self.extra_args = [[f"-vbparams=templatehash:0:{2**63 - 1}"]] # test activation of templatehash
+
+    def test_basic(self):
+        self.log.info("Testing basic committed OP_TEMPLATEHASH spend")
+        node = self.nodes[0]
+
+        # Generate a spending tx ahead of time that will allow for a valid spend to be created later
+        # Just burns everything to fees for simplicity.
+        tx = CTransaction()
+        tx.vin.append(CTxIn(COutPoint(0, 0), b"", SEQUENCE_FINAL))
+        tx.vout.append(CTxOut(0, CScript([OP_RETURN, b"\x00\x00\x00\x00"])))
+
+        # Single tapscript that commits to future spend
+        real_template_hash = get_template_hash(tx, input_index=0)
+        scripts = [
+            ("basic", CScript([real_template_hash, OP_TEMPLATEHASH, OP_EQUAL])),
+        ]
+        tap = taproot_construct(self.public_keys[0], scripts)
+
+        # Seed a utxo with committed hash
+        commit_tx = self.wallet.send_to(from_node=node, scriptPubKey=tap.scriptPubKey, amount=330)
+
+        # Now that funding tx is generated, the spending transaction
+        # prevout can be properly bound
+        tx.vin[0].prevout.hash = int(commit_tx["tx"].rehash(), 16)
+        tx.vin[0].prevout.n = commit_tx["sent_vout"]
+
+        # And fill out witness data for spend
+        tx.wit.vtxinwit = [CTxInWitness()]
+
+        # template digest should be unchanged
+        assert_equal(get_template_hash(tx, input_index=0), real_template_hash)
+
+        control_block = bytes([tap.leaves["basic"].version | tap.negflag]) + tap.internal_pubkey + tap.leaves["basic"].merklebranch
+        assert_equal(len(control_block), 33)
+        tx.wit.vtxinwit[0].scriptWitness.stack = [tap.leaves["basic"].script, control_block]
+
+        node.sendrawtransaction(tx.serialize().hex(), maxfeerate=0)
+        self.generate(self.wallet, 1)
+
+    def test_mutations(self):
+        self.log.info("Basic testing of mutations of OP_TEMPLATEHASH spend")
+        node = self.nodes[0]
+
+        # Checking for non-disconnection
+        peer = node.add_p2p_connection(P2PInterface())
+
+        # Generate a spending tx ahead of time that will allow for a valid spend to be created later
+        # Just burns everything to fees for simplicity.
+        tx = CTransaction()
+        tx.vin.append(CTxIn(COutPoint(0, 0), b"", SEQUENCE_FINAL))
+        tx.vout.append(CTxOut(0, CScript([OP_RETURN, b"\x00\x00\x00\x00"])))
+
+        # Single tapscript that commits to future spend
+        real_template_hash = get_template_hash(tx, input_index=0)
+        scripts = [
+            ("basic", CScript([real_template_hash, OP_TEMPLATEHASH, OP_EQUAL])),
+            ("alt", CScript([OP_RETURN])),
+        ]
+        tap = taproot_construct(self.public_keys[0], scripts)
+
+        # Seed a utxo with committed hash
+        commit_tx = self.wallet.send_to(from_node=node, scriptPubKey=tap.scriptPubKey, amount=330)
+
+        # Now that funding tx is generated, the spending transaction
+        # prevout can be properly bound
+        tx.vin[0].prevout.hash = int(commit_tx["tx"].rehash(), 16)
+        tx.vin[0].prevout.n = commit_tx["sent_vout"]
+
+        # And fill out witness data for spend
+        tx.wit.vtxinwit = [CTxInWitness()]
+
+        # template digest should be unchanged
+        assert_equal(get_template_hash(tx, input_index=0), real_template_hash)
+
+        control_block = bytes([tap.leaves["basic"].version | tap.negflag]) + tap.internal_pubkey + tap.leaves["basic"].merklebranch
+        assert_equal(len(control_block), 33 + 32)
+        tx.wit.vtxinwit[0].scriptWitness.stack = [tap.leaves["basic"].script, control_block]
+
+        # Tx would have been ok
+        assert node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+
+        # Mutate version
+        tx.version = 1
+        peer.send_and_ping(msg_tx(tx))
+        assert not node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+        assert_raises_rpc_error(-25, "TestBlockValidity failed: mandatory-script-verify-flag-failed (Script evaluated without error but finished with a false/empty top stack element)", self.generateblock, node, output="raw(51)", transactions=[commit_tx["hex"], tx.serialize().hex()])
+        tx.version = 2
+        assert node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+
+        # Mutate locktime
+        tx.nLockTime += 1
+        peer.send_and_ping(msg_tx(tx))
+        assert not node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+        assert_raises_rpc_error(-25, "TestBlockValidity failed: mandatory-script-verify-flag-failed (Script evaluated without error but finished with a false/empty top stack element)", self.generateblock, node, output="raw(51)", transactions=[commit_tx["hex"], tx.serialize().hex()])
+        tx.nLockTime -= 1
+        assert node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+
+        # Mutate nsequence
+        tx.vin[0].nSequence -= 1
+        peer.send_and_ping(msg_tx(tx))
+        assert not node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+        assert_raises_rpc_error(-25, "TestBlockValidity failed: mandatory-script-verify-flag-failed (Script evaluated without error but finished with a false/empty top stack element)", self.generateblock, node, output="raw(51)", transactions=[commit_tx["hex"], tx.serialize().hex()])
+        tx.vin[0].nSequence += 1
+        assert node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+
+        # Mutate output amount
+        tx.vout[0].nValue += 1
+        peer.send_and_ping(msg_tx(tx))
+        assert not node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+        assert_raises_rpc_error(-25, "TestBlockValidity failed: mandatory-script-verify-flag-failed (Script evaluated without error but finished with a false/empty top stack element)", self.generateblock, node, output="raw(51)", transactions=[commit_tx["hex"], tx.serialize().hex()])
+        tx.vout[0].nValue -= 1
+        assert node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+
+        # Add extraneous output
+        tx.vout.append(tx.vout[-1])
+        peer.send_and_ping(msg_tx(tx))
+        assert not node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+        assert_raises_rpc_error(-25, "TestBlockValidity failed: mandatory-script-verify-flag-failed (Script evaluated without error but finished with a false/empty top stack element)", self.generateblock, node, output="raw(51)", transactions=[commit_tx["hex"], tx.serialize().hex()])
+        del tx.vout[1]
+        assert node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+
+        # Mutate annex (not relay standard)
+        tx.wit.vtxinwit[0].scriptWitness.stack.append(bytes([ANNEX_TAG]) + b"\x00")
+        peer.send_and_ping(msg_tx(tx))
+        assert_raises_rpc_error(-25, "TestBlockValidity failed: mandatory-script-verify-flag-failed (Script evaluated without error but finished with a false/empty top stack element)", self.generateblock, node, output="raw(51)", transactions=[commit_tx["hex"], tx.serialize().hex()])
+        tx.wit.vtxinwit[0].scriptWitness.stack = tx.wit.vtxinwit[0].scriptWitness.stack[:-1]
+        assert node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+
+        # "Ok" to mutate other witness data
+        tx.wit.vtxinwit[0].scriptWitness.stack = [b"\x00"] + tx.wit.vtxinwit[0].scriptWitness.stack
+        peer.send_and_ping(msg_tx(tx))
+        assert_raises_rpc_error(-25, "TestBlockValidity failed: mandatory-script-verify-flag-failed (Stack size must be exactly one after execution)", self.generateblock, node, output="raw(51)", transactions=[commit_tx["hex"], tx.serialize().hex()])
+        tx.wit.vtxinwit[0].scriptWitness.stack = tx.wit.vtxinwit[0].scriptWitness.stack[1:]
+        assert node.testmempoolaccept([tx.serialize().hex()])[0]["allowed"]
+
+        node.disconnect_p2ps()
+
+    def run_test(self):
+        node = self.nodes[0]
+
+        # Can be expanded to mix keys
+        self.secret_keys = [generate_privkey() for _ in range(1)]
+        self.public_keys = [compute_xonly_pubkey(sec)[0] for sec in self.secret_keys]
+
+        self.log.info("Activating templatehash")
+        assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["heretical"]["status"], "defined")
+        self.wallet = MiniWallet(node)
+        self.generate(self.wallet, 144)
+        assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["heretical"]["status"], "started")
+        signal_version = int(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["heretical"]["signal_activate"], 16)
+        coinbase_tx = create_coinbase(self.nodes[0].getblockcount() + 1)
+        now = self.nodes[0].getblock(self.nodes[0].getbestblockhash())["time"]
+        block = create_block(hashprev=int(self.nodes[0].getbestblockhash(), 16), ntime=now, coinbase=coinbase_tx, version=signal_version)
+        block.solve()
+        self.nodes[0].submitblock(block.serialize().hex())
+        self.generate(self.nodes[0], 144 * 2)
+        assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["heretical"]["status"], "active")
+
+        self.test_basic()
+        self.test_mutations()
+
+if __name__ == '__main__':
+    TemplateHashTest(__file__).main()
diff --git a/test/functional/test_framework/script.py b/test/functional/test_framework/script.py
index f83f24798e02..3f078ea75d85 100644
--- a/test/functional/test_framework/script.py
+++ b/test/functional/test_framework/script.py
@@ -824,6 +824,21 @@ def BIP341_sha_sequences(txTo):
 def BIP341_sha_outputs(txTo):
     return sha256(b"".join(o.serialize() for o in txTo.vout))
 
+def TemplateMsg(txTo, input_index=0, annex=None):
+    assert (input_index < len(txTo.vin))
+    ss = txTo.version.to_bytes(4, "little")
+    ss += txTo.nLockTime.to_bytes(4, "little")
+    ss += BIP341_sha_sequences(txTo)
+    ss += BIP341_sha_outputs(txTo)
+    annex_present = 0
+    if annex is not None:
+        annex_present |= 1
+    ss += bytes([annex_present])
+    ss += input_index.to_bytes(4, "little")
+    if (annex is not None):
+        ss += sha256(ser_string(annex))
+    return ss
+
 def TaprootSignatureMsg(txTo, spent_utxos, hash_type, input_index=0, *, scriptpath=False, leaf_script=None, codeseparator_pos=-1, annex=None, leaf_ver=LEAF_VERSION_TAPSCRIPT, key_ver=KEY_VERSION_TAPROOT):
     assert (len(txTo.vin) == len(spent_utxos))
     assert key_ver == KEY_VERSION_TAPROOT or key_ver == KEY_VERSION_ANYPREVOUT
diff --git a/test/functional/test_runner.py b/test/functional/test_runner.py
index 6defca85eea3..38cdd02f10dc 100755
--- a/test/functional/test_runner.py
+++ b/test/functional/test_runner.py
@@ -413,6 +413,7 @@
     'feature_help.py',
     'feature_shutdown.py',
     'wallet_migration.py',
+    'feature_templatehash.py',
     'p2p_ibd_txrelay.py',
     'p2p_seednode.py',
     # Don't append tests at the end to avoid merge conflicts