BOLT 12 variants of PaymentPurpose

In order to provide more context in PaymentClaimable and PaymentClaimed
events, introduce new variants of PaymentPurpose for use with BOLT 12
payments. Separate variants are used for offers and refunds. An unknown
variant is used for backwards compatibility and ease of testing, but is
otherwise not publicly constructable.

Add PaymentPurpose::is_keysend utility method

Rename InvoicePayment to Bolt11InvoicePayment

PaymentPurpose will be expanded to include BOLT 12 payment context.
Rename the InvoicePayment variant accordinly before new variants are
added.

Include Refund context in blinded payment paths

When requesting a payment for a refund, include a context in the
Bolt12Invoice's blinded payment paths indicated it is for such. When the
eventual payment is received, the user can use the payment hash to
correlate it with the corresponding Refund.

Include Offer context in blinded payment paths

When constructing blinded payment paths for a Bolt12Invoice response,
include the OfferId so that the eventual payment can be correlated with
the Offer.

Include OfferId in VerifiedInvoiceRequest

Extract the OfferId from the offer metadata sent back in the
InvoiceRequest and include it in VerifiedInvoiceRequest. This can be
used to correspond the eventual payment for the invoice response by
including it in the invoice's blinded payment paths.

Define an OfferId for BOLT 12 Offers

Use a merkle root hash of the offer TLV records to define an offer id.
Will be included in a BOLT 12 invoice's blinded payment paths in order
for the recipient to identify which offer the payment is for.

Pass PaymentContext through HTLC processing

PendingInboundPayment::BlindedReceive includes a PaymentContext, which
the recipient includes in each blinded path. Included this when
processing HTLCs in ChannelManager, first into PendingHTLCRouting and
then to OnionPayload. Later, this will be included in the PaymentPurpose
when surfaced to user in PaymentClaimable and PaymentClaimed events.

Add PaymentContext to payment::ReceiveTlvs

Providing LDK-specific data in a BlindedPath allows for the data to be
received with the corresponding payment. This is useful as it can then
be surfaced in PaymentClaimable events where the user may correlated
with an Offer, for instance. Define a PaymentContext enum for including
various context (e.g., offer, refund, static invoice).

Return the invoice when requesting a refund

When sending an invoice for a refund, information from the invoice may
be useful for caller. For instance, the payment_hash can be used to
track whether the refund was paid. Return the invoice to facilitate this
use case.

Implement Eq and Hash for Bolt12Invoice

Bolt12Invoice will be added to a new Event::InvoiceGenerated variant.
These traits along with PartialEq are required to be implemented for any
type used in an Event.

Refactor handling of Bolt12Invoice

In order to provide an InvoiceGenerated event, it would be cleaner to
have one location where a Bolt12Invoice is successfully created.
Refactor the handling code to this end and clean-up line length by
making some of the type conversions more streamlined.

Refactor handling of InvoiceRequest

In order to generate and InvoiceSent event, it would be cleaner to have
one location where a Bolt12Invoice is successfully generated. Refactor
the handling code to this end and clean-up line length by making some of
the type conversions more streamlined.

Merge pull request #2961 from jkczyz/2024-03-compact-blinded-paths

Compact blinded path handling

Fix typos

Resolve blinded path when creating onion message

