hypercall/liquidator/

executor.rs

//! Liquidation executor service.
//!
//! Owns full-liquidation transaction submission and stop requests.

use super::cache::LiquidationCache;
#[cfg(test)]
use super::state::LiquidatedMetadata;
use super::state::{has_material_projection_change, LiquidationState};
use crate::read_cache::portfolio::PortfolioCache;
use crate::rsm_directive_publisher::RsmDirectivePublisher;
use alloy::primitives::U256;
use alloy::sol_types::SolValue;
use anyhow::anyhow;
use hypercall_signer::{encode_action_bytes, RsmSigner};
use hypercall_types::directives::{
    StartLiquidation, StopLiquidation, SYSTEM_ACTION_ID_START_LIQUIDATION,
    SYSTEM_ACTION_ID_STOP_LIQUIDATION, SYSTEM_ACTION_VERSION,
};
use hypercall_types::WalletAddress;
use hypercall_types::{EngineMessage, LiquidationStateMessage, LiquidationStateType};
use metrics::counter;
use rust_decimal::prelude::ToPrimitive;
use rust_decimal::Decimal;
use rust_decimal::RoundingStrategy;
use rust_decimal_macros::dec;
use std::sync::Arc;
use tokio::sync::mpsc;
use tracing::{info, warn};
use uuid::Uuid;

const ONCHAIN_USDC_SCALE_DP: u32 = 6;

/// Liquidation executor service.
///
/// Orchestrates full-liquidation request submission and reconciliation metadata updates.
pub struct LiquidationExecutor {
    /// Liquidation state cache.
    cache: Arc<LiquidationCache>,
    /// Portfolio cache for getting account positions.
    portfolio_cache: Arc<PortfolioCache>,
    /// Event sender for publishing state changes.
    event_sender: Option<mpsc::UnboundedSender<EngineMessage>>,
    /// Shared publisher for signed RSM transaction requests.
    rsm_directive_publisher: Option<Arc<RsmDirectivePublisher>>,
    /// Shared backend RSM signer.
    rsm_signer: Option<Arc<dyn RsmSigner>>,
    /// Target health buffer after full liquidation, in basis points.
    full_target_buffer_bps: u32,
}

impl LiquidationExecutor {
    /// Create a new liquidation executor.
    pub fn new(cache: Arc<LiquidationCache>, portfolio_cache: Arc<PortfolioCache>) -> Self {
        Self {
            cache,
            portfolio_cache,
            event_sender: None,
            rsm_directive_publisher: None,
            rsm_signer: None,
            full_target_buffer_bps: 0,
        }
    }

    /// Set the event sender for publishing state changes.
    pub fn with_event_sender(mut self, sender: mpsc::UnboundedSender<EngineMessage>) -> Self {
        self.event_sender = Some(sender);
        self
    }

    pub fn with_rsm_directive_publisher(mut self, publisher: Arc<RsmDirectivePublisher>) -> Self {
        self.rsm_directive_publisher = Some(publisher);
        self
    }

    pub fn with_rsm_signer(mut self, rsm_signer: Arc<dyn RsmSigner>) -> Self {
        self.rsm_signer = Some(rsm_signer);
        self
    }

    pub fn with_full_target_buffer_bps(mut self, full_target_buffer_bps: u32) -> Self {
        self.full_target_buffer_bps = full_target_buffer_bps;
        self
    }

