hypercall_api/handlers/

testnet.rs

#[cfg(feature = "faucet")]
use alloy::primitives::FixedBytes;
#[cfg(feature = "faucet")]
use rust_decimal::prelude::ToPrimitive;
use utoipa::ToSchema;

use crate::error::ApiError;
use crate::sonic_json::SonicJson;
use axum::extract::State;
#[cfg(any(feature = "test-endpoints", all(test, feature = "faucet")))]
use axum::http::StatusCode;
#[cfg(feature = "test-endpoints")]
use hypercall_runtime_api::MarketRequest;
#[cfg(feature = "test-endpoints")]
use hypercall_types::utils::get_timestamp_millis;
#[cfg(feature = "test-endpoints")]
use hypercall_types::ParsedOptionSymbol;
#[cfg(any(feature = "faucet", feature = "test-endpoints"))]
use hypercall_types::WalletAddress;
use serde::{Deserialize, Serialize};

use super::AppState;

#[cfg(feature = "faucet")]
use super::{FAUCET_LIFETIME_CAP_USDC, MARKET_MAKER_TIER};
#[cfg(feature = "faucet")]
use hypercall_db::FaucetWriter;
#[cfg(feature = "faucet")]
use hypercall_runtime_api::DepositRequest;
use rust_decimal::Decimal;

#[cfg(feature = "faucet")]
fn synthetic_faucet_source_event_hash(sequence: u64) -> FixedBytes<32> {
    let mut bytes = [0u8; 32];
    bytes[..8].copy_from_slice(&sequence.to_be_bytes());
    FixedBytes::from(bytes)
}

// =============================================================================
// Balance Ledger Endpoint (Testnet Only)
// =============================================================================

#[cfg(feature = "test-endpoints")]
#[derive(Debug, Deserialize, ToSchema)]
pub struct TestBalanceLedgerRequest {
    #[schema(value_type = String)]
    pub wallet: hypercall_types::WalletAddress,
}

#[cfg(feature = "test-endpoints")]
#[derive(Debug, Serialize, ToSchema)]
pub struct TestBalanceLedgerResponse {
    #[schema(value_type = String)]
    pub wallet: hypercall_types::WalletAddress,
    pub balance: String,
}

#[cfg(feature = "test-endpoints")]
pub async fn get_balance_ledger(
    State(state): State<AppState>,
    SonicJson(request): SonicJson<TestBalanceLedgerRequest>,
) -> Result<SonicJson<TestBalanceLedgerResponse>, ApiError> {
    if !state.runtime_config.testnet_mode {
        return Err(ApiError::forbidden(
            "Balance ledger test endpoint requires testnet mode",
        ));
    }

    let balance = state
        .balance_provider
        .get_balance(&request.wallet)
        .await
        .map_err(|error| {
            ApiError::internal_error(format!("failed to read engine balance ledger: {error}"))
        })?;
    Ok(SonicJson(TestBalanceLedgerResponse {
        wallet: request.wallet,
        balance: balance.to_string(),
    }))
}

// =============================================================================
// Option Deposit Endpoint (Testnet Only)
// =============================================================================

#[cfg(feature = "test-endpoints")]
#[derive(Debug, Deserialize, ToSchema)]
pub struct TestOptionDepositRequest {
    #[schema(value_type = String)]
    pub wallet: hypercall_types::WalletAddress,
    pub symbol: String,
    pub quantity: String,
}

#[cfg(feature = "test-endpoints")]
#[derive(Debug, Serialize, ToSchema)]
pub struct TestOptionDepositResponse {
    pub request_id: String,
    #[schema(value_type = String)]
    pub wallet: hypercall_types::WalletAddress,
    pub symbol: String,
    pub quantity: String,
}

