rust-lightning

Add `PaymentId` to logging `Record`s

While `PaymentHash`es are great for searching logs, in the case of
BOLT 12 the hash isn't selected until well into the payment
process. Thus, its important that we allow for filtering by
`PaymentId` as well to ensure payment-related logs are always
reliably searchable.

Require `WithContext` log wrappers on `OutboundPayments` calls

In much of LDK we pass around `Logger` objects both to avoid having
to `Clone` `Logger` `Deref`s (soon to only be `Logger`s) and to
allow us to set context with a wrapper such that any log calls on
that wrapper get additional useful metadata in them.

Sadly, when we added a `Logger` type to `OutboundPayments` we broke
the ability to do the second thing - payment information logged
directly or indirectly via logic in the `OutboundPayments` has no
context making log-searching rather challenging.

Here we fix this by retunring to passing loggers explicitly to
`OutboundPayments` methods that need them, specifically requiring
`WithContext` wrappers to ensure the callsite sets appropriate
context on the logger.

Fixes #4307

ln: add function to build trampoline forwarding onions

Use a single `WithContext` wrapper rather than several log-wrappers

In `ChannelMonitor` logging, we often wrap a logger with
`WithChannelMonitor` to automatically include metadata in our
structured logging. That's great, except having too many logger
wrapping types flying around makes for less compatibility if we
have methods that want to require a wrapped-logger.

Here we change the `WithChannelMonitor` "constructors" to actually
return a `WithContext` instead, making things more consistent.

Refactor monitor file listing in tests to filter .tmp files

Extract common logic for listing monitor files into a helper function
that filters out temporary .tmp files created during persistence
operations. This simplifies test code and improves reliability on
systems where directory iteration order is non-deterministic.

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

Add basic `CLAUDE.md` file

We add a basic `CLAUDE.md` file pointing it to some workspace specifics
(in particular running `cargo fmt` on 1.75.0 MSRV, and using
`./ci/ci-tests.sh` to run tests).

Signed-off-by: Elias Rohrer <dev@tnull.de>

Move HTLC interception decisions to `forward_htlcs` callsites

In the next commit we'll substantially expand the types of HTLCs
which can be intercepted. In order to do so, we want to make
forwarding decisions with access to the (specified) destination
channel. Sadly, this isn't available in `forward_htlcs`, so here we
move interception decisions out of `forward_htlcs` and into
`process_pending_update_add_htlcs` and `handle_release_held_htlc`.

Note that we do not handle HTLC interception when forwarding an
HTLC which was decoded in LDK versions prior to 0.2, which is noted
in a suggested release note. This is due to a gap where such HTLC
might have had its routing decision made already and be waiting
for an interception decision in `forward_htlcs`, but now we will
only make an interception decision when decoding the onion.

Expose the outgoing HTLC's CLTV expiry in `Event::HTLCIntercepted`

In the previous commit our interception documentation noted that in
some cases devs may wish to validate the CLTV expiry of HTLCs
before forwarding. Here we enable that by exposing the next-hop's
CLTV value in `Event::HTLCIntercepted`

Support generic HTLC interception

At various points we've had requests to support more generic HTLC
interception in LDK. In most cases, full HTLC interception was not,
in fact, the right way to accomplish what the developer wanted, but
there have been various times when it might have been.

Here, we finally add full HTLC interception support, doing so with
a configurable bitfield to allow developers to intercept only
certain classes of HTLCs.

Specifically, we currently support intercepting HTLCs:
* which were to be forwarded to intercept SCIDs (as was already
supported),
* which were to be forwarded to offline private channels (for LSPs
to accept HTLCs for offline clients so that they can attempt to
wake them before failing the HTLC),
* which were to be forwarded to online private channels (for LSPs
to take additional fees or enforce certain policies),
* which were to be forwarded over public channels (for general
forwarding policy enforcement),
* which were to be forwarded to unknown SCIDs (for everything
else).

Drop lockorder comments on `ChannelManager`

While its nice to document things, the lockorder comment at the top
of `ChannelManager` is just annoying to always update and doesn't
add all that much value. Developers likely shouldn't be checking it
while writing code, our automated lockorder issue detection
framework more than suffices to catch any bugs in test-reachable
code. That makes it basically write-only which isn't exactly a
useful comment.

Move HTLC holding into HTLC decode from `forward_htlcs`

When we added support for async payments (which requires holding
HTLCs until we receive an onion message), we added the hold logic
to `ChannelManager::forward_htlcs`. This made sense as we reused
the forwarding datastructure in the holding logic so already had
the right types in place, but it turns out only a single call of
`forward_htlcs` should ever result in an HTLC being held.

All of the other calls (un-holding an HTLC, forwarding an
intercepted HTLC, forwarding an HTLC decoded by LDK prior to 0.2,
or processing a phantom receive) should never result in an HTLC
being held. Instead, HTLCs should actually only ever be held when
the HTLC is decoded in `process_pending_update_add_htlcs` before
forwarding.

