Track the amount spent on fees as payments are retried

Especially once we merge the `InvoicePayer` logic soon, we'll want
to expose the total fee paid in the `PaymentSent` event.

Pass the failing/succeeding `Path` to PendingOutboundPayment meths

This will make the next commit much simpler

Add a utility trait in `router` to get the fees along a given path

Merge pull request #1059 from jkczyz/2021-08-payment-retry

Payment Retries

Implement Payer and Router for lightning crate

Implements Payer for ChannelManager and Rotuer for find_route, which can
be used to parameterize InvoicePayer when needing payment retries.

Fail payment retry if Invoice is expired

According to BOLT 11:

- after the `timestamp` plus `expiry` has passed
  - SHOULD NOT attempt a payment

Add a convenience method for checking if an Invoice has expired, and use
it to short-circuit payment retries.

Support paying zero-value invoices

Add InvoicePayer for retrying failed payments

When a payment fails, it's useful to retry the payment once the network
graph and channel scores are updated. InvoicePayer is a utility for
making payments which will retry any failed payment paths for a payment
up to a configured number of total attempts. It is parameterized by a
Payer and Router for ease of customization and testing.

Implement EventHandler for InvoicePayer as a decorator that intercepts
PaymentPathFailed events and retries that payment using the parameters
from the event. It delegates to the decorated EventHandler after retries
have been exhausted and for other events.

Unify route finding methods

An upcoming Router interface will be used for finding a Route both when
initially sending a payment and also when retrying failed payment paths.
Unify the three varieties of get_route so the interface can consist of a
single method implemented by the new `find_route` method. Give get_route
pub(crate) visibility so it can still be used in tests.

Rewrite Invoice's interface in terms of msats

InvoiceBuilder's interface was changed recently to work in terms of
msats. Update Invoice's interface to return the amount in msats, too,
and make amount_pico_btc private.

Add PaymentId to PaymentPathFailed event

The PaymentId is needed when retrying payments. Include it in the
PaymentPathFailed event so it can be used in that manner.

Add PaymentId to PaymentSent event

The payment_hash may not uniquely identify the payment if it has been
reused. Include the payment_id in PaymentSent events so it can
correlated with the send_payment call.

Expose log_bytes! macro for use in other crates

Needed to log PaymentHash in the lightning-invoice crate when retrying
payments.

Merge pull request #1138 from TheBlueMatt/2021-10-payee-in-monitors

Store `Payee` info with HTLCs

Store `Payee` information in `HTLCSource::OutboundRoute`.

This stores and tracks HTLC payee information with HTLCSource info,
allowing us to provide it back to the user if the HTLC fails and
ensuring persistence by keeping it with the HTLC itself as it
passes between Channel and ChannelMonitor.

Copy `Payee` into `Route`s to provide them to `ChannelManager`

Make `Payee::pubkey` pub.

`Payee` is expected to be used by users to get routes for payment
retries, potentially with their own router. Thus, its helpful if it
is pub, even if it is redundant with the last hop in the `path`
field in `Events::PaymentPathFailed`.

Merge pull request #1134 from jkczyz/2021-10-payee-arg

Payee abstraction for use in get_route and PaymentPathFailed

Use option TLV decoding for short_channel_id

Using ignorable TLV decoding is only applicable for an Option containing
an enum, but short_channel_id is an Option<u64>. Use option TLV encoding
instead.

Include PaymentPathRetry data in PaymentPathFailed

When a payment path fails, it may be retried. Typically, this means
re-computing the route after updating the NetworkGraph and channel
scores in order to avoid the failing hop. The last hop in
PaymentPathFailed's path field contains the pubkey, amount, and CLTV
values needed to pass to get_route. However, it does not contain the
payee's features and route hints from the invoice.

Include the entire set of parameters in PaymentPathRetry and add it to
the PaymentPathFailed event. Add a get_retry_route wrapper around
get_route that takes PaymentPathRetry. This allows an EventHandler to
retry failed payment paths using the payee's route hints and features.

Remove outdated line from get_route docs

Define Payee abstraction for use in get_route

A payee can be identified by a pubkey and optionally have an associated
set of invoice features and route hints. Use this in get_route instead
of three separate parameters. This may be included in PaymentPathFailed
later to use when finding a new route.

Merge pull request #1104 from TheBlueMatt/2021-10-payment-id-in-monitors

Reload pending outbound payments from ChannelMonitors on startup

Add a test of an HTLC being fulfilled and then later failed

Peers probably shouldn't do this, but if they want to give us free
money, we should take it and not generate any spurious events.

Move test_dup_htlc_onchain_fails_on_reload to payment_tests

test_dup_htlc_onchain_fails_on_reload is now more of a
payment_test than a functional_test, testing for handling of
pending payments.

Add some basic test coverage of monitor payment data reloading

