rust-lightning

ln/refactor: add blinded forwarding failure helper function

We'll want this extracted when we need to handle trampoline and regular
forwards.

Co-authored-by: Arik Sosman <git@arik.io>
Co-authored-by: Maurice Poirrier <mpch@hey.com>

ln: add trampoline routing payment claiming

Implement payment claiming for `HTLCSource::TrampolineForward` by
iterating through previous hop data and claiming funds for each
HTLC. Similar to regular forwards, we need to block the outbound
channel's RAA on the inbound monitor persisting preimages received.
If we have multiple inbound HTLCs for trampoline, we'll add multiple
blockers so that we don't proceed until each inbound HTLC is claimable.

Co-authored-by: Arik Sosman <git@arik.io>
Co-authored-by: Maurice Poirrier <mpch@hey.com>

ln/refactor: pass closure to create PaymentForwarded event

When we introduce trampoline forwards, we're going to want to provide
two external pieces of information to create events:
- When to emit an event: we only want to emit one trampoline event, even
when we have multiple incoming htlcs. We need to make multiple calls
to claim_funds_from_htlc_forward_hop to claim each individual htlc,
which are not aware of each other, so we rely on the caller's closure
to decide when to emit Some or None.
- Forwarding fees: we will not be able to calculate the total fee for
a trampoline forward when an individual outgoing htlcs is fulfilled,
because there may be other outgoing htlcs that are not accounted for
(we only get the htlc_claim_value_msat for the single htlc that was
just fulfilled). In future, we'll be able to provide the total fee
from the channelmanager's top level view.

ln/refactor: add claim funds for htlc forward helper

Will need to share this code when we add trampoline forwarding. This
commit exactly moves the logic as-is, in preparation for the next
commit that will update to suit trampoline.

Co-authored-by: Arik Sosman <git@arik.io>
Co-authored-by: Maurice Poirrier <mpch@hey.com>

ln: add failure_type helper to HTLCSource for HTLCHandlingFailureType

To create the right handling type based on source, add a helper. This
is mainly useful for PreviousHopData/TrampolineForward. This helper
maps an OutboundRoute to a HTLCHandlingFailureType::Forward. This value
isn't actually used once we reach `forward_htlc_backwards_internal`,
because we don't emit `HTLCHandlingFailed` events for our own payments.
This issue is pre-existing, and could be addressed with an API change
to the failure function, which is left out of scope of this work.

ln: add TrampolineForward variant to HTLCSource enum

We only have payment details for HTLCSource::TrampolineForward available
once we've dispatched the payment. If we get to the stage where we need
a HTLCId for the outbound payment, we expect dispatch details to be
present.

Co-authored-by: Arik Sosman <git@arik.io>
Co-authored-by: Maurice Poirrier <mpch@hey.com>

ln: add TrampolineForward SendHTLCId variant

This commit adds a SendHTLCId for trampoline forwards, identified by
their session_priv. As with an OutboundRoute, we can expect our HTLC
to be uniquely identified by a randomly generated session_priv.

TrampolineForward could also be identified by the set of all previous
outbound scid/htlc id pairs that represent its incoming HTLC(s). We
choose the 32 byte session_priv to fix the size of this identifier
rather than 16 byte scid/id pairs that will grow with the number of
incoming htlcs.

events: add TrampolineForward variant to HTLCHandlingFailureType

ln+events: allow multiple prev_channel_id in HTLCHandlingFailed

In preparation for trampoline failures, allow multiple previous channel
ids. We'll only emit a single HTLCHandlingFailed for all of our failed
back HTLCs, so we want to be able to express all of them in one event.

ln/refactor: rename FreeOtherChannelImmediately to FreeDuplicateClaimImmediately

ln: make channel required in `MonitorUpdateCompletionAction`

`downstream_counterparty_and_funding_outpoint` was added to LDK in
0.0.116. We do not allow direct upgrades with pending forwards to 0.1
from 0.0.123 and below, so we can now assume that this field will
always be present.

This change also makes it impossible to create a
`EmitEventOptionAndFreeOtherChannel` action with nothing in it (no
event or channel), which could have been possible now that we've made
the event optional).

ln/refactor: rename EmitEventAndFreeOtherChannel to note optional event

ln: make event optional in EmitEventAndFreeOtherChannel

In the commits that follow, we want to be able to free the other
channel without emitting an event so that we can emit a single event
for trampoline payments with multiple incoming HTLCs. We still want
to go through the full claim flow for each incoming HTLC (and persist
the EmitEventAndFreeOtherChannel event to be picked up on restart), but
do not want multiple events for the same trampoline forward.

Changing from upgradable_required to upgradable_option is forwards
compatible - old versions of the software will always have written this
field, newer versions don't require it to be there but will be able to
read it as-is.

This change is not backwards compatible, because older versions of the
software will expect the field to be present but newer versions may not
write it. An alternative would be to add a new event type, but that
would need to have an even TLV (because the event must be understood
and processed on restart to claim the incoming HTLC), so that option
isn't backwards compatible either.

ln/events: multiple htlcs in/out for trampoline PaymentForwarded

