[2/3] aux revocation: exchange revocation AuxSigs in RevokeAndAck - #11111
Open
GeorgeTsagk wants to merge 8 commits into
Open
[2/3] aux revocation: exchange revocation AuxSigs in RevokeAndAck#11111GeorgeTsagk wants to merge 8 commits into
GeorgeTsagk wants to merge 8 commits into
Conversation
GeorgeTsagk
force-pushed
the
revocation-aux-sigs
branch
from
August 24, 2026 14:56
da59bf0 to
e5bc76a
Compare
GeorgeTsagk
added a commit
to lightninglabs/taproot-assets
that referenced
this pull request
Aug 24, 2026
Points the lnd module and its submodules at the companion series on the GeorgeTsagk/lnd fork: 1. lightningnetwork/lnd#11094, deterministic second-level HTLCs 2. lightningnetwork/lnd#11111, revocation AuxSigs in RevokeAndAck 3. lightningnetwork/lnd#11112, breach-to-confirmation revocation flow The pin is at the tip of part 3, which contains all three. It also adapts the call sites that the new aux interfaces touch. This is temporary and has to be dropped once the lnd series lands.
github-actions
Bot
added
the
severity-critical
🔴 PR Severity: CRITICAL
🔴 Critical (16 files)
🟠 High (1 file)
🟡 Medium (1 file)
🟢 Low (14 files, tests)
AnalysisThis PR modifies core commitment-transaction and HTLC-resolution logic across To override, add a |
Introduce a feature-bit negotiation approach for choosing the sighash type of second-level HTLC transactions, via a new AuxSigner.HtlcSigHashType hook. Add a ResolveHtlcSigHashType helper that queries the aux signer for a channel-specific sighash override based on negotiated features, falling back to the default HtlcSigHashType when no aux signer is present or the feature isn't negotiated. Thread the auxSigner through all HTLC second-level transaction signing and validation call sites. An earlier draft of this feature selected the sighash based on the presence of the commitment's custom blob alone, which is backwards incompatible: a peer that has not upgraded would disagree on the sighash and force close the channel. Explicit feature negotiation ensures both channel parties agree on the sighash type before it is ever used.
When DeterministicHTLCs is negotiated (SigHashDefault second-level HTLCs), the peer's signature commits to the entire transaction, so the sweeper can neither add fee inputs nor RBF the pre-signed tx. Instead of baking a large fixed fee into the transaction, give it a minimal baked-in fee plus a CPFP anchor: - The pre-signed second-level HTLC tx gets a second output: a taproot anchor (AnchorSize sats, keyed to the broadcaster's delay key) that the local party can sweep to CPFP-bump the package fee rate. - The baked-in fee is 1.1x the relay floor over the tx weight (including the anchor output), which is enough for the pre-signed tx to clear min-relay on its own. It deliberately does not track the negotiated commitment fee rate: the whole on-chain BTC value of an aux-channel HTLC is a small fixed budget that already pays this fee, funds the anchor, and must still leave a second-level output that is non-dust AND able to fund the third-level sweep claiming it. At a realistic commitment fee rate the fee alone exceeds that budget, and capping it at what keeps the output non-dust leaves the output unable to pay for its own sweep, stranding the asset value it carries. Adapting to the fee market is the CPFP child's job; where a mempool minimum sits above the parent's own rate, package relay (walletrpc.SubmitPackage) is the answer, since no child can rescue a parent the mempool never accepted. - HtlcIsDust and the second-level fee/output-amount calculations are threaded with the sigHashDefault flag so dust decisions and the HTLC output value account for both the baked-in fee and the AnchorSize reduction. - The sweep sign descriptor for the second-level output is reduced by AnchorSize accordingly, so the sweeper signs for the correct value. Only aux/custom (taproot asset) channels can negotiate SigHashDefault (see ResolveHtlcSigHashType); all other channel types keep their existing fee and transaction form.
…ault When a second-level HTLC transaction was signed with SigHashDefault, the peer's signature commits to the entire transaction: the sweeper's usual flow of rebuilding the tx with extra fee inputs or batched outputs would invalidate it. Add isSigHashDefault() and publishTimeoutTx() / publishSuccessTx() to the timeout and success resolvers, which broadcast each pre-signed transaction directly and individually via PublishTx. The second-level output itself is still swept through the sweeper after confirmation, like today. The gate lives in the shared isSecondLevelSigHashDefault helper and requires the channel type to carry a tapscript root: SigHashDefault is the zero value of SigHashType, so without the explicit channel-type check any channel that never populates SignDetails.SigHashType would false-positively match. Only aux/custom (taproot asset) channels carry a tapscript root, so non-custom channels provably keep using the sweeper flow.
After publishSuccessTx / publishTimeoutTx broadcasts the pre-signed second-level HTLC tx, offer the anchor output at index 1 to the sweeper so the local party can CPFP-bump the parent's effective fee rate. The pre-signed tx itself cannot be RBF'd under SigHashDefault (the peer's signature commits to the full tx), so CPFP via this anchor is the only fee-bumping path. The sweeper handles fee estimation and package math; we hand it the anchor outpoint, a key-path sign descriptor, and the parent tx info needed for package fee-rate calculation: the exact baked-in parent fee (spent commitment output value minus the parent's outputs) and the parent weight. The fee budget for the CPFP child is derived from the value under protection (the second-level HTLC output) via the same sweeper.budget.anchorcpfp(ratio) configuration used for commitment anchor CPFP, plus the anchor value itself. The child is funded from wallet inputs, so the budget can and usually must exceed the anchor's own 330 sats. The sweep deadline is the incoming HTLC's expiry on the timeout path (matching the other timeout-path sweeps) and the HTLC's own expiry on the success path. The sweep result is consumed in a tracked goroutine so terminal failures (budget exhausted, deadline blown, persistent estimation failure) are logged rather than silently dropped. The anchor is keyed to the broadcaster's to-local delay key, which is derived directly from the second-level output's sweep sign descriptor (delay base point + single tweak), keeping this path self-contained. A no-op when the parent tx has fewer than two outputs, i.e. the channel did not use DeterministicHTLCs. The publish itself happens asynchronously via publishPreSignedHtlcTx: a pre-signed timeout tx carries an absolute locktime and is only final once the chain reaches that height, so the broadcast waits on block epochs for the locktime to become satisfiable and retries on every new block until it succeeds. This also heals transient mempool rejections; without it, a "non final" rejection at resolver launch would permanently strand the resolver, since Launch() only runs once. The anchor is offered to the sweeper only after the parent broadcast succeeded, and all background goroutines are tracked by a wait group the resolver's Stop drains.
Raise the upper bound on maxFeeRatio in sanityCheckFee from 1.0 to a hard ceiling of 100.0, so that an RPC caller can opt in to a fee that exceeds the transaction's total output value. The concrete caller is the taproot-assets daemon, which funds PSBTs that anchor asset outputs through walletrpc.FundPsbt with a ratio of 5.0 (see lndservices.DefaultPsbtMaxFeeRatio). Those transactions spend asset-bearing UTXOs whose BTC value sits near dust because the value they carry lives at the asset level, so in a busy fee market the fee legitimately dwarfs the BTC output value and the 1.0 bound would fail the funding outright. Note that this is independent of the deterministic second-level HTLC work in the rest of this series: the CPFP anchor sweep goes through the sweeper (Sweeper.SweepInput with a budget), not through FundPsbt, so nothing in this PR exercises the relaxed bound. It is carried here because the companion taproot-assets series depends on it, and it can be split into its own PR on request. Every internal funding flow keeps passing DefaultMaxFeeRatio, ratios above 1.0 are logged by FundPsbt so the opt-in is auditable, and the new ceiling still rejects nonsensical values.
The RevokeAndAck message gains a CustomRecords field, encoded and decoded with the standard ParseAndExtractCustomRecords/MergeAndEncode helpers. The field is additive and backward-compatible on the wire: peers that send no records produce byte-identical encodings to before this change, and unknown odd records are tolerated on receive. The following commits use this field to carry revocation AuxSigs for aux/custom (taproot asset) channels; a vanilla lnd channel never populates it.
GeorgeTsagk
force-pushed
the
revocation-aux-sigs
branch
from
August 25, 2026 18:26
e5bc76a to
3311774
Compare
GeorgeTsagk
added a commit
to GeorgeTsagk/taproot-assets
that referenced
this pull request
Aug 25, 2026
Points the lnd module and its submodules at the companion series on the GeorgeTsagk/lnd fork: 1. lightningnetwork/lnd#11094, deterministic second-level HTLCs 2. lightningnetwork/lnd#11111, revocation AuxSigs in RevokeAndAck 3. lightningnetwork/lnd#11112, breach-to-confirmation revocation flow The pin is at the tip of part 3, which contains all three. It also adapts the call sites that the new aux interfaces touch. This is temporary and has to be dropped once the lnd series lands.
When an aux/custom (taproot asset) channel with DeterministicHTLCs revokes a commitment, the revoking party now signs second-level HTLC virtual transactions for BOTH spending paths of every non-dust HTLC on the commitment being revoked, and ships the signatures to the peer inside the RevokeAndAck message's custom records. This hands the honest party the asset-level puzzle pieces it needs at breach time: if the cheater later broadcasts the revoked commitment and takes an HTLC to the second level, the breached party holds a valid asset witness for either path the cheater may use. Changes: - Sender: signLocalHtlcAuxSigs derives, for each non-dust HTLC on the revoked commitment, both the primary path (success for incoming, timeout for outgoing) and the alternate path second-level txs, and submits sign jobs to the aux signer. The resulting signatures are packed per HTLC index as a TLV stream (revocationAuxSigType / revocationAuxSigAltType records). One entry is packed per non-dust HTLC even when the signer produces no signature for it (a BTC-only HTLC), in lockstep with the BTC-level signatures. A signing failure fails the revocation as a whole, before any state is advanced: the peer requires the sigs, so a sig-less RevokeAndAck would just fail the channel on their side. - Receiver: ReceiveRevocation verifies every received aux sig against the revoked commitment's key ring BEFORE the revocation is accepted and the tail advances, then injects the sigs into the remote commitment's HTLC custom records so they are persisted in the revocation log for breach-time consumption. Presence is enforced, mirroring the aux sig count check on CommitSig: an entry is required for every non-dust HTLC on the revoked commitment (a peer cannot strip our breach protection by withholding the records), entries for unknown or dust HTLC indexes are rejected, and an entry carrying exactly one spend path is rejected as a withheld signature. - Retransmission: the packed sig blob is persisted in a new optional TLV field on the channel info, written atomically with the commitment advance in UpdateCommitment, and re-attached when the RevokeAndAck is retransmitted on channel reestablish. Only the latest revocation can ever be owed, so a single overwritten slot suffices. - BaseAuxJob gains WhoseCommit, HtlcTimeout and IncomingHTLCLookup fields needed to describe both-path sign jobs to the aux signer. The gate is factored into a single predicate, exchangesRevocationAuxSigs, used by both hooks and (defense in depth) inside the sign and verify functions themselves. It requires an explicit HasTapscriptRoot() on the channel type in addition to the negotiated SigHashDefault, making the custom-channel-only isolation locally auditable at every call site. A vanilla lnd channel never signs, attaches, reads, or verifies these records and its RevokeAndAck is byte-identical to before this change.
Coverage for the revocation AuxSig exchange introduced in the previous commits: - lnwire codec: encode/decode round trips for RevokeAndAck with and without custom records, including a byte-for-byte assertion that the no-records encoding is identical to the legacy wire format. - TLV blob: pack/unpack round trips and corrupt-blob rejection (truncation, garbage). - Custom-channel-only gating: a non-custom taproot channel with an aux signer that pushes SigHashDefault attaches nothing and ignores stray records. - Happy path over a funded tapscript-root channel pair: both-path sigs for every non-dust HTLC, dust excluded, distinct primary/alt blobs matched to the right verify jobs, and the verified sigs persisted into the revocation log entry of the revoked commitment. - BTC-only HTLCs: sig-less lockstep entries are attached and accepted without verification jobs. - Rejection before the remote chain tail advances: unverifiable sigs, malformed blob, missing sig for a non-dust HTLC, withheld blob, extra entry for an unknown HTLC index, entry for a dust HTLC, and a one-sided entry carrying only one spend path. - Sign-time failure: an aux signer error fails RevokeCurrentCommitment before any state advances, for both batch-level and per-job errors. - Retransmission: a retransmitted RevokeAndAck carries the original aux sigs across a simulated restart (persisted blob reloaded from disk).
GeorgeTsagk
force-pushed
the
revocation-aux-sigs
branch
from
August 26, 2026 14:18
3311774 to
4032f41
Compare
GeorgeTsagk
added a commit
to GeorgeTsagk/taproot-assets
that referenced
this pull request
Aug 26, 2026
Points the lnd module and its submodules at the companion series on the GeorgeTsagk/lnd fork: 1. lightningnetwork/lnd#11094, deterministic second-level HTLCs 2. lightningnetwork/lnd#11111, revocation AuxSigs in RevokeAndAck 3. lightningnetwork/lnd#11112, breach-to-confirmation revocation flow The pin is at the tip of part 3, which contains all three. It also adapts the call sites that the new aux interfaces touch. This is temporary and has to be dropped once the lnd series lands.
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
2 participants
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.
This is part 2 of the HTLC revocation series for aux/custom (taproot asset) channels, stacked on #11094. Only the last three commits are new here.
When a custom channel with deterministic HTLCs revokes a commitment, the revoking party signs second-level transactions for both spending paths of every non-dust HTLC on the revoked commitment and ships the signatures in the RevokeAndAck. This hands the honest party the asset-level material it needs at breach time: whichever path a cheater later uses to take an HTLC to the second level, a valid asset witness is already in hand.
Scope:
RevokeAndAckgainsCustomRecords. Additive and backward compatible, a message without records is byte-identical to today (pinned by test).No lnd-native channel can enter these paths, so end-to-end coverage lives in the taproot-assets custom channel itest suite; unit tests here cover the happy path, dust exclusion, all rejection cases, retransmission across a restart, and codec round trips.
Previous PR: #11094
Next PR: #11112