cbe_program/
rent.rs

1//! Configuration for network [rent].
2//!
3//! [rent]: https://docs.cartallum.com/implemented-proposals/rent
4
5#![allow(clippy::integer_arithmetic)]
6
7use {crate::clock::DEFAULT_SLOTS_PER_EPOCH, cbe_sdk_macro::CloneZeroed};
8
9/// Configuration of network rent.
10#[repr(C)]
11#[derive(Serialize, Deserialize, PartialEq, CloneZeroed, Copy, Debug, AbiExample)]
12pub struct Rent {
13    /// Rental rate in scoobies/byte-year.
14    pub scoobies_per_byte_year: u64,
15
16    /// Amount of time (in years) a balance must include rent for the account to
17    /// be rent exempt.
18    pub exemption_threshold: f64,
19
20    /// The percentage of collected rent that is burned.
21    ///
22    /// Valid values are in the range [0, 100]. The remaining percentage is
23    /// distributed to validators.
24    pub burn_percent: u8,
25}
26
27/// Default rental rate in scoobies/byte-year.
28///
29/// This calculation is based on:
30/// - 10^9 scoobies per CBC
31/// - $1 per CBC
32/// - $0.01 per megabyte day
33/// - $3.65 per megabyte year
34pub const DEFAULT_SCOOBIES_PER_BYTE_YEAR: u64 = 1_000_000_000 / 100 * 365 / (1024 * 1024);
35
36/// Default amount of time (in years) the balance has to include rent for the
37/// account to be rent exempt.
38pub const DEFAULT_EXEMPTION_THRESHOLD: f64 = 2.0;
39
40/// Default percentage of collected rent that is burned.
41///
42/// Valid values are in the range [0, 100]. The remaining percentage is
43/// distributed to validators.
44pub const DEFAULT_BURN_PERCENT: u8 = 50;
45
46/// Account storage overhead for calculation of base rent.
47///
48/// This is the number of bytes required to store an account with no data. It is
49/// added to an accounts data length when calculating [`Rent::minimum_balance`].
50pub const ACCOUNT_STORAGE_OVERHEAD: u64 = 128;
51
52impl Default for Rent {
53    fn default() -> Self {
54        Self {
55            scoobies_per_byte_year: DEFAULT_SCOOBIES_PER_BYTE_YEAR,
56            exemption_threshold: DEFAULT_EXEMPTION_THRESHOLD,
57            burn_percent: DEFAULT_BURN_PERCENT,
58        }
59    }
60}
61
62impl Rent {
63    /// Calculate how much rent to burn from the collected rent.
64    ///
65    /// The first value returned is the amount burned. The second is the amount
66    /// to distribute to validators.
67    pub fn calculate_burn(&self, rent_collected: u64) -> (u64, u64) {
68        let burned_portion = (rent_collected * u64::from(self.burn_percent)) / 100;
69        (burned_portion, rent_collected - burned_portion)
70    }
71
72    /// Minimum balance due for rent-exemption of a given account data size.
73    ///
74    /// Note: a stripped-down version of this calculation is used in
75    /// `calculate_split_rent_exempt_reserve` in the stake program. When this
76    /// function is updated, eg. when making rent variable, the stake program
77    /// will need to be refactored.
78    pub fn minimum_balance(&self, data_len: usize) -> u64 {
79        let bytes = data_len as u64;
80        (((ACCOUNT_STORAGE_OVERHEAD + bytes) * self.scoobies_per_byte_year) as f64
81            * self.exemption_threshold) as u64
82    }
83
84    /// Whether a given balance and data length would be exempt.
85    pub fn is_exempt(&self, balance: u64, data_len: usize) -> bool {
86        balance >= self.minimum_balance(data_len)
87    }
88
89    /// Rent due on account's data length with balance.
90    pub fn due(&self, balance: u64, data_len: usize, years_elapsed: f64) -> RentDue {
91        if self.is_exempt(balance, data_len) {
92            RentDue::Exempt
93        } else {
94            RentDue::Paying(self.due_amount(data_len, years_elapsed))
95        }
96    }
97
98    /// Rent due for account that is known to be not exempt.
99    pub fn due_amount(&self, data_len: usize, years_elapsed: f64) -> u64 {
100        let actual_data_len = data_len as u64 + ACCOUNT_STORAGE_OVERHEAD;
101        let scoobies_per_year = self.scoobies_per_byte_year * actual_data_len;
102        (scoobies_per_year as f64 * years_elapsed) as u64
103    }
104
105    /// Creates a `Rent` that charges no scoobies.
106    ///
107    /// This is used for testing.
108    pub fn free() -> Self {
109        Self {
110            scoobies_per_byte_year: 0,
111            ..Rent::default()
112        }
113    }
114
115    /// Creates a `Rent` that is scaled based on the number of slots in an epoch.
116    ///
117    /// This is used for testing.
118    pub fn with_slots_per_epoch(slots_per_epoch: u64) -> Self {
119        let ratio = slots_per_epoch as f64 / DEFAULT_SLOTS_PER_EPOCH as f64;
120        let exemption_threshold = DEFAULT_EXEMPTION_THRESHOLD * ratio;
121        let scoobies_per_byte_year = (DEFAULT_SCOOBIES_PER_BYTE_YEAR as f64 / ratio) as u64;
122        Self {
123            scoobies_per_byte_year,
124            exemption_threshold,
125            ..Self::default()
126        }
127    }
128}
129
130/// The return value of [`Rent::due`].
131#[derive(Debug, Copy, Clone, Eq, PartialEq)]
132pub enum RentDue {
133    /// Used to indicate the account is rent exempt.
134    Exempt,
135    /// The account owes this much rent.
136    Paying(u64),
137}
138
139impl RentDue {
140    /// Return the scoobies due for rent.
141    pub fn scoobies(&self) -> u64 {
142        match self {
143            RentDue::Exempt => 0,
144            RentDue::Paying(x) => *x,
145        }
146    }
147
148    /// Return 'true' if rent exempt.
149    pub fn is_exempt(&self) -> bool {
150        match self {
151            RentDue::Exempt => true,
152            RentDue::Paying(_) => false,
153        }
154    }
155}
156
157#[cfg(test)]
158mod tests {
159    use super::*;
160
161    #[test]
162    fn test_due() {
163        let default_rent = Rent::default();
164
165        assert_eq!(
166            default_rent.due(0, 2, 1.2),
167            RentDue::Paying(
168                (((2 + ACCOUNT_STORAGE_OVERHEAD) * DEFAULT_SCOOBIES_PER_BYTE_YEAR) as f64 * 1.2)
169                    as u64
170            ),
171        );
172        assert_eq!(
173            default_rent.due(
174                (((2 + ACCOUNT_STORAGE_OVERHEAD) * DEFAULT_SCOOBIES_PER_BYTE_YEAR) as f64
175                    * DEFAULT_EXEMPTION_THRESHOLD) as u64,
176                2,
177                1.2
178            ),
179            RentDue::Exempt,
180        );
181
182        let custom_rent = Rent {
183            scoobies_per_byte_year: 5,
184            exemption_threshold: 2.5,
185            ..Rent::default()
186        };
187
188        assert_eq!(
189            custom_rent.due(0, 2, 1.2),
190            RentDue::Paying(
191                (((2 + ACCOUNT_STORAGE_OVERHEAD) * custom_rent.scoobies_per_byte_year) as f64 * 1.2)
192                    as u64,
193            )
194        );
195
196        assert_eq!(
197            custom_rent.due(
198                (((2 + ACCOUNT_STORAGE_OVERHEAD) * custom_rent.scoobies_per_byte_year) as f64
199                    * custom_rent.exemption_threshold) as u64,
200                2,
201                1.2
202            ),
203            RentDue::Exempt
204        );
205    }
206
207    #[test]
208    fn test_rent_due_scoobies() {
209        assert_eq!(RentDue::Exempt.scoobies(), 0);
210
211        let amount = 123;
212        assert_eq!(RentDue::Paying(amount).scoobies(), amount);
213    }
214
215    #[test]
216    fn test_rent_due_is_exempt() {
217        assert!(RentDue::Exempt.is_exempt());
218        assert!(!RentDue::Paying(0).is_exempt());
219    }
220
221    #[test]
222    fn test_clone() {
223        let rent = Rent {
224            scoobies_per_byte_year: 1,
225            exemption_threshold: 2.2,
226            burn_percent: 3,
227        };
228        #[allow(clippy::clone_on_copy)]
229        let cloned_rent = rent.clone();
230        assert_eq!(cloned_rent, rent);
231    }
232}
cbe_program/rent.rs

cbe_program/
rent.rs
