nautilus_hyperliquid/http/

parse.rs

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

use anyhow::Context;
use jiff::Timestamp;
use nautilus_core::{Params, UUID4, UnixNanos, datetime::unix_nanos_to_iso8601};
use nautilus_model::{
    data::TradeTick,
    enums::{
        AggressorSide, AssetClass, CurrencyType, LiquiditySide, OrderSide, OrderStatus, OrderType,
        PositionSide, TimeInForce, TriggerType,
    },
    identifiers::{AccountId, ClientOrderId, InstrumentId, Symbol, TradeId, VenueOrderId},
    instruments::{BinaryOption, CryptoPerpetual, CurrencyPair, Instrument, InstrumentAny},
    reports::{FillReport, OrderStatusReport, PositionStatusReport},
    types::{Currency, Money, Price, Quantity},
};
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use ustr::Ustr;

use super::models::{
    AssetPosition, HyperliquidFill, HyperliquidRecentTrade, OutcomeMarket, OutcomeMeta,
    OutcomeQuestion, PerpMeta, SpotBalance, SpotMeta,
};
use crate::{
    common::{
        consts::{ASSET_INDEX_INFO_KEY, HYPERLIQUID_VENUE},
        converters::hyperliquid_time_in_force_to_nautilus,
        enums::{
            HyperliquidFillDirection, HyperliquidOrderStatus as HyperliquidOrderStatusEnum,
            HyperliquidSide, HyperliquidTimeInForce,
        },
        parse::{
            format_outcome_nautilus_symbol, is_conditional_order_data, make_fill_trade_id,
            millis_to_nanos, parse_trigger_order_type,
        },
        types::HyperliquidAssetId,
    },
    data_types::HyperliquidPublicTrade,
    websocket::messages::{WsBasicOrderData, WsOrderData},
};

/// Market type enumeration for normalized instrument definitions.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum HyperliquidMarketType {
    /// Perpetual futures contract.
    Perp,
    /// Spot trading pair.
    Spot,
    /// HIP-4 binary outcome side token.
    Outcome,
}

/// Outcome-specific metadata carried on [`HyperliquidInstrumentDef`] for HIP-4
/// binary outcome side tokens.
///
/// The venue's `outcomeMeta` payload is partial today (no precision or
/// expiry fields), so unknown values are left as defaults until real venue
/// payloads are available.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HyperliquidOutcomeMetadata {
    /// HIP-4 outcome index (`outcome` field from `outcomeMeta`).
    pub outcome_index: u32,
    /// Side digit (`0` or `1`).
    pub outcome_side: u8,
    /// Outcome market name (for example, "BTC daily").
    pub market_name: Ustr,
    /// Side specification name. Set from the venue's `sideSpecs` entry when
    /// present, otherwise falls back to the canonical HIP-4 labels (`"Yes"`
    /// for side `0`, `"No"` for side `1`).
    pub side_name: Option<Ustr>,
    /// Venue-supplied description.
    pub description: Option<Ustr>,
    /// Activation timestamp; `0` when the venue payload does not expose it.
    pub activation_ns: UnixNanos,
    /// Expiration timestamp; `0` when the venue payload does not expose it.
    pub expiration_ns: UnixNanos,
    /// Structured metadata surfaced as `BinaryOption.info`; see the Hyperliquid
    /// integration guide for the field layout.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub info: Option<Params>,
}

/// Normalized instrument definition produced by this parser.
///
/// This deliberately avoids any tight coupling to Nautilus domain types.
/// The InstrumentProvider can later convert this into Nautilus `Instrument`s.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HyperliquidInstrumentDef {
    /// Human-readable symbol (e.g., "BTC-USD-PERP", "PURR-USDC-SPOT").
    pub symbol: Ustr,
    /// Raw symbol used in Hyperliquid WebSocket subscriptions/messages.
    /// For perps: base currency (e.g., "BTC").
    /// For spot: `@{pair_index}` format (e.g., "@107" for HYPE-USDC).
    /// For outcomes: `#<encoding>` spot-coin form (e.g., "#10").
    pub raw_symbol: Ustr,
    /// Base currency/asset (e.g., "BTC", "PURR").
    pub base: Ustr,
    /// Quote currency (e.g., "USD" for perps, "USDC" for spot).
    pub quote: Ustr,
    /// Settlement currency for perps. `None` for spot and outcome instruments.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub settlement: Option<Ustr>,
    /// Market type (perpetual, spot, or outcome).
    pub market_type: HyperliquidMarketType,
    /// Asset index used for order submission.
    /// For perps: index in meta.universe (0, 1, 2, ...).
    /// For spot: 10000 + index in spotMeta.universe.
    /// For outcomes: `100_000_000 + 10 * outcome + side`.
    pub asset_index: u32,
    /// Number of decimal places for price precision.
    pub price_decimals: u32,
    /// Number of decimal places for size precision.
    pub size_decimals: u32,
    /// Price tick size as decimal.
    pub tick_size: Decimal,
    /// Size lot increment as decimal.
    pub lot_size: Decimal,
    /// Maximum leverage (for perps).
    pub max_leverage: Option<u32>,
    /// Whether requires isolated margin only.
    pub only_isolated: bool,
    /// Whether this is a HIP-3 builder-deployed perpetual.
    pub is_hip3: bool,
    /// Whether the instrument is active/tradeable.
    pub active: bool,
    /// Outcome-specific metadata when [`market_type`](Self::market_type) is
    /// [`HyperliquidMarketType::Outcome`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub outcome: Option<HyperliquidOutcomeMetadata>,
    /// Raw upstream data for debugging.
    pub raw_data: String,
}

// Replace wildcard bytes (`*`, `?`) in a venue-supplied symbol component with
// `x` so the value is safe to embed in a Nautilus `InstrumentId`. HIP-3
// perpetual names from Hyperliquid (e.g. `dex:STREAMABCD****-USD-PERP`)
// collide with msgbus pattern syntax; the venue-official name is preserved on
// `raw_symbol` for HTTP/WS wire calls, and orders use the numeric
// `asset_index` so they do not see the substitution.
#[must_use]
fn sanitize_symbol(value: &str) -> std::borrow::Cow<'_, str> {
    if value.bytes().any(|b| b == b'*' || b == b'?') {
        let mut out = String::with_capacity(value.len());
        for ch in value.chars() {
            out.push(if ch == '*' || ch == '?' { 'x' } else { ch });
        }
        std::borrow::Cow::Owned(out)
    } else {
        std::borrow::Cow::Borrowed(value)
    }
}

/// Parse perpetual instrument definitions from Hyperliquid `meta` response.
///
/// Hyperliquid perps follow specific rules:
/// - Quote is always USD (USDC settled)
/// - Price decimals = max(0, 6 - sz_decimals) per venue docs
/// - Active = !is_delisted
///
/// `asset_index_base` controls the starting offset for asset IDs:
/// - Standard perps (dex 0): base = 0
/// - HIP-3 dexes: base = 100_000 + dex_index * 10_000
///
/// Delisted instruments are included but marked as inactive to support
/// parsing historical data for instruments that may still have trading history.
pub fn parse_perp_instruments(
    meta: &PerpMeta,
    asset_index_base: u32,
) -> Result<Vec<HyperliquidInstrumentDef>, String> {
    Ok(parse_perp_instruments_with_settlement(
        meta,
        asset_index_base,
        DEFAULT_PERP_SETTLEMENT_CURRENCY,
    ))
}

pub(crate) fn parse_perp_instruments_with_settlement(
    meta: &PerpMeta,
    asset_index_base: u32,
    settlement_currency: &str,
) -> Vec<HyperliquidInstrumentDef> {
    const PERP_MAX_DECIMALS: i32 = 6;

    let mut defs = Vec::new();

    for (index, asset) in meta.universe.iter().enumerate() {
        let is_delisted = asset.is_delisted.unwrap_or(false);

        let price_decimals = (PERP_MAX_DECIMALS - asset.sz_decimals as i32).max(0) as u32;
        let tick_size = pow10_neg(price_decimals);
        let lot_size = pow10_neg(asset.sz_decimals);

        let symbol = format!("{}-USD-PERP", sanitize_symbol(&asset.name));

        let raw_symbol: Ustr = asset.name.as_str().into();

        let def = HyperliquidInstrumentDef {
            symbol: symbol.into(),
            raw_symbol,
            base: asset.name.clone().into(),
            quote: "USD".into(),
            settlement: Some(settlement_currency.into()),
            market_type: HyperliquidMarketType::Perp,
            asset_index: asset_index_base + index as u32,
            price_decimals,
            size_decimals: asset.sz_decimals,
            tick_size,
            lot_size,
            max_leverage: asset.max_leverage,
            only_isolated: asset.only_isolated.unwrap_or(false),
            is_hip3: asset_index_base > 0,
            active: !is_delisted,
            outcome: None,
            raw_data: serde_json::to_string(asset).unwrap_or_default(),
        };

        defs.push(def);
    }

    defs
}

const DEFAULT_PERP_COLLATERAL_TOKEN: u32 = 0;
const DEFAULT_PERP_SETTLEMENT_CURRENCY: &str = "USDC";

pub(crate) fn resolve_perp_settlement_currency(
    meta: &PerpMeta,
    spot_meta: Option<&SpotMeta>,
) -> Result<Ustr, String> {
    let Some(collateral_token) = meta.collateral_token else {
        return Ok(DEFAULT_PERP_SETTLEMENT_CURRENCY.into());
    };

    if collateral_token == DEFAULT_PERP_COLLATERAL_TOKEN {
        return Ok(DEFAULT_PERP_SETTLEMENT_CURRENCY.into());
    }

    let spot_meta = spot_meta.ok_or_else(|| {
        format!("Spot metadata required to resolve perp collateral token {collateral_token}")
    })?;
    let token = spot_meta
        .tokens
        .iter()
        .find(|token| token.index == collateral_token)
        .ok_or_else(|| {
            format!("Perp collateral token index {collateral_token} not found in spot metadata")
        })?;

    Ok(token.name.as_str().into())
}

/// Parse spot instrument definitions from Hyperliquid `spotMeta` response.
///
/// Hyperliquid spot follows these rules:
/// - Price decimals = max(0, 8 - base_sz_decimals) per venue docs
/// - Size decimals from base token
/// - All pairs in the universe are active, including non-canonical pairs
pub fn parse_spot_instruments(meta: &SpotMeta) -> Result<Vec<HyperliquidInstrumentDef>, String> {
    const SPOT_MAX_DECIMALS: i32 = 8; // Hyperliquid spot price decimal limit
    const SPOT_INDEX_OFFSET: u32 = 10000; // Spot assets use 10000 + index

    let mut defs = Vec::new();

    // Build index -> token lookup
    let mut tokens_by_index = ahash::AHashMap::new();
    for token in &meta.tokens {
        tokens_by_index.insert(token.index, token);
    }

    // Cache canonical pairs first because base-token aliases are first-write-wins
    let mut pairs = meta.universe.iter().collect::<Vec<_>>();
    pairs.sort_by(|a, b| {
        b.is_canonical
            .cmp(&a.is_canonical)
            .then(a.index.cmp(&b.index))
    });

    for pair in pairs {
        let base_token = tokens_by_index
            .get(&pair.tokens[0])
            .ok_or_else(|| format!("Base token index {} not found", pair.tokens[0]))?;
        let quote_token = tokens_by_index
            .get(&pair.tokens[1])
            .ok_or_else(|| format!("Quote token index {} not found", pair.tokens[1]))?;

        let price_decimals = (SPOT_MAX_DECIMALS - base_token.sz_decimals as i32).max(0) as u32;
        let tick_size = pow10_neg(price_decimals);
        let lot_size = pow10_neg(base_token.sz_decimals);

        let symbol = format!(
            "{}-{}-SPOT",
            sanitize_symbol(&base_token.name),
            sanitize_symbol(&quote_token.name),
        );

        // Hyperliquid spot raw_symbol formats (per API docs):
        // - PURR uses slash format from pair.name (e.g., "PURR/USDC")
        // - All others use "@{pair_index}" format (e.g., "@107" for HYPE)
        let raw_symbol: Ustr = if base_token.name == "PURR" {
            pair.name.as_str().into()
        } else {
            format!("@{}", pair.index).into()
        };

        let def = HyperliquidInstrumentDef {
            symbol: symbol.into(),
            raw_symbol,
            base: base_token.name.clone().into(),
            quote: quote_token.name.clone().into(),
            settlement: None,
            market_type: HyperliquidMarketType::Spot,
            asset_index: SPOT_INDEX_OFFSET + pair.index,
            price_decimals,
            size_decimals: base_token.sz_decimals,
            tick_size,
            lot_size,
            max_leverage: None,
            only_isolated: false,
            is_hip3: false,
            active: true,
            outcome: None,
            raw_data: serde_json::to_string(pair).unwrap_or_default(),
        };

        defs.push(def);
    }

    Ok(defs)
}