Add a version of the create_onion_message utility function that attempts
to resolved the introduction node of the destination's BlindedPath using
a ReadOnlyNetworkGraph`. Otherwise, if given a path using the compact
representation, using create_onion_message would fail. Keep the current
version for use internally and for external uses where the blinded path
is known to be resolved.

Cache introduction_node_id lookup in get_route

Look up node id from scid in OnionMessenger

When forwarding onion messages, the next node may be represented by a
short channel id instead of a node id. Parameterize OnionMessenger with
a NodeIdLookUp trait to find which node is the next hop. Implement the
trait for ChannelManager for forwarding to channel counterparties.

Also use this trait when advancing a blinded path one hop when the
sender is the introduction node.

Resolve IntroductionNode::DirectedShortChannelId

When OnionMessenger creates an OnionMessage to a Destination, the latter
may contain an IntroductionNode::DirectedShortChannelId inside a
BlindedPath. Resolve these in DefaultMessageRouter and handle unresolved
ones in OnionMessenger.

Generalize BlindedPath::introduction_node_id field

Allow using either a node id or a directed short channel id in blinded
paths. This allows for a more compact representation of blinded paths,
which is advantageous for reducing offer QR code size.

Follow-up commits will implement handling the directed short channel id
case in OnionMessenger as it requires resolving the introduction node in
MessageRouter.

Add source reference to BlindedPathCandidate hop

Blinded paths currently contain a node id for the introduction node.
However, a compact representation will allow a directed short channel id
instead. Update BlindedPathCandidate and OneHopBlindedPathCandidate to
store a NodeId reference from either the NetworkGraph or from the user-
provided first hops.

This approach avoids looking up the introduction node id on demand,
which may not be resolvable. Thus, that would require returning an
Option from CandidateRouteHop::source and handle None accordingly.

Merge pull request #2987 from TheBlueMatt/2024-04-test-ser-bug

Add test coverage for cc78b77c715d6ef62693d4c1bc7190da990ec0fa

Merge pull request #2971 from jbesraa/review-club/2815

Fix comparison in `get_dust_buffer_feerate`

Fix `cmp::max` execution in `ChannelContext::get_dust_buffer_feerate`

  The current `cmp::max` doesnt align with the function comment, ie its
  comparing 2530 and `feerate_plus_quarter` instead of `feerate_per_kw
  + 2530` and `feerate_plus_quarter` which is fixed in this commit

Add BlindedPath::introduction_node_id method

Blinded paths use a pubkey to identify the introduction node, but it
will soon allow using a directed short channel id instead. Add an
introduction_node_id method to BlindedPath to facilitate lookup in the
latter case.

Add IndexedMap::get_key_value

Useful for applying Option::map when needing both the key and value for
when needing a reference to the key with a longer lifetime.

Generalize onion message ForwardTlvs::next_node_id

Allow either using a node id or a short channel id when forwarding an
onion message. This allows for a more compact representation of blinded
paths, which is advantageous for reducing offer QR code size.

Follow-up commits will implement handling the short channel id case as
it requires looking up the destination node id.

Merge pull request #2910 from tnull/2024-02-rustfmt-sign-mod

`rustfmt`:  Format `sign` module

Add test coverage for cc78b77c715d6ef62693d4c1bc7190da990ec0fa

cc78b77c715d6ef62693d4c1bc7190da990ec0fa fixed an important
downgrade bug, but neglected to add test coverage. Here we recitfy
that by adding a few simple tests of common cases.

Tests heavily tweaked by Matt Corallo <git@bluematt.me>.

Remove `no-std-check/src/lib.rs` from `rustfmt` exclusion list

.. now continously checking its formatting in CI.

Remove `msrv-no-dev-deps-check/src/lib.rs` from `rustfmt` exclusion list

.. now continously checking its formatting in CI.

Run `rustfmt` on `msrv-no-dev-deps-check/src/lib.rs`

Remove `sign/type_resolver.rs` from `rustfmt` exclusion list

.. now continously checking its formatting in CI.

Run `rustfmt` on `sign/type_resolver.rs`

Remove `sign/taproot.rs` from `rustfmt` exclusion list

.. now continously checking its formatting in CI.

Run `rustfmt` on `sign/taproot.rs`

Remove `sign/mod.rs` from `rustfmt` exclusion list

.. now continously checking its formatting in CI.

Run `rustfmt` on `sign/mod.rs`

Move `input_idx` retrieval into closure

Move `htlc_basepoint` to variable

Move `hash_to_message` to variable

Move low-R comments into blocks

Pull anchor check into helper function

Remove `sign/ecdsa.rs` from `rustfmt` exclusion list

.. now continously checking its formatting in CI.

Run `rustfmt` on `sing/ecdsa.rs`

Merge pull request #2969 from TheBlueMatt/2024-03-fix-upgradable-enum

Allow `MaybeReadable` to not fully read in `upgradable_option`

Whils this is generally not supported, issues in our
`MaybeReadable` implementations may occur, and we should try to be
robust against them.

Ensure we read the full TLV stream length when maybe-reading `None`

If we are reading an object that is `MaybeReadable` in a TLV stream
using `upgradable_required`, it may return early with `Ok(None)`.
In this case, it will not read any further TLVs from the TLV
stream. This is fine, except that we generally expect
`MaybeReadable` always consume the correct number of bytes for the
full object, even if it doesn't understand it.

This could pose a problem, for example, in cases where we're
reading a TLV-stream `MaybeReadable` object inside another
TLV-stream object. In that case, the `MaybeReadable` object may
return `Ok(None)` and not consume all the available bytes, causing
the outer TLV read to fail as the TLV length does not match.

Fix unknown handling in `impl_writeable_tlv_based_enum_upgradable`

`impl_writeable_tlv_based_enum_upgradable` professed to supporting
upgrades by returning `None` from `MaybeReadable` when unknown
variants written by newer versions of LDK were read. However, it
generally didn't support this as it didn't discard bytes for
unknown types, resulting in corrupt reading.

This is fixed here for enum variants written as a TLV stream,
however we don't have a length prefix for tuple enum variants, so
the documentation on the macro is updated to mention that
downgrades are not supported for tuple variants.

Merge pull request #2704 from jkczyz/2023-11-channelmanager-docs

`ChannelManager` documentation refresh

Add BOLT 12 Refunds section to ChannelManager docs

Add BOLT 12 Offers section to ChannelManager docs

Add a payments section to ChannelManager docs

Add a channels section to ChannelManager docs

Add an operations section to ChannelManager docs

ChannelManager initialization docs with example

Merge pull request #2954 from TheBlueMatt/2024-03-test-ci-beta-fail

Fix new warnings causing CI build failures on rustc beta

Merge pull request #2967 from tnull/2024-03-refactor-drop-handle-message

Split `PeerManager::handle_message` to avoid explicit `mem::drop`

Fix unused warning for un-accessed enum variant field in net-tokio

Remove a handful of redundant imports

... that newer rustc now warns about.

Mark several test_utils which are only used in test as `cfg(test)`

Drop now-unused methods on `Time`

We no longer use `Time` during scoring, which makes several of its
methods now useless. We remove those here.

Use `crate::prelude::*` rather than specific imports

New rustc beta now warns on duplicate imports when one of the
imports is from a wildcard import or the default prelude. Thus, to
avoid this here we prefer to always use `crate::prelude::*` and let
it decide if we actually need to import anything.

Add more `std` prelude items to `crate::prelude`

New rustc beta now warns on duplicate imports when one of the
imports is from a wildcard import or the default prelude. Thus, for
simplicity, we need to make our `crate::prelude` mostly identical
to the `std` one, allowing us to always simply use the
`crate::prelude` and let it decide if we need to import anything.

Allow(unused_imports) on prelude imports

New rustc now warns on duplicate imports when one of the imports
is from a wildcard import or the default prelude. Thus, because we
often don't actually use the imports from our prelude (as they
exist to duplicate the `std` default prelude), we have to mark most
of our `crate::prelude` imports with `#[allow(unused_imports)]`,
which we do here.

