Clean up docs in `keysinterface.rs`

Merge pull request #1863 from TheBlueMatt/2022-11-holding-cell-batch-update

Lean on the holding cell when batch-forwarding/failing HTLCs

Merge pull request #1825 from wpaulino/anchors-bump-htlc-resolution-event

Introduce new BumpTransactionEvent variant HTLCResolution

Extend BaseSign with HTLC output signing support for external claims

Yield BumpHTLCResolution events

Expose HTLC transaction construction helpers

Rename set_equality within update_claims_view_from_matched_txn

Generate ClaimEvent for HolderHTLCOutput inputs from anchor channels

Introduce internal package ID to track pending claims

Now that our txids will no longer be stable for package claims that
require external funds to be allocated, we transition to a 32-byte array
identifier to remain compatible with them.

Support HolderHTLCOutput inputs from anchor channels

Specify amount units in HolderHTLCOutput

This is only a name change, there is no change in behavior.

Update HTLC transaction detection from revoked counterparty commitments

Previously, this method assumed that all HTLC transactions have 1 input
and 1 output, with the sole input having a witness of 5 elements. This
will no longer be the case for HTLC transactions on channels with
anchors outputs since additional inputs and outputs can be attached to
them to allow fee bumping.

Track HTLC resolving transaction to determine input index

Merge pull request #1895 from TheBlueMatt/2022-12-fix-missing-data

Fix some onion errors and assert their length is correct

Correctly handle any `UPDATE` errors to phandom invoices

If we try to send any onion error with the `UPDATE` flag in
response to a phantom receipt, we should always swap it for
something generic that doesn't require a `channel_update` in it.
Here we use `temporary_node_failure`.

Test provided by Valentine Wallace <vwallace@protonmail.com>

Replace `build_first_hop_failure_packet` with `HTLCFailReason`

This ensures we always hit our new debug assertions while building
failure packets in the immediately-fail pipeline while processing
an inbound HTLC.

Use `temporary_node_failure` for a phantom HTLC with bogus CLTV

When we receive a phantom HTLC with a bogus/modified CLTV, we
should fail back with `incorrect_cltv_expiry`, but that requires a
`channel_update`, which we cannot generate for a phantom HTLC which
has no corresponding channel. Thus, instead, we have to fall back
to `incorrect_cltv_expiry`.

Fixes #1879

Assert that all onion error messages are correct len in tests

When we're constructing an HTLCFailReason, we should check that we
set the data to at least the correct length for the given failure
code, which we do here.

Correctly include the `sha256_hash_of_onion` field in BADONION errs

The spec mandates that we copy the `sha256_hash_of_onion` field
from the `UpdateFailMalformedHTLC` message into the error message
we send back to the sender, however we simply ignored it. Here we
copy it into the message correctly.

Drop the stale `final_expiry_too_soon` error code

This replaces `final_expiry_too_soon` with
`incorrect_or_unknown_payment` as was done in
https://github.com/lightning/bolts/pull/608. Note that the
rationale for this (that it may expose whether you are the final
recipient for the payment or not) does not currently apply to us -
we don't apply different final CLTV values to different payments.
However, we might in the future, and this will make us slightly
more consistent with other nodes.

Encapsulate `HTLCFailReason` to not expose struct variants

Now that `HTLCFailReason` is opaque and in `onion_utils`, we should
encapsulate it so that `ChannelManager` can no longer directly
access its inner fields.

Move `HTLCFailReason` to `onion_utils`

Now that it's entirely abstracted, there's no reason for
`HTLCFailReason` to be in `channelmanager`, it's really an
onion-level abstraction.

Merge pull request #1902 from tnull/2022-12-payment-received-renaming-follow-up

Also rename variables referring to `PaymentClaimable`

Correct confusing docs on `Channel` methods

The methods return `Ok(())` always, they just happen to never
return in the case of a duplicate claim if debug assertions are
enabled.

Lean on the holding cell for commitments when updating fees

Like the previous commit, here we update the update_fee+commit
logic to simply push the fee update into the holding cell and then
use the standard holding-cell-freeing codepaths to actually send
the commitment update. This removes a substantial amount of code,
reducing redundant codepaths and keeping channel state machine
logic in channel.rs.

Free the holding cells during background timer ticks

We currently free the channel holding cells in
`get_and_clear_pending_msg_events`, blocking outbound messages
while we do so. This is fine, but may block the message pipeline
longer than we need to. In the next commit we'll push
timer-originating channel fee updates out through the holding cell
pipeline, leaning more on that freeing in the future.

