Avoid excess multiplies by multiplying in `success_probability`

A substantial portion (~12%!) of our scoring time is spent dividing
the bucket pair probability by the `success_probability` divisor.

Here, we avoid this by multiplying the bucket pair probability
in floating point math and using a floating point divide (which can
be faster in some cases). This also avoids the 2^30 multiplies that
are used to avoid rounding errors when converting the float
numerator and denominator to ints.

Manually lay out scorer memory

Cache the total points tracked in our historical liquidity data

When we go to score a channel using the historical liquidity data,
the first thing we do is step through all the valid bucket
combinations, multiply the min and max bucket, and then add them
together to calculate the total number of points tracked. This
isn't a free operation, and for scorers without much data it
represents a large part of the total time spent scoring during
routefinding.

Thus, here we cache this value, updating it every time the buckets
are updated.

Change the directed history tracker's storage of its direction

Rather than storing the two direction's buckets in
`HistoricalMinMaxBuckets` (renamed
`DirectedHistoricalLiquidityTracker`), we store a single reference
to the `HistoricalLiquidityTracker` as well as the direction bool.

This will allow us in the next commit to reference fields in the
`HistoricalLiquidityTracker` aside from the two directions.

Make the historical bucket data private to `bucketed_history`

In a comming commit we'll cache some additional data in the
historical bucket tracker. In order to do so, here we isolate the
buckets themselves into the `bucketed_history` module, reducing
the possibility of accidentally updating them directly without
updating caches.

Store both min and max historical buckets in one, new, struct

In the coming commits we'll isolate historical bucket logic slightly
further, allowing us to cache some state. This is the first step
towards that, storing the historical liquidity information in a new
`HistoricalLiquidityTracker` rather than in the general
`ChannelLiquidity`.

Move log approximation from `scoring.rs` to its own file

Use a real (probing-generated) scorer in benchmarks

Until now, our routing benchmarks used a synthetic scorer,
generated by scoring random paths to build up some history. This is
pretty far removed from real-world routing conditions, as
alternative paths generally have no scoring information and even
the paths we do take have only one or two past scoring results.

Instead, we fetch a static serialized scorer, generated using
minutely probes. This means future changes to the scorer's data may
be harder to benchmark, but makes for substantially more realistic
benchmarks for changes which don't impact the serialized state.

Force inlining source and target node id lookup in candidate hops

Because our router is rather large, LLVM doesn't always decide to
inline small functions in it, opting instead for a call. This is
somewhat wasteful when we do repeated `match`es on the same data,
so here we force inlining of the `source` and `target` `NodeId`
lookups.

Prefetch per-direction channel info before looking at the channel

In the previous commit, we laid out `ChannelInfo` to ensure most of
the data we cared about was sitting on two adjacent cache lines.
However, this left off the per-direction `ChannelUpdateInfo`, which
is sitting elsewhere.

Here, we try to reduce the cost we pay for accessing those when we
call `ChannelInfo::as_directed` by prefetching them as soon as we
fetch the `ChannelInfo` from the per-channel `HashMap`. We then
check the features for unknown flags, giving the CPU a handful of
instructions to chew on before we actually need the
`ChannelUpdateInfo`.

Sadly, this currently requires unsafe Rust (and is currently only
available on stable for x86), even though the x86 ISA is explicit
that the instruction "does not affect program behavior". Still,
this optimization reduces time taken waiting for the
`ChannelUpdateInfo` to load from ~5% of our routefinding time to
~2.5%, for a net reduction of ~2.5% in routefinding time.

Layout channel info to ensure routing uses cache lines well

Because we scan per-channel information in the hot inner loop of
our routefinding immediately after looking a channel up in a
`HashMap`, we end up spending a nontrivial portion of our
routefinding time waiting on memory to be read in.

While there is only so much we can do about that, ensuring the
channel information that we care about is sitting on one or
adjacent cache lines avoids paying that penalty twice. Thus, here
we manually lay out `ChannelInfo` and `ChannelUpdateInfo` and set
them to 128b and 32b alignment, respectively. This wastes some
space in memory in our network graph, but improves routing
performance in return.

Push the route benchmark results into a separate uninlined function

This ensures the route benchmarks themselves will appear with a
distinct callgraph, making router profiling somewhat easier.

Consolidate `candidate` access in `add_entry` during routing

Because fetching fields from the `$candidate` often implies an
indirect read, grouping them together may result in one or two
fewer memory loads, so we do so here.

