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

bitcoin_units/
fee_rate.rs
