From 716163deb0d5e3b94f98b03c7a3dd4391f4ecb16 Mon Sep 17 00:00:00 2001
From: Antoine Poinsot <darosior@protonmail.com>
Date: Thu, 12 Jun 2025 10:44:02 -0400
Subject: [PATCH 01/12] chainparams: introduce a deployment for OP_TEMPLATEHASH

The deployment is never active on mainnet or testnet. Activation parameters are intentionally left
to be defined eventually and out of scope for this patchset.

The deployment is always active on regtest, allowing us to extensively test expected behaviour of
the proposed operation using the functional test suite.

Co-Authored-By: Greg Sanders <gsanders87@gmail.com>
---
 src/consensus/params.h            |  1 +
 src/deploymentinfo.cpp            |  4 ++++
 src/kernel/chainparams.cpp        | 32 +++++++++++++++++++++++++++++++
 src/rpc/blockchain.cpp            |  1 +
 test/functional/mining_basic.py   |  2 +-
 test/functional/rpc_blockchain.py | 13 +++++++++++++
 6 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/src/consensus/params.h b/src/consensus/params.h
index 7f56729455a8..6514e3ebee3d 100644
--- a/src/consensus/params.h
+++ b/src/consensus/params.h
@@ -36,6 +36,7 @@ constexpr bool ValidDeployment(BuriedDeployment dep) { return dep <= DEPLOYMENT_
 
 enum DeploymentPos : uint16_t {
     DEPLOYMENT_TESTDUMMY,
+    DEPLOYMENT_TEMPLATEHASH,
     // NOTE: Also add new deployments to VersionBitsDeploymentInfo in deploymentinfo.cpp
     // Removing an entry may require bumping MinBIP9WarningHeight.
     MAX_VERSION_BITS_DEPLOYMENTS
diff --git a/src/deploymentinfo.cpp b/src/deploymentinfo.cpp
index 551982b23ae7..f4ff3d1122f0 100644
--- a/src/deploymentinfo.cpp
+++ b/src/deploymentinfo.cpp
@@ -13,6 +13,10 @@ const std::array<VBDeploymentInfo,Consensus::MAX_VERSION_BITS_DEPLOYMENTS> Versi
         .name = "testdummy",
         .gbt_optional_rule = true,
     },
+    VBDeploymentInfo{
+        .name = "templatehash",
+        .gbt_optional_rule = true,
+    }
 };
 
 std::string DeploymentName(Consensus::BuriedDeployment dep)
diff --git a/src/kernel/chainparams.cpp b/src/kernel/chainparams.cpp
index cc77a373481b..06650ef1c6bd 100644
--- a/src/kernel/chainparams.cpp
+++ b/src/kernel/chainparams.cpp
@@ -136,6 +136,12 @@ class CMainParams : public CChainParams {
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].threshold = 1815; // 90%
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].period = 2016;
 
+        // Deployment of OP_TEMPLATEHASH
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].bit = 3;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nStartTime = Consensus::BIP9Deployment::NEVER_ACTIVE;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nTimeout = Consensus::BIP9Deployment::NO_TIMEOUT;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].min_activation_height = 0;
+
         ApplyDeploymentOptions(opts.dep_opts);
 
         consensus.nMinimumChainWork = uint256{"0000000000000000000000000000000000000001128750f82f4c366153a3a030"};
@@ -261,6 +267,12 @@ class CTestNetParams : public CChainParams {
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].threshold = 1512; // 75%
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].period = 2016;
 
+        // Deployment of OP_TEMPLATEHASH
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].bit = 3;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nStartTime = Consensus::BIP9Deployment::NEVER_ACTIVE;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nTimeout = Consensus::BIP9Deployment::NO_TIMEOUT;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].min_activation_height = 0;
+
         ApplyDeploymentOptions(opts.dep_opts);
 
         consensus.nMinimumChainWork = uint256{"0000000000000000000000000000000000000000000017dde1c649f3708d14b6"};
@@ -363,6 +375,12 @@ class CTestNet4Params : public CChainParams {
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].threshold = 1512; // 75%
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].period = 2016;
 
+        // Deployment of OP_TEMPLATEHASH
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].bit = 3;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nStartTime = Consensus::BIP9Deployment::NEVER_ACTIVE;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nTimeout = Consensus::BIP9Deployment::NO_TIMEOUT;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].min_activation_height = 0;
+
         ApplyDeploymentOptions(opts.dep_opts);
 
         consensus.nMinimumChainWork = uint256{"0000000000000000000000000000000000000000000009a0fe15d0177d086304"};
@@ -508,6 +526,12 @@ class SigNetParams : public CChainParams {
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].threshold = 1815; // 90%
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].period = 2016;
 
+        // Deployment of OP_TEMPLATEHASH
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].bit = 3;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nStartTime = Consensus::BIP9Deployment::NEVER_ACTIVE;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nTimeout = Consensus::BIP9Deployment::NO_TIMEOUT;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].min_activation_height = 0;
+
         ApplyDeploymentOptions(options.dep_opts);
 
         // message start is defined as the first 4 bytes of the sha256d of the block script
@@ -592,6 +616,14 @@ class CRegTestParams : public CChainParams
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].threshold = 108; // 75%
         consensus.vDeployments[Consensus::DEPLOYMENT_TESTDUMMY].period = 144; // Faster than normal for regtest (144 instead of 2016)
 
+        // Deployment of OP_TEMPLATEHASH
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].bit = 3;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nStartTime = Consensus::BIP9Deployment::ALWAYS_ACTIVE;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].nTimeout = Consensus::BIP9Deployment::NO_TIMEOUT;
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].min_activation_height = 0; // No activation delay
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].threshold = 108; // 75%
+        consensus.vDeployments[Consensus::DEPLOYMENT_TEMPLATEHASH].period = 144;
+
         consensus.nMinimumChainWork = uint256{};
         consensus.defaultAssumeValid = uint256{};
 
diff --git a/src/rpc/blockchain.cpp b/src/rpc/blockchain.cpp
index 14412c90fcc9..4cd658d0171a 100644
--- a/src/rpc/blockchain.cpp
+++ b/src/rpc/blockchain.cpp
@@ -1516,6 +1516,7 @@ UniValue DeploymentInfo(const CBlockIndex* blockindex, const ChainstateManager&
     SoftForkDescPushBack(blockindex, softforks, chainman, Consensus::DEPLOYMENT_CSV);
     SoftForkDescPushBack(blockindex, softforks, chainman, Consensus::DEPLOYMENT_SEGWIT);
     SoftForkDescPushBack(blockindex, softforks, chainman, Consensus::DEPLOYMENT_TESTDUMMY);
+    SoftForkDescPushBack(blockindex, softforks, chainman, Consensus::DEPLOYMENT_TEMPLATEHASH);
     return softforks;
 }
 } // anon namespace
diff --git a/test/functional/mining_basic.py b/test/functional/mining_basic.py
index 7060a3cba62b..c6979e860937 100755
--- a/test/functional/mining_basic.py
+++ b/test/functional/mining_basic.py
@@ -449,7 +449,7 @@ def run_test(self):
         assert_raises_rpc_error(-8, "getblocktemplate must be called with the segwit rule set", node.getblocktemplate, {})
 
         self.log.info("getblocktemplate: result should set the right rules")
-        assert_equal(['csv', '!segwit', 'taproot'], self.nodes[0].getblocktemplate(NORMAL_GBT_REQUEST_PARAMS)['rules'])
+        assert_equal(['csv', '!segwit', 'taproot', 'templatehash'], self.nodes[0].getblocktemplate(NORMAL_GBT_REQUEST_PARAMS)['rules'])
 
         self.log.info("submitblock: Test block decode failure")
         assert_raises_rpc_error(-22, "Block decode failed", node.submitblock, block.serialize()[:-15].hex())
diff --git a/test/functional/rpc_blockchain.py b/test/functional/rpc_blockchain.py
index d731907fd8ca..17f1b5a1083e 100755
--- a/test/functional/rpc_blockchain.py
+++ b/test/functional/rpc_blockchain.py
@@ -244,6 +244,19 @@ def check_signalling_deploymentinfo_result(self, gdi_result, height, blockhash,
                 },
                 'active': False
             },
+            'templatehash': {
+                'type': 'bip9',
+                'height': 0,
+                'active': True,
+                'bip9': {
+                    'start_time': -1,
+                    'timeout': 9223372036854775807,
+                    'min_activation_height': 0,
+                    'status': 'active',
+                    'since': 0,
+                    'status_next': 'active'
+                }
+            },
           }
         })
 

From 884695fd6fa59821e8fe96db4a7d5b2d728e3b64 Mon Sep 17 00:00:00 2001
From: Antoine Poinsot <darosior@protonmail.com>
Date: Thu, 12 Jun 2025 11:44:15 -0400
Subject: [PATCH 02/12] script: introduce verify flags for OP_TEMPLATEHASH

Script validation of OP_TEMPLATEHASH is enabled past
its activation height, which means it is currently never
enabled on mainnet/testnet and always is on regtest.

Tapscript spends making use of OP_TEMPLATEHASH do not get
relayed nor included in blocks until the soft fork is
active. We no longer disconnect or ban for loose mempool
transaction failures, so we can add the new flag directly to
mandatory flag set, which makes disconnect and bans possible
in blocks only post-activation.

Co-Authored-by: Greg Sanders <gsanders87@gmail.com>
---
 src/policy/policy.h                            |  6 ++++--
 src/script/interpreter.cpp                     |  2 ++
 src/script/interpreter.h                       |  6 ++++++
 src/test/fuzz/script_assets_test_minimizer.cpp |  4 +++-
 src/validation.cpp                             | 12 +++++++++++-
 test/functional/rpc_blockchain.py              |  2 +-
 6 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/src/policy/policy.h b/src/policy/policy.h
index 13bcf4cef750..05d01da4995a 100644
--- a/src/policy/policy.h
+++ b/src/policy/policy.h
@@ -107,7 +107,8 @@ static constexpr script_verify_flags MANDATORY_SCRIPT_VERIFY_FLAGS{SCRIPT_VERIFY
                                                              SCRIPT_VERIFY_CHECKLOCKTIMEVERIFY |
                                                              SCRIPT_VERIFY_CHECKSEQUENCEVERIFY |
                                                              SCRIPT_VERIFY_WITNESS |
-                                                             SCRIPT_VERIFY_TAPROOT};
+                                                             SCRIPT_VERIFY_TAPROOT |
+                                                             SCRIPT_VERIFY_TEMPLATEHASH};
 
 /**
  * Standard script verification flags that standard transactions will comply
@@ -128,7 +129,8 @@ static constexpr script_verify_flags STANDARD_SCRIPT_VERIFY_FLAGS{MANDATORY_SCRI
                                                              SCRIPT_VERIFY_CONST_SCRIPTCODE |
                                                              SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_TAPROOT_VERSION |
                                                              SCRIPT_VERIFY_DISCOURAGE_OP_SUCCESS |
-                                                             SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_PUBKEYTYPE};
+                                                             SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_PUBKEYTYPE |
+                                                             SCRIPT_VERIFY_DISCOURAGE_TEMPLATEHASH};
 
 /** For convenience, standard but not mandatory verify flags. */
 static constexpr script_verify_flags STANDARD_NOT_MANDATORY_VERIFY_FLAGS{STANDARD_SCRIPT_VERIFY_FLAGS & ~MANDATORY_SCRIPT_VERIFY_FLAGS};
diff --git a/src/script/interpreter.cpp b/src/script/interpreter.cpp
index 98b16eca6bcd..bc68dcbd49c5 100644
--- a/src/script/interpreter.cpp
+++ b/src/script/interpreter.cpp
@@ -2200,6 +2200,8 @@ const std::map<std::string, script_verify_flag_name>& ScriptFlagNamesToEnum()
         FLAG_NAME(DISCOURAGE_UPGRADABLE_PUBKEYTYPE),
         FLAG_NAME(DISCOURAGE_OP_SUCCESS),
         FLAG_NAME(DISCOURAGE_UPGRADABLE_TAPROOT_VERSION),
+        FLAG_NAME(TEMPLATEHASH),
+        FLAG_NAME(DISCOURAGE_TEMPLATEHASH),
     };
 #undef FLAG_NAME
     return g_names_to_enum;
