Implement async versions of process_pending_events

Consume events by value in EventHandler's handle_event

Use BaseEventHandler to expose async event handling on InvoicePayer

We introduce a new sealed trait BaseEventHandler that has a blanket
implementation for any T. Since the trait cannot be implemented outside
of the crate, this allow us to expose specific implementations of
InvoicePayer that allow for synchronous and asynchronous event handling.

Apply network graph updates through NetworkUpdate's instead of Event's

Merge pull request #1844 from valentinewallace/2022-11-htlc-interception-refactor-followup

Rename `PendingHTLCInfo` fields to include msat suffix

Merge pull request #1843 from TheBlueMatt/2022-11-fix-bp-exit-docs

Correct async `lightning-background-processor` exit check docs

Merge pull request #1796 from tnull/2022-10-track-confirmation-block-hash

Track confirmation block hash and return via `Confirm::get_relevant_txids`

Rename PendingHTLCInfo fields to include msat suffix

Merge pull request #1842 from jkczyz/2022-11-channel-monitor-docs

Fix outdated `ChannelMonitor` docs

Correct async `lightning-background-processor` exit check docs

The check to stop the background processor is true -> break, not
false -> break. This simply updates the docs and leaves the code
as-is.

Merge pull request #1840 from valentinewallace/2022-11-htlc-intercept-prefactor

Pre-refactor for HTLC Interception

Fix outdated ChannelMonitor docs

ChannelMonitor::get_and_clear_pending_events docs references a method
that had been refactored and is no longer accurate.

Merge pull request #1834 from dunxen/2022-11-expose-pending-monitor-updates

Add public method to list pending monitor updates from `ChainMonitor`

Track block hash, return via `get_relevant_txids`

Previously, `Confirm::get_relevant_txids()` only returned a list of
transactions that have to be monitored for reorganization out of the
chain. This interface however required double bookkeeping: while we
internally keep track of the best block, height, etc, it would also
require the user to keep track which transaction was previously
confirmed in which block and to take actions based on any change, e.g,
to reconfirm them when the block would be reorged-out and the
transactions had been reconfirmed in another block.

Here, we track the confirmation block hash internally and return it via
`Confirm::get_relevant_txids()` to the user, which alleviates the
requirement for double bookkeeping: the user can now simply check
whether the given transaction is still confirmed and in the given block,
and take action if not.

We also split `update_claims_view`: Previously it was one, now it's two
methods: `update_claims_view_from_matched_txn` and
`update_claims_view_from_requests`.

Add public method to list pending monitor updates from `ChainMonitor`

Users have requested the feature to list pending monitor updates from
`ChainMonitor` so this adds that.

Merge pull request #1719 from jkczyz/2022-09-offer-encoding

BOLT 12 `offer` encoding and building

Fix scid_utils::is_valid* false positive

cargo bench was able to find an scid of 0 as a valid fake scid

Track incoming amount in PendingHTLCInfo

Used in upcoming commit(s) when we generate the PaymentIntercepted event for
intercepted payments.

Co-authored-by: John Cantrell <johncantrell97@gmail.com>
Co-authored-by: Valentine Wallace <vwallace@protonmail.com>

Delete unnecessary whitespace in process_pending_forwards

Only whitespace diff

Refactor HTLCForwardInfo::AddHTLC for intercept forwards

In upcoming commit(s), we'll want to store intercepted HTLC forwards in
ChannelManager before the user signals that they should be forwarded.  It
wouldn't make sense to store a HTLCForwardInfo as-is because the FailHTLC
variant doesn't make sense, so we refactor out the ::AddHTLC contents into its
own struct for storage.

Co-authored-by: John Cantrell <johncantrell97@gmail.com>
Co-authored-by: Valentine Wallace <vwallace@protonmail.com>

Merge pull request #1833 from johncantrell97/2022-11-rgs-handle-removed-channel

Ignore RGS channel updates for unknown channels

Builder for creating offers

Add a builder for creating offers given a required description and
node_id. Other settings are optional and duplicative settings will
override previous settings for non-Vec fields.

Merge pull request #1837 from tnull/2022-10-fix-meeting-time

Fix LDK Dev Meeting time

Fix LDK Dev Meeting time and typo

ignore updates for unknown channels

Merge pull request #1639 from ViktorTigerstrom/2022-07-move-short-to-chan-info

Move `short_to_chan_info` into standalone lock

Serialization macro for TLV streams

BOLT 12's offer message is encoded as a TLV stream (i.e., a sequence of
TLV records). impl_writeable_tlv_based can't be used because it writes
the overall length of the struct, whereas TLV streams only include the
length of each TLV record. Add a `tlv_stream` macro for defining structs
used in encoding.

TLV records containing a single variable-length type should not encode
the types length in the value since it is redundant. Add a wrapper type
that can be used within a TLV stream to support the correct behavior
during serialization and de-serialization.

