blvm_protocol/
economic.rs

1//! Economic Model Parameters
2//!
3//! Expanded economic model abstraction beyond basic halving.
4//! Provides comprehensive economic parameters for protocol variants.
5
6use crate::ProtocolVersion;
7use serde::{Deserialize, Serialize};
8
9/// Economic model parameters for a protocol version
10#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
11pub struct EconomicParameters {
12    /// Initial block subsidy (in satoshis)
13    pub initial_subsidy: u64,
14    /// Block subsidy halving interval
15    pub halving_interval: u64,
16    /// Maximum money supply (in satoshis)
17    pub max_money_supply: u64,
18    /// Coinbase maturity (blocks before coinbase can be spent)
19    pub coinbase_maturity: u64,
20    /// Dust limit (minimum output value in satoshis)
21    pub dust_limit: u64,
22    /// Minimum transaction fee rate (satoshis per vbyte)
23    pub min_fee_rate: u64,
24    /// Maximum transaction fee rate (satoshis per vbyte)
25    pub max_fee_rate: u64,
26    /// Minimum relay fee (satoshis per vbyte)
27    pub min_relay_fee: u64,
28    /// Block subsidy schedule (for custom schedules)
29    pub subsidy_schedule: Vec<(u64, u64)>, // (height, subsidy)
30}
31
32impl EconomicParameters {
33    /// Get economic parameters for a protocol version
34    pub fn for_protocol(version: ProtocolVersion) -> Self {
35        match version {
36            ProtocolVersion::BitcoinV1 => Self::mainnet(),
37            ProtocolVersion::Testnet3 => Self::testnet(),
38            ProtocolVersion::Regtest => Self::regtest(),
39            ProtocolVersion::Signet => Self::signet(),
40        }
41    }
42
43    /// Mainnet economic parameters (Bitcoin production network)
44    pub fn mainnet() -> Self {
45        Self {
46            initial_subsidy: 50_0000_0000, // 50 BTC in satoshis
47            halving_interval: 210_000,
48            max_money_supply: 21_0000_0000_0000_0000, // 21M BTC in satoshis
49            coinbase_maturity: 100,                   // 100 blocks
50            dust_limit: 546,                          // 546 satoshis
51            min_fee_rate: 1,                          // 1 sat/vbyte
52            max_fee_rate: 1_000_000,                  // 1M sat/vbyte (safety limit)
53            min_relay_fee: 1000,                      // 1000 satoshis per transaction (BIP125)
54            subsidy_schedule: Vec::new(),             // Use halving formula instead
55        }
56    }
57
58    /// Testnet economic parameters (same as mainnet)
59    pub fn testnet() -> Self {
60        Self {
61            initial_subsidy: 50_0000_0000,
62            halving_interval: 210_000,
63            max_money_supply: 21_0000_0000_0000_0000,
64            coinbase_maturity: 100,
65            dust_limit: 546,
66            min_fee_rate: 1,
67            max_fee_rate: 1_000_000,
68            min_relay_fee: 1000,
69            subsidy_schedule: Vec::new(),
70        }
71    }
72
73    /// Regtest economic parameters (relaxed for testing)
74    pub fn regtest() -> Self {
75        Self {
76            initial_subsidy: 50_0000_0000,
77            halving_interval: 150, // Faster halving for testing
78            max_money_supply: 21_0000_0000_0000_0000,
79            coinbase_maturity: 100,
80            dust_limit: 546,
81            min_fee_rate: 0, // No minimum fee for testing
82            max_fee_rate: 1_000_000,
83            min_relay_fee: 0, // No minimum relay fee for testing
84            subsidy_schedule: Vec::new(),
85        }
86    }
87
88    /// Signet economic parameters (same halving schedule as mainnet)
89    pub fn signet() -> Self {
90        Self {
91            initial_subsidy: 50_0000_0000,
92            halving_interval: 210_000,
93            max_money_supply: 21_0000_0000_0000_0000,
94            coinbase_maturity: 100,
95            dust_limit: 546,
96            min_fee_rate: 1,
97            max_fee_rate: 1_000_000,
98            min_relay_fee: 1000,
99            subsidy_schedule: Vec::new(),
100        }
101    }
102
103    /// Calculate block subsidy for a given height
104    pub fn get_block_subsidy(&self, height: u64) -> u64 {
105        // If custom subsidy schedule exists, use it
106        if !self.subsidy_schedule.is_empty() {
107            for (schedule_height, subsidy) in self.subsidy_schedule.iter().rev() {
108                if height >= *schedule_height {
109                    return *subsidy;
110                }
111            }
112            return 0;
113        }
114
115        // Use standard halving formula
116        let halving_period = height / self.halving_interval;
117
118        // After 64 halvings, subsidy becomes 0
119        if halving_period >= 64 {
120            return 0;
121        }
122
123        // Calculate: initial_subsidy / 2^halving_period
124        self.initial_subsidy >> halving_period
125    }
126
127    /// Calculate total supply up to a given height
128    pub fn total_supply_at_height(&self, height: u64) -> u64 {
129        let mut total = 0u64;
130
131        for h in 0..=height {
132            total = total.saturating_add(self.get_block_subsidy(h));
133        }
134
135        total
136    }
137
138    /// Check if a value meets dust limit
139    pub fn is_dust(&self, value: u64) -> bool {
140        value < self.dust_limit
141    }
142
143    /// Check if a fee rate is valid
144    pub fn is_valid_fee_rate(&self, fee_rate: u64) -> bool {
145        fee_rate >= self.min_fee_rate && fee_rate <= self.max_fee_rate
146    }
147
148    /// Calculate fee for a transaction size
149    pub fn calculate_fee(&self, size_vbytes: usize, fee_rate_sat_per_vbyte: u64) -> u64 {
150        if !self.is_valid_fee_rate(fee_rate_sat_per_vbyte) {
151            return 0;
152        }
153
154        (size_vbytes as u64).saturating_mul(fee_rate_sat_per_vbyte)
155    }
156
157    /// Check if total supply exceeds maximum
158    pub fn exceeds_max_supply(&self, height: u64) -> bool {
159        self.total_supply_at_height(height) > self.max_money_supply
160    }
161}
162
163#[cfg(test)]
164mod tests {
165    use super::*;
166
167    #[test]
168    fn test_mainnet_economic_parameters() {
169        let params = EconomicParameters::mainnet();
170
171        assert_eq!(params.initial_subsidy, 50_0000_0000);
172        assert_eq!(params.halving_interval, 210_000);
173        assert_eq!(params.max_money_supply, 21_0000_0000_0000_0000);
174        assert_eq!(params.coinbase_maturity, 100);
175        assert_eq!(params.dust_limit, 546);
176    }
177
178    #[test]
179    fn test_block_subsidy_halving() {
180        let params = EconomicParameters::mainnet();
181
182        // Initial subsidy
183        assert_eq!(params.get_block_subsidy(0), 50_0000_0000);
184        assert_eq!(params.get_block_subsidy(209_999), 50_0000_0000);
185
186        // First halving
187        assert_eq!(params.get_block_subsidy(210_000), 25_0000_0000);
188        assert_eq!(params.get_block_subsidy(419_999), 25_0000_0000);
189
190        // Second halving
191        assert_eq!(params.get_block_subsidy(420_000), 12_5000_0000);
192
193        // After 64 halvings (13,440,000 blocks)
194        assert_eq!(params.get_block_subsidy(13_440_000), 0);
195        assert_eq!(params.get_block_subsidy(20_000_000), 0);
196    }
197
198    #[test]
199    fn test_total_supply_calculation() {
200        let params = EconomicParameters::mainnet();
201
202        // Genesis block
203        assert_eq!(params.total_supply_at_height(0), 50_0000_0000);
204
205        // After 10 blocks
206        assert_eq!(params.total_supply_at_height(9), 10 * 50_0000_0000);
207
208        // At first halving
209        let first_halving_height = 210_000;
210        let _before_halving_subsidy = first_halving_height * 50_0000_0000;
211        // Approximate calculation (simplified)
212        assert!(params.total_supply_at_height(first_halving_height) > 0);
213    }
214
215    #[test]
216    fn test_dust_limit() {
217        let params = EconomicParameters::mainnet();
218
219        assert!(params.is_dust(545));
220        assert!(!params.is_dust(546));
221        assert!(!params.is_dust(1000));
222    }
223
224    #[test]
225    fn test_fee_rate_validation() {
226        let params = EconomicParameters::mainnet();
227
228        // Valid fee rates
229        assert!(params.is_valid_fee_rate(1));
230        assert!(params.is_valid_fee_rate(100));
231        assert!(params.is_valid_fee_rate(1_000_000));
232
233        // Invalid fee rates
234        assert!(!params.is_valid_fee_rate(0));
235        assert!(!params.is_valid_fee_rate(1_000_001));
236    }
237
238    #[test]
239    fn test_fee_calculation() {
240        let params = EconomicParameters::mainnet();
241
242        // 250 vbyte transaction at 10 sat/vbyte = 2500 sats
243        assert_eq!(params.calculate_fee(250, 10), 2500);
244
245        // Invalid fee rate returns 0
246        assert_eq!(params.calculate_fee(250, 0), 0);
247        assert_eq!(params.calculate_fee(250, 2_000_000), 0);
248    }
249
250    #[test]
251    fn test_regtest_relaxed_parameters() {
252        let params = EconomicParameters::regtest();
253
254        // Faster halving
255        assert_eq!(params.halving_interval, 150);
256
257        // No minimum fees
258        assert_eq!(params.min_fee_rate, 0);
259        assert_eq!(params.min_relay_fee, 0);
260
261        // Can use zero fees
262        assert!(params.is_valid_fee_rate(0));
263    }
264
265    #[test]
266    fn test_regtest_faster_halving() {
267        let params = EconomicParameters::regtest();
268
269        // Subsidy halves at block 150 instead of 210,000
270        assert_eq!(params.get_block_subsidy(0), 50_0000_0000);
271        assert_eq!(params.get_block_subsidy(149), 50_0000_0000);
272        assert_eq!(params.get_block_subsidy(150), 25_0000_0000);
273        assert_eq!(params.get_block_subsidy(299), 25_0000_0000);
274        assert_eq!(params.get_block_subsidy(300), 12_5000_0000);
275    }
276
277    #[test]
278    fn test_testnet_same_as_mainnet() {
279        let mainnet = EconomicParameters::mainnet();
280        let testnet = EconomicParameters::testnet();
281
282        assert_eq!(mainnet.initial_subsidy, testnet.initial_subsidy);
283        assert_eq!(mainnet.halving_interval, testnet.halving_interval);
284        assert_eq!(mainnet.max_money_supply, testnet.max_money_supply);
285        assert_eq!(mainnet.coinbase_maturity, testnet.coinbase_maturity);
286        assert_eq!(mainnet.dust_limit, testnet.dust_limit);
287    }
288
289    #[test]
290    fn test_custom_subsidy_schedule() {
291        let mut params = EconomicParameters::mainnet();
292        params.subsidy_schedule = vec![
293            (0, 100_0000_0000),      // 100 BTC for first 1000 blocks
294            (1000, 50_0000_0000),    // 50 BTC after
295            (210_000, 25_0000_0000), // 25 BTC after halving
296        ];
297
298        assert_eq!(params.get_block_subsidy(0), 100_0000_0000);
299        assert_eq!(params.get_block_subsidy(999), 100_0000_0000);
300        assert_eq!(params.get_block_subsidy(1000), 50_0000_0000);
301        assert_eq!(params.get_block_subsidy(210_000), 25_0000_0000);
302    }
303
304    #[test]
305    fn test_max_supply_check() {
306        let params = EconomicParameters::mainnet();
307
308        // At reasonable heights, shouldn't exceed
309        assert!(!params.exceeds_max_supply(100_000));
310        assert!(!params.exceeds_max_supply(1_000_000));
311
312        // At extremely high heights (beyond 64 halvings), should check
313        // Note: This test may need adjustment based on actual calculation
314    }
315
316    #[test]
317    fn test_economic_parameters_serialization() {
318        let mainnet = EconomicParameters::mainnet();
319        let json = serde_json::to_string(&mainnet).unwrap();
320        let deserialized: EconomicParameters = serde_json::from_str(&json).unwrap();
321
322        assert_eq!(mainnet.initial_subsidy, deserialized.initial_subsidy);
323        assert_eq!(mainnet.halving_interval, deserialized.halving_interval);
324        assert_eq!(mainnet.max_money_supply, deserialized.max_money_supply);
325        assert_eq!(mainnet.coinbase_maturity, deserialized.coinbase_maturity);
326        assert_eq!(mainnet.dust_limit, deserialized.dust_limit);
327    }
328
329    #[test]
330    fn test_economic_parameters_equality() {
331        let mainnet1 = EconomicParameters::mainnet();
332        let mainnet2 = EconomicParameters::mainnet();
333        let testnet = EconomicParameters::testnet();
334
335        assert_eq!(mainnet1, mainnet2);
336        assert_eq!(mainnet1, testnet); // Mainnet and testnet have same economic params
337    }
338}
blvm_protocol/economic.rs

blvm_protocol/
economic.rs
