Expand `create_blinded_path` Functionality for Enhanced Path Diversification

- Previously, the `create_blinded_path` function was limited to
  returning a single `BlindedPath`, which restricted the usage of
  `blinded_paths`.
- This commit extends the `create_blinded_path` function to return
  the entire blinded path vector generated by the `MessageRouter`'s
  `create_blinded_paths`.
- The updated functionality is integrated across the codebase, enabling
  the sending of Offers Response messages, such as `InvoiceRequest`
  (in `pay_for_offer`) and `Invoice` (in `request_refund_payment`),
  utilizing multiple reply paths.

Merge pull request #3104 from TheBlueMatt/2024-06-routing-counters

Move blinded path introduction point resolution to a helper method

This marginally reduces the size of `get_route` by moving a the
blinded path introduction point resolution and blinded path checks
into a helper method.

Align `PathBuildingHop` to 128b, now that we store them in a `Vec`

Now that `PathBuildingHop` is stored in a `Vec` (as `Option`s),
rather than `HashMap` entries, they can grow to fill a full two
cache lines without a memory access performance cost. In the next
commit we'll take advantage of this somewhat, but here we update
the assertions and drop the `repr(C)`, allowing rust to lay the
memory out as it wishes.

Drop the `dist` `HashMap` in routing, replacing it with a `Vec`.

Now that we have unique, dense, 32-bit identifiers for all the
nodes in our network graph, we can store the per-node information
when routing in a simple `Vec` rather than a `HashMap`. This avoids
the overhead of hashing and table scanning entirely, for a nice
"simple" optimization win.

Use `NodeCounters` `NodeId`s as the blinded path intro references

The router's `introduction_node_id_cache` is used to cache the
`NodeId`s of blinded path introduction points so that we don't
have to look them up every time we go around the main router loop.
When using it, if the introduction point isn't a public node we
then look up the introduction in our first-hops map.

In either case, we have to end up with a reference to a `NodeId`
that outlives our `dist` map.

Here we consolidate both the initial cache building and the
first-hops map lookup to one place, storing only a reference to a
`NodeId` either in the `NetworkGraph` or in the new `NodeCounters`
to get the required lifetime without needing to reference into the
first-hops map.

We then take this opportunity to avoid `clone`ing the first-hops
map entries as we now no longer reference into it.

Drop `private_hop_key_cache` in favor of `NodeCounters`

With the new `NodeCounters` have have a all the `NodeId`s we'll
need during routing, so there's no need to keep the
`private_hop_key_cache` which existed to provide references to
`NodeId`s which are needed during routing.

Add a new `NodeCounters` utility to track counters when routing

In the next commit we'll stop using `NodeId`s to look up nodes when
routing, instead using the new per-node counters. Here we take the
first step, adding a local struct which tracks temporary counters
for route hints/source/destination nodes.

Because we must ensure we have a 1-to-1 mapping from node ids to
`node_counter`s, even across first-hop and last-hop hints, we have
to be careful to check the network graph first, then a new
`private_node_id_to_node_counter` map to ensure we only ever end up
with one counter per node id.

Merge pull request #3085 from shaavan/issue2837

Introduce RecipientData and use it to allow abandon failed payments

Merge pull request #3161 from vincenzopalazzo/macros/fix-docs

meta: update docs to reflect the code

meta: update docs to reflect the code

The code documentation is outdated after the commit 935a716cc6c4fada075e2b740a70bb1b7b349d49

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

Merge pull request #3149 from alecchendev/2024-06-async-sign-cs-raa-order

Fix bug failing CS-RAA resend order on pending commitment signatures

Allow create_blinded_paths functions to accept MessageContext as input field

- Enabled `create_blinded_paths` to accept `MessageContext` TLVs as
  an input field.
- `MessageContext` is intended to be sent along with the `reply_path`
   to the counterparty.
- Added `MessageContext` in the `create_blinded_paths` flow, optionally
  appending it within the `reply_path`.
- Updated tests to verify the new feature.

Update handle_message to accept OffersContext data as an input field

1. Handling Offers Data:
   - Updated `handle_message` to accept `OffersContext` data as an input field.
   - If it is present, it will be utilized by the handler to
     abandon outbound payments that have failed for any reason.