    /// Submit a `StartLiquidation` request for a wallet already in pre-liquidation.
    ///
    /// The account remains in `PreLiquidation` until the chain observer sees
    /// `LiquidationStarted` on-chain.
    pub async fn start_auction(&self, wallet: &WalletAddress) -> anyhow::Result<String> {
        let rsm_signer = self
            .rsm_signer
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("RsmSignerService not configured"))?;
        let rsm_directive_publisher = self
            .rsm_directive_publisher
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("RsmDirectivePublisher not configured"))?;
        let status = self
            .cache
            .get_status(wallet)
            .await
            .ok_or_else(|| anyhow::anyhow!("wallet {} missing liquidation status", wallet))?;
        let partial_metadata = match &status.state {
            LiquidationState::PreLiquidation(metadata) => metadata,
            other => {
                anyhow::bail!(
                    "full liquidation can only be requested from pre-liquidation, wallet {} is in {}",
                    wallet,
                    other.as_str()
                );
            }
        };
        if let Some(existing_request_id) = partial_metadata.pending_full_request_id.clone() {
            let auction_id = partial_metadata
                .pending_full_auction_id
                .clone()
                .ok_or_else(|| {
                    anyhow::anyhow!(
                        "wallet {} has pending full liquidation request {} without auction id",
                        wallet,
                        existing_request_id
                    )
                })?;
            info!(
                wallet = %wallet,
                auction_id = %auction_id,
                request_id = %existing_request_id,
                "Skipping duplicate full liquidation request while one is already pending"
            );
            return Ok(auction_id);
        }
        let margin_needed = Self::compute_margin_needed(self.full_target_buffer_bps, &status);
        if margin_needed <= Decimal::ZERO {
            anyhow::bail!(
                "refusing to start liquidation for {} with non-positive margin_needed={}",
                wallet,
                margin_needed
            );
        }

        let auction_id = Uuid::now_v7().to_string();
        let request_id = Uuid::now_v7().to_string();
        let timestamp = get_timestamp_millis();

        // Get positions for this wallet
        let positions = self.get_position_symbols(wallet).await;

        let action = encode_start_liquidation_action(status.equity, margin_needed)?;
        let signed = rsm_signer
            .sign(&request_id, wallet, &action)
            .await
            .map_err(|error| anyhow!("{}", error))?;
        let mut current_status = self
            .cache
            .get_status(wallet)
            .await
            .ok_or_else(|| anyhow::anyhow!("wallet {} missing liquidation status", wallet))?;
        let previous_state = current_status.state.clone();
        if !Self::apply_start_claim(
            &mut current_status,
            wallet,
            &auction_id,
            &request_id,
            margin_needed,
            timestamp,
        ) {
            info!(
                wallet = %wallet,
                auction_id = %auction_id,
                request_id = %request_id,
                current_state = %current_status.state.as_str(),
                "Skipped persisting stale full liquidation start claim because wallet state advanced during directive submission"
            );
            return Ok(auction_id);
        }
        self.cache.set_status(current_status.clone()).await;
        self.emit_status_update(&previous_state, &current_status, timestamp);
        if let Err(error) = rsm_directive_publisher
            .publish(&request_id, wallet, signed)
            .await
        {
            self.clear_start_claim_after_publish_failure(wallet, &request_id)
                .await;
            return Err(error);
        }
        info!(
            wallet = %wallet,
            auction_id = %auction_id,
            request_id = %request_id,
            positions = ?positions,
            equity = %status.equity,
            mm_required = %status.mm_required,
            margin_needed = %margin_needed,
            "Enqueued full liquidation start directive"
        );
        counter!("ht_liquidation_full_start_requests_total").increment(1);

        info!(
            "Enqueued liquidation auction {} for wallet {} with {} positions, request_id={}",
            auction_id,
            wallet,
            positions.len(),
            request_id
        );

        Ok(auction_id)
    }

    /// Submit a `StopLiquidation` request for an active full liquidation.
    ///
    /// The account remains in `InLiquidation` until the chain observer sees
    /// `LiquidationStopped` on-chain.
    pub async fn stop_auction(
        &self,
        wallet: &WalletAddress,
        start_time: u64,
    ) -> anyhow::Result<String> {
        let rsm_signer = self
            .rsm_signer
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("RsmSignerService not configured"))?;
        let rsm_directive_publisher = self
            .rsm_directive_publisher
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("RsmDirectivePublisher not configured"))?;
        let status = self
            .cache
            .get_status(wallet)
            .await
            .ok_or_else(|| anyhow::anyhow!("wallet {} missing liquidation status", wallet))?;
        let metadata = match &status.state {
            LiquidationState::InLiquidation(metadata) => metadata,
            other => {
                anyhow::bail!(
                    "stop liquidation requires in-liquidation state, wallet {} is in {}",
                    wallet,
                    other.as_str()
                );
            }
        };

        if let Some(existing_request_id) = metadata.stop_request_id.clone() {
            info!(
                wallet = %wallet,
                auction_id = %metadata.auction_id,
                request_id = %existing_request_id,
                "Skipping duplicate stop liquidation request while one is already pending"
            );
            return Ok(existing_request_id);
        }

        let chain_start_time = metadata.chain_start_time.ok_or_else(|| {
            anyhow::anyhow!(
                "cannot submit stop liquidation for {} without observed chain_start_time",
                wallet
            )
        })?;
        if chain_start_time != start_time {
            anyhow::bail!(
                "stop liquidation start_time mismatch for {}: observed={}, requested={}",
                wallet,
                chain_start_time,
                start_time
            );
        }

        let auction_id = metadata.auction_id.clone();
        let request_id = Uuid::now_v7().to_string();
        let action = encode_stop_liquidation_action(start_time)?;
        let signed = rsm_signer
            .sign(&request_id, wallet, &action)
            .await
            .map_err(|error| anyhow!("{}", error))?;
        let timestamp = get_timestamp_millis();
        let mut current_status = self
            .cache
            .get_status(wallet)
            .await
            .ok_or_else(|| anyhow::anyhow!("wallet {} missing liquidation status", wallet))?;
        let previous_state = current_status.state.clone();
        if !Self::apply_stop_claim(&mut current_status, wallet, &request_id, timestamp) {
            info!(
                wallet = %wallet,
                auction_id = %auction_id,
                request_id = %request_id,
                current_state = %current_status.state.as_str(),
                "Skipped persisting stale stop liquidation claim because wallet state advanced during directive submission"
            );
            return Ok(request_id);
        }
        self.cache.set_status(current_status.clone()).await;
        self.emit_status_update(&previous_state, &current_status, timestamp);
        if let Err(error) = rsm_directive_publisher
            .publish(&request_id, wallet, signed)
            .await
        {
            self.clear_stop_claim_after_publish_failure(wallet, &request_id)
                .await;
            return Err(error);
        }
        counter!("ht_liquidation_full_stop_requests_total").increment(1);

        info!(
            wallet = %wallet,
            auction_id = %auction_id,
            request_id = %request_id,
            start_time,
            "Enqueued stop liquidation directive"
        );

        Ok(request_id)
    }

    /// Get position symbols for a wallet.
    async fn get_position_symbols(&self, wallet: &WalletAddress) -> Vec<String> {
        match self
            .portfolio_cache
            .get_service()
            .get_portfolio_balance(wallet)
            .await
        {
            Some(portfolio) => portfolio.positions.keys().cloned().collect(),
            None => Vec::new(),
        }
    }

    fn compute_margin_needed(
        full_target_buffer_bps: u32,
        status: &crate::liquidator::AccountLiquidationStatus,
    ) -> Decimal {
        let buffer_multiplier =
            Decimal::from(10_000u64 + u64::from(full_target_buffer_bps)) / dec!(10000);
        let target_equity = status.mm_required * buffer_multiplier;
        let bonus = if status.equity.is_sign_negative() {
            -status.equity
        } else {
            Decimal::ZERO
        };
        let margin_needed = target_equity - status.equity - bonus;
        if margin_needed.is_sign_negative() {
            Decimal::ZERO
        } else {
            margin_needed
        }
    }

    fn apply_start_claim(
        status: &mut crate::liquidator::AccountLiquidationStatus,
        wallet: &WalletAddress,
        auction_id: &str,
        request_id: &str,
        margin_needed: Decimal,
        timestamp: u64,
    ) -> bool {
        let LiquidationState::PreLiquidation(metadata) = &mut status.state else {
            warn!(
                wallet = %wallet,
                current_state = %status.state.as_str(),
                "Wallet left pre-liquidation before full start claim persistence, preserving newer state"
            );
            return false;
        };

        metadata.pending_full_auction_id = Some(auction_id.to_string());
        metadata.pending_full_request_id = Some(request_id.to_string());
        metadata.pending_full_tx_hash = None;
        metadata.pending_full_margin_needed = Some(margin_needed);
        status.updated_at = timestamp;
        true
    }

    fn apply_stop_claim(
        status: &mut crate::liquidator::AccountLiquidationStatus,
        wallet: &WalletAddress,
        request_id: &str,
        timestamp: u64,
    ) -> bool {
        let LiquidationState::InLiquidation(metadata) = &mut status.state else {
            warn!(
                wallet = %wallet,
                current_state = %status.state.as_str(),
                "Wallet left in-liquidation before stop claim persistence, preserving newer state"
            );
            return false;
        };

        metadata.stop_request_id = Some(request_id.to_string());
        metadata.stop_tx_hash = None;
        status.updated_at = timestamp;
        true
    }

    async fn clear_start_claim_after_publish_failure(
        &self,
        wallet: &WalletAddress,
        request_id: &str,
    ) {
        let timestamp = get_timestamp_millis();
        let Some(mut status) = self.cache.get_status(wallet).await else {
            warn!(
                wallet = %wallet,
                request_id,
                "Cannot clear failed full liquidation start claim because wallet status is missing"
            );
            return;
        };
        let previous_state = status.state.clone();
        if Self::clear_start_claim(&mut status, wallet, request_id, timestamp) {
            self.cache.set_status(status.clone()).await;
            self.emit_status_update(&previous_state, &status, timestamp);
        }
    }

    async fn clear_stop_claim_after_publish_failure(
        &self,
        wallet: &WalletAddress,
        request_id: &str,
    ) {
        let timestamp = get_timestamp_millis();
        let Some(mut status) = self.cache.get_status(wallet).await else {
            warn!(
                wallet = %wallet,
                request_id,
                "Cannot clear failed stop liquidation claim because wallet status is missing"
            );
            return;
        };
        let previous_state = status.state.clone();
        if Self::clear_stop_claim(&mut status, wallet, request_id, timestamp) {
            self.cache.set_status(status.clone()).await;
            self.emit_status_update(&previous_state, &status, timestamp);
        }
    }

    fn clear_start_claim(
        status: &mut crate::liquidator::AccountLiquidationStatus,
        wallet: &WalletAddress,
        request_id: &str,
        timestamp: u64,
    ) -> bool {
        let LiquidationState::PreLiquidation(metadata) = &mut status.state else {
            warn!(
                wallet = %wallet,
                request_id,
                current_state = %status.state.as_str(),
                "Wallet left pre-liquidation before failed full start claim cleanup, preserving newer state"
            );
            return false;
        };

        if metadata.pending_full_request_id.as_deref() != Some(request_id) {
            warn!(
                wallet = %wallet,
                request_id,
                current_request_id = ?metadata.pending_full_request_id,
                "Skipping failed full start claim cleanup because pending request changed"
            );
            return false;
        }

        metadata.pending_full_auction_id = None;
        metadata.pending_full_request_id = None;
        metadata.pending_full_tx_hash = None;
        metadata.pending_full_margin_needed = None;
        status.updated_at = timestamp;
        true
    }

    fn clear_stop_claim(
        status: &mut crate::liquidator::AccountLiquidationStatus,
        wallet: &WalletAddress,
        request_id: &str,
        timestamp: u64,
    ) -> bool {
        let LiquidationState::InLiquidation(metadata) = &mut status.state else {
            warn!(
                wallet = %wallet,
                request_id,
                current_state = %status.state.as_str(),
                "Wallet left in-liquidation before failed stop claim cleanup, preserving newer state"
            );
            return false;
        };

        if metadata.stop_request_id.as_deref() != Some(request_id) {
            warn!(
                wallet = %wallet,
                request_id,
                current_request_id = ?metadata.stop_request_id,
                "Skipping failed stop claim cleanup because pending request changed"
            );
            return false;
        }

        metadata.stop_request_id = None;
        metadata.stop_tx_hash = None;
        status.updated_at = timestamp;
        true
    }

    fn emit_status_update(
        &self,
        previous_state: &LiquidationState,
        status: &crate::liquidator::AccountLiquidationStatus,
        timestamp: u64,
    ) {
        let Some(sender) = &self.event_sender else {
            return;
        };

        let msg = LiquidationStateMessage {
            wallet: status.wallet,
            previous_state: liquidation_state_to_type(previous_state),
            new_state: liquidation_state_to_type(&status.state),
            previous_liquidation_mode: previous_state
                .liquidation_mode()
                .map(|mode| mode.as_str().to_string()),
            liquidation_mode: status
                .liquidation_mode()
                .map(|mode| mode.as_str().to_string()),
            margin_mode: status.margin_mode.as_str().to_string(),
            equity: status.equity,
            mm_required: status.mm_required,
            maintenance_margin: status.maintenance_margin,
            shortfall: status.shortfall(),
            previous_auction_id: previous_state.auction_id().map(str::to_string),
            projection_changed: has_material_projection_change(previous_state, &status.state),
            auction_id: status
                .state
                .auction_id()
                .map(ToOwned::to_owned)
                .or_else(|| previous_state.auction_id().map(ToOwned::to_owned)),
            status: status.clone(),
            timestamp,
        };

        if let Err(e) = sender.send(EngineMessage::LiquidationStateChange(msg)) {
            warn!("Failed to send liquidation state change event: {}", e);
        }
    }
}

