There was and inconsistent usage of `#`, `##` and `###` in rustdoc
headings. The difference in the rendered rustdocs is a minimal font
size change.
Change all headings to be H1 `#`.
Change all subheadings to be `###` to have a noticeable difference in
font size in the rendered docs.
Since the introduction of `Script` `unsafe` started slowly creeping in
as more types with similar semantics were added. The `unsafe` in these
cases is just for trivial conversions between various pointer-like
types. As such, it's possible to move these into a single macro that
takes care of the conversions at one place and avoid repeating the same
`unsafe` code in the codebase. This decreases the cost of audits which
now only need to happen in `internals`, focuses any changes to happen in
that single macro and decreases the chance that we will mess up
similarly to the recent `try_into().expect()` issue (but this time with
UB rather than panic).
The new macro accepts syntax very similar to the already-existing struct
declarations with these differences:
* The struct MUST NOT have `#[repr(transparent)]` - it's added by the
macro
* If the struct uses `PhantomData` it must be the first field and the
real data must be the second field (to allow unsized types).
* The struct must be immediately followed by an impl block containing at
least on conversion function.
* If the struct has generics the impl block has to use the same names of
generics.
* The conversion functions don't have bodies (similarly to required
trait methods) and have a fixed set of allowed signatures.
* Underscore (`_`) must be used in place of the inner type in the
conversion function parameters.
The existing code can simply call the macro with simple changes and get
the same behavior without any direct use of `unsafe`. This change
already calls the macro for all relevant existing types. There are still
some usages left unrelated to the macro, except one additional
conversion in reverse direction on `Script`. It could be moved as well
but since it's on a single place so far it's not really required.
There's a restriction that for structs containing unsized types the
unsized type has to be the last field. `Address` is not an unsize type
but we are going to introduce a macro that will assume this order to
work equally well with both sized and unsized types. Thus we swap it
upfront here.
Previously we've used `try_into().expect()` because const generics were
unavailable. Then they became available but we didn't realize we could
already convert a bunch of code to not use panicking conversions. But we
can (and could for a while).
This adds an extension trait for arrays to provide basic non-panicking
operations returning arrays, so they can be composed with other
functions accepting arrays without any conversions. It also refactors a
bunch of code to use the non-panicking constructs but it's certainly not
all of it. That could be done later. This just aims at removing the
ugliest offenders and demonstrate the usefulness of this approach.
Aside from this, to avoid a bunch of duplicated work, this refactors
BIP32 key parsing to use a common method where xpub and xpriv are
encoded the same. Not doing this already led to a mistake where xpriv
implemented some additional checks that were missing in xpub. Thus this
change also indirectly fixes that bug.
Users may wish to ask of an address 'what kind of address is this?' We
have the `NetworkKind` struct that abstracts over the answer but
currently no API to ask the question.
The address may have been parsed or constructed and weather the network
has been checked already is immaterial. Hence we add the function for
both `NetworkChecked` and `NetworkUnchecked` addresses.
Fix: #4247
43ae9d7516 primitives: Hide script error internals (Tobin C. Harding)
2d8227f091 Hide relative locktime error internals (Tobin C. Harding)
Pull request description:
Make the struct fields private and add getters.
ACKs for top commit:
apoelstra:
ACK 43ae9d751622c7bef548a469466d74cf01284129; successfully ran local tests; nice! Way easier to understand these types with the new incompatible / expected names
Tree-SHA512: cfe67d60ea61a2a4c27b09071a6b11739ca281bf0b4a655121f90215ce38c3a637acf53a6e01aa2ef26fa80004cd919bf3b3334dbd9566ee2f594cab7750b563
As part of the 1.0 effort and forward maintainability hide the internals
of the two error types in the `script` module. Add getters to get at the
invalid size.
Currently it is not possible for downstream to use a generic on the
`Address` type in structs in conjuncture with
derives (`serde::Deserialize` and `Display`) because our impls are only
done for `NetworkUnchecked` (as they should be).
However, as observed by dpc, if we add a secondary marker trait and use
it to bound the impls, implementing the new marker for
`NetworkUnchecked` then downstream can use derives by way of
```
#[derive(Serialize, Deserialize)]
struct Foo<V>
where V: NetworkValidation,
{
#[serde(bound(deserialize = "V: NetworkValidationUnchecked"))]
address: Address<V>,
}
```
This is cool as hell because the `Address` type is currently a royal PITA.
There is a loose convention in Rust to not use `test_` prefix. The
reason being that `cargo test` outputs 'test <test name>' using the
prefix makes the output stutter.
This patch smells a bit like code-churn but having the prefix in some
places and not others is confusing to new contributors and is leading me
to explain this many times now. Lets just fix it.
Remove the prefix unless doing so breaks the code.
Adds an ergonomic way to convert any `Address` (network can be checked
or unchecked) into an `Address<NetworkUnchecked>` without cloning, which
I've found useful in several contexts.
There is a range of different wordings used in the docs of constructor
type functions.
Change all to start with `Constructs a new` or `Constructs an empty`.
In functions that act like constructors there is a mixture of the usage
of `creates` and `constructs`.
Replace all occurrences of `creates` with `constructs` in the first line
of docs of constructor like functions.
This has been fixed and we use nightly to lint so we have access to the
merged fix.
Removing the attribute uncovers a bunch of real lint warnings, fix
them while we are at it.
We do not want `bech32` to appear in the public API of the `address`
module in case `bech32` does not stabalize before the soon-to-be-created
`address` crates does.
We already had a go at removing it but forgot one error variant - wrap
the variant in a new type with a private inner bech32 error field.
ParseError is too general and the functions returning it do not have an
error path for all variants.
Split out the Bech32 and Base58 related errors into their own enums.
When a decoding error occurs for a bech32 address string the error is
discarded and the same address string is attempted to be decoded as
base58. This then incorrectly returns a base58 error.
Check the string prefix and decode as bech32 or base58 and return the
relevant error. If the prefix is unknown return an `UnknownHrpError`.
Examples in documentation are not linted in the same way as other code,
but should still contain correctly written code.
Throughout the bitcoin crate unused variables have either been prefixed
with _ or an assert used. And unused methods have been used in the
example code.
Examples in documentation are not linted in the same way as other code,
but should still contain correctly written code.
unused_imports in docs have been removed in bitcoin, and a warn
attribute added to lib.rs.
In preparation for moving the `ScritpBuf` type to `primitives` add a
public and private extension trait for the functions we want to leave
here in `bitcoin`.
Note, includes a change to the `difine_extension_trait` metavariable
used on `$gent` from `ident` to `path` to support the generic
`AsRef<PushBytes>`.
In preparation to move script types to `primitives` we replace impl
block with extension traits by replacing the temporary modules with
`define_extension_trait`.
The `Params` struct is currently defined in the `consensus` module which
has become a collection of orthogonal consensus-ish things. We would
like to put things in more descriptive places.
The `Params` struct defines constants that are network specific so it
makes sense to put it in the `network` module. As soft proof of this
argument note in this patch how often the `Params` type is imported
along with the `Network` type.
API break:
The type is no longer available at `bitcoin::consensus::Params` but
rather is re-exported at `bitcoin::network::Params`.
Done in preparation for moving the script types to `primitives`.
The script types have a bunch of functionality to support scriptPubkeys,
and scriptPubkeys are an address thing.
Create a module under `address` and in it create a bunch of extension
traits to hold all scriptPubkey functionality.
Includes adding an ugly-as-hell macro to create the traits.
Currently we are using a type alias for the `hash160::HashEngine`.
Type alias' allow for potential mixing of types, a `hash160::HashEngine`
struct can better serve our users with not much additional complexity or
maintenance burden.
As we did for the `sha256d::HashEngine`, add a new wrapper type
`hash160::HashEngine` that replaces the current type alias.
865ba3fc39 Move serde string macros to internals (Tobin C. Harding)
4a2b13fcde internals: Feature gate whole serde module (Tobin C. Harding)
Pull request description:
The macros are internal things and can live in `internals`. This will help with future crate smashing.
ACKs for top commit:
apoelstra:
ACK 865ba3fc39
Kixunil:
ACK 865ba3fc39
Tree-SHA512: 7b3f029206c690ecf2894e0ad099d391312f7f8ec65ac9b5d4d9f25e6827f92075dcc851d0940a0faf1e27e7d0a305b575c8cc790939b3f222d7a2920d4d24fe
d099b9c195 Remove wildcard from prelude import (Jamil Lambert, PhD)
Pull request description:
This patch replaces `prelude::*` wildcard imports with the types actually used. In a couple of cases `DisplayHex` was previously imported by the wildcard but was only used in the test module, an additional import was added to the test module instead of at the top where it causes an unused import warning.
Close: #2875
ACKs for top commit:
Kixunil:
ACK d099b9c195
tcharding:
ACK d099b9c195
Tree-SHA512: d59dfac0961d2649d509039a11c1b5574d81d05fef567a624cf15be2f587de796ea960ba5a08bef788199331c2f790fb06f7b393182538c7d8b1891ded119efc
Erick Cestari
Luis Schwab
Jamil Lambert
Fmt Bot
tushar994
Martin Habovstiak
Tobin C. Harding
kevincatty
merge-script
Erik De Smedt
Jose Storopoli
Max Fang
BinChengZhao
Chris Hyunhum Cho