Thus, to avoid a regression in message time, here we clear the
holding cell after processing all timer events. This also avoids
needing to change tests in the next commit.

Lean on the holding cell when batch-forwarding/failing HTLCs

When we batch HTLC updates, we currently do the explicit queueing
plus the commitment generation in the `ChannelManager`. This is a
bit strange as its ultimately really a `Channel` responsibility to
generate commitments at the correct time, with the abstraction
leaking into `ChannelManager` with the `send_htlc` and
`get_update_fail_htlc` method docs having clear comments about
how `send_commitment` MUST be called prior to calling other
`Channel` methods.

Luckily `Channel` already has an update queue - the holding cell.
Thus, we can trivially rewrite the batch update logic as inserting
the desired updates into the holding cell and then asking all
channels to clear their holding cells.

Merge pull request #1867 from wpaulino/remove-signer-persistence

Re-derive signers instead of persisting them

Rename variables referring to `PaymentClaimable`

Merge pull request #1857 from TheBlueMatt/2022-11-reload-htlc

Fail HTLCs which were removed from a channel but not persisted

Fail HTLCs which were removed from a channel but not persisted

When a channel is force-closed, if a `ChannelMonitor` update is
completed but a `ChannelManager` persist has not yet happened,
HTLCs which were removed in the latest (persisted) `ChannelMonitor`
update will not be failed even though they do not appear in the
commitment transaction which went on chain. This is because the
`ChannelManager` thinks the `ChannelMonitor` is responsible for
them (as it is stale), but the `ChannelMonitor` has no knowledge of
the HTLC at all (as it is not stale).

The fix for this is relatively simple - we need to check for this
specific case and fail back such HTLCs when deserializing a
`ChannelManager`

Avoid attempting to forward to a closed chan on stale-data reload

If, after forwarding a payment to our counterparty, we restart with
a ChannelMonitor update having been persisted, but the
corresponding ChannelManager update was not persisted, we'll still
have the forwarded HTLC in the `forward_htlcs` map on start. This
will cause us to generate a (spurious) `PendingHTLCsForwardable`
event. However, when we go to forward said HTLC, we'll notice the
channel has been closed and leave it up to the `ChannelMontior` to
finalize the HTLC.

This is all fine today - we won't lose any funds, we'll just
generate an excess forwardable event and then fail to forward.
However, in the future when we allow for forward-time channel
changes this could break. Thus, its worth adding tests for this
behavior today, and, while we're at it, removing the spurious
forwardable HTLCs event.

Expose the full set of outbound HTLCs from a `ChannelMonitor`

This expands the outbound-HTLC-listing support in `ChannelMonitor`
to include not only the set of outbound HTLCs which have not yet
been resolved but to also include the full set of HTLCs which the
`ChannelMonitor` is currently able to to or has already finalized.

This will be used in the next commit to fail-back HTLCs which were
removed from a channel in the ChannelMonitor but not in a Channel.
Using the existing `get_pending_outbound_htlcs` for this purpose is
subtly broken - if the channel is already closed, an HTLC fail may
have completed on chain and is no longer "pending" to the monitor,
but the fail event is still in the monitor waiting to be handed
back to the `ChannelMonitor` when polled.

Remove unnecessary byte_utils helpers

Now that to_be_bytes is available under our current MSRV of 1.41, we
can use it instead of our own version.

Drop Clone requirement from Sign

Now that we opt to always re-derive channel secrets whenever required,
we can drop the Clone requirement from Sign.

Avoid use of OnlyReadsKeysInterface

Since `ChannelMonitor`s will now re-derive signers rather than
persisting them, we can no longer use the OnlyReadsKeysInterface
concrete implementation.

Re-derive signers upon deserializing OnchainTxHandler

Similar to the previous commit, we introduce a new serialization version
that doesn't store a monitor's signer. Since the monitor already knows
of a channel's `channel_keys_id`, there's no need to store any new data
to re-derive all private key material for said channel.

Re-derive signers upon deserializing Channel

To do so, we introduce a new serialization version that doesn't store a
channel's signer, and instead stores its signer's `channel_keys_id`.
This is a unique identifier that can be provided to our `KeysInterface`
to re-derive all private key material for said channel.

We choose to not upgrade the minimum compatible serialization version
until a later time, which will also remove any signer serialization
logic on implementations of `KeysInterface` and `Sign`.

Rename KeysInterface ready_channel to provide_channel_parameters

Now that ready_channel is also called on startup upon deserializing
channels, we opt to rename it to a more indicative name.

We also derive `PartialEq` on ChannelTransactionParameters to allow
implementations to determine whether `provide_channel_parameters` calls
are idempotent after the channel parameters have already been provided.

