Builder for creating static invoices from offers

Add a builder for creating static invoices for an offer. Building produces a
semantically valid static invoice for the offer, which can then be signed with
the key associated with the offer's signing pubkey.

Static invoice encoding and parsing

Define an interface for BOLT 12 static invoice messages. The underlying
format consists of the original bytes and the parsed contents.

The bytes are later needed for serialization. This is because it must
mirror all the offer TLV records, including unknown ones, which aren't
represented in the contents.

Invoices may be created from an offer.

InvoiceTlvStream{Ref}: add message_paths field

Will be used in static invoices. Also test that we'll fail to decode if these
paths are included in single-use BOLT 12 invoices.

Use ? instead of matching in BOLT 12 invoice parsing.

Minor cleanup to be more concise.

BOLT 12 invoice: extract helper for invoice signing pubkey checks

Will be useful for static invoices.

BOLT 12 invoice: expose common helper methods and fields

Useful for static invoice support.

Genericize BOLT 12 invoice{_builder} common macro docs over invoice type

Will be useful so the docs generated work for static invoices.

Move common BOLT 12 accessor methods to new macro.

Will be useful when we support static BOLT 12 invoices.

Move common BOLT 12 invoice builder setters to new macro.

Will be useful when we later add support for static BOLT 12 invoices.

Remove redundant checks in BOLT 12 invoice tests.

Merge pull request #3060 from TheBlueMatt/2024-05-parallel-async-om-events

Add a parallel async event handler to OnionMessenger and pass it directly to BackgroundProcessor

Merge pull request #3088 from alecchendev/2024-06-fc-no-disconnect

Don't disconnect on manual force closes

Merge pull request #3089 from TheBlueMatt/2024-06-channel_state-module

Move the public channel state API into a new module

Move the public path for `channel_state` types to their new path

Reformat `channel_state.rs` to match rustfmt requirements

Move the public channel state API into a new module

Our "what is the channel's current state" structs have slowly
grown to be rather nontrivial, and now include eight structs with
many fields. Thus, it makes sense to pull them out of
`ln::channelmanager` and into their own module.

This also makes things easier for the C bindings which don't
support `pub use` from a private module.

Merge pull request #2965 from tnull/2024-03-impl-readable-writeable-offer-invoice-refund

Implement `Readable` for `Offer` and `Refund`

Implement `Readable` for `Refund`

When storing `Refund`s, it's useful for them to implement LDK's
deserialization trait.

Implement `Readable` for `Offer`

When storing `Offer`s, it's useful for them to implement LDK's
deserialization trait.

Don't disconnect on manual force closes

Merge pull request #2889 from Sharmalm/2840

Allow for user-specified error message during force close channel

Drop `EventsProvider` bounds on `OnionMessageHandler`s

This never really made a lot of sense from an API perspective, but
was required to avoid handing the background processor an explicit
`OnionMessegner`, which we are now doing. Thus, we can simply drop
these bounds as unnecessary.

f fix imports in BP

Switch to using the `OnionMessenger` directly in BP

When `OnionMessenger` first developed a timer and events interface,
we accessed the `OnionMessenger` indirectly via the `PeerManager`.
While this is a fairly awkward interface, it avoided a large pile
of generics on the background processor interfaces. However, since
we now have an `AOnionMessenger` trait, this concern is no longer
significant. Further, because we now want to use the built-in
`OnionMessenger` async event processing method, we really need a
direct referene to the `OnionMessenger` in the background
processor, which we add here optionally.

Add a parallel async event handler to `OnionMessenger`

This adds an `OnionMessenger::process_pending_events_async`
mirroring the same in `ChannelManager`. However, unlike the one in
`ChannelManager`, this processes the events in parallel by spawning
all futures and using the new `MultiFuturePoller`.

Because `OnionMessenger` just generates a stream of messages to
store/fetch, we first process all the events to store new messages,
`await` them, then process all the events to fetch stored messages,
ensuring reordering shouldn't result in lost messages (unless we
race with a peer disconnection, which could happen anyway).