diff --git a/src/script/interpreter.h b/src/script/interpreter.h
index ff63a73f0fc7..71f16a9b48d6 100644
--- a/src/script/interpreter.h
+++ b/src/script/interpreter.h
@@ -146,6 +146,12 @@ enum class script_verify_flag_name : uint8_t {
     // Making unknown public key versions (in BIP 342 scripts) non-standard
     SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_PUBKEYTYPE,
 
+    // OP_TEMPLATEHASH validation (BIP 446)
+    SCRIPT_VERIFY_TEMPLATEHASH,
+
+    // Make OP_TEMPLATEHASH spend non-standard before activation.
+    SCRIPT_VERIFY_DISCOURAGE_TEMPLATEHASH,
+
     // Constants to point to the highest flag in use. Add new flags above this line.
     //
     SCRIPT_VERIFY_END_MARKER
diff --git a/src/test/fuzz/script_assets_test_minimizer.cpp b/src/test/fuzz/script_assets_test_minimizer.cpp
index fc6f9fb167a1..034cfaff32d2 100644
--- a/src/test/fuzz/script_assets_test_minimizer.cpp
+++ b/src/test/fuzz/script_assets_test_minimizer.cpp
@@ -98,13 +98,14 @@ const std::map<std::string, script_verify_flag_name> FLAG_NAMES = {
     {std::string("CHECKSEQUENCEVERIFY"), SCRIPT_VERIFY_CHECKSEQUENCEVERIFY},
     {std::string("WITNESS"), SCRIPT_VERIFY_WITNESS},
     {std::string("TAPROOT"), SCRIPT_VERIFY_TAPROOT},
+    {std::string("TEMPLATE"), SCRIPT_VERIFY_TEMPLATEHASH},
 };
 
 std::vector<script_verify_flags> AllFlags()
 {
     std::vector<script_verify_flags> ret;
 
-    for (unsigned int i = 0; i < 128; ++i) {
+    for (unsigned int i = 0; i < 256; ++i) {
         script_verify_flags flag = 0;
         if (i & 1) flag |= SCRIPT_VERIFY_P2SH;
         if (i & 2) flag |= SCRIPT_VERIFY_DERSIG;
@@ -113,6 +114,7 @@ std::vector<script_verify_flags> AllFlags()
         if (i & 16) flag |= SCRIPT_VERIFY_CHECKSEQUENCEVERIFY;
         if (i & 32) flag |= SCRIPT_VERIFY_WITNESS;
         if (i & 64) flag |= SCRIPT_VERIFY_TAPROOT;
+        if (i & 128) flag |= SCRIPT_VERIFY_TEMPLATEHASH;
 
         // SCRIPT_VERIFY_WITNESS requires SCRIPT_VERIFY_P2SH
         if (flag & SCRIPT_VERIFY_WITNESS && !(flag & SCRIPT_VERIFY_P2SH)) continue;
diff --git a/src/validation.cpp b/src/validation.cpp
index 77e91999b6cd..d1e055f2cf34 100644
--- a/src/validation.cpp
+++ b/src/validation.cpp
@@ -1136,7 +1136,12 @@ bool MemPoolAccept::PolicyScriptChecks(const ATMPArgs& args, Workspace& ws)
     const CTransaction& tx = *ws.m_ptx;
     TxValidationState& state = ws.m_state;
 
-    constexpr script_verify_flags scriptVerifyFlags = STANDARD_SCRIPT_VERIFY_FLAGS;
+    script_verify_flags scriptVerifyFlags = STANDARD_SCRIPT_VERIFY_FLAGS;
+
+    // Past activation, don't discourage OP_TEMPLATEHASH spends.
+    if (DeploymentActiveAt(*m_active_chainstate.m_chain.Tip(), m_active_chainstate.m_chainman, Consensus::DEPLOYMENT_TEMPLATEHASH)) {
+        scriptVerifyFlags &= ~SCRIPT_VERIFY_DISCOURAGE_TEMPLATEHASH;
+    }
 
     // Check input scripts and signatures.
     // This is done last to help prevent CPU exhaustion denial-of-service attacks.
@@ -2284,6 +2289,11 @@ script_verify_flags GetBlockScriptFlags(const CBlockIndex& block_index, const Ch
         flags |= SCRIPT_VERIFY_NULLDUMMY;
     }
 
+    // Enforce OP_TEMPLATEHASH (BIP446)
+    if (DeploymentActiveAt(block_index, chainman, Consensus::DEPLOYMENT_TEMPLATEHASH)) {
+        flags |= SCRIPT_VERIFY_TEMPLATEHASH;
+    }
+
     return flags;
 }
 
diff --git a/test/functional/rpc_blockchain.py b/test/functional/rpc_blockchain.py
index 17f1b5a1083e..6a018549190e 100755
--- a/test/functional/rpc_blockchain.py
+++ b/test/functional/rpc_blockchain.py
@@ -216,7 +216,7 @@ def check_signalling_deploymentinfo_result(self, gdi_result, height, blockhash,
         assert_equal(gdi_result, {
           "hash": blockhash,
           "height": height,
-          "script_flags": ["CHECKLOCKTIMEVERIFY","CHECKSEQUENCEVERIFY","DERSIG","NULLDUMMY","P2SH","TAPROOT","WITNESS"],
+          "script_flags": ["CHECKLOCKTIMEVERIFY","CHECKSEQUENCEVERIFY","DERSIG","NULLDUMMY","P2SH","TAPROOT","TEMPLATEHASH","WITNESS"],
           "deployments": {
             'bip34': {'type': 'buried', 'active': True, 'height': 2},
             'bip66': {'type': 'buried', 'active': True, 'height': 3},

From b89d43f7abd34086d75fc671a4aea5f8671fe4e0 Mon Sep 17 00:00:00 2001
From: Antoine Poinsot <darosior@protonmail.com>
Date: Tue, 10 Jun 2025 17:25:39 -0400
Subject: [PATCH 03/12] 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 BIP446 for details.

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

Co-Authored-By: Greg Sanders <gsanders87@gmail.com>
---
 src/script/interpreter.cpp               | 46 ++++++++++++++++++++++++
 src/script/interpreter.h                 | 11 ++++++
 src/script/script.cpp                    |  3 ++
 src/script/script.h                      |  3 ++
 src/script/script_error.cpp              |  2 ++
 src/script/script_error.h                |  1 +
 src/test/script_tests.cpp                |  3 +-
 test/functional/feature_taproot.py       |  4 +--
 test/functional/test_framework/script.py |  8 ++++-
 9 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/src/script/interpreter.cpp b/src/script/interpreter.cpp
index bc68dcbd49c5..95b87bcaf4c9 100644
--- a/src/script/interpreter.cpp
+++ b/src/script/interpreter.cpp
@@ -1224,6 +1224,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_SUCCESS206 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);
             }
@@ -1476,6 +1490,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)
 {
@@ -1835,6 +1850,27 @@ bool GenericTransactionSignatureChecker<T>::CheckSequence(const CScriptNum& nSeq
     return true;
 }
 
+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>;
@@ -1854,6 +1890,16 @@ static bool ExecuteWitnessScript(const std::span<const valtype>& stack_span, con
             }
             // New opcodes will be listed here. May use a different sigversion to modify existing opcodes.
             if (IsOpSuccess(opcode)) {
+                // Do not return early success on OP_TEMPLATEHASH (OP_SUCCESS206) once it is active. It is
+                // non-standard until then.
+                if (opcode == OP_TEMPLATEHASH) {
+                    if (flags & SCRIPT_VERIFY_DISCOURAGE_TEMPLATEHASH) {
+                        return set_error(serror, SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH);
+                    }
+                    if (flags & SCRIPT_VERIFY_TEMPLATEHASH) {
+                        continue;
+                    }
+                }
                 if (flags & SCRIPT_VERIFY_DISCOURAGE_OP_SUCCESS) {
                     return set_error(serror, SCRIPT_ERR_DISCOURAGE_OP_SUCCESS);
                 }
diff --git a/src/script/interpreter.h b/src/script/interpreter.h
index 71f16a9b48d6..b8538c9c653e 100644
--- a/src/script/interpreter.h
+++ b/src/script/interpreter.h
@@ -301,6 +301,11 @@ class BaseSignatureChecker
          return false;
     }
 
+    virtual uint256 GetTemplateHash(ScriptExecutionData& execdata) const
+    {
+        return {};
+    }
+
     virtual ~BaseSignatureChecker() = default;
 };
 
@@ -338,6 +343,7 @@ class GenericTransactionSignatureChecker : public BaseSignatureChecker
     bool CheckSchnorrSignature(std::span<const unsigned char> sig, std::span<const unsigned char> pubkey, SigVersion sigversion, ScriptExecutionData& execdata, ScriptError* serror = nullptr) const override;
     bool CheckLockTime(const CScriptNum& nLockTime) const override;
     bool CheckSequence(const CScriptNum& nSequence) const override;
+    uint256 GetTemplateHash(ScriptExecutionData& execdata) const override;
 };
 
 using TransactionSignatureChecker = GenericTransactionSignatureChecker<CTransaction>;
@@ -369,6 +375,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. */
diff --git a/src/script/script.cpp b/src/script/script.cpp
index 4097d13d2c4a..ca474078f5e3 100644
--- a/src/script/script.cpp
+++ b/src/script/script.cpp
@@ -150,6 +150,9 @@ std::string GetOpName(opcodetype opcode)
     // Opcode added by BIP 342 (Tapscript)
     case OP_CHECKSIGADD            : return "OP_CHECKSIGADD";
 
+    // Opcode added by BIP446 (Tapscript)
+    case OP_TEMPLATEHASH           : return "OP_TEMPLATEHASH";
+
     case OP_INVALIDOPCODE          : return "OP_INVALIDOPCODE";
 
     } // no default case, so the compiler can warn about missing cases
diff --git a/src/script/script.h b/src/script/script.h
index e0112cc386e7..329cfb851ffa 100644
--- a/src/script/script.h
+++ b/src/script/script.h
@@ -210,6 +210,9 @@ enum opcodetype
     // Opcode added by BIP 342 (Tapscript)
     OP_CHECKSIGADD = 0xba,
 
+    // Opcode added by BIP xx (Tapscript-only, formerly OP_SUCCESS206)
+    OP_TEMPLATEHASH = 0xce,
+
     OP_INVALIDOPCODE = 0xff,
 };
 
diff --git a/src/script/script_error.cpp b/src/script/script_error.cpp
index 7fa127420e65..53f6a09ee93b 100644
--- a/src/script/script_error.cpp
+++ b/src/script/script_error.cpp
@@ -79,6 +79,8 @@ std::string ScriptErrorString(const ScriptError serror)
             return "OP_SUCCESSx reserved for soft-fork upgrades";
         case SCRIPT_ERR_DISCOURAGE_UPGRADABLE_PUBKEYTYPE:
             return "Public key version reserved for soft-fork upgrades";
+        case SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH:
+            return "Templatehash is not active";
         case SCRIPT_ERR_PUBKEYTYPE:
             return "Public key is neither compressed or uncompressed";
         case SCRIPT_ERR_CLEANSTACK:
diff --git a/src/script/script_error.h b/src/script/script_error.h
index 60ab3e51bfe6..c1ca6e015683 100644
--- a/src/script/script_error.h
+++ b/src/script/script_error.h
@@ -60,6 +60,7 @@ typedef enum ScriptError_t
     SCRIPT_ERR_DISCOURAGE_UPGRADABLE_TAPROOT_VERSION,
     SCRIPT_ERR_DISCOURAGE_OP_SUCCESS,
     SCRIPT_ERR_DISCOURAGE_UPGRADABLE_PUBKEYTYPE,
+    SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH,
 
     /* segregated witness */
     SCRIPT_ERR_WITNESS_PROGRAM_WRONG_LENGTH,
diff --git a/src/test/script_tests.cpp b/src/test/script_tests.cpp
index 37ca862a8d6d..0aaaf0a8f615 100644
--- a/src/test/script_tests.cpp
+++ b/src/test/script_tests.cpp
@@ -93,7 +93,8 @@ static ScriptErrorDesc script_errors[]={
     {SCRIPT_ERR_TAPSCRIPT_EMPTY_PUBKEY, "TAPSCRIPT_EMPTY_PUBKEY"},
     {SCRIPT_ERR_OP_CODESEPARATOR, "OP_CODESEPARATOR"},
     {SCRIPT_ERR_SIG_FINDANDDELETE, "SIG_FINDANDDELETE"},
-    {SCRIPT_ERR_SCRIPTNUM, "SCRIPTNUM"}
+    {SCRIPT_ERR_SCRIPTNUM, "SCRIPTNUM"},
+    {SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH, "DISCOURAGE_TEMPLATEHASH"},
 };
 
 static std::string FormatScriptFlags(script_verify_flags flags)
diff --git a/test/functional/feature_taproot.py b/test/functional/feature_taproot.py
index eb3bb86ec3d6..2d9f34032dfa 100755
--- a/test/functional/feature_taproot.py
+++ b/test/functional/feature_taproot.py
@@ -1172,7 +1172,7 @@ def predict_sigops_ratio(n, dummy_size):
     hashtype = lambda _: random.choice(VALID_SIGHASHES_TAPROOT)
     for opval in range(76, 0x100):
         opcode = CScriptOp(opval)
-        if not is_op_success(opcode):
+        if not is_op_success(opcode, is_temphash_active=True):
             continue
         scripts = [
             ("bare_success", CScript([opcode])),
@@ -1203,7 +1203,7 @@ def predict_sigops_ratio(n, dummy_size):
     # Non-OP_SUCCESSx (verify that those aren't accidentally treated as OP_SUCCESSx)
     for opval in range(0, 0x100):
         opcode = CScriptOp(opval)
-        if is_op_success(opcode):
+        if is_op_success(opcode, is_temphash_active=True):
             continue
         scripts = [
             ("normal", CScript([OP_RETURN, opcode] + [OP_NOP] * 75)),
diff --git a/test/functional/test_framework/script.py b/test/functional/test_framework/script.py
index fb168928c3e8..83f4dd271e5d 100644
--- a/test/functional/test_framework/script.py
+++ b/test/functional/test_framework/script.py
@@ -256,6 +256,9 @@ def __new__(cls, n):
 # BIP 342 opcodes (Tapscript)
 OP_CHECKSIGADD = CScriptOp(0xba)
 
+# BIP xx opcode (Tapscript-only, formerly OP_SUCCESS206)
+OP_TEMPLATEHASH = CScriptOp(0xce)
+
 OP_INVALIDOPCODE = CScriptOp(0xff)
 
 OPCODE_NAMES.update({
@@ -371,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',
 })
 
@@ -940,5 +944,7 @@ def taproot_construct(pubkey, scripts=None, treat_internal_as_infinity=False):
     leaves = dict((name, TaprootLeafInfo(script, version, merklebranch, leaf)) for name, version, script, merklebranch, leaf in ret)
     return TaprootInfo(CScript([OP_1, tweaked]), pubkey, negated + 0, tweak, leaves, h, tweaked)
 
-def is_op_success(o):
+def is_op_success(o, is_temphash_active):
+    if o == OP_TEMPLATEHASH:
+        return not is_temphash_active
     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 af6912ed68f35f484c59660c49445a01a6335882 Mon Sep 17 00:00:00 2001
From: Antoine Poinsot <darosior@protonmail.com>
Date: Wed, 11 Jun 2025 15:56:14 -0400
Subject: [PATCH 04/12] 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 | 364 ++++++++++++++++++++++++++++++++++++++
 src/test/util/script.h    |  39 ++++
 2 files changed, 403 insertions(+)

diff --git a/src/test/script_tests.cpp b/src/test/script_tests.cpp
index 0aaaf0a8f615..4429e54d288e 100644
--- a/src/test/script_tests.cpp
+++ b/src/test/script_tests.cpp
@@ -6,6 +6,7 @@
 #include <compressor.h>
 #include <core_io.h>
 #include <key.h>
+#include <policy/policy.h>
 #include <rpc/util.h>
 #include <script/interpreter.h>
 #include <script/script.h>
@@ -21,6 +22,7 @@
 #include <test/util/common.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 <univalue.h>
@@ -1732,4 +1734,366 @@ BOOST_AUTO_TEST_CASE(formatscriptflags)
     BOOST_CHECK_EQUAL(FormatScriptFlags(script_verify_flags::from_int(1u<<26)), "0x04000000");
 }
 
+/** 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 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;
+    assert(SCRIPT_VERIFY_TEMPLATEHASH & MANDATORY_SCRIPT_VERIFY_FLAGS);
+    bool res{VerifyScript(tx.vin[in_index].scriptSig, spent_spk, &tx.vin[in_index].scriptWitness, MANDATORY_SCRIPT_VERIFY_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, ToScript("001482074bdf6ce32b071dd120a17cf99cbc01ad3080"_hex));
+
+    // 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, ToScript("76a914079ded3e3befdab0757fe0e8842aeffc0ff2160288ac"_hex)};
+    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 pass when committing to and spending a non-zero input index.
+    {
+        CMutableTransaction tx2{tx};
+        auto spent_outputs2{spent_outputs};
+
+        // Commit the template hash for input index 1 in an output placed at index 1.
+        const uint256 hash_in1{GetTemplateHash(tx2, 1)};
+        const auto leaf_script1{CScript() << hash_in1 << OP_TEMPLATEHASH << OP_EQUAL};
+        TaprootBuilder builder1;
+        builder1.Add(0, leaf_script1, TAPROOT_LEAF_TAPSCRIPT);
+        builder1.Finalize(XOnlyPubKey::NUMS_H);
+        spent_outputs2[1].scriptPubKey = GetScriptForDestination(builder1.GetOutput());
+
+        const auto spend_data1{builder1.GetSpendData()};
+        const auto& cb1{*spend_data1.scripts.begin()->second.begin()};
+        tx2.vin[1].scriptWitness.stack.clear();
+        tx2.vin[1].scriptWitness.stack.emplace_back(leaf_script1.begin(), leaf_script1.end());
+        tx2.vin[1].scriptWitness.stack.emplace_back(cb1.begin(), cb1.end());
+
+        CheckTemplateMatch(tx2, std::move(spent_outputs2), 1, /*is_valid=*/true, test_cases, std::string{"Template hash matches at a non-zero input index."});
+    }
+
+    // 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 = ToScript("001482074bdf6ce32b071dd120a17cf99cbc01ad3081"_hex);
+        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 = ToScript("0014266a4832c001885db26e853ef1d1dde840f7dbaf"_hex);
+        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
+}
+
+/** OP_TEMPLATEHASH is only defined in Tapscript. In legacy and witness v0 scripts it must behave
+ *  like any other undefined opcode (SCRIPT_ERR_BAD_OPCODE), even when the consensus rule is active. */
+BOOST_AUTO_TEST_CASE(templatehash_outside_tapscript)
+{
+    const CScript script{CScript() << OP_TEMPLATEHASH};
+    for (const SigVersion sigversion : {SigVersion::BASE, SigVersion::WITNESS_V0}) {
+        std::vector<std::vector<unsigned char>> stack;
+        ScriptError err;
+        const bool res{EvalScript(stack, script, SCRIPT_VERIFY_TEMPLATEHASH, BaseSignatureChecker(), sigversion, &err)};
+        BOOST_CHECK(!res);
+        BOOST_CHECK_MESSAGE(err == ScriptError::SCRIPT_ERR_BAD_OPCODE, ScriptErrorString(err));
+    }
+}
+
+/** Exercise the three states of OP_TEMPLATEHASH in Tapscript: discouraged as a policy rule before
+ *  activation, an unconditional OP_SUCCESS at the consensus level before activation, and an
+ *  executed opcode once active. */
+BOOST_AUTO_TEST_CASE(templatehash_activation_states)
+{
+    // A Tapscript that is trivially satisfied once OP_TEMPLATEHASH executes.
+    const CScript leaf_script{CScript() << OP_TEMPLATEHASH << OP_DROP << OP_1};
+    TaprootBuilder builder;
+    builder.Add(0, leaf_script, TAPROOT_LEAF_TAPSCRIPT);
+    builder.Finalize(XOnlyPubKey::NUMS_H);
+    const CScript spent_spk{GetScriptForDestination(builder.GetOutput())};
+
+    CMutableTransaction tx;
+    tx.vin = {CTxIn{*Txid::FromHex("0437cd7f8525ceed2324359c2d0ba26006d92d856a9c20fa0241106ee5a597c9"), 21}};
+    tx.vout.emplace_back(424242, ToScript("001482074bdf6ce32b071dd120a17cf99cbc01ad3080"_hex));
+    const std::vector<CTxOut> spent_outputs{CTxOut{424243, spent_spk}};
+
+    const auto spend_data{builder.GetSpendData()};
+    const auto& cb{*spend_data.scripts.begin()->second.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());
+
+    PrecomputedTransactionData precomp;
+    precomp.Init(tx, std::vector<CTxOut>{spent_outputs});
+    const auto checker{GenericTransactionSignatureChecker(&tx, 0, CAmount{0}, precomp, MissingDataBehavior::ASSERT_FAIL)};
+    const auto verify{[&](script_verify_flags flags, ScriptError& err) {
+        return VerifyScript(tx.vin[0].scriptSig, spent_spk, &tx.vin[0].scriptWitness, flags, checker, &err);
+    }};
+    const script_verify_flags base{SCRIPT_VERIFY_P2SH | SCRIPT_VERIFY_WITNESS | SCRIPT_VERIFY_TAPROOT};
+    ScriptError err;
+
+    // Before activation, as a standardness rule: discouraged.
+    BOOST_CHECK(!verify(base | SCRIPT_VERIFY_DISCOURAGE_TEMPLATEHASH, err));
+    BOOST_CHECK_MESSAGE(err == ScriptError::SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH, ScriptErrorString(err));
+
+    // Before activation, at the consensus level: still an OP_SUCCESS, so unconditionally valid.
+    BOOST_CHECK_MESSAGE(verify(base, err), ScriptErrorString(err));
+
+    // Once active: the opcode executes and the script is satisfied.
+    BOOST_CHECK_MESSAGE(verify(base | SCRIPT_VERIFY_TEMPLATEHASH, err), ScriptErrorString(err));
+}
+
 BOOST_AUTO_TEST_SUITE_END()
