Add OP_TEMPLATEHASH and TH+CSFS+IK bundle BIP

[instagibbs]

Opening this here for wider discussion and feedback.

edit: Probably need to add implementation section: https://github.com/instagibbs/bitcoin/tree/2025-07-op_templatehash

[darosior]

Some previous related discussions:

• "What's a good stopping point? Making the case for the capabilities enabled by CTV+CSFS" - Bitcoin dev mailing list thread discussing the capabilities offered in this proposal.
• "A Taproot-native (re-)bindable transaction bundle proposal" - Bitcoin dev mailing list thread announcing this proposal.
• Reference implementation of this proposal.

[Ademan]

I'm afraid I'm going to write a lot and say very little, but I have a few thoughts maybe worth sharing. TL;DR I like this proposal. As-is I prefer it slightly over CTV, but I think committing to the annex may be undesirable, and it's worth further discussion (as much as I'd like to avoid excessive bikeshedding).

The improvements on CTV are obvious, pushing the hash onto the stack is better, leveraging only cached intermediate hashes is better.

scriptSig Commitment

Dropping the scriptSig commitment seems debatable, but I accept the given rationale for omitting it. Furthermore, CTV's scriptSig commitment introduces a new variable length chunk of data to hash.

The Annex Commitment

The annex commitment is of course the most controversial addition. On the one hand, it is incredibly useful to eltoo style protocols, and TEMPLATEHASH commits to similar items as the taproot sighash, which includes the annex. On the other hand, the annex is the only witness item committed to, and there are plausible conflicts with future annex usage. I have to plead ignorance on the future annex usage issues, I can only say it seems plausible. Furthermore, it could be desirable to commit to only part of the annex, which is not permitted by TEMPLATEHASH, and developing a structured annex format adds a significant development dependency to TEMPLATEHASH.

I can imagine, for example, that CISA might leverage the annex to set the order of public keys in an aggregate key. In this scenario, committing to the entire annex ahead of time would prevent using CISA, though once again I confess I don't know what such a scheme would actually look like.

My instinct here is to reduce the scope of TEMPLATEHASH. When in doubt, leave it out (how can it be wrong if it rhymes?) I could envision a future OP_TEMPLATEHASH_ANNEX if annex commitments proved to be that desirable, but at present it seems to me like the practical motivation for committing to the annex is entirely around eltoo, and there's a non-zero chance it could conflict with other annex usages.

On the other hand, introducing a future OP_TEMPLATEHASH_NO_ANNEX would be similarly simple if the annex commitment proved to be a problem, and OP_TEMPLATEHASH (with annex) would be immediately useful for, and remain useful for eltoo style constructions.

This is why I'm ok with the proposal as-is, if the annex commitment proves to be a mistake, it can still serve a useful purpose now and into the future, and a second opcode could be introduced to address the annex-less case.

Crazy Talk

I'd like to very tentatively float another way to dodge the annex issue: a hash selector bitfield. To this, instagibbs said something like "why not go full TXHASH then?" Unlike TXHASH which has a huge amount of flexibility, a bitfield that permits choosing to commit to all or none of the sequences, all or none of the outputs, and all or none of the annex should not change the stopping point. One could also leverage the other five bits of a 1 byte stack item to potentially commit to the first N<32 outpoints, to support the sibling commitments. This last one in particular changes the performance profile of TEMPLATEHASH by an order of magnitude (though 5 bits is arbitrary, it could be 1, it could be 32) and drastically increases the surface area to consider, but it might be worth considering if it's useful enough to the BitVM crowd. (The sibling commitment might be well past the point of "we should just go full TXHASH" however)

I can say that for me, committing to all of the outputs but none of the input sequences (and therefore not the input count) would be very useful for one of my projects which currently uses a deleted key ALL|ANYONECANPAY signature.

Hashing Performance

Today one can use the script PUSHDATA2 0x0802 <520 bytes> DUP SHA256 DROP to hash 520 bytes, requiring a 526 byte script. Repeating DUP SHA256 DROP can cause a verifier to hash 520 more bytes. You can cause a verifier to hash hashed_bytes(n) = 520 * n bytes for a script of script_len(n) = 523 + 3 * n bytes.