Store `OnionMessenger` events in different `Vec`s

In the next commit, `OnionMessenger` events are handled in parallel
using rust async. When we do that, we'll want to handle
`OnionMessageIntercepted` events prior to
`OnionMessagePeerConnected` ones.

While we'd generally prefer to handle all events in the order they
were generated, if we want to handle them in parallel, we don't
want a `OnionMessageIntercepted` event to start being processed,
then handle an `OnionMessagePeerConnected` prior to the first
completing. This could cause us to store a freshly-intercepted
message for a peer in a DB that was just wiped because the peer
is now connected.

This does run the risk of processing a `OnionMessagePeerConnected`
event prior to an `OnionMessageIntercepted` event (because a peer
connected, then disconnected, then we received a message for that
peer all before any events were handled), that is somewhat less
likely and discarding a message in a rare race is better than
leaving a message lying around undelivered.

Thus, here, we store `OnionMessenger` events in separate `Vec`s
which we can pull from in message-type-order.

Merge pull request #3057 from G8XSU/2024-05-08-claimable-persist-3049

Minimize reads to counterparty_claimable_outpoints

Merge pull request #2947 from tnull/2024-03-log-features-if-mismatch

Merge pull request #2996 from shaavan/issue2882.2

Allow responding asynchronously to OnionMessage

Merge pull request #3063 from jirijakes/upgrade-bitcoin-031

Upgrade rust-bitcoin dependency to 0.31

Merge pull request #2931 from TheBlueMatt/2024-03-log-outbound-channels

Log available liquidity on each channel when starting routefinding

Merge pull request #3084 from jkczyz/2024-05-onion-fields

Include `RecipientOnionFields` in `Event::PaymentClaimed`

Minimize reads to counterparty_claimable_outpoints

Reads related to current/previous commitment_tx should be explicit
and reads related to older commitment_txs should be minimized.

Log available liquidity on each channel when starting routefinding

One of the most common first-steps in troubleshooting routefinding
issues is we ask for the local channel state to determine what the
available HTLC bounds are. While we log first-hop channel details
when we decline to use them, this doesn't tell us if we have
missing channels, and thus here we log all first-hop channels at
the start.

We also take this opportunity to log the limits that were violated
any time we log that we're not using a channel, rather than only
when its a first-hop.

Upgrade rust-bitcoin to 0.31

Introduce new tests for `ResponseInstruction::WithReplyPath`

- The new tests check both successful and unsuccessful `reply_path`
  creation conditions.

Refactor TestCustomMessageHandler

- Introduce a new struct for keeping expectations organized.
- Add a boolean field to track whether a response is expected,
  and hence whether a `reply_path` should be included with the response.
- Update Ping and Pong roles for bidirectional communication.
- Introduce panic for when there is no responder and we were expecting
  to include a `reply_path`.
- Refactor `handle_custom_message` code.

Refactor: Rename Request & Response to Ping & Pong

1. These two variants will be modified in an upcoming commit
   to be each other's response.
2. The names are updated to better fit their new roles.

Introduce ResponseInstruction::WithReplyPath variant.

And expand handle_onion_message_response return Type

1. Introduce a new function in OnionMessenger to create blinded paths.
2. Use it in handle_onion_message_response to create a reply_path for
   the right variant and use it in onion_message.