#[cfg(feature = "test-endpoints")]
pub async fn apply_option_deposit(
    State(state): State<AppState>,
    SonicJson(request): SonicJson<TestOptionDepositRequest>,
) -> Result<SonicJson<TestOptionDepositResponse>, ApiError> {
    if !state.runtime_config.testnet_mode {
        return Err(ApiError::forbidden(
            "Option deposit test endpoint requires testnet mode",
        ));
    }

    let quantity = request
        .quantity
        .parse::<Decimal>()
        .map_err(|_| ApiError::bad_request("quantity must be a decimal string"))?;
    if quantity <= Decimal::ZERO {
        return Err(ApiError::bad_request("quantity must be positive"));
    }

    let sender = state.option_deposit_sender.clone().ok_or_else(|| {
        ApiError::new(
            StatusCode::SERVICE_UNAVAILABLE,
            "service_unavailable",
            "option deposit engine path disabled",
        )
    })?;
    let request_id = uuid::Uuid::now_v7().to_string();
    let timestamp_ms = get_timestamp_millis();
    let (applied_tx, applied_rx) = tokio::sync::oneshot::channel();
    sender
        .send(hypercall_runtime_api::OptionDepositRequest {
            request_id: request_id.clone(),
            wallet: request.wallet,
            symbol: request.symbol.clone(),
            quantity,
            timestamp_ms,
            applied_tx: Some(applied_tx),
        })
        .await
        .map_err(|_| {
            ApiError::new(
                StatusCode::SERVICE_UNAVAILABLE,
                "service_unavailable",
                "option deposit engine path closed",
            )
        })?;
    applied_rx
        .await
        .map_err(|_| {
            ApiError::new(
                StatusCode::SERVICE_UNAVAILABLE,
                "service_unavailable",
                "option deposit apply dropped",
            )
        })?
        .map_err(ApiError::bad_request)?;

    Ok(SonicJson(TestOptionDepositResponse {
        request_id,
        wallet: request.wallet,
        symbol: request.symbol,
        quantity: quantity.to_string(),
    }))
}

// =============================================================================
// Faucet Endpoint (compile-time gated by `faucet` feature)
// =============================================================================

#[cfg(feature = "faucet")]
/// Request body for faucet endpoint
#[derive(Debug, Deserialize, ToSchema)]
pub struct FaucetRequest {
    /// Wallet address to fund
    #[schema(value_type = String)]
    pub wallet: WalletAddress,
    /// Amount of USDC to credit (default: 10000.0 if not specified)
    #[serde(default = "default_faucet_amount")]
    pub amount: f64,
}

#[cfg(feature = "faucet")]
fn default_faucet_amount() -> f64 {
    10000.0
}

#[cfg(feature = "faucet")]
fn faucet_cap_exceeded_message() -> String {
    format!(
        "faucet lifetime deposit cap exceeded: wallet cap is {} USDC",
        FAUCET_LIFETIME_CAP_USDC
    )
}

#[cfg(feature = "faucet")]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum FaucetCapMode {
    Enforced,
    MarketMakerExempt,
}

#[cfg(feature = "faucet")]
impl FaucetCapMode {
    fn enforces_limit(self) -> bool {
        matches!(self, Self::Enforced)
    }
}

#[cfg(feature = "faucet")]
async fn resolve_faucet_cap_mode(state: &AppState, wallet: &WalletAddress) -> FaucetCapMode {
    match state.tier_cache.get_tier(wallet).await {
        Some(tier) if tier.tier == MARKET_MAKER_TIER => FaucetCapMode::MarketMakerExempt,
        _ => FaucetCapMode::Enforced,
    }
}

#[cfg(feature = "faucet")]
async fn do_persist_faucet_credit(
    db: &dyn FaucetWriter,
    wallet: &WalletAddress,
    amount: Decimal,
    request_ts_ms: i64,
    cap_mode: FaucetCapMode,
) -> Result<u64, ApiError> {
    // For market-maker-exempt mode, use Decimal::MAX as the limit (effectively unlimited).
    let limit = match cap_mode {
        FaucetCapMode::Enforced => Decimal::from(FAUCET_LIFETIME_CAP_USDC),
        FaucetCapMode::MarketMakerExempt => Decimal::MAX,
    };

    let result = db
        .persist_faucet_credit(wallet, amount, limit, request_ts_ms)
        .await
        .map_err(|e| {
            let msg = e.to_string();
            if msg.contains("exceed") {
                ApiError::bad_request(faucet_cap_exceeded_message())
            } else {
                tracing::error!("Faucet: failed to persist credit for {}: {}", wallet, e);
                ApiError::internal_error("Failed to persist faucet credit")
            }
        })?;

    Ok(result.ledger_event_id as u64)
}