Debug more information when we fail to find a lock call symbol

Fix new warnings causing CI build failures on rustc beta

Split `PeerManager::handle_message` to avoid explicit `mem::drop`

Previously, `handle_message` was a single large method consisting of two
logical parts: one modifying the peer state hence requiring us to hold
the `peer_lock` `MutexGuard`, and, after calling `mem::drop(peer_lock)`,
the remainder which does not only *not* require to hold the
`MutexGuard`, but relies on it being dropped to avoid double-locking.

However, the `mem::drop` was easily overlooked, making reasoning about
lock orders etc. a headache. Here, we therefore have
`handle_message` call two sub-methods reflecting the two logical parts,
allowing us to avoid the explicit `mem::drop`, while at the same time
making it less error-prone due to the two methods' signatures.

Merge pull request #2731 from shaavan/issue2711

Delay broadcasting Channel Updates until connected to peers

Delay broadcasting Channel Updates until connected to peers

    - We might generate channel updates to be broadcast when
      we are not connected to any peers to broadcast them to.
    - This PR ensures to cache them and broadcast them only when
      we are connected to some peers.

Other Changes:
    1. Introduce a test.
    2. Update the relevant current tests affected by this change.
    3. Fix a typo.
    4. Introduce two functions in functional_utils that optionally
       connect and disconnect a dummy node during broadcast testing.