Reload pending payments from ChannelMonitor HTLC data on reload

If we go to send a payment, add the HTLC(s) to the channel(s),
commit the ChannelMonitor updates to disk, and then crash, we'll
come back up with no pending payments but HTLC(s) ready to be
claim/failed.

This makes it rather impractical to write a payment sender/retryer,
as you cannot guarantee atomicity - you cannot guarantee you'll
have retry data persisted even if the HTLC(s) are actually pending.

Because ChannelMonitors are *the* atomically-persisted data in LDK,
we lean on their current HTLC data to figure out what HTLC(s) are a
part of an outbound payment, rebuilding the pending payments list
on reload.

Add PaymentSecrets to HTLCSource::OutboundRoute objects

Rename payment object vars to refer to payments and not session IDs

Track payments after they resolve until all HTLCs are finalized

In the next commit, we will reload lost pending payments from
ChannelMonitors during restart. However, in order to avoid
re-adding pending payments which have already been fulfilled, we
must ensure that we do not fully remove pending payments until all
HTLCs for the payment have been fully removed from their
ChannelMonitors.

We do so here, introducing a new PendingOutboundPayment variant
called `Completed` which only tracks the set of pending HTLCs.

Inform ChannelManager when fulfilled HTLCs are finalized

When an HTLC has been failed, we track it up until the point there
exists no broadcastable commitment transaction which has the HTLC
present, at which point Channel returns the HTLCSource back to the
ChannelManager, which fails the HTLC backwards appropriately.

When an HTLC is fulfilled, however, we fulfill on the backwards path
immediately. This is great for claiming upstream HTLCs, but when we
want to track pending payments, we need to ensure we can check with
ChannelMonitor data to rebuild pending payments. In order to do so,
we need an event similar to the HTLC failure event, but for
fulfills instead.

Specifically, if we force-close a channel, we remove its off-chain
`Channel` object entirely, at which point, on reload, we may notice
HTLC(s) which are not present in our pending payments map (as they
may have received a payment preimage, but not fully committed to
it). Thus, we'd conclude we still have a retryable payment, which
is untrue.

This commit does so, informing the ChannelManager via a new return
element where appropriate of the HTLCSource corresponding to the
failed HTLC.

Implement `HashMap` read for `MaybeReadable` values

This allows us to read a `HashMap` that has values which may be
skipped if they are some backwards-compatibility type.

We also take this opportunity to fail deserialization if keys are
duplicated.

Make `Channel::monitor_updating_restored`'s return tuple a struct

This improves readability at the callsite and in the function.

Make `Channel::revoke_and_ack`'s return tuple a struct

This substantially improves readability at the callsite and in the
function.

Merge pull request #1108 from TheBlueMatt/2021-10-persist-mon-blocks

Persist ChannelMonitors after new blocks are connected

Clarify the contexts in which persist_new_channel may be called

Its somewhat confusing that `persist_new_channel` is called on
startup for an existing channel in common deployments, so we call
it out explicitly.

Always release `MonitorEvent`s to `ChannelManager` after 3 blocks

If we have a `ChannelMonitor` update from an on-chain event which
returns a `TemporaryFailure`, we block `MonitorEvent`s from that
`ChannelMonitor` until the update is persisted. This prevents
duplicate payment send events to the user after payments get
reloaded from monitors on restart.

However, if the event being avoided isn't going to generate a
PaymentSent, but instead result in us claiming an HTLC from an
upstream channel (ie the HTLC was forwarded), then the result of a
user delaying the event is that we delay getting our money, not a
duplicate event.

Because user persistence may take an arbitrary amount of time, we
need to bound the amount of time we can possibly wait to return
events, which we do here by bounding it to 3 blocks.

Thanks to Val for catching this in review.

Update test_dup_htlc_onchain_fails_on_reload for new persist API

ChannelMonitors now require that they be re-persisted before
MonitorEvents be provided to the ChannelManager, the exact thing
that test_dup_htlc_onchain_fails_on_reload was testing for when it
*didn't* happen. As such, test_dup_htlc_onchain_fails_on_reload is
now testing that we bahve correctly when the API guarantees are not
met, something we don't need to do.

Here, we adapt it to test the new API requirements through
ChainMonitor's calls to the Persist trait instead.

Persist `ChannelMonitor`s after new blocks are connected

This resolves several user complaints (and issues in the sample
node) where startup is substantially delayed as we're always
waiting for the chain data to sync.