#[cfg(feature = "faucet")]
fn engine_deposit_unavailable_error() -> ApiError {
    ApiError::new(
        axum::http::StatusCode::SERVICE_UNAVAILABLE,
        "service_unavailable",
        "Faucet engine deposit path is unavailable",
    )
}

#[cfg(feature = "faucet")]
async fn reserve_deposit_handoff(
    deposit_sender: &Option<tokio::sync::mpsc::Sender<DepositRequest>>,
) -> Result<tokio::sync::mpsc::OwnedPermit<DepositRequest>, ApiError> {
    let Some(deposit_tx) = deposit_sender else {
        return Err(engine_deposit_unavailable_error());
    };

    deposit_tx.clone().reserve_owned().await.map_err(|e| {
        tracing::error!("Faucet: engine deposit handoff unavailable: {}", e);
        engine_deposit_unavailable_error()
    })
}

#[cfg(feature = "faucet")]
/// Response from faucet endpoint
#[derive(Debug, Serialize, ToSchema)]
pub struct FaucetResponse {
    #[schema(value_type = String)]
    pub wallet: WalletAddress,
    pub amount_credited: f64,
    pub new_balance: f64,
}

#[cfg(feature = "faucet")]
/// Credit test funds to a wallet (testnet only)
///
/// This endpoint is only available when the `faucet` feature is enabled
/// and `modes.testnet_mode=true`.
#[utoipa::path(
    post,
    path = "/faucet",
    request_body = FaucetRequest,
    responses(
        (status = 200, description = "Funds credited successfully", body = ApiResponse<FaucetResponse>),
        (status = 400, description = "Invalid request"),
        (status = 403, description = "Faucet not enabled (production mode)"),
        (status = 500, description = "Internal server error")
    ),
    tag = "testnet"
)]
pub async fn faucet(
    State(state): State<AppState>,
    SonicJson(request): SonicJson<FaucetRequest>,
) -> Result<SonicJson<crate::models::ApiResponse<FaucetResponse>>, ApiError> {
    // Check if in testnet mode
    if !state.runtime_config.testnet_mode {
        tracing::warn!("Faucet request rejected, testnet mode is disabled in backend config.");
        return Err(ApiError::forbidden(
            "Faucet not enabled, set modes.testnet_mode=true",
        ));
    }

    // Validate request (WalletAddress is always valid since it's parsed)

    if !request.amount.is_finite() || request.amount <= 0.0 {
        tracing::error!("Faucet request with invalid amount: {}", request.amount);
        return Err(ApiError::bad_request(
            "Amount must be a finite positive number",
        ));
    }

    let amount = request.amount;
    let amount_decimal = Decimal::from_f64_retain(amount)
        .ok_or_else(|| ApiError::bad_request("Amount must be a finite positive number"))?;
    let cap_mode = resolve_faucet_cap_mode(&state, &request.wallet).await;
    if cap_mode.enforces_limit() && amount_decimal > Decimal::from(FAUCET_LIFETIME_CAP_USDC) {
        return Err(ApiError::bad_request(faucet_cap_exceeded_message()));
    }

    tracing::info!(
        "Faucet: Crediting {} USDC to wallet {}",
        amount,
        request.wallet
    );

    let deposit_permit = reserve_deposit_handoff(&state.deposit_sender).await?;
    let now_ts_ms = chrono::Utc::now().timestamp_millis();
    let sequence = do_persist_faucet_credit(
        state.db.as_ref(),
        &request.wallet,
        amount_decimal,
        now_ts_ms,
        cap_mode,
    )
    .await?;

    let (applied_tx, applied_rx) = tokio::sync::oneshot::channel();
    deposit_permit.send(DepositRequest {
        wallet: request.wallet,
        amount: amount_decimal,
        timestamp_ms: now_ts_ms as u64,
        sequence: Some(sequence),
        source_event_hash: synthetic_faucet_source_event_hash(sequence),
        // Journal the deposit so it survives engine restart. Without a
        // request_id the DepositUpdate is applied to the in-memory ledger but
        // never journaled; on restart, journal replay does not restore it and
        // the engine cash diverges from the durable account_balances written
        // above, tripping the snapshot-cash restore guard.
        journal_request_id: uuid::Uuid::now_v7().to_string(),
        outbox_appends: Vec::new(),
        applied_tx: Some(applied_tx),
    });

    match applied_rx.await {
        Ok(Ok(())) => {}
        Ok(Err(e)) => panic!(
            "Faucet: DB commit succeeded for {} but engine deposit apply failed: {}",
            request.wallet, e
        ),
        Err(e) => panic!(
            "Faucet: DB commit succeeded for {} but engine deposit apply ack dropped: {}",
            request.wallet, e
        ),
    }
    let new_balance = state
        .balance_provider
        .get_balance(&request.wallet)
        .await
        .map_err(|error| {
            ApiError::internal_error(format!("failed to read engine balance ledger: {error}"))
        })?;

    tracing::info!(
        "Faucet: Credited {} USDC to wallet {} via engine balance ledger (new balance: {})",
        amount,
        request.wallet,
        new_balance
    );

    Ok(SonicJson(crate::models::ApiResponse::success(
        FaucetResponse {
            wallet: request.wallet,
            amount_credited: amount,
            new_balance: new_balance
                .to_f64()
                .expect("Faucet: new_balance Decimal not representable as f64"),
        },
    )))
}

