Provide more color in filter registration methods

A few years ago we had repeated user confusion dealing with the
`Filter` methods and exactly how they differ. Here we try to add a
bit more color in several ways as suggested by users in a few
places - listing examples of why the methods are used as well as
ensuring its clearly communicated that not all parameters need be
used.

Fixes #1069

Merge pull request #3035 from TheBlueMatt/2024-04-upstream-123-bindings

Merge pull request #3018 from jkczyz/2024-04-optional-description

Optional description for `Offer` and `Refund`

Merge pull request #3029 from TheBlueMatt/2024-04-fix-batch-funding-failures

Add error handling for channels which fail to be created in `funding_transaction_generated_intern`

Only require description when offer has an amount

The spec was changed to allow excluding an offer description if the
offer doesn't have an amount. However, it is still required when the
amount is set.

Merge pull request #3033 from TheBlueMatt/2024-04-notify-bp-on-blocks

Wake `background-processor` from `ChainMonitor` on new blocks

Wake `background-processor` from `ChainMonitor` on new blocks

When we receive a new block we may generate
`Event::SpendableOutputs` in `ChannelMonitor`s which then need to
be processed by the background processor. While it will do so
eventually when its normal loop goes around, this may cause user
tests to be delayed in finding events, so we should notify the BP
immediately to wake it on new blocks.

We implement that here, unconditionally notifying the
`background-processor` whenever we receive a new block or confirmed
transactions.

Update documentation on `[u8; 32]` wrappers for clarity

Move `[u8; 32]` wrapper types to a common module

The `PaymentHash`, `PaymentSecret`, `PaymentPreimage`, and
`ChannelId` types are all small wrappers around `[u8; 32]` and are
used throughout the codebase but were defined in the top-level
`ln/mod.rs` file and the relatively sparsely-populated
`ln/channel_id.rs` file.

Here we move them to a common `types` module and go ahead and
update all our in-crate `use` statements to refer to the new
module for bindings. We do, however, leave a `pub use` alias for
the old paths to avoid upgrade hassle for users.

Add bindings no-export tags to doc test types

We don't actually intend these to be public as they're just for
docs but the bindings don't currently parse `#[doc(hidden)]` as
"no-export" so we add manual no-export tags as well.

Add derives where they make sense and the bindings require them

Rename and expose message-specific `NextHop`

`onion::message::messenger::PeeledOnion` is a public enum which
included the private enum `NextHop`, which is not acceptable. Thus,
we here expose `NextHop` but rename it `NextMessageHop` to make
clear that it is specific to messages.

Merge pull request #3032 from valentinewallace/2024-04-pico-btc-overflow

Fix overflow in lightning-invoice `amount_pico_btc`

Merge pull request #3031 from TheBlueMatt/2024-04-new-rustc-warning

Fix new rustc `#[macro_export]` warning in doctests

Fix new rustc `#[macro_export]` warning in doctests

rustc now warns any time a `#[macro_export]` is used inside a
function as it generates surprising results. Because doctests are
run inside implicit test functions this means any use of
`#[macro_export]` inside a doctest will now warn. We do this in
`lightning-custom-message` to demonstrated how to use the crate,
which now fails to compile.

Here we fix this by adding an `fn main() {}` to the doctest, which
causes doctests to be compiled as freestanding code rather than
inside a test function.

Note that while discussing this upstream it came up that rustc is
also planning on changing the way doctests are compiled to compile
an entire crate's doctests in one go rather than in separate
crates, causing doctests to have a shared namespace which may
generate future surprising outcomes.

Fix overflow in lightning-invoice amount_pico_btc.

Send peers error messages for failures due to invalid batch funding

If we fail to fund a batch open we'll force-close all channels in
the batch, however would previously fail to send error messages to
our peers for any channels we were due to test after the one that
failed.

This commit fixes that issue, sending the required error messages
to allow our peers to clean up their state.

Close channels when `find_funding_output` fails to find an output

In `funding_transaction_generated_intern`, if `find_funding_output`
fails (e.g. due to the require output not being present in the
provided funding transaction) we'd previously not generated a
`ChannelClosed` event which leaves users possibly in a confused
state.

Here we fix this, also fixing the relevant tests to check for the
new event.

Fixes #2843.

Merge pull request #3017 from jkczyz/2024-04-optional-pubkey

Sending to `Offer` without `signing_pubkey`

Merge pull request #3028 from jkczyz/2024-04-offer-id-followups

Follow-ups to #2970

Remove InvoiceRequestFields::features

InvoiceRequestFeatures may contain a large, odd bit. Including this in
InvoiceRequestFields, which is in each BlindedPath of a Bolt12Invoice,
could cause the invoice's onion message to exceed the maximum size. The
features are already checked before sending an invoice.

Remove InvoiceRequestFields::amount_msats

Event::PaymentClaimable and Event::PaymentClaimed already contain the
paid amount, so there's no need to included the requested amount in
InvoiceRequestFields.

Remove PaymentContext from OnionPayload

PaymentContext is already stored in ClaimablePayment via PaymentPurpose,
so there is no need to repeat it in each ClaimableHTLC via OnionPayload.
This avoids cloning the PaymentContext each time an HTLC is received,
other than for the first HTLC for a payment.

Don't require Refund::description in API

Refunds currently require a description, though this may change to be
optional. Remove the description requirement from the API, setting and
empty string by default.

Don't require Offer::description in API

Offers currently require a description, though this may change to be
optional. Remove the description requirement from the API, setting and
empty string by default.

Bolt12Invoice for Offer without signing_pubkey

