Close last pinning vector using OP_TEMPLATEHASH#2
Open
darosior wants to merge 2 commits into
Open
Conversation
Leverage OP_TEMPLATEHASH to fix the last pinning gap in Lightning, by committing to a v3 spending transaction in the preimage spend path in offered HTLC outputs.
Test vectors for the htlc_success tapscript spend path introduced by
option_htlcs_claim_tx (offered HTLC outputs become P2TR with a two-leaf
tapscript tree, and the htlc_success leaf commits via OP_TEMPLATEHASH to
a fixed v3 claim transaction).
Channel parameters reuse the same keys as zero-fee-commitments-test.json.
Three cases:
1. Single offered HTLC above dust (baseline).
2. Offered HTLC with sub-satoshi millisatoshi truncation — the claim tx
output is 25000 sat for both a 25000000 msat and a 25000821 msat HTLC;
the template hash is identical in both cases (commits to the output
value, not the msat amount).
3. Mixed: one outgoing offered (P2TR) + one incoming received (P2WSH,
unchanged) HTLC.
Each case includes: signed commitment tx, htlc_timeout_script (2-of-2
tapscript), htlc_success_script (preimage check + OP_TEMPLATEHASH),
template_hash, unsigned htlc_claim_tx, and htlc_claim_tx_with_witness
(tapscript spend with the payment preimage).
Generated from the rust-lightning implementation in
lightning/src/ln/channel.rs::htlcs_claim_tx_test_vectors.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
darosior
force-pushed
the
templatehash_pinning
branch
from
6135147 to
57d5430
Compare
This was referenced Jul 1, 2026
darosior
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A single pinning vector remains open in today's Lightning channels following the adoption of TRUC with the
zero_fee_commitmentsupgrade. Unfortunately patching this gap requires introducing more interactivity (and therefore complexity) when updating the channel's state, because it requires committing to a second-stage HTLC transaction also for the preimage spend path paying the remote party in offered HTLC outputs.The added interactivity can be avoided by simply committing to the second-stage HTLC transaction using
OP_TEMPLATEHASHinstead. This PR specifies exactly how this could be achieved, using a minimal approach with an experimental feature bit. A full implementation for LDK is available here, and an integration test for LDK-node demonstrating the feature end-to-end is available here.The purpose of this work is to demonstrate that
OP_TEMPLATEHASHcan realistically reduce interactivity in existing protocols. It is not intended to argue that Lightning should adopt this particular change, as such a decision for a mature protocol involves many tradeoffs.