Everything That Changed in bitcoin-units 1.0

EN AI Assisted Writing · Claude 3 min read

The public API delta of bitcoin-units from the 0.32 era to 1.0, type by type.

bitcoin open source rust rust-bitcoin
Table of Contents

Every public API change between the bitcoin 0.32 era units and bitcoin-units 1.0, grouped by type. Use it as a checklist when migrating a crate.

Generated with cargo public-api on bitcoin-units 0.1.101 (the 0.32.xxx compat branch) against bitcoin-units 1.0.0, default features. Types marked “moved in” lived in bitcoin or primitives during 0.32, so for those the old side is the bitcoin 0.32 type.

Crate wide

  • Checked arithmetic between typed values goes through NumOpResult<T> (new result module with NumOpError and MathOp).
  • CheckedSum is gone. Sum with iter.map(NumOpResult::from).sum::<NumOpResult<T>>().
  • *Assign operator impls on Amount and SignedAmount are gone. FeeRate and Weight gained theirs.
  • Every error type moved into a per-module error submodule, implements source(), and lost ad hoc constructors (TimeOverflowError::new, ParseIntError::input()).
  • Most integer newtypes gained from_hex (0x prefixed) and from_unprefixed_hex. The parse module grew hex_u16 through hex_u128 with prefixed and unprefixed variants.

Amount

  • from_sat(u64) returns Result<_, OutOfRangeError>, capped at MAX_MONEY. The infallible constructors are from_sat_u32(u32) and from_btc_u16(u16).
  • from_int_btc takes impl Into<u16> instead of u64.
  • to_signed is infallible, since every capped Amount fits.
  • unchecked_add / unchecked_sub removed.
  • div_by_weight_floor / div_by_weight_ceil return NumOpResult<FeeRate> (were Option). New div_by_fee_rate_floor / _ceil returning NumOpResult<Weight>.
  • New signed_sub, from_sat_hex, from_sat_unprefixed_hex, const FIFTY_BTC.
  • Div also accepts FeeRate, Weight and NonZeroU64 divisors.

SignedAmount

  • Mirrors Amount. Fallible from_sat(i64) capped at plus or minus MAX_MONEY, new from_sat_i32, from_btc_i16, from_int_btc(impl Into<i16>), hex constructors, FIFTY_BTC. Unchecked and assign ops removed.
  • New infallible From<Amount> for SignedAmount.
  • positive_sub still returns Option.

FeeRate

  • Precision changed and constructors take u32. from_sat_per_kwu(u32) and from_sat_per_vb(u32) are infallible (were u64 -> Option). from_sat_per_vb_u32 and from_sat_per_vb_unchecked are gone. New from_sat_per_kvb(u32).
  • to_sat_per_kwu split into _floor and _ceil. New to_sat_per_kvb_floor / _ceil.
  • fee_vb, fee_wu and checked_mul_by_weight removed. Use to_fee(Weight) -> Amount or mul_by_weight(Weight) -> NumOpResult<Amount>.
  • New from_per_kwu, from_per_vb, from_per_kvb, each taking an Amount and returning NumOpResult<Self>.
  • FromStr and TryFrom<&str> removed.
  • Gained Add / Sub with assign variants, checked_add / checked_sub, Sum.

Weight

  • Removed from_vb_unwrap, from_wu_usize, from_non_witness_data_size, from_witness_data_size, scale_by_witness_factor.
  • New mul_by_fee_rate(FeeRate) -> NumOpResult<Amount>, to_kwu_ceil, Rem ops, hex constructors.

Absolute locktime

  • Time renamed MedianTimePast. On LockTime, from_time is now from_mtp, is_satisfied_by_time returns Result<bool, IncompatibleTimeError> and is_satisfied_by_height returns Result<bool, IncompatibleHeightError>.
  • On Height and MedianTimePast, from_consensus is renamed from_u32 and to_consensus_u32 is renamed to_u32. New is_satisfied_by(self, Self) and from_unprefixed_hex.
  • New MedianTimePast::new([BlockTime; 11]) computes MTP from the last eleven block timestamps.
  • absolute::LockTime moved in from bitcoin. is_satisfied_by takes (Height, MedianTimePast).

Relative locktime

  • relative::Height renamed NumberOfBlocks, relative::Time renamed NumberOf512Seconds. The old value() getters are gone.
  • relative::LockTime moved in from bitcoin. from_consensus is fallible with DisabledLockTimeError. New to_sequence / from_sequence.
  • is_satisfied_by takes four arguments (chain tip height and MTP, plus the height and MTP the UTXO was mined at) and returns Result<bool, IsSatisfiedByError>. The _height and _time variants take BlockHeight or BlockMtp pairs and return their own error enums.

Sequence (moved in)

  • The inner field is private. Sequence(n) no longer compiles, use from_consensus. In tests, Sequence(1000) became relative::LockTime::from_consensus(1000).unwrap().
  • to_relative_lock_time returns the stable relative::LockTime.
  • Gained FromStr, TryFrom<&str>, hex constructors. All predicates (is_final, is_rbf, is_height_locked, …) and consts (MAX, ZERO, FINAL, …) are present.

Pow types (moved in)

  • Target, Work and CompactTarget are units types with byte conversions, to_compact_lossy, to_work / to_target, CompactTarget::from_consensus / to_consensus, and the MAX_ATTAINABLE_* consts. Difficulty calculations that need chain params stayed in bitcoin.

Block module (new)

  • BlockHeight, BlockHeightInterval, BlockMtp, BlockMtpInterval, BlockTime. Point minus point gives an interval, point plus interval gives a point, with checked_ and saturating_ variants and From conversions to and from the locktime types. These are the argument types of the new relative is_satisfied_by family.

Removed with no direct replacement

  • trait CheckedSum, use NumOpResult sums.
  • absolute::Time and the old relative Height / Time names, all renamed.
  • FeeRate: FromStr.
More Posts