Expose an event when a payment has failed and retries complete

When a payment fails, a payer needs to know when they can consider
a payment as fully-failed, and when only some of the HTLCs in the
payment have failed. This isn't possible with the current event
scheme, as discovered recently and as described in the previous
commit.

This adds a new event which describes when a payment is fully and
irrevocably failed, generating it only after the payment has
expired or been marked as expired with
`ChannelManager::mark_retries_exceeded` *and* all HTLCs for it
have failed. With this, a payer can more simply deduce when a
payment has failed and use that to remove payment state or
finalize a payment failure.

Add a variant to `PendingOutboundPayment` for retries-exceeded

When a payer gives up trying to retry a payment, they don't know
for sure what the current state of the event queue is.
Specifically, they cannot be sure that there are not multiple
additional `PaymentPathFailed` or even `PaymentSuccess` events
pending which they will see later. Thus, they have a very hard
time identifying whether a payment has truly failed (and informing
the UI of that fact) or if it is still pending. See [1] for more
information.

In order to avoid this mess, we will resolve it here by having the
payer give `ChannelManager` a bit more information - when they
have given up on a payment - and using that to generate a
`PaymentFailed` event when all paths have failed.

This commit adds the neccessary storage and changes for the new
state inside `ChannelManager` and a public method to mark a payment
as failed, the next few commits will add the new `Event` and use
the new features in our `PaymentRetrier`.

[1] https://github.com/lightningdevkit/rust-lightning/issues/1164

DRY up payment failure macros in functional_test_utils

... with a more extensible expectation-checking framework for them.

Merge pull request #1201 from jkczyz/2021-12-idempotent-channelmanager

Ensure ChannelManager methods are idempotent

Ensure ChannelManager methods are idempotent

During event handling, ChannelManager methods may need to be called as
indicated in the Event documentation. Ensure that these calls are
idempotent for the same event rather than panicking. This allows users
to persist events for later handling without needing to worry about
processing the same event twice (e.g., if ChannelManager is not
persisted but the events were, the restarted ChannelManager would return
some of the same events).

Merge pull request #1204 from TheBlueMatt/2021-12-no-torv2

Remove OnionV2 parsing support

Merge pull request #1130 from TheBlueMatt/2021-10-mon-fail-after-conf

Always return failure in update_monitor after funding spend

Add trivial test of monitor update failure during block connection

Add a test for MonitorEvent holding when they complete out-of-order

Add a simple test for ChainMonitor MonitorUpdate-holding behavior

Make APIError debug output more clear by including the variant

Drop `MonitorUpdateErr` in favor of opaque errors.

We don't expect users to ever change behavior based on the string
contained in a `MonitorUpdateErr`, except log it, so there's little
reason to not just log it ourselves and return a `()` for errors.

We do so here, simplifying the callsite in `ChainMonitor` as well.

Always return failure in `update_monitor` after funding spend

Previously, monitor updates were allowed freely even after a
funding-spend transaction confirmed. This would allow a race
condition where we could receive a payment (including the
counterparty revoking their broadcasted state!) and accept it
without recourse as long as the ChannelMonitor receives the block
first, the full commitment update dance occurs after the block is
connected, and before the ChannelManager receives the block.

Obviously this is an incredibly contrived race given the
counterparty would be risking their full channel balance for it,
but its worth fixing nonetheless as it makes the potential
ChannelMonitor states simpler to reason about.

The test in this commit also tests the behavior changed in the
previous commit.

Remove OnionV2 parsing support

OnionV2s don't (really) work on Tor anymore anyway, and the field
is set for removal in the BOLTs [1]. Sadly because of the way
addresses are parsed we have to continue to understand that type 3
addresses are 12 bytes long. Thus, for simplicity we keep the
`OnionV2` enum variant around and just make it an opaque 12 bytes,
with the documentation updated to note the deprecation.

[1] https://github.com/lightning/bolts/pull/940

Merge pull request #1197 from jkczyz/2021-11-score-successful-payment-path

Score successful payment paths

Fix shift overflow in Scorer::channel_penalty_msat