With TEMPLATEHASH as proposed and implemented, one can use the script 1 TEMPLATEHASH DROP to hash 109 bytes. Repeating TEMPLATEHASH DROP can cause a verifier to hash 109 more bytes. Therefore, you can cause a verifier to hash hashed_bytes(n) = 2 * n bytes for a script of script_len(n) = 2 * n bytes.

At exactly n = 80, the SHA256 script will hash 41600 bytes with a 763 byte script. TEMPLATEHASH on the other hand, will hash only 41529 bytes with a 763 byte script, and the SHA256 script's worst case hashing will get considerably worse from there.

Less naively, one can use the script PUSHDATA2 0x0802 <520 bytes> 3DUP SHA256 DROP SHA256 DROP SHA256 DROP to hash 1560 bytes, requiring a 530 byte script. Repeating 3DUP SHA256 DROP SHA256 DROP SHA256 DROP will cause a verifier to hash 1560 more bytes. This works out to hashed_bytes(n) = 1560 * n bytes for a script of length script_len(n) = 523 + 7 * n bytes.

Similarly, the TEMPLATEHASH abusing script can be made more efficient with 1 TEMPLATEHASH TEMPLATEHASH 2DROP to hash 218 bytes. Repeating TEMPLATEHASH TEMPLATEHASH 2DROP can cause a verifier to hash 218 more bytes. Therefore you can cause a verifier to hash hashed_bytes(n) = 218 * n bytes for a script of length script_len(n) = 1 + 3 * n bytes.

The less naive SHA256 script will hash 57720 bytes in 782 script bytes, and the less naive TEMPLATEHASH hashes 56898 bytes in 784 script bytes. Once again, beyond this point, the SHA256 script is worse, therefore at the limit of script size, the SHA256 script will be worse.

I suppose all of that is to say "This is strictly less hashing than is necessary for other existing operations." seems correct, assuming there aren't more clever pathological scripts. Furthermore, the result of TEMPLATEHASH would be trivial to cache, while the result of DUP SHA256 DROP would be more difficult.

[moonsettler]

the TEMPLATEHASH abusing script

Wouldn't the hash naturally be cached in implementation?

[darosior]

Thanks for the feedback @Ademan.

as much as I'd like to avoid excessive bikeshedding

Some amount of bikeshedding is justified for a proposal as consequential as a consensus change. :)

annex commitment

If i understand correctly, your criticism is that while committing to the annex is very useful for the flagship usecase of this proposal, this may clash with potential future usages of the annex. That on its own i don't think is a valid reason not to have the annex commitment, if only because you can make the same argument in the other direction: not committing to the annex would be a design mistake as it allows to be forward-compatible with future usages of the annex, and is already provably useful for some of the main applications enabled by this proposal.

To substantiate your point you bring up that the annex would be the only witness element committed to by TEMPLATEHASH and that it might be useful for CISA. But the annex is different from other witness elements, it was a new field expected to be useful precisely because it is committed to by signatures. In this sense, it's the only witness element committed to by TEMPLATEHASH in the same way it is by CHECKSIG/CHECKSIGADD today. Now, i don't quite understand your point about CISA. You present a scenario where "committing to the entire annex ahead of time would prevent using CISA", but in this case it would also prevent any other opcode that commits to the transaction, like the signature opcodes. If those needs to be re-designed (new pubkey types?) then it seems fine to do TEMPLATEHASH along with it. And until then, i'd much rather the opcodes that commit to a transaction be consistent with each other.

As more of a general point, i think starting from CTV to analyze TEMPLATEHASH is the wrong way to approach this. We should start from what we want to enable and argue the best way to achieve it. If what we want to enable is committing to a transaction, then since Taproot the annex is just another transaction field that should be committed to.

[darosior]

Wouldn't the hash naturally be cached in implementation?

In the Taproot signature hash (which this proposal re-uses), various parts of the transaction are pre-hashed such that the hash can be cached across signatures. For each signature, those pre-computed hashes are hashed together along with some fixed-size transaction fields, such that the maximum amount of data hashed per signature is capped: https://github.com/bitcoin/bips/blob/87f3fe164484f73c30cdb122481bed96a1f79af9/bip-0341.mediawiki#L128

This final hash is pointless to cache, because other opcodes let you hash strictly more arbitrary (i.e. uncachable) data (and even have less restrictions on them).

[instagibbs]

The Annex Commitment

Clearly, I think, this is the most debatable point precisely because there isn't widespread use (or demand yet) for such space.

