feat: oracle health monitoring, rate history, pool optimizer, priority liquidation (#774)

- #680: Add monitor_oracle_health() with auto circuit breaker trigger,
  consecutive failure tracking, incident timeline, and recovery
- #681: Add rate history snapshots, simulate_rate_at_utilization(),
  average rate calculation, and rate change tracking
- #682: Add optimize_allocation() with utilization-based recommendations,
  rebalance threshold detection, and yield improvement estimates
- #683: Add priority ordering to batch_liquidate() with insertion sort
  by profit potential and calculate_priority_score()

Closes #680, #681, #682, #683

Author: brightcli-stack

stellar-lend/contracts/hello-world/src/amm.rs

@@ -386,3 +386,156 @@ pub fn get_il_snapshot(env: &Env, asset: &Address) -> Option<IlSnapshot> {
         .persistent()
         .get(&AmmLendingKey::IlTracking(asset.clone()))
 }
+
+// ─── Pool Allocation Optimizer (#682) ─────────────────────────────────────────
+
+/// Target utilization for optimal capital efficiency (80%)
+const OPTIMAL_UTILIZATION_BPS: i128 = 8000;
+
+/// Minimum rebalance threshold (5% difference to trigger rebalance)
+const REBALANCE_THRESHOLD_BPS: i128 = 500;
+
+/// Pool allocation recommendation
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct AllocationRecommendation {
+    pub asset: Address,
+    pub current_utilization_bps: i128,
+    pub recommended_allocation_bps: i128,
+    pub action: AllocationAction,
+    pub amount: i128,
+}
+
+/// Action to take for allocation optimization
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub enum AllocationAction {
+    /// Move funds into this pool (under-utilized)
+    Increase,
+    /// Move funds out of this pool (over-utilized)
+    Decrease,
+    /// No change needed
+    NoChange,
+}
+
+/// Result of an optimization pass
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct OptimizationResult {
+    pub recommendations: Vec<AllocationRecommendation>,
+    pub total_capital_efficiency_bps: i128,
+    pub estimated_yield_improvement_bps: i128,
+}
+
+/// Analyze pool utilization and recommend allocation changes.
+///
+/// Examines all tracked pools and recommends rebalancing actions to
+/// maximize capital efficiency while maintaining safety buffers.
+pub fn optimize_allocation(
+    env: &Env,
+    pools: &Vec<Address>,
+) -> Result<OptimizationResult, AmmError> {
+    let mut recommendations: Vec<AllocationRecommendation> = Vec::new(env);
+    let mut total_utilization: i128 = 0;
+    let mut pool_count: i128 = 0;
+
+    for pool in pools.iter() {
+        let utilization_key = AmmLendingKey::PoolUtilization(pool.clone());
+        let current_utilization: i128 = env
+            .storage()
+            .persistent()
+            .get::<AmmLendingKey, i128>(&utilization_key)
+            .unwrap_or(0);
+
+        total_utilization = total_utilization.saturating_add(current_utilization);
+        pool_count = pool_count.saturating_add(1);
+
+        let deviation = if current_utilization > OPTIMAL_UTILIZATION_BPS {
+            current_utilization - OPTIMAL_UTILIZATION_BPS
+        } else {
+            OPTIMAL_UTILIZATION_BPS - current_utilization
+        };
+
+        let (action, amount) = if deviation < REBALANCE_THRESHOLD_BPS {
+            (AllocationAction::NoChange, 0)
+        } else if current_utilization < OPTIMAL_UTILIZATION_BPS {
+            // Under-utilized — increase allocation
+            let buffer_key = AmmLendingKey::WithdrawalBufferBps(pool.clone());
+            let buffer_bps: i128 = env
+                .storage()
+                .persistent()
+                .get::<AmmLendingKey, i128>(&buffer_key)
+                .unwrap_or(DEFAULT_WITHDRAWAL_BUFFER_BPS);
+            let available = BPS_SCALE.saturating_sub(buffer_bps);
+            let increase_amount = available
+                .saturating_mul(OPTIMAL_UTILIZATION_BPS - current_utilization)
+                .checked_div(BPS_SCALE)
+                .unwrap_or(0);
+            (AllocationAction::Increase, increase_amount)
+        } else {
+            // Over-utilized — decrease allocation
+            let excess = current_utilization - OPTIMAL_UTILIZATION_BPS;
+            let decrease_amount = excess
+                .saturating_mul(current_utilization)
+                .checked_div(BPS_SCALE)
+                .unwrap_or(0);
+            (AllocationAction::Decrease, decrease_amount)
+        };
+
+        recommendations.push_back(AllocationRecommendation {
+            asset: pool.clone(),
+            current_utilization_bps: current_utilization,
+            recommended_allocation_bps: OPTIMAL_UTILIZATION_BPS,
+            action,
+            amount,
+        });
+    }
+
+    let avg_utilization = if pool_count > 0 {
+        total_utilization.checked_div(pool_count).unwrap_or(0)
+    } else {
+        0
+    };
+
+    // Estimate yield improvement: closer to optimal = better yield
+    let efficiency = if avg_utilization <= OPTIMAL_UTILIZATION_BPS {
+        avg_utilization
+    } else {
+        // Over-utilization means higher rates but more risk
+        OPTIMAL_UTILIZATION_BPS
+    };
+
+    // Yield improvement estimate: moving from current to optimal
+    let yield_improvement = if avg_utilization < OPTIMAL_UTILIZATION_BPS {
+        (OPTIMAL_UTILIZATION_BPS - avg_utilization).checked_div(100).unwrap_or(0)
+    } else {
+        0
+    };
+
+    Ok(OptimizationResult {
+        recommendations,
+        total_capital_efficiency_bps: efficiency,
+        estimated_yield_improvement_bps: yield_improvement,
+    })
+}
+
+/// Update the utilization snapshot for a pool.
+///
+/// Should be called whenever deposits/withdrawals/borrows change pool state.
+pub fn update_pool_utilization(
+    env: &Env,
+    asset: &Address,
+    utilization_bps: i128,
+) {
+    let key = AmmLendingKey::PoolUtilization(asset.clone());
+    env.storage().persistent().set(&key, &utilization_bps);
+}
+
+/// Get the current utilization snapshot for a pool.
+pub fn get_pool_utilization(env: &Env, asset: &Address) -> i128 {
+    let key = AmmLendingKey::PoolUtilization(asset.clone());
+    env.storage()
+        .persistent()
+        .get::<AmmLendingKey, i128>(&key)
+        .unwrap_or(0)
+}

stellar-lend/contracts/hello-world/src/interest_rate.rs

@@ -568,3 +568,182 @@ pub fn compute_index_interest(
         .ok_or(InterestRateError::DivisionByZero)?;
     Ok(interest)
 }
+
+// ── Rate History & Dynamic Adjustment (#681) ───────────────────────────────
+
+/// Maximum number of rate history entries to keep per asset
+const MAX_RATE_HISTORY: u32 = 100;
+
+/// A snapshot of the interest rate at a point in time
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct RateHistoryEntry {
+    /// Borrow rate at this point (bps)
+    pub borrow_rate_bps: i128,
+    /// Supply rate at this point (bps)
+    pub supply_rate_bps: i128,
+    /// Utilization at this point (bps)
+    pub utilization_bps: i128,
+    /// Timestamp of the snapshot
+    pub timestamp: u64,
+}
+
+/// Storage keys for rate history
+#[contracttype]
+#[derive(Clone)]
+pub enum RateHistoryKey {
+    /// Vec<RateHistoryEntry> — rolling window of rate snapshots
+    RateHistory,
+    /// RateHistoryEntry — the last recorded snapshot
+    LastSnapshot,
+}
+
+/// Record a rate snapshot in the history.
+///
+/// Should be called whenever interest is accrued or rates are updated.
+pub fn record_rate_snapshot(env: &Env) -> Result<(), InterestRateError> {
+    let borrow_rate = calculate_borrow_rate(env)?;
+    let supply_rate = calculate_supply_rate(env)?;
+    let utilization = calculate_utilization(env)?;
+    let now = env.ledger().timestamp();
+
+    let entry = RateHistoryEntry {
+        borrow_rate_bps: borrow_rate,
+        supply_rate_bps: supply_rate,
+        utilization_bps: utilization,
+        timestamp: now,
+    };
+
+    // Store as last snapshot
+    env.storage()
+        .persistent()
+        .set(&RateHistoryKey::LastSnapshot, &entry);
+
+    // Append to rolling history
+    let history_key = RateHistoryKey::RateHistory;
+    let mut history: Vec<RateHistoryEntry> = env
+        .storage()
+        .persistent()
+        .get::<RateHistoryKey, Vec<RateHistoryEntry>>(&history_key)
+        .unwrap_or_else(|| Vec::new(env));
+
+    history.push_back(entry);
+
+    // Trim to max size
+    let mut trimmed: Vec<RateHistoryEntry> = Vec::new(env);
+    let start = if history.len() as u32 > MAX_RATE_HISTORY {
+        history.len() - MAX_RATE_HISTORY
+    } else {
+        0
+    };
+    for i in start..history.len() {
+        trimmed.push_back(history.get(i).unwrap());
+    }
+
+    env.storage().persistent().set(&history_key, &trimmed);
+
+    Ok(())
+}
+
+/// Get the rate history.
+pub fn get_rate_history(env: &Env) -> Vec<RateHistoryEntry> {
+    let key = RateHistoryKey::RateHistory;
+    env.storage()
+        .persistent()
+        .get::<RateHistoryKey, Vec<RateHistoryEntry>>(&key)
+        .unwrap_or_else(|| Vec::new(env))
+}
+
+/// Get the last recorded rate snapshot.
+pub fn get_last_rate_snapshot(env: &Env) -> Option<RateHistoryEntry> {
+    env.storage()
+        .persistent()
+        .get::<RateHistoryKey, RateHistoryEntry>(&RateHistoryKey::LastSnapshot)
+}
+
+/// Simulate what the borrow rate would be at a given utilization level.
+///
+/// Does not modify state — purely a read-only calculation.
+///
+/// # Arguments
+/// * `env` - The Soroban environment
+/// * `target_utilization_bps` - The utilization to simulate (0-10000)
+///
+/// # Returns
+/// The simulated borrow rate in basis points
+pub fn simulate_rate_at_utilization(
+    env: &Env,
+    target_utilization_bps: i128,
+) -> Result<i128, InterestRateError> {
+    let config = get_interest_rate_config(env).ok_or(InterestRateError::InvalidParameter)?;
+
+    if target_utilization_bps < 0 || target_utilization_bps > BASIS_POINTS_SCALE {
+        return Err(InterestRateError::InvalidParameter);
+    }
+
+    let mut rate = config.base_rate_bps;
+
+    if target_utilization_bps <= config.kink_utilization_bps {
+        if config.kink_utilization_bps > 0 {
+            let rate_increase = target_utilization_bps
+                .checked_mul(config.multiplier_bps)
+                .ok_or(InterestRateError::Overflow)?
+                .checked_div(config.kink_utilization_bps)
+                .ok_or(InterestRateError::DivisionByZero)?;
+            rate = rate
+                .checked_add(rate_increase)
+                .ok_or(InterestRateError::Overflow)?;
+        }
+    } else {
+        let rate_at_kink = config
+            .base_rate_bps
+            .checked_add(config.multiplier_bps)
+            .ok_or(InterestRateError::Overflow)?;
+
+        let above_kink = target_utilization_bps
+            .checked_sub(config.kink_utilization_bps)
+            .ok_or(InterestRateError::Overflow)?;
+
+        let max_above = BASIS_POINTS_SCALE
+            .checked_sub(config.kink_utilization_bps)
+            .ok_or(InterestRateError::Overflow)?;
+
+        if max_above > 0 {
+            let additional = above_kink
+                .checked_mul(config.jump_multiplier_bps)
+                .ok_or(InterestRateError::Overflow)?
+                .checked_div(max_above)
+                .ok_or(InterestRateError::DivisionByZero)?;
+            rate = rate_at_kink
+                .checked_add(additional)
+                .ok_or(InterestRateError::Overflow)?;
+        } else {
+            rate = rate_at_kink;
+        }
+    }
+
+    rate = rate
+        .checked_add(config.emergency_adjustment_bps)
+        .ok_or(InterestRateError::Overflow)?;
+
+    Ok(rate.max(config.rate_floor_bps).min(config.rate_ceiling_bps))
+}
+
+/// Get the average borrow rate over the recorded history.
+pub fn get_average_borrow_rate(env: &Env) -> Result<i128, InterestRateError> {
+    let history = get_rate_history(env);
+    if history.is_empty() {
+        return Ok(0);
+    }
+
+    let mut total: i128 = 0;
+    for entry in history.iter() {
+        total = total
+            .checked_add(entry.borrow_rate_bps)
+            .ok_or(InterestRateError::Overflow)?;
+    }
+
+    total
+        .checked_div(history.len() as i128)
+        .ok_or(InterestRateError::DivisionByZero)
+}