apollo_consensus_orchestrator: add SNIP-35 fee_market functions and tests

Author: sirandreww-starkware

crates/apollo_consensus_orchestrator/src/fee_market/mod.rs

@@ -22,6 +22,12 @@ mod test;
 // in approximately 10 minutes.
 const MIN_GAS_PRICE_INCREASE_DENOMINATOR: u128 = 333;
 
+/// Scale factor for 18-decimal fixed-point conversion (1 STRK = 10^18 FRI).
+const FRI_DECIMALS_SCALE: u128 = 10u128.pow(18);
+
+/// Denominator for parts-per-thousand calculations in SNIP-35 fee_proposal bounds.
+pub(crate) const PPT_DENOMINATOR: u128 = 1000;
+
 /// Fee market information for the next block.
 #[derive(Debug, Default, Serialize)]
 pub struct FeeMarketInfo {
@@ -136,3 +142,58 @@ pub fn calculate_next_base_gas_price(
     let adjusted_price = u128::try_from(adjusted_price_u256).unwrap_or(u128::MAX);
     GasPrice(max(adjusted_price, min_gas_price.0))
 }
+
+/// Compute fee_actual from the last `window_size` fee_proposal values (SNIP-35).
+/// Returns the average of the two middle values, rounded down.
+/// Returns `None` if fewer than `window_size` proposals are available.
+pub fn compute_fee_actual(proposals: &[GasPrice], window_size: usize) -> Option<GasPrice> {
+    if proposals.len() < window_size || window_size < 2 {
+        return None;
+    }
+    let window = &proposals[proposals.len() - window_size..];
+    let mut sorted: Vec<u128> = window.iter().map(|p| p.0).collect();
+    sorted.sort();
+    // Median = average of the two middle values, rounded down.
+    // Use overflow-safe averaging: a + (b - a) / 2 (safe because sorted, so b >= a).
+    let mid = window_size / 2;
+    let median = sorted[mid - 1] + (sorted[mid] - sorted[mid - 1]) / 2;
+    // Return None if median is zero (e.g., pre-SNIP-35 blocks with fee_proposal=0).
+    // This triggers the l2_gas_price fallback in both proposer and validator paths.
+    if median == 0 { None } else { Some(GasPrice(median)) }
+}
+
+/// Compute the fee target from STRK/USD price and a USD cost target (SNIP-35).
+/// `target_atto_usd_per_l2_gas` is in atto-USD (18-decimal fixed-point).
+/// `strk_usd_rate` is the STRK/USD price with 18 decimals (from oracle).
+/// Result is in FRI, clamped to `[floor_min_fri, floor_max_fri]`.
+pub fn compute_fee_target(
+    target_atto_usd_per_l2_gas: u128,
+    strk_usd_rate: u128,
+    floor_min_fri: u128,
+    floor_max_fri: u128,
+) -> GasPrice {
+    if strk_usd_rate == 0 {
+        return GasPrice(floor_max_fri);
+    }
+    // floor_fri = target_atto_usd_per_l2_gas * 10^18 / strk_usd_rate
+    let numerator = U256::from(target_atto_usd_per_l2_gas) * U256::from(FRI_DECIMALS_SCALE);
+    let floor = numerator / U256::from(strk_usd_rate);
+    let floor_u128 = u128::try_from(floor).unwrap_or(u128::MAX);
+    GasPrice(floor_u128.clamp(floor_min_fri, floor_max_fri))
+}
+
+/// Compute the fee_proposal an honest proposer should publish (SNIP-35).
+/// - If oracle failed (`fee_target` is `None`): freeze at `fee_actual`.
+/// - Otherwise: clamp `fee_target` to within +/-`margin_ppt` parts per thousand of `fee_actual`.
+pub fn compute_fee_proposal(
+    fee_target: Option<GasPrice>,
+    fee_actual: GasPrice,
+    margin_ppt: u128,
+) -> GasPrice {
+    let Some(fee_target) = fee_target else {
+        return fee_actual;
+    };
+    let upper = fee_actual.0.saturating_mul(PPT_DENOMINATOR + margin_ppt) / PPT_DENOMINATOR;
+    let lower = fee_actual.0.saturating_mul(PPT_DENOMINATOR) / (PPT_DENOMINATOR + margin_ppt);
+    GasPrice(fee_target.0.clamp(lower, upper))
+}

crates/apollo_consensus_orchestrator/src/fee_market/test.rs

@@ -7,6 +7,9 @@ use starknet_api::versioned_constants_logic::VersionedConstantsTrait;
 
 use crate::fee_market::{
     calculate_next_base_gas_price,
+    compute_fee_actual,
+    compute_fee_proposal,
+    compute_fee_target,
     get_min_gas_price_for_height,
     MIN_GAS_PRICE_INCREASE_DENOMINATOR,
 };
@@ -214,3 +217,144 @@ fn test_calculate_with_price_close_to_minimum() {
     // When price is close to minimum, should cap at min_gas_price to avoid overshooting
     assert_eq!(result, min_gas_price);
 }
+
+#[test]
+fn test_compute_fee_actual_with_10_identical_values() {
+    let proposals: Vec<GasPrice> = vec![GasPrice(1000); 10];
+    assert_eq!(compute_fee_actual(&proposals, 10), Some(GasPrice(1000)));
+}
+
+#[test]
+fn test_compute_fee_actual_with_ascending_values() {
+    let proposals: Vec<GasPrice> = (1..=10).map(|i| GasPrice(i * 100)).collect();
+    // Sorted: 100,200,300,400,500,600,700,800,900,1000. Median = (500+600)/2 = 550.
+    assert_eq!(compute_fee_actual(&proposals, 10), Some(GasPrice(550)));
+}
+
+#[test]
+fn test_compute_fee_actual_with_descending_values() {
+    let proposals: Vec<GasPrice> = (1..=10).rev().map(|i| GasPrice(i * 100)).collect();
+    // Same sorted order, same median.
+    assert_eq!(compute_fee_actual(&proposals, 10), Some(GasPrice(550)));
+}
+
+#[test]
+fn test_compute_fee_actual_with_outliers() {
+    let mut proposals: Vec<GasPrice> = vec![GasPrice(100); 8];
+    proposals.push(GasPrice(1)); // Low outlier
+    proposals.push(GasPrice(1_000_000)); // High outlier
+    // Sorted: 1,100,100,100,100,100,100,100,100,1000000. Median = (100+100)/2 = 100.
+    assert_eq!(compute_fee_actual(&proposals, 10), Some(GasPrice(100)));
+}
+
+#[test]
+fn test_compute_fee_actual_fewer_than_window_returns_none() {
+    let proposals: Vec<GasPrice> = vec![GasPrice(100); 9];
+    assert_eq!(compute_fee_actual(&proposals, 10), None);
+}
+
+#[test]
+fn test_compute_fee_actual_empty_returns_none() {
+    assert_eq!(compute_fee_actual(&[], 10), None);
+}
+
+#[test]
+fn test_compute_fee_actual_custom_window_size() {
+    let proposals: Vec<GasPrice> = vec![GasPrice(200); 4];
+    assert_eq!(compute_fee_actual(&proposals, 4), Some(GasPrice(200)));
+    assert_eq!(compute_fee_actual(&proposals, 5), None);
+}
+
+#[test]
+fn test_compute_fee_actual_zero_median_returns_none() {
+    // All zeros → median is 0 → returns None (triggers l2_gas_price fallback).
+    let proposals: Vec<GasPrice> = vec![GasPrice(0); 10];
+    assert_eq!(compute_fee_actual(&proposals, 10), None);
+}
+
+#[test]
+fn test_compute_fee_actual_uses_only_last_window_entries() {
+    // 12 entries: first 2 are outliers, last 10 are 500.
+    let mut proposals: Vec<GasPrice> = vec![GasPrice(999_999); 2];
+    proposals.extend(vec![GasPrice(500); 10]);
+    // With window_size=10, the outliers should be ignored (only last 10 used).
+    assert_eq!(compute_fee_actual(&proposals, 10), Some(GasPrice(500)));
+}
+
+#[test]
+fn test_compute_fee_target_normal() {
+    // Target: $3e-9/gas = 3_000_000_000 atto-USD. STRK at $0.50 = 500_000_000_000_000_000.
+    // floor = 3_000_000_000 * 10^18 / 500_000_000_000_000_000 = 6_000_000_000.
+    let target = compute_fee_target(3_000_000_000, 500_000_000_000_000_000, 0, u128::MAX);
+    assert_eq!(target, GasPrice(6_000_000_000));
+}
+
+#[test]
+fn test_compute_fee_target_clamp_min() {
+    let target = compute_fee_target(1, 10u128.pow(18), 100, u128::MAX);
+    // floor = 1 * 10^18 / 10^18 = 1, but clamped to min 100.
+    assert_eq!(target, GasPrice(100));
+}
+
+#[test]
+fn test_compute_fee_target_clamp_max() {
+    // Very low STRK price → very high floor, clamped to max.
+    let target = compute_fee_target(10u128.pow(18), 1, 0, 1000);
+    assert_eq!(target, GasPrice(1000));
+}
+
+#[test]
+fn test_compute_fee_target_zero_rate() {
+    let target = compute_fee_target(100, 0, 0, 999);
+    assert_eq!(target, GasPrice(999));
+}
+
+#[test]
+fn test_compute_fee_proposal_oracle_failure_freezes() {
+    let proposal = compute_fee_proposal(None, GasPrice(1000), 2);
+    assert_eq!(proposal, GasPrice(1000));
+}
+
+#[test]
+fn test_compute_fee_proposal_target_above_actual() {
+    // fee_target=2000, fee_actual=1000, margin=2ppt. Upper bound = 1000*1002/1000 = 1002.
+    let proposal = compute_fee_proposal(Some(GasPrice(2000)), GasPrice(1000), 2);
+    assert_eq!(proposal, GasPrice(1002));
+}
+
+#[test]
+fn test_compute_fee_proposal_target_below_actual() {
+    // fee_target=500, fee_actual=1000, margin=2ppt. Lower bound = 1000*1000/1002 = 998.
+    let proposal = compute_fee_proposal(Some(GasPrice(500)), GasPrice(1000), 2);
+    assert_eq!(proposal, GasPrice(998));
+}
+
+#[test]
+fn test_compute_fee_proposal_target_within_bounds() {
+    // fee_target=1001, fee_actual=1000, margin=2ppt. 1001 is within [998, 1002].
+    let proposal = compute_fee_proposal(Some(GasPrice(1001)), GasPrice(1000), 2);
+    assert_eq!(proposal, GasPrice(1001));
+}
+
+#[test]
+fn test_compute_fee_proposal_fee_actual_zero_clamps_to_zero() {
+    // When fee_actual=0, both bounds are 0, so fee_proposal is always 0.
+    let proposal = compute_fee_proposal(Some(GasPrice(1000)), GasPrice(0), 2);
+    assert_eq!(proposal, GasPrice(0));
+}
+
+#[test]
+fn test_compute_fee_actual_window_size_below_minimum_returns_none() {
+    let proposals: Vec<GasPrice> = vec![GasPrice(100); 10];
+    assert_eq!(compute_fee_actual(&proposals, 0), None);
+    assert_eq!(compute_fee_actual(&proposals, 1), None);
+}
+
+#[test]
+fn test_compute_fee_proposal_custom_margin() {
+    // margin=10ppt (1%). fee_actual=10000. Upper=10000*1010/1000=10100. Lower=10000*1000/1010=9900.
+    let proposal_up = compute_fee_proposal(Some(GasPrice(99999)), GasPrice(10000), 10);
+    assert_eq!(proposal_up, GasPrice(10100));
+    let proposal_down = compute_fee_proposal(Some(GasPrice(1)), GasPrice(10000), 10);
+    assert_eq!(proposal_down, GasPrice(9900));
+}