We would like to return an error when doing math ops on amount types.
We cannot however use the stdlib `Result` or `Option` because we want to
implement ops on the result type.
Add an `AmountOpResult` type. Return this type from all math operations
on `Amount` and `SignedAmount`.
Implement `core::iter::Sum` for the new type to allow summing iterators
of amounts - somewhat ugly to use, see tests for example usage.
13a3f490b8 Use Self instead of amount type (Tobin C. Harding)
34e3049ae0 Use sats instead of satoshi (Tobin C. Harding)
00b71a670f Use from_sat_unchecked for hardcoded ints (Tobin C. Harding)
8fdec67f7d Change local var ua to sat (Tobin C. Harding)
c6f056672b Change local var sa to ssat (Tobin C. Harding)
f3e853e07a units: Do trivial refactor of amount::tests (Tobin C. Harding)
dbec9807f9 Shorten identifiers by removing _in_sats (Tobin C. Harding)
154a4420fc Stop using FQP on Amount type (Tobin C. Harding)
8e16a48252 Run the formatter (Tobin C. Harding)
Pull request description:
Do a bunch of refactorings to tease out changes from #3794.
The first 8 are uncontroversial. The 9th one is subjective. The last one is unusual but IMO worth doing because of the relationship between the two amount modules.
Do note that this PR is 100% internal changes - please please don't bike shed this to death.
ACKs for top commit:
apoelstra:
ACK 13a3f490b80e4c8f8e1753111a914315eefd73e6; successfully ran local tests; lgtm
Tree-SHA512: e2ef0e7fbdaaf632a9840920a227a901fbeb55a29398013cd6cb764b1ff7c0a7c5a1648fd8f606e8b5f7523943886f5eff54cf4054d24349feb72f0b4de05b91
We have an `_unchecked` amount constructor that makes no assumptions
about the argument. We would like to start enforcing MAX_MONEY but the
diff to introduce this is massive. In an effort to make it smaller we
can do all the hardcoded ints first. We did this already but a bunch
more snuck in or were missed.
In any amount constructor that passes in a hardcoded const as a decimal
integer (i.e., not hex) use the `_unchecked` version.
Done in preparation for enforcing MAX_MONEY.
4dcdf73cfa Add `µBTC` and `µbtc` to tests (Jamil Lambert, PhD)
afba28e188 Change `uBTC` to `µBTC` in rustdocs (Jamil Lambert, PhD)
2ca24f00f2 Add `µBTC` as a recognized `str` form of `uBTC` (Jamil Lambert, PhD)
Pull request description:
`µ` is the correct letter for the SI unit micro but is not on most standard keyboards. `u` was used instead because it looks similar.
Add `µBTC` to the list of recognized strings for MicroBitcoin. This is an addition only, `uBTC` still works as normal.
Change `uBTC` to `µBTC` in the rustdocs. The examples have been left as `uBTC` since this is easier for most people to use.
Add `µBTC` and `µbtc` to the tests.
Close#3941
ACKs for top commit:
apoelstra:
ACK 4dcdf73cfa896b2c095cda9064c6e0a0e9aeec2b; successfully ran local tests
storopoli:
ACK 4dcdf73cfa
tcharding:
ACK 4dcdf73cfa
Tree-SHA512: 0f6e8b8b9c04f1a4dc6536c0420b2ded568ab96d2301b7d488807cb26003b91a787a6cf9023705c731682580f73ae5247f3f3b1e8646e4eb720c5a65da582933
bfba2a85dd Kill remaining mutants (Shing Him Ng)
871fa08f61 Fix typo in serde docs (Shing Him Ng)
462c7a1130 Add weekly cargo-mutants workflow (Shing Him Ng)
Pull request description:
This PR introduces `cargo-mutants` via a Github weekly workflow, similar to how the formatter job runs. It can also be updated to run against [incremental changes in a PR](https://mutants.rs/pr-diff.html) or to create an issues that list the new mutants. To address #3796, I've configured it to only run in `units` for now since that's nearing 1.0.
Here's a [sample run](https://github.com/shinghim/rust-bitcoin/actions/runs/12457984710) i did in my fork, if anyone would like to see what's in the `mutants-out` artifact that gets generated.
ACKs for top commit:
tcharding:
ACK bfba2a85dd
apoelstra:
ACK bfba2a85ddaad6b366a7502cbda1ff2462dfd4c7; successfully ran local tests
Tree-SHA512: e4a44b6f5121e4238c1c3576616f551f4f43349cf5fd5ac1d6331f958a4458753a55519bdafc16965cb2e67201ef6c91b188c79ffcc222f780c421df9a701063
7482fcd934 Run just check-api (jrakibi)
bcc38c40e0 Add Amount division by FeeRate (jrakibi)
Pull request description:
Add checked_div_by_fee_rate method to Amount that computes the maximum weight for a transaction with a given fee rate. This complements the existing `fee = fee_rate * weight `and `fee_rate = fee / weight` operations
- Add `checked_div_by_fee_rate` method that returns Option<Weight>
- Implement` Div<FeeRate>` for Amount for operator syntax support
- Use `floor` division to ensure weight doesn't exceed intended fee
This allows calculating the maximum transaction weight possible for a given fee amount and fee rate.
Closes#3814
ACKs for top commit:
apoelstra:
ACK 7482fcd934c09e3cd6cd25fd4328960b02f8e976; successfully ran local tests
tcharding:
ACK 7482fcd934
Tree-SHA512: 622ca42bde1f67782a3c2996efcba0132fedb5e984f594603aece974de6acdeb4b22d63239d29d46fb8623c8082841c33b1d5b9ad2ea51e2f63e6f5d859daa7e
Implement `checked_div_by_fee_rate_floor` and `checked_div_by_fee_rate_ceil` methods to compute the maximum and minimum transaction weights.
These methods provide precise weight calculations using both floor and ceiling divisions.
- Introduce `checked_div_by_fee_rate_floor` for floor-based weight division.
- Add `checked_div_by_fee_rate_ceil` for ceiling-based weight division.
- Update `ops::Div` implementation for `Amount` to use floor division by default.
- Include unit tests to validate both floor and ceiling division methods.
As we do in other places in the `amount::tests` module; use a local
`sat` variable bound to the `Amount::from_sat` constructor.
Internal change, no logic changes.
As we do in other places in the `amount::tests` module; use a local
`ssat` variable bound to the `SignedAmount::from_sat` constructor.
Internal change, no logic changes.
Reorder assertions in `units::amount::tests` to follow got, want order
Makes debugging easier, as there's no need to check the test to verify the order.
We have a `_unchecked` constructor now for both `Amount` and
`SignedAmount`. In preparation for enforcing the `MAX_MONEY` invariant
use the `_unchecked` constructor throughout the codebase to construct
amounts from hard coded integer values.
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
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.
We now have both `Amount::from_sat_unchecked` and
`SignedAmount::from_sat_unchecked`. These constructors are explicitly
for ignoring any invariant (implied or otherwise) especially in test
code.
Note we do not enforce an invariant currently. This patch is a baby step
towards getting the `amount` module in order.
Replace all calls to `from_sat` for const int values with the
`_unchecked` constructor. Done in `amount::tests` only.
As we did for `SignedAmount` add a constructor to the `Amount` type that
does no checks on its argument.
(This is in preparation for enforcing the MAX_MONEY invariant.)
Use the `_unchecked` version in a single unit test. The rest of the unit
tests will be refactored later to minimise the size of this patch.
As we already do in this test function for other constructors; add a
local variable and bind it to the `SignedAmount::from_sat` constructor.
Refactor only, no logic change.
e13355318e Add From impl (yancy)
364e9ff775 Change method return type (yancy)
fdf3336ed5 Add unchecked variant (yancy)
Pull request description:
Any SignedAmount can now be cast to Amount since the range is the same. Specifically, the range for SignedAmount is (- 21 million, 21 million) while the range for Amount is (0, 21 million). Therefore any value from Amount can be cast to a SignedAmount and it will work. Note it's not the same and still requires checking when going from SignedAmount to Amount since Amount can't handle the negative range.
ACKs for top commit:
tcharding:
ACK e13355318e
Tree-SHA512: c016b51bdd87a12eb09d9c1a82699dad1e866bf96bd3235eeb131f216f02422acb992ddb3a8135af00bbc10e240178fde5e37fb7860d9e6eaf433cf917d4d16a
Any SignedAmount can now be cast to Amount since the range is the same.
Specifically, the range for SignedAmount is (- 21 million, 21 million)
while the range for Amount is (0, 21 million). Therefore any value from
Amount can be cast to a SignedAmount and it will work. Note it's not
the same and still requires checking when going from SignedAmount to
Amount since Amount can't handle the negative range.
As a side effect of changing the return type, TryFrom is no longer valid
and does not compile. Therefore in addition to changing the return
type, TryFrom is also removed.
f08d8741d3 Test types MIN/MAX instead of i64::MIN/i64::MAX (yancy)
Pull request description:
The MIN/MAX for SignedAmount recently changed from i64::MIN and i64::MAX to MAX_MONEY/MIN_MONEY. Update the tests to reflect this new MIN/MAX since it is no longer valid to create a value above or bellow MAX_MONEY/MIN_MONEY.
ACKs for top commit:
apoelstra:
ACK f08d8741d39685b636830680bb891bd414826e88; successfully ran local tests
tcharding:
ACK f08d8741d3
Tree-SHA512: 563408240dffaf95f88a9d570e56f9b9b161b422cb59a89828c18b9c784e7acb717f57fe55c80411f104443ac2a3f908f2a98ab1a4b34edab69b6946a723b30c
2513e05501 api: Run just check-api (Tobin C. Harding)
9619f68956 units: Move excluded lints to manifest (Tobin C. Harding)
5290a93a38 units: Add all pedantic lints (Tobin C. Harding)
Pull request description:
Add all pedantic clippy lints but leave a few marked as TODO.
The coment on the list claims to it is an exhaustive list of pedantic lints, that claim is going to go stale. I would be nice if we had tooling to catch new lints as they were added.
ACKs for top commit:
apoelstra:
ACK 2513e05501e3a014c097f24eb9178c291785db81; successfully ran local tests
Tree-SHA512: 33b2a7448d49d6a5571c9e4e9922b6042ab03aaaa9f7acad243a926f8a03a0ffed75d4f5f37be4705f23862c32f96879582214cd17c7e5ab81e47517a84745e0
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`
The MIN/MAX for SignedAmount recently changed from i64::MIN and
i64::MAX to MAX_MONEY/MIN_MONEY. Update the tests to reflect this new
MIN/MAX since it is no longer valid to create a value above or bellow
MAX_MONEY/MIN_MONEY.
68f3c3e5d7 api: Run just check-api (Tobin C. Harding)
b956940a6d Add ops unit tests for amount types (Tobin C. Harding)
d88306fb68 units: Implement ops for amount types (Tobin C. Harding)
4a3aa4a08b Add ops unit tests for Weight (Tobin C. Harding)
43ef9a618c units: Implement ops for Weight (Tobin C. Harding)
c5fbc7e117 units: Add assign macros (Tobin C. Harding)
20a79da344 units: Use one level of path for ops traits (Tobin C. Harding)
6ce5385914 units: Add macros for Add and Sub (Tobin C. Harding)
b31ca72b33 units: Use rhs instead of other (Tobin C. Harding)
cd0fa2d1dc Make FeeRate ops impls more terse (Tobin C. Harding)
Pull request description:
Sort out `Add`, `AddAssign`, `Sub`, and `SubAssign` for the following types:
- `Amount`
- `SignedAmount`
- `FeeRate`
- `Weight`
And clean up as we go.
Note that `BlockInterval` isn't touched in this PR - it looks correct already.
The unit tests in the two patches "Add ops tests ..." can be moved if you want to verify that they don't build without the patch they follow.
ACKs for top commit:
apoelstra:
ACK 68f3c3e5d728a60a4b52ca64523770bcdd32f957; successfully ran local tests
Tree-SHA512: a82d3bf288f61b169b8cff498e81bd2cd123c8dcbf534413233ff03f06102a42508e09b2f7e5b268b21f82d4bf2b3612cd88dea1231b4d3e6455c7e99f82e729
183ecf1fe6 Add units tests for cBTC (Tobin C. Harding)
Pull request description:
We added the "cBTC" denomination but forgot to test it.
Add units test for "cBTC" as we do for the other denominations. Put all the tests lines of code in the same order as the enum variants so a reader can see easily that all cases are tested.
ACKs for top commit:
apoelstra:
ACK 183ecf1fe6944187151036e36d6726fae9b64392; successfully ran local tests
Tree-SHA512: 93a3f3e5430f7b6f525d7c55ad3d318f8b30fef8cdef24ea92a1687e898f73d3829875861f026af70dde013743d310d87331b5654b524f4ee90c20f7e6ed7f7c
We added the "cBTC" denomination but forgot to test it.
Add units test for "cBTC" as we do for the other denominations. Put all
the tests lines of code in the same order as the enum variants so a
reader can see easily that all cases are tested.
We have multiple constructors for `Amount`, one of which accepts an
integer representing whole bitcoin.
In an attempt to make the API crystal clear change the parameter type
used for whole bitcoin to either `Into<u64>` or `u32` instead of a
`u64` which may well be mapped to sats in the mind of developers (it
is in mine anyway).
To prevent rounding errors converting to and from f64 change
`SignedAmount` `MAX` and `MIN` to +/- `MAX_MONEY` which are within the
limit in f64 that has issues.
Add checks to `from_str_in`, `checked_add`, `checked_sub` and
`checked_mul` that the result is within MIN and MAX.
Modify tests to work with new `MIN` and `MAX`
c27f443520 Add basic unit tests for Amount serde (Tobin C. Harding)
22530f6a2b Support serde serializing Amount as string (Tobin C. Harding)
Pull request description:
Sometimes JSON parsers may munge floats. Instead of using `f64` we can serialize BTC amounts as strings.
Close: #894
ACKs for top commit:
apoelstra:
ACK c27f4435208cc3ca7b98580fd7e2784e089b545e; successfully ran local tests
sanket1729:
utACK c27f443520.
Tree-SHA512: 084669a0622557b75fceae732fb485e7139ecada48c0b65642d122e1a02f6f7e41564c3579fd10adbf3aa14c82c9f10abc3f9201858e50b729852140b31a4216
To prevent rounding errors converting to and from f64 change
`Amount::MAX` to `MAX_MONEY` which is below the limit in f64 that has
issues.
Add checks to `from_str_in`, `checked_add` and `checked_mul` that the
result is below MAX, where previously a u64 overflow was relied on.
Change tests to account for new lower MAX that is within the range of
SignedAmount and does not overflow so easily
Remove overflow tests
`Amount::MAX` is now below `u64::MAX` and within the range of values for
`SignedAmount`. These tests therefore do not overflow.
In effective_value there is no error with `Amount::MAX` and the correct
value is returned.
In psbt the removed test is effectively the same as the previous test.
Modify `Amount` tests to work with new `MAX`
Tests need to be changed that checked values above the new `MAX` or
`Amount::MAX` was out of range for `SignedAmount` which it isn't anymore
Sometimes JSON parsers may munge floats. Instead of using `f64` we can
serialize BTC amounts as strings.
Includes addition of `alloc` feature gate to `DisplayFullError` to
remove lint warnings when building with `--no-default-features`.
Close: #894
fd2a5c1ec7 Close amounts error types (Tobin C. Harding)
23c77275b1 Reduce code comment lines (Tobin C. Harding)
d595f421c6 Remove whitespace between enum variants (Tobin C. Harding)
Pull request description:
Close the two pubic enum error types in `units::amounts`. All the other structs are closed already because they either have private fields or marked `non_exhaustive`.
ACKs for top commit:
apoelstra:
ACK fd2a5c1ec79f337fb3695c030c9fb6b4671468f2; successfully ran local tests; thanks!
Tree-SHA512: f8d68ef821449e0829c926cf527df4b226b29c8d1d41b320a016fbf70b4b39cc54c8c218955caa0c3776158eeeae0ebacc1cc89dab67bafc399b94063324ab0e
Close the two pubic enum error types in `units::amounts`. All the other
structs are closed already because they either have private fields or
marked `non_exhaustive`.
Tobin C. Harding
merge-script
Jamil Lambert, PhD
Shing Him Ng
jrakibi
Fmt Bot
yhzlsm
yancy