fn encode_start_liquidation_action(
    equity: Decimal,
    margin_needed: Decimal,
) -> anyhow::Result<Vec<u8>> {
    if margin_needed <= Decimal::ZERO {
        anyhow::bail!(
            "refusing to submit StartLiquidation with non-positive margin_needed={}",
            margin_needed
        );
    }

    let equity_units = scaled_signed_usdc_units(equity, "equity")?;
    let margin_needed_units = scaled_unsigned_usdc_units(margin_needed, "margin_needed")?;
    if margin_needed_units == 0 {
        anyhow::bail!(
            "margin_needed quantized to zero after USDC scaling (raw={})",
            margin_needed
        );
    }

    encode_action_bytes(
        SYSTEM_ACTION_VERSION,
        SYSTEM_ACTION_ID_START_LIQUIDATION,
        &StartLiquidation {
            equity: alloy::primitives::I256::try_from(equity_units).map_err(|error| {
                anyhow!("equity {} exceeds I256 range: {}", equity_units, error)
            })?,
            marginNeeded: U256::from(margin_needed_units),
        }
        .abi_encode(),
    )
    .map_err(|error| anyhow!("{}", error))
}

fn encode_stop_liquidation_action(start_time: u64) -> anyhow::Result<Vec<u8>> {
    if start_time == 0 {
        anyhow::bail!("refusing to submit StopLiquidation with start_time=0");
    }

    encode_action_bytes(
        SYSTEM_ACTION_VERSION,
        SYSTEM_ACTION_ID_STOP_LIQUIDATION,
        &StopLiquidation {
            startTime: U256::from(start_time),
        }
        .abi_encode(),
    )
    .map_err(|error| anyhow!("{}", error))
}