Somewhat optimize the generic `Features::requires_unknown_bits`

It turns out we spend several percent of our routefinding time just
checking if nodes and channels require unknown features
byte-by-byte. While the cost is almost certainly dominated by the
memory read latency, avoiding doing the checks byte-by-byte should
reduce the branch count slightly, which may reduce the overhead.

Store source/target `node_counter`s in `DirectionalChannelInfo`

Because we now have some slack space in `PathBuildingHop`, we can
use it to cache some additional hot values. Here we use it to
cache the source and target `node_counter`s for public channels,
effectively prefetching the values from the channel state.

DRY redundant calls to `$candidate.htlc_minimum_msat()` in routing

While LLVM should inline and elide the redundant calls, because the
router is rather large LLVM can decide against inlining in some
cases where it would be an nice win.

Thus, its worth DRY'ing the redundant calls explicitly.

Align `PathBuildingHop` to 128b, now that we store them in a `Vec`

Now that `PathBuildingHop` is stored in a `Vec` (as `Option`s),
rather than `HashMap` entries, they can grow to fill a full two
cache lines without a memory access performance cost. In the next
commit we'll take advantage of this somewhat, but here we update
the assertions and drop the `repr(C)`, allowing rust to lay the
memory out as it wishes.

Cache whether a node is a first-hop target in the per-node state

When processing the main loop during routefinding, for each node,
we check whether it happens to be our peer in one of our channels.
This ensures we never fail to find a route that takes a hop through
a private channel of ours, to a private node, then through
invoice-provided route hints to reach the ultimate payee.

Because this is incredibly hot code, doing a full `HashMap` lookup
to check if each node is a first-hop target ends up eating a good
chunk of time during routing. Luckily, we can trivially avoid this
cost.

Because we're already looking up the per-node state in the `dist`
map, we can store a bool in each first-hop target's state, avoiding
the lookup unless we know its going to succeed.

This requires storing a dummy entry in `dist`, which feels somewhat
strange, but is ultimately fine as we should never be looking at
per-node state unless we've already found a path to that node,
updating the fields in doign so.

Drop the `dist` `HashMap` in routing, replacing it with a `Vec`.

Now that we have unique, dense, 32-bit identifiers for all the
nodes in our network graph, we can store the per-node information
when routing in a simple `Vec` rather than a `HashMap`. This avoids
the overhead of hashing and table scanning entirely, for a nice
"simple" optimization win.

Because we must ensure we have a 1-to-1 mapping from node ids to
`node_counter`s, even across first-hop and last-hop hints, we have
to be careful to check the network graph first, then a new
`private_node_id_to_node_counter` map to ensure we only ever end up
with one counter per node id.

Store the source and destination `node_counter`s in `ChannelInfo`

In the next commit, we'll use the new `node_counter`s to remove a
`HashMap` from the router, using a `Vec` to store all our per-node
information. In order to make finding entries in that `Vec` cheap,
here we store the source and destintaion `node_counter`s in
`ChannelInfo`, givind us the counters for both ends of a channel
without doing a second `HashMap` lookup.

Track a `counter` for each node in our network graph

These counters are simply a unique number describing each node.
They have no specific meaning, but start at 0 and count up, with
counters being reused after a node has been deleted.

Drop fake time advancing in scoring tests

Now that we use explicit times passed to decay methods, there's no
reason to make calls to `SinceEpoch::advance` in scoring tests.

f drop shift test

Drop half-life-based bucket decay in `update_history_buckets`

Because we decay the bucket information in the background, there's
not much reason to try to decay them immediately prior to updating,
and in removing that we can also clean up a good bit of dead code,
which we do here.

Make scorer decay + persistence more frequent

There's some edge cases in our scoring when the information really
should be decayed but hasn't yet been prior to an update. Rather
than try to fix them exactly, we instead decay the scorer a bit
more often, which largely solves them but also gives us a bit more
accurate bounds on our channels, allowing us to reuse channels at
a similar amount to what just failed immediately, but at a
substantial penalty.

Drop warning about mixing `no-std` and `std` `ProbabilisticScorer`s

Now that the serialization format of `no-std` and `std`
`ProbabilisticScorer`s both just use `Duration` since UNIX epoch
and don't care about time except when decaying, we don't need to
warn users to not mix the scorers across `no-std` and `std` flags.

Fixes #2539

Add a benchmark for decaying a 100k channel scorer's liquidity info

This is a good gut-check to ensure we don't end up taking a ton of
time decaying channel liquidity info.