An unchecked shift of more than 64 bits on u64 values causes a shift
overflow panic. This may happen if a channel is penalized only once and
(1) is not successfully routed through and (2) after 64 or more half
life decays. Use a checked shift to prevent this from happening.

Decay channel failure penalty upon success

If a payment failed to route through a channel, a penalty is applied to
the channel in the future when finding a route. This penalty decays over
time. Immediately decay the penalty by one half life when a payment is
successfully routed through the channel.

Score successful payment paths

Expand the Score trait with a payment_path_successful function for
scoring successful payment paths. Called by InvoicePayer's EventHandler
implementation when processing PaymentPathSuccessful events. May be used
by Score implementations to revert any channel penalties that were
applied by calls to payment_path_failed.

Merge pull request #1196 from TheBlueMatt/2021-11-bad-rustdoc

Fix compilation in `payment` rustdoc examples

Fix compilation in `payment` rustdoc examples

The samples were not valid rust, but previous versions of rustc had
a bug where they were accepted anyway. Latest rustc beta no longer
accepts these.

Merge pull request #1195 from TheBlueMatt/2021-11-chanman-read-regression

Fix regression when reading `Event::PaymentReceived` in some cases

Fix regression when reading `Event::PaymentReceived` in some cases

For some reason rustc was deciding on a type for the `Option` being
deserialized for us as `_user_payment_id`. This really, really,
absolutely should have been a compile failure - the type (with
methods called on it!) was ambiguous! Instead, rustc seems to have
been defaulting to `Option<()>`, causing us to read zero of the
eight bytes in the `user_payment_id` field, which returns an
`Err(InvalidValue)` error as TLVs must always be read fully.

This should likely be reported to rustc as its definitely a bug,
but I cannot seem to cause the same error on any kinda of
vaguely-minimized version of the same code.

Found by `chanmon_consistency` fuzz target.

Merge pull request #1163 from TheBlueMatt/2021-11-support-insecure-counterparty

Explicitly support counterparty setting 0 channel reserve

Explicitly support counterparty setting 0 channel reserve

A peer providing a channel_reserve_satoshis of 0 (or less than our
dust limit) is insecure, but only for them. Because some LSPs do it
with some level of trust of the clients (for a substantial UX
improvement), we explicitly allow it. Because its unlikely to
happen often in normal testing, we test it explicitly here.

Merge pull request #1189 from TheBlueMatt/2021-11-trivial-impls

Derive `Clone` and friends on additional public structs

Implement Clone for InvalidShutdownScript

Users hopefully shouldn't have much of a reason to use this, but
the bindings may need it to ensure no leaking pointers over an ffi.

Implement Clone, Hash, PartialEq for ClosingTransaction

This is a public struct intended to be used as an object by users,
so it should likely have common implementations, given they're
trivial.

Continue after a single failure in `ChannelMonitor::update_monitor`

`ChannelMonitorUpdate`s may contain multiple updates, including, eg
a payment preimage after a commitment transaction update. While
such updates are generally not generated today, we shouldn't return
early out of the update loop, causing us to miss any updates after
an earlier update fails.

Prefer fully-specified paths in test macros

This avoids macros being context-specific use-dependent.

Allow missing-docs on test-only macros

Merge pull request #1184 from TheBlueMatt/2021-11-c-bindings-tweaks

C Bindings Compatibility Tweaks

Seal `scoring::Time` and only use `Instant` or `Eternity` publicly

`scoring::Time` exists in part to make testing the passage of time
in `Scorer` practical. To allow no-std users to provide a time
source it was exposed as a trait as well. However, it seems
somewhat unlikely that a no-std user is going to have a use for
providing their own time source (otherwise they wouldn't be a
no-std user), and likely they won't have a graph in memory either.

`scoring::Time` as currently written is also exceptionally hard to
write C bindings for - the C bindings trait mappings relies on the
ability to construct trait implementations at runtime with function
pointers (i.e. `dyn Trait`s). `scoring::Time`, on the other hand,
is a supertrait of `core::ops::Sub` which requires a `sub` method
which takes a type parameter and returns a type parameter. Both of
which aren't practical in bindings, especially given the
`Sub::Output` associated type is not bound by any trait bounds at
all (implying we cannot simply map the `sub` function to return an
opaque trait object).

