|
| 1 | +``` |
| 2 | + BIP: ? |
| 3 | + Layer: Consensus (soft fork) |
| 4 | + Title: OP_TEMPLATEHASH |
| 5 | + Author: Gregory Sanders <[email protected]> |
| 6 | + Antoine Poinsot <[email protected]> |
| 7 | + |
| 8 | + Comments-Summary: No comments yet. |
| 9 | + Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-? |
| 10 | + Status: Draft |
| 11 | + Type: Standards Track |
| 12 | + Created: ? |
| 13 | + License: CC0-1.0 |
| 14 | +``` |
| 15 | + |
| 16 | +## Abstract |
| 17 | + |
| 18 | +This document proposes a new operation for [Tapscript][tapscript-bip]: `OP_TEMPLATEHASH`. It introduces the ability to |
| 19 | +push on the stack a hash of the transaction spending an output. |
| 20 | + |
| 21 | +## Motivation |
| 22 | + |
| 23 | +`OP_TEMPLATEHASH` can be used to commit to the transaction spending an output[^commit-exact-tx]. This capability |
| 24 | +can replace the use of pre-signed transactions in second-layer protocols. By reducing interactivity it makes such |
| 25 | +protocols simpler, safer, and sometimes notably more efficient. For instance it can remove the need to share HTLC |
| 26 | +signatures in the Lightning Network protocol's [`commitment_signed` message][ln-commit-signed][^ln-second-stage], make |
| 27 | +receiving an Ark "VTXO" [non-interactive][ark-case-ctv], and [reduces roundtrips][symmetric-greg] in the implementation |
| 28 | +of LN-Symmetry. It is also a [significant optimisation][fournier-ctv-dlcs] for [Discreet Log Contracts][optech-dlcs]. |
| 29 | + |
| 30 | +## Specification |
| 31 | + |
| 32 | +`OP_TEMPLATEHASH` redefines `OP_SUCCESS187` (0xbb) in the Tapscript execution context with further restrictions. |
| 33 | + |
| 34 | +Upon execution of the opcode, the template hash of the transaction in context is pushed onto the stack as defined below, |
| 35 | +and script execution continues. |
| 36 | + |
| 37 | +The template hash uses a tagged hash as introduced by [BIP340][schnorr-bip] and [BIP341][taproot-bip]. We use a new tag |
| 38 | +for this purpose: *TemplateHash*. |
| 39 | + |
| 40 | +The template hash re-uses the *sha_sequences*, *sha_outputs* and *sha_annex* pre-computed transaction data introduced in |
| 41 | +BIP341. Numerical values in 4-byte are encoded in little-endian. |
| 42 | + |
| 43 | +The template hash is the *hash<sub>TemplateHash</sub>* of the following transaction fields concatenated: |
| 44 | + |
| 45 | +- Transaction data: |
| 46 | + - *nVersion* (4): the version of the transaction. |
| 47 | + - *nLockTime* (4): the locktime of the transaction. |
| 48 | + - *sha_sequences* (32): the SHA256 of the serialization of all input sequence, as per BIP341. |
| 49 | + - *sha_outputs* (32): the SHA256 of the serialization of all outputs in `CTxOut` format, as per BIP341. |
| 50 | +- Data about this input: |
| 51 | + - *annex_present* (1): as defined in BIP341 (0 if no annex is present, or 1 otherwise). |
| 52 | + - *input_index* (4): index of this input in the transaction input vector. Index of the first input is 0. |
| 53 | + - If an annex is present: |
| 54 | + - *sha_annex* (32): the SHA256 of the annex, as per BIP341. |
| 55 | + |
| 56 | +## Rationale |
| 57 | + |
| 58 | +The template hash follows BIP341's signature message format, with minimal necessary deviations. This reuses a |
| 59 | +tried-and-proven approach to hashed messages, and importantly makes it possible to reuse the pre-computed subfields |
| 60 | +introduced by BIP341 to prevent quadratic hashing. Besides the hash tags, this results in at most 109 bytes being hashed |
| 61 | +upon execution of the operation[^hashed-msg-max-size]. This is strictly less hashing than is necessary for other |
| 62 | +existing operations. |
| 63 | + |
| 64 | +The specific fields from the BIP341 signature message that are ommitted when computing the template hash are the |
| 65 | +following: |
| 66 | +- *hash_type*: this is the sighash type identifier. Only a single hash type is supported by `OP_TEMPLATEHASH`, so there |
| 67 | + is no need to commit to such an identifier. |
| 68 | +- *spend_type*: this value is defined by BIP341 as *2\*ext_flag + annex_present*. Since no extension is appended to the |
| 69 | + signature message, *ext_flag* is set to 0. Therefore we commit directly to *annex_present*. |
| 70 | +- *sha_prevouts* / *sha_scriptpubkeys*: committing to these fields as is would introduce a hash cycle when the hash is |
| 71 | + committed in the output itself. Committing to all other prevouts or scriptpubkeys would introduce hashing a quantity |
| 72 | + of data quadratic in the number of inputs. It would also prevent spending two coins encumbered by a template hash |
| 73 | + check in the same transaction. Finally, the flexibility of not committing to the specific coins spent is also |
| 74 | + desirable to recover from mistakes[^no-commit-other-coins]. |
| 75 | +- *sha_amounts*: the BIP341 rationale for committing to the amounts of all spent coins is to be able to prove to an offline |
| 76 | + signer the fees of a transaction. Although `OP_TEMPLATEHASH` can be used as a building block for rebindable |
| 77 | + signatures, the utility of committing to spent amounts but not spent scriptpubkeys [is |
| 78 | + limited][greg-attack-input-ownership]. Still for rebindable signatures, committing to spent amounts can be justified |
| 79 | + as defense-in-depth against implementation mistakes[^commit-spent-amounts]. However, the lack of flexibility this |
| 80 | + introduces also makes it harder to recover from a mistake in committing to the next |
| 81 | + transaction[^no-commit-other-coins]. Furthermore, committing to all spent amounts also makes overcommitting funds to |
| 82 | + such a script result in the output being forever unspendable instead of the excess just going to fees at spend time. |
| 83 | + |
| 84 | +The design of `OP_TEMPLATEHASH` was inspired by the design of [BIP119][ctv-bip] `OP_CHECKTEMPLATEVERIFY` but differs in |
| 85 | +several important ways. |
| 86 | + |
| 87 | +First of all, `OP_TEMPLATEHASH` is only defined for Tapscript, as modifying legacy Script comes with an unnecessarily |
| 88 | +increased risk surface. In addition, sticking to Tapscript allows leveraging more powerful upgrade hooks (`OP_SUCCESS`s |
| 89 | +instead of `OP_NOP`s) which make it possible to push the template hash on the stack instead of being constrained to |
| 90 | +strict assertions with no stack modification. Pushing the template hash on the stack substantially improves the |
| 91 | +efficiency of using `OP_TEMPLATEHASH` as a building block for rebindable signatures. |
| 92 | + |
| 93 | +Unlike `OP_TEMPLATEHASH`, `OP_CHECKTEMPLATEVERIFY` also commits to the scriptSig of all inputs of the spending |
| 94 | +transaction. `OP_CHECKTEMPLATEVERIFY` gives txid stability when the committed spending transaction has a single input, |
| 95 | +and when the scriptSig of this single input has been committed by the hash. |
| 96 | +Taproot scriptSigs must be empty and therefore under the single input case `OP_TEMPLATEHASH` has no requirement |
| 97 | +to commit to scriptSigs to achieve txid stability. |
| 98 | + |
| 99 | +Finally, BIP119 `OP_CHECKTEMPLATEVERIFY` does not commit to the Taproot annex (or its absence). `OP_TEMPLATEHASH` does. |
| 100 | +Deviating from other operations which do commit to the annex would be unnecessary and surprising. Committing to the |
| 101 | +annex also makes usage of `OP_TEMPLATEHASH` forward compatible with potential future meaning that it could be given. Not |
| 102 | +committing to it would also prevent using `OP_TEMPLATEHASH` in conjunction with annex-based proof of publication |
| 103 | +techniques unless additional signatures are included, as used for instance [in the LN-Symmetry demo][symmetry-annex-publication]. |
| 104 | + |
| 105 | +Programmable transaction introspection capabilities have been proposed as an alternative to a primitive which only |
| 106 | +allows committing to the exact next transaction. It remains to be shown that these more flexible capabilities do |
| 107 | +enable important use cases which justify each proposed change's specific semantics and implementation complexity. It |
| 108 | +has been suggested that the new primitive should have its own upgrade hook from which to softfork in additional |
| 109 | +consensus meaning for more flexible introspection at some future point. We have not done so due to the fact that Taproot |
| 110 | +and Tapscript already presents plentiful upgrade hooks for the future. |
| 111 | + |
| 112 | +## Backward compatibility |
| 113 | + |
| 114 | +This document proposes to give meaning to a Tapscript `OP_SUCCESS` operation. The presence of an `OP_SUCCESS` in a |
| 115 | +Tapscript would previously make it unconditionally succeed. This proposal therefore only tightens the block validation |
| 116 | +rules: there is no block that is valid under the rules proposed in this BIP but not under the existing Bitcoin consensus |
| 117 | +rules. As a consequence these changes are backward-compatible with non-upgraded node software. That said, the authors |
| 118 | +strongly encourage node operators to upgrade in order to fully validate all consensus rules. |
| 119 | + |
| 120 | +## Implementation |
| 121 | + |
| 122 | +* https://github.com/instagibbs/bitcoin/tree/2025-07-op_templatehash |
| 123 | + |
| 124 | +## Test Vectors |
| 125 | + |
| 126 | +For development and testing purposes, we provide a [collection of test vectors](bip-templatehash/test_vectors). The test |
| 127 | +vectors are separated into two JSON files. The [first one](bip-templatehash/test_vectors/basics.json) is a short list of |
| 128 | +simple test cases exercising the various fields of a transaction committed to when using `OP_TEMPLATEHASH`. The [second |
| 129 | +one](bip-templatehash/test_vectors/script_assets_test.json) is a more exhaustive suite of tests exercising `OP_TEMPLATEHASH` |
| 130 | +under a large number of different conditions. It reuses the [Bitcoin Core Taproot test framework][feature_taproot.py] |
| 131 | +introduced with the implementation of BIP341. Format details and usage demonstration are available |
| 132 | +[here](bip-templatehash/test_vectors/README.md). |
| 133 | + |
| 134 | +## Acknowledgements |
| 135 | + |
| 136 | +Credit to Jeremy Rubin for his leadership and perseverance in defending how a simple primitive which |
| 137 | +allows committing to the entire spending transaction is useful for reducing |
| 138 | +interactivity in second layer protocols. This BIP draws on the design of BIP119 and is |
| 139 | +heavily inspired by his exploration of the potential uses for such a primitive. |
| 140 | + |
| 141 | +## Copyright |
| 142 | + |
| 143 | +This document is licensed under the Creative Commons CC0 1.0 Universal license. |
| 144 | + |
| 145 | + |
| 146 | +[^ln-second-stage]: Second-stage HTLC transactions are currently enforced through a 2-of-2 multisig between the channel |
| 147 | +partners. Committing to the HTLC transaction directly in the commitment transaction's HTLC output is a drop-in |
| 148 | +replacement for the multisig, which has the advantage of not requiring Lightning nodes to transmit and store signatures |
| 149 | +for every HTLC at every state it is still active for. |
| 150 | +[^commit-exact-tx]: All the transaction's fields are committed to except the inputs' prevout. This means the output must |
| 151 | +be spent by this exact transaction, although the other spent outputs may vary. |
| 152 | +[^no-commit-other-coins]: It is possible to commit to an underfunded transaction to spend a coin. If the transaction |
| 153 | +commits to more than one input, it is possible to recover from the mistake by creating a separate coin of an appropriate |
| 154 | +value and spending it along with the encumbered coin. Committing to other inputs this transaction must spend or their |
| 155 | +input removes the ability to recover from such a mistake. |
| 156 | +[^commit-spent-amounts]: Adding commitments to the spent amounts may offer extra protection when reusing a public key |
| 157 | +previously associate with a rebindable signature. See [BIP118's rationale][apo-bip-spent-amounts] for more about this. |
| 158 | +[^hashed-msg-max-size]: If no annex is committed, 77 bytes are hashed: 72 bytes of transaction data + 5 bytes of data |
| 159 | +about this input. Committing to an annex adds 32 additional bytes of data about this input, bringing the total to 109. |
| 160 | + |
| 161 | + |
| 162 | +[schnorr-bip]: bip-0340.mediawidi |
| 163 | +[taproot-bip]: bip-0341.mediawidi |
| 164 | +[tapscript-bip]: bip-0342.mediawidi |
| 165 | +[csfs-bip]: bip-0348.md |
| 166 | +[ctv-bip]: bip-0119.md |
| 167 | +[apo-bip-spent-amounts]: https://github.com/bitcoin/bips/blob/master/bip-0118.mediawiki#cite_note-3 |
| 168 | +[ark-case-ctv]: https://delvingbitcoin.org/t/the-ark-case-for-ctv/1528 |
| 169 | +[symmetric-greg]: https://delvingbitcoin.org/t/ln-symmetry-project-recap/359 |
| 170 | +[greg-attack-input-ownership]: https://gnusha.org/pi/bitcoindev/CAB3F3Dv1kuJdu8veNUHa4b58TvWy=BT6zfxdhqEPBQ8rjDfWtA@mail.gmail.com |
| 171 | +[symmetry-annex-publication]: https://github.com/instagibbs/bolts/blob/eltoo_draft/XX-eltoo-transactions.md#update-transaction |
| 172 | +[ln-commit-signed]: https://github.com/lightning/bolts/blob/master/02-peer-protocol.md#committing-updates-so-far-commitment_signed |
| 173 | +[fournier-ctv-dlcs]: https://gnusha.org/pi/bitcoindev/CAH5Bsr2vxL3FWXnJTszMQj83jTVdRvvuVpimEfY7JpFCyP1AZA@mail.gmail.com |
| 174 | +[optech-dlcs]: https://bitcoinops.org/en/topics/discreet-log-contracts |
| 175 | +[feature_taproot.py]: https://github.com/bitcoin/bitcoin/blob/v29.0/test/functional/feature_taproot.py |
0 commit comments