the practical motivation for committing to the annex is entirely around eltoo

Any scheme that wants to shift from sign-time OP_RETURN to witness data may want to use it in the same manner. It's my fault for making ln-symmetry the go-to during discussion. Granted, this is a fairly minimal improvement, and can be done by many other means with CSFS and friends, or just eating the OP_RETURN cost.

In the end, "Any annex scheme that is compatible with OP_CHECKSIG(ADD) is compatible with OP_TEMPLATEHASH" seems the most straight-forward and least foot-gunny to me.

Crazy Talk

I feel like without a specific proposal, we're going to miss the real costs in terms of complexity.

I'm also worried that if a proposal becomes "general purpose" without actually being general, it won't capture the behavior we actually want, with respect to "programmable money".

(The sibling commitment might be well past the point of "we should just go full TXHASH" however)

No BitVM bridge has launched, and the space is moving very very fast. It's on my docket to try to learn more about the fundamental requirements of these systems to transition from permissioned systems to permissionless for both safety of funds and unilateral exit (these are different concepts IIUC), but I think this is out of scope, and the answer may be "we need GSR / btclisp / Simplicity" and stop trying to guess what specific systems need? I have plenty of controversial thoughts on this but seems way out of scope here, unless we find the next-tx capability and rebindable signatures insufficient motivation for a softfork.

[stevenroose]

My take on the annex is as long as there is no clear potential use for the annex proposed, treating it consistently seems to make the most sense. We treat it exactly like the taproot sighashes are, so that's consistent. Take note that we're only committing the current input's annex, if the annex would be used for something that doesn't work with TEMPLATEHASH, it just means they can't be used together, which seems fine. It would also not be able to be used together with any other sighash-(all/default)-using scheme.

I feel that since new use-cases for the annex will almost certainly come with their own soft fork, they can be resolved when the time comes. You speak about CISA, which I think is a great example, but in my opinion by the time we have a solid CISA soft fork proposal, the TXHASH and TXSIGHASH ideas will hopefully also be more mature and they can solve the annex aspect more elegantly.

This proposal is trying to move the needle for simple next-tx commitment and basic rebindable signatures. Two arguably very simple features that are undeniably useful for almost all second-layer protocols currently being developed and used.

[moonsettler]

If nodes start relaying transactions with non-empty annex the result will predictably a new exogenous asset protocols and a new simpler more efficient ways to inscribe arbitrary data without the need for pre-commitment.

Unleashing the annex is a predictable footgun socially speaking.

[instagibbs]

Unleashing the annex is a predictable footgun socially speaking.

To be clear, this PR / implementation isn't about relaxing these rules for relay.

[moonsettler]

To be clear, this PR / implementation isn't about relaxing these rules for relay.

Yes, this is only relevant further down the line. I think what @Ademan was also picking at is that this proposal feels predictive direction wise.

[Ademan]

@darosior

Thanks for the feedback @Ademan.

Sure! I hope it's productive...

you can make the same argument in the other direction: not committing to the annex would be a design mistake as it allows to be forward-compatible with future usages of the annex,

From my very limited perspective, that seems considerably less likely than the opposite, but that is kind of the problem, this is ~guessing. Maybe it would be useful to at least attempt to identify concrete or partially specified proposals that use the annex. I suppose the onus is on me since I'm the one suggesting they may conflict, but you, instagibbs, steven and moonsettler are all likely closer to the people who might be working on them.

and is already provably useful for some of the main applications enabled by this proposal.

Absolutely! I just want to ensure that "it's useful" isn't overriding compatibility concerns. There are other ways to do data publication, it doesn't necessarily need to be a part of TEMPLATEHASH.

but in this case it would also prevent any other opcode that commits to the transaction, like the signature opcodes.

To be clear, I'm distinguishing between ahead of time commitment (via TEMPLATEHASH or a pre-signed transaction) and signing time commitment. Obviously with CHECKSIG{,VERIFY,ADD} you can typically modify the annex and re-sign at any point before confirmation. This is a significant difference in flexibility. (OTOH, you can also modify the non-witness portions of the TX and re-sign, but I don't accept that as an argument against committing to sequences or outputs... after all that's the whole point here.)

I think I may have been talked out of my position, but I still think it deserves some litigation (perhaps with a better advocate than I).

To give it one last go, I suspect (admittedly without evidence!) that varying annex data independently of the rest of the TX will be the norm and desirable if/when the annex finds uses besides data publication.