Further, in an upcoming PR, we'll be reloading pending payments
from ChannelMonitors on restart, at which point we'll need the
change here which avoids handling events until after the user
has confirmed the `ChannelMonitor` has been persisted to disk.
It will avoid a race where we
 * send a payment/HTLC (persisting the monitor to disk with the
   HTLC pending),
 * force-close the channel, removing the channel entry from the
   ChannelManager entirely,
 * persist the ChannelManager,
 * connect a block which contains a fulfill of the HTLC, generating
   a claim event,
 * handle the claim event while the `ChannelMonitor` is being
   persisted,
 * persist the ChannelManager (before the CHannelMonitor is
   persisted fully),
 * restart, reloading the HTLC as a pending payment in the
   ChannelManager, which now has no references to it except from
   the ChannelMonitor which still has the pending HTLC,
 * replay the block connection, generating a duplicate PaymentSent
   event.

Use an opaque type to describe monitor updates in Persist

In the next commit, we'll be originating monitor updates both from
the ChainMonitor and from the ChannelManager, making simple
sequential update IDs impossible.

Further, the existing async monitor update API was somewhat hard to
work with - instead of being able to generate monitor_updated
callbacks whenever a persistence process finishes, you had to
ensure you only did so at least once all previous updates had also
been persisted.

Here we eat the complexity for the user by moving to an opaque
type for monitor updates, tracking which updates are in-flight for
the user and only generating monitor-persisted events once all
pending updates have been committed.

Move ChannelManager::monitor_updated to a MonitorEvent

In the next commit we'll need ChainMonitor to "see" when a monitor
persistence completes, which means `monitor_updated` needs to move
to `ChainMonitor`. The simplest way to then communicate that
information to `ChannelManager` is via `MonitorEvet`s, which seems
to line up ok, even if they're now constructed by multiple
different places.

Merge pull request #1133 from jkczyz/2021-10-expand-scorer

Include source and destination nodes in routing::Score

Add source and target nodes to routing::Score

Expand routing::Score::channel_penalty_msat to include the source and
target node ids of the channel. This allows scorers to avoid certain
nodes altogether if desired.

Simplify prefers_shorter_route_with_higher_fees

In order to make the scoring tests easier to read, only check the
relevant RouteHop fields. The remaining fields are tested elsewhere.
Expand the test to show the path used without scoring.

Move the two-AtomicUsize counter in peer_handler to a util struct

We also take this opportunity to drop byte_utils::le64_to_array, as
our MSRV now supports the native to_le_bytes() call.

Move MonitorEvent serialization to TLV-enum-upgradable from custom

Merge pull request #1127 from TheBlueMatt/2021-10-0.0.102

Cut 0.0.102

Bump crate versions to 0.0.102 and lightning-invoice 0.10

Add CHANGELOG entries for 0.0.102

Merge pull request #1121 from TheBlueMatt/2021-10-return-temp-id

Expose temporary channel ID and user channel ID pre-funding

Merge pull request #1124 from jkczyz/2021-10-default-channel-scoring

Add channel scoring to get_route

Rename create_channel param to user_channel_id to standardize it

Merge pull request #1123 from tnull/fix_video_url

Fixed 'Advancing Bitcoin' video URL.

Add channel scoring to get_route

Failed payments may be retried, but calling get_route may return a Route
with the same failing path. Add a routing::Score trait used to
parameterize get_route, which it calls to determine how much a channel
should be penalized in terms of msats willing to pay to avoid the
channel.

Also, add a Scorer struct that implements routing::Score with a constant
constant penalty. Subsequent changes will allow for more robust scoring
by feeding back payment path success and failure to the scorer via event
handling.

Fixed 'Advancing Bitcoin' video URL.

Merge pull request #1112 from TheBlueMatt/2021-10-mon-refactors

Hide internals of ChainMonitor behind getter

Use Persister to return errors in fuzzers not chain::Watch

Use Persister to return errors in tests not chain::Watch

As ChainMonitor will need to see those errors in a coming PR,
we need to return errors via Persister so that our ChainMonitor
chain::Watch implementation sees them.

Handle Persister returning TemporaryFailure for new channels

Previously, if a Persister returned a TemporaryFailure error when
we tried to persist a new channel, the ChainMonitor wouldn't track
the new ChannelMonitor at all, generating a PermanentFailure later
when the updating is restored.

This fixes that by correctly storing the ChannelMonitor on
TemporaryFailures, allowing later update restoration to happen
normally.

This is (indirectly) tested in the next commit where we use
Persister to return all monitor-update errors.

Simplify channelmonitor tests which use chain::Watch and Persister

test_simple_monitor_permanent_update_fail and
test_simple_monitor_temporary_update_fail both have a mode where
they use either chain::Watch or persister to return errors.

As we won't be doing any returns directly from the chain::Watch
wrapper in a coming commit, the chain::Watch-return form of the
test will no longer make sense.

Make `ChainMonitor::monitors` private and expose monitor via getter

Exposing a `RwLock<HashMap<>>` directly was always a bit strange,
and in upcoming changes we'd like to change the internal
datastructure in `ChainMonitor`.