Because of this, and because we want to move the interception (and
thus also the holding logic) out of `forward_htlcs`, here we move
the holding logic into `process_pending_update_add_htlcs`.

Fix the HTLC failure reason reported when a peer is offline

If a peer is offline, but only recently went offline and thus the
channel has not yet been marked disabled in our gossip, we should
be returning `LocalHTLCFailureReason::PeerOffline` rather than
`LocalHTLCFailureReason::ChannelNotReady`. Here we fix the error
returned and tweak documentation to make the cases clearer.

DRY HTLC failure paths in `process_pending_update_add_htlcs`

BOLT 12: Validate bech32 padding per BIP-173

Add validation for bech32 padding in BOLT 12 offer parsing per BIP-173
which states: "Any incomplete group at the end MUST be 4 bits or less,
MUST be all zeroes, and is discarded."

This adds a test vector from the BOLT specification that ensures offers
with invalid padding (exceeding the 4-bit limit) are properly rejected.

Previously, LDK would accept offers with invalid bech32 padding. This
was identified through differential fuzzing across Lightning
implementations (see lightning/bolts#1312).

The fix calls `validate_segwit_padding()` from the bech32 crate during
offer parsing, and introduces a new `InvalidPadding` variant to
`Bolt12ParseError` to surface these errors.

Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>

`ElectrumSyncClient`: Skip unconfirmed `get_history` entries

Electrum's `blockchain.scripthash.get_history` will return the
*confirmed* history for any scripthash, but will then also append any
matching entries from the mempool, with respective `height` fields set
to 0 or -1 (depending on whether all inputs are confirmed or not).

Unfortunately we previously only included a filter for confirmed
`get_history` entries in the watched output case, and forgot to add such
a check also when checking for watched transactions. This would have us
treat the entry as confirmed, then failing on the `get_merkle` step
which of course couldn't prove block inclusion. Here we simply fix this
omission and skip entries that are still unconfirmed (e.g., unconfirmed
funding transactions from 0conf channels).

Signed-off-by: Elias Rohrer <dev@tnull.de>

rustfmt: format priv_short_conf_tests

Set dont_forward on private channel updates and add tests

Drop unnecessary Rust install in SemVer CI

In the last few days there was incompatibility of `cargo-semver-checks`
with the new stable Rust 1.93.0. While this should fixed by today's
release of `cargo-semver-checks`, we take the opportunity to drop an
unnecessary install step from the CI workflow, as the action will bring
their own Rust version if not configured otherwise.

fuzz: add transaction broadcast assertions

Add transaction tracking to TestBroadcaster and verify no unexpected
broadcasts occur during normal fuzzing operation:

- Store all broadcast transactions in TestBroadcaster
- Clear the broadcast set after initial channel opens
- Assert in test_return! that no transactions were broadcast

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

fuzz: track pending and resolved payments

Track payment lifecycle by maintaining pending_payments and
resolved_payments arrays per node:

- When sending a payment, add its PaymentId to pending_payments
- On PaymentSent/PaymentFailed events, move the PaymentId from
pending to resolved (or assert it was already resolved for
duplicate events)

This tracking enables verifying payment state consistency after
node restarts.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Matt Corallo <git@bluematt.me>

fuzz: convert send helpers to closures with node indices

Replace the standalone `send_noret` and `send_hop_noret` functions with
closures defined inside the main loop. This allows them to capture the
`nodes` array and use simple node indices (0, 1, 2) instead of passing
`&nodes[x]` references at each call site.

The `send_payment` and `send_hop_payment` functions are modified to take
pre-computed `PaymentSecret`, `PaymentHash`, and `PaymentId` parameters,
with the closures handling the credential generation. This centralizes
where `PaymentId` is constructed, which will make it easier to add
payment tracking in a future change.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Matt Corallo <git@bluematt.me>

fuzz: simplify get_payment_secret_hash return type

Change `get_payment_secret_hash` to return `(PaymentSecret, PaymentHash)`
directly instead of `Option<...>`.

The function calls `create_inbound_payment_for_hash` with `min_value_msat=None`
and `min_final_cltv_expiry=None`, which cannot fail. Remove the retry loop
and use `.expect()` since the call will always succeed with these parameters.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Matt Corallo <git@bluematt.me>

fuzz: rename chan_id to scid in hop payment functions

Rename `middle_chan_id` to `middle_scid` and `dest_chan_id` to `dest_scid`
in `send_hop_noret` and `send_hop_payment`. These parameters are short
channel IDs (SCIDs), not channel IDs, so the rename improves clarity.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Matt Corallo <git@bluematt.me>

fuzz: consolidate payment counters into single counter

Replace the separate `p_id: u8` (for payment hash generation) and
`p_idx: u64` (for payment IDs) with a single `p_ctr: u64` counter.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Matt Corallo <git@bluematt.me>

Add `total_consistency_lock` check in `handle_post_event_actions`

We expect callers of `handle_post_event_actions` to hold a read
lock on `total_consistency_lock`, and found that we forgot it in
`process_pending_events` until recently. Here we add a relevant
assertion to avoid such issues in the future.