fn quantize_onchain_usdc_units(amount: Decimal) -> Decimal {
    amount.round_dp_with_strategy(
        ONCHAIN_USDC_SCALE_DP,
        RoundingStrategy::MidpointAwayFromZero,
    )
}

fn scaled_unsigned_usdc_units(amount: Decimal, field: &str) -> anyhow::Result<u128> {
    if amount < Decimal::ZERO {
        anyhow::bail!("{} must be non-negative, got {}", field, amount);
    }
    let scaled =
        quantize_onchain_usdc_units(amount) * hypercall_types::CONTRACT_UNIT_MULTIPLIER_DECIMAL;
    scaled
        .to_u128()
        .ok_or_else(|| anyhow!("{}={} exceeds u128 range after scaling", field, amount))
}

fn scaled_signed_usdc_units(amount: Decimal, field: &str) -> anyhow::Result<i128> {
    let scaled =
        quantize_onchain_usdc_units(amount) * hypercall_types::CONTRACT_UNIT_MULTIPLIER_DECIMAL;
    scaled
        .to_i128()
        .ok_or_else(|| anyhow!("{}={} exceeds i128 range after scaling", field, amount))
}

/// Get current timestamp in milliseconds.
fn get_timestamp_millis() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default()
        .as_millis() as u64
}