Further, the use of `RwLock` and `HashMap` meant we weren't able
to expose the ChannelMonitors themselves to users in bindings,
leaving a bindings/rust API gap.

Thus, we take this opportunity go expose ChannelMonitors directly
via a wrapper, hiding the internals of `ChainMonitor` behind
getters. We also update tests to use the new API.

Move ChannelMonitorUpdateErr to chain as it is a chain::Watch val

Move `Persist` trait to chainmonitor as that's the only reference

Merge pull request #1120 from jkczyz/2021-10-test-refactors

Pre-scoring test clean-ups

Move mpp_failure test to payment_tests.rs

Replace get_route with get_route_and_payment_hash

The interface for get_route will change to take a scorer. Using
get_route_and_payment_hash whenever possible allows for keeping the
scorer inside get_route_and_payment_hash rather than at every call site.

Replace get_route with get_route_and_payment_hash wherever possible.
Additionally, update get_route_and_payment_hash to use the known invoice
features and the sending node's logger.

Include the user channel id counter in Event::ChannelClosed

This makes it more practical for users to track channels using
their own IDs, especially across funding.

Return the temporary channel id in success from `create_channel`

This makes it more practical for users to track channels prior to
funding, especially if the channel fails because the peer rejects
it for a parameter mismatch.

Merge pull request #1115 from TheBlueMatt/2021-10-expose-addr-vec

Expose ReadOnlyNetworkGraph::get_addresses to C by cloning result

Fix unused variable warnings in fuzzer

Speed up test_timer_tick_called

Expose ReadOnlyNetworkGraph::get_addresses to C by cloning result

We cannot expose ReadOnlyNetworkGraph::get_addresses as is in C as
it returns a list of references to an enum, which the bindings
dont support. Instead, we simply clone the result so that it
doesn't contain references.

Merge pull request #1077 from jkczyz/2021-09-failing-route-hop

Include short channel id in PaymentPathFailed

Add failing short channel id to PaymentPathFailed

This will be useful for scoring channels when a payment fails.

Merge pull request #1116 from TheBlueMatt/2021-10-test-local-chan-routing

Use local channel state when constructing routes in test macro  + Fix compile-warning

Fix loop label shadowing warning

Use local channel state when constructing routes in test macro

This is a bit more realistic and needed to route over non-public
channels.

Clean up fee_insufficient computation

Merge pull request #1098 from 1nF0rmed/2021-09-adds-discard-funding-event

Add Event::DiscardFunding generation

Adds DiscardFunding event

During the event of a channel close, if the funding transaction
is yet to be broadcasted then a DiscardFunding event is issued
along with the ChannelClose event.

Merge pull request #1107 from dunxen/2021-10-swap-pubkey-for-bytearray

Replace PublicKey with [u8; 33] in NetworkGraph

Merge pull request #1062 from galderz/t_payment_hash_999

Replace PublicKey with [u8; 33] in NetworkGraph

Add payment_hash to PaymentSent #999

Merge pull request #1109 from TheBlueMatt/2021-10-init-fail-payment-retry-leak

Move pending payment tracking to after the new HTLC flies

Correct error returned when `retry_payment` doesn't have a payment

Move pending payment tracking to after the new HTLC flies

If we attempt to send a payment, but the HTLC cannot be send due to
local channel limits, we'll provide the user an error but end up
with an entry in our pending payment map. This will result in a
memory leak as we'll never reclaim the pending payment map entry.

Pass hop index in construct_onion_keys_callback

This simplifies failing route hop calculation, which will be useful for
later identifying the failing hop for PaymentFailed events.

Remove special case for onion error expiry_too_far

With channel scoring and payment retries, it is no longer necessary to
have expiry_too_far imply a payment failure.

Merge pull request #1079 from TheBlueMatt/2021-09-stale-docs

Update Event::PaymentReceived docs since we require payment secret

Update Event::PaymentReceived docs since we require payment secret

Users no longer need to verify the amounts of received payments as
the payment secret will protect us against the probing attacks such
verification was intended to fix.

Move tests of payment retries into a new module

Merge pull request #1100 from TheBlueMatt/2021-09-multihop-route-hint-fix

Consider many first-hop paths to the same counterparty in routing

Merge pull request #1096 from valentinewallace/2021-09-mpp-retries

Expire outbound payments after 3 blocks if no parts are pending

Don't remove failed payments when all paths fail

This is because we want the ability to retry completely failed
payments.

Upcoming commits will remove these payments on timeout to prevent
DoS issues

Also test that this removal allows retrying single-path payments

Add method to retry payments

Merge pull request #1080 from valentinewallace/2021-09-dup-chan-outpoint

Fix fuzzer-found panic from duplicate channel outpoint

f readability improvements from val

Merge pull request #1076 from TheBlueMatt/2021-09-forwardable-regen