Thus, for simplicity, we here simply seal `scoring::Time` and make
it effectively-private, ensuring the bindings don't need to bother
with it.

Make `Score : Writeable` in c_bindings and impl on `LockedScore`

Ultimately we likely need to wrap the locked `Score` in a struct
that exposes writeable somehow, but because all traits have to be
fully concretized for C bindings we'll still need `Writeable` on
all `Score` in order to expose `Writeable` on the locked score.
Otherwise, we'll only have a `LockedScore` with a `Score` visible
that only has the `Score` methods, never the original type.

Merge pull request #1186 from TheBlueMatt/2021-11-fix-log-select

Fix the `max_level_trace` feature

Test all log-limiting features in CI

Fix compilation with the max_level_trace feature

Store holder channel reserve and max-htlc-in-flight explicitly

Previously, `holder_selected_channel_reserve_satoshis` and
`holder_max_htlc_value_in_flight_msat` were constant functions
of the channel value satoshis. However, in the future we may allow
allow users to specify it. In order to do so, we'll need to track
them explicitly, including serializing them as appropriate.

We go ahead and do so here, in part as it will make testing
different counterparty-selected channel reserve values easier.

Merge pull request #1162 from TheBlueMatt/2021-11-fix-accept-chan-checks

Correct initial commitment tx fee affordability checks on open

Merge pull request #1178 from jkczyz/2021-11-payment-path-successful

Generate PaymentPathSuccessful event for each path

Merge pull request #1176 from lightning-signer/2021-11-htlc-anchors

Add anchors support for HTLCs

Generate PaymentPathSuccessful event for each path

A single PaymentSent event is generated when a payment is fulfilled.
This is occurs when the preimage is revealed on the first claimed HTLC.
For subsequent HTLCs, the event is not generated.

In order to score channels involved with a successful payments, the
scorer must be notified of each successful path involved in the payment.
Add a PaymentPathSuccessful event for this purpose. Generate it whenever
a part is removed from a pending outbound payment. This avoids duplicate
events when reconnecting to a peer.

Add test vectors for get_htlc_redeemscript wrt anchors

Adjust HTLC_{SUCCESS,TIMEOUT}_TX_WEIGHT when anchors used

Add anchor support to build_htlc_transaction

Increase visibility of anchor related methods

Add anchor support to commitment HTLC outputs

Support `logger::Record` in C by String-ing the fmt::Arguments

This adds a new (non-feature) cfg argument `c_bindings` which will
be set when building C bindings. With this, we can (slightly) tweak
behavior and API based on whether we are being built for Rust or C
users.

Ideally we'd never need this, but as long as we can keep the API
consistent-enough to avoid material code drift, this gives us a
cheap way of doing the "right" thing for both C and Rust when the
two are in tension.

We also move lightning-background-processor to support the same
MSRV as the main lightning crate, instead of only
lightning-net-tokio's MSRV.

Test fixed channel reserve checks on channel open

Correct initial commitment tx fee affordability checks on open

Previously, we would reject inbound channels if the funder wasn't
able to meet our channel reserve on their first commitment
transaction only if they also failed to push enough to us for us
to not meet their initial channel reserve as well.

There's not a lot of reason to care about us meeting their reserve,
however - its largely expected that they may not push enough to us
in the initial open to meet it, and its not actually our problem if
they don't.

Further, we used our own fee, instead of the channel's actual fee,
to calculate fee affordability of the initial commitment
transaction.

We resolve both issues here, rewriting the combined affordability
check conditionals in inbound channel open handling and adding a
fee affordability check for outbound channels as well.

The prior code may have allowed a counterparty to start the channel
with "no punishment" states - violating the reason for the reserve
threshold.

Rewrite test_update_fee_that_funder_cannot_afford to avoid magic

Instead of magic hard-coded constants, its better for tests to
derive the values used so that they change if constants are changed
and so that it is easier to re-derive constants in the future as
needed.

Make Channel::commit_tx_fee_msat static and take fee explicitly