2. Consistency in Custom Message Handling:
   - Updated `handle_custom_message` to accept optional custom data.
     for consistency.
   - Note: `custom_data` will remain unused in this PR.

Fix bug failing CS-RAA resend order on pending commitment signatures

Merge pull request #3120 from TheBlueMatt/2023-11-mon-claim-bug

Block monitor updates to ensure preimages are in each MPP part

Introduce MessageContext in ReceiveTlvs

1. New Enum for Enhanced Data Handling:
   - Introduced the `MessageContext` enum, which allows the node to include
     additional context data along with the `reply_path` sent to the counterparty.
   - The node anticipates receiving this data back for further processing.

2. Variants in MessageContext:
   - The `MessageContext` enum includes two variants: "Offers" and
     "Context"
   - One of the variants, `Offers`, holds the `payment_id`
     of the associated Outbound BOLT12 Payment.

3. Future Usage:
   - This enum will be utilized in a subsequent commit to abandon outbound
     payments that have failed to complete for various reasons.

Remove path_id from Responder, and OnionMessageResponse struct

1. The path_id will be removed from the codebase in the following
   commits.

Test the new `RAAMonitorUpdateBlockingAction::ClaimedMPPPayment`

Block monitor updates to ensure preimages are in each MPP part

If we claim an MPP payment and only persist some of the
`ChannelMonitorUpdate`s which include the preimage prior to
shutting down, we may be in a state where some of our
`ChannelMonitor`s have the preimage for a payment while others do
not.

This, it turns out, is actually mostly safe - on startup
`ChanelManager` will detect there's a payment it has as unclaimed
but there's a corresponding payment preimage in a `ChannelMonitor`
and go claim the other MPP parts. This works so long as the
`ChannelManager` has been persisted after the payment has been
received but prior to the `PaymentClaimable` event being processed
(and the claim itself occurring). This is not always true and
certainly not required on our API, but our
`lightning-background-processor` today does persist prior to event
handling so is generally true subject to some race conditions.

In order to address this we need to use copy payment preimages
across channels irrespective of the `ChannelManager`'s payment
state, but this introduces another wrinkle - if one channel makes
substantial progress while other channel(s) are still waiting to
get the payment preimage in `ChannelMonitor`(s) while the
`ChannelManager` hasn't been persisted after the payment was
received, we may end up without the preimage on disk.

Here, we address this issue by using the new
`RAAMonitorUpdateBlockingAction` variant for this specific case. We
block persistence of an RAA `ChannelMonitorUpdate` which may remove
the preimage from disk until all channels have had the preimage
added to their `ChannelMonitor`.

We do this only in-memory (and not on disk) as we can recreate this
blocker during the startup re-claim logic.

This will enable us to claim MPP parts without using the
`ChannelManager`'s payment state in later work.

Add a `RAAMonitorUpdateBlockingAction::ClaimedMPPPayment`

If we claim an MPP payment and only persist some of the
`ChannelMonitorUpdate`s which include the preimage prior to
shutting down, we may be in a state where some of our
`ChannelMonitor`s have the preimage for a payment while others do
not.

This, it turns out, is actually mostly safe - on startup
`ChanelManager` will detect there's a payment it has as unclaimed
but there's a corresponding payment preimage in a `ChannelMonitor`
and go claim the other MPP parts. This works so long as the
`ChannelManager` has been persisted after the payment has been
received but prior to the `PaymentClaimable` event being processed
(and the claim itself occurring). This is not always true and
certainly not required on our API, but our
`lightning-background-processor` today does persist prior to event
handling so is generally true subject to some race conditions.

In order to address this race we need to use copy payment preimages
across channels irrespective of the `ChannelManager`'s payment
state, but this introduces another wrinkle - if one channel makes
substantial progress while other channel(s) are still waiting to
get the payment preimage in `ChannelMonitor`(s) while the
`ChannelManager` hasn't been persisted after the payment was
received, we may end up without the preimage on disk.

Here, we address this issue with a new
`RAAMonitorUpdateBlockingAction` variant for this specific case. We
block persistence of an RAA `ChannelMonitorUpdate` which may remove
the preimage from disk until all channels have had the preimage
added to their `ChannelMonitor`.

We do this only in-memory (and not on disk) as we can recreate this
blocker during the startup re-claim logic.

This will enable us to claim MPP parts without using the
`ChannelManager`'s payment state in later work.