// =============================================================================
// Set Spot Price Endpoint (Testnet Only)
// =============================================================================

#[cfg(feature = "test-endpoints")]
/// Request body for set_spot_price endpoint
#[derive(Debug, Deserialize, ToSchema)]
pub struct SetSpotPriceRequest {
    /// Underlying asset (e.g., "BTC", "ETH")
    pub underlying: String,
    /// Spot price in USD
    pub price: f64,
}

#[cfg(feature = "test-endpoints")]
/// Response for set_spot_price endpoint
#[derive(Debug, Serialize, ToSchema)]
pub struct SetSpotPriceResponse {
    /// Underlying asset
    pub underlying: String,
    /// New spot price
    pub price: f64,
}

#[cfg(feature = "test-endpoints")]
/// Request body for set_option_iv endpoint
#[derive(Debug, Deserialize, ToSchema)]
pub struct SetOptionIvRequest {
    /// Option symbol (e.g., "BTC-20260331-100000-C")
    pub symbol: String,
    /// Implied volatility as decimal (e.g., 0.8 for 80%)
    pub implied_vol: f64,
}

#[cfg(feature = "test-endpoints")]
/// Response for set_option_iv endpoint
#[derive(Debug, Serialize, ToSchema)]
pub struct SetOptionIvResponse {
    /// Option symbol
    pub symbol: String,
    /// Applied implied volatility
    pub implied_vol: f64,
}

