Change `Event` `amt` fields to `amount_msat` for clarity

Add internal docs for ChannelMonitor::payment_preimages

Drop return value from `fail_htlc_backwards`, clarify docs

`ChannelManager::fail_htlc_backwards`' bool return value is quite
confusing - just because it returns false doesn't mean the payment
wasn't (already) failed. Worse, in some race cases around shutdown
where a payment was claimed before an unclean shutdown and then
retried on startup, `fail_htlc_backwards` could return true even
though (a duplicate copy of the same payment) was claimed, but the
claim event has not been seen by the user yet.

While its possible to use it correctly, its somewhat confusing to
have a return value at all, and definitely lends itself to misuse.

Instead, we should push users towards a model where they don't care
if `fail_htlc_backwards` succeeds - either they've locally marked
the payment as failed (prior to seeing any `PaymentReceived`
events) and will fail any attempts to pay it, or they have not and
the payment is still receivable until its timeout time is reached.

We can revisit this decision based on user feedback, but will need
to very carefully document the potential failure modes here if we
do.

Do additional pre-flight checks before claiming a payment

As additional sanity checks, before claiming a payment, we check
that we have the full amount available in `claimable_htlcs` that
the payment should be for. Concretely, this prevents one
somewhat-absurd edge case where a user may receive an MPP payment,
wait many *blocks* before claiming it, allowing us to fail the
pending HTLCs and the sender to retry some subset of the payment
before we go to claim. More generally, this is just good
belt-and-suspenders against any edge cases we may have missed.

Provide a redundant `Event::PaymentClaimed` on restart if needed

If we crashed during a payment claim and then detected a partial
claim on restart, we should ensure the user is aware that the
payment has been claimed. We do so here by using the new
partial-claim detection logic to create a `PaymentClaimed` event.

Add a `PaymentClaimed` event to indicate a payment was claimed

This replaces the return value of `claim_funds` with an event. It
does not yet change behavior in any material way.

Ensure all HTLCs for a claimed payment are claimed on startup

While the HTLC-claim process happens across all MPP parts under one
lock, this doesn't imply that they are claimed fully atomically on
disk. Ultimately, an application can crash after persisting one
`ChannelMonitorUpdate` out of multiple monitor updates needed for
the full claim.

Previously, this would leave us in a very bad state - because of
the all-channels-available check in `claim_funds` we'd refuse to
claim the payment again on restart (even though the
`PaymentReceived` event will be passed to the user again), and we'd
end up having partially claimed the payment!

The fix for the consistency part of this issue is pretty
straightforward - just check for this condition on startup and
complete the claim across all channels/`ChannelMonitor`s if we
detect it.

This still leaves us in a confused state from the perspective of
the user, however - we've actually claimed a payment but when they
call `claim_funds` we return `false` indicating it could not be
claimed.

Store an `events::PaymentPurpose` with each claimable payment

In fc77c57c3c6e165d26cb5c1f5d1afee0ecd02589 we stopped using the
`FInalOnionHopData` in `OnionPayload::Invoice` directly and intend
to remove it eventually. However, in the next few commits we need
access to the payment secret when claimaing a payment, as we create
a new `PaymentPurpose` during the claim process for a new event.

In order to get access to a `PaymentPurpose` without having access
to the `FinalOnionHopData` we here change the storage of
`claimable_htlcs` to store a single `PaymentPurpose` explicitly
with each set of claimable HTLCs.

Enable removal of `OnionPayload::Invoice::_legacy_hop_data` later

In fc77c57c3c6e165d26cb5c1f5d1afee0ecd02589 we stopped using the
`FinalOnionHopData` in `OnionPayload::Invoice` directly and renamed
it `_legacy_hop_data` with the intent of removing it in a few
versions. However, we continue to check that it was included in the
serialized data, meaning we would not be able to remove it without
breaking ability to serialize full `ChannelManager`s.

This fixes that by making the `_legacy_hop_data` an `Option` which
we will happily handle just fine if its `None`.