It currently clocks in around 1.25ms on an i7-1360P.

Drop now-trivial `decayed_offset_msat` helper utility

As we now no longer decay bounds information when fetching them,
there is no need to have a decaying-fetching helper utility.

Drop now-unused `T: Time` bound on `ProbabilisticScorer`

Now that we don't access time via the `Time` trait in
`ProbabilisticScorer`, we can finally drop the `Time` bound
entirely, removing the `ProbabilisticScorerUsingTime` and type
alias indirection and replacing it with a simple struct.

Use `Duration` based time info in scoring rather than `Time`

In the coming commits, the `T: Time` bound on `ProbabilisticScorer`
will be removed. In order to enable that, we need to switch over to
using the `ScoreUpdate`-provided current time (as a `Duration`
since the unix epoch), making the `T` bound entirely unused.

Pipe `Duration`-based time information through scoring pipeline

In the coming commits, the `T: Time` bound on `ProbabilisticScorer`
will be removed. In order to enable that, we need to pass the
current time (as a `Duration` since the unix epoch) through the
score updating pipeline, allowing us to keep the
`*last_updated_time` fields up-to-date as we go.

Update history bucket last_update time immediately on update

Now that we aren't decaying during scoring, when we set the
last_updated time in the history bucket logic doesn't matter, so
we should just update it when we've just updated the history
buckets.

Stop decaying liquidity information during bounds-based scoring

Because scoring is an incredibly performance-sensitive operation,
doing liquidity information decay (and especially fetching the
current time!) during scoring isn't really a great idea. Now that
we decay liquidity information in the background, we don't have any
reason to decay during scoring, and we ultimately remove it
entirely here.

Stop decaying historical liquidity information during scoring

Because scoring is an incredibly performance-sensitive operation,
doing liquidity information decay (and especially fetching the
current time!) during scoring isn't really a great idea. Now that
we decay liquidity information in the background, we don't have any
reason to decay during scoring, and we remove the historical bucket
liquidity decaying here.

f handle zero half life

f include ms/ns time parts when decaying

Impl decaying in `ProbabilisticScorer::decay_liquidity_certainty`

This implements decaying in the `ProbabilisticScorer`'s
`ScoreLookup::decay_liquidity_certainty` implementation, using
floats for accuracy since we're no longer particularly
time-sensitive. Further, it (finally) removes score entries which
have decayed to zero.

f temp bug

Track historical liquidity update time separately from the bounds

In the next commit, we'll start to use the new
`ScoreUpdate::decay_liquidity_certainty` to decay our bounds in the
background. This will result in the `last_updated` field getting
updated regularly on decay, rather than only on update. While this
isn't an issue for the regular liquidity bounds, it poses a problem
for the historical liquidity buckets, which are decayed on a
separate (and by default much longer) timer. If we didn't move to
tracking their decays separately, we'd never let the `last_updated`
field get old enough for the historical buckets to decay at all.

Instead, here we introduce a new `Duration` in the
`ChannelLiquidity` which tracks the last time the historical
liquidity buckets were last updated. We initialize it to a copy of
`last_updated` on deserialization if it is missing.

f sp

f correct decay+persist log line

f docs

Add a scoring decay method to the `ScoreUpdate` trait

Rather than relying on fetching the current time during
routefinding, here we introduce a new trait method to `ScoreUpdate`
to do so. This largely mirrors what we do with the `NetworkGraph`,
and allows us to take on much more expensive operations (floating
point exponentiation) in our decaying.

Pass the current time through `ScoreUpDate` methods

In the coming commits, we'll stop relying on fetching the time
during routefetching, preferring to decay score data in the
background instead.

The first step towards this - passing the current time through into
the scorer when updating.

Depend on `libm` in `no-std` for `powf`(64)

In the next commits we'll need `f64`'s `powf`, which is only
available in `std`. For `no-std`, here we depend on `libm` (a
`rust-lang` org project), which we can use for `powf`.

Merge pull request #2752 from valentinewallace/2023-11-large-final-onion-payload-fixes

Large final onion payload fixes

Merge pull request #2774 from TheBlueMatt/2023-12-2551-followups

Doc and performance followups to #2551

Error if onion payloads exceed max length on packet construction.

Ensure that if we call construct_onion_packet and friends where payloads are
too large for the allotted packet length, we'll fail to construct. Previously,
senders would happily construct invalid packets by array-shifting the final
node's HMAC out of the packet when adding an intermediate onion layer, causing
the receiver to error with "final payload provided for us as an intermediate
node."