/// Convert LiquidationState to LiquidationStateType for messages.
fn liquidation_state_to_type(state: &LiquidationState) -> LiquidationStateType {
    match state {
        LiquidationState::Healthy => LiquidationStateType::Healthy,
        LiquidationState::PreLiquidation(..) => LiquidationStateType::PreLiquidation,
        LiquidationState::InLiquidation(..) => LiquidationStateType::InLiquidation,
        LiquidationState::Liquidated(..) => LiquidationStateType::Liquidated,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::liquidator::{
        AccountLiquidationStatus, FullLiquidationMetadata, LiquidationCache,
        PartialLiquidationMetadata,
    };
    use crate::rsm::MarginMode;
    use rust_decimal_macros::dec;

    fn test_wallet() -> WalletAddress {
        "0x1234567890123456789012345678901234567890"
            .parse()
            .unwrap()
    }

    fn test_liquidator() -> WalletAddress {
        "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
            .parse()
            .unwrap()
    }

    fn partial_metadata() -> PartialLiquidationMetadata {
        PartialLiquidationMetadata {
            entered_at: 2_000,
            mm_shortfall: dec!(1000),
            target_equity: dec!(5_500),
            escalation_deadline: 62_000,
            last_reprice_at: None,
            active_order_request_ids: vec![],
            active_order_client_ids: vec![],
            bonus_bps: 0,
            pending_full_auction_id: None,
            pending_full_request_id: None,
            pending_full_tx_hash: None,
            pending_full_margin_needed: None,
        }
    }

    /// Test cache state transitions without PortfolioCache (simpler test setup).
    /// The full integration with PortfolioCache is tested elsewhere.
    #[tokio::test]
    async fn test_cache_transitions_for_liquidation() {
        let cache = Arc::new(LiquidationCache::new());
        let wallet = test_wallet();

        // Initialize wallet in cache
        cache
            .init_if_absent(wallet, MarginMode::Standard, dec!(4000), dec!(5000), 1000)
            .await;

        // Verify starts healthy
        let state = cache.get_state(&wallet).await;
        assert!(state.is_healthy());

        // Enter pre-liquidation
        cache
            .enter_pre_liquidation(&wallet, partial_metadata(), 2000)
            .await;
        let state = cache.get_state(&wallet).await;
        assert!(state.is_pre_liquidation());

        // Enter liquidation (simulates what executor.start_auction does)
        let auction_id = "test-auction-123".to_string();
        cache
            .enter_liquidation(
                &wallet,
                FullLiquidationMetadata {
                    auction_id: auction_id.clone(),
                    request_id: None,
                    tx_hash: None,
                    started_at: 3_000,
                    chain_start_time: None,
                    margin_needed: dec!(1000),
                    stop_request_id: None,
                    stop_tx_hash: None,
                },
                3000,
            )
            .await;
        let state = cache.get_state(&wallet).await;
        assert!(state.is_in_liquidation());
        assert_eq!(state.auction_id(), Some(auction_id.as_str()));

        // Complete liquidation (simulates what executor.settle_auction does)
        cache
            .complete_liquidation(
                &wallet,
                LiquidatedMetadata {
                    auction_id,
                    completed_at: 4_000,
                    winner: Some(test_liquidator()),
                    bonus: Decimal::ZERO,
                    tx_hash: None,
                },
                4000,
            )
            .await;
        let state = cache.get_state(&wallet).await;
        assert!(state.is_liquidated());
    }

    #[tokio::test]
    async fn test_settle_and_complete_logs_onchain_calls() {
        let cache = Arc::new(LiquidationCache::new());
        let wallet = test_wallet();
        let liquidator = test_liquidator();

        // Initialize wallet in InLiquidation state
        cache
            .init_if_absent(wallet, MarginMode::Standard, dec!(4000), dec!(5000), 1000)
            .await;
        cache
            .enter_liquidation(
                &wallet,
                FullLiquidationMetadata {
                    auction_id: "auction-123".to_string(),
                    request_id: None,
                    tx_hash: None,
                    started_at: 2_000,
                    chain_start_time: None,
                    margin_needed: dec!(1000),
                    stop_request_id: None,
                    stop_tx_hash: None,
                },
                2000,
            )
            .await;

        // Settle auction using the cache method
        let result = cache
            .settle_and_complete_liquidation(&wallet, "auction-123", &liquidator, dec!(3500), 3000)
            .await;

        assert!(result.is_some());

        // Verify state is now Liquidated
        let state = cache.get_state(&wallet).await;
        assert!(state.is_liquidated());
    }

    #[test]
    fn test_compute_margin_needed_for_solvent_account() {
        let status = AccountLiquidationStatus::healthy(
            test_wallet(),
            MarginMode::Standard,
            dec!(90),
            dec!(100),
            1_000,
        );

        let margin_needed = LiquidationExecutor::compute_margin_needed(500, &status);

        assert_eq!(margin_needed, dec!(15));
    }

    #[test]
    fn test_compute_margin_needed_for_insolvent_account() {
        let status = AccountLiquidationStatus::healthy(
            test_wallet(),
            MarginMode::Standard,
            dec!(-10),
            dec!(100),
            1_000,
        );

        let margin_needed = LiquidationExecutor::compute_margin_needed(500, &status);

        assert_eq!(margin_needed, dec!(105));
    }

    #[test]
    fn test_apply_start_claim_updates_pre_liquidation_status() {
        let wallet = test_wallet();
        let mut status = AccountLiquidationStatus::healthy(
            wallet,
            MarginMode::Standard,
            dec!(90),
            dec!(100),
            1_000,
        );
        status.enter_pre_liquidation(partial_metadata(), 2_000);

        let applied = LiquidationExecutor::apply_start_claim(
            &mut status,
            &wallet,
            "auction-123",
            "request-123",
            dec!(15),
            3_000,
        );

        assert!(applied);
        match &status.state {
            LiquidationState::PreLiquidation(metadata) => {
                assert_eq!(
                    metadata.pending_full_auction_id.as_deref(),
                    Some("auction-123")
                );
                assert_eq!(
                    metadata.pending_full_request_id.as_deref(),
                    Some("request-123")
                );
                assert_eq!(metadata.pending_full_margin_needed, Some(dec!(15)));
            }
            other => panic!("expected pre-liquidation status, got {}", other.as_str()),
        }
        assert_eq!(status.updated_at, 3_000);
    }

    #[test]
    fn test_apply_start_claim_preserves_newer_liquidation_state() {
        let wallet = test_wallet();
        let mut status = AccountLiquidationStatus::healthy(
            wallet,
            MarginMode::Standard,
            dec!(90),
            dec!(100),
            1_000,
        );
        status.enter_liquidation(
            FullLiquidationMetadata {
                auction_id: "auction-live".to_string(),
                request_id: Some("existing-request".to_string()),
                tx_hash: Some("0xstart".to_string()),
                started_at: 2_000,
                chain_start_time: Some(55),
                margin_needed: dec!(20),
                stop_request_id: None,
                stop_tx_hash: None,
            },
            2_000,
        );
        let original = status.clone();

        let applied = LiquidationExecutor::apply_start_claim(
            &mut status,
            &wallet,
            "auction-123",
            "request-123",
            dec!(15),
            3_000,
        );

        assert!(!applied);
        assert_eq!(status.state, original.state);
        assert_eq!(status.updated_at, original.updated_at);
    }

    #[test]
    fn test_clear_start_claim_removes_only_matching_pending_request() {
        let wallet = test_wallet();
        let mut status = AccountLiquidationStatus::healthy(
            wallet,
            MarginMode::Standard,
            dec!(90),
            dec!(100),
            1_000,
        );
        status.enter_pre_liquidation(partial_metadata(), 2_000);
        assert!(LiquidationExecutor::apply_start_claim(
            &mut status,
            &wallet,
            "auction-123",
            "request-123",
            dec!(15),
            3_000,
        ));

        assert!(!LiquidationExecutor::clear_start_claim(
            &mut status,
            &wallet,
            "other-request",
            4_000,
        ));
        match &status.state {
            LiquidationState::PreLiquidation(metadata) => {
                assert_eq!(
                    metadata.pending_full_request_id.as_deref(),
                    Some("request-123")
                );
            }
            other => panic!("expected pre-liquidation status, got {}", other.as_str()),
        }

        assert!(LiquidationExecutor::clear_start_claim(
            &mut status,
            &wallet,
            "request-123",
            5_000,
        ));
        match &status.state {
            LiquidationState::PreLiquidation(metadata) => {
                assert_eq!(metadata.pending_full_auction_id, None);
                assert_eq!(metadata.pending_full_request_id, None);
                assert_eq!(metadata.pending_full_tx_hash, None);
                assert_eq!(metadata.pending_full_margin_needed, None);
            }
            other => panic!("expected pre-liquidation status, got {}", other.as_str()),
        }
        assert_eq!(status.updated_at, 5_000);
    }

    #[test]
    fn test_apply_stop_claim_updates_in_liquidation_status() {
        let wallet = test_wallet();
        let mut status = AccountLiquidationStatus::healthy(
            wallet,
            MarginMode::Standard,
            dec!(90),
            dec!(100),
            1_000,
        );
        status.enter_liquidation(
            FullLiquidationMetadata {
                auction_id: "auction-live".to_string(),
                request_id: Some("existing-request".to_string()),
                tx_hash: Some("0xstart".to_string()),
                started_at: 2_000,
                chain_start_time: Some(55),
                margin_needed: dec!(20),
                stop_request_id: None,
                stop_tx_hash: None,
            },
            2_000,
        );

        let applied =
            LiquidationExecutor::apply_stop_claim(&mut status, &wallet, "stop-request", 3_000);

        assert!(applied);
        match &status.state {
            LiquidationState::InLiquidation(metadata) => {
                assert_eq!(metadata.stop_request_id.as_deref(), Some("stop-request"));
                assert_eq!(metadata.stop_tx_hash, None);
            }
            other => panic!("expected in-liquidation status, got {}", other.as_str()),
        }
        assert_eq!(status.updated_at, 3_000);
    }

    #[test]
    fn test_clear_stop_claim_removes_only_matching_pending_request() {
        let wallet = test_wallet();
        let mut status = AccountLiquidationStatus::healthy(
            wallet,
            MarginMode::Standard,
            dec!(90),
            dec!(100),
            1_000,
        );
        status.enter_liquidation(
            FullLiquidationMetadata {
                auction_id: "auction-live".to_string(),
                request_id: Some("existing-request".to_string()),
                tx_hash: Some("0xstart".to_string()),
                started_at: 2_000,
                chain_start_time: Some(55),
                margin_needed: dec!(20),
                stop_request_id: None,
                stop_tx_hash: None,
            },
            2_000,
        );
        assert!(LiquidationExecutor::apply_stop_claim(
            &mut status,
            &wallet,
            "stop-request",
            3_000,
        ));

        assert!(!LiquidationExecutor::clear_stop_claim(
            &mut status,
            &wallet,
            "other-request",
            4_000,
        ));
        match &status.state {
            LiquidationState::InLiquidation(metadata) => {
                assert_eq!(metadata.stop_request_id.as_deref(), Some("stop-request"));
            }
            other => panic!("expected in-liquidation status, got {}", other.as_str()),
        }

        assert!(LiquidationExecutor::clear_stop_claim(
            &mut status,
            &wallet,
            "stop-request",
            5_000,
        ));
        match &status.state {
            LiquidationState::InLiquidation(metadata) => {
                assert_eq!(metadata.stop_request_id, None);
                assert_eq!(metadata.stop_tx_hash, None);
            }
            other => panic!("expected in-liquidation status, got {}", other.as_str()),
        }
        assert_eq!(status.updated_at, 5_000);
    }

    #[test]
    fn test_apply_stop_claim_preserves_terminal_state() {
        let wallet = test_wallet();
        let mut status = AccountLiquidationStatus::healthy(
            wallet,
            MarginMode::Standard,
            dec!(90),
            dec!(100),
            1_000,
        );
        status.complete_liquidation(
            LiquidatedMetadata {
                auction_id: "auction-live".to_string(),
                completed_at: 2_500,
                winner: Some(test_liquidator()),
                bonus: Decimal::ZERO,
                tx_hash: Some("0xresolve".to_string()),
            },
            2_500,
        );
        let original = status.clone();

        let applied =
            LiquidationExecutor::apply_stop_claim(&mut status, &wallet, "stop-request", 3_000);

        assert!(!applied);
        assert_eq!(status.state, original.state);
        assert_eq!(status.updated_at, original.updated_at);
    }
}