#[cfg(feature = "test-endpoints")]
/// Set spot price for an underlying asset (TESTNET ONLY).
///
/// This endpoint is only available when `modes.enable_test_endpoints=true`.
/// It allows tests to set spot prices for margin calculations.
#[utoipa::path(
    post,
    path = "/test/spot-price",
    request_body = SetSpotPriceRequest,
    responses(
        (status = 200, description = "Spot price set successfully", body = ApiResponse<SetSpotPriceResponse>),
        (status = 400, description = "Invalid request"),
        (status = 403, description = "Not enabled (production mode)"),
        (status = 404, description = "Oracle not configured for underlying"),
        (status = 500, description = "Internal server error")
    ),
    tag = "testnet"
)]
pub async fn set_spot_price(
    State(state): State<AppState>,
    SonicJson(request): SonicJson<SetSpotPriceRequest>,
) -> Result<SonicJson<crate::models::ApiResponse<SetSpotPriceResponse>>, ApiError> {
    if !request.price.is_finite() || request.price <= 0.0 {
        tracing::error!(
            "set_spot_price request with invalid price: {}",
            request.price
        );
        return Err(ApiError::bad_request(
            "Price must be a finite positive number",
        ));
    }

    tracing::info!(
        "Setting spot price for {} to ${:.2}",
        request.underlying,
        request.price
    );

    // Update spot price in greeks cache via oracle
    let success = state
        .greeks_cache
        .set_spot_price_for_testing(&request.underlying, request.price)
        .await;

    if !success {
        tracing::error!(
            "Failed to set spot price for {}: oracle not configured",
            request.underlying
        );
        return Err(ApiError::not_found(format!(
            "Oracle not configured for underlying: {}",
            request.underlying
        )));
    }

    Ok(SonicJson(crate::models::ApiResponse::success(
        SetSpotPriceResponse {
            underlying: request.underlying,
            price: request.price,
        },
    )))
}

#[cfg(feature = "test-endpoints")]
/// Set theoretical option IV for repricing (TESTNET ONLY).
///
/// This endpoint is only available when `modes.enable_test_endpoints=true`.
#[utoipa::path(
    post,
    path = "/test/option-iv",
    request_body = SetOptionIvRequest,
    responses(
        (status = 200, description = "Option IV set successfully", body = ApiResponse<SetOptionIvResponse>),
        (status = 400, description = "Invalid request"),
        (status = 403, description = "Not enabled (production mode)")
    ),
    tag = "testnet"
)]
pub async fn set_option_iv(
    State(state): State<AppState>,
    SonicJson(request): SonicJson<SetOptionIvRequest>,
) -> Result<SonicJson<crate::models::ApiResponse<SetOptionIvResponse>>, ApiError> {
    if request.implied_vol <= 0.0 || !request.implied_vol.is_finite() {
        return Err(ApiError::bad_request(
            "implied_vol must be a finite positive decimal value",
        ));
    }

    state
        .greeks_cache
        .set_theoretical_iv_for_testing(&request.symbol, request.implied_vol)
        .await;

    Ok(SonicJson(crate::models::ApiResponse::success(
        SetOptionIvResponse {
            symbol: request.symbol,
            implied_vol: request.implied_vol,
        },
    )))
}

// =============================================================================
// Expire Instrument Endpoint (Testnet Only)
// =============================================================================

#[cfg(feature = "test-endpoints")]
/// Request body for expire_instrument endpoint
#[derive(Debug, Deserialize, ToSchema)]
pub struct ExpireInstrumentRequest {
    /// Option symbol to expire (e.g., "BTC-20260331-100000-C")
    pub symbol: String,
}