3. Expand the return type of handle_onion_message_response to handle three cases:
1. Ok(None) in case of no response to be sent.
2. Ok(Some(SendSuccess) and Err(SendError) in case of successful and
    unsuccessful queueing up of response messages respectively.

This allows the user to get access to the Success/Failure status of the sending
of response and handle it accordingly.

Convert handle_onion_message_response to a public function and add test coverage

This commit modifies handle_onion_message_response to be accessible
publicly as handle_onion_message, enabling users to respond
asynchronously. Additionally, a new test is introduced to validate this
functionality.

Merge pull request #3011 from jkczyz/2024-04-compact-blinded-path-creation

Compact blinded path creation

Add missing copyright statement

Compact introduction node test vector

Compact a BlindedPath's introduction node

Add a method to BlindedPath that given a network graph will compact the
IntroductionNode as the DirectedShortChannelId variant. Call this method
from DefaultMessageRouter so that Offer paths use the compact
representation (along with reply paths). This leaves payment paths in
Bolt12Invoice using the NodeId variant, as the compact representation
isn't as useful there.

Unwrap reply_path in extract_invoice_request

Pass ForwardNode when creating BlindedPath

Instead of passing Vec<PublicKey> to MessageRouter::crate_blinded_path,
pass Vec<ForwardNode>. This way callers can include a short_channel_id
for a more compact BlindedPath encoding.

Support NextHop::ShortChannelId in BlindedPath

When sending an onion message to a blinded path, the short channel id
between hops isn't need in each hop's encrypted_payload since it is not
a payment. However, using the short channel id instead of the node id
gives a more compact representation. Update BlindedPath::new_for_message
to allow for this.

Merge pull request #3006 from arik-so/arik/trampoline/2024-04-trampoline-onion-deserialization

Trampoline Onion Deserialization

Merge pull request #3051 from TheBlueMatt/2024-04-2982-123-fix

Don't attempt to resume channels if we already exchanged funding

Don't attempt to resume channels if we already exchanged funding

ddf75afd16 introduced the ability to re-exchange our `ChannelOpen`
after a peer disconnects if we didn't complete funding on our end.
It did not implement nor consider what would happen if we
re-connected after we created our own funding transactions, and
currently it panics (and even if it did not it would replay the
`FundingTransactionGenerated` event to users).

While we'd very much like to replay the `open_channel` flow even
if we have already received an `accept_channel` and funded the
channel, we cannot as the peer will likely provide different key
material in their `accept_channel`, causing us to need a different
funding transaction.

Thus, here, we simply close channels which have been funded but not
yet signed when our peer disconnects.

f docs

Check custom_tlvs in Event::PaymentClaimed

Pass ClaimAlongRouteArgs to claim_payment_along_route

Pass ClaimAlongRouteArgs to do_claim_payment_along_route

Include RecipientOnionFields in PaymentClaimed

RecipientOnionFields are included in Event::PaymentClaimable, so
naturally they should be included in Event::PaymentClaimed, too.

Add RecipientOnionFields to ClaimingPayment

This will be used to include the same field in Event::PaymentClaimed.

Use HashMap::entry instead of HashMap::insert

This allows for obtaining the value without needing to re-look it up. An
upcoming commit will include RecipientOnionFields in the inserted value.
Having it available afterwards prevents needing to clone it.

Format HashMap::insert call

Merge pull request #3079 from jkczyz/2024-05-expects-quantity

Add missing `Offer::expects_quantity` to tests

Add missing Offer::expects_quantity to tests

Merge pull request #3038 from TheBlueMatt/2024-05-no-dir-with-on-side-offline

Ignore partially-pruned channels during routing

Merge pull request #3026 from valentinewallace/2024-04-limit-path-len

Limit payment path length based on `payment_metadata`, custom TLVs, etc.

Merge pull request #3073 from tnull/2024-05-bump-nits

Fix minor nits in `BumpTransactionEventHandler`

Merge pull request #3068 from toxeus/main

Re-export bitcoin crate

Test Trampoline onion (de)serialization round trip.

Make Trampoline onion deserializable.

Add public util on RouteParameters for setting max path length.

Test routing payment parameters' max path length setting and usage.

outbound_payment: set max path length in PaymentParameters.

So the router knows how long the maximum payment path can be.

Test utils: include payment_metadata in PassAlongPathArgs.

Abide by max path length param in router.

Also adds some testing by augmenting existing tests.

Add max path length knob to PaymentParameters.

Will be used so the outbound_payment module can calculate the maximum path
length with knowledge of any custom TLVs or payment metadata present.

Merge pull request #3069 from TheBlueMatt/2024-06-log-chan-count

Log how many nodes/channels we have synced when we try to route

Log how many nodes/channels we have synced when we try to route

A common issue in LN is not having fully synced the network graph
when we attempt to send a payment. This should be improved
substantially with gossip v1.5, but for now we should improve our
debugability by logging how many nodes we have in our graph when
we attempt to find a route.

Re-export bitcoin crate

For the same reason the `bitcoin` crate is re-exporting
the `secp256k1` crate the `lightning` crate should
re-export the `bitcoin` crate: to ease the burden on
calling code to maintain compatible `bitcoin` versions.

The `lightning` crate makes heavy use of types defined in
(or re-exported by) the `bitcoin` crate. Compilation will
fail if e.g. comparisons or `match` expressions are done with
types from `bitcoin` crate versions with a non-equal minor
version. This forces calling code to depend on a `bitcoin`
crate with a compatible version. This becomes a maintenance
nightmare once two or more crates, that use `bitcoin` types
in their public API, are used in calling code simultaneously.

Fix minor nits in `BumpTransactionEventHandler`

Extract onion_utils::build_onion_payloads_callback helper.

Will be useful when we want to calculate the total size of the payloads without
actually allocating for them.

Merge pull request #3036 from TheBlueMatt/2024-05-filter-color

Provide more color in filter registration methods

Make MAX_PATH_LENGTH_ESTIMATE const pub and expand doc comment.

Will be used in the next commit when we make this configurable in
PaymentParameters.

TestRouter: support checking only that route params are as expected.

Remove unnecessary RecipientOnionFields clone.

Doable now that we take Vecs by reference in OutboundOnionPayload.

OutboundOnionPayload: hold Vec fields as references.

Will be useful when we reuse this enum to calculate the maximum path length,
to avoid cloning the vecs.

Merge pull request #3061 from TheBlueMatt/2024-05-bindings-upstream

Minor bindings tweaks

Allow any `Deref` to an `EntropySource` in `BlindedPath` building

This matches our normal API semantics and allows, for example,
`Arc`s to `EntropySource`s.

impl `Clone` on various public (mostly BOLT12) types

This is required for bindings as passing types from Rust to GC'd
languages can't map the concept of a type that has a lifetime of
the called function but instead needs to clone for safety.

Expose `ChannelManager` offer constructors in bindings

Mark `io_extras` as no-bindings-export as its not for public use

Make `offers::Amount` `Copy` and export it in bindings

`Amount` is less than two pointers long, so there's no reason it
shouldn't be `Copy`. Further, because its an enum, bindings can't
map a reference to it in an `Option`. Thus, here, we simply make it
`Copy` and return it in `Option`s rather than a reference to it.

Use prelude by universal import, rather than single import

This avoids the bindings trying to figure out what a
`lightning::prelude::Vec` is rather than matching it as a `Vec`.

Export `ChannelId` in bindings rather than `[u8; 32]`

Now that `ChannelId` has useful constructors and methods we need
to start exposing it to bindings users rather than relying on using
`[u8; 32]`.

Skip `BestBlock::new` in bindings as we already have one

Merge pull request #3058 from benthecarman/deref-empty-nod-id-lookup

impl Deref for EmptyNodeIdLookUp

Merge pull request #3059 from jkczyz/2024-05-drop-writeable-signer

Remove `WriteableEcdsaChannelSigner` trait

Remove WriteableEcdsaChannelSigner trait

WriteableEcdsaChannelSigner is no longer needed now that
EcdsaChannelSigner isn't written in OnchainTxHandler.

Stop writing EcdsaChannelSigner

EcdsaChannelSigner is no longer deserialized as of version 0.0.113 and
downgrades before version 0.0.113 are no longer supported as of version
0.0.119.

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

impl Deref for EmptyNodeIdLookUp