rust-lightning

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

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>

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>

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

Check that funder covers the fee spike buffer multiple after a splice

We do this for HTLCs, so we should also do this for splices. This
only applies to channels with non-zero-fee HTLC transactions.

Get rid of unnecessary clone when constructing page token

Propagate unexpected metadata errors when preserving mtime in fs_store

Previously, all fs::metadata errors were silently ignored via .ok(),
which could hide permission or I/O errors. Now error are properly
handled.

Move `PeerState` and related types to `peer_state.rs` module

We move the `PeerState` related types to a new module. In the following
commits we'll bit-by-bit drop the `pub(super)`s introduced here,
asserting better separation of state and logic going forward.