Clean up docs on peer_handler significantly.

There are various typo and grammatical fixes here, as well as
concrete updates to correctness.

No longer block disconnect_socket calls in lightning-net-tokio

See the previous commit for more information.

Do not require that no calls are made post-disconnect_socket

The only practical way to meet this requirement is to block
disconnect_socket until any pending events are fully processed,
leading to this trivial deadlock:

 * Thread 1: select() woken up due to a read event
 * Thread 2: Event processing causes a disconnect_socket call to
             fire while the PeerManager lock is held.
 * Thread 2: disconnect_socket blocks until the read event in
             thread 1 completes.
 * Thread 1: bytes are read from the socket and
             PeerManager::read_event is called, waiting on the lock
             still held by thread 2.

There isn't a trivial way to address this deadlock without simply
making the final read_event call return immediately, which we do
here. This also implies that users can freely call event methods
after disconnect_socket, but only so far as the socket descriptor
is different from any later socket descriptor (ie until the file
descriptor is re-used).

Merge pull request #948 from TheBlueMatt/2021-06-p2p-fixes

Clean up message forwarding and relay gossip messages

[peer_handler] Drop unused return from get_peer_for_forwarding!()

This avoids a now-unnecessary SocketDescriptor clone() call in
addition to cleaning up the callsite code somewhat.

Somewhat simplify message handling error mapping in peer_handler

Drop peers_needing_send tracking and try to write for each peer

We do a lot of work to track which peers have buffers which need
to be flushed, when we could instead just try to flush ever peer's
buffer.

Skip forwarding gossip messages to peers if their buffer is over-full

Forward gossip msgs

Refactor message broadcasting out into a utility method

This will allow us to broadcast messages received in the next
commit.

Fix bogus reentrancy from read_event -> do_attempt_write_data

`Julian Knutsen <julianknutsen@users.noreply.github.com>` pointed
out in a previous discussion that `read_event` can reenter user
code despite the documentation stating explicitly that it will not.

This was addressed in #456 by simply codifying the reentrancy, but
its somewhat simpler to just drop the `do_attempt_write_data` call.

Ideally we could land most of Julian's work, but its still in need
of substantial git history cleanup to get it in a reviewable state
and this solves the immediate issue.

Drop unused "peer gone" handling in get_peer_for_forwarding!()

We can never assume that messages were reliably delivered whether
we placed them in the socket or not, so there isn't a lot of use in
explicitly handling the case that a peer was not connected when we
went to send it a message.

Two TODOs are left for the generation of a `FundingAbandoned` (or
similar) event, though it ultimately belongs in `ChannelManager`.

Merge pull request #947 from GeneFerneau/hash

Use hashbrown replacements for std equivalents

Use hashbrown replacements for std equivalents

Merge pull request #956 from jkczyz/2021-06-validate-pub

Increase poll::Validate visibility to pub

Merge pull request #955 from TheBlueMatt/2021-06-rustc-bugz

Fix trivial doc warnings and make CI use old rustc

Remove unnecessary spaces

Increase poll::Validate visibility to pub

Previously, poll::Validate was pub(crate) to force external implementors
of Poll to define their implementation in terms of ChainPoller. This was
because ChainPoller::look_up_previous_header checks for consistency
between headers and any errors would be checked at that level rather
than by the caller. Otherwise, if performed by the caller, a Poll
implementation would not be aware if the underlying BlockSource was
providing bad data and therefore couldn't react accordingly.

Widening the visibility to pub relaxes this requirement, although it's
still encourage to use ChainPoller to implement Poll. This permits
either copying or moving lightning-block-sync's test utilities to a
separate crate since they use poll::Validate.

Clarify invoice comment noting the relevant final-cltv-expiry vals

Make links in message signing docs rustdoc links

Latest rustc warns that "this URL is not a hyperlink" and notes that
"bare URLs are not automatically turned into clickable links". This
resolves those warnings.

Thanks to Joshua Nelson for pointing out the correct syntax for
this.

Expose doc-linked constants in lightning-invoice

These constants are generally useful, and are linked from
documentation, so should be exposed in any case.

Only check docs on rustc 1.52 as rustc stable now crashes

Merge pull request #944 from TheBlueMatt/2021-06-0.0.99

0.0.98

Merge pull request #946 from jkczyz/2021-06-get-route-interface