Add WithoutLength wrapper

When serializing variable-length types as part of a TLV stream, the
length does not need to be serialized as it is already encoded in TLV
records. Add a WithoutLength wrapper for this encoding. Replace
VecReadWrapper and VecWriteWrapper with this single type to avoid
redundant encoders.

Offer message interface and data format

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

The bytes are later needed when constructing an `invoice_request`
message. This is because it must mirror all the `offer` TLV records,
including unknown ones, which aren't represented in the contents.

The contents will be used in `invoice_request` messages to avoid
duplication. Some fields while required in a typical user-pays-merchant
flow may not be necessary in the merchant-pays-user flow (i.e., refund).

Add PrintableString utility

Strings defined by third parties may contain control characters. Provide
a wrapper such that these are replaced when displayed. Useful in node
aliases and offer fields.

Offer features for BOLT 12

The offer message in BOLT 12 contains a features TLV record. Add a
corresponding OfferFeatures type where the length is not included in the
serialization as it would be redundant with the record length.
Otherwise, define the features to be the same as InvoiceFeatures.

Make `process_pending_htlc_forwards` more readable

Refactor `process_pending_htlc_forwards` to ensure that both branches
that fails `pending_forwards` are placed next to eachother for improved
readability.

Consider `channel_id`s in `short_to_chan_info` as unguaranteed

As the `short_to_chan_info` map has been removed from the
`channel_state`, there is no longer any consistency guarantees between
the `by_id` and `short_to_chan_info` maps. This commit ensures that we
don't force unwrap channels where the channel_id has been queried from
the `short_to_chan_info` map.

Remove excess `channel_state` passing to macros

As the `short_to_chan_info` has been moved out of the `channel_state` to
a standalone lock, several macros no longer need the `channel_state`
passed into the macro.

Move `short_to_chan_info` into standalone lock

As the `channel_state` (`ChannelHolder`) struct will be removed, this
commit moves the `short_to_chan_info` map from that lock into a seperate
lock.

Remove empty match arm during prefix check

Merge pull request #1831 from benthecarman/hash-ConfirmationTarget

Implement Hash for ConfirmationTarget

Implement Hash for ConfirmationTarget

Merge pull request #1811 from valentinewallace/2022-10-chanman-router

Move `InflightHtlcs` and `Router` trait into `ChannelManager`

Merge pull request #1761 from TheBlueMatt/2022-10-user-idempotency-token

Provide `send_payment` idempotency guarantees

Move InvoicePayer's Router into ChannelManager

This helps prepare to parameterize ChannelManager with a Router, to eventually
use in trampoline payments.

Move InFlightHtlcs into ChannelManager

This is part of moving the Router trait into ChannelManager, which will help
allow ChannelManager to fetch routes on-the-fly as part of supporting
trampoline payments.

Merge pull request #1817 from TheBlueMatt/2022-10-removed-no-score-after

Merge pull request #1743 from tnull/2022-09-channel-events

Add `ChannelReady` event

Fix warnings for ununsed anchor imports

Previously introduced during release commit.

Rename chan state `ChannelFunded` to `ChannelReady`

We rename `ChannelState::ChannelFunded` to `ChannelState::ChannelReady`
as we'll be in this state when both sides sent the `ChannelReady`
messages, which may also be before funding in the 0conf case.

Add `ChannelReady` event

This adds a `ChannelReady` event that is emitted as soon as a new
channel becomes usable, i.e., after both sides have sent
`channel_ready`.

Add missing break when scoring a path with a missing channel

If we send payments over a path where a channel ended up being
closed, we'll remove it before we call
`ProbabilisticPaymentScorer::payment_path_failed`. This should be
fine, except that `payment_path_failed` does not break out of its
scoring loop if a channel is missing, causing it to assign a
minimum available-liquidity of the payment amount even to channels
which our attempt never arrived at.

The fix is simple - add the missing check and break.

Merge pull request #1735 from naumenkogs/2022-09-prune-channels-if-either-not-upd

Prune channels if either not updated + track pruning time

Merge pull request #1753 from wpaulino/avoid-redundant-claims-after-initial-conf

Avoid generating redundant claims after initial confirmation

Avoid generating redundant claims after initial confirmation

These claims will never be valid as a previous claim has already
confirmed. If a previous claim is reorged out of the chain, a new claim
will be generated bypassing the new behavior.

While this doesn't change much for our existing transaction-based
claims, as broadcasting an already confirmed transaction acts as a NOP,
it prevents us from yielding redundant event-based claims, which will be
introduced as part of the anchors patchset.

Track the time a stale channel was pruned

Add a pending changelog entry for the past few commits

Allow users to specify the `PaymentId` used in `InvoicePayer`

