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 #1893 from valentinewallace/2022-12-jit-forwards-followup

HTLC JIT channel interception followup + minor cleanups

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

Do not lock while looping `htlcs_to_fail`

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

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.

Lock pending inbound and outbound payments to before `channel_state`

As the `channel_state` lock will be removed, we prepare for that by
flipping the lock order for `pending_inbound_payments` and
`pending_outbound_payments` locks to before the `channel_state` lock.

Move `claimable_htlcs` to separate lock

Merge pull request #1830 from jurvis/jurvis/2022-10-calculate-inflight-with-chanmanager

Calculate `InFlightHtlcs` based on information in `ChannelManager`

Remove the `post_handle_chan_restoration` macro

Now that `handle_channel_resumption` can't fail, the error handling
in `post_handle_chan_restoration` is now dead code. Removing it
makes `post_handle_chan_restoration` only a single block, so here
we simply remove the macro and inline the single block into the two
places the macro was used.

Remove pub visibility of InFlightHtlcs HashMap

Add functional test for inflight HTLC tracking with ChanManager

Remove `paths` from `PaymentInfo` in `payment_cache`

In c70bd1f, we implemented tracking HTLCs by adding path information
for pending HTLCs to `InvoicePayer`’s `payment_cache` when receiving
specific events.

Since we can now track inflight HTLCs entirely within ChannelManager,
there is no longer a need for this to exist.

Compute InflightHtlcs from available information in ChannelManager

Merge pull request #1846 from TheBlueMatt/2022-11-more-robust-unconfirmed

Handle `transaction_unconfirmed` as a full reorg to the tx height

Explicitly track the set of spendable transactions which confirm

In `ChannelMonitor`s, when a transaction containing a spend of a
revoked remote output reaches 6 confs, we may have no other
tracking of that txid remaining. Thus, if we see that transaction
again (because a user duplicatively confirms it), we'll generate a
redundant spendable output event for it.

Here we simply explicitly track all txids of transactions which
confirm with a spendable output, allowing us to check this
condition in the next commit.

Merge pull request #1852 from TheBlueMatt/2022-11-accept-bad-but-better-fee-updates

Accept feerate increases even if they aren't high enough for us

Handle `transaction_unconfirmed` as a full reorg to the tx height

In `ChannelMonitor`, if we see a `transaction_unconfirmed` for a
transaction we last saw in a block at height X, we shouldn't
*only* remove the `onchain_events_awaiting_threshold_conf` entry
for the given tx but rather for all transactions that we last saw
at height >= X.

This avoids any potential `onchain_events_awaiting_threshold_conf`
inconsistencies due to the order in whcih users mark transactions
unconfirmed (which the `chain::Confirm` docs do not currently set
any requirements on).

This also matches the `OnchainTxHandler` behavior, which does the
same lookup.

Merge pull request #1726 from jkczyz/2022-09-offer-parsing

BOLT 12 offer parsing

Fix one test still connecting invalid blocks

In the next commit we'll add some checks that redundant
transactions aren't confirmed in different blocks, which would
cause test_htlc_ignore_latest_remote_commitment to fail. Here we
fix it to avoid the issue.

Expose the default Quantity::one as pub

Limit TLV stream decoding to type ranges

BOLT 12 messages are limited to a range of TLV record types. Refactor
decode_tlv_stream into a decode_tlv_stream_range macro for limiting
which types are parsed. Requires a SeekReadable trait for rewinding when
a type outside of the range is seen. This allows for composing TLV
streams of different ranges.

Updates offer parsing accordingly and adds a test demonstrating failure
if a type outside of the range is included.

Offer parsing tests

Test semantic errors when parsing offer bytes.

Use SemanticError in OfferBuilder::build

Offer parsing from bech32 strings

Add common bech32 parsing for BOLT 12 messages. The encoding is similar
to bech32 only without a checksum and with support for continuing
messages across multiple parts.

Messages implementing Bech32Encode are parsed into a TLV stream, which
is converted to the desired message content while performing semantic
checks. Checking after conversion allows for more elaborate checks of
data composed of multiple TLV records and for more meaningful error
messages.

The parsed bytes are also saved to allow creating messages with mirrored
data, even if TLV records are unknown.

Convert the `handle_chan_restoration_locked` macro to a function

There is no reason anymore for `handle_chan_restoration_locked` to
be a macro, and our long-term desire is to move away from macros as
they substantially bloat our compilation time (and binary size).
Thus, we simply remove `handle_chan_restoration_locked` here and
turn it into a function.

Wait to free the holding cell during channel_reestablish handling

When we process a `channel_reestablish` message we free the HTLC
update holding cell as things may have changed while we were
disconnected. However, some time ago, to handle freeing from the
holding cell when a monitor update completes, we added a holding
cell freeing check in `get_and_clear_pending_msg_events`. This
leaves the in-`channel_reestablish` holding cell clear redundant,
as doing it immediately or is `get_and_clear_pending_msg_events` is
not a user-visible difference.

Thus, we remove the redundant code here, substantially simplifying
`handle_chan_restoration_locked` while we're at it.

Remove log assertions in `chanmon_update_fail_tests`