Split KeysInterface::get_channel_signer into two

`get_channel_signer` previously had two different responsibilites:
generating unique `channel_keys_id` and using said ID to derive channel
keys. We decide to split it into two methods `generate_channel_keys_id`
and `derive_channel_signer`, such that we can use the latter to fulfill
our goal of re-deriving signers instead of persisting them. There's no
point in storing data that can be easily re-derived.

Merge pull request #1891 from tnull/2022-12-rename-payment-events

Rename `PaymentReceived` to `PaymentClaimable`

Update docs and add pending changelog

Merge pull request #1887 from TheBlueMatt/2022-11-definitely-valid

Remove cryptographically unreachable error conditions

Merge pull request #1893 from valentinewallace/2022-12-jit-forwards-followup

HTLC JIT channel interception followup + minor cleanups

Construct from-message `HTLCFailReason` via a constructor method

Fix `impl_writeable_tlv_based_enum` to not require `DecodeError`

`impl_writeable_tlv_based_enum` shouldn't be assuming that
`DecodeError` is in scope, which we address here.

Decode `HTLCFailReason`s in a util method on the enum

Encode HTLC failure packets in a util method on `HTLCFailReason`

Merge pull request #1880 from tcharding/11-29-move-lock-outside-loop

Do not lock while looping `htlcs_to_fail`

Rename `PaymentReceived` to `PaymentClaimable`

Rename APIError::RouteError to ::InvalidRoute

Soon we're going to need to return an error when ChannelManager is unable to
find a route, so we'll need a way to distinguish between that and the user
supplying an invalid route.

Fix weird import format in persist

HTLC intercept test: swap hardcoded value for const

Test for unknown HTLC intercept id error

Clean up HTLC intercept errors

ChannelUnavailable is a better fit for errors regarding unavailable channels
than APIMisuseError.

Also log bytes in errors as hex instead of decimal.

Merge pull request #1862 from valentinewallace/2022-11-chanman-retries-prep

Prepare for Payment Retries in `ChannelManager`

Do not lock while looping htlcs_to_fail

Currently we loop over `htlcs_to_fail` locking `channel_state` for each
element only to call `get_htlc_inbound_temp_fail_err_and_data` with the
same inputs on each iteration. This is unnecessary, we can refactor and
call `get_htlc_inbound_temp_fail_err_and_data` outside of the loop.

Make fail_htlc_backwards_internal borrow parameters

Currently `fail_htlc_backwards_internal` takes ownership of its source
and reason parameters however they are not consumed so we can borrow them.

Includes refactoring to use local variables before the function call.

Add constructors to HTLCFailReason

We create `HTLCFailReason` inline in function calls in a bunch of places
in the `channelmanager` module, we can make the code more terse with no
loss of clarity by implementing a couple of constructor methods.

Merge pull request #1835 from valentinewallace/2022-11-jit-chan-htlc-intercept

Intercept HTLC forwards for JIT channels

Remove unreachable `Err` cases when constructing `TxCreationKeys`

Remove unreachable `Err` cases on `derive_*_revocation_key`

The `derive_{public,private}_revocation_key` methods hash the two
input keys and then multiply the two input keys by hashed values
before adding them together. Because addition can fail if the tweak
is the inverse of the secret key this method currently returns a
`Result`.

However, it is not cryptographically possible to reach the error
case - in order to create an issue, the point-multiplied-by-hash
values must be the inverse of each other, however each point
commits the SHA-256 hash of both keys together. Thus, because
changing either key changes the hashes (and the ultimate points
added together) in an unpredictable way, there should be no way to
construct such points.

Remove unreachable `Err` cases on `derive_{public,private}_key`

The `derive_{public,private}_key` methods hash the two input keys
and then add them to the input public key. Because addition can
fail if the tweak is the inverse of the secret key this method
currently returns a `Result`.

