Log when a ChannelMonitor's claimable balances set goes empty

Correct `ChannelMonitor::is_fully_resolved` docs

The block count at which the monitor will become prunable was
changed by an update while the PR was pending but not propagated
to the docs.

Merge pull request #2964 from jbesraa/prune-stale-chanmonitor

Add `archive_fully_resolved_monitors` to `ChainMonitor`

Merge pull request #2998 from tnull/2024-04-fix-potential-lock-race-in-CM-write

Merge pull request #3001 from optout21/splicing-feature-bit-with-any

Add splicing feature flag

Merge pull request #2999 from keyuebao/keyue/update-ldk-docs

Update docs for ChannelClosed Event

Add `ChainMonitor::archive_fully_resolved_monitor_channels`

  Archives fully resolved channel monitors by adding them to a backup
  location and removing them from the primary storage & the monitor set.

  This is useful for pruning fully resolved monitors from the monitor
  set and primary storage so they are not reloaded on every new new
  block connection.

  We also add a new function, `archive_persisted_channel` to the
  `Persist` trait that writes the monitor to an archive storage and
  removes it from the primary storage.

Add `ChannelMonitor::is_fully_resolved` function

  Checks if the monitor is fully resolved. Resolved monitor is one that has claimed all of
  its ouputs and balacnes.

  This function returns true only if `get_claimable_balances` has been empty for at least
  2016 blocks.

Merge pull request #2825 from tnull/2024-01-upstream-output-sweeper

Add `OutputSweeper` utility persisting and sweeping spendable outputs

Merge pull request #2970 from jkczyz/2024-03-offer-id

Include a `PaymentContext` in `PaymentPurpose`

Edit `Event::SpendableOutputs` docs to mention `OutputSweeper`

Add basic `OutputSweeper` test in BP

.. we simply check that the `OutputSweeper` generates a spending tx and
that the `TrackedSpendableOutput` is pruned once it reaches
`ANTI_REORG_DELAY`.

Allow delaying generation and broadcasting of spending txs

.. which enables users to batch output spends.

Add `OutputSweeper` utility persisting and sweeping spendable outputs

We add a `OutputSweeper` utility that allows to track the state of
spendable output descriptors as emitted by `Event::SpendableOutputs`.

To this end, the `OutputSweeper` persists the necessary information in
our `KVStore` and regularly tries to sweep the spendable outputs,
removing them after reaching threshold confirmations, i.e.,
`ANTI_REORG_DELAY`.

Add `ConfirmationTarget::OutputSpendingFee`

Update PaymentPurpose's payment_preimage docs

Clarify that payment_preimage should only be used to claim a payment
when handling Event::PaymentClaimable, not Event::PaymentClaimed.

Include InvoiceRequest fields in PaymentContext

When receiving a payment, it's useful to know information about the
InvoiceRequest. Include this data in PaymentContext::Bolt12Offer so
users can display information about an inbound payment (e.g., the payer
note).

Test for PaymentContext in offers_tests.rs

Use BOLT 12 PaymentPurpose variants

When constructing a PaymentPurpose in ChannelManager, use the
PaymentContext from OnionPayload to determine which variant to
construct, including those for BOLT 12 payments.

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.

Introduce `ChangeDestinationSource` trait

.. which users should implement on their on-chain wallet to allow us to
retrieve a new change destination script.

Introduce `OutputSpender` trait and implement for `(Phantom)KeysManager`

.. we move `spend_spendable_outputs` to a new trait which we can easily
reuse in `OutputSweeper` later.

Add splicing feature flag (also triggers dual_funding)

Update docs for ChannelClosed Event

Acquire `per_peer_state` `write` lock earlier in `ChannelManager::write`

Previously, we would hold the `per_peer_state` `read` lock during the
serialization of channel objects. While this might have reduced lock
congestion minimally, we also calculated the number of serializable
peers in this phase, only to use it later after dropping and reacquiring
the `per_peer_state` `write` lock.

This could potentially result in inconsistiencies if the
`serializable_peer_count` would change after we dropped the `read` lock
but before we acquired the `write` lock.

To mitigate the issue we just acquire the `write` lock ealier and hold
it for the remainder of `ChannelManager::write`.

Merge pull request #2991 from optout21/txsigs-splicing

Add tx_signatures.tlvs field (splicing-specific field in dual funding message)

Add tx_signatures.tlvs field (splicing-specific field in dual funding message)

Merge pull request #2993 from wpaulino/handshake-complete-timer-tick-occurred-race

Fix race between handshake_complete and timer_tick_occurred

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

Fix race between handshake_complete and timer_tick_occurred

The initial noise handshake on connection establishment must complete
within a single timer tick. This timeout is enforced via
`awaiting_pong_timer_tick_intervals` whenever a timer tick fires while
our handshake has yet to complete. Currently, on an inbound connection,
if a timer tick fires after we've sent act two of the noise handshake
along with our init message and before receiving the counterparty's init
message, we begin enforcing such timeout. Even if we immediately
continue to process the counterparty's init message to complete to
handshake, the timeout enforcement is not cleared. With the handshake
complete, `awaiting_pong_timer_tick_intervals` is now tracked to enforce
a pong timeout, except a ping was never actually sent. If a single timer
tick fires again without having received a message from the peer, or
enough timer ticks fire to trigger the
`MAX_BUFFER_DRAIN_TICK_INTERVALS_PER_PEER` logic, we'll end up
disconnecting the peer due to a timeout for a pong we'll never receive.

We fix this by always resetting `awaiting_pong_timer_tick_intervals`
upon processing our counterparty's init message.

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.