This may avoid risk of bugs in the future as it requires the caller
to think about the fee being used, not just blindly use the current
(committed) channel feerate.

Merge pull request #1054 from ariard/2021-08-check-outbound-feerate

Check for outbound feerate update affordability before sending

Merge pull request #1168 from TheBlueMatt/2021-11-mpp-routing-fixes

Fix MPP routefinding when we first collect 95% of payment value

Check outbound update_fee affordance incremented with holding cell HTLCs

Fix MPP routefinding when we first collect 95% of payment value

See comment in new test for more details.

Merge pull request #1145 from tnull/add_gossip_log_level

Introduce GOSSIP log level to PeerHandler

Add a new log-level for gossip messages.

Merge pull request #1180 from valentinewallace/2021-11-remove-user-pmt-id

Remove user_payment_id

Merge pull request #1182 from TheBlueMatt/2021-11-fix-txid-log

Trivial Logging Fixes

Introduce CommitmentStats

Re-add `test_max_dust_htlc_exposure`

Ensure current channel state is logged for all channels on startup

Correct txid logging to reverse bytes.

We also take this opportunity to log the channel being closed when
one is closed by an on-chain spend of the funding output.

Merge pull request #1027 from TheBlueMatt/2021-07-check-dust

Check all outputs meet the dust threshold in `check_spends!()`

Check we won't overflow `max_dust_htlc_exposure_msat` at outbound feerate update

Remove user_payment_id

In upcoming commits, we'll be making the payment secret and payment hash/preimage
derivable from info about the payment + a node secret. This means we don't
need to store any info about incoming payments and can eventually get rid of the
channelmanager::pending_inbound_payments map.

Check all outputs meet the dust threshold in check_spends!()

Limit minimum output size to the dust limit when RBF-bumping

Cancel the outbound feerate update if above what we can afford

Introduce new helper commit_tx_fee_sat

Merge pull request #1173 from tnull/add_accept_inbound_channels_option

Add 'accept_inbound_channels' config option.

Add 'accept_inbound_channels' config option.

Merge pull request #1083 from TheBlueMatt/2021-09-funding-timeout

Automatically close channels that go unfunded for 2016 blocks

Merge pull request #1166 from TheBlueMatt/2021-11-chan-size-scoring

Automatically close channels that go unfunded for 2016 blocks

As recommended by BOLT 2 added in
https://github.com/lightningnetwork/lightning-rfc/pull/839

Return `ClosureReason` from `Channel` chain update methods

This fixes a few `ClosureReason`s and allows us to have
finer-grained user-visible errors when a channel closes due to an
on-chain event.

Move `Score` into a `scoring` module instead of a top-level module

Traits in top-level modules is somewhat confusing - generally
top-level modules are just organizational modules and don't contain
things themselves, instead placing traits and structs in
sub-modules. Further, its incredibly awkward to have a `scorer`
sub-module, but only have a single struct in it, with the relevant
trait it is the only implementation of somewhere else. Not having
`Score` in the `scorer` sub-module is further confusing because
it's the only module anywhere that references scoring at all.

Penalize large HTLCs relative to channels in default `Scorer`

Sending HTLCs which are any greater than a very small fraction of the
channel size tend to fail at a much higher rate. Thus, by default
we start applying a penalty at only 1/8th the channel size and
increase it linearly as the amount reaches the channel's capacity,
20 msat per 1024th of the channel capacity.

Provide `Score` the HTLC amount and channel capacity

This should allow `Score` implementations to make substantially
better decisions, including of the form "willing to pay X to avoid
routing over this channel which may have a high failure rate".

Merge pull request #1160 from jkczyz/2011-11-spontaneous-invoice-payer

Retries for spontaneous payments

Add PaymentHash parameter to Router::find_route

Implementations of Router may need the payment hash in order to look up
pre-computed routes from a probe for a given payment. Add a PaymentHash
parameter to Router::find_route to allow for this.

Test retrying payment on partial send failure

Add some test coverage for when InvoicePayer retries within pay_invoice
because the Payer returned a partial failure.

Replace expect_value_msat with expect_send