diff --git a/src/test/util/script.h b/src/test/util/script.h
index 44d9acd9197e..b49759457f40 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 a360dd5778ee1c848e61204288864e3f568b1435 Mon Sep 17 00:00:00 2001
From: Antoine Poinsot <darosior@protonmail.com>
Date: Wed, 11 Jun 2025 10:41:48 -0400
Subject: [PATCH 05/12] 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 | 213 +++++++++++++++++++++++++++++++++
 2 files changed, 214 insertions(+)
 create mode 100644 src/test/fuzz/templatehash.cpp

diff --git a/src/test/fuzz/CMakeLists.txt b/src/test/fuzz/CMakeLists.txt
index a159ef7e11cd..54a18be1f9a4 100644
--- a/src/test/fuzz/CMakeLists.txt
+++ b/src/test/fuzz/CMakeLists.txt
@@ -122,6 +122,7 @@ add_executable(fuzz
   string.cpp
   strprintf.cpp
   system.cpp
+  templatehash.cpp
   threadpool.cpp
   timeoffsets.cpp
   torcontrol.cpp
diff --git a/src/test/fuzz/templatehash.cpp b/src/test/fuzz/templatehash.cpp
new file mode 100644
index 000000000000..75daa09c1d8d
--- /dev/null
+++ b/src/test/fuzz/templatehash.cpp
@@ -0,0 +1,213 @@
+// 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{1'000};
+//! Verification flags to set for script validation.
+static constexpr script_verify_flags 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.push_back(annex);  // TODO: 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);
+        },
+        // Adding an output changes sha_outputs and invalidates the template hash.
+        [&] {
+            tx.vout.emplace_back();
+            Assert(!VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk));
+        },
+        // Removing an output changes sha_outputs and invalidates the template hash.
+        [&] {
+            if (tx.vout.empty()) return;
+            tx.vout.pop_back();
+            Assert(!VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk));
+        },
+        // Adding an input changes sha_sequences and invalidates the template hash.
+        [&] {
+            tx.vin.emplace_back();
+            spent_outputs.emplace_back();
+            Assert(!VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk));
+        },
+        // Removing an input changes sha_sequences and invalidates the template hash. Only the last
+        // input is removed, so the index being spent stays valid and in place.
+        [&] {
+            if (tx.vin.size() < 2 || in_index + 1 == tx.vin.size()) return;
+            tx.vin.pop_back();
+            spent_outputs.pop_back();
+            Assert(!VerifyTemplateCheck(tx, in_index, std::move(spent_outputs), spent_spk));
+        }
+    );
+}

From 8bea35b5a4ade5c02b32a7795aad7cb52eb55637 Mon Sep 17 00:00:00 2001
From: Greg Sanders <gsanders87@gmail.com>
Date: Fri, 13 Jun 2025 13:26:52 -0400
Subject: [PATCH 06/12] 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       | 163 ++++++++++++++--
 test/functional/feature_templatehash.py  | 238 +++++++++++++++++++++++
 test/functional/test_framework/script.py |  15 ++
 test/functional/test_runner.py           |   1 +
 4 files changed, 397 insertions(+), 20 deletions(-)
 create mode 100755 test/functional/feature_templatehash.py