// Default precision for HIP-4 outcome side tokens until the venue exposes
// per-market values via `outcomeMeta`. Outcomes settle in `[0, 1]` so 4
// decimals of price granularity (tick `0.0001`) and 2 decimals of size
// granularity (lot `0.01`) are conservative starting values; refine when
// real venue payloads land.
pub const OUTCOME_PRICE_DECIMALS: u32 = 4;
pub const OUTCOME_SIZE_DECIMALS: u32 = 2;

/// Parse outcome instrument definitions from Hyperliquid `outcomeMeta` response.
///
/// Each [`OutcomeMarket`] yields two definitions, one per side (`0` and `1`),
/// modeled as binary outcome side tokens. The Nautilus internal symbol uses
/// the form `{outcome_index}-{YES|NO}-OUTCOME` (symmetric with `-PERP` /
/// `-SPOT`), and the wire `raw_symbol` uses the spot-coin form
/// (`#<encoding>`) which is what `l2Book`, `trades`, and `bbo` subscriptions
/// accept.
///
/// Expiry is read from the market's own description when it carries
/// `class:priceBinary`; for outcomes that point at a parent question (`other`
/// or `index:N`), the expiry is inherited from that question's description.
///
/// `side_name` is taken from the venue's `sideSpecs` entry when present,
/// otherwise it falls back to the canonical HIP-4 labels (`"Yes"` / `"No"`).
pub fn parse_outcome_instruments(
    meta: &OutcomeMeta,
) -> Result<Vec<HyperliquidInstrumentDef>, String> {
    let mut defs = Vec::with_capacity(meta.outcomes.len() * 2);

    for market in &meta.outcomes {
        for side in 0u8..=1u8 {
            defs.push(build_outcome_def(market, side, meta)?);
        }
    }

    Ok(defs)
}

fn build_outcome_def(
    market: &OutcomeMarket,
    side: u8,
    meta: &OutcomeMeta,
) -> Result<HyperliquidInstrumentDef, String> {
    let outcome_index = market.outcome;
    let asset_id = HyperliquidAssetId::outcome(outcome_index, side);
    let encoding = asset_id.outcome_encoding().ok_or_else(|| {
        format!("Invalid outcome encoding for outcome={outcome_index} side={side}")
    })?;

    let token = format!("+{encoding}");
    let coin = format!("#{encoding}");
    let symbol = format_outcome_nautilus_symbol(outcome_index, side);

    let side_name = market
        .side_specs
        .get(usize::from(side))
        .map(|spec| Ustr::from(spec.name.as_str()))
        .or_else(|| Some(Ustr::from(default_side_label(side))));

    let description = if market.description.is_empty() {
        None
    } else {
        Some(Ustr::from(market.description.as_str()))
    };

    let parent_question = meta.parent_question(outcome_index);
    let expiration_ns = resolve_outcome_expiration_ns(market, meta);

    let info = build_outcome_info(
        market,
        side,
        encoding,
        asset_id.to_raw(),
        side_name.as_ref().map(Ustr::as_str),
        parent_question,
    );

    let outcome_metadata = HyperliquidOutcomeMetadata {
        outcome_index,
        outcome_side: side,
        market_name: Ustr::from(market.name.as_str()),
        side_name,
        description,
        activation_ns: UnixNanos::default(),
        expiration_ns,
        info: Some(info),
    };

    Ok(HyperliquidInstrumentDef {
        symbol: Ustr::from(symbol.as_str()),
        raw_symbol: Ustr::from(coin.as_str()),
        base: Ustr::from(token.as_str()),
        quote: "USDH".into(),
        settlement: None,
        market_type: HyperliquidMarketType::Outcome,
        asset_index: asset_id.to_raw(),
        price_decimals: OUTCOME_PRICE_DECIMALS,
        size_decimals: OUTCOME_SIZE_DECIMALS,
        tick_size: pow10_neg(OUTCOME_PRICE_DECIMALS),
        lot_size: pow10_neg(OUTCOME_SIZE_DECIMALS),
        max_leverage: None,
        only_isolated: false,
        is_hip3: false,
        active: true,
        outcome: Some(outcome_metadata),
        raw_data: serde_json::to_string(market).unwrap_or_default(),
    })
}

// Side `0` is Yes, `1` is No; matches the HIP-4 encoding convention.
fn default_side_label(side: u8) -> &'static str {
    if side == 0 { "Yes" } else { "No" }
}

// Splits a `key:value|key:value|...` description into snake_case keyed entries
// keyed on the venue's camelCase keys lowered to snake_case. Empty descriptions
// produce an empty iterator.
fn parse_description_fields(description: &str) -> impl Iterator<Item = (String, String)> + '_ {
    description
        .split('|')
        .filter_map(|piece| piece.split_once(':'))
        .map(|(key, value)| (camel_to_snake(key.trim()), value.trim().to_string()))
}

fn camel_to_snake(s: &str) -> String {
    let mut out = String::with_capacity(s.len() + 4);
    for (i, ch) in s.char_indices() {
        if ch.is_ascii_uppercase() {
            if i > 0 {
                out.push('_');
            }
            out.push(ch.to_ascii_lowercase());
        } else {
            out.push(ch);
        }
    }
    out
}

fn build_outcome_info(
    market: &OutcomeMarket,
    side: u8,
    encoding: u32,
    asset_id_raw: u32,
    side_name: Option<&str>,
    parent_question: Option<&OutcomeQuestion>,
) -> Params {
    let mut info = Params::new();

    info.insert("outcome_index".into(), json!(market.outcome));
    info.insert("outcome_side".into(), json!(side));
    if let Some(name) = side_name {
        info.insert("side_name".into(), Value::String(name.to_string()));
    }
    info.insert("encoding".into(), json!(encoding));
    info.insert("asset_id".into(), json!(asset_id_raw));
    info.insert("market_name".into(), Value::String(market.name.clone()));

    // Direct binary outcomes (`class:priceBinary|...`) carry the full metadata
    // on the market description. Named-outcome descriptions are sentinels
    // (`index:N` / `other`) that just point at the parent question.
    for (key, value) in parse_description_fields(&market.description) {
        match key.as_str() {
            "index" => {
                if let Ok(named) = value.parse::<u32>() {
                    info.insert("named_index".into(), json!(named));
                }
            }
            "other" => {
                info.insert("is_fallback".into(), json!(true));
            }
            _ => {
                info.insert(key, Value::String(value));
            }
        }
    }

    // The market description for named outcomes is literally the keyless
    // sentinel `other`; capture it explicitly so consumers don't need to
    // inspect the raw description.
    if market.description.trim() == "other" {
        info.insert("is_fallback".into(), json!(true));
    }

    if let Some(question) = parent_question {
        info.insert("question".into(), json!(question.question));
        info.insert("question_name".into(), Value::String(question.name.clone()));
        for (key, value) in parse_description_fields(&question.description) {
            let prefixed = format!("question_{key}");
            info.insert(prefixed, Value::String(value));
        }
    }

    info
}

fn pow10_neg(decimals: u32) -> Decimal {
    if decimals == 0 {
        return Decimal::ONE;
    }

    // Build 1 / 10^decimals using integer arithmetic
    Decimal::from_i128_with_scale(1, decimals)
}

// Direct binary outcomes carry `expiry:` in their own description. Named
// outcomes (`index:N`) and the `other` fallback inherit expiry from the
// parent question. Returns zero when no expiry can be located.
fn resolve_outcome_expiration_ns(market: &OutcomeMarket, meta: &OutcomeMeta) -> UnixNanos {
    if let Some(ns) = parse_expiry_from_description(&market.description) {
        return ns;
    }

    meta.parent_question(market.outcome)
        .and_then(|q| parse_expiry_from_description(&q.description))
        .unwrap_or_default()
}

fn parse_expiry_from_description(description: &str) -> Option<UnixNanos> {
    description
        .split('|')
        .filter_map(|piece| piece.split_once(':'))
        .find_map(|(key, value)| (key == "expiry").then_some(value))
        .and_then(parse_outcome_expiry_ns)
}

// Parses a Hyperliquid outcome expiry stamp `YYYYMMDD-HHMM` (UTC) to UnixNanos.
fn parse_outcome_expiry_ns(s: &str) -> Option<UnixNanos> {
    let (date_part, time_part) = s.split_once('-')?;
    if date_part.len() != 8 || time_part.len() != 4 {
        return None;
    }

    let year: i32 = date_part[0..4].parse().ok()?;
    let month: u32 = date_part[4..6].parse().ok()?;
    let day: u32 = date_part[6..8].parse().ok()?;
    let hour: u32 = time_part[0..2].parse().ok()?;
    let minute: u32 = time_part[2..4].parse().ok()?;

    let datetime = format!("{year:04}-{month:02}-{day:02}T{hour:02}:{minute:02}:00Z")
        .parse::<Timestamp>()
        .ok()?;
    u64::try_from(datetime.as_nanosecond())
        .ok()
        .map(UnixNanos::from)
}

/// Settlement state for a single HIP-4 outcome side token.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OutcomeSettlement {
    /// Outcome index from `outcomeMeta`.
    pub outcome_index: u32,
    /// Side token (`0` or `1`).
    pub outcome_side: u8,
    /// Final settlement value: `1` for the winning side, `0` for losing sides.
    pub final_value: u8,
}