Track the cp `node_id` which originated an HTLC in the `HTLCSource`

Because we track pending `ChannelMonitorUpdate`s per-peer, we
really need to know what peer an HTLC came from when we go to claim
it on-chain, allowing us to look up any blocked actions in the
`PeerState`. While we could do this by moving the blocked actions
to some global "closed-channel update queue", its simpler to do it
this way.

While this trades off `ChannelMonitorUpdate` size somewhat (the
`HTLCSource` is included in many of them), which we should be
sensitive to, it will also allow us to (eventually) remove the
SCID -> peer + channel_id lookups we do when claiming or failing
today, which are somewhat annoying to deal with.

Add skipping variants to `impl_writeable_tlv_based_enum_upgradable`

In some cases, we have variants of an enum serialized using
`impl_writeable_tlv_based_enum_upgradable` which we don't want to
write/read. Here we add support for such variants by writing them
using the (odd) type 255 without any contents and using
`MaybeReadable` to decline to read them.

Merge pull request #3151 from alecchendev/2024-06-async-test-util-followup

Async signing test util follow ups

Merge pull request #3156 from valentinewallace/2024-07-b12-max-path-len

Set max path length when paying BOLT 12 invoices.

Set max path length when paying BOLT 12 invoices.

Merge pull request #3158 from dunxen/2024-07-excludemergesfrommutants

Skip incremental-mutants job for main

Fix CI for unused `PendingOnionMessage`

Skip incremental-mutants job for main

There is no diff when running against main, so we skip incremental-mutants.
Before this commit, we'd get `Error: Failed to parse diff: Line 1: Error while parsing:`
as the diff file was empty.

Test router: support expecting blinded payment paths.

Remove spurious commented out code line.

Merge pull request #3154 from TheBlueMatt/2024-06-message-flags

Fix spelling in comment

Allow sending RAA upon unblocking the signer

Fix spelling in comment

From @valentinewallace at
https://github.com/lightningdevkit/rust-lightning/pull/3144#discussion_r1661404243

Merge pull request #3144 from TheBlueMatt/2024-06-message-flags

(Re-)add handling for `ChannelUpdate::message_flags`

Use `test_msg_exact` in `channl_update` fuzz testing

Gossip messages should always use `test_msg_exact` to ensure they
round-trip during signature validation.

(Re-)add handling for `ChannelUpdate::message_flags`

When the `htlc_maximum_msat` field was made mandatory in
`ChannelUpdate` (in b0e8b739b73cc25f3e1ab00695a14d972162a140) we
started ignoring the `message_flags` field entirely and always
writing `1`. The comment updates indicated that the `message_flags`
field was deprecated, but this is not true - only the
`htlc_maximum_msat` indicator bit was deprecated, requiring it to
be 1.

If a node creates a `channel_update` with `message_flags` bits set
other than the low bit, this will cause us to spuriously reject
the message with an invalid signature error as we will check the
message against the wrong hash.

With today's current spec this is totally fine - the only other bit
defined for `message_flags` is the `dont_forward` bit, which when
set indicates we shouldn't accept the message into our gossip store
anyway (though this may lead to spurious `warning` messages being
sent to peers). However, in the future this may mean we start
rejecting valid `channel_update`s if new bits are defiend.

Async signing test util follow ups

- Remove unused unavailable signers in TestKeysInterface
- Remove unnecessary display implementation for SignerOp
- Move set of test disabled signer ops to EnforcementState
- Add method to enable/disable all signer ops at once

Merge pull request #2763 from dunxen/2023-11-mutation-testing

Introduce mutation testing

Introduce basic incremental mutation testing

We introduce a CI job for mutation testing of PR diffs using cargo-mutants.
Missed cases do not trigger a fail of this job yet as we just introduce it
now for visibility. We may start enforcing stricter rules at a later stage.

Merge pull request #3129 from optout21/splicing-msgs-update

Update splice messages according to new spec draft

Merge pull request #3147 from TheBlueMatt/2024-06-feerate-overflow

Handle feerates of `u32::MAX` without overflowing

Merge pull request #2989 from optout21/iatx-shared-output

Interactive TX negotiation tracks shared outputs

Handle feerates of `u32::MAX` without overflowing