Merge pull request #2978 from wpaulino/reserve-async-signing-channel-tlvs

Reserve async signing related channel TLV types

Reserve async signing related channel TLV types

A LDK user deployed to production a WIP version of the async signing
branch in which two new TLVs were added to channel. To prevent them from
needing to perform a migration, we can just new types for TLVs that have
yet to be included in a release. A note has been added to ensure types
45 and 47 are not used for another purpose.

Merge pull request #2975 from valentinewallace/2024-03-blinded-path-custom-tlvs

Merge pull request #2845 from wpaulino/decode-htlc-onion-when-committed

Support decoding HTLC onions once fully committed

Test sending + receiving custom TLVs to blinded paths.

Merge pull request #2974 from benthecarman/dang-value

Add DecodeError::DangerousValue for decoding invalid channel managers

Add DecodeError::DangerousValue for decoding invalid channel managers

This would help distinguish different types of errors when deserialzing
a channel manager. InvalidValue was used previously but this could be
because it is an old serialization format, whereas DangerousValue is a
lot more clear on why the deserialization failed.

Contrast ChannelManager and ChannelMonitor in docs

Re-write ChannelManager summary documentation

Merge pull request #2976 from wvanlint/simplify_trait_object_impl

Simplify implementation for KVStore trait objects

Simplify implementation for KVStore trait objects

The implementation of the Persist and Persister trait for KVStore types
can also be used for trait objects if there is no implicit bound of
`Sized`.

Break ChannelManager docs into sections

ChannelManager docs aren't very approachable as they consist of a large
wall of texts without much direction. As a first step of improvement,
add sections to help delineate the existing text and make it easier to
scan.

Decode update_add_htlc onions before forwarding HTLCs

This commit completes all of the groundwork necessary to decode incoming
`update_add_htlc` onions once they're fully committed to by both sides.
HTLCs are tracked in batches per-channel on the channel they were
received on. While this path is unreachable for now, until
`InboundHTLCResolution::Resolved` is replaced with
`InboundHTLCResolution::Pending`, it will allow us to obtain
`HTLCHandlingFailed` events for _any_ failed HTLC that comes across a
channel.

Refactor forward_htlcs to return whether to push a forward event

When decoding pending `update_add_htlc` onions, we may need to forward
HTLCs using `ChannelManager::forward_htlcs`. This may end up queueing a
`PendingHTLCsForwardable` event, but we're only decoding these pending
onions as a result of handling a `PendingHTLCsForwardable`, so we
shouldn't have to queue another one and wait for it to be handled. By
having a `forward_htlcs` variant that does not push the forward event,
we can ignore the forward event push when forwarding HTLCs which we just
decoded the onion for.

Consider pending decode_update_add_htlcs when pushing forward event

Since decoding pending `update_add_htlc` onions will go through the HTLC
forwarding path, we'll want to make sure we don't queue more events than
necessary if we have both HTLCs to forward/fail and pending
`update_add_htlc` onions to decode.

Refactor incoming HTLC accept checks out from Channel::update_add_htlc

In the future, we plan to completely remove
`decode_update_add_htlc_onion` and replace it with a batched variant.
This refactor, while improving readability in its current form, does not
feature any functional changes and allows us to reuse the incoming HTLC
acceptance checks in the batched variant.