Fix debug panic in onion utils on large custom TLVs or metadata.

We previously assumed that the final node's payload would be ~93 bytes, and had
code to ensure that the filler encoded after that payload is not all 0s. Now
with custom TLVs and metadata supported, the final node's payload may take up
the entire onion packet, so we can't assume that there are 64 bytes of filler
to check.

Pre-calculate heap element scores (retaining RouteGraphNode size)

`RouteGraphNode` currently recalculates scores in its `Ord`
implementation, wasting time while sorting the main Dijkstra's
heap.

Further, some time ago, when implementing the `htlc_maximum_msat`
amount reduction while walking the graph, we added
`PathBuildingHop::was_processed`, looking up the source node in
`dist` each time we pop'ed an element off of the binary heap.
As a result, we now have a reference to our `PathBuildingHop` when
processing a best-node's channels, leading to several fields in
`RouteGraphNode` being entirely redundant.

Here we drop those fields, but add a pre-calculated score field,
as well as force a suboptimal `RouteGraphNode` layout, retaining
its existing 64 byte size.

Without the suboptimal layout, performance is very mixed, but with
it performance is mostly improved, by around 10% in most tests.

Reorder `PathBuildingHop` fields somewhat

Given `PathBuildingHop` is now an even multiple of cache lines, we
can pick which fields "fall off" the cache line we have visible
when dealing with hops, which we do here.

Make `find_route`'s `dist` map elements fit in 128 bytes

We'd previously aggressively cached elements in the
`PathBuildingHop` struct (and its sub-structs), which resulted in a
rather bloated size. This implied cache misses as we read from and
write to multiple cache lines during processing of a single
channel.

Here, we reduce caching in `DirectedChannelInfo`, fitting the
`(NodeId, PathBuildingHop)` tuple in exactly 128 bytes. While this
should fit in a single cache line, it sadly does not generally lie
in only two lines, as glibc returns large buffers from `malloc`
which are very well aligned, plus 16 bytes (for its own allocation
tracking). Thus, we try to avoid reading from the last 16 bytes of
a `PathBuildingHop`, but luckily that isn't super hard.

Note that here we make accessing
`DirectedChannelInfo::effective_capacity` somewhat slower, but
that's okay as its only ever done once per `DirectedChannelInfo`
anyway.

While our routing benchmarks are quite noisy, this appears to
result in between a 5% and 15% performance improvement in the
probabilistic scoring benchmarks.

Make `CandidateRouteHop::PrivateHop::target_node_id` a reference

This avoids bloating `CandidateRouteHop` with a full 33-byte
node_id (and avoids repeated public key serialization when we do
multiple pathfinding passes).

Simplify and make scoring calls in `TestRouter` more complete

`TestRouter` tries to make scoring calls that mimic what an actual
router would do, but the changes in f0ecc3ec73dcdb9303b1bd5ac687a36
failed to make scoring calls for private hints or if we take a
public hop for the last hop.

This fixes those regressions, though no tests currently depend on
this behavior.

Make `CandidateRouteHop` method docs somewhat more descriptive

Fix indentation in `router.rs` broken in a1d15ac1926f70aa5ab4f6686f

Rename `CandidateRouteHop::FirstHop::node_id` and make it a ref

Rather than calling `CandidateRouteHop::FirstHop::node_id` just
`node_id`, we should call it `payer_node_id` to provide more
context.

We also take this opportunity to make it a reference, avoiding
bloating `CandidateRouteHop`.

`#[inline]` `CandidateRouteHop` accessors

These are used in the performance-critical routing and scoring
operations, which may happen outside of our crate. Thus, we really
need to allow downstream crates to inline these accessors into
their code, which we do here.

Fix new unused warnings in `scoring.rs`

Privatise `CandidateRouteHop::short_channel_id` as its a footgun

Short channel "ID"s are not globally unique when they come from a
BOLT 11 route hint or a first hop (which can be an outbound SCID
alias). In those cases, its rather confusing that we have a
`short_channel_id` method which mixes them all together, and even
more confusing that we have a `CandidateHopId` which is not, in
fact returning a unique identifier.

In our routing logic this is mostly fine - the cost of a collision
isn't super high and we should still do just fine finding a route,
however the same can't be true for downstream users, as they may or
may not rely on the apparent guarantees.

Thus, here, we privatise the SCID and id accessors.

