script: implement OP_TEMPLATEHASH

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

This operation is introduced as replacing OP_SUCCESS187 (0xbb).

Co-Authored-By: Greg Sanders <[email protected]>

Author: darosior

src/script/interpreter.cpp

@@ -1213,6 +1213,20 @@ bool EvalScript(std::vector<std::vector<unsigned char> >& stack, const CScript&
                 }
                 break;
 
+                case OP_TEMPLATEHASH:
+                {
+                    // OP_TEMPLATEHASH is only available in Tapscript. Note this is the exact same error
+                    // returned in the default case, which would be the one hit by OP_SUCCESS187 before
+                    // the introduction of OP_TEMPLATEHASH.
+                    if (sigversion == SigVersion::BASE || sigversion == SigVersion::WITNESS_V0) {
+                        return set_error(serror, SCRIPT_ERR_BAD_OPCODE);
+                    }
+
+                    const uint256 template_hash{checker.GetTemplateHash(execdata)};
+                    stack.push_back({template_hash.begin(), template_hash.end()});
+                }
+                break;
+
                 default:
                     return set_error(serror, SCRIPT_ERR_BAD_OPCODE);
             }
@@ -1461,6 +1475,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)
 {
@@ -1781,6 +1796,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>;
@@ -1800,6 +1836,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_SUCCESS187) 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);
                 }

src/script/interpreter.h

@@ -271,6 +271,11 @@ class BaseSignatureChecker
          return false;
     }
 
+    virtual uint256 GetTemplateHash(ScriptExecutionData& execdata) const
+    {
+        return {};
+    }
+
     virtual ~BaseSignatureChecker() = default;
 };
 
@@ -307,6 +312,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>;
@@ -338,6 +344,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. */

src/script/script.cpp

@@ -149,6 +149,9 @@ std::string GetOpName(opcodetype opcode)
     // Opcode added by BIP 342 (Tapscript)
     case OP_CHECKSIGADD            : return "OP_CHECKSIGADD";
 
+    // Opcode added by BIP xx (Tapscript-only, formerly OP_SUCCESS187)
+    case OP_TEMPLATEHASH           : return "OP_TEMPLATEHASH";
+
     case OP_INVALIDOPCODE          : return "OP_INVALIDOPCODE";
 
     default:

src/script/script.h

@@ -209,6 +209,9 @@ enum opcodetype
     // Opcode added by BIP 342 (Tapscript)
     OP_CHECKSIGADD = 0xba,
 
+    // Opcode added by BIP xx (Tapscript-only, formerly OP_SUCCESS187)
+    OP_TEMPLATEHASH = 0xbb,
+
     OP_INVALIDOPCODE = 0xff,
 };
 

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:

src/script/script_error.h

@@ -59,6 +59,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,

src/test/script_tests.cpp

@@ -93,6 +93,7 @@ static ScriptErrorDesc script_errors[]={
     {SCRIPT_ERR_WITNESS_PUBKEYTYPE, "WITNESS_PUBKEYTYPE"},
     {SCRIPT_ERR_OP_CODESEPARATOR, "OP_CODESEPARATOR"},
     {SCRIPT_ERR_SIG_FINDANDDELETE, "SIG_FINDANDDELETE"},
+    {SCRIPT_ERR_DISCOURAGE_TEMPLATEHASH, "DISCOURAGE_TEMPLATEHASH"},
 };
 
 static std::string FormatScriptError(ScriptError_t err)

test/functional/feature_taproot.py

@@ -1141,7 +1141,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])),
@@ -1172,7 +1172,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)),

test/functional/test_framework/script.py

@@ -250,6 +250,9 @@ def __new__(cls, n):
 # BIP 342 opcodes (Tapscript)
 OP_CHECKSIGADD = CScriptOp(0xba)
 
+# BIP xx opcode (Tapscript-only, formerly OP_SUCCESS187)
+OP_TEMPLATEHASH = CScriptOp(0xbb)
+
 OP_INVALIDOPCODE = CScriptOp(0xff)
 
 OPCODE_NAMES.update({
@@ -365,6 +368,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',
 })
 
@@ -936,5 +940,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)