f docs

Add a utility to poll multiple futures simultaneously

If we have a handful of futures we want to make progress on
simultaneously we need some way to poll all of them in series,
which we add here in the form of `MultiFuturePoller`. Its probably
not as effecient as some of the options in the `futures` crate, but
it is very trivial and not that bad.

Create an `AOnionMessenger` trait similar to our other `AStruct`s

This allows us to have a bound on any `OnionMessenger` without
having to create bounds for every bound in `OnionMessenger`.

Merge pull request #2930 from jbesraa/Add-PaymentHash-to-Record

Add `PaymentHash` to `Record`

Merge pull request #2973 from valentinewallace/2024-03-om-mailbox

Support intercepting onion messages for offline peers

Fill in top-level docs for onion message offline peer interception.

Limit OnionMessenger event buffer size.

Manually implement Debug for onion message packets.

Previously we derived Debug, but that caused a lot of unreadable encrypted
bytes to be printed.

Test offline peer onion message interception.

Fix outdated comment in onion message functional test.

Refactor MessengerNode test util construction to take config.

Will be used in the next commit when another config parameter is added.

Support forwarding prebuilt onion messages in OnionMessenger.

OnionMessenger: support generating peer connection events.

Useful if we are in the mode of interception OMs for offline peers, so
users know when to re-inject intercepted OMs.

Support generating events when an OM for an offline peer is received.

Docs will be added in upcoming commits.

Merge pull request #3041 from G8XSU/followup-2957

Followups to #2957

Add `payment_hash` to `WithChannelMonitor`

Add `PaymentHash` to `Record`

    Adding the `payment_hash` to `Record` so we are able to track it
    in logs.

Merge pull request #2907 from shaavan/issue2882

Introduce ResponseInstructions for OnionMessage Handling

Merge pull request #3012 from TheBlueMatt/2024-04-0.0.123-rl

Add draft release notes for 0.0.123

Merge pull request #3054 from TheBlueMatt/2024-04-fuzz-bolt11

Add fuzzing coverage for BOLT11 invoice deserialization

Bump `possiblyrandom` to 0.2

I'd uploaded `possiblyrandom` 0.1 to reserve the crate name but
with a dummy library so now we need ot use 0.2 for the release.

Add changelog entries for 0.0.123

Use consistent byte/char offsets when parsing invoice HRPs

When parsing lightning-invoice HRPs we want to read them
char-by-char, tracking at which offset different fields were. Prior
to this commit this was done first by reading char-by-char and then
by indexing using the byte offset which works for ASCII strings but
fails on multi-byte characters.

This commit fixes this issue by simply always walking byte-by-byte
and rejecting multi-byte characters which don't belong in HRPs.

Substantially increase coverage in BOLT11 deserialization fuzzer

Move existing BOLT11 fuzz test to the `fuzz` crate

Merge pull request #3046 from TheBlueMatt/2024-03-fees-are-dust

Fix the `full_stack_target` breakage test and doc feerate requests

Implement ResponseInstruction Usage in OnionMessage Handling

This commit integrates the newly introduced ResponseInstruction structs
and enums into the codebase for handling OnionMessage responses.

Fix the `full_stack_target` breakage test and doc feerate requests

When we added the additional deust exposure checks in
702196819e6445048b803574fcacef77d5ce8c9c we added several
additional feerate fetches which broke the `full_stack_target`
change-detection test.

This updates the hard-coded test to support the new feerate fetches
and also includes a comment on `FeeEstimator` to indicate that
users really need to be caching feerates as otherwise they'll slow
us down.

Merge pull request #3045 from TheBlueMatt/2024-03-fees-are-dust

Include excess counterparty commitment transaction fees in dust exposure

Add a simple test of the new excess-fees-are-dust behavior

Update default dust exposure limit and the documentation thereof

Now that we're including excess counterparty commitment transaction
fees in our dust calculation, we need to update the docs
accordingly. We do so here, describing some of the considerations
and risks that come with the new changes.

We also take this opportunity to double the default value, as users
have regularly complained that non-anchor channels fail to send
HTLCs with the default settings with some feerates.

Fixes #2922

Include excess commitment transaction fees in dust exposure