diff --git a/test/functional/feature_taproot.py b/test/functional/feature_taproot.py
index 2d9f34032dfa..bacea2656b1a 100755
--- a/test/functional/feature_taproot.py
+++ b/test/functional/feature_taproot.py
@@ -71,7 +71,9 @@
     OP_NOTIF,
     OP_PUSHDATA1,
     OP_RETURN,
+    OP_SIZE,
     OP_SWAP,
+    OP_TEMPLATEHASH,
     OP_TUCK,
     OP_VERIFY,
     SIGHASH_DEFAULT,
@@ -82,6 +84,7 @@
     SegwitV0SignatureMsg,
     TaggedHash,
     TaprootSignatureMsg,
+    TemplateMsg,
     is_op_success,
     taproot_construct,
 )
@@ -273,6 +276,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:
@@ -407,6 +422,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.
@@ -641,6 +660,7 @@ def byte_popper(expr):
 ERR_WITNESS_PROGRAM_WITNESS_EMPTY = {"err_msg": "Witness program was passed an empty witness"}
 ERR_CHECKSIGVERIFY = {"err_msg": "Script failed an OP_CHECKSIGVERIFY operation"}
 ERR_SCRIPT_NUM = {"err_msg": "Script number overflowed or is non-minimally encoded"}
+SCRIPT_ERR_EQUALVERIFY = {"err_msg": "Script failed an OP_EQUALVERIFY operation"}
 
 VALID_SIGHASHES_ECDSA = [
     SIGHASH_ALL,
@@ -674,7 +694,7 @@ def byte_popper(expr):
 # === Actual test cases ===
 
 
-def spenders_taproot_active():
+def spenders_taproot_active(template_active):
     """Return a list of Spenders for testing post-Taproot activation behavior."""
 
     secs = [generate_privkey() for _ in range(8)]
@@ -1172,7 +1192,7 @@ def predict_sigops_ratio(n, dummy_size):
     hashtype = lambda _: random.choice(VALID_SIGHASHES_TAPROOT)
     for opval in range(76, 0x100):
         opcode = CScriptOp(opval)
-        if not is_op_success(opcode, is_temphash_active=True):
+        if not is_op_success(opcode, is_temphash_active=template_active):
             continue
         scripts = [
             ("bare_success", CScript([opcode])),
@@ -1203,7 +1223,7 @@ def predict_sigops_ratio(n, dummy_size):
     # Non-OP_SUCCESSx (verify that those aren't accidentally treated as OP_SUCCESSx)
     for opval in range(0, 0x100):
         opcode = CScriptOp(opval)
-        if is_op_success(opcode, is_temphash_active=True):
+        if is_op_success(opcode, is_temphash_active=template_active):
             continue
         scripts = [
             ("normal", CScript([OP_RETURN, opcode] + [OP_NOP] * 75)),
@@ -1231,13 +1251,16 @@ 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_EVAL_FALSE)
                     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_EVAL_FALSE)
 
-    # Verify that OP_CHECKSIGADD wasn't accidentally added to pre-taproot validation logic.
+    # Verify that OP_CHECKSIGADD, 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)]:
                 standard = hashtype in VALID_SIGHASHES_ECDSA and (p2sh or witv0)
                 add_spender(spenders, "compat/nocsa", hashtype=hashtype, p2sh=p2sh, witv0=witv0, standard=standard, script=CScript([OP_IF, OP_11, pubkey1, OP_CHECKSIGADD, OP_12, OP_EQUAL, OP_ELSE, pubkey1, OP_CHECKSIG, OP_ENDIF]), key=eckey1, sigops_weight=4-3*witv0, inputs=[getter("sign"), b''], failure={"inputs": [getter("sign"), b'\x01']}, **ERR_BAD_OPCODE)
 
+            # Should still fail if not in executed branch
+            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 ==
 
     # Sighash caching in legacy.
@@ -1304,6 +1327,82 @@ def predict_sigops_ratio(n, dummy_size):
 
     return spenders
 
+def generate_template_spenders_consensus():
+    """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"}, **SCRIPT_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
+
+def generate_template_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 spenders_taproot_nonstandard():
     """Spenders for testing that post-activation Taproot rules may be nonstandard."""
@@ -1366,11 +1465,14 @@ def sample_spenders():
 # Consensus validation flags to use in dumps for all other tests.
 TAPROOT_FLAGS = "P2SH,DERSIG,CHECKLOCKTIMEVERIFY,CHECKSEQUENCEVERIFY,WITNESS,NULLDUMMY,TAPROOT"
 
-def dump_json_test(tx, input_utxos, idx, success, failure):
+def dump_json_test(tx, input_utxos, idx, success, failure, template_active):
     spender = input_utxos[idx].spender
     # Determine flags to dump
     flags = LEGACY_FLAGS if spender.comment.startswith("legacy/") or spender.comment.startswith("inactive/") else TAPROOT_FLAGS
 
+    if template_active and flags == TAPROOT_FLAGS:
+        flags += ",TEMPLATEHASH"
+
     fields = [
         ("tx", tx.serialize().hex()),
         ("prevouts", [x.output.serialize().hex() for x in input_utxos]),
@@ -1415,6 +1517,7 @@ def skip_test_if_missing_module(self):
     def set_test_params(self):
         self.num_nodes = 1
         self.setup_clean_chain = True
+        self.extra_args = [[f"-vbparams=templatehash:0:{2**63 - 1}"]] # test activation of templatehash
 
     def block_submit(self, node, txs, msg, err_msg, cb_pubkey=None, fees=0, sigops_weight=0, witness=False, accept=False):
 
@@ -1448,7 +1551,7 @@ def init_blockinfo(self, node):
         self.lastblockheight = block['height']
         self.lastblocktime = block['time']
 
-    def test_spenders(self, node, spenders, input_counts):
+    def test_spenders(self, node, spenders, input_counts, template_active):
         """Run randomized tests with a number of "spenders".
 
         Steps:
@@ -1613,7 +1716,7 @@ def test_spenders(self, node, spenders, input_counts):
                     fail = fn(tx, i, [utxo.output for utxo in input_utxos], False)
                 input_data.append((fail, success))
                 if self.options.dump_tests:
-                    dump_json_test(tx, input_utxos, i, success, fail)
+                    dump_json_test(tx, input_utxos, i, success, fail, template_active)
 
             # Sign each input incorrectly once on each complete signing pass, except the very last.
             for fail_input in list(range(len(input_utxos))) + [None]:
@@ -1883,19 +1986,39 @@ def run_test(self):
 
         self.log.info("Post-activation tests...")
 
-        # New sub-tests not checking standardness can be added to consensus_spenders
-        # to allow for increased coverage across input types.
-        # See sample_spenders for a minimal example
-        consensus_spenders = sample_spenders()
-        consensus_spenders += spenders_taproot_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
-        # when all their inputs are standard).
-        nonstd_spenders = spenders_taproot_nonstandard()
-        self.test_spenders(self.nodes[0], nonstd_spenders, input_counts=[1])
-        self.test_spenders(self.nodes[0], nonstd_spenders, input_counts=[2, 3])
+        # Run all non-TEMPLATEHASH tests pre and post-activation to avoid regressions
+        for template_active in [False, True]:
+            discouragement_spenders = spenders_taproot_nonstandard()
+            consensus_spenders = spenders_taproot_active(template_active=template_active)
+
+            if not template_active:
+                self.log.info("TEMPLATEHASH Pre-activation tests...")
+                assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["bip9"]["status"], "defined")
+
+                # Discouragement tests to ensure non-inclusion in mempool before activation
+                discouragement_spenders += generate_template_spenders_nonstandard()
+
+            else:
+                self.log.info("Activating TEMPLATEHASH softfork")
+                # Blocks being created until now have not signalled
+                self.generate(self.nodes[0], 432)
+                assert_equal(self.nodes[0].getdeploymentinfo()["deployments"]["templatehash"]["bip9"]["status"], "active")
+
+                self.log.info("TEMPLATEHASH Post-activation tests...")
+                # Test coverage for committed hash in outputs is not included here but in
+                # feature_templatehash.py
+                consensus_spenders += generate_template_spenders_consensus()
+
+            # New sub-tests not checking standardness can be added to consensus_spenders
+            # to allow for increased coverage across input types.
+            # See sample_spenders for a minimal example
+            self.test_spenders(self.nodes[0], consensus_spenders, input_counts=[1, 2, 2, 2, 2, 3], template_active=template_active)
+
+            # 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
+            # when all their inputs are standard).
+            self.test_spenders(self.nodes[0], discouragement_spenders, input_counts=[1], template_active=template_active)
+            self.test_spenders(self.nodes[0], discouragement_spenders, input_counts=[2, 3], template_active=template_active)
 
 
 if __name__ == '__main__':
diff --git a/test/functional/feature_templatehash.py b/test/functional/feature_templatehash.py
new file mode 100755
index 000000000000..8bc0300c47b8
--- /dev/null
+++ b/test/functional/feature_templatehash.py
@@ -0,0 +1,238 @@
+#!/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.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_discourage_no_disconnect(self):
+        self.log.info("Testing discouragement doesn't result in disconnection")
+        node = self.nodes[0]
+
+        # Checking for non-disconnection
+        peer = node.add_p2p_connection(P2PInterface())
+        scripts = [
+            ("basic", CScript([OP_TEMPLATEHASH])),
+        ]
+        tap = taproot_construct(self.public_keys[0], scripts)
+
+        # Seed a utxo with script
+        commit_tx = self.wallet.send_to(from_node=node, scriptPubKey=tap.scriptPubKey, amount=330)
+
+        tx = CTransaction()
+        tx.vin.append(CTxIn(COutPoint(commit_tx["tx"].txid_int, commit_tx["sent_vout"]), b"", SEQUENCE_FINAL))
+        tx.vout.append(CTxOut(0, CScript([OP_RETURN, b"\x00\x00\x00\x00"])))
+
+        # And fill out witness data for spend
+        tx.wit.vtxinwit = [CTxInWitness()]
+        control_block = bytes([tap.leaves["basic"].version | tap.negflag]) + tap.internal_pubkey + tap.leaves["basic"].merklebranch
+        tx.wit.vtxinwit[0].scriptWitness.stack = [tap.leaves["basic"].script, control_block]
+
+        assert_raises_rpc_error(-26, "mempool-script-verify-flag-failed (Templatehash is not active)", node.sendrawtransaction, tx.serialize().hex())
+        peer.send_and_ping(msg_tx(tx))
+        node.disconnect_p2ps()
+        self.generate(self.wallet, 1)
+
+    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 = commit_tx["tx"].txid_int
+        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 = commit_tx["tx"].txid_int
+        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: block-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: block-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: block-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: block-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: block-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: block-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: block-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.wallet = MiniWallet(node)
+        self.generate(self.wallet, 101)
+        assert_equal(node.getdeploymentinfo()["deployments"]["templatehash"]["bip9"]["status"], "defined")
+
+        self.test_discourage_no_disconnect()
+
+        self.log.info("Activating templatehash")
+        self.generate(self.nodes[0], 432-101)
+        assert_equal(node.getdeploymentinfo()["deployments"]["templatehash"]["bip9"]["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 83f4dd271e5d..85130a03ed27 100644
--- a/test/functional/test_framework/script.py
+++ b/test/functional/test_framework/script.py
@@ -818,6 +818,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):
     assert_equal(len(txTo.vin), len(spent_utxos))
     assert input_index < len(txTo.vin)
diff --git a/test/functional/test_runner.py b/test/functional/test_runner.py
index 5bfc7d86239b..867466a31e5a 100755
--- a/test/functional/test_runner.py
+++ b/test/functional/test_runner.py
@@ -391,6 +391,7 @@
     'feature_framework_startup_failures.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

From a01d605054e4a3c33fb89c15fda831000d2bdf09 Mon Sep 17 00:00:00 2001
From: Gregory Sanders <gsanders87@gmail.com>
Date: Wed, 24 Jun 2026 12:18:25 -0400
Subject: [PATCH 07/12] pubkey: take a span message in
 XOnlyPubKey::VerifySchnorr

---
 src/pubkey.cpp | 4 ++--
 src/pubkey.h   | 5 +++--
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/pubkey.cpp b/src/pubkey.cpp
index 264f861bc7a4..7f6775bb8ab0 100644
--- a/src/pubkey.cpp
+++ b/src/pubkey.cpp
@@ -233,12 +233,12 @@ bool XOnlyPubKey::IsFullyValid() const
     return secp256k1_xonly_pubkey_parse(secp256k1_context_static, &pubkey, m_keydata.data());
 }
 
