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.

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.

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

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.

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

If we are missing a `ChannelMonitor` for which the `ChannelManager`
has pending updates, it may be useful to print what the updates we
have actually are, at least useful in identifying the bug(s).

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.