/// Derives per-side settlement values from an `outcomeMeta` snapshot.
///
/// Returns one [`OutcomeSettlement`] for every side of every outcome whose
/// resolution can be inferred from the snapshot:
///
/// - For each question with non-empty `settled_named_outcomes`, every named
///   outcome and the fallback are emitted: the winning named outcomes get
///   `Yes -> 1, No -> 0`, every other named outcome and the fallback get
///   `Yes -> 0, No -> 1`.
/// - Standalone outcomes (not referenced by any question) are skipped because
///   the venue does not expose their resolution in `outcomeMeta`. They will
///   need a separate signal (status flag, fill, or position-state event).
///
/// Outcomes referenced by a question that has not yet settled are also
/// skipped. This lets a caller poll `outcomeMeta` and emit settlement events
/// when entries first appear in the result.
#[must_use]
pub fn derive_outcome_settlements(meta: &OutcomeMeta) -> Vec<OutcomeSettlement> {
    let mut settlements = Vec::new();

    for question in &meta.questions {
        if question.settled_named_outcomes.is_empty() {
            continue;
        }

        let losing_sides_won = |outcome_index: u32| -> [OutcomeSettlement; 2] {
            // Named outcome did not win; Yes side -> 0, No side -> 1.
            [
                OutcomeSettlement {
                    outcome_index,
                    outcome_side: 0,
                    final_value: 0,
                },
                OutcomeSettlement {
                    outcome_index,
                    outcome_side: 1,
                    final_value: 1,
                },
            ]
        };

        let winning_sides = |outcome_index: u32| -> [OutcomeSettlement; 2] {
            // Named outcome won; Yes side -> 1, No side -> 0.
            [
                OutcomeSettlement {
                    outcome_index,
                    outcome_side: 0,
                    final_value: 1,
                },
                OutcomeSettlement {
                    outcome_index,
                    outcome_side: 1,
                    final_value: 0,
                },
            ]
        };

        for outcome_index in &question.named_outcomes {
            if question.settled_named_outcomes.contains(outcome_index) {
                settlements.extend(winning_sides(*outcome_index));
            } else {
                settlements.extend(losing_sides_won(*outcome_index));
            }
        }

        // The fallback is the "no named outcome resolved" branch; it loses
        // whenever any named outcome won.
        if let Some(fallback) = question.fallback_outcome {
            settlements.extend(losing_sides_won(fallback));
        }
    }

    settlements
}

pub fn get_currency(code: &str) -> Currency {
    Currency::try_from_str(code).unwrap_or_else(|| {
        let currency = Currency::new(code, 8, 0, code, CurrencyType::Crypto);
        if let Err(e) = Currency::register(currency, false) {
            log::error!("Failed to register currency '{code}': {e}");
        }
        currency
    })
}

/// Returns the HIP-4 outcome settlement currency, registering it on first call.
///
/// Outcome markets settle in USDH (token index 360 on the `USDH/USDC` spot pair
/// `@230`), not USDC. The registration is explicit so the precision is
/// deterministic rather than dependent on whichever caller first triggers
/// `get_currency`'s auto-register path.
pub fn get_usdh_currency() -> Currency {
    Currency::try_from_str("USDH").unwrap_or_else(|| {
        let currency = Currency::new("USDH", 8, 0, "Hyperliquid USD", CurrencyType::Crypto);
        if let Err(e) = Currency::register(currency, false) {
            log::error!("Failed to register USDH currency: {e}");
        }
        currency
    })
}

/// Resolves the commission currency for a fill given the venue's `feeToken` field.
///
/// HIP-4 outcome fills echo the side token (e.g. `+50`) as `feeToken` even when
/// the fee is zero. The side token is not a Nautilus currency and emitting it as
/// the commission currency would leak into `OrderFilled` events and persistence;
/// for outcome side tokens the instrument's quote currency is always used, even
/// when another adapter path (such as spot-balance parsing) has registered the
/// side token in the global registry. Non-zero side-token fees error: the venue
/// does not denominate fees in side tokens. Other unknown tokens fall back to
/// the instrument's quote currency only when the fee is zero.
///
/// # Errors
///
/// Returns an error when an outcome side token carries a non-zero fee, or when
/// `fee_token` cannot be resolved and `fee_amount` is non-zero.
pub fn resolve_fee_currency(
    fee_token: &str,
    fee_amount: Decimal,
    instrument: &dyn Instrument,
) -> anyhow::Result<Currency> {
    if is_outcome_side_token(fee_token) {
        if !fee_amount.is_zero() {
            anyhow::bail!(
                "Outcome side token '{fee_token}' carried a non-zero fee {fee_amount}; \
                 venue does not denominate fees in side tokens",
            );
        }
        return Ok(instrument.quote_currency());
    }

    if let Some(currency) = Currency::try_from_str(fee_token) {
        return Ok(currency);
    }

    if fee_amount.is_zero() {
        let fallback = instrument.quote_currency();
        log::debug!(
            "Unregistered fee token '{fee_token}' on zero-fee fill for {}; using {fallback} as fallback",
            instrument.id(),
        );
        return Ok(fallback);
    }

    anyhow::bail!("Unknown fee token '{fee_token}' with non-zero fee {fee_amount}")
}

fn is_outcome_side_token(symbol: &str) -> bool {
    let Some(rest) = symbol.strip_prefix('+') else {
        return false;
    };
    !rest.is_empty() && rest.bytes().all(|b| b.is_ascii_digit())
}

// Hyperliquid documents a venue-wide minimum order notional: $10 for perps,
// and 10 quote_token for spot.
// https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/error-responses
const HYPERLIQUID_MIN_ORDER_NOTIONAL: Decimal = Decimal::TEN;

/// Returns `info` with the venue asset index added under [`ASSET_INDEX_INFO_KEY`].
///
/// Hyperliquid signs orders with the numeric asset index rather than the symbol,
/// and `InstrumentAny` is the only instrument shape published on the message bus.
/// Carrying the index here lets the execution client register a market discovered
/// after its own bootstrap without refetching venue metadata.
fn info_with_asset_index(info: Option<Params>, asset_index: u32) -> Params {
    let mut info = info.unwrap_or_default();
    info.insert(ASSET_INDEX_INFO_KEY.to_string(), json!(asset_index));
    info
}

/// Converts a single Hyperliquid instrument definition into a Nautilus `InstrumentAny`.
///
/// Returns `None` if the conversion fails (e.g., unsupported market type).
///
/// # Panics
///
/// Panics if the constructed instrument fails validation.
#[must_use]
pub fn create_instrument_from_def(
    def: &HyperliquidInstrumentDef,
    ts_init: UnixNanos,
) -> Option<InstrumentAny> {
    let symbol = Symbol::new(def.symbol);
    let venue = *HYPERLIQUID_VENUE;
    let instrument_id = InstrumentId::new(symbol, venue);

    // Use the raw_symbol from the definition which is format-specific:
    // - Perps: base currency (e.g., "BTC")
    // - Spot PURR: slash format (e.g., "PURR/USDC")
    // - Spot others: @{index} format (e.g., "@107")
    let raw_symbol = Symbol::new(def.raw_symbol);
    let price_increment = Price::from(def.tick_size.to_string());
    let size_increment = Quantity::from(def.lot_size.to_string());

    match def.market_type {
        HyperliquidMarketType::Spot => {
            let base_currency = get_currency(&def.base);
            let quote_currency = get_currency(&def.quote);
            let min_notional = Some(min_order_notional(quote_currency)?);
            let info = serde_json::from_str::<Params>(&def.raw_data).ok();
            let info = info_with_asset_index(info, def.asset_index);

            Some(InstrumentAny::CurrencyPair(
                CurrencyPair::builder()
                    .instrument_id(instrument_id)
                    .raw_symbol(raw_symbol)
                    .base_currency(base_currency)
                    .quote_currency(quote_currency)
                    .price_precision(def.price_decimals as u8)
                    .size_precision(def.size_decimals as u8)
                    .price_increment(price_increment)
                    .size_increment(size_increment)
                    .maybe_min_notional(min_notional)
                    .info(info)
                    // Identical to ts_init for now
                    .ts_event(ts_init)
                    .ts_init(ts_init)
                    .build()
                    .unwrap(),
            ))
        }
        HyperliquidMarketType::Perp => {
            let base_currency = get_currency(&def.base);
            let quote_currency = get_currency(&def.quote);
            let settlement_code = def
                .settlement
                .as_ref()
                .map_or(DEFAULT_PERP_SETTLEMENT_CURRENCY, Ustr::as_str);
            let settlement_currency = if settlement_code == "USDH" {
                get_usdh_currency()
            } else {
                get_currency(settlement_code)
            };
            let min_notional = Some(min_order_notional(quote_currency)?);

            Some(InstrumentAny::CryptoPerpetual(
                CryptoPerpetual::builder()
                    .instrument_id(instrument_id)
                    .raw_symbol(raw_symbol)
                    .base_currency(base_currency)
                    .quote_currency(quote_currency)
                    .settlement_currency(settlement_currency)
                    .is_inverse(false)
                    .price_precision(def.price_decimals as u8)
                    .size_precision(def.size_decimals as u8)
                    .price_increment(price_increment)
                    .size_increment(size_increment)
                    .maybe_min_notional(min_notional)
                    .info(info_with_asset_index(None, def.asset_index))
                    // Identical to ts_init for now
                    .ts_event(ts_init)
                    .ts_init(ts_init)
                    .build()
                    .unwrap(),
            ))
        }
        HyperliquidMarketType::Outcome => {
            let outcome = def.outcome.as_ref()?;
            let currency = get_usdh_currency();

            Some(InstrumentAny::BinaryOption(
                BinaryOption::builder()
                    .instrument_id(instrument_id)
                    .raw_symbol(raw_symbol)
                    .asset_class(AssetClass::Alternative)
                    .currency(currency)
                    .activation_ns(outcome.activation_ns)
                    .expiration_ns(outcome.expiration_ns)
                    .price_precision(def.price_decimals as u8)
                    .size_precision(def.size_decimals as u8)
                    .price_increment(price_increment)
                    .size_increment(size_increment)
                    .maybe_outcome(outcome.side_name)
                    .maybe_description(outcome.description)
                    .info(info_with_asset_index(outcome.info.clone(), def.asset_index))
                    .ts_event(ts_init)
                    .ts_init(ts_init)
                    .build()
                    .unwrap(),
            ))
        }
    }
}

fn min_order_notional(currency: Currency) -> Option<Money> {
    Money::from_decimal(HYPERLIQUID_MIN_ORDER_NOTIONAL, currency).ok()
}

/// Convert a collection of Hyperliquid instrument definitions into Nautilus instruments,
/// discarding any definitions that fail to convert.
#[must_use]
pub fn instruments_from_defs(
    defs: &[HyperliquidInstrumentDef],
    ts_init: UnixNanos,
) -> Vec<InstrumentAny> {
    defs.iter()
        .filter_map(|def| create_instrument_from_def(def, ts_init))
        .collect()
}

/// Convert owned definitions into Nautilus instruments, consuming the input vector.
#[must_use]
pub fn instruments_from_defs_owned(
    defs: Vec<HyperliquidInstrumentDef>,
    ts_init: UnixNanos,
) -> Vec<InstrumentAny> {
    defs.into_iter()
        .filter_map(|def| create_instrument_from_def(&def, ts_init))
        .collect()
}

fn parse_fill_side(side: &HyperliquidSide) -> OrderSide {
    match side {
        HyperliquidSide::Buy => OrderSide::Buy,
        HyperliquidSide::Sell => OrderSide::Sell,
    }
}

/// Parse WebSocket order data to OrderStatusReport.
///
/// # Errors
///
/// Returns an error if required fields are missing or invalid.
pub fn parse_order_status_report_from_ws(
    order_data: &WsOrderData,
    instrument: &dyn Instrument,
    account_id: AccountId,
    ts_init: UnixNanos,
) -> anyhow::Result<OrderStatusReport> {
    parse_order_status_report_from_basic(
        &order_data.order,
        &order_data.status,
        instrument,
        account_id,
        ts_init,
    )
}