-bool XOnlyPubKey::VerifySchnorr(const uint256& msg, std::span<const unsigned char> sigbytes) const
+bool XOnlyPubKey::VerifySchnorr(std::span<const unsigned char> msg, std::span<const unsigned char> sigbytes) const
 {
     assert(sigbytes.size() == 64);
     secp256k1_xonly_pubkey pubkey;
     if (!secp256k1_xonly_pubkey_parse(secp256k1_context_static, &pubkey, m_keydata.data())) return false;
-    return secp256k1_schnorrsig_verify(secp256k1_context_static, sigbytes.data(), msg.begin(), 32, &pubkey);
+    return secp256k1_schnorrsig_verify(secp256k1_context_static, sigbytes.data(), msg.data(), msg.size(), &pubkey);
 }
 
 static const HashWriter HASHER_TAPTWEAK{TaggedHash("TapTweak")};
diff --git a/src/pubkey.h b/src/pubkey.h
index 0391609ebcc3..da2cae854970 100644
--- a/src/pubkey.h
+++ b/src/pubkey.h
@@ -255,9 +255,10 @@ class XOnlyPubKey
 
     /** Verify a Schnorr signature against this public key.
      *
-     * sigbytes must be exactly 64 bytes.
+     * msg may be of any length: per BIP340 the message is not required to be a
+     * 32-byte hash. sigbytes must be exactly 64 bytes.
      */
-    bool VerifySchnorr(const uint256& msg, std::span<const unsigned char> sigbytes) const;
+    bool VerifySchnorr(std::span<const unsigned char> msg, std::span<const unsigned char> sigbytes) const;
 
     /** Compute the Taproot tweak as specified in BIP341, with *this as internal
      * key:

From db1f5c02dbfd53134446b9e4dc4dcf322aade67d Mon Sep 17 00:00:00 2001
From: Gregory Sanders <gsanders87@gmail.com>
Date: Wed, 24 Jun 2026 12:21:57 -0400
Subject: [PATCH 08/12] consensus: implement OP_CHECKSIGFROMSTACK (BIP-348)

---
 src/script/interpreter.cpp               | 89 +++++++++++++++++++++++-
 src/script/script.cpp                    |  3 +
 src/script/script.h                      |  3 +
 src/script/script_error.cpp              |  2 +-
 test/functional/feature_templatehash.py  |  2 +-
 test/functional/test_framework/script.py |  6 +-
 6 files changed, 99 insertions(+), 6 deletions(-)

diff --git a/src/script/interpreter.cpp b/src/script/interpreter.cpp
index 95b87bcaf4c9..c32e1c2d09b1 100644
--- a/src/script/interpreter.cpp
+++ b/src/script/interpreter.cpp
@@ -414,6 +414,57 @@ static bool EvalChecksig(const valtype& sig, const valtype& pubkey, CScript::con
     assert(false);
 }
 
+/** Helper for OP_CHECKSIGFROMSTACK (BIP-348).
+ *
+ * Returns false when script execution must immediately fail. On success, success_out indicates
+ * whether the signature check itself succeeded (false only for an empty signature).
+ */
+static bool EvalChecksigFromStack(const valtype& sig, const valtype& msg, const valtype& pubkey_in, ScriptExecutionData& execdata, script_verify_flags flags, SigVersion sigversion, ScriptError* serror, bool& success_out)
+{
+    assert(sigversion == SigVersion::TAPSCRIPT);
+
+    /*
+     *  The following validation sequence is consensus critical. Please note how --
+     *    upgradable public key versions precede other rules;
+     *    the script execution fails when using empty signature with invalid public key;
+     *    the script execution fails when using non-empty invalid signature.
+     */
+    success_out = !sig.empty();
+    if (success_out) {
+        // Implement the sigops/witnesssize ratio test.
+        // Passing with an upgradable public key version is also counted.
+        assert(execdata.m_validation_weight_left_init);
+        execdata.m_validation_weight_left -= VALIDATION_WEIGHT_PER_SIGOP_PASSED;
+        if (execdata.m_validation_weight_left < 0) {
+            return set_error(serror, SCRIPT_ERR_TAPSCRIPT_VALIDATION_WEIGHT);
+        }
+    }
+    if (pubkey_in.size() == 0) {
+        return set_error(serror, SCRIPT_ERR_TAPSCRIPT_EMPTY_PUBKEY);
+    } else if (pubkey_in.size() == 32) {
+        if (success_out) {
+            if (sig.size() != 64) {
+                return set_error(serror, SCRIPT_ERR_SCHNORR_SIG_SIZE);
+            }
+            XOnlyPubKey pubkey{pubkey_in};
+            if (!pubkey.VerifySchnorr(msg, sig)) {
+                return set_error(serror, SCRIPT_ERR_SCHNORR_SIG);
+            }
+        }
+    } else {
+        /*
+         *  New public key version softforks should be defined before this `else` block.
+         *  Generally, the new code should not do anything but failing the script execution. To avoid
+         *  consensus bugs, it should not modify any existing values (including `success_out`).
+         */
+        if ((flags & SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_PUBKEYTYPE) != 0) {
+            return set_error(serror, SCRIPT_ERR_DISCOURAGE_UPGRADABLE_PUBKEYTYPE);
+        }
+    }
+
+    return true;
+}
+
 bool EvalScript(std::vector<std::vector<unsigned char> >& stack, const CScript& script, script_verify_flags flags, const BaseSignatureChecker& checker, SigVersion sigversion, ScriptExecutionData& execdata, ScriptError* serror)
 {
     static const CScriptNum bnZero(0);
@@ -1238,6 +1289,38 @@ bool EvalScript(std::vector<std::vector<unsigned char> >& stack, const CScript&
                 }
                 break;
 
+                case OP_CHECKSIGFROMSTACK:
+                {
+                    // DISCOURAGE/activation for OP_CHECKSIGFROMSTACK is handled in OP_SUCCESS handling.
+                    // OP_CHECKSIGFROMSTACK is only available in Tapscript.
+                    if (sigversion == SigVersion::BASE || sigversion == SigVersion::WITNESS_V0) {
+                        return set_error(serror, SCRIPT_ERR_BAD_OPCODE);
+                    }
+
+                    // If fewer than 3 elements are on the stack, the script MUST fail and terminate immediately.
+                    if (stack.size() < 3) {
+                        return set_error(serror, SCRIPT_ERR_INVALID_STACK_OPERATION);
+                    }
+
+                    // The public key (top element), message (second to top element), and
+                    // signature (third from top element) are read from the stack.
+                    const valtype& pubkey = stacktop(-1);
+                    const valtype& msg = stacktop(-2);
+                    const valtype& sig = stacktop(-3);
+
+                    bool push_success{true};
+                    if (!EvalChecksigFromStack(sig, msg, pubkey, execdata, flags, sigversion, serror, push_success)) {
+                        return false; // serror set by EvalChecksigFromStack
+                    }
+
+                    popstack(stack);
+                    popstack(stack);
+                    popstack(stack);
+
+                    stack.push_back(push_success ? vchTrue : vchFalse);
+                }
+                break;
+
                 default:
                     return set_error(serror, SCRIPT_ERR_BAD_OPCODE);
             }
@@ -1890,9 +1973,9 @@ static bool ExecuteWitnessScript(const std::span<const valtype>& stack_span, con
             }
             // New opcodes will be listed here. May use a different sigversion to modify existing opcodes.
             if (IsOpSuccess(opcode)) {
-                // Do not return early success on OP_TEMPLATEHASH (OP_SUCCESS206) once it is active. It is
-                // non-standard until then.
-                if (opcode == OP_TEMPLATEHASH) {
+                // Do not return early success on the BIP-448 opcodes (OP_TEMPLATEHASH,
+                // OP_CHECKSIGFROMSTACK) once they are active. They are non-standard until then.
+                if (opcode == OP_TEMPLATEHASH || opcode == OP_CHECKSIGFROMSTACK) {
                     if (flags & SCRIPT_VERIFY_DISCOURAGE_TEMPLATEHASH) {
                         return set_error(serror, SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH);
                     }
diff --git a/src/script/script.cpp b/src/script/script.cpp
index ca474078f5e3..38d0fa81480b 100644
--- a/src/script/script.cpp
+++ b/src/script/script.cpp
@@ -153,6 +153,9 @@ std::string GetOpName(opcodetype opcode)
     // Opcode added by BIP446 (Tapscript)
     case OP_TEMPLATEHASH           : return "OP_TEMPLATEHASH";
 
+    // Opcode added by BIP348 (Tapscript)
+    case OP_CHECKSIGFROMSTACK      : return "OP_CHECKSIGFROMSTACK";
+
     case OP_INVALIDOPCODE          : return "OP_INVALIDOPCODE";
 
     } // no default case, so the compiler can warn about missing cases
diff --git a/src/script/script.h b/src/script/script.h
index 329cfb851ffa..2c55e99d8ab8 100644
--- a/src/script/script.h
+++ b/src/script/script.h
@@ -213,6 +213,9 @@ enum opcodetype
     // Opcode added by BIP xx (Tapscript-only, formerly OP_SUCCESS206)
     OP_TEMPLATEHASH = 0xce,
 
+    // Opcode added by BIP348 (Tapscript-only, formerly OP_SUCCESS204)
+    OP_CHECKSIGFROMSTACK = 0xcc,
+
     OP_INVALIDOPCODE = 0xff,
 };
 
diff --git a/src/script/script_error.cpp b/src/script/script_error.cpp
index 53f6a09ee93b..afcabad76a0d 100644
--- a/src/script/script_error.cpp
+++ b/src/script/script_error.cpp
@@ -80,7 +80,7 @@ std::string ScriptErrorString(const ScriptError serror)
         case SCRIPT_ERR_DISCOURAGE_UPGRADABLE_PUBKEYTYPE:
             return "Public key version reserved for soft-fork upgrades";
         case SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH:
-            return "Templatehash is not active";
+            return "BIP-448 opcode not active";
         case SCRIPT_ERR_PUBKEYTYPE:
             return "Public key is neither compressed or uncompressed";
         case SCRIPT_ERR_CLEANSTACK:
diff --git a/test/functional/feature_templatehash.py b/test/functional/feature_templatehash.py
index 8bc0300c47b8..9aa5233ba7de 100755
--- a/test/functional/feature_templatehash.py
+++ b/test/functional/feature_templatehash.py
@@ -73,7 +73,7 @@ def test_discourage_no_disconnect(self):
         control_block = bytes([tap.leaves["basic"].version | tap.negflag]) + tap.internal_pubkey + tap.leaves["basic"].merklebranch
         tx.wit.vtxinwit[0].scriptWitness.stack = [tap.leaves["basic"].script, control_block]
 
-        assert_raises_rpc_error(-26, "mempool-script-verify-flag-failed (Templatehash is not active)", node.sendrawtransaction, tx.serialize().hex())
+        assert_raises_rpc_error(-26, "mempool-script-verify-flag-failed (BIP-448 opcode not active)", node.sendrawtransaction, tx.serialize().hex())
         peer.send_and_ping(msg_tx(tx))
         node.disconnect_p2ps()
         self.generate(self.wallet, 1)
diff --git a/test/functional/test_framework/script.py b/test/functional/test_framework/script.py
index 85130a03ed27..42e5d9ea373b 100644
--- a/test/functional/test_framework/script.py
+++ b/test/functional/test_framework/script.py
@@ -259,6 +259,9 @@ def __new__(cls, n):
 # BIP xx opcode (Tapscript-only, formerly OP_SUCCESS206)
 OP_TEMPLATEHASH = CScriptOp(0xce)
 
+# BIP348 opcode (Tapscript-only, formerly OP_SUCCESS204)
+OP_CHECKSIGFROMSTACK = CScriptOp(0xcc)
+
 OP_INVALIDOPCODE = CScriptOp(0xff)
 
 OPCODE_NAMES.update({
@@ -375,6 +378,7 @@ def __new__(cls, n):
     OP_NOP10: 'OP_NOP10',
     OP_CHECKSIGADD: 'OP_CHECKSIGADD',
     OP_TEMPLATEHASH: 'OP_TEMPLATEHASH',
+    OP_CHECKSIGFROMSTACK: 'OP_CHECKSIGFROMSTACK',
     OP_INVALIDOPCODE: 'OP_INVALIDOPCODE',
 })
 
@@ -960,6 +964,6 @@ def taproot_construct(pubkey, scripts=None, treat_internal_as_infinity=False):
     return TaprootInfo(CScript([OP_1, tweaked]), pubkey, negated + 0, tweak, leaves, h, tweaked)
 
 def is_op_success(o, is_temphash_active):
-    if o == OP_TEMPLATEHASH:
+    if o == OP_TEMPLATEHASH or o == OP_CHECKSIGFROMSTACK:
         return not is_temphash_active
     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 f15a1d429b723bbfb83c852884a2b8814c351e7d Mon Sep 17 00:00:00 2001
From: Gregory Sanders <gsanders87@gmail.com>
Date: Wed, 24 Jun 2026 12:23:44 -0400
Subject: [PATCH 09/12] consensus: implement OP_INTERNALKEY (BIP-349)

---
 src/script/interpreter.cpp               | 18 ++++++++++++++++--
 src/script/interpreter.h                 |  3 +++
 src/script/script.cpp                    |  3 +++
 src/script/script.h                      |  3 +++
 test/functional/test_framework/script.py |  6 +++++-
 5 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/src/script/interpreter.cpp b/src/script/interpreter.cpp
index c32e1c2d09b1..1d99e2f6a2c4 100644
--- a/src/script/interpreter.cpp
+++ b/src/script/interpreter.cpp
@@ -1321,6 +1321,18 @@ bool EvalScript(std::vector<std::vector<unsigned char> >& stack, const CScript&
                 }
                 break;
 
+                case OP_INTERNALKEY:
+                {
+                    // OP_INTERNALKEY is only available in Tapscript.
+                    if (sigversion == SigVersion::BASE || sigversion == SigVersion::WITNESS_V0) {
+                        return set_error(serror, SCRIPT_ERR_BAD_OPCODE);
+                    }
+                    // The internal key is always set when executing Tapscript (see VerifyWitnessProgram).
+                    assert(execdata.m_internal_key);
+                    stack.emplace_back(execdata.m_internal_key->begin(), execdata.m_internal_key->end());
+                }
+                break;
+
                 default:
                     return set_error(serror, SCRIPT_ERR_BAD_OPCODE);
             }