i think starting from CTV to analyze TEMPLATEHASH is the wrong way to approach this. We should start from what we want to enable and argue the best way to achieve it.

Fair enough, I definitely agree with the second part.

[moonsettler]

@instagibbs how do you feel about adding OP_SHA256TAGGED to this mix? Even with the "French CTV" it would be a pretty viable LNhance alternative I could support without any misgivings.

[instagibbs]

@instagibbs how do you feel about adding OP_SHA256TAGGED to this mix? Even with the "French CTV" it would be a pretty viable LNhance alternative I could support without any misgivings.

Seems out of scope here, unless I'm missing some key motivation.

[moonsettler]

Seems out of scope here, unless I'm missing some key motivation.

You came up with the motivation yourself afaik (for LN-Symmetry). It's about the whole annex/nulldata/paircommit data availability thing. It is also mildly useful for MATT stuff in a more expressive future script, otherwise it gives us a safe pair-commitment for two stack elements.

Assuming this proposal is activated as-is (as a thought experiment), even if core would be reluctant to, as proven by precedents, it would be a trivial exercise for an LSP to break the annex "filter" using the libre strategy with just a few tens of nodes. Forcing core to "face the reality of the network" and relax policy. Hence our comments on this proposal being predictive of annex use.

I don't want to waste too much time on this topic. But this is exactly why after much agonizing PC was included in LNhance.

[bigspider]

Thanks for writing these specifications. I like the general direction and think that TEMPLATEHASH is cleaner and addresses the undesirable side-effect of CTV of accidentally enabling brother commitments using legacy Script.

One small observation is that the chosen opcode OP_SUCCESS187 (0xbb) is the same as CHECKCONTRACTVERIFY as currently specified in BIP-443, which is of course fine since they are both just proposals at this stage, but a bit of a bummer as I'm planning to make a CCV activation PR to bitcoin-inquisition imminently.

[instagibbs]

@bigspider Our bad, we can switch to another value

edit: trying to find something not colliding :sob:

[moonsettler]

0xcd is PAIRCOMMIT btw which has an implementation and activation client sort of "out there".

  // Tapscript expansion
   OP_INTERNALKEY = 0xcb,
   OP_CHECKSIGFROMSTACK = 0xcc,
   OP_PAIRCOMMIT = 0xcd,

https://github.com/lnhance/bitcoin/commit/91b3036cf5f7366fdb299600f2e6d9f45e70c4aa#diff-93c5ddf703879287802d651b68c9c6199644afe23db0dd3ff77e8d1ce3c20045

[instagibbs]

I’m still a bit confused as to what the bundle document is trying to be

A possible alternative would be to add a Deployment section to the templatehash BIP draft that explicitly links it with bip348/349, like https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#deployment . I'm not sure what the best thing is, but having motivating "glue" text is important. Would be curious as to what others think.

Overall, both documents could perhaps use some more reviewers?

:100:

[darosior]

I think a separate bundle BIP is preferable for at least two reasons:

• Separation of concerns. It's cleaner to give the motivation for a bundled soft fork in its own document, rather than mixing it up with the specifications of one of its opcodes.
• Clearer motivation. I don't think something like OP_TEMPLATEHASH is useful enough on its own to warrant a soft fork. The main motivation for introducing OP_TEMPLATEHASH is because of how it interacts with OP_CHECKSIGFROMSTACK. Rebindable signatures and its possible use cases should be featured as the main motivation for the bundle. It would be awkward to have the weaker OP_TH motivations at the top of the document and then the stronger motivations for the bundle at the end of the document in a Deployment section.

That said, if we can make a reasonably clear document that features both the main motivations of the proposal and the specification of OP_TH, i would be fine with that.

[murchandamus]

It isn’t that they should be combined or that the FISHSTCK proposal is a bad idea. My point is that its type is “Standards Track”, but it lacks a Specification that an implementation could be in compliance with. It therefore appears incomplete.

[darosior]

I didn't mean to imply you suggested that. I was just chiming in as it appeared to have been welcome above. Anyways, what would you recommend here?

[murchandamus]

Not sure, perhaps separate the two documents into different PRs. The Templatehash one is probably close to ready, and the FISHSTCK one would be draft stage and could be moved forward when there is a Specification section that describes activation or smth. Open to other ideas.