In order to allow users to pass a custom idempotency key to the
`send*` methods in `InvoicePayer`, we have to pipe the `PaymentId`
through to the `Payer` methods, which we do here.

By default, existing `InvoicePayer` methods use the `PaymentHash`
as the `PaymentId`, however we also add duplicate `send*_with_id`
methods which allow users to pass a custom `PaymentId`.

Finally, appropriate documentation updates are made to clarify
idempotency guarantees.

Test that PaymentIds are idempotency keys until `abandon_payment`

Stop timing out payments automatically, requiring abandon_payment

When the `abandon_payment` flow was added there was some concern
that upgrading users may not migrate to the new flow, causing
memory leaks in the pending-payment tracking.

While this is true, now that we're relying on the
pending_outbound_payments map for `send_payment` idempotency, the
risk of removing a payment prematurely goes up from "spurious
retry failure" to "sending a duplicative payment", which is much
worse.

Thus, we simply remove the automated payment timeout here,
explicitly requiring that users call `abandon_payment` when they
give up retrying a payment.

Delay removal of fulfilled outbound payments for a few timer ticks

Previously, once a fulfilled outbound payment completed and all
associated HTLCs were resolved, we'd immediately remove the payment
entry from the `pending_outbound_payments` map.

Now that we're using the `pending_outbound_payments` map for send
idempotency, this presents a race condition - if the user makes a
redundant `send_payment` call at the same time that the original
payment's last HTLC is resolved, the user would reasonably expect
the `send_payment` call to fail due to our idempotency guarantees.

However, because the `pending_outbound_payments` entry is being
removed, if it completes first the `send_payment` call will
succeed even though the user has not had a chance to see the
corresponding `Event::PaymentSent`.

Instead, here, we delay removal of `Fulfilled`
`pending_outbound_payments` entries until several timer ticks have
passed without any corresponding event or HTLC pending.

Allow users to specify the `PaymentId` for new outbound payments

In c986e52ce83e9aeaa9447abebc5f6600470337cf, an `MppId` was added
to `HTLCSource` objects as a way of correlating HTLCs which belong
to the same payment when the `ChannelManager` sees an HTLC
succeed/fail. This allows it to have awareness of the state of all
HTLCs in a payment when it generates the ultimate user-facing
payment success/failure events. This was used in the same PR to
avoid generating duplicative success/failure events for a single
payment.

Because the field was only used as an internal token to correlate
HTLCs, and retries were not supported, it was generated randomly by
calling the `KeysInterface`'s 32-byte random-fetching function.
This also provided a backwards-compatibility story as the existing
HTLC randomization key was re-used for older clients.

In 28eea12bbe0d78d256f79ec725cf02366dce4e36 `MppId` was renamed to
the current `PaymentId` which was then used expose the
`retry_payment` interface, allowing users to send new HTLCs which
are considered a part of an existing payment.

At no point has the payment-sending API seriously considered
idempotency, a major drawback which leaves the API unsafe in most
deployments. Luckily, there is a simple solution - because the
`PaymentId` must be unique, and because payment information for a
given payment is held for several blocks after a payment
completes/fails, it represents an obvious idempotency token.

Here we simply require the user provide the `PaymentId` directly in
`send_payment`, allowing them to use whatever token they may
already have for a payment's idempotency token.

Merge pull request #1791 from valentinewallace/2022-10-we-are-intro-node

Onion messages: fix edge case where we are the intro node

Prune channels if *either* not updated

Non-mandatory "fix" enabling future tests

Merge pull request #1815 from TheBlueMatt/2022-10-dead-gossip-code

Require directional updates for a DirectionalChannelInfo

Merge pull request #1818 from TheBlueMatt/2022-10-stable-bench

Use rustc stable for benchmark CI run to fix current breakage

Use rustc stable for benchmark CI run to fix current breakage

OMs: fix panic sending to a two-hop blinded route where we are the intro node

Onion messages: fix edge case where we are the introduction node

If we're sending straight to a blinded route with no unblinded intermediate
hops, and we are the introduction node, we need to advance the blinded route by
one hop so that the second hop is the new introduction node.

Make `htlc_maximum_msat` in `EffectiveCapacity` non-`Option`al

Because we now never generate an `EffectiveCapacity` with an
`htlc_maximum_msat` set to `None`, making it non-`Option`al
effectively removes dead code, which we do here.

Require directional updates for a `DirectionalChannelInfo`

We currently construct `DirectedChannelInfo`s for routing before
checking if the given direction has its directional info filled in.
We then always check for directional info before actually deciding
to route over a channel, as otherwise we assume the channel is not
online.

This makes for somewhat redundant checks, and `DirectedCHannelInfo`
isn't, by itself, a very useful API. Because fetching the HTLC-max
or effective channel capacity gives spurious data if no directional
info is available, there's little reason to have that data
available, and so we here check for directional info first. This
effectively merges `DirectionalChannelInfo` and
`DirectionalChannelInfoWithUpdate`.