Only include channel_update in failure if needed by error code

This simplifies the failure path by allowing us to return the general
error code for a failure, which we can then amend based on whether it
was for a phantom forward.

Refactor outgoing channel lookup out from decode_update_add_htlc_onion

In the future, we plan to complete remove `decode_update_add_htlc_onion`
and replace it with a batched variant. This refactor, while improving
readability in its current form, does not feature any functional changes
and allows us to reuse most of the logic in the batched variant.

Refactor outgoing HTLC checks out from decode_update_add_htlc_onion

In the future, we plan to complete remove `decode_update_add_htlc_onion`
and replace it with a batched variant. This refactor, while improving
readability in its current form, does not feature any functional changes
and allows us to reuse most of the logic in the batched variant.

Refactor HTLCFailureMsg generation out from decode_update_add_htlc_onion

In the future, we plan to complete remove `decode_update_add_htlc_onion`
and replace it with a batched variant. This refactor, while improving
readability in its current form, does not feature any functional changes
and allows us to reuse most of the logic in the batched variant.

Add is_intro_node_blinded_forward helper for onion_utils::Hop

Add new HTLCDestination variant for invalid onion

The existing variants do not cover such case as we previously never
surfaced `HTLCHandlingFailed` events for HTLCs that we failed back with
`UpdateFailMalformedHTLC` due to an invalid onion packet.

Track pending update_add_htlcs in ChannelManager for later processing

We plan to decode the onions of these `update_add_htlc`s as part of the
HTLC forwarding flow (i.e., `process_pending_htlc_forwards`), so we'll
need to track them per-channel at the `ChannelManager` level.

Remove unreachable handling of htlc_forwards upon channel_reestablish

`htlc_forwards` only returns a `Some` value from
`handle_channel_resumption` if we provide it a non-empty
`pending_forwards`. Since we don't, we'll never have a value to handle.

Track incoming UpdateAddHTLC until HTLC resolution

This commit serves as a stepping stone to moving towards resolving HTLCs
once the HTLC has been fully committed to by both sides.

Currently, we decode HTLC onions immediately upon receiving an
`update_add_htlc`. Doing so determines what we should do with the HTLC:
forward it, or immediately fail it back if it cannot be accepted. This
action is tracked until the HTLC is fully committed to by both sides,
and a new commitment in the latter case is proposed to fully remove the
HTLC. While this has worked so far, it has some minor privacy
implications, as forwarding/failing back do not go through the usual
`PendingHTLCsForwardable` flow. It also presents issues with the
quiescence handshake, as failures through this path do not go through
the holding cell abstraction, leading to a potential violation of the
handshake by sending an `update_fail_*` after already having sent
`stfu`.

Since `pending_inbound_htlcs` are written pre-TLVs, we introduce a new
serialization version in which we change the `PendingHTLCStatus`
serialization of
`InboundHTLC::AwaitingRemoteRevokeToRemove/AwaitingRemovedRemoteRevoke`
to be an option instead. We'll still write it as the current version
(`MIN_SERIALIZATION_VERSION`), but we'll support reading the new version
to allow users to downgrade back to this commit.

Support Vec serialization that include element length prefix

We add new macro alternatives to
impl_writeable_for_vec/impl_readable_for_vec that add a length prefix to
each element in the `Vec`. This is intended to be used over the existing
macros when attempting to serialize a `Vec` with elements of variable
lengths.

Don't consume readers with FixedLengthReader

We can't always assume that we're done reading after using a
FixedLengthReader. In some cases, we may need to read a set of
length-prefixed objects one at a time, and we'd like to do so without
incurring an additional allocation by reading a number of bytes first to
then deserialize them.

Support receiving custom TLVs to blinded paths.

Support sending custom TLVs to blinded recipients.

Merge pull request #2906 from arik-so/arik/trampoline/2024-02-trampoline-onion-construction-vectors

Trampoline onion construction vectors