bitcoin_units/
fee_rate.rs

1// SPDX-License-Identifier: CC0-1.0
2
3//! Implements `FeeRate` and assoctiated features.
4
5use core::fmt;
6use core::ops::{Div, Mul};
7
8#[cfg(feature = "arbitrary")]
9use arbitrary::{Arbitrary, Unstructured};
10#[cfg(feature = "serde")]
11use serde::{Deserialize, Serialize};
12
13use crate::amount::Amount;
14use crate::weight::Weight;
15
16/// Represents fee rate.
17///
18/// This is an integer newtype representing fee rate in `sat/kwu`. It provides protection against mixing
19/// up the types as well as basic formatting features.
20#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
21#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
22#[cfg_attr(feature = "serde", serde(transparent))]
23pub struct FeeRate(u64);
24
25impl FeeRate {
26    /// 0 sat/kwu.
27    ///
28    /// Equivalent to [`MIN`](Self::MIN), may better express intent in some contexts.
29    pub const ZERO: FeeRate = FeeRate(0);
30
31    /// Minimum possible value (0 sat/kwu).
32    ///
33    /// Equivalent to [`ZERO`](Self::ZERO), may better express intent in some contexts.
34    pub const MIN: FeeRate = FeeRate::ZERO;
35
36    /// Maximum possible value.
37    pub const MAX: FeeRate = FeeRate(u64::MAX);
38
39    /// Minimum fee rate required to broadcast a transaction.
40    ///
41    /// The value matches the default Bitcoin Core policy at the time of library release.
42    pub const BROADCAST_MIN: FeeRate = FeeRate::from_sat_per_vb_u32(1);
43
44    /// Fee rate used to compute dust amount.
45    pub const DUST: FeeRate = FeeRate::from_sat_per_vb_u32(3);
46
47    /// Constructs `FeeRate` from satoshis per 1000 weight units.
48    pub const fn from_sat_per_kwu(sat_kwu: u64) -> Self { FeeRate(sat_kwu) }
49
50    /// Constructs `FeeRate` from satoshis per virtual bytes.
51    ///
52    /// # Errors
53    ///
54    /// Returns `None` on arithmetic overflow.
55    pub fn from_sat_per_vb(sat_vb: u64) -> Option<Self> {
56        // 1 vb == 4 wu
57        // 1 sat/vb == 1/4 sat/wu
58        // sat_vb sat/vb * 1000 / 4 == sat/kwu
59        Some(FeeRate(sat_vb.checked_mul(1000 / 4)?))
60    }
61
62    /// Constructs a new [`FeeRate`] from satoshis per virtual bytes.
63    pub const fn from_sat_per_vb_u32(sat_vb: u32) -> Self {
64        let sat_vb = sat_vb as u64; // No `Into` in const context.
65        FeeRate(sat_vb * (1000 / 4))
66    }
67
68    /// Constructs `FeeRate` from satoshis per virtual bytes without overflow check.
69    #[deprecated(since = "0.32.7", note = "use from_sat_per_vb_u32 instead")]
70    pub const fn from_sat_per_vb_unchecked(sat_vb: u64) -> Self { FeeRate(sat_vb * (1000 / 4)) }
71
72    /// Returns raw fee rate.
73    ///
74    /// Can be used instead of `into()` to avoid inference issues.
75    pub const fn to_sat_per_kwu(self) -> u64 { self.0 }
76
77    /// Converts to sat/vB rounding down.
78    pub const fn to_sat_per_vb_floor(self) -> u64 { self.0 / (1000 / 4) }
79
80    /// Converts to sat/vB rounding up.
81    pub const fn to_sat_per_vb_ceil(self) -> u64 { (self.0 + (1000 / 4 - 1)) / (1000 / 4) }
82
83    /// Checked multiplication.
84    ///
85    /// Computes `self * rhs` returning `None` if overflow occurred.
86    pub fn checked_mul(self, rhs: u64) -> Option<Self> { self.0.checked_mul(rhs).map(Self) }
87
88    /// Checked division.
89    ///
90    /// Computes `self / rhs` returning `None` if `rhs == 0`.
91    pub fn checked_div(self, rhs: u64) -> Option<Self> { self.0.checked_div(rhs).map(Self) }
92
93    /// Checked weight multiplication.
94    ///
95    /// Computes the absolute fee amount for a given [`Weight`] at this fee rate.
96    ///
97    /// `None` is returned if an overflow occurred.
98    pub fn checked_mul_by_weight(self, rhs: Weight) -> Option<Amount> {
99        let sats = self.0.checked_mul(rhs.to_wu())?.checked_add(999)? / 1000;
100        Some(Amount::from_sat(sats))
101    }
102
103    /// Calculates fee by multiplying this fee rate by weight, in weight units, returning `None`
104    /// if overflow occurred.
105    ///
106    /// This is equivalent to `Self::checked_mul_by_weight()`.
107    pub fn fee_wu(self, weight: Weight) -> Option<Amount> { self.checked_mul_by_weight(weight) }
108
109    /// Calculates fee by multiplying this fee rate by weight, in virtual bytes, returning `None`
110    /// if overflow occurred.
111    ///
112    /// This is equivalent to converting `vb` to `weight` using `Weight::from_vb` and then calling
113    /// `Self::fee_wu(weight)`.
114    pub fn fee_vb(self, vb: u64) -> Option<Amount> {
115        Weight::from_vb(vb).and_then(|w| self.fee_wu(w))
116    }
117}
118
119/// Alternative will display the unit.
120impl fmt::Display for FeeRate {
121    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
122        if f.alternate() {
123            write!(f, "{}.00 sat/vbyte", self.to_sat_per_vb_ceil())
124        } else {
125            fmt::Display::fmt(&self.0, f)
126        }
127    }
128}
129
130impl From<FeeRate> for u64 {
131    fn from(value: FeeRate) -> Self { value.to_sat_per_kwu() }
132}
133
134/// Computes ceiling so that fee computation is conservative.
135impl Mul<FeeRate> for Weight {
136    type Output = Amount;
137
138    fn mul(self, rhs: FeeRate) -> Self::Output {
139        Amount::from_sat((rhs.to_sat_per_kwu() * self.to_wu() + 999) / 1000)
140    }
141}
142
143impl Mul<Weight> for FeeRate {
144    type Output = Amount;
145
146    fn mul(self, rhs: Weight) -> Self::Output { rhs * self }
147}
148
149impl Div<Weight> for Amount {
150    type Output = FeeRate;
151
152    fn div(self, rhs: Weight) -> Self::Output { FeeRate(self.to_sat() * 1000 / rhs.to_wu()) }
153}
154
155crate::impl_parse_str_from_int_infallible!(FeeRate, u64, from_sat_per_kwu);
156
157#[cfg(feature = "arbitrary")]
158impl<'a> Arbitrary<'a> for FeeRate {
159    fn arbitrary(u: &mut Unstructured<'a>) -> arbitrary::Result<Self> {
160        let choice = u.int_in_range(0..=4)?;
161        match choice {
162            0 => Ok(FeeRate::MIN),
163            1 => Ok(FeeRate::BROADCAST_MIN),
164            2 => Ok(FeeRate::DUST),
165            3 => Ok(FeeRate::MAX),
166            _ => Ok(FeeRate(u64::arbitrary(u)?)),
167        }
168    }
169}
170
171#[cfg(test)]
172mod tests {
173    use super::*;
174
175    #[test]
176    fn fee_rate_const_test() {
177        assert_eq!(0, FeeRate::ZERO.to_sat_per_kwu());
178        assert_eq!(u64::MIN, FeeRate::MIN.to_sat_per_kwu());
179        assert_eq!(u64::MAX, FeeRate::MAX.to_sat_per_kwu());
180        assert_eq!(250, FeeRate::BROADCAST_MIN.to_sat_per_kwu());
181        assert_eq!(750, FeeRate::DUST.to_sat_per_kwu());
182    }
183
184    #[test]
185    fn fee_rate_from_sat_per_vb_test() {
186        let fee_rate = FeeRate::from_sat_per_vb(10).expect("expected feerate in sat/kwu");
187        assert_eq!(FeeRate(2500), fee_rate);
188    }
189
190    #[test]
191    fn fee_rate_from_sat_per_vb_overflow_test() {
192        let fee_rate = FeeRate::from_sat_per_vb(u64::MAX);
193        assert!(fee_rate.is_none());
194    }
195
196    #[test]
197    fn from_sat_per_vb_u32() {
198        let fee_rate = FeeRate::from_sat_per_vb_u32(10);
199        assert_eq!(FeeRate(2500), fee_rate);
200    }
201
202    #[test]
203    #[cfg(debug_assertions)]
204    #[allow(deprecated)] // Keep test until we remove the function.
205    #[should_panic]
206    fn from_sat_per_vb_unchecked_panic_test() { FeeRate::from_sat_per_vb_unchecked(u64::MAX); }
207
208    #[test]
209    fn raw_feerate_test() {
210        let fee_rate = FeeRate(333);
211        assert_eq!(333, fee_rate.to_sat_per_kwu());
212        assert_eq!(1, fee_rate.to_sat_per_vb_floor());
213        assert_eq!(2, fee_rate.to_sat_per_vb_ceil());
214    }
215
216    #[test]
217    fn checked_mul_test() {
218        let fee_rate = FeeRate(10).checked_mul(10).expect("expected feerate in sat/kwu");
219        assert_eq!(FeeRate(100), fee_rate);
220
221        let fee_rate = FeeRate(10).checked_mul(u64::MAX);
222        assert!(fee_rate.is_none());
223    }
224
225    #[test]
226    fn checked_weight_mul_test() {
227        let weight = Weight::from_vb(10).unwrap();
228        let fee: Amount = FeeRate::from_sat_per_vb(10)
229            .unwrap()
230            .checked_mul_by_weight(weight)
231            .expect("expected Amount");
232        assert_eq!(Amount::from_sat(100), fee);
233
234        let fee = FeeRate(10).checked_mul_by_weight(Weight::MAX);
235        assert!(fee.is_none());
236
237        let weight = Weight::from_vb(3).unwrap();
238        let fee_rate = FeeRate::from_sat_per_vb(3).unwrap();
239        let fee = fee_rate.checked_mul_by_weight(weight).unwrap();
240        assert_eq!(Amount::from_sat(9), fee);
241    }
242
243    #[test]
244    fn checked_div_test() {
245        let fee_rate = FeeRate(10).checked_div(10).expect("expected feerate in sat/kwu");
246        assert_eq!(FeeRate(1), fee_rate);
247
248        let fee_rate = FeeRate(10).checked_div(0);
249        assert!(fee_rate.is_none());
250    }
251}
bitcoin_units/fee_rate.rs

bitcoin_units/
fee_rate.rs