/// Parse basic order data to OrderStatusReport.
///
/// # Errors
///
/// Returns an error if required fields are missing or invalid.
pub fn parse_order_status_report_from_basic(
    order: &WsBasicOrderData,
    status: &HyperliquidOrderStatusEnum,
    instrument: &dyn Instrument,
    account_id: AccountId,
    ts_init: UnixNanos,
) -> anyhow::Result<OrderStatusReport> {
    let instrument_id = instrument.id();
    let venue_order_id = VenueOrderId::new(order.oid.to_string());
    let order_side = OrderSide::from(order.side);

    let is_conditional = is_conditional_order_data(order.trigger_px, order.tpsl.as_ref());
    let order_type = if is_conditional {
        match (order.is_market, order.tpsl.as_ref()) {
            (Some(is_market), Some(tpsl)) => parse_trigger_order_type(is_market, tpsl),
            (None, Some(tpsl)) => parse_trigger_order_type(false, tpsl),
            _ => OrderType::Limit,
        }
    } else {
        OrderType::Limit
    };

    let time_in_force = order
        .tif
        .map_or(TimeInForce::Gtc, hyperliquid_time_in_force_to_nautilus);
    let order_status = OrderStatus::from(*status);

    let price_precision = instrument.price_precision();
    let size_precision = instrument.size_precision();

    let orig_sz = order.orig_sz;
    let current_sz = order.sz;

    let quantity = Quantity::from_decimal_dp(orig_sz.abs(), size_precision)
        .map_err(|e| anyhow::anyhow!("Failed to create quantity from orig_sz: {e}"))?;
    let filled_sz = orig_sz.abs() - current_sz.abs();
    let filled_qty = Quantity::from_decimal_dp(filled_sz, size_precision)
        .map_err(|e| anyhow::anyhow!("Failed to create quantity from filled_sz: {e}"))?;

    let ts_accepted = UnixNanos::from(order.timestamp * 1_000_000);
    let ts_last = ts_accepted;
    let report_id = UUID4::new();

    let mut report = OrderStatusReport::new(
        account_id,
        instrument_id,
        None, // client_order_id - will be set if present
        venue_order_id,
        order_side.into(),
        order_type,
        time_in_force,
        order_status,
        quantity,
        filled_qty,
        ts_accepted,
        ts_last,
        ts_init,
        Some(report_id),
    );

    // Add client order ID if present
    if let Some(cloid) = &order.cloid {
        report = report.with_client_order_id(ClientOrderId::new(cloid.as_str()));
    }

    if matches!(order.tif, Some(HyperliquidTimeInForce::Alo)) {
        report = report.with_post_only(true);
    }

    if let Some(reduce_only) = order.reduce_only {
        report = report.with_reduce_only(reduce_only);
    }

    if let Some(reason) = status.rejection_reason() {
        report = report.with_cancel_reason(reason.to_string());
    }

    // Only set price for non-filled orders. For filled orders, the limit price is not
    // the execution price, and setting it would cause bogus inferred fills to be created
    // during reconciliation. Real fills arrive via the userEvents WebSocket channel.
    if !matches!(
        order_status,
        OrderStatus::Filled | OrderStatus::PartiallyFilled
    ) {
        let price = Price::from_decimal_dp(order.limit_px, price_precision)
            .map_err(|e| anyhow::anyhow!("Failed to create price from limit_px: {e}"))?;
        report = report.with_price(price);
    }

    if is_conditional && let Some(trigger_px) = order.trigger_px {
        let trigger_price = Price::from_decimal_dp(trigger_px, price_precision)
            .map_err(|e| anyhow::anyhow!("Failed to create trigger price: {e}"))?;
        report = report
            .with_trigger_price(trigger_price)
            .with_trigger_type(TriggerType::Default);
    }

    Ok(report)
}

/// Parses a `recentTrades` info entry into a [`TradeTick`].
///
/// Mirrors the field mapping of the WebSocket trade parser
/// [`parse_ws_trade_tick`](crate::websocket::parse::parse_ws_trade_tick): both the
/// `trades` channel and the `recentTrades` endpoint carry the same
/// `px`/`sz`/`side`/`time`/`tid` fields. For this historical snapshot `ts_init` is
/// set to the trade's `ts_event` (venue time), matching the other request
/// converters so the data engine's window trimming keeps bounded requests.
///
/// # Errors
///
/// Returns an error if the price, size, trade identifier, or timestamp is invalid.
pub fn parse_recent_trade(
    trade: &HyperliquidRecentTrade,
    instrument: &InstrumentAny,
) -> anyhow::Result<TradeTick> {
    let price = Price::from_decimal_dp(trade.px, instrument.price_precision())
        .with_context(|| format!("Failed to create price from '{}'", trade.px))?;

    let size = Quantity::from_decimal_dp(trade.sz.abs(), instrument.size_precision())
        .with_context(|| format!("Failed to create size from '{}'", trade.sz))?;

    let aggressor = AggressorSide::from(trade.side);
    let trade_id = TradeId::new_checked(trade.tid.to_string())
        .context("invalid trade identifier in Hyperliquid recent trade")?;
    let ts_event = millis_to_nanos(trade.time)?;

    TradeTick::new_checked(
        instrument.id(),
        price,
        size,
        aggressor,
        trade_id,
        ts_event,
        ts_event,
    )
    .context("failed to construct TradeTick from Hyperliquid recent trade")
}

/// Parses a `recentTrades` info entry into a complete public Hyperliquid trade.
pub fn parse_recent_public_trade(
    trade: &HyperliquidRecentTrade,
    instrument: &InstrumentAny,
) -> anyhow::Result<HyperliquidPublicTrade> {
    let price = Price::from_decimal_dp(trade.px, instrument.price_precision())
        .with_context(|| format!("Failed to create price from '{}'", trade.px))?;
    let size = Quantity::from_decimal_dp(trade.sz.abs(), instrument.size_precision())
        .with_context(|| format!("Failed to create size from '{}'", trade.sz))?;
    let ts_event = millis_to_nanos(trade.time)?;

    Ok(HyperliquidPublicTrade::new(
        instrument.id(),
        price,
        size,
        AggressorSide::from(trade.side),
        trade.tid.to_string(),
        trade.users[0].clone(),
        trade.users[1].clone(),
        trade.hash.clone(),
        ts_event,
        ts_event,
    ))
}

/// Constrains a recent public-trade snapshot to a requested time window.
///
/// The `recentTrades` endpoint only provides bounded recent coverage, so a
/// request whose end precedes the snapshot floor cannot be fulfilled.
pub fn filter_recent_public_trades(
    trades: Vec<HyperliquidPublicTrade>,
    start: Option<UnixNanos>,
    end: Option<UnixNanos>,
    limit: Option<usize>,
    instrument_id: InstrumentId,
) -> Vec<HyperliquidPublicTrade> {
    let Some(floor) = trades.first().map(|trade| trade.ts_event) else {
        return Vec::new();
    };

    if let Some(end) = end
        && end < floor
    {
        log::warn!(
            "Recent public trades for {instrument_id} are entirely older than the requested window; \
             snapshot only covers back to {}",
            unix_nanos_to_iso8601(floor),
        );
        return Vec::new();
    }

    if let Some(start) = start
        && start < floor
    {
        log::warn!(
            "Recent public trades for {instrument_id} only cover back to {}; \
             the requested start is earlier and cannot be served",
            unix_nanos_to_iso8601(floor),
        );
    }

    let mut filtered: Vec<HyperliquidPublicTrade> = trades
        .into_iter()
        .filter(|trade| start.is_none_or(|value| trade.ts_event >= value))
        .filter(|trade| end.is_none_or(|value| trade.ts_event <= value))
        .collect();

    if let Some(limit) = limit
        && filtered.len() > limit
    {
        // Preserve ascending event-time order while retaining the newest data.
        filtered.drain(0..filtered.len() - limit);
    }

    filtered
}

/// Parse Hyperliquid fill to FillReport.
///
/// # Errors
///
/// Returns an error if required fields are missing or invalid.
pub fn parse_fill_report(
    fill: &HyperliquidFill,
    instrument: &dyn Instrument,
    account_id: AccountId,
    ts_init: UnixNanos,
) -> anyhow::Result<FillReport> {
    let instrument_id = instrument.id();
    let venue_order_id = VenueOrderId::new(fill.oid.to_string());

    if matches!(fill.dir, HyperliquidFillDirection::AutoDeleveraging) {
        log::warn!(
            "Auto-deleveraging fill: {instrument_id} oid={} px={} sz={}",
            fill.oid,
            fill.px,
            fill.sz,
        );
    }

    let trade_id = make_fill_trade_id(
        &fill.hash,
        fill.oid,
        fill.px,
        fill.sz,
        fill.time,
        fill.start_position,
    );
    let order_side = parse_fill_side(&fill.side);

    let price_precision = instrument.price_precision();
    let size_precision = instrument.size_precision();

    let last_px = Price::from_decimal_dp(fill.px, price_precision)
        .map_err(|e| anyhow::anyhow!("Failed to create price from fill px: {e}"))?;
    let last_qty = Quantity::from_decimal_dp(fill.sz.abs(), size_precision)
        .map_err(|e| anyhow::anyhow!("Failed to create quantity from fill sz: {e}"))?;

    let fee_amount = fill.fee;

    let fee_currency = resolve_fee_currency(fill.fee_token.as_str(), fee_amount, instrument)?;
    let commission = Money::from_decimal(fee_amount, fee_currency)
        .map_err(|e| anyhow::anyhow!("Failed to create commission from fee: {e}"))?;

    // Determine liquidity side based on 'crossed' flag
    let liquidity_side = if fill.crossed {
        LiquiditySide::Taker
    } else {
        LiquiditySide::Maker
    };

    let ts_event = UnixNanos::from(fill.time * 1_000_000);
    let report_id = UUID4::new();

    let report = FillReport::new(
        account_id,
        instrument_id,
        venue_order_id,
        trade_id,
        order_side,
        last_qty,
        last_px,
        commission,
        liquidity_side,
        None, // client_order_id - to be linked by execution engine
        None, // venue_position_id
        ts_event,
        ts_init,
        Some(report_id),
    );

    Ok(report)
}

/// Parse position data from clearinghouse state to PositionStatusReport.
///
/// # Errors
///
/// Returns an error if required fields are missing or invalid.
pub fn parse_position_status_report(
    position_data: &serde_json::Value,
    instrument: &dyn Instrument,
    account_id: AccountId,
    ts_init: UnixNanos,
) -> anyhow::Result<PositionStatusReport> {
    // Deserialize the position data
    let asset_position: AssetPosition = serde_json::from_value(position_data.clone())
        .context("failed to deserialize AssetPosition")?;

    let position = &asset_position.position;
    let instrument_id = instrument.id();

    // Determine position side based on size (szi)
    let (position_side, quantity_value) = if position.szi.is_zero() {
        (PositionSide::Flat, Decimal::ZERO)
    } else if position.szi.is_sign_positive() {
        (PositionSide::Long, position.szi)
    } else {
        (PositionSide::Short, position.szi.abs())
    };

    let quantity = Quantity::from_decimal_dp(quantity_value, instrument.size_precision())
        .context("failed to create quantity from decimal")?;
    let report_id = UUID4::new();
    let ts_last = ts_init;
    let avg_px_open = position.entry_px;

    // Hyperliquid uses netting (one position per instrument), not hedging
    Ok(PositionStatusReport::new(
        account_id,
        instrument_id,
        position_side,
        quantity,
        ts_last,
        ts_init,
        Some(report_id),
        None, // No venue_position_id for netting positions
        avg_px_open,
    ))
}