Though we generally shouldn't be seeing these, and the
`get_dust_buffer_feerate` implementation will still return
`u32::MAX` in spite of the overflow, we should handle the overflow
to avoid panic when `debug_assertions` are enabled.

Found by the `full_stack_target` fuzzer

Merge pull request #3145 from valentinewallace/2024-06-AP-prefactor-followup

Followups to #3125

Implement AsyncPaymentsMessageHandler for ChanMan and use everywhere

Dummy implementation for now. This avoids having to change a bunch of type
signatures in the future when we replace the dummy impl with a real one.

Onion message fuzzer: update held_htlc_available handling

Fuzzers should always do more, not less. Post-merge feedback on
e8f154dd3c299c7988762909df48b0c9d919d6f8.

Merge pull request #3125 from valentinewallace/2024-06-async-payments-prefactor

Async payments message encoding and prefactor

Update splice messages according to new spec draft

Cfg-gate async payments module and public enum variants.

Remove unused imports in static_invoice.rs

Add OffersMessage variant for static invoices.

DRY responder instantiation for onion messages.

AsyncPaymentsMessageHandler trait for OnionMessenger

Add a trait for handling async payments messages to OnionMessenger. This allows
users to either provide their own custom handling for async payments messages
or rely on a version provided by LDK.

Merge pull request #2966 from G8XSU/2647-distribute

Optimize ChannelMonitor persistence on block connections.

Interactive TX negotiation tracks shared outputs

Merge pull request #3127 from wvanlint/non_strict_forwarding

Implement non-strict forwarding

Onion message payload for async payments

Async payments uses onion messages to indicate when HTLCs are held and
released. Add these types along with the necessary parsing and encoding.

Merge pull request #3135 from tnull/2024-06-rustfmt-rgs

Run `rustfmt` on `lightning-rapid-gossip-sync`

`rustfmt`: Drop `benches/src/bench.rs` from excluded files

`rustfmt`: Run on `lightning-rapid-gossip-sync/src/lib.rs`

`rustfmt`: Run on `lightning-rapid-gossip-sync/src/processing.rs`

`rustfmt`: Prepare `lightning-rapid-gossip-sync/src/processing.rs`

Implement non-strict forwarding