Merge pull request #1476 from tnull/2022-05-maximum-path-length

Consider maximum path length during path finding.

Consider maximum path length during path finding.

Merge pull request #1472 from TheBlueMatt/2022-06-less-secp-ctx

Pull secp256k1 contexts from per-peer to per-PeerManager

Merge pull request #1418 from bruteforcecat/timeout-outbound-paymnet-retires-instead-of-count-out

add timeout retry strategy to outbound payment

add timeout retry strategy to outbound payment

Merge pull request #1485 from ViktorTigerstrom/2022-05-add-force-close-param

Add missing `counterparty_node_id` in `force_close_channel` calls

Add missing `counterparty_node_id` in `force_close_channel` calls

Merge pull request #1479 from ViktorTigerstrom/2022-05-pass-counterparty-id-to-functions

Pass `counterparty_node_id` to `ChannelManager` functions

Merge pull request #1475 from atalw/2022-04-paymentforwarded-event

Expose `next_channel_id` in `PaymentForwarded` event

Add `next_channel_id` in `PaymentForwarded` event

This update also includes a minor refactor. The return type of
`pending_monitor_events` has been changed to a `Vec` tuple with the
`OutPoint` type. This associates a `Vec` of `MonitorEvent`s with a
funding outpoint.

We've also renamed `source/sink_channel_id` to `prev/next_channel_id` in
the favour of clarity.

Merge pull request #1429 from TheBlueMatt/2022-04-drop-no-conn-possible

Update `OpenChannelRequest` documentation

As the `counterparty_node_id` is now required to be passed back to the
`ChannelManager` to accept or reject an inbound channel request, the
documentation is updated to reflect that.

Pass `counterparty_node_id` to `accept_inbound_channel`

Pass `counterparty_node_id` to `funding_transaction_generated`

Pass `counterparty_node_id` to `force_close_channel`

Pass `counterparty_node_id` to `close_channel` functions

move Time trait from scoring mod to util::time and set it visibile within crate

Add `counterparty_node_id` to `FundingGenerationReady`

Merge pull request #1480 from tnull/2022-05-fix-test-warnings

Fix unused code warnings test.

Fix unused code warnings.

Pull secp256k1 contexts from per-peer to per-PeerManager

Instead of including a `Secp256k1` context per
`PeerChannelEncryptor`, which is relatively expensive memory-wise
and nontrivial CPU-wise to construct, we should keep one for all
peers and simply reuse it.

This is relatively trivial so we do so in this commit.

Since its trivial to do so, we also take this opportunity to
randomize the new PeerManager context.

Merge pull request #1023 from TheBlueMatt/2021-07-par-gossip-processing

Merge pull request #1477 from dunxen/2022-05-invoice-expiry-nits

Address post-ACK formatting nits from #1474

Add a few more simple tests of the PeerHandler

These increase coverage and caught previous lockorder inversions.

Add support for testing recvd messages in TestChannelMessageHandler

Require `PartialEq` for `wire::Message` in `cfg(test)`

...and implement wire::Type for `()` for `feature = "_test_utils"`.

Drop a needless match in favor of an `if let`

[net-tokio] Explicitly yield after processing messages from a peer

This reduces instances of disconnect peers after single timer
intervals somewhat, at least on Tokio 1.14.

Drop `PeerHolder` as it now only has one field

Keep the same read buffer unless the last message was overly large

This avoids repeatedly deallocating-allocating a Vec for the peer
read buffer after every message/header.

Create a simple `FairRwLock` to avoid readers starving writers

Because we handle messages (which can take some time, persisting
things to disk or validating cryptographic signatures) with the
top-level read lock, but require the top-level write lock to
connect new peers or handle disconnection, we are particularly
sensitive to writer starvation issues.

Rust's libstd RwLock does not provide any fairness guarantees,
using whatever the OS provides as-is. On Linux, pthreads defaults
to starving writers, which Rust's RwLock exposes to us (without
any configurability).

Here we work around that issue by blocking readers if there are
pending writers, optimizing for readable code over
perfectly-optimized blocking.