@@ -1974,8 +1986,8 @@ static bool ExecuteWitnessScript(const std::span<const valtype>& stack_span, con
             // New opcodes will be listed here. May use a different sigversion to modify existing opcodes.
             if (IsOpSuccess(opcode)) {
                 // Do not return early success on the BIP-448 opcodes (OP_TEMPLATEHASH,
-                // OP_CHECKSIGFROMSTACK) once they are active. They are non-standard until then.
-                if (opcode == OP_TEMPLATEHASH || opcode == OP_CHECKSIGFROMSTACK) {
+                // OP_CHECKSIGFROMSTACK, OP_INTERNALKEY) once they are active. They are non-standard until then.
+                if (opcode == OP_TEMPLATEHASH || opcode == OP_CHECKSIGFROMSTACK || opcode == OP_INTERNALKEY) {
                     if (flags & SCRIPT_VERIFY_DISCOURAGE_TEMPLATEHASH) {
                         return set_error(serror, SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH);
                     }
@@ -2119,6 +2131,8 @@ static bool VerifyWitnessProgram(const CScriptWitness& witness, int witversion,
                 exec_script = CScript(script.begin(), script.end());
                 execdata.m_validation_weight_left = ::GetSerializeSize(witness.stack) + VALIDATION_WEIGHT_OFFSET;
                 execdata.m_validation_weight_left_init = true;
+                // Expose the verified 32-byte internal key (control[1:33]) for OP_INTERNALKEY.
+                execdata.m_internal_key = uint256{std::span{control}.subspan(1, 32)};
                 return ExecuteWitnessScript(stack, exec_script, flags, SigVersion::TAPSCRIPT, checker, execdata, serror);
             }
             if (flags & SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_TAPROOT_VERSION) {
diff --git a/src/script/interpreter.h b/src/script/interpreter.h
index b8538c9c653e..95f015e78df4 100644
--- a/src/script/interpreter.h
+++ b/src/script/interpreter.h
@@ -238,6 +238,9 @@ struct ScriptExecutionData
 
     //! The hash of the corresponding output
     std::optional<uint256> m_output_hash;
+
+    //! The 32-byte x-only Taproot internal key, set for Tapscript spends (for OP_INTERNALKEY).
+    std::optional<uint256> m_internal_key;
 };
 
 /** Signature hash sizes */
diff --git a/src/script/script.cpp b/src/script/script.cpp
index 38d0fa81480b..56358292c1df 100644
--- a/src/script/script.cpp
+++ b/src/script/script.cpp
@@ -156,6 +156,9 @@ std::string GetOpName(opcodetype opcode)
     // Opcode added by BIP348 (Tapscript)
     case OP_CHECKSIGFROMSTACK      : return "OP_CHECKSIGFROMSTACK";
 
+    // Opcode added by BIP349 (Tapscript)
+    case OP_INTERNALKEY            : return "OP_INTERNALKEY";
+
     case OP_INVALIDOPCODE          : return "OP_INVALIDOPCODE";
 
     } // no default case, so the compiler can warn about missing cases
diff --git a/src/script/script.h b/src/script/script.h
index 2c55e99d8ab8..af1463637c72 100644
--- a/src/script/script.h
+++ b/src/script/script.h
@@ -216,6 +216,9 @@ enum opcodetype
     // Opcode added by BIP348 (Tapscript-only, formerly OP_SUCCESS204)
     OP_CHECKSIGFROMSTACK = 0xcc,
 
+    // Opcode added by BIP349 (Tapscript-only, formerly OP_SUCCESS203)
+    OP_INTERNALKEY = 0xcb,
+
     OP_INVALIDOPCODE = 0xff,
 };
 
diff --git a/test/functional/test_framework/script.py b/test/functional/test_framework/script.py
index 42e5d9ea373b..7a1739e4b40e 100644
--- a/test/functional/test_framework/script.py
+++ b/test/functional/test_framework/script.py
@@ -262,6 +262,9 @@ def __new__(cls, n):
 # BIP348 opcode (Tapscript-only, formerly OP_SUCCESS204)
 OP_CHECKSIGFROMSTACK = CScriptOp(0xcc)
 
+# BIP349 opcode (Tapscript-only, formerly OP_SUCCESS203)
+OP_INTERNALKEY = CScriptOp(0xcb)
+
 OP_INVALIDOPCODE = CScriptOp(0xff)
 
 OPCODE_NAMES.update({
@@ -379,6 +382,7 @@ def __new__(cls, n):
     OP_CHECKSIGADD: 'OP_CHECKSIGADD',
     OP_TEMPLATEHASH: 'OP_TEMPLATEHASH',
     OP_CHECKSIGFROMSTACK: 'OP_CHECKSIGFROMSTACK',
+    OP_INTERNALKEY: 'OP_INTERNALKEY',
     OP_INVALIDOPCODE: 'OP_INVALIDOPCODE',
 })
 
@@ -964,6 +968,6 @@ def taproot_construct(pubkey, scripts=None, treat_internal_as_infinity=False):
     return TaprootInfo(CScript([OP_1, tweaked]), pubkey, negated + 0, tweak, leaves, h, tweaked)
 
 def is_op_success(o, is_temphash_active):
-    if o == OP_TEMPLATEHASH or o == OP_CHECKSIGFROMSTACK:
+    if o == OP_TEMPLATEHASH or o == OP_CHECKSIGFROMSTACK or o == OP_INTERNALKEY:
         return not is_temphash_active
     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 fe3c63f65c47f20f62db4b53d4d8a35b64f90233 Mon Sep 17 00:00:00 2001
From: Gregory Sanders <gsanders87@gmail.com>
Date: Wed, 24 Jun 2026 14:06:46 -0400
Subject: [PATCH 10/12] qa: unit tests for OP_CHECKSIGFROMSTACK and
 OP_INTERNALKEY

---
 src/test/script_tests.cpp | 105 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)

diff --git a/src/test/script_tests.cpp b/src/test/script_tests.cpp
index 4429e54d288e..2f7ba9d29d87 100644
--- a/src/test/script_tests.cpp
+++ b/src/test/script_tests.cpp
@@ -2096,4 +2096,109 @@ BOOST_AUTO_TEST_CASE(templatehash_activation_states)
     BOOST_CHECK_MESSAGE(verify(base | SCRIPT_VERIFY_TEMPLATEHASH, err), ScriptErrorString(err));
 }
 
+/** Build a single-leaf Taproot output, spend it with `leaf` as the tapscript, and return the
+ *  resulting ScriptError (SCRIPT_ERR_OK iff the spend is valid) under the given verify flags. */
+static ScriptError EvalTapscriptLeaf(const CScript& leaf, script_verify_flags flags, const XOnlyPubKey& internal_key = XOnlyPubKey::NUMS_H)
+{
+    TaprootBuilder builder;
+    builder.Add(0, leaf, TAPROOT_LEAF_TAPSCRIPT);
+    builder.Finalize(internal_key);
+    const CScript spk{GetScriptForDestination(builder.GetOutput())};
+
+    CMutableTransaction tx;
+    tx.vin.emplace_back(COutPoint{*Txid::FromHex("0000000000000000000000000000000000000000000000000000000000000001"), 0});
+    tx.vout.emplace_back(1000, CScript() << OP_RETURN);
+    const std::vector<CTxOut> spent_outputs{CTxOut{1000, spk}};
+
+    const auto spend_data{builder.GetSpendData()};
+    const auto& cb{*spend_data.scripts.begin()->second.begin()};
+    tx.vin[0].scriptWitness.stack.emplace_back(leaf.begin(), leaf.end());
+    tx.vin[0].scriptWitness.stack.emplace_back(cb.begin(), cb.end());
+
+    PrecomputedTransactionData precomp;
+    precomp.Init(tx, std::vector<CTxOut>{spent_outputs});
+    const auto checker{GenericTransactionSignatureChecker(&tx, 0, CAmount{1000}, precomp, MissingDataBehavior::ASSERT_FAIL)};
+    ScriptError err{SCRIPT_ERR_OK};
+    VerifyScript(tx.vin[0].scriptSig, spk, &tx.vin[0].scriptWitness, flags, checker, &err);
+    return err;
+}
+
+/** Sanity-check OP_CHECKSIGFROMSTACK (BIP-348). */
+BOOST_AUTO_TEST_CASE(checksigfromstack)
+{
+    const auto check{[](ScriptError got, ScriptError want) { BOOST_CHECK_MESSAGE(got == want, ScriptErrorString(got)); }};
+    const script_verify_flags base{SCRIPT_VERIFY_P2SH | SCRIPT_VERIFY_WITNESS | SCRIPT_VERIFY_TAPROOT};
+    const script_verify_flags active{base | SCRIPT_VERIFY_TEMPLATEHASH};
+
+    // A key, a 32-byte message, and a valid BIP-340 signature over it.
+    const CKey key{GenerateRandomKey()};
+    const XOnlyPubKey xpk{key.GetPubKey()};
+    const std::vector<unsigned char> pubkey{xpk.begin(), xpk.end()};
+    const uint256 msg{uint256::ONE};
+    const std::vector<unsigned char> msg_vec{msg.begin(), msg.end()};
+    std::vector<unsigned char> sig(64);
+    BOOST_REQUIRE(key.SignSchnorr(msg, sig, /*merkle_root=*/nullptr, /*aux=*/uint256{}));
+
+    // Valid signature: CSFS pushes 1.
+    const CScript ok_leaf{CScript() << sig << msg_vec << pubkey << OP_CHECKSIGFROMSTACK};
+    check(EvalTapscriptLeaf(ok_leaf, active), SCRIPT_ERR_OK);
+    // Before activation it is still an OP_SUCCESS (valid), and discouraged as a policy rule.
+    check(EvalTapscriptLeaf(ok_leaf, base), SCRIPT_ERR_OK);
+    check(EvalTapscriptLeaf(ok_leaf, active | SCRIPT_VERIFY_DISCOURAGE_TEMPLATEHASH), SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH);
+
+    // Tampered signature fails.
+    std::vector<unsigned char> bad_sig{sig};
+    bad_sig[10] ^= 0x01;
+    check(EvalTapscriptLeaf(CScript() << bad_sig << msg_vec << pubkey << OP_CHECKSIGFROMSTACK, active), SCRIPT_ERR_SCHNORR_SIG);
+
+    // Wrong (non-empty) signature size fails.
+    check(EvalTapscriptLeaf(CScript() << std::vector<unsigned char>(63, 0) << msg_vec << pubkey << OP_CHECKSIGFROMSTACK, active), SCRIPT_ERR_SCHNORR_SIG_SIZE);
+
+    // Zero-length public key fails.
+    check(EvalTapscriptLeaf(CScript() << sig << msg_vec << std::vector<unsigned char>{} << OP_CHECKSIGFROMSTACK, active), SCRIPT_ERR_TAPSCRIPT_EMPTY_PUBKEY);
+
+    // An unknown (non-32-byte) public key type succeeds without verification...
+    const std::vector<unsigned char> unknown_pk(33, 0x02);
+    check(EvalTapscriptLeaf(CScript() << sig << msg_vec << unknown_pk << OP_CHECKSIGFROMSTACK, active), SCRIPT_ERR_OK);
+    // ...but is discouraged when DISCOURAGE_UPGRADABLE_PUBKEYTYPE is set.
+    check(EvalTapscriptLeaf(CScript() << sig << msg_vec << unknown_pk << OP_CHECKSIGFROMSTACK, active | SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_PUBKEYTYPE), SCRIPT_ERR_DISCOURAGE_UPGRADABLE_PUBKEYTYPE);
+
+    // An empty signature pushes an empty vector (false) and continues: <empty> <msg> <pk> CSFS OP_NOT -> 1.
+    check(EvalTapscriptLeaf(CScript() << std::vector<unsigned char>{} << msg_vec << pubkey << OP_CHECKSIGFROMSTACK << OP_NOT, active), SCRIPT_ERR_OK);
+
+    // Outside Tapscript it is an unknown opcode.
+    std::vector<std::vector<unsigned char>> stack;
+    ScriptError err;
+    BOOST_CHECK(!EvalScript(stack, CScript() << OP_CHECKSIGFROMSTACK, active, BaseSignatureChecker(), SigVersion::BASE, &err));
+    BOOST_CHECK_MESSAGE(err == SCRIPT_ERR_BAD_OPCODE, ScriptErrorString(err));
+}
+
+/** Sanity-check OP_INTERNALKEY (BIP-349). */
+BOOST_AUTO_TEST_CASE(internalkey)
+{
+    const auto check{[](ScriptError got, ScriptError want) { BOOST_CHECK_MESSAGE(got == want, ScriptErrorString(got)); }};
+    const script_verify_flags base{SCRIPT_VERIFY_P2SH | SCRIPT_VERIFY_WITNESS | SCRIPT_VERIFY_TAPROOT};
+    const script_verify_flags active{base | SCRIPT_VERIFY_TEMPLATEHASH};
+
+    // Use a real internal key so OP_INTERNALKEY has a non-trivial value to push.
+    const XOnlyPubKey internal_key{GenerateRandomKey().GetPubKey()};
+    const std::vector<unsigned char> ik_bytes{internal_key.begin(), internal_key.end()};
+
+    // OP_INTERNALKEY pushes the Taproot internal key.
+    const CScript ok_leaf{CScript() << OP_INTERNALKEY << ik_bytes << OP_EQUAL};
+    check(EvalTapscriptLeaf(ok_leaf, active, internal_key), SCRIPT_ERR_OK);
+    // Before activation it is still an OP_SUCCESS (valid), and discouraged as a policy rule.
+    check(EvalTapscriptLeaf(ok_leaf, base, internal_key), SCRIPT_ERR_OK);
+    check(EvalTapscriptLeaf(ok_leaf, active | SCRIPT_VERIFY_DISCOURAGE_TEMPLATEHASH, internal_key), SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH);
+
+    // Comparing against the wrong key fails.
+    check(EvalTapscriptLeaf(CScript() << OP_INTERNALKEY << std::vector<unsigned char>(32, 0) << OP_EQUAL, active, internal_key), SCRIPT_ERR_EVAL_FALSE);
+
+    // Outside Tapscript it is an unknown opcode.
+    std::vector<std::vector<unsigned char>> stack;
+    ScriptError err;
+    BOOST_CHECK(!EvalScript(stack, CScript() << OP_INTERNALKEY, active, BaseSignatureChecker(), SigVersion::WITNESS_V0, &err));
+    BOOST_CHECK_MESSAGE(err == SCRIPT_ERR_BAD_OPCODE, ScriptErrorString(err));
+}
+
 BOOST_AUTO_TEST_SUITE_END()