When parsing a Bolt12Invoice use both the Offer's signing_pubkey and
paths to determine if it is for an Offer or a Refund. Previously, an
Offer was required to have a signing_pubkey. But now that it is
optional, the Offers paths can be used to make the determination.
Additionally, check that the invoice matches one of the blinded node ids
from the paths' last hops.

Add InvoiceRequestTlvStream::paths

Instead of reusing OfferTlvStream::paths, add a dedicated paths TLV to
InvoiceRequestTlvStream such that it can be used in Refund. This allows
for an Offer without a signing_pubkey and still be able to differentiate
whether an invoice is for an offer or a refund.

Allow parsing Offer without signing_pubkey

If an offer has at least one path, it may omit the signing pubkey and
use the blinded node id of the last hop of a path to sign an invoice.
Allow parsing such offers but not yet creating them.

Optional OfferContents::signing_pubkey

If an Offer contains a path, the blinded_node_id of the path's final hop
can be used as the signing pubkey. Make Offer::signing_pubkey and
OfferContents::signing_pubkey return an Option to support this. Upcoming
commits will implement this behavior.

Merge pull request #3003 from TheBlueMatt/2024-04-2964-followups

#2964 Followups

Merge pull request #3021 from TheBlueMatt/2024-04-drop-blocked-completed-updates

Drop completed blocked `ChannelMonitorUpdate`s on startup

Merge pull request #3004 from TheBlueMatt/2024-04-2761-followups

#2761 Followups

Drop completed blocked `ChannelMonitorUpdate`s on startup

If a user receives a payment preimage for an outbound payment, the
`PaymentSent` event will block any eventual RAA
`ChannelMonitorUpdate` from the same channel, assuming it comes in
before the event can be processed. If this blocking kicks in, but
the flow eventually completes with the RAA `ChannelMonitorUpdate`
being persisted, but the `ChannelManager` is only persisted prior
to the event being handled, on startup we'll have a fully
up-to-date `ChannelMonitor` but a pending, blocked
`ChannelMonitorUpdate`. When the `PaymentSent` event is replayed
we'll end up trying to apply a redundant `ChannelMonitorUpdate`
which will panic.

See the test added in this commit for an implementation of this
situation.

In this commit we fix this issue by simply dropping blocked
`ChannelMonitorUpdate`s the same as we do pending ones.

Merge pull request #3015 from tnull/2024-04-sweeper-error-on-persistence-failure

Make `OutputSweeper::track_spendable_outputs` fallible

Make `OutputSweeper::track_spendable_outputs` fallible

.. as otherwise we might only log an error and continue if we fail to
persist the sweeper state.

Merge pull request #2981 from dunxen/2024-03-PR2419fixups

Fixups for #2419

Add intermediate `ConstructedTransaction`

Add lower bound segwit input weight estimates

Add descriptions to test cases

Abort if we add a duplicate input

Make sent_tx_* fallible and handle errors & simplify counterparty_weight_contributed calc

Check if msg.script.is_witness_program() before checking version

Use HashMaps as, well, HashMaps (don't iter for key match)

Remove unnecessary PaymentPreimage clone

Merge pull request #2990 from TheBlueMatt/2024-04-log-in-flights

Log pending in-flight updates when we are missing a monitor

Drop the rustup-specific calling in `ci/rustfmt.sh`

The +rustversion call semantics are specific to rustup and do not
work with standard rust toolchains. However, because rustfmt
formatting differs slightly between stable and our 1.63 target, we
need to keep the +1.63.0 for rustup users.

Thus, here, we check for the presence of a `rustup` command and
pass the "+1.63.0" argument if we find one.

Include `channel_keys.rs` in the rustfmt list

Since its already formatted and there's not much active work going
on in it.

Only include `derive_add_tweak` for base key types that use it

Specifically `RevocationBasepoint` has a different derivation, so
shouldn't have a `derive_add_tweak` at all. We also use this
opportunity to link to the `from_basepoint` function in the
`derive_add_tweak` docs.

Word-wrap new doc comment in `DelayedPaymentOutputDescriptor`

Use `Sha256`s for tweaks in `sign` to enforce randomness

We assume that tweaks are the output of a SHA-256 hash function
(and thus that failing to create a private key from the has
negligible probability) in `add_public_key_tweak` and elsewhere.

Thus, we really shouldn't be taking byte arrays in the public API
but rather `Sha256` objects, and communicating in the docs for
`add_public_key_tweak` that we can panic if its not the output of
a hash function, both of which we do here.

Simplify and clarify `derive_add_tweak` documentation

Log when a ChannelMonitor's claimable balances set goes empty

Debug-log monitor update starts and completions in `ChainMonitor`

When a `ChannelMonitor[Update]` persistence completes, we rely on
logging in `ChannelManager` to hear about it. However, this won't
happen at all if there's still pending updates as no `MonitorEvent`
will be generated.

Thus, here, we add logging directly in `ChainMonitor`, ensuring we
can deduce when individual updates completed from debug logs.

Merge pull request #3009 from tnull/2024-04-fix-sweeper-typo

Fix typo in `OutputSweeper`

Fix typo in `OutputSweeper`

... as 'ouputs' isn't a thing.

Merge pull request #3005 from TheBlueMatt/2024-04-0.0.123-beta

Cut 0.0.123-beta

Bump crate versions to 0.0.123-beta/invoice 0.31-beta

Merge pull request #2761 from yellowred/self_sufficient_psbt

Implement PSBT fields that were missing for a Signer

Implement Script for Witness and Add Tweak in PSBT.

Adding Witness Script and key tweaks makes
a Partially Signed Bitcoin Transaction the single data
source needed for a Signer to produce valid signatures.
A Signer is not required to be able to generate L2 keys,
e.g delayed payment basepoint.

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