Align get_route's interface with ChannelManager and Invoice

Fix type name in docs

Accept multi-hop route hints in get_route

Lightning invoices allow for zero or more multi-hop route hints. Update
get_route's interface to accept such hints, although only the last hop
from each is used for the time being.

Moves RouteHint from lightning-invoice crate to lightning crate. Adds a
PrivateRoute wrapper around RouteHint for use in lightning-invoice.

Add find_all_extract macro to lightning-invoice

Used for extracting more than one field of the same type.

Bump versions to 0.0.98, lightning-invoice to 0.6.0

Merge pull request #940 from TheBlueMatt/2021-06-fix-docs

Clean up docs on public chan_utils methods to be more useful

Merge pull request #936 from TheBlueMatt/2021-05-spendable-event-locktime-delay

Delay DelayedPaymentOutput spendable events until the CSV delay

Merge pull request #943 from lightning-signer/2021-06-signet

Add proper signet support for invoices

Clean up docs on public chan_utils methods to be more useful

Merge pull request #939 from TheBlueMatt/2021-05-derives

Add additional derives for a few structs

Merge pull request #942 from lightning-signer/2021-06-accept-channel-reserve-dust

Remove unwanted check in accept_channel

Add proper signet support for invoices

Remove unwanted check in accept_channel

This caused an interoperability issue with lnd, because they can propose a reserve lower than their dust limit (but not lower than ours).

Add additional derives for a few structs

Delay DelayedPaymentOutput spendable events until the CSV delay

Merge pull request #935 from TheBlueMatt/2021-05-enum-tlvs

TLV-ize enum serialization and a few additional structs

Update network graph sample used in benchmarks

Convert SpendableOutputDescriptor to new TLV-based serialization

Clean up ChannelMonitor object serialization to use TLVs/versions

Use TLVs inside of serialization of Event variants

Convert remaining channel inner structs and enums to TLV-based ser

Convert most chain::* inner structs and enums to TLV-based ser macros

Add generic serialization implementations for Boxs and 3-tuples

These are used in the next commit(s).

Use TLV instead of explicit length for VecReadWrapper termination

VecReadWrapper is only used in TLVs so there is no need to prepend
a length before writing/reading the objects - we can instead simply
read until we reach the end of the TLV stream.

Add a macro to implement serialization of enums using TLVs

Merge pull request #938 from lightning-signer/2020-06-test-background

Expose test_process_background_events

Expose test_process_background_events

Give OnchainEvent::HTLCUpdate individual fields instead of a pair

Merge pull request #933 from TheBlueMatt/2021-05-ser-fast

Speed up deserialization of secp256k1 objects significantly

Add additional inline hints in serialization methods

This substantially improves deserialization performance when LLVM
decides not to inline many short methods, eg when not building
with LTO/codegen-units=1.

Even with the default bench params of LTO/codegen-units=1, the
serialization benchmarks on an Intel 2687W v3 take:

test routing::network_graph::benches::read_network_graph  ... bench: 1,955,616,225 ns/iter (+/- 4,135,777)
test routing::network_graph::benches::write_network_graph ... bench: 165,905,275 ns/iter (+/- 118,798)

Impl `serialized_length()` without `LengthCalculatingWriter`

With the new `serialized_length()` method potentially being
significantly more efficient than `LengthCalculatingWriter`, this
commit ensures we call `serialized_length()` when calculating
length of a larger struct.

Specifically, prior to this commit a call to
`serialized_length()` on a large object serialized with
`impl_writeable`, `impl_writeable_len_match`, or
`encode_varint_length_prefixed_tlv` (and
`impl_writeable_tlv_based`) would always serialize all inner fields
of that object using `LengthCalculatingWriter`. This would ignore
any `serialized_length()` overrides by inner fields. Instead, we
override `serialized_length()` on all of the above by calculating
the serialized size using calls to `serialized_length()` on inner
fields.

Further, writes to `LengthCalculatingWriter` should never fail as
its `write` method never returns an error. Thus, any write failures
indicate a bug in an object's write method or in our
object-creation sanity checking. We `.expect()` such write calls
here.

As of this commit, on an Intel 2687W v3, the serialization
benchmarks take:

test routing::network_graph::benches::read_network_graph  ... bench: 2,039,451,296 ns/iter (+/- 4,329,821)
test routing::network_graph::benches::write_network_graph ... bench: 166,685,412 ns/iter (+/- 352,537)

