d8377d90dd units: Remove serde derive feature (Tobin C. Harding)
1031851da4 units: Manually implement serde traits for block types (Tobin C. Harding)
Pull request description:
Currently we only need the `derive` feature of `serde` in test code.
Observe:
- We do not need the error testing logic because `ParseAmountError` is already exhaustively tested.
- The rest of the `serde` test logic in `amount` can be done using the public API so it can be moved to the integration test directory.
Move the unit test code to `tests/` excluding the error testing logic. Remove the `derive` feature from the `serde` dependency. Add a `dev-dependency` on `serde` that enables the `derive` feature.
ACKs for top commit:
apoelstra:
ACK d8377d90dd8d6bd066f51f45c23ffdfe2d0ab694; successfully ran local tests; nice!
Tree-SHA512: 03eb24ae1917e838a2e20c3c62ef9381e2a1eaccdb6474f60a2db59af98d9533054227af4c404013ea8deb4cfe4d57075ae4890857f8af283ebb4338ddb4ed3f
7fbe07a6e0 Use uniform docs for overflow (Tobin C. Harding)
153a6a2f3c Make Weight docs uniform with FeeRate (Tobin C. Harding)
c87f7292be Fix rustdocs on Weight (Tobin C. Harding)
02b523a8ad Remove whitespace from encapsulate module (Tobin C. Harding)
Pull request description:
Make a sweep of the `units` crate's rustdocs.
ACKs for top commit:
apoelstra:
ACK 7fbe07a6e0b3e398aca845d64ec86f3f0068edf4; successfully ran local tests
Tree-SHA512: ba50f3afb94dda43f89d04eb53c6e85df302292d4647fe81a20e3f7d1ca75e8ee8cdf6548864b2f3c33ed661205d109dbd763db1061ea45a59eab25f134191f8
The `block` module does not follow the `encapsulate` pattern but we can
still use the getters instead of accessing the inner field directly.
Refactor, no logic change.
4ccecf5dec Fix stale Height type link (Tobin C. Harding)
caebb1bf73 units: relative: Do minor rustdocs fixes (Tobin C. Harding)
40bb177bc2 Put is_satisfied_by functions together (Tobin C. Harding)
480a2cd62a Favour new function `from_mtp` over deprecated (Tobin C. Harding)
f9d6453d5b Shorten locktime type term (Tobin C. Harding)
727047bd39 Fix off-by-one-bug in absolute locktime (Tobin C. Harding)
3ffdc54ca5 Fix off-by-one bug in relative locktime (Tobin C. Harding)
a2ff8ddbbb Improve relative::LockTime is_satisfied_by_{height, time} (Tobin C. Harding)
Pull request description:
Make the APIs uniform in relative and absolute locktimes in relation to the `is_satisfied_by` functions. In doing so improve the API and fix an off-by-one bug when checking satisfaction of locks by height.
Done in three patches but maybe should be squashed? Probably easiest to review by looking at all the `is_satisfied_by*` functions and convincing yourself we got it right.
EDIT: Now has 5 cleanup patches also (mostly docs cleanups).
ACKs for top commit:
apoelstra:
ACK 4ccecf5decfead9818b74fbdee73115c349e2f3e; successfully ran local tests
Tree-SHA512: 9206cb464a06647510a35a7d564062823117e75df60251969be458616f4f5d04acf0aada53dbf7d493a2a2a72d26b3a300417a6499e45413d5f2a011538b7826
Recently we added a private `impl_u32_macro`. It included a bunch of
associated consts and a pair of u32 constructor/getter functions.
We overlooked the fact that the macro produces incorrect docs.
Move the offending code out of the macro and into the already existent
impl block for each type.
Docs only, no other logic change.
We recently added a bunch of types in the `block` module that are
wrappers around `u32`. When we did we slapped `pub` on the inner fields.
Lets be more mindful and make the inner fields private. Note all these
types have `to_u32`, `from_u32` and `From` in both directions.
Name the type exactly what it is. This used to be `Time`, then we tried
`MtpInterval`.
Note that this makes some of the original function names overly verbose
e.g., `NumberOf512seconds::from_512_second_intervals()` but given the
curlyness of locktimes too verbose is better than too terse. Also this
type, along with `NumberOfBlocks` is not going to be in very wide use so
the ergonomic hit is worth the additional clarity.
Name this type exactly what it is. Note for the error we just use
'height' even though this is a bit stale but the general concept is ok
in the error type because the name is long already.
See the previous commit message for justification; for sensible
arithmetic on block timestamps we need the ability to do MTP
calculations on arbitrary MTPs and arbitrary intervals between them.
However, the absolute::Mtp and relative::MtpInterval types are severely
limited in both range and precision.
Also adds a bunch of arithmetic ops to match the existing ops for
BlockHeight and BlockInterval. These panic on overflow, just like the
underlying std arithmetic, which I think is reasonable behavior for
types which are documented as being thin wrappers around u32.
We may want to add checked_add, checked_sub and maybe checked_sum
methods, but that's out of scope for this PR.
For our relative locktime API, we are going to want to take differences
of arbitrary MTPs in order to check whether they meet some relative
timelock threshold.
However, the `locktime::absolute::Mtp` type can only represent MTPs that
exceed 500 million. In practice this is a non-issue; by consensus MTPs
must be monotonic and every real chain (even test chains) have initial
real MTPs well above 500 million, which as a UNIX timestamp corresponds
to November 5, 1985.
But in theory this is a big problem: if we were to treat relative MTPs
as "differences of absolute-timelock MTPs" then we will be unable to
construct relative timelocks on chains with weird timestamps (and on
legitimate chains, we'd have .unwrap()s everywhere that would be hard to
justify). But we need to treat them as a "difference of MTPs" in *some*
sense, because otherwise they'd be very hard to construct.
There is a lot of duplicated code between BlockHeight and BlockInterval.
It obfuscates the differences between them: which timelock types they
can be converted to/from and what their arithmetic properties are.
Rename `value` to `to_height` to be symmetric with `from_height`;
deprecate `to_consensus_u32` which had no symmetric `from_consensus_u32`
and was only used to implement the corresponding methods in primitives
and bitcoin.
This is disruptive, but makes the type name consistent with
`MtpInterval` and also greatly improves clarity, helping to distinguish
between absolute and relative locktimes and reminding the author (and
reviewer) of locktime code that this needs to be a diff.
As with absolute::Mtp, there is no "consensus encoding" of a block
height, except that obtained by converting it to a locktime. For
symmetry with `Mtp`, rename the methods.
We have a new macro for implementing ops with a bunch of reference
combos. Lets use it for block `Height` and `Interval`.
This patch is strictly additive.
Next patch will move all the impls of `Add` and `Sub` into a macro call.
In order to make that patch smaller move the assign impls to be together
below the add/sub impls.
Code move only, no logic change.
Preemptively addressing these mutants before introducing the
cargo-mutants workflow
There are several types of changes:
- Changes that address mutants that were actually missing
- Changes that address test values that cause `cargo-mutants` to think
mutants were missed. For example, `cargo-mutants` will replace the
return values for unsigned integer types with 0 and 1. While a function
might be tested, the test might be testing the function with a call that
results in 0 or 1. When `cargo-mutants` substitutes the function call
with `Ok(1)`, the test will still pass, and it will consider this a
mutant. `cargo-mutants` also replaces operations (+, -, /, %), bitwise
operations (&, |, ^, etc), so an operation such as `3 - 2` results in a
mutant because changing it to `3 / 2` yields the same result
- TODOs to ignore functions/impls in the future
04dfe8dd45 Add api test to check Arbitrary impls (Shing Him Ng)
678fc71b88 Implement Arbitrary for units types (Shing Him Ng)
Pull request description:
Implement Arbitrary for the rest of the types in `units`. Also moved the implementation in `FeeRate` right before the `tests` module
Closes#3705
ACKs for top commit:
apoelstra:
ACK 04dfe8dd45fae9b55dacfe9eb0d73ea306db14ba; successfully ran local tests
tcharding:
ACK 04dfe8dd45
Tree-SHA512: 156bd26d4de85d484711d476df1d2758805387125209f0307aa786dd1585ff9953dbe41b0864b00ae101419176647e3bde7994ed9257c18307d161463b1c8d2e
Add all the pedantic lints to the repository by way of the repository
manifest. Then enable these lints in the `units` manifest.
Some things worth mentioning:
- Fix `needless_pass_by_value` by adding derives to `FormatOptions`.
- Fix lint `cast_lossless` using `cargo clippy --fix``
- While fixing `lint enum_glob_use` introduce a new style to the
codebase; import enums using a single character. Doing so prevents
namespace clashes, improves clarity, and maintains terseness.
Audit:
Use the following lints locally and audit all the warnings, they produce
many false positives so we can't enable them permentently.
- `cast_possible_truncation`
- `cast_possible_lint`
- `cast_sign_loss`
A block interval is a relative thing so it makes sense to default to
zero. This is the same as how we derive `Debug` for `relative::Height`
but not `absolute::Height`.
These lints are valuable, lets get at em.
Changes are API breaking but because the changes make functions consume
self for types that are `Copy` downstream should not notice the breaks.
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.
The use of links in the rustdocs was inconsistent.
Links have been added when missing.
[`locktime::absolute::Height`] and [`locktime::relative::Height`] did
not work and `(crate::locktime)` was appended to fix it.
Add two simple integer wrapper types for abstracting over block
height (from genesis block) and block interval.
This does not include hex because block height is typically written in
decimal.
These types are very thin wrappers, their usecase is to assist in code
readability instead of enforcing any logic.
Andrew Poelstra
Tobin C. Harding
Jamil Lambert, PhD
Fmt Bot
Shing Him Ng