/// Parse a spot token balance into a [`PositionStatusReport`] against the spot instrument.
///
/// Spot holdings are always Long (Hyperliquid spot has no short exposure). The average
/// entry price is derived from `entry_ntl / total` when both are non-zero; otherwise it
/// is omitted.
///
/// # Errors
///
/// Returns an error if the quantity cannot be constructed at the instrument's precision.
pub fn parse_spot_position_status_report(
    balance: &SpotBalance,
    instrument: &dyn Instrument,
    account_id: AccountId,
    ts_init: UnixNanos,
) -> anyhow::Result<PositionStatusReport> {
    let (position_side, quantity_value) = if balance.total.is_zero() {
        (PositionSide::Flat, Decimal::ZERO)
    } else {
        (PositionSide::Long, balance.total)
    };

    let quantity = Quantity::from_decimal_dp(quantity_value, instrument.size_precision())
        .context("failed to create spot quantity from decimal")?;

    Ok(PositionStatusReport::new(
        account_id,
        instrument.id(),
        position_side,
        quantity,
        ts_init,
        ts_init,
        Some(UUID4::new()),
        None,
        balance.avg_entry_px(),
    ))
}

#[cfg(test)]
mod tests {
    use rstest::rstest;
    use rust_decimal_macros::dec;

    use super::{
        super::models::{
            HyperliquidL2Book, OutcomeMarket, OutcomeMeta, OutcomeQuestion, OutcomeSideSpec,
            PerpAsset, SpotPair, SpotToken,
        },
        *,
    };

    #[rstest]
    fn test_parse_fill_side() {
        assert_eq!(parse_fill_side(&HyperliquidSide::Buy), OrderSide::Buy,);
        assert_eq!(parse_fill_side(&HyperliquidSide::Sell), OrderSide::Sell,);
    }

    #[rstest]
    fn test_pow10_neg() {
        assert_eq!(pow10_neg(0), dec!(1));
        assert_eq!(pow10_neg(1), dec!(0.1));
        assert_eq!(pow10_neg(5), dec!(0.00001));
    }

    #[rstest]
    fn test_parse_perp_instruments() {
        let meta = PerpMeta {
            universe: vec![
                PerpAsset {
                    name: "BTC".to_string(),
                    sz_decimals: 5,
                    max_leverage: Some(50),
                    ..Default::default()
                },
                PerpAsset {
                    name: "DELIST".to_string(),
                    sz_decimals: 3,
                    max_leverage: Some(10),
                    only_isolated: Some(true),
                    is_delisted: Some(true),
                    ..Default::default()
                },
            ],
            margin_tables: vec![],
            collateral_token: None,
        };

        let defs = parse_perp_instruments(&meta, 0).unwrap();

        // Should have both BTC and DELIST (delisted instruments are included for historical data)
        assert_eq!(defs.len(), 2);

        let btc = &defs[0];
        assert_eq!(btc.symbol, "BTC-USD-PERP");
        assert_eq!(btc.base, "BTC");
        assert_eq!(btc.quote, "USD");
        assert_eq!(btc.settlement.as_ref().unwrap(), "USDC");
        assert_eq!(btc.market_type, HyperliquidMarketType::Perp);
        assert_eq!(btc.price_decimals, 1); // 6 - 5 = 1
        assert_eq!(btc.size_decimals, 5);
        assert_eq!(btc.tick_size, dec!(0.1));
        assert_eq!(btc.lot_size, dec!(0.00001));
        assert_eq!(btc.max_leverage, Some(50));
        assert!(!btc.only_isolated);
        assert!(btc.active);

        let delist = &defs[1];
        assert_eq!(delist.symbol, "DELIST-USD-PERP");
        assert_eq!(delist.base, "DELIST");
        assert!(!delist.active); // Delisted instruments are marked as inactive
    }

    use crate::common::testing::load_test_data;

    #[rstest]
    fn test_parse_perp_instruments_from_real_data() {
        let meta: PerpMeta = load_test_data("http_meta_perp_sample.json");

        let defs = parse_perp_instruments(&meta, 0).unwrap();

        // Should have 3 instruments (BTC, ETH, ATOM)
        assert_eq!(defs.len(), 3);

        // Validate BTC
        let btc = &defs[0];
        assert_eq!(btc.symbol, "BTC-USD-PERP");
        assert_eq!(btc.base, "BTC");
        assert_eq!(btc.quote, "USD");
        assert_eq!(btc.settlement.as_ref().unwrap(), "USDC");
        assert_eq!(btc.market_type, HyperliquidMarketType::Perp);
        assert_eq!(btc.size_decimals, 5);
        assert_eq!(btc.max_leverage, Some(40));
        assert!(btc.active);

        // Validate ETH
        let eth = &defs[1];
        assert_eq!(eth.symbol, "ETH-USD-PERP");
        assert_eq!(eth.base, "ETH");
        assert_eq!(eth.size_decimals, 4);
        assert_eq!(eth.max_leverage, Some(25));

        // Validate ATOM
        let atom = &defs[2];
        assert_eq!(atom.symbol, "ATOM-USD-PERP");
        assert_eq!(atom.base, "ATOM");
        assert_eq!(atom.size_decimals, 2);
        assert_eq!(atom.max_leverage, Some(5));
    }

    #[rstest]
    fn test_parse_recent_trade() {
        let meta: PerpMeta = load_test_data("http_meta_perp_sample.json");
        let defs = parse_perp_instruments(&meta, 0).unwrap();
        let instrument = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();

        let trade = HyperliquidRecentTrade {
            coin: Ustr::from("BTC"),
            side: HyperliquidSide::Sell,
            px: dec!(50000.0),
            sz: dec!(0.5),
            hash: "0xhash".to_string(),
            time: 1_769_916_000_000,
            tid: 987_654_321,
            users: ["0xbuyer".to_string(), "0xseller".to_string()],
        };

        let tick = parse_recent_trade(&trade, &instrument).unwrap();

        assert_eq!(tick.instrument_id, instrument.id());
        assert_eq!(tick.price.as_decimal(), dec!(50000));
        assert_eq!(tick.size.as_decimal(), dec!(0.5));
        assert_eq!(tick.aggressor_side, AggressorSide::Sell);
        assert_eq!(tick.trade_id.to_string(), "987654321");
        assert_eq!(
            tick.ts_event,
            UnixNanos::from(1_769_916_000_000 * 1_000_000)
        );
        // Historical trades carry ts_init == ts_event so the engine's window
        // trimming (by ts_init) keeps bounded requests.
        assert_eq!(tick.ts_init, tick.ts_event);
    }

    #[rstest]
    fn test_recent_trade_rejects_invalid_price() {
        // Price is now a Decimal field, so an invalid value is rejected at
        // deserialization rather than by parse_recent_trade.
        let json = r#"{"coin":"BTC","side":"B","px":"not-a-number","sz":"0.5","time":1769916000000,"tid":1}"#;
        assert!(serde_json::from_str::<HyperliquidRecentTrade>(json).is_err());
    }

    #[rstest]
    fn test_create_instrument_from_def_perp_sets_min_notional() {
        let meta: PerpMeta = load_test_data("http_meta_perp_sample.json");
        let defs = parse_perp_instruments(&meta, 0).unwrap();

        let instrument = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();

        match instrument {
            InstrumentAny::CryptoPerpetual(perp) => {
                let min_notional = perp.min_notional.unwrap();
                assert_eq!(min_notional.currency, Currency::USD());
                assert_eq!(min_notional.as_decimal(), dec!(10));
                assert_eq!(perp.settlement_currency.code, "USDC");
            }
            other => panic!("Expected CryptoPerpetual, was {other:?}"),
        }
    }

    #[rstest]
    fn test_create_instrument_from_def_carries_asset_index_on_info() {
        // The execution client resolves a market listed after its own bootstrap
        // from the instrument published on the message bus, so every market type
        // must carry its signing asset index on `info`.
        let perp_meta: PerpMeta = load_test_data("http_meta_perp_sample.json");
        let outcome_meta = OutcomeMeta {
            outcomes: vec![OutcomeMarket {
                outcome: 2,
                name: "Recurring BTC".to_string(),
                description: "Daily settlement".to_string(),
                side_specs: vec![
                    OutcomeSideSpec {
                        name: "Yes".to_string(),
                    },
                    OutcomeSideSpec {
                        name: "No".to_string(),
                    },
                ],
            }],
            questions: vec![],
        };

        let mut defs = parse_perp_instruments(&perp_meta, 0).unwrap();
        defs.extend(parse_perp_instruments(&perp_meta, 110_000).unwrap());
        defs.extend(parse_outcome_instruments(&outcome_meta).unwrap());

        assert!(defs.iter().any(|def| def.is_hip3));

        for def in &defs {
            let instrument = create_instrument_from_def(def, UnixNanos::default()).unwrap();
            let info = instrument
                .info()
                .unwrap_or_else(|| panic!("info missing for {}", def.symbol));

            assert_eq!(
                info.get_u64(ASSET_INDEX_INFO_KEY),
                Some(u64::from(def.asset_index)),
                "asset index mismatch for {}",
                def.symbol,
            );
        }
    }

    #[rstest]
    fn test_parse_perp_instruments_with_non_usdc_collateral() {
        let all_metas: Vec<PerpMeta> =
            load_test_data("http_all_perp_metas_non_usdc_collateral.json");
        let spot_meta: SpotMeta = load_test_data("http_spot_meta_non_usdc_collateral.json");

        assert_eq!(all_metas[1].collateral_token, Some(360));
        assert_eq!(all_metas[2].collateral_token, Some(235));

        let settlement_currency =
            resolve_perp_settlement_currency(&all_metas[1], Some(&spot_meta)).unwrap();
        let defs = parse_perp_instruments_with_settlement(
            &all_metas[1],
            110_000,
            settlement_currency.as_str(),
        );

        assert_eq!(settlement_currency, "USDH");
        assert_eq!(defs.len(), 1);
        assert_eq!(defs[0].symbol, "km:US500-USD-PERP");
        assert_eq!(defs[0].quote, "USD");
        assert_eq!(defs[0].settlement.as_ref().unwrap(), "USDH");

        let instrument = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();
        match instrument {
            InstrumentAny::CryptoPerpetual(perp) => {
                assert_eq!(perp.quote_currency.code, "USD");
                assert_eq!(perp.settlement_currency.code, "USDH");
                assert_eq!(perp.settlement_currency.name, "Hyperliquid USD");
            }
            other => panic!("Expected CryptoPerpetual, was {other:?}"),
        }

        let settlement_currency =
            resolve_perp_settlement_currency(&all_metas[2], Some(&spot_meta)).unwrap();
        let defs = parse_perp_instruments_with_settlement(
            &all_metas[2],
            140_000,
            settlement_currency.as_str(),
        );

        assert_eq!(settlement_currency, "USDE");
        assert_eq!(defs.len(), 1);
        assert_eq!(defs[0].symbol, "hyna:BTC-USD-PERP");
        assert_eq!(defs[0].quote, "USD");
        assert_eq!(defs[0].settlement.as_ref().unwrap(), "USDE");

        let instrument = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();
        match instrument {
            InstrumentAny::CryptoPerpetual(perp) => {
                assert_eq!(perp.quote_currency.code, "USD");
                assert_eq!(perp.settlement_currency.code, "USDE");
            }
            other => panic!("Expected CryptoPerpetual, was {other:?}"),
        }
    }