Asserting that specific log entries were printed isn't all that
useful, we should really be focusing on the expected messages (or,
when a monitor udpate fails, the lack thereof). In the next commit
one of these log checks would otherwise break due to the particular
time a monitor update fails changing, but I also plan on reworking
the montior update flows substantially soon, breaking lots of them.

Unparameterize HashMap from InFlightHtlcs initializer

Merge pull request #1855 from tnull/2022-11-inbound-user-channel-id-randomization-fixup

Inbound `user_channel_id` randomization follow-up

Remove unused import

Mention `user_channel_id` rand. version req.

As it was previously omitted, we clarify here starting from which version users can expect the `user_channel_id` to be randomized for inbound channels.

Also set `user_channel_id` when its overridden

Merge pull request #1826 from TheBlueMatt/2022-10-idempotency-err

Add a separate PaymentSendFailure for idempotency violation

Merge pull request #1853 from TheBlueMatt/2022-11-reload-macro

Replace manual node reloading with a macro/function in tests

Merge pull request #1851 from TheBlueMatt/2022-11-fix-broken-futures-----again

Unset the needs-notify bit in a Notifier when a Future is fetched

Accept feerate increases even if they aren't high enough for us

LND nodes have very broken fee estimators, causing them to suggest
feerates that don't even meet a current mempool minimum feerate
when fees go up over the course of hours. This can cause us to
reject their feerate estimates as they're not high enough, even
though their new feerate is higher than what we had already (which
is the feerate we'll use to broadcast a closing transaction). This
implies we force-close the channel and broadcast something with a
feerate lower than our counterparty was offering.

Here we simply accept such feerates as they are better than what we
had. We really should also close the channel, but only after we
get their signature on the new feerate. That should happen by
checking channel feerates every time we see a new block so is
orthogonal to this code.

Ultimately the fix is anchor outputs plus package-based relay in
Bitcoin Core, however we're still quite some ways from that, so
worth needlessly closing channels for now.

Await `Future::poll` `Complete`d before unsetting notify-required

When we mark a future as complete, if the user is using the
`std::future::Future` impl to get notified, we shouldn't just
assume we have completed the `Future` when we call the `Waker`. A
`Future` may have been `drop`'d at that point (or may not be
`poll`'d again) even though we wake the `Waker`.

Because we now have a `callbacks_made` flag, we can fix this rather
trivially, simply not setting the flag until the `Future` is
`poll`'d `Complete`.

Wipe `Notifier` `FutureState` when returning from a waiter.

When we return from one of the wait functions in `Notifier`, we
should also ensure that the next `Future` doesn't start in the
`complete` state, as we have already notified the user, as far as
we're concerned.

This is technically a regression from the previous commit, but as
it is a logically separate change it is in its own commit.

Unset the needs-notify bit in a Notifier when a Future is fetched

If a `Notifier` gets `notify()`ed and the a `Future` is fetched,
even though the `Future` is marked completed from the start and
the user may pass callbacks which are called, we'll never wipe the
needs-notify bit in the `Notifier`.

The solution is to keep track of the `FutureState` in the returned
`Future` even though its `complete` from the start, adding a new
flag in the `FutureState` which indicates callbacks have been made
and checking that flag when waiting or returning a second `Future`.

Remove excess module

This appears to have been added with the intent of having a sealed
trait, which was never committed.

Move restart-related tests to their own file

Replace manual node reloading with a macro/function in tests

Fixes #1696

Merge pull request #1790 from tnull/2022-10-inbound-user-channel-id-randomization

Randomize `user_channel_id` for inbound channels

Make `user_channel_id` a `u128`

We increase the `user_channel_id` type from `u64` to `u128`. In order to
maintain backwards compatibility, we have to de-/serialize it as two
separate `u64`s in `Event` as well as in the `Channel` itself.

Randomize `user_channel_id` for inbound channels

Previously, all inbound channels defaulted to a `user_channel_id` of 0,
which didn't allow for them being discerned on that basis. Here, we
simply randomize the identifier to fix this and enable the use of
`user_channel_id` as a true identifier for channels (assuming an equally
reasonable value is chosen for outbound channels and given upon
`create_channel()`).

Introduce `init_and_read_tlv_fields` macro

We introduce a new macro that inits and reads tlv fields and DRY up
`impl_writeable_tlv_based` and other macros.

Merge pull request #1845 from TheBlueMatt/2022-11-future-wake-fix

Fix persistence-required futures always completing instantly

Merge pull request #1806 from arik-so/2022-10-background-processor-deparametrization

Remove generic `Signer` parameter where it can be inferred from `KeysInterface`

Fix persistence-required futures always completing instantly

After the first persistence-required `Future` wakeup, we'll always
complete additional futures instantly as we don't clear the
"need wake" bit. Instead, we need to just assume that if a future
was generated (and not immediately drop'd) that its sufficient to
notify the user.

Merge pull request #1413 from ViktorTigerstrom/2022-04-default-to-bolt4-tlv-onions

Drop support for creating BOLT 4 Legacy onion format payloads

Add test for only creating tlv format onions

Remove `OnionHopDataFormat::Legacy`