hypercall/

backend_config.rs

use alloy::primitives::{Address, B256};
use anyhow::{bail, Context, Result};
use catalog_manager::{CatalogConfig, SecretPlaceholderMode};
pub use hypercall_config::{
    ApiRuntimeConfig, PricingConfig, DEFAULT_HYPERLIQUID_INFO_URL,
    DEFAULT_HYPERLIQUID_TESTNET_INFO_URL,
};
use hypercall_transaction_submitter::{TransactionSubmitterConfig, TransactionSubmitterMode};
use serde::Deserialize;
use std::path::{Path, PathBuf};
use std::str::FromStr;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SecretValidationMode {
    FullRuntime,
    Migrations,
    ConfigOnly,
    DatabaseOnly,
}

#[derive(Debug, Clone)]
pub struct BackendRuntime {
    pub config: BackendConfig,
    pub secrets: BackendSecrets,
}

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RsmEnvironmentConfig {
    #[default]
    Development,
    Staging,
    Testnet,
    Mainnet,
}

#[cfg(feature = "rsm-state")]
impl From<RsmEnvironmentConfig> for hypercall_db::ValidatorRsmEnvironment {
    fn from(value: RsmEnvironmentConfig) -> Self {
        match value {
            RsmEnvironmentConfig::Development => Self::Development,
            RsmEnvironmentConfig::Staging => Self::Staging,
            RsmEnvironmentConfig::Testnet => Self::Testnet,
            RsmEnvironmentConfig::Mainnet => Self::Mainnet,
        }
    }
}

impl BackendRuntime {
    pub fn load_from_path(path: &Path) -> Result<Self> {
        Self::load_from_path_with_secret_validation(path, SecretValidationMode::FullRuntime)
    }

    pub fn load_from_path_for_migrations(path: &Path) -> Result<Self> {
        Self::load_from_path_with_secret_validation(path, SecretValidationMode::Migrations)
    }

    pub fn load_from_path_for_config_only(path: &Path) -> Result<Self> {
        Self::load_from_path_with_secret_validation(path, SecretValidationMode::ConfigOnly)
    }

    pub fn load_from_path_for_database_only(path: &Path) -> Result<Self> {
        Self::load_from_path_with_secret_validation(path, SecretValidationMode::DatabaseOnly)
    }

    fn load_from_path_with_secret_validation(
        path: &Path,
        secret_validation: SecretValidationMode,
    ) -> Result<Self> {
        let contents = std::fs::read_to_string(path)
            .with_context(|| format!("Failed to read backend config {}", path.display()))?;
        Self::load_from_str_with_secret_validation(&contents, secret_validation)
            .with_context(|| format!("Failed to parse backend config {}", path.display()))
    }

    pub fn load_from_str(contents: &str) -> Result<Self> {
        Self::load_from_str_with_secret_validation(contents, SecretValidationMode::FullRuntime)
    }

    #[cfg(test)]
    fn load_from_str_for_migrations(contents: &str) -> Result<Self> {
        Self::load_from_str_with_secret_validation(contents, SecretValidationMode::Migrations)
    }

    #[cfg(test)]
    fn load_from_str_for_config_only(contents: &str) -> Result<Self> {
        Self::load_from_str_with_secret_validation(contents, SecretValidationMode::ConfigOnly)
    }

    #[cfg(test)]
    fn load_from_str_for_database_only(contents: &str) -> Result<Self> {
        Self::load_from_str_with_secret_validation(contents, SecretValidationMode::DatabaseOnly)
    }

    fn load_from_str_with_secret_validation(
        contents: &str,
        secret_validation: SecretValidationMode,
    ) -> Result<Self> {
        let config: BackendConfig = catalog_manager::with_secret_placeholder_mode(
            secret_placeholder_mode(secret_validation),
            || serde_yaml_ng::from_str(contents).context("Invalid backend YAML config"),
        )?;
        config.validate_for_mode(secret_validation)?;

        let secrets = BackendSecrets::from_env();
        secrets.validate_for_mode(&config, secret_validation)?;

        Ok(Self { config, secrets })
    }

    pub fn from_legacy_env() -> Result<Self> {
        Self::from_legacy_env_with_secret_validation(SecretValidationMode::FullRuntime)
    }

    pub fn from_legacy_env_for_migrations() -> Result<Self> {
        Self::from_legacy_env_with_secret_validation(SecretValidationMode::Migrations)
    }

    pub fn from_legacy_env_for_config_only() -> Result<Self> {
        Self::from_legacy_env_with_secret_validation(SecretValidationMode::ConfigOnly)
    }

    pub fn from_legacy_env_for_database_only() -> Result<Self> {
        Self::from_legacy_env_with_secret_validation(SecretValidationMode::DatabaseOnly)
    }

    fn from_legacy_env_with_secret_validation(
        secret_validation: SecretValidationMode,
    ) -> Result<Self> {
        let mut config = BackendConfig::default();
        apply_legacy_env_overrides(&mut config, should_load_legacy_catalog(secret_validation))?;
        config.validate_for_mode(secret_validation)?;

        let secrets = BackendSecrets::from_env();
        secrets.validate_for_mode(&config, secret_validation)?;

        Ok(Self { config, secrets })
    }

    pub fn apply_process_env(&self) {
        std::env::set_var(
            "TESTNET_MODE",
            if self.config.modes.testnet_mode {
                "1"
            } else {
                "0"
            },
        );
        std::env::set_var(
            "EXCHANGE_CONTRACT_ADDRESS",
            &self.config.contracts.exchange_contract_address,
        );
        std::env::set_var(
            "OPTION_REGISTRY_ADDRESS",
            &self.config.contracts.option_registry_address,
        );
        std::env::set_var(
            "OPTION_TOKEN_BEACON_PROXY_INIT_CODE_HASH",
            &self
                .config
                .contracts
                .option_token_beacon_proxy_init_code_hash,
        );
    }

    pub fn apply_portfolio_margin_pool_env_overrides(&mut self) -> Result<()> {
        apply_portfolio_margin_pool_env_overrides(&mut self.config)
    }
}

fn secret_placeholder_mode(secret_validation: SecretValidationMode) -> SecretPlaceholderMode {
    match secret_validation {
        SecretValidationMode::FullRuntime => SecretPlaceholderMode::ResolveRequired,
        SecretValidationMode::Migrations
        | SecretValidationMode::ConfigOnly
        | SecretValidationMode::DatabaseOnly => SecretPlaceholderMode::AllowUnresolved,
    }
}