From adcf744b6554da7c49e3e8f3d84a5a5f3d36b594 Mon Sep 17 00:00:00 2001
From: Gregory Sanders <gsanders87@gmail.com>
Date: Wed, 24 Jun 2026 14:25:36 -0400
Subject: [PATCH 11/12] fuzz: target for OP_CHECKSIGFROMSTACK (BIP-348)

---
 src/test/fuzz/CMakeLists.txt        |   1 +
 src/test/fuzz/checksigfromstack.cpp | 107 ++++++++++++++++++++++++++++
 2 files changed, 108 insertions(+)
 create mode 100644 src/test/fuzz/checksigfromstack.cpp

diff --git a/src/test/fuzz/CMakeLists.txt b/src/test/fuzz/CMakeLists.txt
index 54a18be1f9a4..4e2f89af5e4d 100644
--- a/src/test/fuzz/CMakeLists.txt
+++ b/src/test/fuzz/CMakeLists.txt
@@ -25,6 +25,7 @@ add_executable(fuzz
   buffered_file.cpp
   chain.cpp
   checkqueue.cpp
+  checksigfromstack.cpp
   cluster_linearize.cpp
   cmpctblock.cpp
   coins_view.cpp
diff --git a/src/test/fuzz/checksigfromstack.cpp b/src/test/fuzz/checksigfromstack.cpp
new file mode 100644
index 000000000000..7a469a7470ab
--- /dev/null
+++ b/src/test/fuzz/checksigfromstack.cpp
@@ -0,0 +1,107 @@
+// 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 <key.h>
+#include <policy/policy.h>
+#include <primitives/transaction.h>
+#include <pubkey.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 <uint256.h>
+
+#include <vector>
+
+//! Verification flags with OP_CHECKSIGFROMSTACK (BIP-348) active.
+static constexpr script_verify_flags VERIFY_FLAGS{MANDATORY_SCRIPT_VERIFY_FLAGS | SCRIPT_VERIFY_TEMPLATEHASH};
+
+//! Spend a Taproot output whose only leaf is `<sig> <msg> <pubkey> OP_CHECKSIGFROMSTACK` and return
+//! the resulting ScriptError (SCRIPT_ERR_OK iff the spend is valid).
+static ScriptError EvalCsfsLeaf(const std::vector<unsigned char>& sig, const std::vector<unsigned char>& msg, const std::vector<unsigned char>& pubkey)
+{
+    const CScript leaf{CScript() << sig << msg << pubkey << OP_CHECKSIGFROMSTACK};
+    TaprootBuilder builder;
+    builder.Add(0, leaf, TAPROOT_LEAF_TAPSCRIPT);
+    builder.Finalize(XOnlyPubKey::NUMS_H);
+    const CScript spk{GetScriptForDestination(builder.GetOutput())};
+
+    CMutableTransaction tx;
+    tx.vin.emplace_back(COutPoint{Txid::FromUint256(uint256::ONE), 0});
+    tx.vout.emplace_back(1000, CScript() << OP_RETURN);
+    const std::vector<CTxOut> spent_outputs{CTxOut{1000, spk}};
+
+    const auto spend_data{builder.GetSpendData()};
+    const auto& cb{*spend_data.scripts.begin()->second.begin()};
+    tx.vin[0].scriptWitness.stack.emplace_back(leaf.begin(), leaf.end());
+    tx.vin[0].scriptWitness.stack.emplace_back(cb.begin(), cb.end());
+
+    PrecomputedTransactionData precomp;
+    precomp.Init(tx, std::vector<CTxOut>{spent_outputs});
+    const auto checker{GenericTransactionSignatureChecker(&tx, 0, CAmount{1000}, precomp, MissingDataBehavior::ASSERT_FAIL)};
+    ScriptError err{SCRIPT_ERR_OK};
+    VerifyScript(tx.vin[0].scriptSig, spk, &tx.vin[0].scriptWitness, VERIFY_FLAGS, checker, &err);
+    return err;
+}
+
+static void initialize_checksigfromstack()
+{
+    static ECC_Context ecc_context{};
+}
+
+/** Exercise OP_CHECKSIGFROMSTACK (BIP-348) and assert its consensus-relevant invariants. */
+FUZZ_TARGET(checksigfromstack, .init = initialize_checksigfromstack)
+{
+    FuzzedDataProvider provider(buffer.data(), buffer.size());
+
+    // A signing key derived from fuzzer entropy.
+    auto sk_bytes{provider.ConsumeBytes<unsigned char>(32)};
+    sk_bytes.resize(32);
+    CKey key;
+    key.Set(sk_bytes.begin(), sk_bytes.end(), /*fCompressedIn=*/true);
+    if (!key.IsValid()) return;
+    const XOnlyPubKey xpk{key.GetPubKey()};
+    const std::vector<unsigned char> real_pk{xpk.begin(), xpk.end()};
+
+    // A fuzzer-chosen message and a correct BIP-340 signature over it.
+    const uint256 msg{ConsumeUInt256(provider)};
+    const std::vector<unsigned char> msg_vec{msg.begin(), msg.end()};
+    std::vector<unsigned char> good_sig(64);
+    if (!key.SignSchnorr(msg, good_sig, /*merkle_root=*/nullptr, /*aux=*/uint256{})) return;
+
+    // A correct (sig, msg, pubkey) triple is accepted.
+    Assert(EvalCsfsLeaf(good_sig, msg_vec, real_pk) == SCRIPT_ERR_OK);
+
+    CallOneOf(
+        provider,
+        [&] {
+            // An empty signature pushes false; the bare CSFS leaf then fails the final true check.
+            Assert(EvalCsfsLeaf({}, msg_vec, real_pk) == SCRIPT_ERR_EVAL_FALSE);
+        },
+        [&] {
+            // Any signature other than the correct one makes the spend fail (never validates).
+            const auto other{ConsumeRandomLengthByteVector(provider)};
+            if (other == good_sig) return;
+            Assert(EvalCsfsLeaf(other, msg_vec, real_pk) != SCRIPT_ERR_OK);
+        },
+        [&] {
+            // Verifying the signature against any other message makes the spend fail.
+            const auto other_msg{ConsumeRandomLengthByteVector(provider)};
+            if (other_msg == msg_vec) return;
+            Assert(EvalCsfsLeaf(good_sig, other_msg, real_pk) != SCRIPT_ERR_OK);
+        },
+        [&] {
+            // A zero-length public key fails.
+            Assert(EvalCsfsLeaf(good_sig, msg_vec, {}) == SCRIPT_ERR_TAPSCRIPT_EMPTY_PUBKEY);
+        },
+        [&] {
+            // Arbitrary signature/message/pubkey inputs must never crash.
+            (void)EvalCsfsLeaf(ConsumeRandomLengthByteVector(provider), ConsumeRandomLengthByteVector(provider), ConsumeRandomLengthByteVector(provider));
+        }
+    );
+}

From 0fa7490e30b5c31453b414aea054af933d2a555b Mon Sep 17 00:00:00 2001
From: Gregory Sanders <gsanders87@gmail.com>
Date: Wed, 24 Jun 2026 14:47:43 -0400
Subject: [PATCH 12/12] qa: feature_taproot coverage for OP_CHECKSIGFROMSTACK
 and OP_INTERNALKEY

---
 test/functional/feature_taproot.py | 121 ++++++++++++++++++++++++++++-
 1 file changed, 120 insertions(+), 1 deletion(-)

diff --git a/test/functional/feature_taproot.py b/test/functional/feature_taproot.py
index bacea2656b1a..7b5e790c9c24 100755
--- a/test/functional/feature_taproot.py
+++ b/test/functional/feature_taproot.py
@@ -53,10 +53,12 @@
     OP_16,
     OP_2DROP,
     OP_2DUP,
+    OP_3DUP,
     OP_CHECKMULTISIG,
     OP_CHECKMULTISIGVERIFY,
     OP_CHECKSIG,
     OP_CHECKSIGADD,
+    OP_CHECKSIGFROMSTACK,
     OP_CHECKSIGVERIFY,
     OP_CODESEPARATOR,
     OP_DROP,
@@ -66,6 +68,7 @@
     OP_EQUAL,
     OP_EQUALVERIFY,
     OP_IF,
+    OP_INTERNALKEY,
     OP_NOP,
     OP_NOT,
     OP_NOTIF,
@@ -1121,6 +1124,22 @@ def big_spend_inputs(ctx):
         # n OP_CHECKSIGADDs and 1 OP_CHECKSIG, but also an OP_CHECKSIGADD with an empty signature.
         lambda n, pk: (CScript([OP_DROP, OP_0, OP_10, pk, OP_CHECKSIGADD, OP_10, OP_EQUALVERIFY, pk] + [OP_2DUP, OP_16, OP_SWAP, OP_CHECKSIGADD, b'\x11', OP_EQUALVERIFY] * n + [OP_CHECKSIG]), n + 1),
     ]