Transaction fees on counterparty commitment transactions are
ultimately not our money and thus are really "dust" from our PoV -
they're funds that may be ours during off-chain updates but are not
ours once we go on-chain.

Thus, here, we count any such fees in excess of our own fee
estimates towards dust exposure. We don't bother to make an
inbound/outbound channel distinction here as in most cases users
will use `MaxDustExposure::FeeRateMultiplier` which will scale
with the fee we set on outbound channels anyway.

Note that this also enables the dust exposure checks on anchor
channels during feerate updates. We'd previously elided these as
increases in the channel feerates do not change the HTLC dust
exposure, but now do for the fee dust exposure.

Stop tracking chain_sync_monitor_persistences in TestPersister

Make ChannelMonitor chain-sync log a trace log

Minor Doc fixes after #2957

Merge pull request #3039 from valentinewallace/2024-04-invoice-amt-msats-overflow

Fix overflow in invoice amount setter.

Merge pull request #2957 from G8XSU/pause-events

Don't pause events for chainsync persistence

Fix overflow in invoice amount setter.

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

Keep newlines between releases in CHANGELOG consistent

Add release note for 0.0.122 with just three PRs.

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`

Introduce ResponseInstructions for OnionMessage Handling

- Currently, handle_message (or handle_custom_message) only exposes
  the generated response for an OnionMessage, lacking the necessary
  reply_path for asynchronous responses.

- This commit introduces a new flow for OnionMessage handling.

- Instead of solely taking the message as input, handle_message now accepts
  an Optional `responder`, returning a `ResponseInstruction` containing both
  the response and the reply_path.

- `ResponseInstruction` utilizes different enum variants to indicate how
  `handle_onion_message_response` should handle the response.

- This enhancement enables exposing the reply_path alongside the response
  and allows for more complex response mechanisms, such as responding with
  an added reply_path.

- The commit introduces the foundational framework (structs & enums) for this new flow.

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.

Swap `UserConfig::default()` for `test_default_channel_config`

As LDK changes, `UserConfig::default()` may imply marginally
different behavior, whereas `test_default_channel_config` is
intended to tweak defaults to provide a stable behavior for test
contexts.

This commit changes a few uses of `UserConfig::default()` to
`test_default_channel_config` in cases that will fail over the
coming commits due to dust changes.

Correct indentation in `get_pending_htlc_stats`

The previous commit left indentation in `get_pending_htlc_stats`
deliberately wrong, to ease reviewability. This commit fixes the
indentation.

Unify `get_{inbound,outbound}_pending_htlc_stats`

In most cases we already call both in a pair, and in fact always
consolidate some of the returned values across both accessors, so
there's not much reason to have them be separate methods.

Here we merge them.

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.

Remove ChainMonitor::sync_persistence_id

It was used earlier for generating unique MonitorUpdateId for
UpdateOrigin::ChainSync monitor updates.

Remove MonitorUpdateId from persist trait

MonitorUpdateId was an opaque abstraction for id's generated by
UpdateOrigin:Offchain and UpdateOrigin::ChainSync monitor updates.
It was mainly needed to map calls made to
ChainMonitor::channel_monitor_updated. We no longer track
UpdateOrigin::ChainSync MonitorUpdates and can directly use
ChannelMonitor::get_latest_update_id() for tracking
UpdateOrigin::Offchain monitor updates.

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.

Stop tracking MonitorUpdates from ChainSync in pending_monitor_updates

We no longer need to track them since we no longer hold events for
pending MonitorUpdates resulting from ChainSync.

Stop storing last_chain_persist_height

We only used to store last_chain_persist_height to release
events held for more than LATENCY_GRACE_PERIOD_BLOCKS due to
pending monitor update with UpdateOrigin::ChainSync. Since we no
longer pause events for ChainSync persistence, we no longer need to
store last_chain_persist_height.

Don't pause events for chainsync persistence

We used to wait on ChannelMonitor persistence to avoid
duplicate payment events. But this can still happen in cases where
ChannelMonitor handed the event to ChannelManager and we did not persist
ChannelManager after event handling.
It is expected to receive payment duplicate events and clients should handle these
events in an idempotent manner. Removing this hold-up of events simplifies
the logic and makes it easier to not persist ChannelMonitors on every block connect.

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