    #[rstest]
    fn test_create_instrument_from_def_perp_defaults_missing_settlement_to_usdc() {
        let meta: PerpMeta = load_test_data("http_meta_perp_sample.json");
        let mut defs = parse_perp_instruments(&meta, 0).unwrap();
        defs[0].settlement = None;

        let instrument = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();

        match instrument {
            InstrumentAny::CryptoPerpetual(perp) => {
                assert_eq!(perp.quote_currency.code, "USD");
                assert_eq!(perp.settlement_currency.code, "USDC");
            }
            other => panic!("Expected CryptoPerpetual, was {other:?}"),
        }
    }

    #[rstest]
    fn test_resolve_perp_settlement_currency_defaults_to_usdc() {
        let legacy_meta: PerpMeta = load_test_data("http_meta_perp_sample.json");
        let all_metas: Vec<PerpMeta> =
            load_test_data("http_all_perp_metas_non_usdc_collateral.json");

        let legacy_settlement = resolve_perp_settlement_currency(&legacy_meta, None).unwrap();
        let token_zero_settlement = resolve_perp_settlement_currency(&all_metas[0], None).unwrap();

        assert_eq!(legacy_settlement, "USDC");
        assert_eq!(token_zero_settlement, "USDC");
    }

    #[rstest]
    fn test_resolve_perp_settlement_currency_requires_spot_meta_for_non_usdc() {
        let all_metas: Vec<PerpMeta> =
            load_test_data("http_all_perp_metas_non_usdc_collateral.json");

        let err = resolve_perp_settlement_currency(&all_metas[1], None).unwrap_err();

        assert_eq!(
            err,
            "Spot metadata required to resolve perp collateral token 360",
        );
    }

    #[rstest]
    fn test_resolve_perp_settlement_currency_errors_on_missing_token_index() {
        let all_metas: Vec<PerpMeta> =
            load_test_data("http_all_perp_metas_non_usdc_collateral.json");
        let spot_meta = SpotMeta {
            tokens: Vec::new(),
            universe: Vec::new(),
        };

        let err = resolve_perp_settlement_currency(&all_metas[1], Some(&spot_meta)).unwrap_err();

        assert_eq!(
            err,
            "Perp collateral token index 360 not found in spot metadata",
        );
    }

    #[rstest]
    fn test_deserialize_l2_book_from_real_data() {
        let book: HyperliquidL2Book = load_test_data("http_l2_book_btc.json");

        // Validate basic structure
        assert_eq!(book.coin, "BTC");
        assert_eq!(book.levels.len(), 2); // [bids, asks]
        assert_eq!(book.levels[0].len(), 5); // 5 bid levels
        assert_eq!(book.levels[1].len(), 5); // 5 ask levels

        // Verify bids and asks are properly ordered
        let bids = &book.levels[0];
        let asks = &book.levels[1];

        // Bids should be descending (highest first)
        for i in 1..bids.len() {
            let prev_price = bids[i - 1].px;
            let curr_price = bids[i].px;
            assert!(prev_price >= curr_price, "Bids should be descending");
        }

        // Asks should be ascending (lowest first)
        for i in 1..asks.len() {
            let prev_price = asks[i - 1].px;
            let curr_price = asks[i].px;
            assert!(prev_price <= curr_price, "Asks should be ascending");
        }
    }

    #[rstest]
    fn test_parse_spot_instruments() {
        let tokens = vec![
            SpotToken {
                name: "USDC".to_string(),
                sz_decimals: 6,
                wei_decimals: 6,
                index: 0,
                token_id: "0x1".to_string(),
                is_canonical: true,
                evm_contract: None,
                full_name: None,
                deployer_trading_fee_share: None,
            },
            SpotToken {
                name: "PURR".to_string(),
                sz_decimals: 0,
                wei_decimals: 5,
                index: 1,
                token_id: "0x2".to_string(),
                is_canonical: true,
                evm_contract: None,
                full_name: None,
                deployer_trading_fee_share: None,
            },
        ];

        let pairs = vec![
            SpotPair {
                name: "PURR/USDC".to_string(),
                tokens: [1, 0], // PURR base, USDC quote
                index: 0,
                is_canonical: true,
            },
            SpotPair {
                name: "ALIAS".to_string(),
                tokens: [1, 0],
                index: 1,
                is_canonical: false,
            },
        ];

        let meta = SpotMeta {
            tokens,
            universe: pairs,
        };

        let defs = parse_spot_instruments(&meta).unwrap();

        assert_eq!(defs.len(), 2);

        let purr_usdc = &defs[0];
        assert_eq!(purr_usdc.symbol, "PURR-USDC-SPOT");
        assert_eq!(purr_usdc.base, "PURR");
        assert_eq!(purr_usdc.quote, "USDC");
        assert_eq!(purr_usdc.market_type, HyperliquidMarketType::Spot);
        assert_eq!(purr_usdc.price_decimals, 8); // 8 - 0 = 8 (PURR sz_decimals = 0)
        assert_eq!(purr_usdc.size_decimals, 0);
        assert_eq!(purr_usdc.tick_size, dec!(0.00000001));
        assert_eq!(purr_usdc.lot_size, dec!(1));
        assert_eq!(purr_usdc.max_leverage, None);
        assert!(!purr_usdc.only_isolated);
        assert!(purr_usdc.active);

        let alias = &defs[1];
        assert_eq!(alias.symbol, "PURR-USDC-SPOT");
        assert_eq!(alias.base, "PURR");
        assert!(alias.active);

        let instrument = create_instrument_from_def(purr_usdc, UnixNanos::default()).unwrap();

        match instrument {
            InstrumentAny::CurrencyPair(pair) => {
                let min_notional = pair.min_notional.unwrap();
                let info = pair.info.unwrap();
                assert_eq!(min_notional.currency, Currency::USDC());
                assert_eq!(min_notional.as_decimal(), dec!(10));
                assert_eq!(info.len(), 5);
                assert_eq!(info.get_str("name"), Some("PURR/USDC"));
                assert_eq!(info.get("tokens"), Some(&json!([1, 0])));
                assert_eq!(info.get_u64("index"), Some(0));
                assert_eq!(info.get_bool("isCanonical"), Some(true));
                assert_eq!(
                    info.get_u64(ASSET_INDEX_INFO_KEY),
                    Some(u64::from(purr_usdc.asset_index)),
                );
            }
            other => panic!("Expected CurrencyPair, was {other:?}"),
        }

        let instrument = create_instrument_from_def(alias, UnixNanos::default()).unwrap();

        match instrument {
            InstrumentAny::CurrencyPair(pair) => {
                let info = pair.info.unwrap();
                assert_eq!(info.len(), 5);
                assert_eq!(info.get_str("name"), Some("ALIAS"));
                assert_eq!(info.get("tokens"), Some(&json!([1, 0])));
                assert_eq!(info.get_u64("index"), Some(1));
                assert_eq!(info.get_bool("isCanonical"), Some(false));
                assert_eq!(
                    info.get_u64(ASSET_INDEX_INFO_KEY),
                    Some(u64::from(alias.asset_index)),
                );
            }
            other => panic!("Expected CurrencyPair, was {other:?}"),
        }
    }

    #[rstest]
    fn test_parse_spot_instruments_sorts_canonical_before_non_canonical() {
        // Non-canonical pair uses a lower pair index than the canonical one;
        // the sort must still put canonical first so the base-token alias in
        // cache_instrument resolves to the canonical instrument.
        let tokens = vec![
            SpotToken {
                name: "USDC".to_string(),
                sz_decimals: 6,
                wei_decimals: 6,
                index: 0,
                token_id: "0x1".to_string(),
                is_canonical: true,
                evm_contract: None,
                full_name: None,
                deployer_trading_fee_share: None,
            },
            SpotToken {
                name: "HYPE".to_string(),
                sz_decimals: 2,
                wei_decimals: 8,
                index: 150,
                token_id: "0x2".to_string(),
                is_canonical: true,
                evm_contract: None,
                full_name: None,
                deployer_trading_fee_share: None,
            },
        ];

        let pairs = vec![
            SpotPair {
                name: "HYPE_OLD".to_string(),
                tokens: [150, 0],
                index: 3,
                is_canonical: false,
            },
            SpotPair {
                name: "HYPE".to_string(),
                tokens: [150, 0],
                index: 107,
                is_canonical: true,
            },
        ];

        let defs = parse_spot_instruments(&SpotMeta {
            tokens,
            universe: pairs,
        })
        .unwrap();

        assert_eq!(defs.len(), 2);
        assert!(defs[0].active);
        assert_eq!(defs[0].raw_symbol, "@107");
        assert_eq!(defs[0].asset_index, 10000 + 107);
        assert!(defs[1].active);
        assert_eq!(defs[1].raw_symbol, "@3");
        assert_eq!(defs[1].asset_index, 10000 + 3);
    }

    #[rstest]
    fn test_price_decimals_clamping() {
        let meta = PerpMeta {
            universe: vec![PerpAsset {
                name: "HIGHPREC".to_string(),
                sz_decimals: 10, // 6 - 10 = -4, should clamp to 0
                max_leverage: Some(1),
                ..Default::default()
            }],
            margin_tables: vec![],
            collateral_token: None,
        };

        let defs = parse_perp_instruments(&meta, 0).unwrap();
        assert_eq!(defs[0].price_decimals, 0);
        assert_eq!(defs[0].tick_size, dec!(1));
    }

    #[rstest]
    fn test_parse_perp_instruments_hip3_dex() {
        // HIP-3 dex at index 1: asset_index_base = 100_000 + 1 * 10_000 = 110_000
        let meta = PerpMeta {
            universe: vec![
                PerpAsset {
                    name: "xyz:TSLA".to_string(),
                    sz_decimals: 3,
                    max_leverage: Some(10),
                    only_isolated: None,
                    is_delisted: None,
                    growth_mode: Some("enabled".to_string()),
                    margin_mode: Some("strictIsolated".to_string()),
                },
                PerpAsset {
                    name: "xyz:NVDA".to_string(),
                    sz_decimals: 3,
                    max_leverage: Some(20),
                    only_isolated: None,
                    is_delisted: None,
                    growth_mode: None,
                    margin_mode: None,
                },
            ],
            margin_tables: vec![],
            collateral_token: None,
        };

        let defs = parse_perp_instruments(&meta, 110_000).unwrap();
        assert_eq!(defs.len(), 2);

        // HIP-3 asset: colon in symbol, offset asset index
        assert_eq!(defs[0].symbol, "xyz:TSLA-USD-PERP");
        assert!(defs[0].symbol.contains(':'));
        assert_eq!(defs[0].base, "xyz:TSLA");
        assert_eq!(defs[0].asset_index, 110_000);
        assert!(defs[0].active);

        assert_eq!(defs[1].symbol, "xyz:NVDA-USD-PERP");
        assert_eq!(defs[1].asset_index, 110_001);
    }

    #[rstest]
    #[case("BTC", "BTC")]
    #[case("kPEPE", "kPEPE")]
    #[case("xyz:TSLA", "xyz:TSLA")]
    #[case("dex:STREAMABCD****", "dex:STREAMABCDxxxx")]
    #[case("ABC?", "ABCx")]
    #[case("a*b?c", "axbxc")]
    fn test_sanitize_symbol(#[case] input: &str, #[case] expected: &str) {
        assert_eq!(sanitize_symbol(input), expected);
    }