Small tweaks to CLAUDE.md

Fix spurious `debug_assert` in UTXO gossip dedup check

`check_replace_previous_entry` hit `debug_assert!(false)` when
`channel_announce` was `None` on a still-live `UtxoMessages`. The
comment claimed this was unreachable because `channel_announce` is set
under the same lock as the channel map entry. However, there is a
legitimate race:

1. A channel announcement arrives, an async UTXO lookup starts, and
`pending_channels[scid]` is set with a `Weak` to the
`UtxoMessages`.
2. The lookup resolves. `resolve_single_future` takes both
`channel_announce` and `complete` via `.take()`, but the
`Arc<Mutex<UtxoMessages>>` is still alive on the stack of
`check_resolved_futures`.
3. A duplicate announcement for the same SCID arrives during this
window. `check_replace_previous_entry` upgrades the `Weak`,
finds `channel_announce` is `None`, and hits the assert.

Replace the unconditional `debug_assert!(false)` with a targeted check
that `complete` has also been taken (confirming the future resolved),
which would catch a genuinely unexpected state where
`channel_announce` is `None` but `complete` is still pending.

Co-Authored-By: HAL 9000

Refactor complete_interactive_funding_negotiation_for_both

Use a single get_and_clear_pending_msg_events() + match pattern for the
initiator's turn, matching the existing acceptor code path. Also add
assertions that all expected initiator inputs and outputs were sent.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Contribute to splice as acceptor

When both nodes want to splice simultaneously, the quiescence
tie-breaker designates one as the initiator. Previously, the losing
node responded with zero contribution, requiring a second full splice
session after the first splice locked. This is wasteful, especially for
often-offline nodes that may connect and immediately want to splice.

Instead, the losing node contributes to the winner's splice as the
acceptor, merging both contributions into a single splice transaction.
Since the FundingContribution was originally built with initiator fees
(which include common fields and shared input/output weight), the fee is
adjusted to the acceptor rate before contributing, with the surplus
returned to the change output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Adjust FundingContribution for acceptor

When constructing a FundingContribution, it's always assumed the
estimated_fee is for when used as the initiator, who pays for the common
fields and shared inputs / outputs. However, when the contribution is
used as the acceptor, we'd be overpaying fees.

Additionally, the initiator's chosen fee rate may not be compatible with
the acceptors contributions. The selected UTXOs may not be enough to pay
for a higher feerate (i.e., the change output is not enough to pay or
there is no change output).

This change provides a method on FundingContribution for adjusting the
fee rate with the above concerns in mind. It also updates it to include
a max_feerate specified by the user when initiating a splice. This
ensures the acceptor isn't forced to pay an overly high fee rate.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Include change output weight in estimate_transaction_fee

Add a `change_output: Option<&TxOut>` parameter to
`estimate_transaction_fee` so the initial fee estimate accounts for the
change output's weight. Previously, the change output weight was omitted
from `estimated_fee` in `FundingContribution`, causing the estimate to
be slightly too low when a change output was present.

This also eliminates an unnecessary `Vec<TxOut>` allocation in
`compute_feerate_adjustment`, which previously cloned outputs into a
temporary Vec just to include the change output for the fee estimate.

A mock `TightBudgetWallet` is added to `splicing_tests` to demonstrate
that `validate()` correctly rejects contributions where the input value
is sufficient without the change output weight but insufficient with it.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Stop persisting QuiescentAction and remove legacy code

Now that the Splice variant (containing non-serializable
FundingContribution) is the only variant produced, and the previous
commit consumes the acceptor's quiescent_action in splice_init(),
there is no longer a need to persist it. This allows removing
LegacySplice, SpliceInstructions, ChangeStrategy, and related code
paths including calculate_change_output, calculate_change_output_value,
and the legacy send_splice_init method.

With ChangeStrategy removed, the only remaining path in
calculate_change_output was FromCoinSelection which always returned
Ok(None), making it dead code. The into_interactive_tx_constructor
method is simplified accordingly, and the signer_provider parameter
is removed from it and from splice_init/splice_ack since it was only
needed for the removed change output calculation.

On deserialization, quiescent_action (TLV 65) is still read for
backwards compatibility but discarded, and the awaiting_quiescence
channel state flag is cleared since it cannot be acted upon without
a quiescent_action.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Split InteractiveTxConstructor::new into outbound/inbound variants

Replace the single public InteractiveTxConstructor::new() with separate
new_for_outbound() and new_for_inbound() constructors. This moves the
initiator's first message preparation out of the core constructor,
making it infallible and removing is_initiator from the args struct.

Callers no longer need to handle constructor errors, which avoids having
to generate SpliceFailed/DiscardFunding events after the QuiescentAction
has already been consumed during splice_init/splice_ack handling.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Skip non-key entries in list_paginated

Use dir_entry_is_key in list_paginated_impl to skip .tmp files,
directories, and other non-key entries, to be the same as list_impl.

Claude added a test for this as well.

Clarify CLTV expiry delta for trampolines further

Use the new `total_cltv_expiry_delta()` in place of explicit sum