This change implements non-strict forwarding, allowing the node to
forward an HTLC along a channel other than the one specified
by short_channel_id in the onion message, so long as the receiver has
the same node public key intended by short_channel_id
([BOLT](https://github.com/lightning/bolts/blob/57ce4b1e05c996fa649f00dc13521f6d496a288f/04-onion-routing.md#non-strict-forwarding)).
This can improve payment reliability when there are multiple channels
with the same peer e.g. when outbound liquidity is replenished by
opening a new channel.

The implemented forwarding strategy now chooses the channel with the
lowest outbound liquidity that can forward an HTLC to maximize the
probability of being able to successfully forward a subsequent HTLC.

Fixes #1278.

Store the source and destination `node_counter`s in `ChannelInfo`

In the next commit, we'll use the new `node_counter`s to remove a
`HashMap` from the router, using a `Vec` to store all our per-node
information. In order to make finding entries in that `Vec` cheap,
here we store the source and destintaion `node_counter`s in
`ChannelInfo`, givind us the counters for both ends of a channel
without doing a second `HashMap` lookup.

Track a `counter` for each node in our network graph

These counters are simply a unique number describing each node.
They have no specific meaning, but start at 0 and count up, with
counters being reused after a node has been deleted.

Merge pull request #3132 from jkczyz/2024-06-bolt12-unannounced

Blinded paths with unannounced introduction nodes

Optimize ChannelMonitor persistence on block connections.

Currently, every block connection triggers the persistence of all
ChannelMonitors with an updated best_block. This approach poses
challenges for large node operators managing thousands of channels.
Furthermore, it leads to a thundering herd problem
(https://en.wikipedia.org/wiki/Thundering_herd_problem), overwhelming
the storage with simultaneous requests.

To address this issue, we now persist ChannelMonitors at a
regular cadence, spreading their persistence across blocks to
mitigate spikes in write operations.

Outcome: After doing this, Ldk's IO footprint should be reduced
by ~50 times. The processing time required to sync each block
will be significantly reduced, particularly for nodes with 1000s
of channels, as write latency plays a significant role in this process.
As a result, the Node/ChainMonitor will be blocked for a shorter
duration, leading to further efficiency gains.

Merge pull request #3126 from TheBlueMatt/2024-06-preimage-removal-blocked-by-claim-event

(Very) marginally expand `test_monitor_update_fail_claim`

(Very) marginally expand `test_monitor_update_fail_claim`

For some reason I wasn't sure this happened yet, so making the
test for no-`PaymentClaimed`-event-before-preimage-on-disk explicit
is nice.

Merge pull request #3115 from alecchendev/2024-06-specific-async-sign

Refactor async signing test utils to toggle specific method availability

Relax channel count check for unannounced nodes

When creating blinded paths, introduction nodes are limited to peers
with at least three channels to prevent easily guessing the recipient.
Relax this check when the recipient is unannounced since they won't be
in the NetworkGraph.

Advance self blinded payment paths

DefaultRouter will ignore blinded paths where the sender is the
introduction node. Similar to message paths, advance such paths by one
so that payments may be sent to them.

Re-order imports

Rename variable

Add advance_path_by_one for blinded payment paths

Similar to blinded paths for onion messages, if given a blinded payment
path where we are the introduction node, the path must be advanced by
one in order to use it.

Don't modify path when advance_path_by_one errors

When using advance_path_by_one when we are the introduction node, any
error will result having the first hop of the input blinded path
removed. Instead, only remove the first hop on success. Otherwise, the
path will be invalid.

Blinded payments to unannounced introduction node

When creating blinded paths for receiving onion payments, allow using
the recipient's only peer as the introduction node when the recipient is
unannounced. This allows for sending payments without going through an
intermediary, which is useful for testing or when only connected to an
LSP with an empty NetworkGraph.

BlindedPath with unannounced introduction node

When creating blinded paths for receiving onion messages, allow using
the recipient's only peer as the introduction node when the recipient is
unannounced. This allows for sending messages without going through an
intermediary, which is useful for testing or when only connected to an
LSP with an empty NetworkGraph.

Merge pull request #3130 from TheBlueMatt/2024-06-doc-fee-present

Document when `Events::PaymentSent::pending_fee_msat` is `Some`

Remove global availability logic for testing async signing

Refactor tests to use specific async signing ops

Allow toggling specific signing methods in test channel signer

Start tracking chain_sync_monitor_persistences in TestPersister

It is helpful to assert that chain-sync did trigger a monitor
persist.

Merge pull request #3128 from TheBlueMatt/2024-06-no-claim-ret

Drop unused return value from `claim_funds_from_hop`

Document when `Events::PaymentSent::pending_fee_msat` is `Some`

Merge pull request #3123 from dunxen/2024-06-channelrefactor

Move accept_channel checks into `ChannelContext::do_accept_channel_checks`

Drop unused return value from `claim_funds_from_hop`

Move accept_channel checks into `ChannelContext::do_accept_channel_checks`

This is done ahead of getting the dual-funding implementation to reduce
refactoring noise there.

ser_macros: support messages with no fields

Merge pull request #3102 from tnull/2024-06-rustfmt-fuzz

`rustfmt`: Reformat the `fuzz` dir

Merge pull request #3098 from arik-so/arik/gossip-v2-parsing

Parse v2 gossip

Merge pull request #3078 from jkczyz/2024-05-invoice-event

Asynchronous `Bolt12Invoice` payment

Update documentation.

Parse v2 gossip.

Add pays_bolt12_invoice_asynchronously test

Expose send_payment_for_bolt12_invoice

UserConfig::manually_handle_bolt12_invoices allows deferring payment of
BOLT12 invoices by generating Event::InvoiceReceived. Expose
ChannelManager::send_payment_for_bolt12_invoice to allow users to pay
the Bolt12Invoice included in the event. While the event contains the
PaymentId for reference, that parameter is now removed from the method
in favor of extracting the PaymentId from the invoice's payer_metadata.

Reformat and tick config docs

Add UserConfig::manually_handle_bolt12_invoices

BOLT12 invoices are automatically paid once they have been verified.
Users may want to manually pay them by first performing additional
checks. Add a manually_handle_bolt12_invoices configuration option that
when set generates an Event::InvoiceReceived instead of paying the
invoice.

Merge pull request #3082 from valentinewallace/2024-04-bolt12-keysend-invoice

BOLT 12 static invoice encoding and building