826acb8273 units: rename relative::HeightInterval constructors (Andrew Poelstra)
39b4f7670d units: rename relative::Height to HeightInterval (Andrew Poelstra)
d3619cc1bc units: deprecate relative::MtpInterval::to_consensus_u32 (Andrew Poelstra)
1a6b8b4c7a units: rename relative::Time to MtpInterval (Andrew Poelstra)
39b057fade units: rename absolute::Height consensus functions (Andrew Poelstra)
5a8f33f380 units: rename absolute::Mtp consensus functions (Andrew Poelstra)
8ffcd2cf30 units: rename absolute::Time to absolute::Mtp (Andrew Poelstra)
Pull request description:
This PR does a whole bunch of renames to the `units` locktime modules. These modules contain the underlying units for locktime types and hopefully aren't used directly too often, which should minimize the disruption from these renames.
This fixes a number of issues:
* Confusion between blocktimes and MTPs (which in fairness, *are* blocktimes, but they're not the one that users are likely to reach for)
* Constructor and conversion names that imply there is a "consensus encoding" for these bare units, which corresponded to the consensus encoding of the corresponding locktimes/sequence numbers
* `from_*` methods without `to_*` methods and vice-versa (overlaps with the above)
* the horribly named `value` method on relative heights and times (but not absolute ones)
This PR does **not** remove the `MtpAndHeight` type, nor does it add constructors for `Mtp` from lists of blocktimes. This is because the PR was too big already and I felt I should split it up.
Alternate to #4427
ACKs for top commit:
tcharding:
ACK 826acb8273
Tree-SHA512: 6e0491e17927625cde85c2cf92ff152a10613e632474122a626ee31b662d21c09fcb9fa3014c44708c97536535a33845cbbcd81e73dcdf98e9ee9fd6143c698f
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.
This method is weird. It's basically just used internally to implement
the locktime methods in `primitives` and `bitcoin`. It has no symmetric
from_consensus_u32.
Conversely the constructors from 512-second intervals have no symmetric
to_* method -- the inverse of these functions is called `value`, which
is a meaningless and undiscoverable name.
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.
16f6fc6b5b Improve docs on absolute::LockTime::is_implied_by (Tobin C. Harding)
Pull request description:
If one wishes to verify a script that contains CLTV is valid in a transaction then one must compare the argument to CLTV (the locktime) to the transaction locktime. And to be valid the CLTV locktime must be less than or equal to the transaction locktime. This usage kind of lends itself to the term 'implied by' and we have a function already `is_implied_by` that does exactly this.
Improve the docs by adding a section mentioning this usecase.
ACKs for top commit:
apoelstra:
ACK 16f6fc6b5b469741c076bc3a4d92f7d4e619ffc7; successfully ran local tests
Tree-SHA512: f7de177927150ae27b3db187465e0f699da9e8e00a490b0354176b2dedc34d731fda40bf4d55324aa28b0d55f2f036653ab14d99b82d56705c929986db8fb30e
There is no "consensus encoding" for a MTP. The intention for these
methods was that a user could interpret the MTP as a locktime and then
consensus-encode that locktime. However, it was instead interpreted as
the MTP representing a *blocktime* as it is consensus-encoded in a block
header.
Evidence of this misinterpretation is in several doccomments, which
casually refer to the Mtp (which used to be just called Time) as a
"block time", which is simply incorrect.
This is not a generic UNIX timestamp, but rather a MTP restricted to
have values between 500 million and u32::MAX. Most importantly, it is
*not* a blocktime, which is what is implied by its name and
constructors.
If one wishes to verify a script that contains CLTV is valid in a
transaction then one must compare the argument to CLTV (the locktime) to
the transaction locktime. And to be valid the CLTV locktime must be less
than or equal to the transaction locktime. This usage kind of lends
itself to the term 'implied by' and we have a function already
`is_implied_by` that does exactly this.
Improve the docs by adding a section mentioning this usecase.
The output of `Display` should not change in stable crates for types
that have well defined formatting and ones that implement `FromStr`.
Error types do not need to be tested.
Add missing tests for all implementations in `primitives` and round
trips for types that implement `FromStr`.
5d5a19793a Run the formatter (Tobin C. Harding)
2b72f1f30b Make Lower/Upper hex print scripts with len prefix (Tobin C. Harding)
c27b95fb0d Make script to/from hex use consensus encoding (Tobin C. Harding)
f4bc58dc48 bitcoin: Add a script encoding example (Tobin C. Harding)
Pull request description:
Done while investigating #3910 - this PR is quite invasive.
- Patch 1 adds an example that shows the current behaviour of various API calls for converting scripts to/from hex.
- Patch 2 adds a pair of functions that do not use the length prefix and makes script to/from_hex use the prefix.
- Patch 3 makes `LowerHex` and `UpperHex` use the len prefix also
- Patch 4 runs the formatter
Explicitly keeps serde untouched - i.e., without the len prefix
ACKs for top commit:
apoelstra:
ACK 5d5a19793aae73ff09d7064455a1a995eb796c28; successfully ran local tests
Tree-SHA512: dbbec372ea7b01818fce68ffb807a4531f068e10147e8bedf37b77f66a068a628e380549c379c061b868973e97806ada59729248b03bbd1cf6809f6098170cb6
8b47068a2e feat(locktime): implement MtpAndHeight structure and validation logic (aagbotemi)
Pull request description:
This PR fixes#4299
- Computed MtpAndHeight structure
- Checked if relative time and height is satisfied by MtpAndHeight
- Compared the Ordering of MtpAndHeight with time and height
- Checked MtpAndHeight satisfaction and comparison in Locktime
- Added unit tests for all the implementation
I've reviewed and adhered to the contribution guidelines
ACKs for top commit:
apoelstra:
ACK 8b47068a2efada30aec21c61ae4be0da4d8e8fc8; successfully ran local tests
Kixunil:
ACK 8b47068a2e
tcharding:
ACK 8b47068a2e
Tree-SHA512: b00d1384d5deaa038b486ca9d77ad33cfa6cd8c987e08407863f2be8d540014bdcc971cd9d46acb51a2d105341accc04ba151e5cccb276e8352a5d45b33097eb
Add the length prefix when formatting hex strings by way of `LowerHex`
and `UpperHex`.
This looses formatting options because I can't remember right now how
not to - again.
- Add MtpAndHeight for relative locktime checks
- Include unit tests for time/height comparisons
- Fix API design for mtp_as_time() error handling
- Update documentation and dependencies
- Fix BlockTime, CI, remove Ordering, and PR discussion fixed
- Fix UTXO height and timestamps
- Fix: chain_state and utxo_state handled seperately for is_satisfied_by
- Fix: panic on overflow fixed with check_add
- Fix: documentation updated and trailing whitespaces removed
- docs(mtpheight): documentation updated
- used accessors to_height and to_mtp over From impl
c4d9c1b9f8 Use a consistent rustdoc heading level of H1 `#` (Jamil Lambert)
6325a7cdea Change rustdoc heading level of references (Jamil Lambert)
f22e997587 Use parameters instead of arguments in rustdocs (Jamil Lambert)
e2c7be6d2f Fix typo (Jamil Lambert)
Pull request description:
In the rustdocs both `# Parameters` and `# Arguments` are used to mean the same thing. In a previous PR #2792 it was decided to go with Parameters everywhere. Since then there have been a few additions of "Arguments" into the rustdocs.
There is also a mix in the usage of `#`, `##` or `###` for headings. Noticed here https://github.com/rust-bitcoin/rust-bitcoin/pull/2792#issuecomment-2125775974.
- Fix a typo found when looking into this.
- Change all occurances to use `# Parameters` in rustdocs.
- Change all heading levels to H1 `#`
- Change all subheading levels to H3 `###` to make the small difference in the rendered font size noticable
Closes#4380
ACKs for top commit:
apoelstra:
ACK c4d9c1b9f8e59bf795812c42bd1eee68d97b9bbd; successfully ran local tests
Tree-SHA512: c8cc77ccf7e2003dd2dd1d309268624576e3bf390cd8ac61b0a7bb1141ca05377c83627576b0b7ff258b8e51c2d255097a4363fbdd1b368db7d32ac32ece58a1
9eaaf114b0 fix(witness): remove explicit type (aagbotemi)
5b572c5976 docs(witness): use constructs instead of creates (aagbotemi)
Pull request description:
This PR fixes#4379
- Removed explicit type
- updated documentation
- PR is in two seperate patches
ACKs for top commit:
apoelstra:
ACK 9eaaf114b0d6afb810cec8e9dac603ecadf64ff4; successfully ran local tests
Tree-SHA512: 65a6ca880c64aa81d83dffbfcd21a0427c874237a606d82ab70f226839adb164c9ee7fd1ecd5d8cee662660efcd1c458c523a27964cd1d00704d40a3bb6a1deb
6370aac7e1 Make Version::maybe_non_standard and Version::is_standard const (Shing Him Ng)
Pull request description:
Closes#4206
ACKs for top commit:
apoelstra:
ACK 6370aac7e119042d8b6b40021bbcd6324ad02bbb; successfully ran local tests
Tree-SHA512: aaf6afbe39d6568e0d05776a2a2f58a9a657f28cd3942391b599390bb4db974684e7d76cdf8db51a0fbcb948cdc4e19f22ba4b8ca39537e162cbd5bb2d4cd40e
cf42c511d8 primitives: replace error propagation with `expect` (Andrew Poelstra)
Pull request description:
This error path cannot happen, and if it could, failing formatting is not the correct source of action, because the std docs say that formatting may only fail if the formatter says so.
Fixes comment in #4269
ACKs for top commit:
tcharding:
ACK cf42c511d8
Kixunil:
ACK cf42c511d8
Tree-SHA512: 0ad47bb210dc71568bde426b8fd7782a4d48415fbf27133783975117d174b58eb791e68290e53f150a7e65236efda75032852bb6ed30bf4a182f18b9440cfcf9
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.
`Bitcoin Core References` used H3 `###` in rustdocs, and one occurrence
had another `References` heading above it.
Change them to be H1 `#` like other headings.
Remove the redundant `References` heading. NB. there are no other
occurrences of `# References` in this crate.
This error path cannot happen, and if it could, failing formatting is
not the correct source of action, because the std docs say that
formatting may only fail if the formatter says so.
Fixes comment in #4269
e0b627ea81 deserialize witness from a list of hex strings - ci(primitives): enable hex feature in CI build - from_hex() implemented more efficiently (aagbotemi)
Pull request description:
This PR implements `from_hex` function for deserialize `Witness` from a list of hex strings. Added unit test.
This PR fixes#4350
ACKs for top commit:
apoelstra:
ACK e0b627ea816a730949cdb200105598600fcac094; successfully ran local tests
tcharding:
ACK e0b627ea81
Tree-SHA512: deec3f9e5f67a0915b11a811c40c341dd9f24d0394d6cfbd6a09f765ce3fc0dcce2740949c264d4aa2d2db748a5ce81416b4dac15b1b64475a7c024b205e40ab
6323867c65 Run the formatter (Tobin C. Harding)
d5c08aef32 units: Update column width (Tobin C. Harding)
f7f1a0be8c Add privacy boundary to BlockTime (Tobin C. Harding)
b3dfe0df3f Add privacy boundary to Weight (Tobin C. Harding)
e1a14b3c2d Add privacy boundary to FeeRate (Tobin C. Harding)
4b733d4dad Run the formatter (Tobin C. Harding)
Pull request description:
Add privacy boundary for `FeeRate`, `BlockTime`, and `Weight`. The lock times are a bit curly so just doing these ones for now.
ACKs for top commit:
apoelstra:
ACK 6323867c65cdbf0f1b25d252fded6873acd35a3a; successfully ran local tests
Tree-SHA512: b6cf5eb032e055414f48f3469ec1748635b9f53ca64c158bd861d1ae6e2cfbe7b4d82de98f7dc90913d98429e6ae6991a4a61b6c438574fcbef9b3bc7ebafb4b
b4b61cb884 Add tests to increase coverage (Jamil Lambert, PhD)
6bcc6b703d Expand display test to cover debug and OP_0 (Jamil Lambert, PhD)
8a096b77d5 Expand as_ref and as_mut tests (Jamil Lambert, PhD)
afa51f7bfa Add missing empty line, and remove extra one (Jamil Lambert, PhD)
Pull request description:
Expand existing tests and add new ones to increase the test coverage in `primitives/src/script/` to 100% excluding `serde` and `arbitrary` features.
ACKs for top commit:
apoelstra:
ACK b4b61cb8849d5d536532474691c5d9f10c146672; successfully ran local tests
tcharding:
ACK b4b61cb884
Tree-SHA512: 6c37a194e5a94fe04bb26d4e904bd98efc75bd433b59aa09b1c102df96b753602d3ad6540ed9941827f03c7d38e7bbb8b10bbcc8c6ab52b8f96b83743eec4519
e3b059cebf Implement Display for block::Header (Tobin C. Harding)
Pull request description:
Not all the fields within `block::Header` implement `Display` however a block header can reasonably be displayed by using 160 hex characters.
Implement `Display` for `block::Header` by printing the header in hex in the same layout as we hash it in `block_hash`.
Close: #3658
ACKs for top commit:
apoelstra:
ACK e3b059cebfb917c3a876cc5a39d942d2dead475c; successfully ran local tests
Tree-SHA512: c1ff0d73562c9e00e93659f385a471c2d7912e1f09faf6c646bd7864d1a98e6e2baddebfcd1a032bf5adc3e27586022927261c8867098f7e7bf166bf35a9ffbd
Add to the test to cover the `fmt::Debug` impl without checking the
actual text.
Change one of the opcodes so that the display of the special case OP_0
is checked.
The tests for both `Script` and `ScriptBuf` `as_ref` and `as_mut` only
covered the `u8` impl.
Expand the tests to cover the `Self` impl as well.
The allow useless_asref is required to remove a clippy lint. Removing
the "useless" as_ref also removes the test coverage of the as_ref or
as_mut impl.
35ca48a85c primitives: Document script to/from bytes (Tobin C. Harding)
Pull request description:
The byte slice/vector in the to/from methods for the script types does not include the length prefix that is used when consensus encoding.
Add docs to make this more clear.
ACKs for top commit:
apoelstra:
ACK 35ca48a85cd90fc9c1b13da439177a4772c1c330; successfully ran local tests; yeah, I like this
Tree-SHA512: 6efeddfd8fe9e5bb32a6d40ca1a0fa3aa686047ad9f4cb865e3c70f8339cd39c18daa01441a1a5898300b1e73150b39c53d507af528830bbd68904148b65ef35
Not all the fields within `block::Header` implement `Display` however
a block header can reasonably be displayed by using 160 hex characters.
Implement `Display` for `block::Header` by printing the header in hex in
the same layout as we hash it in `block_hash`.
a5f904559d primitives: Make hex optional (Tobin C. Harding)
Pull request description:
Make the `hex` dependency optional. This means not implementing
`Display` for some types if `hex` is not enabled and only implementing
`Debug`.
Also without `hex` enabled:
- We loose the ability to parse an `OutPoint` from string because we
can no longer parse `Txid`.
- We loose the hex formatting of witness elements.
Note also that `primitives` builds with the `serde` feature even if
`hex?/serde` is excluded from the `serde` feature. I found this
surprising.
Close: #4183
ACKs for top commit:
apoelstra:
ACK a5f904559d3b5d2dfbcbed8b1746305e32103fee; successfully ran local tests
Tree-SHA512: c105e089508036af8251cb923f3eda163b8f2d6151ea043aa1489edb6ce396975d1f598a240f4ca6e48f6ef780774f7d86cb70ec9399f3d2ff87c0ac53ceee91
7e1369b3f1 Cover all TryFrom implementations in Script (Jamil Lambert, PhD)
6dfa3d8f4d Update test to increase coverage (Jamil Lambert, PhD)
Pull request description:
Update test in borrowed to cover the `default` implementation of `Script`.
Add tests to cover all `TryFrom` implementations in `Script`
ACKs for top commit:
apoelstra:
ACK 7e1369b3f1a7789b2757951c2e3ff58937442200; successfully ran local tests
tcharding:
ACK 7e1369b3f1
Tree-SHA512: 766b8eb63abbb1f10670f42b3789a8a4d4d73470ade13f14a1140d4cdd93b49d79865645d49f404774d8ff7aeb22b68059275902dc063d2baaf79fc8a89dca95
The byte slice/vector in the to/from methods for the script types does
not include the length prefix that is used when consensus
encoding.
Add docs to make this more clear.
Make the `hex` dependency optional. This means not implementing
`Display` for some types if `hex` is not enabled and only implementing
`Debug`.
Also without `hex` enabled:
- We loose the ability to parse an `OutPoint` from string because we
can no longer parse `Txid`.
- We loose the hex formatting of witness elements.
Note also that `primitives` builds with the `serde` feature even if
`hex?/serde` is excluded from the `serde` feature. I found this
surprising.
The `default` implementation is missed in the test coverage.
Change calling `new()` to using the `default` implementation, which then
calls `new()` anyway.
merge-script
Andrew Poelstra
Jamil Lambert, PhD
Fmt Bot
aagbotemi
Shing Him Ng