+    # OP_CHECKSIGFROMSTACK (BIP-348) verifications count against the tapscript validation-weight
+    # budget, so exercise them in the sigops-ratio test to confirm they cannot be used as a cheap
+    # "sighash bomb". The signature/message are embedded in the leaf (CSFS does not introspect), and
+    # these are only added once active: pre-activation the opcode is an OP_SUCCESS and the ratio
+    # prediction would not hold.
+    if template_active:
+        CSFS_MSG = b'\x00\x00'
+        CSFS_SIG = sign_schnorr(secs[1], CSFS_MSG)
+        SIGOPS_RATIO_SCRIPTS += [
+            # n OP_CHECKSIGFROMSTACKs, each validating the embedded signature (n sigops).
+            lambda n, pk: (CScript([OP_2DROP, CSFS_SIG, CSFS_MSG, pk] + [OP_3DUP, OP_CHECKSIGFROMSTACK, OP_DROP] * n + [OP_2DROP]), n),
+            # 1 OP_CHECKSIGVERIFY then n OP_CHECKSIGFROMSTACKs, all with non-empty signatures (n+1 sigops).
+            lambda n, pk: (CScript([OP_DROP, pk, OP_CHECKSIGVERIFY, CSFS_SIG, CSFS_MSG, pk] + [OP_3DUP, OP_CHECKSIGFROMSTACK, OP_DROP] * n + [OP_2DROP]), n + 1),
+            # 1 empty OP_CHECKSIG and 1 empty OP_CHECKSIGFROMSTACK (neither counts) then n more (n sigops).
+            lambda n, pk: (CScript([OP_2DROP, OP_0, pk, OP_CHECKSIG, OP_DROP, OP_0, CSFS_MSG, pk, OP_CHECKSIGFROMSTACK, OP_DROP, CSFS_SIG, CSFS_MSG, pk] + [OP_3DUP, OP_CHECKSIGFROMSTACK, OP_DROP] * n + [OP_2DROP]), n),
+        ]
     for annex in [None, bytes([ANNEX_TAG]) + random.randbytes(random.randrange(1000))]:
         for hashtype in [SIGHASH_DEFAULT, SIGHASH_ALL]:
             for pubkey in [pubs[1], random.randbytes(random.choice([x for x in range(2, 81) if x != 32]))]:
@@ -1251,7 +1270,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_EVAL_FALSE)
                     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_EVAL_FALSE)
 
-    # Verify that OP_CHECKSIGADD, OP_TEMPLATEHASH weren't accidentally added to pre-taproot validation logic.
+    # Verify that OP_CHECKSIGADD, OP_TEMPLATEHASH, OP_CHECKSIGFROMSTACK and OP_INTERNALKEY 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)]:
@@ -1260,6 +1279,8 @@ def predict_sigops_ratio(n, dummy_size):
 
             # Should still fail if not in executed branch
             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)
+            add_spender(spenders, "compat/nocsfs", p2sh=p2sh, witv0=witv0, standard=p2sh or witv0, script=CScript([OP_IF, OP_CHECKSIGFROMSTACK, OP_ENDIF, OP_1]), inputs=[b''], failure={"inputs": [b'\x01']}, **ERR_BAD_OPCODE)
+            add_spender(spenders, "compat/noik", p2sh=p2sh, witv0=witv0, standard=p2sh or witv0, script=CScript([OP_IF, OP_INTERNALKEY, OP_ENDIF, OP_1]), inputs=[b''], failure={"inputs": [b'\x01']}, **ERR_BAD_OPCODE)
 
     # == sighash caching tests ==
 
@@ -1404,6 +1425,100 @@ def generate_template_spenders_nonstandard():
     return spenders
 
 
+def generate_csfs_spenders_consensus():
+    """Spenders exercising OP_CHECKSIGFROMSTACK (BIP-348) once active."""
+    secs = [generate_privkey() for _ in range(2)]
+    pubs = [compute_xonly_pubkey(sec)[0] for sec in secs]
+
+    # The message and pubkey are embedded in the leaf; the signature comes from the witness.
+    CSFS_MSG = random.randbytes(random.randrange(0, 520))
+    # A message with one byte removed (if non-empty) and one with bytes appended both fail to verify.
+    TRUNC_CSFS_MSG = None
+    if len(CSFS_MSG) > 0:
+        prune_index = random.randrange(len(CSFS_MSG))
+        TRUNC_CSFS_MSG = CSFS_MSG[:prune_index] + CSFS_MSG[prune_index + 1:]
+    extendable = 520 - len(CSFS_MSG)
+    EXTEND_CSFS_MSG = CSFS_MSG + random.randbytes(random.randrange(1, extendable + 1)) if extendable > 0 else None
+    OTHER_CSFS_MSG = CSFS_MSG
+    while OTHER_CSFS_MSG == CSFS_MSG:
+        OTHER_CSFS_MSG = random.randbytes(random.randrange(0, 520))
+    UNK_PUBKEY = random.randbytes(random.randrange(1, 520))
+    while len(UNK_PUBKEY) == 32:
+        UNK_PUBKEY = random.randbytes(random.randrange(1, 520))
+
+    scripts = [
+        ("simple_csfs", CScript([CSFS_MSG, pubs[0], OP_CHECKSIGFROMSTACK, OP_1, OP_EQUAL])),
+        ("simple_fail_csfs", CScript([CSFS_MSG, pubs[0], OP_CHECKSIGFROMSTACK, OP_0, OP_EQUAL])),
+        ("unk_pubkey_csfs", CScript([CSFS_MSG, UNK_PUBKEY, OP_CHECKSIGFROMSTACK])),
+        ("onearg_csfs", CScript([pubs[0], OP_CHECKSIGFROMSTACK])),
+        ("twoargs_csfs", CScript([CSFS_MSG, pubs[0], OP_CHECKSIGFROMSTACK])),
+        ("empty_pk_csfs", CScript([CSFS_MSG, OP_0, OP_CHECKSIGFROMSTACK, OP_0, OP_EQUAL])),
+    ]
+    tap = taproot_construct(pubs[0], scripts)
+    spenders = []
+
+    # "sighash" is the BIP-340 message verified against; getter("sign") signs it with `key`.
+    add_spender(spenders, "csfs/simple", tap=tap, leaf="simple_csfs", key=secs[0], inputs=[getter("sign")], sighash=CSFS_MSG, failure={"sighash": OTHER_CSFS_MSG}, **ERR_SCHNORR_SIG)
+    if TRUNC_CSFS_MSG is not None:
+        add_spender(spenders, "csfs/trunc_msg", tap=tap, leaf="onearg_csfs", key=secs[0], inputs=[getter("sign"), CSFS_MSG], standard=len(CSFS_MSG) <= 80, sighash=CSFS_MSG, failure={"inputs": [getter("sign"), TRUNC_CSFS_MSG]}, **ERR_SCHNORR_SIG)
+    if EXTEND_CSFS_MSG is not None:
+        add_spender(spenders, "csfs/extend_msg", tap=tap, leaf="onearg_csfs", key=secs[0], inputs=[getter("sign"), CSFS_MSG], standard=len(CSFS_MSG) <= 80, sighash=CSFS_MSG, failure={"inputs": [getter("sign"), EXTEND_CSFS_MSG]}, **ERR_SCHNORR_SIG)
+    # Empty signature pushes an empty vector and continues, unless the pubkey is empty.
+    add_spender(spenders, "csfs/empty_sig", tap=tap, leaf="simple_fail_csfs", inputs=[b''], failure={"leaf": "empty_pk_csfs", "inputs": [OTHER_CSFS_MSG]}, **ERR_TAPSCRIPT_EMPTY_PUBKEY)
+    # An unknown (non-32-byte) pubkey is unconditionally valid given a (non-empty) signature.
+    add_spender(spenders, "csfs/unk_pubkey", tap=tap, leaf="unk_pubkey_csfs", standard=False, key=secs[0], inputs=[getter("sign")], sighash=CSFS_MSG, failure={"inputs": []}, **ERR_INVALID_STACK_OPERATION)
+    # CSFS requires three stack elements.
+    add_spender(spenders, "csfs/onearg", tap=tap, leaf="onearg_csfs", key=secs[0], inputs=[getter("sign"), CSFS_MSG], standard=len(CSFS_MSG) <= 80, sighash=CSFS_MSG, failure={"inputs": []}, **ERR_INVALID_STACK_OPERATION)
+    add_spender(spenders, "csfs/twoarg", tap=tap, leaf="twoargs_csfs", key=secs[0], inputs=[getter("sign")], sighash=CSFS_MSG, failure={"inputs": []}, **ERR_INVALID_STACK_OPERATION)
+    # A known-key signature that is neither empty nor 64 bytes must fail.
+    add_spender(spenders, "csfs/65_sig", tap=tap, leaf="simple_csfs", key=secs[0], inputs=[getter("sign")], sighash=CSFS_MSG, failure={"leaf": "simple_fail_csfs", "inputs": [zero_appender(getter("sign"))]}, **ERR_SCHNORR_SIG_SIZE)
+    add_spender(spenders, "csfs/63_sig", tap=tap, leaf="simple_csfs", key=secs[0], inputs=[getter("sign")], sighash=CSFS_MSG, failure={"leaf": "simple_fail_csfs", "inputs": [byte_popper(getter("sign"))]}, **ERR_SCHNORR_SIG_SIZE)
+
+    return spenders
+
+
+def generate_internalkey_spenders_consensus():
+    """Spenders exercising OP_INTERNALKEY (BIP-349) once active."""
+    secs = [generate_privkey() for _ in range(2)]
+    pubs = [compute_xonly_pubkey(sec)[0] for sec in secs]
+    scripts = [("ik", CScript([OP_INTERNALKEY, OP_EQUAL]))]
+    tap = taproot_construct(pubs[0], scripts)
+    spenders = []
+    # OP_INTERNALKEY pushes the internal key (pubs[0]); the witness pushes the value to compare.
+    add_spender(spenders, "ik/success", tap=tap, leaf="ik", inputs=[pubs[0]], failure={"inputs": [pubs[1]]}, **ERR_EVAL_FALSE)
+    return spenders
+
+
+def generate_csfs_spenders_nonstandard():
+    """Spenders testing that pre-activation OP_CHECKSIGFROMSTACK usage is valid but discouraged."""
+    sec = generate_privkey()
+    pub, _ = compute_xonly_pubkey(sec)
+    scripts = [
+        ("stilltrue", CScript([b'', b'', b'', OP_CHECKSIGFROMSTACK])),
+        ("still_opsuccess", CScript([OP_RETURN, OP_CHECKSIGFROMSTACK])),
+    ]
+    tap = taproot_construct(pub, scripts)
+    spenders = []
+    add_spender(spenders, "discouraged_csfs/stilltrue", tap=tap, leaf="stilltrue", standard=False)
+    add_spender(spenders, "discouraged_csfs/still_opsuccess", tap=tap, leaf="still_opsuccess", standard=False)
+    return spenders
+
+
+def generate_internalkey_spenders_nonstandard():
+    """Spenders testing that pre-activation OP_INTERNALKEY usage is valid but discouraged."""
+    sec = generate_privkey()
+    pub, _ = compute_xonly_pubkey(sec)
+    scripts = [
+        ("stilltrue", CScript([OP_INTERNALKEY])),
+        ("still_opsuccess", CScript([OP_RETURN, OP_INTERNALKEY])),
+    ]
+    tap = taproot_construct(pub, scripts)
+    spenders = []
+    add_spender(spenders, "discouraged_ik/stilltrue", tap=tap, leaf="stilltrue", standard=False)
+    add_spender(spenders, "discouraged_ik/still_opsuccess", tap=tap, leaf="still_opsuccess", standard=False)
+    return spenders
+
+
 def spenders_taproot_nonstandard():
     """Spenders for testing that post-activation Taproot rules may be nonstandard."""
 
@@ -1997,6 +2112,8 @@ def run_test(self):
 
                 # Discouragement tests to ensure non-inclusion in mempool before activation
                 discouragement_spenders += generate_template_spenders_nonstandard()
+                discouragement_spenders += generate_csfs_spenders_nonstandard()
+                discouragement_spenders += generate_internalkey_spenders_nonstandard()
 
             else:
                 self.log.info("Activating TEMPLATEHASH softfork")
@@ -2008,6 +2125,8 @@ def run_test(self):
                 # Test coverage for committed hash in outputs is not included here but in
                 # feature_templatehash.py
                 consensus_spenders += generate_template_spenders_consensus()
+                consensus_spenders += generate_csfs_spenders_consensus()
+                consensus_spenders += generate_internalkey_spenders_consensus()
 
             # New sub-tests not checking standardness can be added to consensus_spenders
             # to allow for increased coverage across input types.