    #[rstest]
    fn test_parse_spot_instruments_sanitizes_wildcard_token_names() {
        // Hypothetical spot token whose venue name contains `?`. Sanitization
        // must apply to the constructed `symbol` while leaving `raw_symbol`
        // and `base` carrying the venue-official name for wire I/O.
        let tokens = vec![
            SpotToken {
                name: "USDC".to_string(),
                sz_decimals: 6,
                wei_decimals: 6,
                index: 0,
                token_id: "0x1".to_string(),
                is_canonical: true,
                evm_contract: None,
                full_name: None,
                deployer_trading_fee_share: None,
            },
            SpotToken {
                name: "ABC?".to_string(),
                sz_decimals: 4,
                wei_decimals: 4,
                index: 1,
                token_id: "0x2".to_string(),
                is_canonical: true,
                evm_contract: None,
                full_name: None,
                deployer_trading_fee_share: None,
            },
        ];

        let pairs = vec![SpotPair {
            name: "ABC?/USDC".to_string(),
            tokens: [1, 0],
            index: 50,
            is_canonical: true,
        }];

        let meta = SpotMeta {
            tokens,
            universe: pairs,
        };

        let defs = parse_spot_instruments(&meta).unwrap();
        assert_eq!(defs.len(), 1);
        assert_eq!(defs[0].symbol, "ABCx-USDC-SPOT");
        assert_eq!(defs[0].base, "ABC?");
        assert_eq!(defs[0].quote, "USDC");
    }

    #[rstest]
    fn test_parse_perp_instruments_sanitizes_hip3_wildcards() {
        let meta = PerpMeta {
            universe: vec![PerpAsset {
                name: "dex:STREAMABCD****".to_string(),
                sz_decimals: 3,
                max_leverage: Some(10),
                only_isolated: None,
                is_delisted: None,
                growth_mode: None,
                margin_mode: None,
            }],
            margin_tables: vec![],
            collateral_token: None,
        };

        let defs = parse_perp_instruments(&meta, 110_000).unwrap();
        assert_eq!(defs.len(), 1);
        assert_eq!(defs[0].symbol, "dex:STREAMABCDxxxx-USD-PERP");
        assert_eq!(defs[0].raw_symbol, "dex:STREAMABCD****");
        assert_eq!(defs[0].base, "dex:STREAMABCD****");
    }

    #[rstest]
    fn test_parse_outcome_instruments_emits_both_sides() {
        let meta = OutcomeMeta {
            outcomes: vec![OutcomeMarket {
                outcome: 1,
                name: "BTC daily".to_string(),
                description: "BTC settles above strike at 06:00 UTC".to_string(),
                side_specs: vec![
                    OutcomeSideSpec {
                        name: "Yes".to_string(),
                    },
                    OutcomeSideSpec {
                        name: "No".to_string(),
                    },
                ],
            }],
            questions: vec![],
        };

        let defs = parse_outcome_instruments(&meta).unwrap();
        assert_eq!(defs.len(), 2);

        let yes = &defs[0];
        assert_eq!(yes.symbol, "1-YES-OUTCOME");
        assert_eq!(yes.raw_symbol, "#10");
        assert_eq!(yes.market_type, HyperliquidMarketType::Outcome);
        assert_eq!(yes.asset_index, 100_000_010);
        assert_eq!(yes.price_decimals, OUTCOME_PRICE_DECIMALS);
        assert_eq!(yes.size_decimals, OUTCOME_SIZE_DECIMALS);
        assert_eq!(yes.tick_size, dec!(0.0001));
        assert_eq!(yes.lot_size, dec!(0.01));
        assert_eq!(yes.quote, "USDH");
        assert!(yes.active);

        let yes_meta = yes.outcome.as_ref().unwrap();
        assert_eq!(yes_meta.outcome_index, 1);
        assert_eq!(yes_meta.outcome_side, 0);
        assert_eq!(yes_meta.market_name, "BTC daily");
        assert_eq!(yes_meta.side_name.unwrap(), "Yes");
        assert_eq!(
            yes_meta.description.unwrap(),
            "BTC settles above strike at 06:00 UTC"
        );

        let no = &defs[1];
        assert_eq!(no.symbol, "1-NO-OUTCOME");
        assert_eq!(no.raw_symbol, "#11");
        assert_eq!(no.asset_index, 100_000_011);
        let no_meta = no.outcome.as_ref().unwrap();
        assert_eq!(no_meta.outcome_side, 1);
        assert_eq!(no_meta.side_name.unwrap(), "No");
    }

    #[rstest]
    fn test_parse_outcome_instruments_handles_missing_side_specs() {
        let meta = OutcomeMeta {
            outcomes: vec![OutcomeMarket {
                outcome: 5,
                name: "Recurring".to_string(),
                description: String::new(),
                side_specs: vec![],
            }],
            questions: vec![],
        };

        let defs = parse_outcome_instruments(&meta).unwrap();
        assert_eq!(defs.len(), 2);

        // Even when the venue omits `sideSpecs`, the parser falls back to the
        // canonical HIP-4 labels ("Yes" / "No") so downstream `BinaryOption`
        // instruments always carry a meaningful side label.
        assert_eq!(defs[0].outcome.as_ref().unwrap().side_name.unwrap(), "Yes");
        assert_eq!(defs[1].outcome.as_ref().unwrap().side_name.unwrap(), "No");

        for def in &defs {
            assert!(def.outcome.as_ref().unwrap().description.is_none());
        }

        assert_eq!(defs[0].asset_index, 100_000_050);
        assert_eq!(defs[1].asset_index, 100_000_051);
    }

    #[rstest]
    fn test_get_usdh_currency_registers_with_explicit_precision() {
        let currency = get_usdh_currency();
        assert_eq!(currency.code, "USDH");
        assert_eq!(currency.precision, 8);
        assert_eq!(currency.currency_type, CurrencyType::Crypto);

        // Repeated calls return the same registered currency
        let again = get_usdh_currency();
        assert_eq!(again, currency);
        assert!(Currency::try_from_str("USDH").is_some());
    }

    #[rstest]
    fn test_create_instrument_from_def_outcome_emits_binary_option() {
        let meta = OutcomeMeta {
            outcomes: vec![OutcomeMarket {
                outcome: 2,
                name: "Recurring BTC".to_string(),
                description: "Daily settlement".to_string(),
                side_specs: vec![
                    OutcomeSideSpec {
                        name: "Yes".to_string(),
                    },
                    OutcomeSideSpec {
                        name: "No".to_string(),
                    },
                ],
            }],
            questions: vec![],
        };

        let defs = parse_outcome_instruments(&meta).unwrap();
        let instrument = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();

        match instrument {
            InstrumentAny::BinaryOption(bo) => {
                assert_eq!(bo.id.symbol.as_str(), "2-YES-OUTCOME");
                assert_eq!(bo.raw_symbol.as_str(), "#20");
                assert_eq!(bo.asset_class, AssetClass::Alternative);
                assert_eq!(bo.currency.code, "USDH");
                assert_eq!(bo.price_precision, OUTCOME_PRICE_DECIMALS as u8);
                assert_eq!(bo.size_precision, OUTCOME_SIZE_DECIMALS as u8);
                assert_eq!(bo.outcome.unwrap(), "Yes");
                assert_eq!(bo.description.unwrap(), "Daily settlement");

                let info = bo.info.expect("info should be populated for outcomes");
                assert_eq!(info.get_u64("outcome_index"), Some(2));
                assert_eq!(info.get_u64("outcome_side"), Some(0));
                assert_eq!(info.get_u64("encoding"), Some(20));
                assert_eq!(info.get_u64("asset_id"), Some(100_000_020));
                assert_eq!(info.get_str("side_name"), Some("Yes"));
                assert_eq!(info.get_str("market_name"), Some("Recurring BTC"));
            }
            other => panic!("Expected BinaryOption, was {other:?}"),
        }
    }

    #[rstest]
    fn test_create_instrument_from_def_outcome_info_carries_parsed_description() {
        let meta = OutcomeMeta {
            outcomes: vec![OutcomeMarket {
                outcome: 5,
                name: "Recurring BTC".to_string(),
                description:
                    "class:priceBinary|underlying:BTC|expiry:20260508-0600|targetPrice:81041|period:1d"
                        .to_string(),
                side_specs: vec![
                    OutcomeSideSpec {
                        name: "Yes".to_string(),
                    },
                    OutcomeSideSpec {
                        name: "No".to_string(),
                    },
                ],
            }],
            questions: vec![],
        };

        let defs = parse_outcome_instruments(&meta).unwrap();
        let yes = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();

        match yes {
            InstrumentAny::BinaryOption(bo) => {
                let info = bo.info.expect("info should be populated for outcomes");
                assert_eq!(info.get_str("class"), Some("priceBinary"));
                assert_eq!(info.get_str("underlying"), Some("BTC"));
                assert_eq!(info.get_str("expiry"), Some("20260508-0600"));
                assert_eq!(info.get_str("target_price"), Some("81041"));
                assert_eq!(info.get_str("period"), Some("1d"));
                assert!(info.get("question").is_none());
            }
            other => panic!("Expected BinaryOption, was {other:?}"),
        }
    }

    #[rstest]
    fn test_create_instrument_from_def_outcome_info_merges_parent_question() {
        let meta = OutcomeMeta {
            outcomes: vec![
                OutcomeMarket {
                    outcome: 6,
                    name: "Recurring Fallback".to_string(),
                    description: "other".to_string(),
                    side_specs: vec![],
                },
                OutcomeMarket {
                    outcome: 7,
                    name: "Recurring Named Outcome".to_string(),
                    description: "index:0".to_string(),
                    side_specs: vec![],
                },
            ],
            questions: vec![OutcomeQuestion {
                question: 0,
                name: "Recurring".to_string(),
                description:
                    "class:priceBucket|underlying:BTC|expiry:20260508-0600|priceThresholds:79303,82540|period:1d"
                        .to_string(),
                fallback_outcome: Some(6),
                named_outcomes: vec![7, 8, 9],
                settled_named_outcomes: vec![],
            }],
        };

        let defs = parse_outcome_instruments(&meta).unwrap();

        // Named outcome 7, Yes side (defs[2]).
        let named = create_instrument_from_def(&defs[2], UnixNanos::default()).unwrap();
        match named {
            InstrumentAny::BinaryOption(bo) => {
                assert_eq!(bo.id.symbol.as_str(), "7-YES-OUTCOME");
                let info = bo.info.expect("info should be populated for outcomes");
                assert_eq!(info.get_u64("named_index"), Some(0));
                assert_eq!(info.get_u64("question"), Some(0));
                assert_eq!(info.get_str("question_name"), Some("Recurring"));
                assert_eq!(info.get_str("question_class"), Some("priceBucket"));
                assert_eq!(info.get_str("question_underlying"), Some("BTC"));
                assert_eq!(
                    info.get_str("question_price_thresholds"),
                    Some("79303,82540"),
                );
                assert_eq!(info.get_str("question_expiry"), Some("20260508-0600"));
            }
            other => panic!("Expected BinaryOption, was {other:?}"),
        }

        // Fallback outcome 6, Yes side (defs[0]).
        let fallback = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();
        match fallback {
            InstrumentAny::BinaryOption(bo) => {
                assert_eq!(bo.id.symbol.as_str(), "6-YES-OUTCOME");
                let info = bo.info.expect("info should be populated for outcomes");
                assert_eq!(info.get_bool("is_fallback"), Some(true));
                assert_eq!(info.get_u64("question"), Some(0));
                assert_eq!(info.get_str("question_class"), Some("priceBucket"));
            }
            other => panic!("Expected BinaryOption, was {other:?}"),
        }
    }

