units: remove Denomination::MicroBitcoin
What changed, and why it matters
This commit removes support for the old 'microbitcoin' unit (uBTC/µBTC) from the Rust Bitcoin library and tells users to use 'bits' instead, since both mean the same 100-satoshi unit. It is a deliberate API cleanup, not a security fix. The change could break applications that still parse or display uBTC strings, but it does not create a vulnerability.
Treat as a normal breaking-change review. If you depend on rust-bitcoin's amount parsing, verify that no code or data still uses uBTC/µBTC strings; replace them with 'bits'. No security patch or incident response is indicated.
Security signals we found
No security-relevant code change: purely a denomination naming/API cleanup.
Breaking change: previously accepted input strings (uBTC/µBTC forms) now fail to parse.
Error message now explicitly guides users to the 'bits' replacement.
No memory safety, cryptographic, or authorization changes observed.
Evidence from the diff
The patch deletes the Denomination::MicroBitcoin enum variant and stops parsing ‘uBTC’, ‘ubtc’, ‘µBTC’, and ‘µbtc’. The equivalent ‘bit’/’bits’ variant remains. Error handling is updated so UnknownDenominationError carries a flag indicating whether the rejected input was a deprecated micro-bitcoin form, and the display message advises using bits. Tests are adjusted accordingly. The commit is a breaking API change for users relying on micro-bitcoin forms, with no evidence of a security defect being fixed.
Changed components
units/src/amount/mod.rs (Denomination enum and parsing)units/src/amount/error.rs (UnknownDenominationError struct)units/src/amount/tests.rs (test updates)Inspect 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 21/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.