Modify all InvoicePayer unit tests to use expect_send instead of
expect_value_msat, since the former can discern whether the send was for
an invoice, spontaneous payment, or a retry. Updates tests to set payer
expectations if they weren't already and assert these before returning a
failure.

Support spontaneous payments in InvoicePayer

InvoicePayer handles retries not only when handling PaymentPathFailed
events but also for some types of PaymentSendFailure on the initial
send. Expand InvoicePayer's interface with a pay_pubkey function for
spontaneous (keysend) payments. Add a send_spontaneous_payment function
to the Payer trait to support this and implement it for ChannelManager.

Refactor InvoicePayer for spontaneous payments

To support spontaneous payments, InvoicePayer's sending logic must be
invoice-agnostic. Refactor InvoicePayer::pay_invoice_internal such that
invoice-specific code is in pay_invoice_using_amount and the remaining
logic is in pay_internal.

Further refactor the code's payment_cache locking such that it is
accessed consistently when needed, and tidy up the code a bit.

Merge pull request #1161 from TheBlueMatt/2021-11-fix-chan-type-ser

Correct Channel type serialization logic

Correct Channel type serialization logic

Currently, we write out the Channel's `ChannelTypeFeatures` as an
odd type, implying clients which don't understand the
`ChannelTypeFeatures` field can simply ignore it. This is obviously
nonsense if the channel type is some future version - the client
needs to fail to deserialize as it doesn't understand the channel's
type.

We adapt the serialization logic here to only write out the
`ChannelTypeFeatures` field if it is something other than
only-static-remote-key, and simply consider that "default" (as it
is the only supported type today). Then, we write out the channel
type as an even TLV, implying clients which do not understand it
must fail to read the `Channel`.

Note that we do not need to bother reserving the TLV type no longer
written as it never appeared in a release (merged post-0.0.103).

Merge pull request #1119 from TheBlueMatt/2021-10-less-aggressive-htlc-timeouts

Be less aggressive in outbound HTLC CLTV timeout checks

Be less aggressive in outbound HTLC CLTV timeout checks

We currently assume our counterparty is naive and misconfigured and
may force-close a channel to get an HTLC we just forwarded them.

There shouldn't be any reason to do this - we don't have any such
bug, and we shouldn't start by assuming our counterparties are
buggy. Worse, this results in refusing to forward payments today,
failing HTLCs for largely no reason.

Instead, we keep a fairly conservative check, but not one which
will fail HTLC forwarding spuriously - testing only that the HTLC
doesn't expire for a few blocks from now.

Fixes #1114.

Merge pull request #1131 from TheBlueMatt/2021-10-upstream-dust

Use upstream rust-bitcoin's dust calculation instead of our own

Use upstream rust-bitcoin's dust calculation instead of our own

Not only does this move to common code, but it fixes handling of
all output types except for a few trivial cases.

Merge pull request #1143 from TheBlueMatt/2021-10-no-payment-id-leaks

Fix a minor memory leak on PermanentFailure mon errs when sending

Merge pull request #1165 from lightning-signer/2021-11-fix-anchors

Fix countersignatory (to_remote) output redeemscript when anchors enabled

Renamed script_for_p2wpkh to get_p2wpkh_redeemscript to match convention

Fix to_remote output redeemscript when anchors enabled

Fix a minor memory leak on PermanentFailure mon errs when sending

If we send a payment and fail to update the first-hop channel state
with a `PermanentFailure` ChannelMonitorUpdateErr, we would have an
entry in our pending payments map, but possibly not return the
PaymentId back to the user to retry the payment, leading to a (rare
and relatively minor) memory leak.

Merge pull request #1105 from TheBlueMatt/2021-10-log-persist-time

Log before+after ChannelMonitor/Manager updates for visibility

Log before+after ChannelMonitor/Manager updates for visibility

I realized on my own node that I don't have any visibility into how
long a monitor or manager persistence call takes, potentially
blocking other operations. This makes it much more clear by adding
a relevant log_trace!() print immediately before and immediately
after persistence.

Merge pull request #1158 from jkczyz/2021-11-scorer-tests

Scorer unit tests

Add unit tests for Scorer

Test basic and channel failure penalties, including after a
(de-)serialization round trip.