    #[rstest]
    fn test_parse_fill_report_outcome_round_trip() {
        let meta = OutcomeMeta {
            outcomes: vec![OutcomeMarket {
                outcome: 42,
                name: "BTC daily".to_string(),
                description: "BTC settles above strike at 06:00 UTC".to_string(),
                side_specs: vec![
                    OutcomeSideSpec {
                        name: "Yes".to_string(),
                    },
                    OutcomeSideSpec {
                        name: "No".to_string(),
                    },
                ],
            }],
            questions: vec![],
        };

        let defs = parse_outcome_instruments(&meta).unwrap();
        let yes = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();
        assert_eq!(yes.id().symbol.as_str(), "42-YES-OUTCOME");

        let fill = HyperliquidFill {
            coin: Ustr::from("#420"),
            px: dec!(0.5500),
            sz: dec!(1000.00),
            side: HyperliquidSide::Buy,
            time: 1_704_470_400_000,
            start_position: dec!(0.00),
            dir: HyperliquidFillDirection::OpenLong,
            closed_pnl: dec!(0.0),
            hash: "0xfeed".to_string(),
            oid: 99_001,
            crossed: true,
            fee: dec!(0.0),
            tid: 77_001,
            fee_token: Ustr::from("+420"),
            builder_fee: Some(dec!(0.0001)),
        };

        let account_id = AccountId::from("HYPERLIQUID-001");
        let report = parse_fill_report(&fill, &yes, account_id, UnixNanos::default()).unwrap();

        // Zero-fee outcome fills resolve commission to the instrument's quote
        // currency (USDH) rather than the side token, so downstream OrderFilled
        // events and persistence carry a registered currency.
        assert_eq!(report.commission.currency.code, "USDH");
        assert!(report.commission.as_decimal().is_zero());
        assert_eq!(report.order_side, OrderSide::Buy);
        assert_eq!(report.liquidity_side, LiquiditySide::Taker);
        assert_eq!(report.last_qty.as_decimal(), dec!(1000));
        assert_eq!(report.last_px.as_decimal(), dec!(0.55));
    }

    #[rstest]
    fn test_deserialize_user_fills_with_dust_conversion() {
        // #4325 regression: a userFills batch must decode whole, not fail on one
        // unmodeled direction. Fixture is real mainnet wire data.
        let fills: Vec<HyperliquidFill> = load_test_data("http_user_fills_dust_conversion.json");

        let dirs: Vec<HyperliquidFillDirection> = fills.iter().map(|f| f.dir).collect();

        assert_eq!(
            dirs,
            vec![
                HyperliquidFillDirection::OpenLong,
                HyperliquidFillDirection::CloseShort,
                HyperliquidFillDirection::Buy,
                HyperliquidFillDirection::SpotDustConversion,
                HyperliquidFillDirection::NetChildVaults,
            ],
        );
    }

    #[rstest]
    fn test_resolve_fee_currency_outcome_token_returns_quote_even_when_registered() {
        let meta = OutcomeMeta {
            outcomes: vec![OutcomeMarket {
                outcome: 88,
                name: "Edge".to_string(),
                description: String::new(),
                side_specs: vec![],
            }],
            questions: vec![],
        };
        let defs = parse_outcome_instruments(&meta).unwrap();
        let yes = create_instrument_from_def(&defs[0], UnixNanos::default()).unwrap();

        // Simulate another adapter path (e.g. spot balance parsing) having already
        // registered the side token in the global currency registry.
        let _ = get_currency("+880");
        assert!(Currency::try_from_str("+880").is_some());

        let currency = resolve_fee_currency("+880", Decimal::ZERO, &yes)
            .expect("zero-fee outcome side token must resolve to quote currency");
        assert_eq!(currency.code, "USDH");

        let err = resolve_fee_currency("+880", dec!(0.01), &yes).unwrap_err();
        let err_msg = err.to_string();
        assert!(err_msg.contains("Outcome side token '+880'"));
        assert!(err_msg.contains("non-zero fee"));
    }

    #[rstest]
    #[case("+50", true)]
    #[case("+0", true)]
    #[case("+880", true)]
    #[case("", false)]
    #[case("+", false)]
    #[case("+abc", false)]
    #[case("+50a", false)]
    #[case("#50", false)]
    #[case("USDC", false)]
    #[case("-50", false)]
    fn test_is_outcome_side_token(#[case] input: &str, #[case] expected: bool) {
        assert_eq!(is_outcome_side_token(input), expected);
    }

    #[rstest]
    fn test_resolve_fee_currency_falls_back_to_quote_when_unregistered_and_zero_fee() {
        let meta = OutcomeMeta {
            outcomes: vec![OutcomeMarket {
                outcome: 77,
                name: "Edge".to_string(),
                description: String::new(),
                side_specs: vec![],
            }],
            questions: vec![],
        };

        let defs = parse_outcome_instruments(&meta).unwrap();
        let no = create_instrument_from_def(&defs[1], UnixNanos::default()).unwrap();

        // Use a token that the venue would not normally emit; resolve_fee_currency must still
        // return the instrument's quote currency on a zero-fee fill.
        let currency = resolve_fee_currency("+UNREGISTERED-TOKEN", Decimal::ZERO, &no)
            .expect("zero-fee fallback should succeed");
        assert_eq!(currency.code, "USDH");

        let err = resolve_fee_currency("+UNREGISTERED-TOKEN", dec!(0.01), &no).unwrap_err();
        assert!(err.to_string().contains("non-zero fee"));
    }

    #[rstest]
    fn test_parse_outcome_expiry_ns_round_trip() {
        // 2026-05-08 06:00:00 UTC == 1778652000 seconds since epoch
        let ns = parse_outcome_expiry_ns("20260508-0600").unwrap();
        assert_eq!(ns.as_u64(), 1_778_220_000_000_000_000);
    }

    #[rstest]
    #[case("")]
    #[case("20260508")]
    #[case("20260508-")]
    #[case("20260508-0600 ")]
    #[case("2026-05-08-06-00")]
    #[case("20261308-0600")]
    fn test_parse_outcome_expiry_ns_rejects_bad_input(#[case] input: &str) {
        assert!(parse_outcome_expiry_ns(input).is_none());
    }

    #[rstest]
    fn test_parse_outcome_instruments_pulls_expiry_from_price_binary() {
        let meta = OutcomeMeta {
            outcomes: vec![OutcomeMarket {
                outcome: 5,
                name: "Recurring".to_string(),
                description:
                    "class:priceBinary|underlying:BTC|expiry:20260508-0600|targetPrice:81041|period:1d"
                        .to_string(),
                side_specs: vec![
                    OutcomeSideSpec {
                        name: "Yes".to_string(),
                    },
                    OutcomeSideSpec {
                        name: "No".to_string(),
                    },
                ],
            }],
            questions: vec![],
        };

        let defs = parse_outcome_instruments(&meta).unwrap();
        let yes_meta = defs[0].outcome.as_ref().unwrap();
        assert_eq!(yes_meta.expiration_ns.as_u64(), 1_778_220_000_000_000_000);
    }

    #[rstest]
    fn test_parse_outcome_instruments_inherits_expiry_from_parent_question() {
        // outcome=7 has `index:0` description and is referenced by question 0's
        // `named_outcomes`. outcome=6 has `other` description and is the
        // `fallback_outcome`. Both should pick up the question's expiry.
        let meta = OutcomeMeta {
            outcomes: vec![
                OutcomeMarket {
                    outcome: 6,
                    name: "Recurring Fallback".to_string(),
                    description: "other".to_string(),
                    side_specs: vec![],
                },
                OutcomeMarket {
                    outcome: 7,
                    name: "Recurring Named Outcome".to_string(),
                    description: "index:0".to_string(),
                    side_specs: vec![],
                },
            ],
            questions: vec![OutcomeQuestion {
                question: 0,
                name: "Recurring".to_string(),
                description:
                    "class:priceBucket|underlying:BTC|expiry:20260508-0600|priceThresholds:79303,82540|period:1d"
                        .to_string(),
                fallback_outcome: Some(6),
                named_outcomes: vec![7, 8, 9],
                settled_named_outcomes: vec![],
            }],
        };

        let defs = parse_outcome_instruments(&meta).unwrap();
        let expected_ns: u64 = 1_778_220_000_000_000_000;

        for def in &defs {
            let outcome = def.outcome.as_ref().unwrap();
            assert_eq!(
                outcome.expiration_ns.as_u64(),
                expected_ns,
                "outcome {} side {} should inherit expiry",
                outcome.outcome_index,
                outcome.outcome_side,
            );
        }
    }

    #[rstest]
    fn test_derive_outcome_settlements_returns_empty_when_no_questions() {
        let meta = OutcomeMeta {
            outcomes: vec![],
            questions: vec![],
        };
        assert!(derive_outcome_settlements(&meta).is_empty());
    }

    #[rstest]
    fn test_derive_outcome_settlements_returns_empty_when_no_questions_settled() {
        let meta = OutcomeMeta {
            outcomes: vec![],
            questions: vec![OutcomeQuestion {
                question: 0,
                name: "Recurring".to_string(),
                description: "class:priceBucket|expiry:20260508-0600".to_string(),
                fallback_outcome: Some(6),
                named_outcomes: vec![7, 8, 9],
                settled_named_outcomes: vec![],
            }],
        };

        assert!(derive_outcome_settlements(&meta).is_empty());
    }

    #[rstest]
    fn test_derive_outcome_settlements_marks_winners_losers_and_fallback() {
        let meta = OutcomeMeta {
            outcomes: vec![],
            questions: vec![OutcomeQuestion {
                question: 0,
                name: "Recurring".to_string(),
                description: "class:priceBucket|expiry:20260508-0600".to_string(),
                fallback_outcome: Some(6),
                named_outcomes: vec![7, 8, 9],
                settled_named_outcomes: vec![8],
            }],
        };

        let settlements = derive_outcome_settlements(&meta);
        let lookup: ahash::AHashMap<(u32, u8), u8> = settlements
            .into_iter()
            .map(|s| ((s.outcome_index, s.outcome_side), s.final_value))
            .collect();

        // Winning named outcome 8: Yes -> 1, No -> 0
        assert_eq!(lookup[&(8, 0)], 1);
        assert_eq!(lookup[&(8, 1)], 0);

        // Losing named outcomes 7, 9 and fallback 6: Yes -> 0, No -> 1
        for losing in [7, 9, 6] {
            assert_eq!(lookup[&(losing, 0)], 0, "outcome {losing} Yes side");
            assert_eq!(lookup[&(losing, 1)], 1, "outcome {losing} No side");
        }

        assert_eq!(lookup.len(), 8);
    }

    #[rstest]
    fn test_parse_outcome_meta_question_settlement_round_trip() {
        let json = r#"{
            "outcomes": [{"outcome": 5, "name": "Recurring", "description": "class:priceBinary|expiry:20260508-0600", "sideSpecs": []}],
            "questions": [{
                "question": 0,
                "name": "Recurring",
                "description": "class:priceBucket|expiry:20260508-0600",
                "fallbackOutcome": 6,
                "namedOutcomes": [7, 8, 9],
                "settledNamedOutcomes": [8]
            }]
        }"#;

        let meta: OutcomeMeta = serde_json::from_str(json).unwrap();
        assert_eq!(meta.questions.len(), 1);
        let q = &meta.questions[0];
        assert_eq!(q.fallback_outcome, Some(6));
        assert_eq!(q.named_outcomes, vec![7, 8, 9]);
        assert_eq!(q.settled_named_outcomes, vec![8]);

        assert!(meta.parent_question(7).is_some());
        assert!(meta.parent_question(6).is_some());
        assert!(meta.parent_question(99).is_none());
    }
}