#[cfg(feature = "test-endpoints")]
/// Response for expire_instrument endpoint
#[derive(Debug, Serialize, ToSchema)]
pub struct ExpireInstrumentResponse {
    /// Symbol that was expired
    pub symbol: String,
    /// Result status from the engine
    pub status: String,
    /// Reason if settlement is pending
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

#[cfg(feature = "test-endpoints")]
/// Expire an instrument and settle all positions (TESTNET ONLY).
///
/// This endpoint triggers expiry for a given symbol: it cancels all open orders,
/// settles positions at the current settlement price, and removes the orderbook.
/// Only available when `modes.enable_test_endpoints=true`.
#[utoipa::path(
    post,
    path = "/test/expire-instrument",
    request_body = ExpireInstrumentRequest,
    responses(
        (status = 200, description = "Instrument expired/pending settlement", body = ApiResponse<ExpireInstrumentResponse>),
        (status = 400, description = "Invalid symbol"),
        (status = 403, description = "Not enabled (production mode)"),
        (status = 500, description = "Engine communication failure")
    ),
    tag = "testnet"
)]
pub async fn expire_instrument(
    State(state): State<AppState>,
    SonicJson(request): SonicJson<ExpireInstrumentRequest>,
) -> Result<SonicJson<crate::models::ApiResponse<ExpireInstrumentResponse>>, ApiError> {
    // Parse symbol to extract market fields
    let parsed = ParsedOptionSymbol::from_symbol(&request.symbol)
        .map_err(|e| ApiError::bad_request(format!("Invalid symbol: {}", e)))?;

    tracing::info!("Expiring instrument {} (testnet)", request.symbol);

    let market = hypercall_types::Market {
        symbol: request.symbol.clone(),
        underlying: parsed.underlying,
        expiry: parsed.expiry,
        strike: parsed.strike,
        option_type: parsed.option_type,
    };

    let message = hypercall_types::MarketActionMessage {
        market,
        action: hypercall_types::MarketAction::ExpireMarket,
        timestamp: get_timestamp_millis(),
    };

    let (response_tx, mut response_rx) = tokio::sync::mpsc::channel(1);

    let market_request = MarketRequest {
        message,
        response_tx,
    };

    state
        .market_sender
        .send(market_request)
        .await
        .map_err(|_| ApiError::internal_error("Failed to send expire request to engine"))?;

    // Wait for response with timeout
    let response = tokio::time::timeout(std::time::Duration::from_secs(30), response_rx.recv())
        .await
        .map_err(|_| ApiError::internal_error("Timeout waiting for engine response"))?
        .ok_or_else(|| ApiError::internal_error("Engine dropped response channel"))?;

    let (status_str, reason) = match response.status {
        hypercall_types::MarketUpdateStatus::MarketExpired => ("SETTLED".to_string(), None),
        hypercall_types::MarketUpdateStatus::MarketPendingSettlement => {
            ("PENDING_SETTLEMENT".to_string(), response.reason)
        }
        other => ("UNEXPECTED".to_string(), Some(format!("{:?}", other))),
    };

    Ok(SonicJson(crate::models::ApiResponse::success(
        ExpireInstrumentResponse {
            symbol: request.symbol,
            status: status_str,
            reason,
        },
    )))
}

// =============================================================================
// Cancel All Orders Endpoint (Testnet Only)
// =============================================================================

/// Response for cancel_all_orders endpoint
#[derive(Debug, Serialize, ToSchema)]
pub struct CancelAllOrdersResponse {
    /// Total MM orders found to cancel
    pub total_mm_orders: usize,
    /// Message indicating background processing started
    pub message: String,
}

#[cfg(test)]
mod faucet_tests {
    use super::*;

    #[cfg(feature = "faucet")]
    #[tokio::test]
    async fn test_reserve_deposit_handoff_rejects_missing_sender() {
        let err = reserve_deposit_handoff(&None)
            .await
            .expect_err("missing engine deposit sender should fail before DB persistence");
        assert_eq!(err.status, StatusCode::SERVICE_UNAVAILABLE);
    }

    #[cfg(feature = "faucet")]
    #[tokio::test]
    async fn test_reserve_deposit_handoff_rejects_closed_sender() {
        let (deposit_tx, deposit_rx) = tokio::sync::mpsc::channel(1);
        drop(deposit_rx);

        let err = reserve_deposit_handoff(&Some(deposit_tx))
            .await
            .expect_err("closed engine deposit sender should fail before DB persistence");
        assert_eq!(err.status, StatusCode::SERVICE_UNAVAILABLE);
    }

    #[cfg(feature = "faucet")]
    #[tokio::test]
    async fn test_reserve_deposit_handoff_accepts_open_sender() {
        let (deposit_tx, _deposit_rx) = tokio::sync::mpsc::channel(1);

        reserve_deposit_handoff(&Some(deposit_tx))
            .await
            .expect("open engine deposit sender should reserve handoff capacity");
    }
}