Merge rust-bitcoin/rust-bitcoin#7167: units: remove `Denomination::MicroBitcoin`
What changed, and why it matters
This is a routine API cleanup, not a security fix. The change removes one way of naming a Bitcoin unit ('MicroBitcoin' / 'uBTC') and keeps the equivalent 'bits' form. Any code that previously used the old name will fail to compile or fail to parse those strings, but there is no vulnerability being fixed and no new attack path being opened.
No security action required. Downstream users should update code that references Denomination::MicroBitcoin or parses 'uBTC'/'µBTC' strings to use Denomination::Bit and 'bits' instead.
Security signals we found
No security signal: public API deprecation and enum variant removal
No memory safety, cryptographic, or consensus code modified
Error message change is informational only
Evidence from the diff
The commit removes the Denomination::MicroBitcoin enum variant from rust-bitcoin’s units crate and stops parsing ‘uBTC’ / ‘µBTC’ strings. It maps the same 100-satoshi magnitude to the existing Denomination::Bit (‘bits’) and adds a deprecation hint in the parse error. This is a breaking public API change intended to simplify Ord/Eq derivation and reduce user confusion. No memory-safety, cryptographic, or consensus-critical change is present.
Changed components
units/src/amount/mod.rsunits/src/amount/error.rsunits/src/amount/tests.rsInspect captured patch +53 / −40
### units/src/amount/error.rs
@@ -417,7 +417,12 @@ impl std::error::Error for MissingDenominationError {
/// Error returned when parsing an unknown denomination.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
-pub struct UnknownDenominationError(pub(super) InputString);
+pub struct UnknownDenominationError {
+ /// The string that failed to parse.
+ pub(super) input: InputString,
+ /// Whether the input was a micro-bitcoin form, which has been deprecated.
+ pub(super) is_micro_bitcoin: bool,
+}
impl From<Infallible> for UnknownDenominationError {
#[inline]
@@ -427,15 +432,19 @@ impl From<Infallible> for UnknownDenominationError {
impl fmt::Display for UnknownDenominationError {
#[inline]
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
- self.0.unknown_variant("bitcoin denomination", f)
+ self.input.unknown_variant("bitcoin denomination", f)?;
+ if self.is_micro_bitcoin {
+ f.write_str(", micro bitcoin must be expressed as bits")?;
+ }
+ Ok(())
}
}
#[cfg(feature = "std")]
impl std::error::Error for UnknownDenominationError {
#[inline]
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
- let Self(_) = self;
+ let Self { input: _, is_micro_bitcoin: _ } = self;
None
}
}
### units/src/amount/mod.rs
@@ -89,10 +89,12 @@ pub use self::unsigned::{AmountDecoder, AmountEncoder};
///
/// # Accepted Denominations
///
-/// All upper or lower case, excluding SI prefixes c, m and u (or µ) which must be lower case.
-/// - Singular: BTC, cBTC, mBTC, uBTC
+/// All upper or lower case, excluding SI prefixes c and m which must be lower case.
+/// - Singular: BTC, cBTC, mBTC
/// - Plural or singular: sat, satoshi, bit
///
+/// We no longer parse "uBTC" and "µBTC". Please use "bits" instead.
+///
/// # Note
///
/// Due to ambiguity between mega and milli we prohibit usage of leading capital 'M'. It is
@@ -109,7 +111,6 @@ pub use self::unsigned::{AmountDecoder, AmountEncoder};
/// ("1 BTC", 100_000_000),
/// ("1 cBTC", 1_000_000),
/// ("1 mBTC", 100_000),
-/// ("1 uBTC", 100),
/// ("1 bit", 100),
/// ("1 sat", 1),
/// ];
@@ -131,9 +132,8 @@ pub enum Denomination {
CentiBitcoin,
/// mBTC (1 mBTC = 100,000 satoshi).
MilliBitcoin,
- /// µBTC (1 µBTC = 100 satoshi).
- MicroBitcoin,
- /// bits (bits = µBTC).
+ /// bits (1 bit = 1 µBTC = 100 satoshi).
+ #[doc(alias("MicroBitcoin", "uBTC", "µBTC"))]
Bit,
/// satoshi (1 BTC = 100,000,000 satoshi).
Satoshi,
@@ -157,7 +157,6 @@ impl Denomination {
Self::Bitcoin => -8,
Self::CentiBitcoin => -6,
Self::MilliBitcoin => -5,
- Self::MicroBitcoin => -2,
Self::Bit => -2,
Self::Satoshi => 0,
Self::_DoNotUse(infallible) => match infallible {},
@@ -171,7 +170,6 @@ impl Denomination {
Self::Bitcoin => "BTC",
Self::CentiBitcoin => "cBTC",
Self::MilliBitcoin => "mBTC",
- Self::MicroBitcoin => "uBTC",
Self::Bit => "bits",
Self::Satoshi => "satoshi",
Self::_DoNotUse(infallible) => match infallible {},
@@ -185,7 +183,6 @@ impl Denomination {
"BTC" | "btc" => Some(Self::Bitcoin),
"cBTC" | "cbtc" => Some(Self::CentiBitcoin),
"mBTC" | "mbtc" => Some(Self::MilliBitcoin),
- "uBTC" | "ubtc" | "µBTC" | "µbtc" => Some(Self::MicroBitcoin),
"bit" | "bits" | "BIT" | "BITS" => Some(Self::Bit),
"SATOSHI" | "satoshi" | "SATOSHIS" | "satoshis" | "SAT" | "sat" | "SATS" | "sats" =>
Some(Self::Satoshi),
@@ -197,7 +194,10 @@ impl Denomination {
/// These forms are ambiguous and could have many meanings. For example, M could denote Mega or Milli.
/// If any of these forms are used, an error type [`PossiblyConfusingDenominationError`] is
/// returned.
-const CONFUSING_FORMS: [&str; 6] = ["CBTC", "Cbtc", "MBTC", "Mbtc", "UBTC", "Ubtc"];
+const CONFUSING_FORMS: [&str; 4] = ["CBTC", "Cbtc", "MBTC", "Mbtc"];
+
+/// Forms of micro-bitcoin, which has been deprecated.
+const MICRO_BITCOIN_FORMS: [&str; 6] = ["uBTC", "ubtc", "µBTC", "µbtc", "UBTC", "Ubtc"];
impl fmt::Display for Denomination {
#[inline]
@@ -212,7 +212,7 @@ impl FromStr for Denomination {
/// # Errors
///
/// - [`ParseDenominationError::PossiblyConfusing`]: If the denomination begins with a capital
- /// letter that could be confused with centi, milli, or micro-bitcoin.
+ /// letter that could be confused with centi or milli-bitcoin.
/// - [`ParseDenominationError::Unknown`]: If an unknown denomination is used.
fn from_str(s: &str) -> Result<Self, Self::Err> {
use self::ParseDenominationError as E;
@@ -223,7 +223,11 @@ impl FromStr for Denomination {
let form = Self::forms(s);
- form.ok_or_else(|| UnknownDenominationError(s.into())).map_err(E::Unknown)
+ form.ok_or_else(|| UnknownDenominationError {
+ input: s.into(),
+ is_micro_bitcoin: MICRO_BITCOIN_FORMS.contains(&s),
+ })
+ .map_err(E::Unknown)
}
}
@@ -702,13 +706,12 @@ enum DisplayStyle {
impl<'a> Arbitrary<'a> for Denomination {
#[inline]
fn arbitrary(u: &mut Unstructured<'a>) -> arbitrary::Result<Self> {
- let choice = u.int_in_range(0..=5)?;
+ let choice = u.int_in_range(0..=4)?;
match choice {
0 => Ok(Self::Bitcoin),
1 => Ok(Self::CentiBitcoin),
2 => Ok(Self::MilliBitcoin),
- 3 => Ok(Self::MicroBitcoin),
- 4 => Ok(Self::Bit),
+ 3 => Ok(Self::Bit),
_ => Ok(Self::Satoshi),
}
}
### units/src/amount/tests.rs
@@ -79,7 +79,7 @@ fn check_if_num_is_too_precise() {
#[test]
#[cfg(feature = "alloc")]
fn from_str_zero() {
- let denoms = ["BTC", "cBTC", "mBTC", "uBTC", "bits", "sats"];
+ let denoms = ["BTC", "cBTC", "mBTC", "bits", "sats"];
for denom in denoms {
for v in &["0", "000"] {
let s = format!("{} {}", v, denom);
@@ -806,13 +806,13 @@ fn from_str() {
assert_eq!(
"xBTC".parse::<Amount>(),
Err(ParseError(ParseErrorInner::Denomination(ParseDenominationError::Unknown(
- UnknownDenominationError("xBTC".into())
+ UnknownDenominationError { input: "xBTC".into(), is_micro_bitcoin: false }
)))),
);
assert_eq!(
"5 BTC BTC".parse::<Amount>(),
Err(ParseError(ParseErrorInner::Denomination(ParseDenominationError::Unknown(
- UnknownDenominationError("BTC BTC".into())
+ UnknownDenominationError { input: "BTC BTC".into(), is_micro_bitcoin: false }
)))),
);
assert_eq!(
@@ -827,7 +827,7 @@ fn from_str() {
assert_eq!(
"5 5 BTC".parse::<Amount>(),
Err(ParseError(ParseErrorInner::Denomination(ParseDenominationError::Unknown(
- UnknownDenominationError("5 BTC".into())
+ UnknownDenominationError { input: "5 BTC".into(), is_micro_bitcoin: false }
)))),
);
@@ -857,7 +857,17 @@ fn from_str() {
case(
"5 BCH",
- &Err(denom_err(ParseDenominationError::Unknown(UnknownDenominationError("BCH".into())))),
+ &Err(denom_err(ParseDenominationError::Unknown(UnknownDenominationError {
+ input: "BCH".into(),
+ is_micro_bitcoin: false,
+ }))),
+ );
+ case(
+ "200 uBTC",
+ &Err(denom_err(ParseDenominationError::Unknown(UnknownDenominationError {
+ input: "uBTC".into(),
+ is_micro_bitcoin: true,
+ }))),
);
case("-1 BTC", &Err(parse_err(ParseAmountErrorInner::OutOfRange(OutOfRangeError::negative()))));
@@ -966,11 +976,6 @@ fn to_from_string_in() {
assert_eq!("100", sat(100_000_00).to_string_in(D::MilliBitcoin));
assert_eq!("-100", ssat(-100_000_00).to_string_in(D::MilliBitcoin));
- assert_eq!("2535.83", sat(253_583).to_string_in(D::MicroBitcoin));
- assert_eq!("-2535.83", ssat(-253_583).to_string_in(D::MicroBitcoin));
- assert_eq!("100000", sat(100_000_00).to_string_in(D::MicroBitcoin));
- assert_eq!("-100000", ssat(-100_000_00).to_string_in(D::MicroBitcoin));
-
assert_eq!("0.5", sat(50).to_string_in(D::Bit));
assert_eq!("100", sat(10_000).to_string_in(D::Bit));
assert_eq!("-0.5", ssat(-50).to_string_in(D::Bit));
@@ -991,24 +996,22 @@ fn to_from_string_in() {
ua_str(&sat(1_000_000_000_000).to_string_in(D::MilliBitcoin), D::MilliBitcoin),
Ok(sat(1_000_000_000_000))
);
- assert_eq!(ua_str(&sat(1).to_string_in(D::MicroBitcoin), D::MicroBitcoin), Ok(sat(1)));
assert_eq!(ua_str(&sat(21_000_000).to_string_in(D::Bit), D::Bit), Ok(sat(21_000_000)));
assert_eq!(ua_str(&sat(0).to_string_in(D::Satoshi), D::Satoshi), Ok(sat(0)));
assert!(ua_str(&Amount::MAX.to_string_in(D::Bitcoin), D::Bitcoin).is_ok());
assert!(ua_str(&Amount::MAX.to_string_in(D::CentiBitcoin), D::CentiBitcoin).is_ok());
assert!(ua_str(&Amount::MAX.to_string_in(D::MilliBitcoin), D::MilliBitcoin).is_ok());
- assert!(ua_str(&Amount::MAX.to_string_in(D::MicroBitcoin), D::MicroBitcoin).is_ok());
assert!(ua_str(&Amount::MAX.to_string_in(D::Bit), D::Bit).is_ok());
assert!(ua_str(&Amount::MAX.to_string_in(D::Satoshi), D::Satoshi).is_ok());
assert_eq!(
- sa_str(&SignedAmount::MAX.to_string_in(D::Satoshi), D::MicroBitcoin),
+ sa_str(&SignedAmount::MAX.to_string_in(D::Satoshi), D::Bit),
Err(amt_err(ParseAmountErrorInner::OutOfRange(OutOfRangeError::too_big(true))))
);
// Test an overflow bug in `abs()`
assert_eq!(
- sa_str(&SignedAmount::MIN.to_string_in(D::Satoshi), D::MicroBitcoin),
+ sa_str(&SignedAmount::MIN.to_string_in(D::Satoshi), D::Bit),
Err(amt_err(ParseAmountErrorInner::OutOfRange(OutOfRangeError::too_small())))
);
}
@@ -1023,20 +1026,19 @@ fn to_string_with_denomination_from_str_roundtrip() {
assert_eq!(denom(amt, D::Bitcoin).parse::<Amount>(), Ok(amt));
assert_eq!(denom(amt, D::CentiBitcoin).parse::<Amount>(), Ok(amt));
assert_eq!(denom(amt, D::MilliBitcoin).parse::<Amount>(), Ok(amt));
- assert_eq!(denom(amt, D::MicroBitcoin).parse::<Amount>(), Ok(amt));
assert_eq!(denom(amt, D::Bit).parse::<Amount>(), Ok(amt));
assert_eq!(denom(amt, D::Satoshi).parse::<Amount>(), Ok(amt));
assert_eq!(
"42 satoshi BTC".parse::<Amount>(),
Err(ParseError(ParseErrorInner::Denomination(ParseDenominationError::Unknown(
- UnknownDenominationError("satoshi BTC".into())
+ UnknownDenominationError { input: "satoshi BTC".into(), is_micro_bitcoin: false }
))))
);
assert_eq!(
"-42 satoshi BTC".parse::<SignedAmount>(),
Err(ParseError(ParseErrorInner::Denomination(ParseDenominationError::Unknown(
- UnknownDenominationError("satoshi BTC".into())
+ UnknownDenominationError { input: "satoshi BTC".into(), is_micro_bitcoin: false }
)))),
);
}
@@ -1079,9 +1081,8 @@ fn sum_amounts() {
fn denomination_string_acceptable_forms() {
// Exhaustive list of valid forms.
let valid = [
- "BTC", "btc", "cBTC", "cbtc", "mBTC", "mbtc", "uBTC", "ubtc", "µBTC", "µbtc", "bit",
- "bits", "BIT", "BITS", "SATOSHI", "satoshi", "SATOSHIS", "satoshis", "SAT", "sat", "SATS",
- "sats",
+ "BTC", "btc", "cBTC", "cbtc", "mBTC", "mbtc", "bit", "bits", "BIT", "BITS", "SATOSHI",
+ "satoshi", "SATOSHIS", "satoshis", "SAT", "sat", "SATS", "sats",
];
for denom in valid {
assert!(denom.parse::<Denomination>().is_ok());
@@ -1090,7 +1091,7 @@ fn denomination_string_acceptable_forms() {
#[test]
fn disallow_confusing_forms() {
- let confusing = ["CBTC", "Cbtc", "MBTC", "Mbtc", "UBTC", "Ubtc"];
+ let confusing = ["CBTC", "Cbtc", "MBTC", "Mbtc"];
for denom in confusing {
match denom.parse::<Denomination>() {
Ok(_) => panic!("from_str should error for {}", denom),
@@ -1103,7 +1104,7 @@ fn disallow_confusing_forms() {
#[test]
fn disallow_unknown_denomination() {
// Non-exhaustive list of unknown forms.
- let unknown = ["NBTC", "ABC", "abc", "mSat", "msat"];
+ let unknown = ["NBTC", "ABC", "abc", "mSat", "msat", "uBTC", "ubtc", "µBTC", "µbtc", "UBTC"];
for denom in unknown {
match denom.parse::<Denomination>() {
Ok(_) => panic!("from_str should error for {}", denom),Why this scored 24/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.