Fix and re-enable the `remembers_historical_failures` test

f0ecc3ec73dcdb9303b1bd5ac687a361decce2dd introduced a regression in
the `remembers_historical_failures` test, and disabled it by simply
removing the `#[test]` annotation. This fixes the test and marks it
as a test again.

Rename `DirectedChannelInfo::outbound` to `from_node_one`

...to give a bit more readability on accessing sites.

Rewrite docs in `CandidateRouteHop` to be somewhat more descriptive

Merge pull request #2760 from TheBlueMatt/2023-11-chan-close-loop

Fix infinite loop when closing a pre-funding channel

Merge pull request #2776 from jkczyz/2023-12-direct-connect-follow-ups

Folllow-ups to #2723

Return correct SendSuccess in OnionMessenger

When enqueuing a message for a node already awaiting a connection,
BufferedAwaitingConnection should be returned when a node is not yet
connected as a peer. However, it was only returned when the first
message was enqueued. Any messages enqueued after but before a
connection was established incorrectly returned Buffered.

Rename OnionMessagePath::addresses

The name itself doesn't provide much meaning to what the addresses
correspond to.

Fix create_onion_message return type documentation

Immediately error in `close_channel_internal` if there is no chan

Previously, unfunded channels would be stored outside of
`PeerState::channel_by_id`, and thus if there is no channel when
we look in `PeerState::channel_by_id`, `close_channel_internal`
called `force_close_channel_with_peer` to hunt for unfunded
channels.

However, that is no longer the case, so the call is redundant, and
we can simply return an error instead.

Move pre-funded-channel immediate shutdown logic to the right place

Because a `Funded` `Channel` cannot possibly be pre-funding, the
logic in `ChannelManager::close_channel_internal` to handle
pre-funding channels is in the wrong place.

Rather than being handled inside the `Funded` branch, it should be
in an `else` following it, handling either of the two
`ChannelPhases` outside of `Funded`.

Sadly, because of a previous control flow management `loop {}`, the
existing code will infinite loop, which is fixed here.

Drop unreachable shutdown code in `Channel::get_shutdown`

`Channel` is only a thing for funded channels. Thus, checking if a
channel has not yet been funded is dead code and can simply be
elided.

Limit the scope of `get_funding_created_msg` to outbound channels

Since we no longer use `ChannelContext::get_funding_created_msg`,
it can be moved back into `UnfundedOutboundV1` channels only,
where it realistically belongs.

Move to `Funded` after `funding_signed` rather than on funding

Previously, channels were stored in different maps in `PeerState`
based on whether the funding had been set, keeping the keys across
the maps consistent (pre-funding temporary_channel_ids vs
funding-outpoint-based channel_ids). However, channels are now
stored in a single `channel_by_id` map, making that point moot.

Instead, here, we convert the `ChannelPhase` state transition
boundary to "once we have a `ChannelMonitor`", which makes more
sense now, and was actually the original proposed boundary.

This also requires calling `signer_maybe_unblocked` on a pre-funded
outbound channel, but that nicely also lets us limit the scope of
`FundingCreated` message generation, which we do in the next
commit.

Merge pull request #2723 from jkczyz/2023-11-direct-connect

Direct connect for `OnionMessage` sending

Merge pull request #2691 from wpaulino/refactor-channel-state

Refactor ChannelState to decouple state flags from states

Rename certain flags to align with dual funding

`FundingCreated` and `FundingSent` were mostly named after the
respective `funding_created` and `funding_sent` wire messages. They
include the signature for the initial commitment transaction when
opening a channel. With dual funding, these messages are no longer used,
and instead we rely on the existing `commitment_signed` to exchange
those signatures.

Rename OnionMessageBuffer to OnionMessageRecipient

Remove superfluous space from where clause

Test pending connection onion message buffering

Add tests for onion message buffering checking that messages are cleared
upon disconnection and timed out after MAX_TIMER_TICKS. Also, checks
that ConnectionNeeded events are generated.

Reuse MessengerNode in spec_test_vector

Additional tests will be added needing a similar node struct, so
consolidate its usage.

Call OnionMessageHandler::timer_tick_occurred

lightning-background-processor processes events provided by the
PeerManager's OnionMessageHandler for when a connection is needed. If a
connection is not established in a reasonable amount of time, drop any
buffered onion messages by calling timer_tick_occurred.

Process OnionMessageHandler events in background

OnionMessageHandler implementations now also implement EventsProvider.
Update lightning-background-processor to also process any events the
PeerManager's OnionMessageHandler provides.