However, it is not cryptographically possible to reach the error
case - in order to create an issue, the SHA-256 hash of the
`base_point` (and other data) must be the inverse of the
`base_point`('s secret key). Because changing the `base_point`
changes the hash in an unpredictable way, there should be no way to
construct such a `base_point`.

Move DefaultRouter to router module

Move ScorerAccountingForInFlightHtlcs to router + make public

We move it to router instead of scoring because it pairs with the InFlightHtlcs
struct in router and is useful for custom Router trait implementations

Merge pull request #1839 from ariard/2022-11-increase-visibility-helpers

Chan_utils helpers visibility relaxation

Don't forward HTLC intercepts over unestablished channels

Automatically fail intercepts back on timeout

Add config knob for forwarding intercept payments

Allow failing back intercepted HTLCs

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

Utils for forwarding intercepted htlcs + getting intercept scids

See ChannelManager::forward_intercepted_htlc and
ChannelManager::get_intercept_scid for details

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

Generate HTLCIntercepted event upon interceptable forward

And store the pending intercepted HTLC in pending_intercepted_htlcs

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

Add HTLCIntercepted event

Used in upcoming commit(s) so users can intercept forwarded HTLCs

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

Add fake scid namespace for intercepted HTLCs

This is useful for LSPs who wish to create a just-in-time channel for end users
receiving a lightning payment. These fake scids will be encoded into route
hints in end user invoices, and signal to LDK to create an event triggering the
JIT channel, after which the payment will be received.

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

Persist pending intercepted htlcs in ChannelManager

No htlcs are intercepted yet, that will be added in upcoming commit(s)

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

Merge pull request #1885 from TheBlueMatt/2022-11-dumb-lookup

Drop useless SCID lookup in `claim_funds_from_hop`

Drop unnecessary clone

Drop useless SCID lookup in `claim_funds_from_hop`

We have the channel_id available in `prev_hop` so there's no reason
to look it up by SCID.

Remove get_p2wpkh_redeemscript in favor of lib helper

Increase visibility of script helper

Increase visibility of protocol-level consts

Merge pull request #1856 from tnull/2022-10-expose-channel-id

Expose the channel via which we received a payment

Fix typo in ScorerAccountingForInFlightHtlcs

Move ScoringRouter methods to Router

This helps us prepare to move all payment retries into ChannelManager, which is
needed for trampoline payments.

Expose `confirmations` via `ChannelDetails`

We expose the current number of confirmations in `ChannelDetails`.

Expose the channel via which we received a payment

We expose the `channel_id` and `user_channel_id` via which we received a
payment in the `PaymentReceived` event.

Merge pull request #1766 from tee8z/event-node-received

adds node_id to Event::Payment{Received, Claimed}

Merge pull request #1874 from LeoDog896/patch-1

Small grammar fixes to README.md

adds 'receiver_node_id' to 'Event::Payment{Received,Claimed}'

Small grammar fixes to README.md

Merge pull request #1861 from TheBlueMatt/2022-11-tx-connection-idempotency

Ensure transactions_confirmed is idempotent

Add additional testing in `montior_tests` for chain idempotency

At the end of our `monitor_tests`, which test `ChannelMonitor`
`SpendableOutputs` and claimable `Balance`s, add new checks that
ensure that, if we're using the new
`ConnectStyle::HighlyRedundantTransactionsFirstSkippingBlocks`, we
can replay the full chain without getting redundant events or
`Balance`s.

Ensure `transactions_confirmed` is idempotent

In many complexity-reduced implementations of chain syncing using
esplora `transactions_confirmed` may be called redundantly for
transactions which were already confirmed. To ensure this is
idempotent we add two new `ConnectionStyle`s in our tests which
(a) call `transactions_confirmed` twice for each call, ensuring
simple idempotency is ensured and (b) call `transactions_confirmed`
once for each historical block every time we're connecting a new
block, ensuring we're fully idempotent even if every call is
repeated constantly.

In order to actually behave correctly this requires a simple
already-confirmed check in `ChannelMonitor`, which is included.

Merge pull request #1828 from lightning-signer/2022-11-non-zero-fee-anchors

Re-add support for non-zero-fee-anchors to chan_utils

Merge pull request #1866 from TheBlueMatt/2022-11-noisy-no-graph

Drop verbose log entries in BP when no network graph is provided

Drop verbose log entries in BP when no network graph is provided

If no network graph is provided to the `BackgroundProcessor`, we
log every time the processor loop goes around (at least every
100ms, if not more) which fille up logs with useless indications
that we have no network graph.

Re-add support for non-zero-fee-anchors to chan_utils and InMemorySigner

Merge pull request #1859 from TheBlueMatt/2022-11-rm-redundant-holding-cell-wipe

Wait to free the holding cell during channel_reestablish handling

Merge pull request #1772 from ViktorTigerstrom/2022-10-move-claimable-htlcs-to-seperate-lock

Move `claimable_htlcs` to separate lock

Don't hold `per_peer_state` lock during chain monitor update

For Windows build only, the
`TestPersister::chain_sync_monitor_persistences` lock has a lock order
before the `ChannelManager::per_peer_state` lock. This fix ensures that
the `per_peer_state` lock isn't held before the
`TestPersister::chain_sync_monitor_persistences` lock is acquired.