Remove unused payment_hash param from Router::find_route

This helps prepare for moving the Router trait into ChannelManager, which will
help allow ChannelManager to retrieve routes for trampoline

Fix inaccurate comment in InvoicePayer

Merge pull request #1809 from valentinewallace/2022-10-custom-om-self

Give us a self when reading a custom onion message

Give us a self when reading a custom onion message

+ remove MaybeReadableArgs trait as it is now unused
+ remove onion_utils::DecodeInput as it would've now needed to be parameterized
by the CustomOnionMessageHandler trait, and we'd like to avoid either
implementing DecodeInput in messenger or having onion_utils depend on
onion_message::*

Co-authored-by: Matt Corallo <git@bluematt.me>
Co-authored-by: Valentine Wallace <vwallace@protonmail.com>

Merge pull request #1805 from TheBlueMatt/2022-10-remote-useless-mut

Drop useless `mut` in `KeysInterface::sign_holder_anchor_input`

Merge pull request #1807 from TheBlueMatt/2022-10-errorkind-bindings

Export io::ErrorKind in bindings

Export io::ErrorKind in bindings

The bindings have exported `io::Error` as, basically,
`io::ErrorKind`, for quite some time, so there's little reason to
not just export `io::ErrorKind` as well.

Drop useless `mut` in `KeysInterface::sign_holder_anchor_input`

The `Transaction` is not modified so there's no reason to make the
reference `mut`

Merge pull request #1797 from arik-so/2022-10-channel-manager-deparameterization

Deparametrize `ChannelManager` to infer `Signer` from its `KeysInterface`.

Merge pull request #1802 from TheBlueMatt/2022-10-112

Add release date and release name to CHANGELOG for 0.0.112

Refer to `lnd` as `LND` in CHANGELOG

for consistency since its an abbreviation for "lightning network
daemon".

Add release date and release name to CHANGELOG for 0.0.112

Merge pull request #1798 from TheBlueMatt/2022-10-112

Cut 0.0.112

Deparametrize `ChannelManager` to infer `Signer` from its `KeysInterface`.

Add release notes for 0.0.112

Remove outdated allow(unused)

Bump crate versions to 0.0.112/invoice 0.20

Do not export new anchors structs in `events.rs` without anchors

This avoids adding unused, effectively-dummy public structs in
`events.rs`.

Merge pull request #1779 from valentinewallace/2022-10-node-pk-keysinterface

Add `KeysInterface::get_node_id` method

KeysInterface docs: note that Recipient type must be supported by impl

Merge pull request #1780 from wpaulino/rust-edition-2018

Bump workspace to rust edition 2018

Mostly motivated by the need of async/await.

Add KeysInterface::get_node_id method

Useful since we're working on getting rid of KeysInterface::get_node_secret to
complete support for remote signing.

Will be used in upcoming work to check whether an outbound onion message
blinded path has our node id as the introduction node id

Merge pull request #1770 from jkczyz/2022-10-debug-route-hints

Add logging in route hint filtering

Merge pull request #1788 from TheBlueMatt/2022-10-mtlc-writer

Add `WriteableScore` bindings impl for `MultiThreadedLockableScore`

Add `WriteableScore` bindings impl for `MultiThreadedLockableScore`

In 56b07e52aabdaca521987e765f1fa864966a5d49 we made
`MultiThreadedLockableScore` fully bindings-compatible. However, it
did not add a `WriteableScore` implementation for it. This was an
oversight as it is a `WriteableScore` in Rust and needs to be for
use in other parts of the API.

Here we add the required impl in a way that the bindings generator
is able to handle it and add conversion utilities.

Add logging in route hint filtering

Knowing why a channel was not included as an invoice route hint can be
valuable. Add logging on the decisions made when filtering channels.

Merge pull request #1748 from valentinewallace/2022-10-custom-oms

Support custom onion messages

Disallow sending invalid custom OM TLVs

Onion message data TLV types must be >= 64, enforce this on send

Implement sending and receiving custom onion messages

This uses the work done in the preceding commits to implement encoding a user's
custom TLV in outbound onion messages, and decoding custom TLVs in inbound
onion messages, to be provided to the new CustomOnionMessageHandler.

Merge pull request #1678 from TheBlueMatt/2022-08-funding-locked-mon-persist-fail

Handle async initial ChannelMonitor persistence failing on restart

Rename `ChannelState::MonitorUpdateFailed` `MonitorUpdateInProgress`

As we're moving towards monitor update async being a supported
use-case, we shouldn't call an async monitor update "failed", but
rather "in progress". This simply updates the internal channel.rs
enum name to reflect the new thinking.