Re-order define_run_body macro parameters

Simply to avoid excessive wrapping when possible.

Re-wrap define_run_body macro parameters

Some code hygiene before another parameter is added and rustfmt is
eventually used.

Remove unnecessary BackgroundProcessor type param

Merge pull request #2765 from TheBlueMatt/2023-12-2314-cleanups-1

Post-#2314 Cleanups

Drop buffered messages for timed out nodes

OnionMessenger buffers onion messages for nodes that are pending a
connection. To prevent DoS concerns, add a timer_tick_occurred method to
OnionMessageHandler so that buffered messages can be dropped. This will
be called in lightning-background-processor every 10 seconds.

Make OnionMessageHandler extend EventsProvider

An OnionMessageHandler may buffer messages that can't be sent because
the recipient is not a peer. Have the trait extend EventsProvider so
that implementation so that an Event::ConnectionNeeded can be generated
for any nodes that fall into this category. Also, implement
EventsProvider for OnionMessenger and IgnoringMessageHandler.

Add Event::ConnectionNeeded for onion messages

A MessageRouter may be unable to find a complete path to an onion
message's destination. This could because no such path exists or any
needs on a potential path don't support onion messages. Add an event
that indicates a connection with a node is needed in order to send the
message.

Return socket addresses from DefaultMessageRouter

When there isn't a direct connection with the Destination of an
OnionMessage, look up socket addresses from the NetworkGraph. This is
used to signal to OnionMessenger that a direct connection is needed to
send the message.

Add Option<Vec<SocketAddress>> to OnionMessagePath

MessageRouter::find_path is given a Destination to reach via a set of
peers. If a path cannot be found, it may return a partial path such that
OnionMessenger can signal a direct connection to the first node in the
path is needed. Include a list of socket addresses in the returned
OnionMessagePath to allow OnionMessenger to know how to connect to the
node.

This allows DefaultMessageRouter to use its NetworkGraph to return
socket addresses for gossiped nodes.

Add NetworkGraph reference to DefaultMessageRouter

When buffering onion messages for a node that is not connected as a
peer, it's possible that the node does not exist. Include a NetworkGraph
reference in DefaultMessageRouter so that it can be used to check if the
node actually exists. Otherwise, an malicious node may send an onion
message where the reply path's introduction node doesn't exist. This
would result in buffering messages that may never be delivered.

Buffer onion messages requiring a connection

MessageRouter::find_path returns a path to use when sending an onion
message. If the first node on the path is not connected or does not
support onion messages, sending will fail with InvalidFirstHop. Instead
of failing outright, buffer the message for later sending once the first
node is a connected peer.

Destination in OnionMessenger::send_onion_message

OnionMessenger::send_onion_message takes an OnionMessagePath. This isn't
very useful as it requires finding a path manually. Instead, have the
method take a Destination and use OnionMessenger's MessageRouter to
construct the path. Later, this will allow for buffering messages where
the first node in the path isn't a direct connection.

Merge pull request #2762 from TheBlueMatt/2023-11-htlc-docs

Improve docs on newly-public structs after  #2700

Use a message buffer abstraction in OnionMessenger

Onion messages are buffered for sending to the next node. Since the
network has limited adoption, connecting directly to a peer may be
necessary. Add an OnionMessageBuffer abstraction that can differentiate
between connected peers and those are pending a connection. This allows
for buffering messages before a connection is established and applying
different buffer policies for peers yet to be connected.

Merge pull request #2551 from jbesraa/expose-CandidateRouteHop-to-channel_penalty_msat

Add CandidateRouteHop to channel_penalty_msat inputs

Allow users to accept skimmed fees in calling `peel_payment_onion`

LSP users who wish to use `peel_payment_onion` to understand if
they'd accept an HTLC prior to receit should be able to check the
skimmed fees just like they would for full payment receipt. Thus,
we need to expose the fee-skimming acceptance bool to
`peel_payment_onion`, which we do here, in addition to some doc
cleanups.

Flesh out docs on `PendingHTLCInfo`

Now that `PendingHTLCInfo` is public, its docs should be meaningful
to developers not working directly on LDK, and thus needs
substantially more information than it previously had.

This adds much of that information.

Flesh out docs on `PendingHTLCRouting`

Now that `PendingHTLCRouting` is public, its docs should be
meaningful to developers not working directly on LDK, and thus
needs substantially more information than it previously had.

This adds much of that information.