fn should_load_legacy_catalog(secret_validation: SecretValidationMode) -> bool {
    matches!(secret_validation, SecretValidationMode::FullRuntime)
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct BackendConfig {
    pub environment: EnvironmentConfig,
    pub modes: ModesConfig,
    pub contracts: ContractsConfig,
    pub database: DatabaseConfig,
    pub api: ApiRuntimeConfig,
    pub pricing: PricingConfig,
    pub hydromancer: HydromancerRuntimeConfig,
    pub transaction_submitter: TransactionSubmitterConfig,
    pub rsm_signer: RsmSignerConfig,
    pub liquidation: LiquidationRuntimeConfig,
    pub onchain_deposits: OnchainDepositsRuntimeConfig,
    pub catalog_manager: CatalogManagerRuntimeConfig,
    pub catalog: CatalogConfig,
    pub engine: EngineRuntimeConfig,
    pub background_tasks: BackgroundTasksConfig,
    pub observability: ObservabilityRuntimeConfig,
}

impl Default for BackendConfig {
    fn default() -> Self {
        Self {
            environment: EnvironmentConfig::default(),
            modes: ModesConfig::default(),
            contracts: ContractsConfig::default(),
            database: DatabaseConfig::default(),
            api: ApiRuntimeConfig::default(),
            pricing: PricingConfig::default(),
            hydromancer: HydromancerRuntimeConfig::default(),
            transaction_submitter: TransactionSubmitterConfig::default(),
            rsm_signer: RsmSignerConfig::default(),
            liquidation: LiquidationRuntimeConfig::default(),
            onchain_deposits: OnchainDepositsRuntimeConfig::default(),
            catalog_manager: CatalogManagerRuntimeConfig::default(),
            catalog: default_catalog(),
            engine: EngineRuntimeConfig::default(),
            background_tasks: BackgroundTasksConfig::default(),
            observability: ObservabilityRuntimeConfig::default(),
        }
    }
}

impl BackendConfig {
    pub fn validate(&self) -> Result<()> {
        self.validate_for_mode(SecretValidationMode::FullRuntime)
    }

    fn validate_for_mode(&self, secret_validation: SecretValidationMode) -> Result<()> {
        if mode_requires_contract_validation(secret_validation) {
            self.contracts.validate()?;
        }
        if self.database.pool.diesel_max < 3 {
            bail!("database.pool.diesel_max must be >= 3 (sync needs >=1, async needs >=2)");
        }
        if self.database.pool.journal_max == 0 {
            bail!("database.pool.journal_max must be > 0");
        }
        if self.api.max_open_orders_default < 0 {
            bail!("api.max_open_orders_default must be >= 0");
        }
        if self.api.max_open_positions_default < 0 {
            bail!("api.max_open_positions_default must be >= 0");
        }
        if self.api.ws_heartbeat_interval_ms == 0 {
            bail!("api.ws_heartbeat_interval_ms must be > 0");
        }
        if self.api.ws_pong_timeout_ms < self.api.ws_heartbeat_interval_ms {
            bail!("api.ws_pong_timeout_ms must be >= api.ws_heartbeat_interval_ms");
        }
        if self.api.markets_snapshot_refresh_ms == 0 {
            bail!("api.markets_snapshot_refresh_ms must be > 0");
        }
        if self.pricing.candle_ws_poll_interval_ms == 0 {
            bail!("pricing.candle_ws_poll_interval_ms must be > 0");
        }
        if self.pricing.min_settlement_samples == 0 {
            bail!("pricing.min_settlement_samples must be > 0");
        }
        if self.pricing.hypercore_update_interval_secs == 0 {
            bail!("pricing.hypercore_update_interval_secs must be > 0");
        }
        if self.pricing.oracle_symbol.trim().is_empty() {
            bail!("pricing.oracle_symbol must not be empty");
        }
        if self.liquidation.enabled
            && !self.rsm_signer.is_configured()
            && self.transaction_submitter.mode != TransactionSubmitterMode::Direct
        {
            bail!("liquidation.enabled requires rsm_signer.aws_kms_key_id or transaction_submitter.mode=direct");
        }
        if self.onchain_deposits.poll_interval_ms == 0 {
            bail!("onchain_deposits.poll_interval_ms must be > 0");
        }
        if self.onchain_deposits.startup_lookback_blocks == 0 {
            bail!("onchain_deposits.startup_lookback_blocks must be > 0");
        }
        if self.onchain_deposits.max_blocks_per_poll == 0 {
            bail!("onchain_deposits.max_blocks_per_poll must be > 0");
        }
        if self.onchain_deposits.max_blocks_per_get_logs == 0 {
            bail!("onchain_deposits.max_blocks_per_get_logs must be > 0");
        }
        if self.liquidation.health_poll_interval_ms == 0 {
            bail!("liquidation.health_poll_interval_ms must be > 0");
        }
        if self.liquidation.partial_reprice_interval_ms == 0 {
            bail!("liquidation.partial_reprice_interval_ms must be > 0");
        }
        if self.liquidation.partial_bonus_max_bps < self.liquidation.partial_bonus_start_bps {
            bail!(
                "liquidation.partial_bonus_max_bps must be >= liquidation.partial_bonus_start_bps"
            );
        }
        if self.liquidation.partial_bonus_ramp_ms == 0 {
            bail!("liquidation.partial_bonus_ramp_ms must be > 0");
        }
        if self.liquidation.full_escalation_timeout_ms == 0 {
            bail!("liquidation.full_escalation_timeout_ms must be > 0");
        }
        if self.liquidation.chain_observer_poll_interval_ms == 0 {
            bail!("liquidation.chain_observer_poll_interval_ms must be > 0");
        }
        if self.liquidation.chain_observer_max_lag_blocks == 0 {
            bail!("liquidation.chain_observer_max_lag_blocks must be > 0");
        }
        if self.catalog_manager.interval_secs == 0 {
            bail!("catalog_manager.interval_secs must be > 0");
        }
        if self.engine.persistence.journal.batch_channel_capacity == 0 {
            bail!("engine.persistence.journal.batch_channel_capacity must be > 0");
        }
        if self.engine.persistence.journal.batch_size == 0 {
            bail!("engine.persistence.journal.batch_size must be > 0");
        }
        if self.engine.persistence.journal.flush_interval_ms == 0 {
            bail!("engine.persistence.journal.flush_interval_ms must be > 0");
        }
        if self.engine.persistence.outbox.poll_ms == 0 {
            bail!("engine.persistence.outbox.poll_ms must be > 0");
        }
        if self.engine.persistence.outbox.batch_size == 0 {
            bail!("engine.persistence.outbox.batch_size must be > 0");
        }
        if self.engine.snapshot_interval_secs == 0 {
            bail!("engine.snapshot_interval_secs must be > 0");
        }
        if self.engine.read_snapshot_interval_ms == 0
            && self.engine.persistence.journal.wal_path.is_some()
        {
            bail!(
                "engine.read_snapshot_interval_ms must be > 0 when engine.persistence.journal.wal_path is set"
            );
        }
        if self.background_tasks.bbo_snapshot.interval_secs == 0 {
            bail!("background_tasks.bbo_snapshot.interval_secs must be > 0");
        }
        if self.background_tasks.bbo_snapshot.retention_days <= 0 {
            bail!("background_tasks.bbo_snapshot.retention_days must be > 0");
        }
        if self.background_tasks.historical_pnl.max_periods <= 0 {
            bail!("background_tasks.historical_pnl.max_periods must be > 0");
        }
        if self.background_tasks.historical_pnl.capture_every_5m_ms <= 0
            || self.background_tasks.historical_pnl.capture_every_1h_ms <= 0
            || self.background_tasks.historical_pnl.capture_every_1d_ms <= 0
        {
            bail!("background_tasks.historical_pnl capture intervals must be > 0");
        }
        if !(0.0..=1.0).contains(&self.observability.tracing.sample_ratio) {
            bail!("observability.tracing.sample_ratio must be between 0.0 and 1.0");
        }
        self.catalog.validate().context("Invalid catalog config")?;
        Ok(())
    }
}

fn mode_requires_contract_validation(secret_validation: SecretValidationMode) -> bool {
    matches!(secret_validation, SecretValidationMode::FullRuntime)
}

#[derive(Debug, Clone, Default)]
pub struct BackendSecrets {
    pub database_url: Option<String>,
    pub direct_url: Option<String>,
    pub redis_url: Option<String>,
    pub hydromancer_api_key: Option<String>,
    pub hydromancer_ws_api_key: Option<String>,
    pub transaction_submitter_private_key: Option<String>,
    pub admin_api_key: Option<String>,
}

impl BackendSecrets {
    pub fn from_env() -> Self {
        Self {
            database_url: std::env::var("DATABASE_URL").ok(),
            direct_url: std::env::var("DIRECT_URL").ok(),
            redis_url: std::env::var("REDIS_URL").ok(),
            hydromancer_api_key: std::env::var("HYDROMANCER_API_KEY").ok(),
            // Separate WS key for Hydromancer fill/position feeds.
            // The main HYDROMANCER_API_KEY is for mainnet oracle price feeds and must stay mainnet.
            // Set HYDROMANCER_WS_API_KEY for testnet fill/position WS feeds.
            hydromancer_ws_api_key: std::env::var("HYDROMANCER_WS_API_KEY").ok(),
            transaction_submitter_private_key: std::env::var("TRANSACTION_SUBMITTER_PRIVATE_KEY")
                .ok(),
            admin_api_key: std::env::var("ADMIN_API_KEY").ok(),
        }
    }

    pub fn validate(&self, config: &BackendConfig) -> Result<()> {
        self.validate_for_mode(config, SecretValidationMode::FullRuntime)
    }

    fn validate_for_mode(
        &self,
        config: &BackendConfig,
        secret_validation: SecretValidationMode,
    ) -> Result<()> {
        match secret_validation {
            SecretValidationMode::ConfigOnly => {}
            SecretValidationMode::Migrations => {
                self.direct_or_database_url()?;
            }
            SecretValidationMode::DatabaseOnly => {
                self.require_database_url()?;
            }
            SecretValidationMode::FullRuntime => {
                // Monitoring endpoints expose full account, position, and engine
                // state, so every deployed environment must have an admin key.
                // Only local development may run without one.
                if config.environment.name != "development" {
                    self.require_admin_api_key()?;
                }
                if config.hydromancer.enabled {
                    self.require_hydromancer_api_key()?;
                }
                match config.transaction_submitter.mode {
                    TransactionSubmitterMode::Mock => {}
                    TransactionSubmitterMode::Direct => {
                        self.require_transaction_submitter_private_key()?;
                    }
                    TransactionSubmitterMode::AwsKms => {
                        if config
                            .transaction_submitter
                            .aws_kms_key_id
                            .trim()
                            .is_empty()
                        {
                            bail!("transaction_submitter.mode=aws_kms requires transaction_submitter.aws_kms_key_id");
                        }
                        #[cfg(not(feature = "aws"))]
                        bail!(
                            "transaction_submitter.mode=aws_kms requires building hypercall with the aws feature"
                        );
                    }
                }
                if (config.liquidation.enabled
                    || config.rsm_signer.is_configured()
                    || config.rsm_signer.provider == RsmSignerProvider::AwsKms)
                    && !uses_local_rsm_signer(config)
                {
                    match config.rsm_signer.provider {
                        RsmSignerProvider::Local => {
                            self.require_transaction_submitter_private_key()?;
                        }
                        RsmSignerProvider::AwsKms => {
                            if config.rsm_signer.aws_kms_key_id.trim().is_empty() {
                                bail!("rsm_signer.provider=aws_kms requires rsm_signer.aws_kms_key_id");
                            }
                            #[cfg(not(feature = "aws"))]
                            bail!(
                                "rsm_signer.provider=aws_kms requires building hypercall with the aws feature"
                            );
                        }
                    }
                }
                if config.liquidation.enabled
                    && config.transaction_submitter.mode == TransactionSubmitterMode::Mock
                {
                    bail!("liquidation.enabled requires a non-mock transaction_submitter.mode");
                }
            }
        }
        Ok(())
    }

    pub fn require_database_url(&self) -> Result<&str> {
        self.database_url
            .as_deref()
            .context("DATABASE_URL must be set in the environment")
    }

    pub fn direct_or_database_url(&self) -> Result<&str> {
        self.direct_url
            .as_deref()
            .or(self.database_url.as_deref())
            .context("DIRECT_URL or DATABASE_URL must be set in the environment")
    }

    pub fn require_hydromancer_api_key(&self) -> Result<&str> {
        self.hydromancer_api_key
            .as_deref()
            .context("HYDROMANCER_API_KEY must be set in the environment")
    }

    pub fn require_transaction_submitter_private_key(&self) -> Result<&str> {
        self.transaction_submitter_private_key
            .as_deref()
            .context("TRANSACTION_SUBMITTER_PRIVATE_KEY must be set in the environment")
    }

    pub fn require_admin_api_key(&self) -> Result<&str> {
        let key = self
            .admin_api_key
            .as_deref()
            .context("ADMIN_API_KEY must be set outside the development environment")?;
        if key.trim().is_empty() {
            bail!("ADMIN_API_KEY must not be empty outside the development environment");
        }
        Ok(key)
    }

    pub fn transaction_submitter_secrets(
        &self,
    ) -> hypercall_transaction_submitter::TransactionSubmitterSecrets {
        hypercall_transaction_submitter::TransactionSubmitterSecrets {
            transaction_submitter_private_key: self.transaction_submitter_private_key.clone(),
        }
    }
}

fn uses_local_rsm_signer(config: &BackendConfig) -> bool {
    config.rsm_signer.provider == RsmSignerProvider::Local
        && config.transaction_submitter.mode == TransactionSubmitterMode::Direct
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct EnvironmentConfig {
    pub name: String,
}

impl Default for EnvironmentConfig {
    fn default() -> Self {
        Self {
            name: "development".to_string(),
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct ModesConfig {
    pub testnet_mode: bool,
    pub enable_test_endpoints: bool,
    pub skip_external_oracle: bool,
}

impl Default for ModesConfig {
    fn default() -> Self {
        Self {
            testnet_mode: false,
            enable_test_endpoints: false,
            skip_external_oracle: true,
        }
    }
}

#[derive(Debug, Clone, Deserialize, Default)]
#[serde(default, deny_unknown_fields)]
pub struct ContractsConfig {
    pub exchange_contract_address: String,
    pub core_deposit_wallet_address: String,
    pub usdc_address: String,
    pub option_registry_address: String,
    pub option_token_beacon_proxy_init_code_hash: String,
}

impl ContractsConfig {
    fn validate(&self) -> Result<()> {
        let exchange_contract_address = self.exchange_contract_address.trim();
        if exchange_contract_address.is_empty() {
            bail!("contracts.exchange_contract_address must be set");
        }
        Address::from_str(exchange_contract_address).map_err(|err| {
            anyhow::anyhow!(
                "contracts.exchange_contract_address must be a valid EVM address: {}",
                err
            )
        })?;

        let core_deposit_wallet_address = self.core_deposit_wallet_address.trim();
        if core_deposit_wallet_address.is_empty() {
            bail!("contracts.core_deposit_wallet_address must be set");
        }
        Address::from_str(core_deposit_wallet_address).map_err(|err| {
            anyhow::anyhow!(
                "contracts.core_deposit_wallet_address must be a valid EVM address: {}",
                err
            )
        })?;

        let usdc_address = self.usdc_address.trim();
        if usdc_address.is_empty() {
            bail!("contracts.usdc_address must be set");
        }
        Address::from_str(usdc_address).map_err(|err| {
            anyhow::anyhow!(
                "contracts.usdc_address must be a valid EVM address: {}",
                err
            )
        })?;

        let option_registry_address = self.option_registry_address.trim();
        if option_registry_address.is_empty() {
            bail!("contracts.option_registry_address must be set");
        }

        let option_token_beacon_proxy_init_code_hash =
            self.option_token_beacon_proxy_init_code_hash.trim();
        if option_token_beacon_proxy_init_code_hash.is_empty() {
            bail!("contracts.option_token_beacon_proxy_init_code_hash must be set");
        }

        self.option_token_deployment()?;
        Ok(())
    }

    fn option_token_deployment(&self) -> Result<hypercall_types::OptionTokenDeployment> {
        let option_registry =
            Address::from_str(self.option_registry_address.trim()).map_err(|err| {
                anyhow::anyhow!(
                    "contracts.option_registry_address must be a valid EVM address: {}",
                    err
                )
            })?;
        let beacon_proxy_init_code_hash = B256::from_str(
            self.option_token_beacon_proxy_init_code_hash.trim(),
        )
        .map_err(|err| {
            anyhow::anyhow!(
                "contracts.option_token_beacon_proxy_init_code_hash must be a valid B256 hex string: {}",
                err
            )
        })?;

        Ok(hypercall_types::OptionTokenDeployment::new(
            option_registry,
            beacon_proxy_init_code_hash,
        ))
    }
}

#[derive(Debug, Clone, Deserialize, Default)]
#[serde(default, deny_unknown_fields)]
pub struct DatabaseConfig {
    pub pool: DatabasePoolConfig,
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct DatabasePoolConfig {
    pub diesel_max: u32,
    pub journal_max: u32,
}

impl Default for DatabasePoolConfig {
    fn default() -> Self {
        Self {
            diesel_max: 3,
            journal_max: 2,
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct HydromancerRuntimeConfig {
    pub enabled: bool,
    /// REST endpoint for pricing oracle (mainnet in staging).
    pub api_url: String,
    /// WebSocket endpoint for fill/position feeds (testnet in staging).
    pub ws_url: Option<String>,
    /// API key for WS feed. Falls back to HYDROMANCER_WS_API_KEY / HYDROMANCER_API_KEY env.
    pub ws_api_key: Option<String>,
}

impl Default for HydromancerRuntimeConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            api_url: "https://api.hydromancer.xyz/info".to_string(),
            ws_url: None,
            ws_api_key: None,
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct RsmSignerConfig {
    pub provider: RsmSignerProvider,
    pub aws_kms_key_id: String,
}

#[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum RsmSignerProvider {
    Local,
    AwsKms,
}

impl FromStr for RsmSignerProvider {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value.trim().to_ascii_lowercase().as_str() {
            "local" | "direct" => Ok(Self::Local),
            "aws_kms" => Ok(Self::AwsKms),
            other => Err(format!("expected one of: local, aws_kms; got {}", other)),
        }
    }
}

impl Default for RsmSignerConfig {
    fn default() -> Self {
        Self {
            provider: RsmSignerProvider::Local,
            aws_kms_key_id: String::new(),
        }
    }
}

impl RsmSignerConfig {
    pub fn is_configured(&self) -> bool {
        !self.aws_kms_key_id.trim().is_empty()
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct LiquidationRuntimeConfig {
    pub enabled: bool,
    pub health_poll_interval_ms: u64,
    pub partial_target_buffer_bps: u32,
    pub partial_reprice_interval_ms: u64,
    pub partial_bonus_start_bps: u32,
    pub partial_bonus_max_bps: u32,
    pub partial_bonus_ramp_ms: u64,
    pub min_shortfall_threshold: rust_decimal::Decimal,
    pub full_escalation_timeout_ms: u64,
    pub full_target_buffer_bps: u32,
    pub chain_observer_poll_interval_ms: u64,
    pub chain_observer_max_lag_blocks: u64,
}

impl Default for LiquidationRuntimeConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            health_poll_interval_ms: 5_000,
            partial_target_buffer_bps: 500,
            partial_reprice_interval_ms: 5_000,
            partial_bonus_start_bps: 50,
            partial_bonus_max_bps: 1_000,
            partial_bonus_ramp_ms: 300_000,
            min_shortfall_threshold: rust_decimal::Decimal::ZERO,
            full_escalation_timeout_ms: 60_000,
            full_target_buffer_bps: 500,
            chain_observer_poll_interval_ms: 2_000,
            chain_observer_max_lag_blocks: 32,
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct OnchainDepositsRuntimeConfig {
    pub poll_interval_ms: u64,
    pub startup_lookback_blocks: u64,
    pub max_blocks_per_poll: u64,
    pub max_blocks_per_get_logs: u64,
    pub confirmation_blocks: u64,
    pub pm_liquidity_settlement_grace_ms: i64,
    /// Hydromancer WebSocket URL for live ledger event streaming.
    /// When set, the cash ledger observer uses WS instead of HTTP polling.
    pub ws_url: Option<String>,
}

impl Default for OnchainDepositsRuntimeConfig {
    fn default() -> Self {
        Self {
            poll_interval_ms: 2_000,
            startup_lookback_blocks: 32,
            max_blocks_per_poll: 1_000,
            max_blocks_per_get_logs: 500,
            confirmation_blocks: 2,
            pm_liquidity_settlement_grace_ms: 0,
            ws_url: None,
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct CatalogManagerRuntimeConfig {
    pub enabled: bool,
    pub interval_secs: u64,
}

impl Default for CatalogManagerRuntimeConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            interval_secs: 3600,
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct EngineRuntimeConfig {
    pub persistence: EnginePersistenceConfig,
    pub snapshot_interval_secs: u64,
    pub post_startup_reconcile_delay_secs: u64,
    pub read_snapshot_interval_ms: u64,
    pub allow_standard_margin_shorts: bool,
    pub portfolio_margin_mode_allowlist: Vec<String>,
    pub portfolio_margin_pool_enabled: bool,
    pub portfolio_margin_settlement_allowlist: Vec<String>,
}

impl Default for EngineRuntimeConfig {
    fn default() -> Self {
        Self {
            persistence: EnginePersistenceConfig::default(),
            snapshot_interval_secs: 60,
            post_startup_reconcile_delay_secs: 5,
            read_snapshot_interval_ms: 500,
            allow_standard_margin_shorts: false,
            portfolio_margin_mode_allowlist: Vec::new(),
            portfolio_margin_pool_enabled: false,
            portfolio_margin_settlement_allowlist: Vec::new(),
        }
    }
}

#[derive(Debug, Clone, Deserialize, Default)]
#[serde(default, deny_unknown_fields)]
pub struct EnginePersistenceConfig {
    pub journal: JournalRuntimeConfig,
    pub outbox: OutboxRuntimeConfig,
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct JournalRuntimeConfig {
    pub event_persistence: String,
    pub critical_event_types: Vec<String>,
    pub wal_path: Option<PathBuf>,
    pub batch_channel_capacity: usize,
    pub batch_size: usize,
    pub flush_interval_ms: u64,
    pub digests_enabled: bool,
    pub rsm_environment: RsmEnvironmentConfig,
    #[cfg(feature = "rsm-state")]
    pub rsm_state: RsmStateRuntimeConfig,
}

impl Default for JournalRuntimeConfig {
    fn default() -> Self {
        Self {
            event_persistence: "full".to_string(),
            critical_event_types: vec!["L2Update".to_string()],
            wal_path: None,
            batch_channel_capacity: 1024,
            batch_size: 100,
            flush_interval_ms: 10,
            digests_enabled: true,
            rsm_environment: RsmEnvironmentConfig::Development,
            #[cfg(feature = "rsm-state")]
            rsm_state: RsmStateRuntimeConfig::default(),
        }
    }
}

#[cfg(feature = "rsm-state")]
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct RsmStateRuntimeConfig {
    pub state_store_path: PathBuf,
    pub prune_window_versions: u64,
    pub pruning_enabled: bool,
}

#[cfg(feature = "rsm-state")]
impl Default for RsmStateRuntimeConfig {
    fn default() -> Self {
        Self {
            state_store_path: PathBuf::from("target/validator-rsm-state"),
            prune_window_versions: 10_000,
            pruning_enabled: false,
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct OutboxRuntimeConfig {
    pub poll_ms: u64,
    pub batch_size: i64,
    pub max_drain_iterations: usize,
    pub drain_timeout_secs: u64,
    pub skip_drain: bool,
}

impl Default for OutboxRuntimeConfig {
    fn default() -> Self {
        Self {
            poll_ms: 10,
            batch_size: 500,
            max_drain_iterations: 0,
            drain_timeout_secs: 30,
            skip_drain: false,
        }
    }
}

#[derive(Debug, Clone, Deserialize, Default)]
#[serde(default, deny_unknown_fields)]
pub struct BackgroundTasksConfig {
    pub historical_pnl: HistoricalPnlRuntimeConfig,
    pub bbo_snapshot: BboSnapshotRuntimeConfig,
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct HistoricalPnlRuntimeConfig {
    pub max_periods: i64,
    pub capture_every_5m_ms: i64,
    pub capture_every_1h_ms: i64,
    pub capture_every_1d_ms: i64,
}

impl Default for HistoricalPnlRuntimeConfig {
    fn default() -> Self {
        Self {
            max_periods: 100,
            capture_every_5m_ms: hypercall_types::HISTORICAL_PNL_INTERVAL_5M_MS,
            capture_every_1h_ms: hypercall_types::HISTORICAL_PNL_INTERVAL_1H_MS,
            capture_every_1d_ms: hypercall_types::HISTORICAL_PNL_INTERVAL_1D_MS,
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct BboSnapshotRuntimeConfig {
    pub interval_secs: u64,
    pub retention_days: i64,
}

impl Default for BboSnapshotRuntimeConfig {
    fn default() -> Self {
        Self {
            interval_secs: 300,
            retention_days: 7,
        }
    }
}

#[derive(Debug, Clone, Deserialize, Default)]
#[serde(default, deny_unknown_fields)]
pub struct ObservabilityRuntimeConfig {
    pub tracing: TracingRuntimeConfig,
    pub pyroscope: PyroscopeRuntimeConfig,
    pub metrics: MetricsRuntimeConfig,
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct TracingRuntimeConfig {
    pub enabled: bool,
    pub otlp_endpoint: String,
    pub service_name: String,
    pub sample_ratio: f64,
}

impl Default for TracingRuntimeConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            otlp_endpoint: "http://localhost:4317".to_string(),
            service_name: "hypercall".to_string(),
            sample_ratio: 1.0,
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct PyroscopeRuntimeConfig {
    pub enabled: bool,
    pub server_address: Option<String>,
    pub application_name: String,
}

impl Default for PyroscopeRuntimeConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            server_address: None,
            application_name: "hypercall".to_string(),
        }
    }
}

#[derive(Debug, Clone, Deserialize, Default)]
#[serde(default, deny_unknown_fields)]
pub struct MetricsRuntimeConfig {
    pub skip_db_queries: bool,
}

fn default_catalog() -> CatalogConfig {
    serde_yaml_ng::from_str(include_str!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../market_catalog.yaml"
    )))
    .expect("bundled market catalog must deserialize")
}

fn legacy_catalog_path(testnet_mode: bool) -> String {
    env_string("CATALOG_MANAGER_CATALOG_PATH").unwrap_or_else(|| {
        if testnet_mode {
            "./market_catalog_dev.yaml".to_string()
        } else {
            "./market_catalog.yaml".to_string()
        }
    })
}

fn load_legacy_catalog_config(testnet_mode: bool) -> Result<CatalogConfig> {
    let catalog_path = legacy_catalog_path(testnet_mode);
    crate::catalog_manager::load_catalog_config(&catalog_path)
        .with_context(|| format!("Failed to load catalog config from {}", catalog_path))
}

fn apply_legacy_env_overrides(config: &mut BackendConfig, load_catalog: bool) -> Result<()> {
    config.environment.name =
        env_string("ENVIRONMENT").unwrap_or_else(|| config.environment.name.clone());

    override_env_bool("TESTNET_MODE", &mut config.modes.testnet_mode)?;
    override_env_bool(
        "ENABLE_TEST_ENDPOINTS",
        &mut config.modes.enable_test_endpoints,
    )?;
    override_env_bool(
        "SKIP_EXTERNAL_ORACLE",
        &mut config.modes.skip_external_oracle,
    )?;
    apply_legacy_testnet_pricing_defaults(config);
    override_env_string(
        "EXCHANGE_CONTRACT_ADDRESS",
        &mut config.contracts.exchange_contract_address,
    );
    override_env_string(
        "CORE_DEPOSIT_WALLET_ADDRESS",
        &mut config.contracts.core_deposit_wallet_address,
    );
    override_env_string("USDC_ADDRESS", &mut config.contracts.usdc_address);
    override_env_string(
        "OPTION_REGISTRY_ADDRESS",
        &mut config.contracts.option_registry_address,
    );
    override_env_string(
        "OPTION_TOKEN_BEACON_PROXY_INIT_CODE_HASH",
        &mut config.contracts.option_token_beacon_proxy_init_code_hash,
    );

    override_env_parse("DB_POOL_MAX_DIESEL", &mut config.database.pool.diesel_max)?;
    override_env_parse("DB_POOL_MAX_JOURNAL", &mut config.database.pool.journal_max)?;

    override_env_parse(
        "MAX_OPEN_ORDERS_DEFAULT",
        &mut config.api.max_open_orders_default,
    )?;
    override_env_parse(
        "MAX_OPEN_POSITIONS_DEFAULT",
        &mut config.api.max_open_positions_default,
    )?;
    override_env_bool("TRADING_HALTED", &mut config.api.global_trading_halted)?;
    override_env_csv("HALTED_MARKETS", &mut config.api.halted_markets);
    override_env_option_string(
        "TRADE_EXPLORER_URL_TEMPLATE",
        &mut config.api.trade_explorer_url_template,
    );
    override_env_parse(
        "HT_WS_HEARTBEAT_INTERVAL_MS",
        &mut config.api.ws_heartbeat_interval_ms,
    )?;
    override_env_parse("HT_WS_PONG_TIMEOUT_MS", &mut config.api.ws_pong_timeout_ms)?;
    override_env_parse(
        "MARKETS_SNAPSHOT_REFRESH_MS",
        &mut config.api.markets_snapshot_refresh_ms,
    )?;
    override_env_bool(
        "HT_REQUIRE_RISK_VOL_READINESS",
        &mut config.api.require_risk_vol_readiness,
    )?;

    override_env_string(
        "HYPERLIQUID_INFO_URL",
        &mut config.pricing.hyperliquid_info_url,
    );
    override_env_string("HYPERLIQUID_WS_URL", &mut config.pricing.hyperliquid_ws_url);
    override_env_parse(
        "CANDLE_WS_POLL_INTERVAL_MS",
        &mut config.pricing.candle_ws_poll_interval_ms,
    )?;
    override_env_parse(
        "MIN_SETTLEMENT_SAMPLES",
        &mut config.pricing.min_settlement_samples,
    )?;
    override_env_string("HYPERCORE_INFO_URL", &mut config.pricing.hypercore_info_url);
    override_env_parse(
        "HYPERCORE_UPDATE_INTERVAL_SECS",
        &mut config.pricing.hypercore_update_interval_secs,
    )?;
    override_env_string("ORACLE_SYMBOL", &mut config.pricing.oracle_symbol);

    override_env_bool("HYDROMANCER_ENABLED", &mut config.hydromancer.enabled)?;
    override_env_string("HYDROMANCER_API_URL", &mut config.hydromancer.api_url);
    if let Ok(val) = std::env::var("HYDROMANCER_WS_URL") {
        if !val.trim().is_empty() {
            config.hydromancer.ws_url = Some(val);
        }
    }

    config.transaction_submitter.mode =
        transaction_submitter_mode_from_env(config.transaction_submitter.mode)?;
    override_env_string(
        "TRANSACTION_SUBMITTER_AWS_KMS_KEY_ID",
        &mut config.transaction_submitter.aws_kms_key_id,
    );
    let rsm_signer_provider_from_env = env_string("RSM_SIGNER_PROVIDER");
    if let Some(provider) = &rsm_signer_provider_from_env {
        config.rsm_signer.provider = provider.parse().map_err(|error| {
            anyhow::anyhow!(
                "Invalid value for environment variable RSM_SIGNER_PROVIDER: {}",
                error
            )
        })?;
    }
    let rsm_signer_kms_key_from_env = env_string("RSM_SIGNER_AWS_KMS_KEY_ID");
    override_env_string(
        "RSM_SIGNER_AWS_KMS_KEY_ID",
        &mut config.rsm_signer.aws_kms_key_id,
    );
    if rsm_signer_provider_from_env.is_none() && rsm_signer_kms_key_from_env.is_some() {
        config.rsm_signer.provider = RsmSignerProvider::AwsKms;
    }
    override_env_string(
        "MAX_GAS_PRICE",
        &mut config.transaction_submitter.max_gas_price,
    );
    override_env_string("RPC_URL", &mut config.transaction_submitter.rpc_url);
    override_env_bool("LIQUIDATION_ENABLED", &mut config.liquidation.enabled)?;
    override_env_parse(
        "LIQUIDATION_HEALTH_POLL_INTERVAL_MS",
        &mut config.liquidation.health_poll_interval_ms,
    )?;
    override_env_parse(
        "LIQUIDATION_PARTIAL_TARGET_BUFFER_BPS",
        &mut config.liquidation.partial_target_buffer_bps,
    )?;
    override_env_parse(
        "LIQUIDATION_PARTIAL_REPRICE_INTERVAL_MS",
        &mut config.liquidation.partial_reprice_interval_ms,
    )?;
    override_env_parse(
        "LIQUIDATION_PARTIAL_BONUS_START_BPS",
        &mut config.liquidation.partial_bonus_start_bps,
    )?;
    override_env_parse(
        "LIQUIDATION_PARTIAL_BONUS_MAX_BPS",
        &mut config.liquidation.partial_bonus_max_bps,
    )?;
    override_env_parse(
        "LIQUIDATION_PARTIAL_BONUS_RAMP_MS",
        &mut config.liquidation.partial_bonus_ramp_ms,
    )?;
    override_env_parse(
        "LIQUIDATION_MIN_SHORTFALL_THRESHOLD",
        &mut config.liquidation.min_shortfall_threshold,
    )?;
    override_env_parse(
        "LIQUIDATION_FULL_ESCALATION_TIMEOUT_MS",
        &mut config.liquidation.full_escalation_timeout_ms,
    )?;
    override_env_parse(
        "LIQUIDATION_FULL_TARGET_BUFFER_BPS",
        &mut config.liquidation.full_target_buffer_bps,
    )?;
    override_env_parse(
        "LIQUIDATION_CHAIN_OBSERVER_POLL_INTERVAL_MS",
        &mut config.liquidation.chain_observer_poll_interval_ms,
    )?;
    override_env_parse(
        "LIQUIDATION_CHAIN_OBSERVER_MAX_LAG_BLOCKS",
        &mut config.liquidation.chain_observer_max_lag_blocks,
    )?;
    override_env_parse(
        "ONCHAIN_DEPOSITS_POLL_INTERVAL_MS",
        &mut config.onchain_deposits.poll_interval_ms,
    )?;
    override_env_parse(
        "ONCHAIN_DEPOSITS_STARTUP_LOOKBACK_BLOCKS",
        &mut config.onchain_deposits.startup_lookback_blocks,
    )?;
    override_env_parse(
        "ONCHAIN_DEPOSITS_MAX_BLOCKS_PER_POLL",
        &mut config.onchain_deposits.max_blocks_per_poll,
    )?;
    override_env_parse(
        "ONCHAIN_DEPOSITS_MAX_BLOCKS_PER_GET_LOGS",
        &mut config.onchain_deposits.max_blocks_per_get_logs,
    )?;
    override_env_parse(
        "ONCHAIN_DEPOSITS_CONFIRMATION_BLOCKS",
        &mut config.onchain_deposits.confirmation_blocks,
    )?;
    override_env_parse(
        "ONCHAIN_DEPOSITS_PM_LIQUIDITY_SETTLEMENT_GRACE_MS",
        &mut config.onchain_deposits.pm_liquidity_settlement_grace_ms,
    )?;
    override_env_option_string(
        "ONCHAIN_DEPOSITS_WS_URL",
        &mut config.onchain_deposits.ws_url,
    );

    override_env_bool(
        "CATALOG_MANAGER_ENABLED",
        &mut config.catalog_manager.enabled,
    )?;
    override_env_parse(
        "CATALOG_MANAGER_INTERVAL_SECS",
        &mut config.catalog_manager.interval_secs,
    )?;
    if load_catalog {
        config.catalog = load_legacy_catalog_config(config.modes.testnet_mode)?;
    }

    override_env_string(
        "ENGINE_JOURNAL_EVENT_PERSISTENCE",
        &mut config.engine.persistence.journal.event_persistence,
    );
    override_env_csv(
        "ENGINE_JOURNAL_CRITICAL_EVENT_TYPES",
        &mut config.engine.persistence.journal.critical_event_types,
    );
    override_env_option_path(
        "ENGINE_JOURNAL_WAL_PATH",
        &mut config.engine.persistence.journal.wal_path,
    );
    override_env_parse(
        "ENGINE_JOURNAL_BATCH_CHANNEL_CAPACITY",
        &mut config.engine.persistence.journal.batch_channel_capacity,
    )?;
    override_env_parse(
        "ENGINE_JOURNAL_BATCH_SIZE",
        &mut config.engine.persistence.journal.batch_size,
    )?;
    override_env_parse(
        "ENGINE_JOURNAL_BATCH_FLUSH_MS",
        &mut config.engine.persistence.journal.flush_interval_ms,
    )?;
    override_env_bool(
        "ENGINE_JOURNAL_DIGESTS_ENABLED",
        &mut config.engine.persistence.journal.digests_enabled,
    )?;
    override_env_parse(
        "ENGINE_OUTBOX_POLL_MS",
        &mut config.engine.persistence.outbox.poll_ms,
    )?;
    override_env_parse(
        "ENGINE_OUTBOX_BATCH_SIZE",
        &mut config.engine.persistence.outbox.batch_size,
    )?;
    override_env_parse(
        "ENGINE_OUTBOX_MAX_DRAIN_ITERATIONS",
        &mut config.engine.persistence.outbox.max_drain_iterations,
    )?;
    override_env_parse(
        "ENGINE_OUTBOX_DRAIN_TIMEOUT_SECS",
        &mut config.engine.persistence.outbox.drain_timeout_secs,
    )?;
    override_env_bool(
        "ENGINE_OUTBOX_SKIP_DRAIN",
        &mut config.engine.persistence.outbox.skip_drain,
    )?;
    override_env_parse(
        "ENGINE_POST_STARTUP_RECONCILE_DELAY_SECS",
        &mut config.engine.post_startup_reconcile_delay_secs,
    )?;
    override_env_parse(
        "ENGINE_READ_SNAPSHOT_INTERVAL_MS",
        &mut config.engine.read_snapshot_interval_ms,
    )?;
    apply_portfolio_margin_pool_env_overrides(config)?;
    override_env_parse(
        "ENGINE_SNAPSHOT_INTERVAL_SECS",
        &mut config.engine.snapshot_interval_secs,
    )?;

    override_env_parse(
        "HISTORICAL_PNL_MAX_PERIODS",
        &mut config.background_tasks.historical_pnl.max_periods,
    )?;
    override_env_parse(
        "HISTORICAL_PNL_CAPTURE_EVERY_5M_MS",
        &mut config.background_tasks.historical_pnl.capture_every_5m_ms,
    )?;
    override_env_parse(
        "HISTORICAL_PNL_CAPTURE_EVERY_1H_MS",
        &mut config.background_tasks.historical_pnl.capture_every_1h_ms,
    )?;
    override_env_parse(
        "HISTORICAL_PNL_CAPTURE_EVERY_1D_MS",
        &mut config.background_tasks.historical_pnl.capture_every_1d_ms,
    )?;
    override_env_parse(
        "BBO_SNAPSHOT_INTERVAL_SECS",
        &mut config.background_tasks.bbo_snapshot.interval_secs,
    )?;
    override_env_parse(
        "BBO_SNAPSHOT_RETENTION_DAYS",
        &mut config.background_tasks.bbo_snapshot.retention_days,
    )?;

    override_env_bool("TRACING_ENABLED", &mut config.observability.tracing.enabled)?;
    override_env_string(
        "OTEL_EXPORTER_OTLP_ENDPOINT",
        &mut config.observability.tracing.otlp_endpoint,
    );
    override_env_string(
        "OTEL_SERVICE_NAME",
        &mut config.observability.tracing.service_name,
    );
    override_env_parse(
        "TRACING_SAMPLE_RATIO",
        &mut config.observability.tracing.sample_ratio,
    )?;
    override_env_bool(
        "PYROSCOPE_ENABLED",
        &mut config.observability.pyroscope.enabled,
    )?;
    override_env_option_string(
        "PYROSCOPE_SERVER_ADDRESS",
        &mut config.observability.pyroscope.server_address,
    );
    override_env_string(
        "PYROSCOPE_APPLICATION_NAME",
        &mut config.observability.pyroscope.application_name,
    );
    override_env_bool(
        "METRICS_SKIP_DB_QUERIES",
        &mut config.observability.metrics.skip_db_queries,
    )?;

    Ok(())
}

fn apply_legacy_testnet_pricing_defaults(config: &mut BackendConfig) {
    if !config.modes.testnet_mode {
        return;
    }

    if env_string("HYPERLIQUID_INFO_URL").is_none() {
        config.pricing.hyperliquid_info_url = DEFAULT_HYPERLIQUID_TESTNET_INFO_URL.to_string();
    }
    if env_string("HYPERLIQUID_WS_URL").is_none() {
        config.pricing.hyperliquid_ws_url =
            hypercall_config::DEFAULT_HYPERLIQUID_TESTNET_WS_URL.to_string();
    }
    if env_string("HYPERCORE_INFO_URL").is_none() {
        config.pricing.hypercore_info_url = DEFAULT_HYPERLIQUID_TESTNET_INFO_URL.to_string();
    }
}

fn transaction_submitter_mode_from_env(
    default_mode: TransactionSubmitterMode,
) -> Result<TransactionSubmitterMode> {
    if let Some(mode) = env_string("TRANSACTION_SUBMITTER_MODE") {
        return mode.parse().map_err(|error| {
            anyhow::anyhow!(
                "Invalid value for environment variable TRANSACTION_SUBMITTER_MODE: {}",
                error
            )
        });
    }
    legacy_transaction_submitter_mode_from_env(default_mode)
}

fn legacy_transaction_submitter_mode_from_env(
    default_mode: TransactionSubmitterMode,
) -> Result<TransactionSubmitterMode> {
    if legacy_aws_kms_submitter_env_present() {
        return Ok(TransactionSubmitterMode::AwsKms);
    }
    if legacy_direct_submitter_env_present() {
        return Ok(TransactionSubmitterMode::Direct);
    }
    Ok(default_mode)
}

fn legacy_direct_submitter_env_present() -> bool {
    env_string("TRANSACTION_SUBMITTER_PRIVATE_KEY").is_some()
        && ["RPC_URL", "MAX_GAS_PRICE"]
            .iter()
            .all(|name| env_string(name).is_some())
}

fn legacy_aws_kms_submitter_env_present() -> bool {
    env_string("TRANSACTION_SUBMITTER_AWS_KMS_KEY_ID").is_some()
        && ["RPC_URL", "MAX_GAS_PRICE"]
            .iter()
            .all(|name| env_string(name).is_some())
}

fn env_string(name: &str) -> Option<String> {
    std::env::var(name)
        .ok()
        .map(|value| value.trim().to_string())
        .filter(|value| !value.is_empty())
}

fn override_env_string(name: &str, target: &mut String) {
    if let Some(value) = env_string(name) {
        *target = value;
    }
}

fn override_env_option_string(name: &str, target: &mut Option<String>) {
    if let Some(value) = env_string(name) {
        *target = Some(value);
    }
}

fn override_env_option_path(name: &str, target: &mut Option<PathBuf>) {
    if let Some(value) = env_string(name) {
        *target = Some(PathBuf::from(value));
    }
}

fn override_env_csv(name: &str, target: &mut Vec<String>) {
    if let Some(value) = env_string(name) {
        *target = value
            .split(',')
            .map(str::trim)
            .filter(|value| !value.is_empty())
            .map(ToOwned::to_owned)
            .collect();
    }
}

fn apply_portfolio_margin_pool_env_overrides(config: &mut BackendConfig) -> Result<()> {
    override_env_csv(
        "PORTFOLIO_MARGIN_MODE_ALLOWLIST",
        &mut config.engine.portfolio_margin_mode_allowlist,
    );
    override_env_bool(
        "PORTFOLIO_MARGIN_POOL_ENABLED",
        &mut config.engine.portfolio_margin_pool_enabled,
    )?;
    override_env_csv(
        "PORTFOLIO_MARGIN_SETTLEMENT_ALLOWLIST",
        &mut config.engine.portfolio_margin_settlement_allowlist,
    );
    Ok(())
}

fn override_env_bool(name: &str, target: &mut bool) -> Result<()> {
    if let Some(value) = env_string(name) {
        *target = parse_env_bool(name, &value)?;
    }
    Ok(())
}

fn override_env_parse<T>(name: &str, target: &mut T) -> Result<()>
where
    T: FromStr,
    T::Err: std::fmt::Display,
{
    if let Some(value) = env_string(name) {
        *target = value.parse::<T>().map_err(|err| {
            anyhow::anyhow!("Invalid value for environment variable {}: {}", name, err)
        })?;
    }
    Ok(())
}

fn parse_env_bool(name: &str, value: &str) -> Result<bool> {
    match value.to_ascii_lowercase().as_str() {
        "1" | "true" | "yes" | "on" => Ok(true),
        "0" | "false" | "no" | "off" => Ok(false),
        _ => bail!(
            "Invalid boolean value '{}' for environment variable {}",
            value,
            name
        ),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::test_contracts::{
        testnet_contracts_yaml_block, TESTNET_CORE_DEPOSIT_WALLET_ADDRESS,
        TESTNET_EXCHANGE_CONTRACT_ADDRESS, TESTNET_OPTION_REGISTRY_ADDRESS,
        TESTNET_OPTION_TOKEN_BEACON_PROXY_INIT_CODE_HASH, TESTNET_USDC_ADDRESS,
    };
    use rust_decimal::Decimal;
    use serial_test::serial;
    use std::ffi::OsString;

    struct EnvGuard {
        key: &'static str,
        original: Option<OsString>,
    }

    impl EnvGuard {
        fn set(key: &'static str, value: &str) -> Self {
            let original = std::env::var_os(key);
            unsafe {
                std::env::set_var(key, value);
            }
            Self { key, original }
        }

        fn remove(key: &'static str) -> Self {
            let original = std::env::var_os(key);
            unsafe {
                std::env::remove_var(key);
            }
            Self { key, original }
        }
    }

    impl Drop for EnvGuard {
        fn drop(&mut self) {
            match &self.original {
                Some(value) => unsafe { std::env::set_var(self.key, value) },
                None => unsafe { std::env::remove_var(self.key) },
            }
        }
    }

    fn repo_market_catalog_path() -> &'static str {
        concat!(env!("CARGO_MANIFEST_DIR"), "/../../market_catalog.yaml")
    }

    fn set_test_contract_env() -> (EnvGuard, EnvGuard, EnvGuard, EnvGuard, EnvGuard) {
        (
            EnvGuard::set(
                "EXCHANGE_CONTRACT_ADDRESS",
                TESTNET_EXCHANGE_CONTRACT_ADDRESS,
            ),
            EnvGuard::set(
                "CORE_DEPOSIT_WALLET_ADDRESS",
                TESTNET_CORE_DEPOSIT_WALLET_ADDRESS,
            ),
            EnvGuard::set("USDC_ADDRESS", TESTNET_USDC_ADDRESS),
            EnvGuard::set("OPTION_REGISTRY_ADDRESS", TESTNET_OPTION_REGISTRY_ADDRESS),
            EnvGuard::set(
                "OPTION_TOKEN_BEACON_PROXY_INIT_CODE_HASH",
                TESTNET_OPTION_TOKEN_BEACON_PROXY_INIT_CODE_HASH,
            ),
        )
    }

    fn sample_yaml() -> String {
        let contracts_yaml = testnet_contracts_yaml_block();
        format!(
            r#"
environment:
  name: development
modes:
  testnet_mode: true
  enable_test_endpoints: true
  skip_external_oracle: true
{contracts_yaml}database:
  pool:
    diesel_max: 3
    journal_max: 2
api:
  max_open_orders_default: 100
  max_open_positions_default: 50
  global_trading_halted: false
  halted_markets: []
  ws_heartbeat_interval_ms: 20000
  ws_pong_timeout_ms: 60000
  markets_snapshot_refresh_ms: 1000
  require_risk_vol_readiness: false
pricing:
  hyperliquid_info_url: https://api.hyperliquid-testnet.xyz/info
  hyperliquid_ws_url: wss://api.hyperliquid-testnet.xyz/ws
  candle_ws_poll_interval_ms: 2000
  min_settlement_samples: 500
  hypercore_info_url: https://api.hyperliquid-testnet.xyz/info
  hypercore_update_interval_secs: 30
  oracle_symbol: BTC
hydromancer:
  enabled: false
  api_url: https://api.hydromancer.xyz/info
transaction_submitter:
  mode: mock
  max_gas_price: "500000000000"
  rpc_url: https://rpc.hyperliquid-testnet.xyz/evm
catalog_manager:
  enabled: false
  interval_secs: 3600
catalog:
  version: 1
  expiry:
    expiry_time_utc: "08:00"
    schedule:
      daily_count: 2
      weekly_count: 4
      monthly_count: 3
  underlyings:
    BTC:
      trading_mode: orderbook
  collateral:
    BTC_PERP:
      kind: perp
      asset_id: 3
      underlying: BTC
    USDC:
      kind: stablecoin
      token_id: 0
  strike_selection:
    deribit_table_assets: [BTC, ETH, SOL, AVAX, XRP, TRX]
    deribit_region_steps:
      atm: 3
      outer: 4
      wings: 3
    occ_fallback_side_count: 8
  extension_policy:
    enabled: false
    ensure_min_strikes_per_side: 4
    ensure_atm_within_pct: 0.01
    cooldown_secs: 60
    max_total_strikes_per_expiry: 20
    min_spot_move_pct: 0.01
  observability:
    log_level: info
    metrics_enabled: true
  vol_oracles:
    providers:
      fixed-btc:
        kind: fixed
        iv: 0.55
    routes:
      BTC: fixed-btc
engine:
  persistence:
    journal:
      event_persistence: full
      critical_event_types: [L2Update]
      wal_path: /tmp/hypercall-engine.wal
      batch_channel_capacity: 1024
      batch_size: 100
      flush_interval_ms: 10
      digests_enabled: true
    outbox:
      poll_ms: 10
      batch_size: 500
      max_drain_iterations: 0
      drain_timeout_secs: 30
      skip_drain: false
  snapshot_interval_secs: 60
  post_startup_reconcile_delay_secs: 5
  read_snapshot_interval_ms: 500
background_tasks:
  historical_pnl:
    max_periods: 100
    capture_every_5m_ms: 300000
    capture_every_1h_ms: 3600000
    capture_every_1d_ms: 86400000
  bbo_snapshot:
    interval_secs: 300
    retention_days: 7
observability:
  tracing:
    enabled: true
    otlp_endpoint: http://localhost:4317
    service_name: hypercall
    sample_ratio: 1.0
  pyroscope:
    enabled: false
    server_address:
    application_name: hypercall
  metrics:
    skip_db_queries: false
"#
        )
    }

    #[test]
    fn parses_valid_backend_config() {
        let runtime = BackendRuntime::load_from_str(&sample_yaml()).unwrap();
        assert_eq!(runtime.config.pricing.oracle_symbol, "BTC");
        assert_eq!(
            runtime.config.contracts.exchange_contract_address,
            TESTNET_EXCHANGE_CONTRACT_ADDRESS
        );
    }

    #[test]
    #[serial]
    fn portfolio_margin_pool_env_overrides_yaml_runtime() {
        let _mode_allowlist = EnvGuard::set(
            "PORTFOLIO_MARGIN_MODE_ALLOWLIST",
            "0x0000000000000000000000000000000000001681, 0x0000000000000000000000000000000000001682",
        );
        let _pool_enabled = EnvGuard::set("PORTFOLIO_MARGIN_POOL_ENABLED", "true");
        let _allowlist = EnvGuard::set(
            "PORTFOLIO_MARGIN_SETTLEMENT_ALLOWLIST",
            "0x0000000000000000000000000000000000001693, 0x0000000000000000000000000000000000001694",
        );

        let mut runtime = BackendRuntime::load_from_str(&sample_yaml()).unwrap();
        assert!(!runtime.config.engine.portfolio_margin_pool_enabled);
        assert!(runtime
            .config
            .engine
            .portfolio_margin_mode_allowlist
            .is_empty());
        assert!(runtime
            .config
            .engine
            .portfolio_margin_settlement_allowlist
            .is_empty());

        runtime.apply_portfolio_margin_pool_env_overrides().unwrap();

        assert!(runtime.config.engine.portfolio_margin_pool_enabled);
        assert_eq!(
            runtime.config.engine.portfolio_margin_mode_allowlist,
            vec![
                "0x0000000000000000000000000000000000001681",
                "0x0000000000000000000000000000000000001682"
            ]
        );
        assert_eq!(
            runtime.config.engine.portfolio_margin_settlement_allowlist,
            vec![
                "0x0000000000000000000000000000000000001693",
                "0x0000000000000000000000000000000000001694"
            ]
        );
    }

    #[test]
    fn committed_staging_backend_config_parses() {
        BackendRuntime::load_from_str_for_config_only(include_str!(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../config/backend.staging.yaml"
        )))
        .expect("committed staging backend config should parse");
    }

    #[test]
    fn committed_aws_staging_backend_config_parses() {
        BackendRuntime::load_from_str_for_config_only(include_str!(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../infrastructure/aws/nonprod/staging/k8s/hypercall-staging/config/backend.staging.yaml"
        )))
        .expect("committed AWS staging backend config should parse");
    }

    #[test]
    fn committed_linode_staging_backend_config_parses() {
        BackendRuntime::load_from_str_for_config_only(include_str!(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../infrastructure/linode/staging/k8s/hypercall-staging/config/backend.staging.yaml"
        )))
        .expect("committed Linode staging backend config should parse");
    }

    #[test]
    fn committed_aws_production_backend_config_parses() {
        let runtime = BackendRuntime::load_from_str_for_config_only(include_str!(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../infrastructure/aws/prod/production/k8s/hypercall-production/config/backend.production.yaml"
        )))
        .expect("committed AWS production backend config should parse");
        assert!(
            !runtime.config.api.global_trading_halted,
            "AWS production backend config must not globally halt trading"
        );
    }

    #[test]
    fn committed_testnet_backend_config_parses() {
        BackendRuntime::load_from_str_for_config_only(include_str!(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../config/backend.testnet.yaml"
        )))
        .expect("committed testnet backend config should parse");
    }

    #[test]
    fn rejects_unknown_field() {
        assert!(BackendRuntime::load_from_str(
            &sample_yaml().replace("modes:\n", "modes:\n  nope: true\n"),
        )
        .is_err());
    }

    #[test]
    fn aws_kms_rsm_signer_uses_iam_credentials() {
        let mut config = BackendConfig::default();
        config.rsm_signer.provider = RsmSignerProvider::AwsKms;
        config.rsm_signer.aws_kms_key_id = "alias/hypercall-staging-rsm-signer".to_string();

        BackendSecrets::default()
            .validate(&config)
            .expect("aws_kms RSM signer should use IAM credentials");
    }

    #[test]
    fn aws_kms_rsm_signer_requires_key_id() {
        let mut config = BackendConfig::default();
        config.rsm_signer.provider = RsmSignerProvider::AwsKms;

        let err = BackendSecrets::default()
            .validate(&config)
            .unwrap_err()
            .to_string();

        assert!(err.contains("rsm_signer.provider=aws_kms requires rsm_signer.aws_kms_key_id"));
    }

    #[test]
    fn aws_kms_rsm_signer_requires_key_id_even_with_direct_submitter() {
        let mut config = BackendConfig::default();
        config.transaction_submitter.mode = TransactionSubmitterMode::Direct;
        config.rsm_signer.provider = RsmSignerProvider::AwsKms;

        let secrets = BackendSecrets {
            transaction_submitter_private_key: Some(
                "0x0123456789012345678901234567890123456789012345678901234567890123".to_string(),
            ),
            ..BackendSecrets::default()
        };

        let err = secrets.validate(&config).unwrap_err().to_string();
        assert!(err.contains("rsm_signer.provider=aws_kms requires rsm_signer.aws_kms_key_id"));
    }

    #[test]
    fn aws_kms_transaction_submitter_does_not_require_plaintext_key() {
        let mut config = BackendConfig::default();
        config.transaction_submitter.mode = TransactionSubmitterMode::AwsKms;
        config.transaction_submitter.aws_kms_key_id =
            "alias/hypercall-staging-tx-submitter".to_string();

        BackendSecrets::default()
            .validate(&config)
            .expect("aws_kms transaction submitter should use IAM instead of plaintext keys");
    }

    #[test]
    fn aws_kms_transaction_submitter_requires_key_id() {
        let mut config = BackendConfig::default();
        config.transaction_submitter.mode = TransactionSubmitterMode::AwsKms;

        let err = BackendSecrets::default()
            .validate(&config)
            .unwrap_err()
            .to_string();

        assert!(err.contains(
            "transaction_submitter.mode=aws_kms requires transaction_submitter.aws_kms_key_id"
        ));
    }

    #[test]
    fn aws_kms_transaction_submitter_does_not_satisfy_liquidation_rsm_signer() {
        let mut config = BackendConfig::default();
        config.contracts.exchange_contract_address = TESTNET_EXCHANGE_CONTRACT_ADDRESS.to_string();
        config.contracts.core_deposit_wallet_address =
            TESTNET_CORE_DEPOSIT_WALLET_ADDRESS.to_string();
        config.contracts.usdc_address = TESTNET_USDC_ADDRESS.to_string();
        config.contracts.option_registry_address = TESTNET_OPTION_REGISTRY_ADDRESS.to_string();
        config.contracts.option_token_beacon_proxy_init_code_hash =
            TESTNET_OPTION_TOKEN_BEACON_PROXY_INIT_CODE_HASH.to_string();
        config.transaction_submitter.mode = TransactionSubmitterMode::AwsKms;
        config.transaction_submitter.aws_kms_key_id =
            "alias/hypercall-staging-tx-submitter".to_string();
        config.liquidation.enabled = true;

        let err = config.validate().unwrap_err().to_string();
        assert!(
            err.contains(
                "liquidation.enabled requires rsm_signer.aws_kms_key_id or transaction_submitter.mode=direct"
            ),
            "{err}"
        );
    }

    #[test]
    fn rejects_invalid_ws_timeouts() {
        let err = BackendRuntime::load_from_str(
            &sample_yaml().replace("  ws_pong_timeout_ms: 60000", "  ws_pong_timeout_ms: 1000"),
        )
        .unwrap_err()
        .to_string();
        assert!(err.contains("ws_pong_timeout_ms"));
    }

    #[test]
    fn rejects_zero_sized_db_pools() {
        let err = BackendRuntime::load_from_str(
            &sample_yaml().replace("    diesel_max: 3", "    diesel_max: 0"),
        )
        .unwrap_err()
        .to_string();
        assert!(err.contains("database.pool.diesel_max"));
    }

    #[test]
    fn rejects_missing_contracts_config() {
        let err = BackendRuntime::load_from_str(
            &sample_yaml().replace(&testnet_contracts_yaml_block(), ""),
        )
        .unwrap_err()
        .to_string();

        assert!(err.contains("contracts.exchange_contract_address"));
    }

    #[test]
    #[serial]
    fn non_full_runtime_skips_contract_validation() {
        let _database_url = EnvGuard::set(
            "DATABASE_URL",
            "postgresql://test_user:test_password@localhost:5432/hypercall_test",
        );
        let yaml_without_contracts = sample_yaml().replace(&testnet_contracts_yaml_block(), "");

        BackendRuntime::load_from_str_for_migrations(&yaml_without_contracts)
            .expect("migration runtime should not require contracts config");
        BackendRuntime::load_from_str_for_config_only(&yaml_without_contracts)
            .expect("config-only runtime should not require contracts config");
        BackendRuntime::load_from_str_for_database_only(&yaml_without_contracts)
            .expect("database-only runtime should not require contracts config");
        BackendRuntime::load_from_str_for_database_only(&yaml_without_contracts)
            .expect("database-only runtime should not require contracts config (2)");
    }

    #[test]
    #[serial]
    fn resolves_catalog_secret_placeholders() {
        let _guard = EnvGuard::set("BACKEND_CONFIG_TEST_POLYGON_KEY", "polygon-secret");
        let yaml = sample_yaml().replace(
            r#"    providers:
      fixed-btc:
        kind: fixed
        iv: 0.55
    routes:
      BTC: fixed-btc"#,
            r#"    providers:
      polygon-btc:
        kind: polygon
        api_key: ${BACKEND_CONFIG_TEST_POLYGON_KEY}
        underlyings:
          BTC:
            ticker: X:BTCUSD
            strike_scale: 1.0
    routes:
      BTC: polygon-btc"#,
        );

        let runtime = BackendRuntime::load_from_str(&yaml).unwrap();
        let provider = runtime
            .config
            .catalog
            .vol_oracles
            .providers
            .get("polygon-btc")
            .unwrap();

        match provider {
            catalog_manager::VolOracleProviderConfig::Polygon(config) => {
                assert_eq!(config.api_key, "polygon-secret");
            }
            _ => panic!("expected polygon provider"),
        }
    }

    #[test]
    #[serial]
    fn fails_when_enabled_secret_is_missing() {
        let _guard = EnvGuard::remove("HYDROMANCER_API_KEY");
        let err = BackendRuntime::load_from_str(
            &sample_yaml().replace("  enabled: false", "  enabled: true"),
        )
        .unwrap_err()
        .to_string();
        assert!(err.contains("HYDROMANCER_API_KEY"));
    }

    #[test]
    #[serial]
    fn migration_runtime_only_requires_database_secret() {
        let _database_url = EnvGuard::set(
            "DATABASE_URL",
            "postgresql://test_user:test_password@localhost:5432/hypercall_test",
        );
        let _hydromancer = EnvGuard::remove("HYDROMANCER_API_KEY");

        let yaml = sample_yaml()
            .replace(
                "hydromancer:\n  enabled: false",
                "hydromancer:\n  enabled: true",
            )
            .replace(
                "transaction_submitter:\n  mode: mock",
                "transaction_submitter:\n  mode: direct",
            );

        let runtime = BackendRuntime::load_from_str_for_migrations(&yaml).unwrap();
        assert!(runtime.config.hydromancer.enabled);
        assert_eq!(
            runtime.config.transaction_submitter.mode,
            TransactionSubmitterMode::Direct
        );
    }

    #[test]
    #[serial]
    fn migration_runtime_allows_unresolved_catalog_secret_placeholders() {
        let _database_url = EnvGuard::set(
            "DATABASE_URL",
            "postgresql://test_user:test_password@localhost:5432/hypercall_test",
        );
        let _polygon_key = EnvGuard::remove("BACKEND_CONFIG_TEST_POLYGON_KEY");
        let yaml = sample_yaml().replace(
            r#"    providers:
      fixed-btc:
        kind: fixed
        iv: 0.55
    routes:
      BTC: fixed-btc"#,
            r#"    providers:
      polygon-btc:
        kind: polygon
        api_key: ${BACKEND_CONFIG_TEST_POLYGON_KEY}
        underlyings:
          BTC:
            ticker: X:BTCUSD
            strike_scale: 1.0
    routes:
      BTC: polygon-btc"#,
        );

        let runtime = BackendRuntime::load_from_str_for_migrations(&yaml).unwrap();
        let provider = runtime
            .config
            .catalog
            .vol_oracles
            .providers
            .get("polygon-btc")
            .unwrap();

        match provider {
            catalog_manager::VolOracleProviderConfig::Polygon(config) => {
                assert_eq!(config.api_key, "${BACKEND_CONFIG_TEST_POLYGON_KEY}");
            }
            _ => panic!("expected polygon provider"),
        }
    }

    #[test]
    #[serial]
    fn non_full_runtime_modes_allow_unresolved_catalog_secret_placeholders() {
        let _database_url = EnvGuard::set(
            "DATABASE_URL",
            "postgresql://test_user:test_password@localhost:5432/hypercall_test",
        );
        let _polygon_key = EnvGuard::remove("BACKEND_CONFIG_TEST_POLYGON_KEY");
        let yaml = sample_yaml().replace(
            r#"    providers:
      fixed-btc:
        kind: fixed
        iv: 0.55
    routes:
      BTC: fixed-btc"#,
            r#"    providers:
      polygon-btc:
        kind: polygon
        api_key: ${BACKEND_CONFIG_TEST_POLYGON_KEY}
        underlyings:
          BTC:
            ticker: X:BTCUSD
            strike_scale: 1.0
    routes:
      BTC: polygon-btc"#,
        );

        for loader in [
            BackendRuntime::load_from_str_for_config_only,
            BackendRuntime::load_from_str_for_database_only,
        ] {
            let runtime = loader(&yaml).expect("non-full runtime should allow placeholders");
            let provider = runtime
                .config
                .catalog
                .vol_oracles
                .providers
                .get("polygon-btc")
                .expect("polygon provider should be present");

            match provider {
                catalog_manager::VolOracleProviderConfig::Polygon(config) => {
                    assert_eq!(config.api_key, "${BACKEND_CONFIG_TEST_POLYGON_KEY}");
                }
                _ => panic!("expected polygon provider"),
            }
        }
    }

    #[test]
    #[serial]
    fn full_runtime_requires_catalog_secret_placeholders_to_resolve() {
        let _polygon_key = EnvGuard::remove("BACKEND_CONFIG_TEST_POLYGON_KEY");
        let yaml = sample_yaml().replace(
            r#"    providers:
      fixed-btc:
        kind: fixed
        iv: 0.55
    routes:
      BTC: fixed-btc"#,
            r#"    providers:
      polygon-btc:
        kind: polygon
        api_key: ${BACKEND_CONFIG_TEST_POLYGON_KEY}
        underlyings:
          BTC:
            ticker: X:BTCUSD
            strike_scale: 1.0
    routes:
      BTC: polygon-btc"#,
        );

        let err = BackendRuntime::load_from_str(&yaml).unwrap_err();
        let rendered = format!("{err:#}");
        assert!(rendered.contains("BACKEND_CONFIG_TEST_POLYGON_KEY"));
    }

    #[test]
    #[serial]
    fn migration_runtime_requires_database_secret() {
        let _database_url = EnvGuard::remove("DATABASE_URL");
        let _direct_url = EnvGuard::remove("DIRECT_URL");

        let err = BackendRuntime::load_from_str_for_migrations(&sample_yaml())
            .unwrap_err()
            .to_string();
        assert!(
            err.contains("DIRECT_URL or DATABASE_URL"),
            "unexpected error: {}",
            err
        );
    }

    #[test]
    #[serial]
    fn migration_runtime_skips_legacy_catalog_loading() {
        let _database_url = EnvGuard::set(
            "DATABASE_URL",
            "postgresql://test_user:test_password@localhost:5432/hypercall_test",
        );
        let _catalog_path = EnvGuard::set(
            "CATALOG_MANAGER_CATALOG_PATH",
            "/tmp/definitely-missing-catalog-for-migrations.yaml",
        );

        BackendRuntime::from_legacy_env_for_migrations()
            .expect("migration runtime should not require legacy catalog assets");
    }

    #[test]
    #[serial]
    fn non_full_legacy_env_runtime_skips_legacy_catalog_loading() {
        let _database_url = EnvGuard::set(
            "DATABASE_URL",
            "postgresql://test_user:test_password@localhost:5432/hypercall_test",
        );
        let _catalog_path = EnvGuard::set(
            "CATALOG_MANAGER_CATALOG_PATH",
            "/tmp/definitely-missing-catalog-for-non-full-runtime.yaml",
        );

        BackendRuntime::from_legacy_env_for_config_only()
            .expect("config-only runtime should not require legacy catalog assets");
        BackendRuntime::from_legacy_env_for_database_only()
            .expect("database-only runtime should not require legacy catalog assets");
    }

    #[test]
    #[serial]
    fn config_only_runtime_skips_unrelated_secret_validation() {
        let _database_url = EnvGuard::remove("DATABASE_URL");
        let _hydromancer = EnvGuard::remove("HYDROMANCER_API_KEY");

        let yaml = sample_yaml()
            .replace(
                "hydromancer:\n  enabled: false",
                "hydromancer:\n  enabled: true",
            )
            .replace(
                "transaction_submitter:\n  mode: mock",
                "transaction_submitter:\n  mode: direct",
            );

        let runtime = BackendRuntime::load_from_str_for_config_only(&yaml).unwrap();
        assert!(runtime.config.hydromancer.enabled);
        assert_eq!(
            runtime.config.transaction_submitter.mode,
            TransactionSubmitterMode::Direct
        );
    }

    #[test]
    #[serial]
    fn database_only_runtime_requires_database_but_skips_other_secrets() {
        let _database_url = EnvGuard::set(
            "DATABASE_URL",
            "postgresql://test_user:test_password@localhost:5432/hypercall_test",
        );
        let _hydromancer = EnvGuard::remove("HYDROMANCER_API_KEY");

        let yaml = sample_yaml()
            .replace(
                "hydromancer:\n  enabled: false",
                "hydromancer:\n  enabled: true",
            )
            .replace(
                "transaction_submitter:\n  mode: mock",
                "transaction_submitter:\n  mode: direct",
            );

        let runtime = BackendRuntime::load_from_str_for_database_only(&yaml).unwrap();
        assert!(runtime.config.hydromancer.enabled);
        assert_eq!(
            runtime.config.transaction_submitter.mode,
            TransactionSubmitterMode::Direct
        );
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_uses_catalog_manager_catalog_path() {
        let _contracts = set_test_contract_env();
        let dir = tempfile::tempdir().expect("create tempdir");
        let catalog_path = dir.path().join("catalog.yaml");
        std::fs::write(
            &catalog_path,
            r#"
version: 1
expiry:
  expiry_time_utc: "08:00"
  schedule:
    daily_count: 1
    weekly_count: 1
    monthly_count: 1
underlyings:
  ETH:
    trading_mode: orderbook
collateral:
  ETH_PERP:
    kind: perp
    asset_id: 4
    underlying: ETH
  USDC:
    kind: stablecoin
    token_id: 0
strike_selection:
  deribit_table_assets: [BTC, ETH, SOL, AVAX, XRP, TRX]
  deribit_region_steps:
    atm: 3
    outer: 4
    wings: 3
  occ_fallback_side_count: 8
extension_policy:
  enabled: false
  ensure_min_strikes_per_side: 2
  ensure_atm_within_pct: 0.01
  cooldown_secs: 60
  max_total_strikes_per_expiry: 10
  min_spot_move_pct: 0.01
observability:
  log_level: info
  metrics_enabled: true
vol_oracles:
  providers:
    fixed-eth:
      kind: fixed
      iv: 0.4
  routes:
    ETH: fixed-eth
"#,
        )
        .expect("write catalog");
        let _catalog_path = EnvGuard::set(
            "CATALOG_MANAGER_CATALOG_PATH",
            catalog_path.to_str().expect("catalog path string"),
        );

        let runtime = BackendRuntime::from_legacy_env().unwrap();
        assert!(runtime.config.catalog.underlyings.contains_key("ETH"));
        assert!(!runtime.config.catalog.underlyings.contains_key("BTC"));
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_applies_runtime_overrides() {
        let _contracts = set_test_contract_env();
        let _testnet = EnvGuard::set("TESTNET_MODE", "1");
        let _post_startup = EnvGuard::set("ENGINE_POST_STARTUP_RECONCILE_DELAY_SECS", "0");
        let _orders = EnvGuard::set("MAX_OPEN_ORDERS_DEFAULT", "42");
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());

        let runtime = BackendRuntime::from_legacy_env().unwrap();
        assert!(runtime.config.modes.testnet_mode);
        assert_eq!(runtime.config.engine.post_startup_reconcile_delay_secs, 0);
        assert_eq!(runtime.config.api.max_open_orders_default, 42);
        assert_eq!(
            runtime.config.contracts.option_registry_address,
            TESTNET_OPTION_REGISTRY_ADDRESS
        );
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_uses_testnet_pricing_defaults() {
        let _contracts = set_test_contract_env();
        let _testnet = EnvGuard::set("TESTNET_MODE", "1");
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());
        let _info_url = EnvGuard::remove("HYPERLIQUID_INFO_URL");
        let _ws_url = EnvGuard::remove("HYPERLIQUID_WS_URL");
        let _hypercore_info_url = EnvGuard::remove("HYPERCORE_INFO_URL");

        let runtime = BackendRuntime::from_legacy_env().unwrap();
        assert_eq!(
            runtime.config.pricing.hyperliquid_info_url,
            DEFAULT_HYPERLIQUID_TESTNET_INFO_URL
        );
        assert_eq!(
            runtime.config.pricing.hyperliquid_ws_url,
            crate::price_oracle::hyperliquid_ws::DEFAULT_TESTNET_WS_URL
        );
        assert_eq!(
            runtime.config.pricing.hypercore_info_url,
            DEFAULT_HYPERLIQUID_TESTNET_INFO_URL
        );
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_promotes_transaction_submitter_to_direct() {
        let _contracts = set_test_contract_env();
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());
        let _mode = EnvGuard::remove("TRANSACTION_SUBMITTER_MODE");
        let _signer = EnvGuard::set(
            "TRANSACTION_SUBMITTER_PRIVATE_KEY",
            "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
        );
        let _rpc_url = EnvGuard::set("RPC_URL", "https://rpc.hyperliquid-testnet.xyz/evm");
        let _max_gas_price = EnvGuard::set("MAX_GAS_PRICE", "500000000000");
        let _exchange_address = EnvGuard::set(
            "EXCHANGE_CONTRACT_ADDRESS",
            "0x1d70Ff185F6C25E4d76163F16563D63d5b590Cbc",
        );

        let runtime = BackendRuntime::from_legacy_env().unwrap();
        assert_eq!(
            runtime.config.transaction_submitter.mode,
            TransactionSubmitterMode::Direct
        );
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_promotes_transaction_submitter_to_aws_kms() {
        let _contracts = set_test_contract_env();
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());
        let _mode = EnvGuard::remove("TRANSACTION_SUBMITTER_MODE");
        let _plaintext_signer = EnvGuard::remove("TRANSACTION_SUBMITTER_PRIVATE_KEY");
        let _kms_key = EnvGuard::set(
            "TRANSACTION_SUBMITTER_AWS_KMS_KEY_ID",
            "alias/hypercall-staging-tx-submitter",
        );
        let _rpc_url = EnvGuard::set("RPC_URL", "https://rpc.hyperliquid.xyz/evm");
        let _max_gas_price = EnvGuard::set("MAX_GAS_PRICE", "1000000000");

        let runtime = BackendRuntime::from_legacy_env().unwrap();
        assert_eq!(
            runtime.config.transaction_submitter.mode,
            TransactionSubmitterMode::AwsKms
        );
        assert_eq!(
            runtime.config.transaction_submitter.aws_kms_key_id,
            "alias/hypercall-staging-tx-submitter"
        );
    }

    #[test]
    #[serial]
    fn explicit_transaction_submitter_mode_env_accepts_aws_kms() {
        let _contracts = set_test_contract_env();
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());
        let _mode = EnvGuard::set("TRANSACTION_SUBMITTER_MODE", "aws_kms");
        let _kms_key = EnvGuard::set(
            "TRANSACTION_SUBMITTER_AWS_KMS_KEY_ID",
            "alias/hypercall-staging-tx-submitter",
        );

        let runtime = BackendRuntime::from_legacy_env().unwrap();
        assert_eq!(
            runtime.config.transaction_submitter.mode,
            TransactionSubmitterMode::AwsKms
        );
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_allows_direct_liquidation_with_local_signer() {
        let _contracts = set_test_contract_env();
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());
        let _signer = EnvGuard::set(
            "TRANSACTION_SUBMITTER_PRIVATE_KEY",
            "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
        );
        let _rpc_url = EnvGuard::set("RPC_URL", "https://rpc.hyperliquid-testnet.xyz/evm");
        let _max_gas_price = EnvGuard::set("MAX_GAS_PRICE", "500000000000");
        let _exchange_address = EnvGuard::set(
            "EXCHANGE_CONTRACT_ADDRESS",
            "0x1d70Ff185F6C25E4d76163F16563D63d5b590Cbc",
        );
        let _enabled = EnvGuard::set("LIQUIDATION_ENABLED", "true");

        let runtime = BackendRuntime::from_legacy_env().unwrap();
        assert_eq!(
            runtime.config.transaction_submitter.mode,
            TransactionSubmitterMode::Direct
        );
        assert!(runtime.config.liquidation.enabled);
        assert_eq!(runtime.config.rsm_signer.provider, RsmSignerProvider::Local);
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_promotes_rsm_signer_to_aws_kms_from_key_id() {
        let _contracts = set_test_contract_env();
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());
        let _rsm_provider = EnvGuard::remove("RSM_SIGNER_PROVIDER");
        let _rsm_kms_key = EnvGuard::set(
            "RSM_SIGNER_AWS_KMS_KEY_ID",
            "alias/hypercall-staging-rsm-signer",
        );

        let runtime = BackendRuntime::from_legacy_env().unwrap();

        assert_eq!(
            runtime.config.rsm_signer.provider,
            RsmSignerProvider::AwsKms
        );
        assert_eq!(
            runtime.config.rsm_signer.aws_kms_key_id,
            "alias/hypercall-staging-rsm-signer"
        );
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_accepts_explicit_rsm_signer_provider() {
        let _contracts = set_test_contract_env();
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());
        let _rsm_provider = EnvGuard::set("RSM_SIGNER_PROVIDER", "aws_kms");
        let _rsm_kms_key = EnvGuard::set(
            "RSM_SIGNER_AWS_KMS_KEY_ID",
            "alias/hypercall-staging-rsm-signer",
        );

        let runtime = BackendRuntime::from_legacy_env().unwrap();

        assert_eq!(
            runtime.config.rsm_signer.provider,
            RsmSignerProvider::AwsKms
        );
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_does_not_promote_to_direct_without_signer() {
        let _contracts = set_test_contract_env();
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());
        let _signer = EnvGuard::remove("TRANSACTION_SUBMITTER_PRIVATE_KEY");
        let _rpc_url = EnvGuard::set("RPC_URL", "https://rpc.hyperliquid-testnet.xyz/evm");
        let _max_gas_price = EnvGuard::set("MAX_GAS_PRICE", "500000000000");

        let runtime = BackendRuntime::from_legacy_env().unwrap();
        assert_eq!(
            runtime.config.transaction_submitter.mode,
            TransactionSubmitterMode::Mock
        );
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_applies_liquidation_overrides() {
        let _contracts = set_test_contract_env();
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());
        let _signer = EnvGuard::set(
            "TRANSACTION_SUBMITTER_PRIVATE_KEY",
            "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
        );
        let _rpc_url = EnvGuard::set("RPC_URL", "https://rpc.hyperliquid-testnet.xyz/evm");
        let _max_gas_price = EnvGuard::set("MAX_GAS_PRICE", "500000000000");
        let _enabled = EnvGuard::set("LIQUIDATION_ENABLED", "true");
        let _poll = EnvGuard::set("LIQUIDATION_HEALTH_POLL_INTERVAL_MS", "123");
        let _buffer = EnvGuard::set("LIQUIDATION_PARTIAL_TARGET_BUFFER_BPS", "456");
        let _threshold = EnvGuard::set("LIQUIDATION_MIN_SHORTFALL_THRESHOLD", "7.5");

        let runtime = BackendRuntime::from_legacy_env().unwrap();
        assert!(runtime.config.liquidation.enabled);
        assert_eq!(runtime.config.liquidation.health_poll_interval_ms, 123);
        assert_eq!(runtime.config.liquidation.partial_target_buffer_bps, 456);
        assert_eq!(
            runtime.config.liquidation.min_shortfall_threshold,
            Decimal::from_str("7.5").unwrap()
        );
    }

    #[test]
    #[serial]
    fn legacy_env_runtime_requires_contract_env() {
        let _exchange_address = EnvGuard::remove("EXCHANGE_CONTRACT_ADDRESS");
        let _option_registry = EnvGuard::remove("OPTION_REGISTRY_ADDRESS");
        let _init_code_hash = EnvGuard::remove("OPTION_TOKEN_BEACON_PROXY_INIT_CODE_HASH");
        let _catalog_path =
            EnvGuard::set("CATALOG_MANAGER_CATALOG_PATH", repo_market_catalog_path());

        let err = BackendRuntime::from_legacy_env().unwrap_err().to_string();
        assert!(err.contains("contracts.exchange_contract_address"));
    }
}