Wake reader future when we fail to flush socket buffer

This avoids any extra calls to `read_event` after a write fails to
flush the write buffer fully, as is required by the PeerManager
API (though it isn't critical).

Limit blocked PeerManager::process_events waiters to two

Only one instance of PeerManager::process_events can run at a time,
and each run always finishes all available work before returning.
Thus, having several threads blocked on the process_events lock
doesn't accomplish anything but blocking more threads.

Here we limit the number of blocked calls on process_events to two
- one processing events and one blocked at the top which will
process all available events after the first completes.

Avoid the peers write lock unless we need it in timer_tick_occurred

Similar to the previous commit, this avoids "blocking the world" on
every timer tick unless we need to disconnect peers.

Avoid taking the peers write lock during event processing

Because the peers write lock "blocks the world", and happens after
each read event, always taking the write lock has pretty severe
impacts on parallelism. Instead, here, we only take the global
write lock if we have to disconnect a peer.

[net-tokio] Call PeerManager::process_events without blocking reads

Unlike very ancient versions of lightning-net-tokio, this does not
rely on a single global process_events future, but instead has one
per connection. This could still cause significant contention, so
we'll ensure only two process_events calls can exist at once in
the next few commits.

Process messages with only the top-level read lock held

Users are required to only ever call `read_event` serially
per-peer, thus we actually don't need any locks while we're
processing messages - we can only be processing messages in one
thread per-peer.

That said, we do need to ensure that another thread doesn't
disconnect the peer we're processing messages for, as that could
result in a peer_disconencted call while we're processing a
message for the same peer - somewhat nonsensical.

This significantly improves parallelism especially during gossip
processing as it avoids waiting on the entire set of individual
peer locks to forward a gossip message while several other threads
are validating gossip messages with their individual peer locks
held.

Process messages from peers in parallel in `PeerManager`.

This adds the required locking to process messages from different
peers simultaneously in `PeerManager`. Note that channel messages
are still processed under a global lock in `ChannelManager`, and
most work is still processed under a global lock in gossip message
handling, but parallelizing message deserialization and message
decryption is somewhat helpful.

Merge pull request #1474 from dunxen/2022-05-actually-add-expiry

lightning-invoice/utils: Actually add expiry to invoices

Add expiry to non-phantom invoice utils

Actually add expiry to phantom invoice utils

Merge pull request #1465 from tnull/2022-05-encode-update-type-bytes

Encode & test `channel_update` message type in failure messages.

Merge pull request #1471 from ViktorTigerstrom/2022-05-test-disconnected-before-funding-broadcasted

Add test coverage for `ClosureReason::DisconnectedPeer`

Merge pull request #1467 from arik-so/fuzz_new_target_docs

Add documentation for creating new fuzz test targets.

Add test for `ClosureReason::DisconnectedPeer`

Add test that ensures that channels are closed with
`ClosureReason::DisconnectedPeer` if the peer disconnects before the
funding transaction has been broadcasted.

Encode channel update type in failure messages.

Merge pull request #1389 from lightning-signer/2022-03-bitcoin

Update bitcoin crate to 0.28.1

Add documentation for creating new fuzz test targets.

Improve ShutdownScript::new_witness_program

bitcoin crate 0.28.1

Merge pull request #1468 from johnpc/fix-contributing-typo

fix typos in CONTRIBUTING.md

fix typos in CONTRIBUTING.md

Merge pull request #1463 from TheBlueMatt/2022-05-lol-more-underflow

Reject outbound channels if the total reserve is larger than funding

Merge pull request #1449 from TheBlueMatt/2022-04-fix-remote_ip_race

[lightning-net-tokio] Fix race-y unwrap fetching peer socket address

Merge pull request #1430 from vincenzopalazzo/macros/channel_reestablish_v2

send warning when we receive a old commitment transaction

Merge pull request #1416 from jurvis/jurvis/persist-scorer

Add utils to persist scorer in BackgroundProcessor

send warning when we receive a old commitment transaction

During a `channel_reestablish` now we send a warning message when we receive a old commitment transaction from the peer.

In addition, this commit include the update of functional test to make sure that the receiver will generate warn messages.

Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>

Merge pull request #1461 from TheBlueMatt/2022-05-unconf-0-not-half

Force-close channels on reorg only if the funding is unconfirmed

Merge pull request #1444 from ViktorTigerstrom/2022-04-use-counterparty-htlc-max-for-chan-updates

Set `ChannelUpdate` `htlc_maximum_msat` using the peer's value

Set last_prune_call outside of persistence block

Add utils to persist scorer in BackgroundProcessor

move last_prune_call back

Add correct `ChannelUpdate` `htlc_maximum_msat` test

Set `ChannelUpdate` `htlc_maximum_msat` using the peer's value

Use the `counterparty_max_htlc_value_in_flight_msat` value, and not the
`holder_max_htlc_value_in_flight_msat` value when creating the
`htlc_maximum_msat` value for `ChannelUpdate` messages.

BOLT 7 specifies that the field MUST be less than or equal to
`max_htlc_value_in_flight_msat` received from the peer, which we
currently are not guaranteed to adhere to by using the holder value.

Add test for configurable in-flight limit

Make our in-flight limit percentage configurable

Add a config field
`ChannelHandshakeConfig::max_inbound_htlc_value_in_flight_percent_of_channel`
which sets the percentage of the channel value we cap the total value of
outstanding inbound HTLCs to.

This field can be set to a value between 1-100, where the value
corresponds to the percent of the channel value in whole percentages.

Note that:
* If configured to another value than the default value 10, any new
channels created with the non default value will cause versions of LDK
prior to 0.0.104 to refuse to read the `ChannelManager`.

* This caps the total value for inbound HTLCs in-flight only, and
there's currently no way to configure the cap for the total value of
outbound HTLCs in-flight.

* The requirements for your node being online to ensure the safety of
HTLC-encumbered funds are different from the non-HTLC-encumbered funds.
This makes this an important knob to restrict exposure to loss due to
being offline for too long. See
`ChannelHandshakeConfig::our_to_self_delay` and
`ChannelConfig::cltv_expiry_delta` for more information.

Default value: 10.
Minimum value: 1, any values less than 1 will be treated as 1 instead.
Maximum value: 100, any values larger than 100 will be treated as 100
instead.

Merge pull request #1452 from tnull/2022-04-honor-gossip-timestamp-filters

Initiate gossip sync only after receiving GossipTimestampFilter.

Tweak `test_unconf_chan` to test that we don't prematurely close

Merge pull request #1460 from TheBlueMatt/2022-04-liquidity-log

Provide a utility to log the ProbabilisticScorer's contents

Initiate sync only after receiving `GossipTimestampFilter`.

Reject outbound channels if the total reserve is larger than funding

In 2826af75a5761859dedcddc870de0753ae4ecde4 we fixed a fuzz crash
in which the total reserve values in a channel were greater than
the funding amount, checked when an incoming channel is accepted.

This, however, did not fix the same issue for outbound channels,
where a peer can accept a channel with a nonsense reserve value in
the `accept_channel` message. The `full_stack_target` fuzzer
eventually found its way into the same issue, which this resolves.

Thanks (again) to Chaincode Labs for providing the fuzzing
resources which found this bug!

Merge pull request #1447 from andozw/seana.20220422.avoid-storing-FinalOnionHopData

Avoid storing a full FinalOnionHopData in OnionPayload::Invoice

Provide a utility to log the ProbabilisticScorer's contents

I wrote this when debugging a user's scorer and figured it may be
useful upstream.

Avoid storing a full FinalOnionHopData in OnionPayload::Invoice

We only use it to check the amount when processing MPP parts, but
store the full object (including new payment metadata) in it.
Because we now store the amount in the parent structure, there is
no need for it at all in the `OnionPayload`. Sadly, for
serialization compatibility, we need it to continue to exist, at
least temporarily, but we can avoid populating the new fields in
that case.

Store total payment amount in ClaimableHTLC explicitly

...instead of accessing it via the `OnionPayload::Invoice` form.
This may be useful if we add MPP keysend support, but is directly
useful to allow us to drop `FinalOnionHopData` from `OnionPayload`.

Pass FinalOnionHopData to payment verify by reference, not clone

Add a test for socket connection races

Sadly this does not reproduce the issue fixed in the previous
commit.

Force-close channels on reorg only if the funding is unconfirmed

Currently, if a channel's funding is locked in and then later
reorg'd back to half of the channel's minimum-depth we will
immediately force-close the channel. However, this can happen at
the fork-point while processing a reorg, and generally reorgs do
not reduce the block height at all, making this a rather useless
endeavor.

Ideally we'd never auto-force-close channels at all due to a reorg,
instead simply marking it as inactive until the funding
transaction is re-confirmed (or allowing the user to attempt to
force-close or force-closing once we're confident we have
completed reorg processing if we're at risk of losing funds
already received in the channel).

Sadly, we currently do not support changing a channel's SCID and
updating our SCID maps, so we cannot yet remove the automated
force-close logic. Still, there is no reason to do it until a
funding transaction has been removed from the chain.

This implements that change - only force-closeing once a channel's
funding transaction has been reorg'd out (still potentially at a
reorg's fork point). This continues to imply a 1-confirmation
channel will always be force-closed after a reorg of the funding
transaction, and will imply a similar behavior with 0-conf
channels.

Merge pull request #1451 from TheBlueMatt/2022-04-moar-mpp-fail-test

Add test coverage for failure of inconsistent MPP parts

Merge pull request #1454 from TheBlueMatt/2022-04-fuzz-underflow

Reject channels if the total reserves are larger than the funding

Merge pull request #1425 from valentinewallace/2021-04-wumbo

Wumbo!

Correct error when a peer opens a channel with a huge push_msat

The calculation uses the reserve, so we should mention it in the
error we send to our peers.

Reject channels if the total reserves are larger than the funding

The `full_stack_target` fuzzer managed to find a subtraction
underflow in the new `Channel::get_htlc_maximum` function where we
subtract both sides' reserve values from the channel funding. Such
a channel is obviously completely useless, so we should reject it
during opening instead of integer-underflowing later.

Thanks to Chaincode Labs for providing the fuzzing resources which
found this bug!

Enable wumbo channels to be created

Also redefine MAX_FUNDING_SATOSHIS_NO_WUMBO to no longer be off-by-one.

config: add max_funding_satoshis to enforce for inbound channels

and a bonus grammar fix

Do not force-close channels when we cannot communicate with peers

In general, we should never be automatically force-closing our
users' channels unless there is some immediate risk of funds loss
(ie because of some HTLC(s) which are timing out soon). In any
other case, we should trust the user to be able to figure out what
is going on and close their channels manually instead of trying to
be overly clever and automate closures if we think the channel is
useless.

In this case, even if a peer has some required feature that does
not allow us to communicate with them, there is a strong
possibility that some LDK upgrade may allow us to in the future. In
the mean time, there is no reason to go on-chain unless the user
needs funds immediately. In such a case, the user should already
have logic to force-close channels with peers which are not
available for any reason.

Add test coverage for failure of inconsistent MPP parts

When we receive multiple HTLCs which claim to be a part of the same
MPP but which are inconsistent for some reason, we should fail the
inconsistent HTLCs but keep the first HTLCs up until the first
inconsistency.

This works, but it turns out there was no test coverage, so we add
some here.

Add a `get_route!()` macro for tests which only need a route

Merge pull request #1435 from TheBlueMatt/2022-04-1126-first-step

Consolidate Channel balance fetching into one fn returning struct

Some simple code motion to clean up how channel balances get
fetched.

Merge pull request #1405 from TheBlueMatt/2022-04-log-scoring

Log as channel liquidities are/not updated in ProbabilisticScorer