Avoid calling libsecp serialization fns when calculating length

When writing out libsecp256k1 objects during serialization in a
TLV, we potentially calculate the TLV length twice before
performing the actual serialization (once when calculating the
total TLV-stream length and once when calculating the length of the
secp256k1-object-containing TLV). Because the lengths of secp256k1
objects is a constant, we'd ideally like LLVM to entirely optimize
out those calls and simply know the expected length. However,
without cross-language LTO, there is no way for LLVM to verify that
there are no side-effects of the calls to libsecp256k1, leaving
LLVM with no way to optimize them out.

This commit adds a new method to `Writeable` which returns the
length of an object once serialized. It is implemented by default
using `LengthCalculatingWriter` (which LLVM generally optimizes out
for Rust objects) and overrides it for libsecp256k1 objects.

As of this commit, on an Intel 2687W v3, the serialization
benchmarks take:

test routing::network_graph::benches::read_network_graph  ... bench: 2,035,402,164 ns/iter (+/- 1,855,357)
test routing::network_graph::benches::write_network_graph ... bench: 308,235,267 ns/iter (+/- 140,202)

Drop byte_utils in favor of native `to/from_be_bytes` methods

Now that our MSRV supports the native methods, we have no need
for the helpers anymore. Because LLVM was already matching our
byte_utils methods as byteswap functions, this should have no
impact on generated (optimzied) code.

This removes most of the byte_utils usage, though some remains to
keep the patch size reasonable.

Add bench profiles to Cargo.toml to force codegen-units=1

This makes a small difference for NetworkGraph deserialization
as it enables more inlining across different files, hopefully
better matching user performance as well.

As of this commit, on an Intel 2687W v3, the serialization
benchmarks take:

test routing::network_graph::benches::read_network_graph  ... bench: 2,037,875,071 ns/iter (+/- 760,370)
test routing::network_graph::benches::write_network_graph ... bench: 320,561,557 ns/iter (+/- 176,343)

Add benchmark of deserializing a NetworkGraph.

NetworkGraph is one of the largest structures we generally
deserialize, so it makes for a good benchmark, even if it isn't the
most complicated one.

As of this commit, on an Intel 2687W v3, these benchmarks take:

test routing::network_graph::benches::read_network_graph  ... bench: 2,101,420,078 ns/iter (+/- 6,649,020)
test routing::network_graph::benches::write_network_graph ... bench: 344,696,835 ns/iter (+/- 229,061)

Merge pull request #892 from TheBlueMatt/2021-04-fix-htlc-ser

Correct Channel outbound HTLC serialization and expand fuzzing coverage

Merge pull request #934 from TheBlueMatt/2021-05-new-tag

Add new `(C-not implementable)` tag on `EventsProvider`

Correct Channel outbound HTLC serialization

Channel serialization should happen "as if
remove_uncommitted_htlcs_and_mark_paused had just been called".

This is true for the most part, but outbound RemoteRemoved HTLCs
were being serialized as normal, even though
`remote_uncommitted_htlcs_and_mark_paused` resets them to
`Committed`.

This led to a bug identified by the `chanmon_consistency_target`
fuzzer wherein, if we receive a update_*_htlc message bug not the
corresponding commitment_signed prior to a serialization roundtrip,
we'd force-close the channel due to the peer "attempting to
fail/claim an HTLC which was already failed/claimed".

[fuzz] Expand chanmon_consistency to do single message delivery

While trying to debug the issue ultimately tracked down to a
`PeerHandler` locking bug in #891, the ability to deliver only
individual messages at a time in chanmon_consistency looked
important. Specifically, it initially appeared there may be a race
when an update_add_htlc was delivered, then a node sent a payment,
and only after that, the corresponding commitment-signed was
delivered.

This commit adds such an ability, greatly expanding the potential
for chanmon_consistency to identify channel state machine bugs.

[fuzz] Fix hang due to double-lock in full_stack_target

[fuzz] Do not fail in FST if a channel is closed before we fund it

Merge pull request #931 from jkczyz/2021-05-http-client-reconnect

Cache socket address in HttpClient for reconnect

Add new `(C-not implementable)` tag on `EventsProvider`

