rust-bitcoin

network: clean up docs

witness: Allocate in reserve_batch if capacity < MIN_VECTOR_ALLOCATE

Following #6198, the reserve_batch call now allocates a minimum size of
1000 bytes. Since the allocation only updates beyond capacity when
capacity - len == 0, reserve_batch may not always allocate up to the
given required_len.
In WitnessDecoder::push_bytes, reserve_batch is used in such a way that
assumes self.content will have the required_len. This causes a panic
when writing a compact size to the witness content if it does not.

Replace capacity == 0 check with capacity < MIN_VECTOR_ALLOCATE,
ensuring reserve_batch always allocates at least MIN_VECTOR_ALLOCATE
empty content space.

Add `#[track_caller]` to `ArrayVec::push`

When `push` panics because of capacity being exceeded it's the caller's
fault for not taking care of it, so using `#[track_caller]` provides a
better panic message.

consensus_encoding: Adjust docs spelling and grammar

consensus_encoding: run formatter

consensus_encoding: switch tests to should_panic macro

hashes: Update API files

Update API

consensus_encoding: add checked decode functions for tests

Update API files

consensus_encoding: run formatter

Add DecoderStatus return value to the Decoder trait

Same reasoning as the EncoderStatus, the type makes things a little
easier to reason about than a naked bool.

Update API

consensus_encoding: update docs for the new return emums

consensus_encoding: fix up lints

consensus_encoding: squash mutants

Replace `bool` in `Encoder` with an enum

It was difficult to remember the meaning of `true` and `false` returned
from `advance` making it harder to write and read the code. The
idiomatic solution to such problem is to replace `bool` with an enum
which this commit does.

To make it less annoying, the enum defines methods that can convert it
to bool readably. Notably, they are not named `is_` but `has_finished`
and `has_more` which reads better in the code that's dealing with them.
E.g. `if encoder.advance().has_finished()` reads naturally.

Test outcome of encoding, not chunking

The idea behind the `Encoder` trait is that it represents a stream of
bytes that can be encoded, so it's logically equivalent to iterator of
bytes. The only reason data is returned in chunks is to improve
efficiency by potentially avoiding intermediate copies and some
branches.

As such, encoding should be tested by outcome - are the bytes produced
by the encoder what is expected? How the bytes are chunked is not only
irrelevant but testing it causes churn when refactoring, changing the
chunking strategy and makes the test code more complicated than
required.

We had a bunch of tests that were testing the chunking, including
internal details of encoders, "safety" of encoders which a) really
aren't `unsafe` and b) are not required to be well-behaved when called
after they yield all bytes. This commit changes the tests to check the
outputs of encoding instead, deletes tests that touch internal details
of encoders, deletes redundant tests of the `is_empty` method which is a
provided method and thus shouldn't need to be tested more than once, and
updates the documentation of the `Encoder` trait to clarify that
chunking is not stable, so that consumers don't rely on it.

Update API files

Update `ArrayVec` deserialization

Deserialization of ArrayVec now uses `ArrayVec::try_push` method
over the `ArrayVec::push` method, which would panic if the array
is full, causing us to manually check for capacity before pushing.

The `try_push` method returns a `Result` which is mapped to Serde's
`invalid_length` error.

p2p: Remove `bitcoin` dependency

`hex` is brought in from `primitives` as it is an unconditional
dependency. `arbitrary` is brought in from `primitives` as opposed to
`bitcoin`. `primitives` and `encoding` need `alloc`. One doc line is updated.

Use stacked attributes over #[cfg(all(...))]

Per our policy, feature gates should use stacked attributes instead
of #[cfg(all(...))]. Presumably due to changes at the same time as
this policy was introduced, there remain a few uses of the old style
in primitives.

Move deserialize tests to primitives

In bitcoin, there are various tests that only have a dependency on
bitcoin due to the deserialize/serialize functions on the old encoding
traits. Changing these to use consensus_encoding allows them to be
trivially moved to primitives.

Move tests to upstream crates

Test cases for Outpoint, Version, CompactTarget and Sequence have been
left in bitcoin even following their moves to primitives and units. In
order to keep tests close to the corresponding types, the tests should
be moved to the upstream leaf crates.

Move tests to units and primitives alongside their corresponding types.

p2p: Remove `io` dependency

`io` is no longer required with the introduction of
`bitcoin-consensus-encoding`