This makes it so that users cannot usefully implement their own
`EventsProvider`, which would require substantial new logic in the
bindings generator (for generic methods). In the case of
`EventsProvider`, because there are no Rust methods which accept an
`EventsProvider` as an argument, this is perfectly OK as the
generated code would be entirely unused anyway.

Merge pull request #932 from TheBlueMatt/2021-05-broadcast-locktime-delay

Broadcast transactions only after their timelock is up

panic if locktime is violated when broadcasting in tests

Dont broadcast HTLC-Timeouts when closing a channel until locktime

Skip transactions which are locktime'd when broadcasting in test

Track the blocks a node has connected in the TestBroadcaster

Delay broadcast of PackageTemplate packages until their locktime

This stores transaction templates temporarily until their locktime
is reached, avoiding broadcasting (or RBF bumping) transactions
prior to their locktime. For those broadcasting transactions
(potentially indirectly) via Bitcoin Core RPC, this ensures no
automated rebroadcast of transactions on the client side is
required to get transactions confirmed.

Always pass height to OnchainTxHandler::update_claims_view

This simplifies logic somewhat and avoids duplicating the storage
of the current height in OnchainTxHandler.

Expose the timelock of transaction packages

Simplify tx checks in functional tests to make later commits simpler

This cleans up some of the transaction format verification and docs
to make it easier when we delay CLTV-locked transactions to update
the tests.

Simplify HolderHTLCOutput constructor and track CLTV expiry

This allows us to interrogate a PackageTemplate for the CLTV
timelock of the resulting transaction.

Add assertions to ensure we don't use an invalid package_amount

This somewhat cleans up the public API of PackageSolvingData to
make it harder to get an invalid amount and use it, adding further
debug assertion to check it at test-time.

Merge pull request #928 from TheBlueMatt/2021-05-really-tlv-ser

Migrate some inner structs to TLVs

Update net_graph used for benchmarks to use new ser format.

Migrate packages sub-fields to TLV serialization

Use TLV serialization for Commitment transaction structures

Add TLV suffix to PackageTemplate

Move NetworkGraph inner structs to TLV storage

Move ChannelManager-inner structs to TLV storage

Note that enums are left alone as we can use the type byte already
present for future compatibility.

Add dummy OutPoint constructor to be used when reading it in a TLV

Add a macro which implements Readable/Writeable using TLVs only

This also includes a `VecWriteWrapper` and `VecReadWrapper` which
implements serialization for any `Readable`/`Writeable` type that is
in a Vec. We do this instead of implementing `Readable`/`Writeable`
directly as there isn't always a univerally-defined way to serialize
a Vec and this makes things more explicit.

Finally, this tweaks existing macros (and in the new macros) to
support a trailing `,` after a list, eg
`write_tlv_fields!(stream, {(0, a),}, {});` whereas previously the
trailing `,` after the `(0, a)` would be a compile-error.

Merge pull request #924 from GeneFerneau/alloc

Use alloc for no_std builds

Use alloc for no_std builds

Replace std structs with alloc equivalents to support no_std builds

f use prelude::* credit @devrandom

Cache socket address in HttpClient for reconnect

If the HttpClient attempts to reconnect to bitcoind that is no longer
running, the client fails to get the address from the stream. Cache the
address when connecting to prevent this.

Fix compile warnings reading type-0 TLVs

Merge pull request #929 from jkczyz/2021-05-json-rpc-error

Parse RPC errors as JSON content

Parse RPC errors as JSON content

Bitcoin Core's JSON RPC server returns errors as HTTP error responses
with JSON content in the body. Parse this content as JSON to give a more
meaningful error. Otherwise, "binary" is given because the content
contains ASCII control characters.

Define an HttpError for returning error contents

Return an HTTP error response as a status code and contents. This allows
clients to interpret the response as desired (e.g., the contents as a
JSON-formatted error).

Merge pull request #642 from ariard/2020-06-anchor-backend-refacto

Anchor-outputs (1/3): Refactoring chain backend to extract PackageTemplate

Add package template unit tests

Move compute_output_value as part of package member functions

Move get_height_timer out of OnchainTxHandler

Move onchain* to chain/

Integrate PackageTemplate

This commit replaces InputMaterial in both ChannelMonitor/
OnchainTxHandler.

This doesn't change behavior.

Duplicate fee computation utilities out of OnchainTxHandler

Duplicated code in onchain.rs is removed in next commits.