nautilus_hyperliquid/common/

converters.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.
// -------------------------------------------------------------------------------------------------

//! Order type conversion utilities for Hyperliquid adapter.
//!
//! This module provides conversion functions between Nautilus core order types
//! and Hyperliquid-specific order type representations.

use anyhow::Context;
use nautilus_model::{
    enums::{OrderType, TimeInForce},
    identifiers::{InstrumentId, Symbol},
};
use rust_decimal::Decimal;

use super::{
    consts::HYPERLIQUID_VENUE,
    enums::{
        HyperliquidConditionalOrderType, HyperliquidOrderType, HyperliquidTimeInForce,
        HyperliquidTpSl,
    },
    parse::{format_outcome_nautilus_symbol, parse_outcome_nautilus_symbol, parse_outcome_symbol},
    types::HyperliquidAssetId,
};

/// Converts an outcome (HIP-4) asset ID to its spot coin representation.
///
/// # Errors
///
/// Returns an error if `asset_id` is not a valid outcome asset ID.
pub fn outcome_asset_id_to_coin(asset_id: HyperliquidAssetId) -> anyhow::Result<String> {
    let encoding = outcome_encoding(asset_id)?;
    Ok(format!("#{encoding}"))
}

/// Converts an outcome (HIP-4) asset ID to its token name representation.
///
/// # Errors
///
/// Returns an error if `asset_id` is not a valid outcome asset ID.
pub fn outcome_asset_id_to_token(asset_id: HyperliquidAssetId) -> anyhow::Result<String> {
    let encoding = outcome_encoding(asset_id)?;
    Ok(format!("+{encoding}"))
}

/// Converts an outcome (HIP-4) asset ID to its canonical Nautilus instrument ID.
///
/// The instrument ID uses the form `{outcome_index}-{YES|NO}-OUTCOME.HYPERLIQUID`,
/// symmetric with `-PERP` / `-SPOT`, so the human reading the ID can see which
/// question and side they're trading. The venue wire forms (`#<encoding>` /
/// `+<encoding>`) are preserved on the instrument's `raw_symbol` and base
/// alias, not on the Nautilus symbol.
///
/// # Errors
///
/// Returns an error if `asset_id` is not a valid outcome asset ID.
pub fn outcome_asset_id_to_instrument_id(
    asset_id: HyperliquidAssetId,
) -> anyhow::Result<InstrumentId> {
    let encoding = outcome_encoding(asset_id)?;
    let outcome_index = encoding / 10;
    let side = u8::try_from(encoding % 10).unwrap_or(0);
    let symbol = format_outcome_nautilus_symbol(outcome_index, side);
    Ok(InstrumentId::new(Symbol::new(symbol), *HYPERLIQUID_VENUE))
}

/// Parses an outcome (HIP-4) asset ID from a Nautilus instrument ID.
///
/// Accepts the Nautilus symbol form (`{N}-{YES|NO}-OUTCOME.HYPERLIQUID`) and,
/// for compatibility with venue-wire-derived ids, also the
/// `#<encoding>.HYPERLIQUID` and `+<encoding>.HYPERLIQUID` forms.
///
/// # Errors
///
/// Returns an error if the symbol matches none of the supported forms.
pub fn outcome_asset_id_from_instrument_id(
    instrument_id: InstrumentId,
) -> anyhow::Result<HyperliquidAssetId> {
    let symbol = instrument_id.symbol.as_str();

    if let Some((outcome_index, side)) = parse_outcome_nautilus_symbol(symbol) {
        return Ok(HyperliquidAssetId::outcome(outcome_index, side));
    }

    parse_outcome_symbol(symbol)
}

fn outcome_encoding(asset_id: HyperliquidAssetId) -> anyhow::Result<u32> {
    asset_id
        .outcome_encoding()
        .with_context(|| format!("Invalid Hyperliquid outcome asset ID: {asset_id}"))
}

/// Converts a Nautilus `OrderType` to a Hyperliquid order type configuration.
///
/// # Errors
///
/// Returns an error if the order type is unsupported, a required trigger price
/// is missing, or the time in force is not supported.
pub fn nautilus_order_type_to_hyperliquid(
    order_type: OrderType,
    time_in_force: Option<TimeInForce>,
    trigger_price: Option<Decimal>,
) -> anyhow::Result<HyperliquidOrderType> {
    let result = match order_type {
        // Regular limit order
        OrderType::Limit => {
            let tif = match time_in_force {
                Some(t) => nautilus_time_in_force_to_hyperliquid(t)?,
                None => HyperliquidTimeInForce::Gtc,
            };
            HyperliquidOrderType::Limit { tif }
        }

        // Stop market order (stop loss)
        OrderType::StopMarket => {
            let trigger_px = trigger_price
                .context("Trigger price required for StopMarket order")?
                .to_string();
            HyperliquidOrderType::Trigger {
                is_market: true,
                trigger_px,
                tpsl: HyperliquidTpSl::Sl,
            }
        }

        // Stop limit order (stop loss with limit)
        OrderType::StopLimit => {
            let trigger_px = trigger_price
                .context("Trigger price required for StopLimit order")?
                .to_string();
            HyperliquidOrderType::Trigger {
                is_market: false,
                trigger_px,
                tpsl: HyperliquidTpSl::Sl,
            }
        }

        // Market if touched (take profit market)
        OrderType::MarketIfTouched => {
            let trigger_px = trigger_price
                .context("Trigger price required for MarketIfTouched order")?
                .to_string();
            HyperliquidOrderType::Trigger {
                is_market: true,
                trigger_px,
                tpsl: HyperliquidTpSl::Tp,
            }
        }

        // Limit if touched (take profit limit)
        OrderType::LimitIfTouched => {
            let trigger_px = trigger_price
                .context("Trigger price required for LimitIfTouched order")?
                .to_string();
            HyperliquidOrderType::Trigger {
                is_market: false,
                trigger_px,
                tpsl: HyperliquidTpSl::Tp,
            }
        }

        // Trailing stop market (requires special handling)
        OrderType::TrailingStopMarket => {
            let trigger_px = trigger_price
                .context("Trigger price required for TrailingStopMarket order")?
                .to_string();
            HyperliquidOrderType::Trigger {
                is_market: true,
                trigger_px,
                tpsl: HyperliquidTpSl::Sl,
            }
        }

        // Trailing stop limit (requires special handling)
        OrderType::TrailingStopLimit => {
            let trigger_px = trigger_price
                .context("Trigger price required for TrailingStopLimit order")?
                .to_string();
            HyperliquidOrderType::Trigger {
                is_market: false,
                trigger_px,
                tpsl: HyperliquidTpSl::Sl,
            }
        }

        _ => anyhow::bail!("Unsupported order type: {order_type:?}"),
    };

    Ok(result)
}

/// Converts a Hyperliquid order type to a Nautilus `OrderType`.
pub fn hyperliquid_order_type_to_nautilus(hl_order_type: &HyperliquidOrderType) -> OrderType {
    match hl_order_type {
        HyperliquidOrderType::Limit { .. } => OrderType::Limit,
        HyperliquidOrderType::Trigger {
            is_market, tpsl, ..
        } => match (is_market, tpsl) {
            (true, HyperliquidTpSl::Sl) => OrderType::StopMarket,
            (false, HyperliquidTpSl::Sl) => OrderType::StopLimit,
            (true, HyperliquidTpSl::Tp) => OrderType::MarketIfTouched,
            (false, HyperliquidTpSl::Tp) => OrderType::LimitIfTouched,
        },
    }
}

/// Converts a Hyperliquid conditional order type to a Nautilus `OrderType`.
pub fn hyperliquid_conditional_to_nautilus(
    conditional_type: HyperliquidConditionalOrderType,
) -> OrderType {
    OrderType::from(conditional_type)
}

/// Converts a Nautilus `OrderType` to a Hyperliquid conditional order type.
///
/// # Panics
///
/// Panics if the order type is not a conditional order type.
pub fn nautilus_to_hyperliquid_conditional(
    order_type: OrderType,
) -> HyperliquidConditionalOrderType {
    HyperliquidConditionalOrderType::from(order_type)
}

/// Converts a Nautilus `TimeInForce` to a Hyperliquid time in force.
///
/// # Errors
///
/// Returns an error if the time in force is not supported (e.g. FOK).
pub fn nautilus_time_in_force_to_hyperliquid(
    tif: TimeInForce,
) -> anyhow::Result<HyperliquidTimeInForce> {
    match tif {
        TimeInForce::Gtc => Ok(HyperliquidTimeInForce::Gtc),
        TimeInForce::Ioc => Ok(HyperliquidTimeInForce::Ioc),
        TimeInForce::Fok => {
            anyhow::bail!("FOK time in force is not supported by Hyperliquid")
        }
        TimeInForce::Gtd => {
            anyhow::bail!("GTD time in force is not supported by Hyperliquid")
        }
        TimeInForce::Day => {
            anyhow::bail!("DAY time in force is not supported by Hyperliquid")
        }
        TimeInForce::AtTheOpen => {
            anyhow::bail!("AT_THE_OPEN time in force is not supported by Hyperliquid")
        }
        TimeInForce::AtTheClose => {
            anyhow::bail!("AT_THE_CLOSE time in force is not supported by Hyperliquid")
        }
    }
}

/// Converts a Hyperliquid time in force to a Nautilus `TimeInForce`.
pub fn hyperliquid_time_in_force_to_nautilus(hl_tif: HyperliquidTimeInForce) -> TimeInForce {
    match hl_tif {
        HyperliquidTimeInForce::Gtc => TimeInForce::Gtc,
        HyperliquidTimeInForce::Ioc
        | HyperliquidTimeInForce::FrontendMarket
        | HyperliquidTimeInForce::LiquidationMarket => TimeInForce::Ioc,
        HyperliquidTimeInForce::Alo => TimeInForce::Gtc,
    }
}

/// Determines the TP/SL type based on order type and side.
///
/// # Logic
///
/// For buy orders:
/// - Stop orders (trigger below current price) -> Stop Loss
/// - Take profit orders (trigger above current price) -> Take Profit
///
/// For sell orders:
/// - Stop orders (trigger above current price) -> Stop Loss
/// - Take profit orders (trigger below current price) -> Take Profit
pub fn determine_tpsl_type(order_type: OrderType, is_buy: bool) -> HyperliquidTpSl {
    match order_type {
        OrderType::StopMarket
        | OrderType::StopLimit
        | OrderType::TrailingStopMarket
        | OrderType::TrailingStopLimit => HyperliquidTpSl::Sl,
        OrderType::MarketIfTouched | OrderType::LimitIfTouched => HyperliquidTpSl::Tp,
        _ => {
            // Default logic based on side if order type is ambiguous
            if is_buy {
                HyperliquidTpSl::Sl
            } else {
                HyperliquidTpSl::Tp
            }
        }
    }
}

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

    use super::*;

    #[rstest]
    fn test_outcome_asset_id_to_wire_symbols() {
        let asset_id = HyperliquidAssetId::outcome(1, 0);

        assert_eq!(outcome_asset_id_to_coin(asset_id).unwrap(), "#10");
        assert_eq!(outcome_asset_id_to_token(asset_id).unwrap(), "+10");
    }

    #[rstest]
    fn test_outcome_asset_id_to_wire_symbols_rejects_non_outcome() {
        let err = outcome_asset_id_to_coin(HyperliquidAssetId::spot(7)).unwrap_err();
        assert!(
            err.to_string()
                .contains("Invalid Hyperliquid outcome asset ID"),
            "unexpected error: {err}",
        );
    }

    #[rstest]
    fn test_outcome_asset_id_instrument_id_roundtrip() {
        let asset_id = HyperliquidAssetId::outcome(3, 1);
        let instrument_id = outcome_asset_id_to_instrument_id(asset_id).unwrap();

        assert_eq!(
            instrument_id,
            InstrumentId::from("3-NO-OUTCOME.HYPERLIQUID")
        );
        assert_eq!(
            outcome_asset_id_from_instrument_id(instrument_id).unwrap(),
            asset_id,
        );
    }

    #[rstest]
    fn test_outcome_asset_id_to_instrument_id_yes_side() {
        let asset_id = HyperliquidAssetId::outcome(25, 0);
        let instrument_id = outcome_asset_id_to_instrument_id(asset_id).unwrap();

        assert_eq!(
            instrument_id,
            InstrumentId::from("25-YES-OUTCOME.HYPERLIQUID")
        );
    }

    #[rstest]
    #[case("#10.HYPERLIQUID", 1, 0)]
    #[case("+10.HYPERLIQUID", 1, 0)]
    #[case("1-YES-OUTCOME.HYPERLIQUID", 1, 0)]
    #[case("1-NO-OUTCOME.HYPERLIQUID", 1, 1)]
    fn test_outcome_asset_id_from_instrument_id_accepts_all_forms(
        #[case] symbol: &str,
        #[case] outcome_index: u32,
        #[case] side: u8,
    ) {
        let instrument_id = InstrumentId::from(symbol);
        let asset_id = outcome_asset_id_from_instrument_id(instrument_id).unwrap();

        assert_eq!(asset_id, HyperliquidAssetId::outcome(outcome_index, side));
    }

    #[rstest]
    fn test_nautilus_to_hyperliquid_limit_order() {
        let result =
            nautilus_order_type_to_hyperliquid(OrderType::Limit, Some(TimeInForce::Gtc), None)
                .unwrap();

        match result {
            HyperliquidOrderType::Limit { tif } => {
                assert_eq!(tif, HyperliquidTimeInForce::Gtc);
            }
            _ => panic!("Expected Limit order type"),
        }
    }

    #[rstest]
    fn test_nautilus_to_hyperliquid_stop_market() {
        let result = nautilus_order_type_to_hyperliquid(
            OrderType::StopMarket,
            None,
            Some(Decimal::new(49000, 0)),
        )
        .unwrap();

        match result {
            HyperliquidOrderType::Trigger {
                is_market,
                trigger_px,
                tpsl,
            } => {
                assert!(is_market);
                assert_eq!(trigger_px, "49000");
                assert_eq!(tpsl, HyperliquidTpSl::Sl);
            }
            _ => panic!("Expected Trigger order type"),
        }
    }

    #[rstest]
    fn test_nautilus_to_hyperliquid_stop_limit() {
        let result = nautilus_order_type_to_hyperliquid(
            OrderType::StopLimit,
            None,
            Some(Decimal::new(49000, 0)),
        )
        .unwrap();

        match result {
            HyperliquidOrderType::Trigger {
                is_market,
                trigger_px,
                tpsl,
            } => {
                assert!(!is_market);
                assert_eq!(trigger_px, "49000");
                assert_eq!(tpsl, HyperliquidTpSl::Sl);
            }
            _ => panic!("Expected Trigger order type"),
        }
    }

    #[rstest]
    fn test_nautilus_to_hyperliquid_take_profit_market() {
        let result = nautilus_order_type_to_hyperliquid(
            OrderType::MarketIfTouched,
            None,
            Some(Decimal::new(51000, 0)),
        )
        .unwrap();

        match result {
            HyperliquidOrderType::Trigger {
                is_market,
                trigger_px,
                tpsl,
            } => {
                assert!(is_market);
                assert_eq!(trigger_px, "51000");
                assert_eq!(tpsl, HyperliquidTpSl::Tp);
            }
            _ => panic!("Expected Trigger order type"),
        }
    }

    #[rstest]
    fn test_nautilus_to_hyperliquid_take_profit_limit() {
        let result = nautilus_order_type_to_hyperliquid(
            OrderType::LimitIfTouched,
            None,
            Some(Decimal::new(51000, 0)),
        )
        .unwrap();

        match result {
            HyperliquidOrderType::Trigger {
                is_market,
                trigger_px,
                tpsl,
            } => {
                assert!(!is_market);
                assert_eq!(trigger_px, "51000");
                assert_eq!(tpsl, HyperliquidTpSl::Tp);
            }
            _ => panic!("Expected Trigger order type"),
        }
    }

    #[rstest]
    fn test_hyperliquid_to_nautilus_limit() {
        let hl_order = HyperliquidOrderType::Limit {
            tif: HyperliquidTimeInForce::Gtc,
        };
        assert_eq!(
            hyperliquid_order_type_to_nautilus(&hl_order),
            OrderType::Limit
        );
    }

    #[rstest]
    fn test_hyperliquid_to_nautilus_stop_market() {
        let hl_order = HyperliquidOrderType::Trigger {
            is_market: true,
            trigger_px: "49000".to_string(),
            tpsl: HyperliquidTpSl::Sl,
        };
        assert_eq!(
            hyperliquid_order_type_to_nautilus(&hl_order),
            OrderType::StopMarket
        );
    }

    #[rstest]
    fn test_hyperliquid_to_nautilus_stop_limit() {
        let hl_order = HyperliquidOrderType::Trigger {
            is_market: false,
            trigger_px: "49000".to_string(),
            tpsl: HyperliquidTpSl::Sl,
        };
        assert_eq!(
            hyperliquid_order_type_to_nautilus(&hl_order),
            OrderType::StopLimit
        );
    }

    #[rstest]
    fn test_hyperliquid_to_nautilus_take_profit_market() {
        let hl_order = HyperliquidOrderType::Trigger {
            is_market: true,
            trigger_px: "51000".to_string(),
            tpsl: HyperliquidTpSl::Tp,
        };
        assert_eq!(
            hyperliquid_order_type_to_nautilus(&hl_order),
            OrderType::MarketIfTouched
        );
    }

    #[rstest]
    fn test_hyperliquid_to_nautilus_take_profit_limit() {
        let hl_order = HyperliquidOrderType::Trigger {
            is_market: false,
            trigger_px: "51000".to_string(),
            tpsl: HyperliquidTpSl::Tp,
        };
        assert_eq!(
            hyperliquid_order_type_to_nautilus(&hl_order),
            OrderType::LimitIfTouched
        );
    }

    #[rstest]
    fn test_time_in_force_conversions() {
        // Test Nautilus to Hyperliquid
        assert_eq!(
            nautilus_time_in_force_to_hyperliquid(TimeInForce::Gtc).unwrap(),
            HyperliquidTimeInForce::Gtc
        );
        assert_eq!(
            nautilus_time_in_force_to_hyperliquid(TimeInForce::Ioc).unwrap(),
            HyperliquidTimeInForce::Ioc
        );

        // Test Hyperliquid to Nautilus
        assert_eq!(
            hyperliquid_time_in_force_to_nautilus(HyperliquidTimeInForce::Gtc),
            TimeInForce::Gtc
        );
        assert_eq!(
            hyperliquid_time_in_force_to_nautilus(HyperliquidTimeInForce::Ioc),
            TimeInForce::Ioc
        );
        assert_eq!(
            hyperliquid_time_in_force_to_nautilus(HyperliquidTimeInForce::Alo),
            TimeInForce::Gtc
        );
        assert_eq!(
            hyperliquid_time_in_force_to_nautilus(HyperliquidTimeInForce::FrontendMarket),
            TimeInForce::Ioc
        );
        assert_eq!(
            hyperliquid_time_in_force_to_nautilus(HyperliquidTimeInForce::LiquidationMarket),
            TimeInForce::Ioc
        );
    }

    #[rstest]
    #[case(TimeInForce::Fok, "FOK")]
    #[case(TimeInForce::Gtd, "GTD")]
    #[case(TimeInForce::Day, "DAY")]
    #[case(TimeInForce::AtTheOpen, "AT_THE_OPEN")]
    #[case(TimeInForce::AtTheClose, "AT_THE_CLOSE")]
    fn test_unsupported_time_in_force_returns_error(#[case] tif: TimeInForce, #[case] name: &str) {
        let result = nautilus_time_in_force_to_hyperliquid(tif);
        assert!(result.is_err());
        assert!(
            result
                .unwrap_err()
                .to_string()
                .contains(&format!("{name} time in force is not supported"))
        );
    }

    #[rstest]
    fn test_conditional_order_type_conversions() {
        // Test Hyperliquid conditional to Nautilus
        assert_eq!(
            hyperliquid_conditional_to_nautilus(HyperliquidConditionalOrderType::StopMarket),
            OrderType::StopMarket
        );
        assert_eq!(
            hyperliquid_conditional_to_nautilus(HyperliquidConditionalOrderType::StopLimit),
            OrderType::StopLimit
        );
        assert_eq!(
            hyperliquid_conditional_to_nautilus(HyperliquidConditionalOrderType::TakeProfitMarket),
            OrderType::MarketIfTouched
        );
        assert_eq!(
            hyperliquid_conditional_to_nautilus(HyperliquidConditionalOrderType::TakeProfitLimit),
            OrderType::LimitIfTouched
        );

        // Test Nautilus to Hyperliquid conditional
        assert_eq!(
            nautilus_to_hyperliquid_conditional(OrderType::StopMarket),
            HyperliquidConditionalOrderType::StopMarket
        );
        assert_eq!(
            nautilus_to_hyperliquid_conditional(OrderType::StopLimit),
            HyperliquidConditionalOrderType::StopLimit
        );
        assert_eq!(
            nautilus_to_hyperliquid_conditional(OrderType::MarketIfTouched),
            HyperliquidConditionalOrderType::TakeProfitMarket
        );
        assert_eq!(
            nautilus_to_hyperliquid_conditional(OrderType::LimitIfTouched),
            HyperliquidConditionalOrderType::TakeProfitLimit
        );
    }

    #[rstest]
    fn test_determine_tpsl_type() {
        // Stop orders should always be SL
        assert_eq!(
            determine_tpsl_type(OrderType::StopMarket, true),
            HyperliquidTpSl::Sl
        );
        assert_eq!(
            determine_tpsl_type(OrderType::StopLimit, false),
            HyperliquidTpSl::Sl
        );

        // Take profit orders should always be TP
        assert_eq!(
            determine_tpsl_type(OrderType::MarketIfTouched, true),
            HyperliquidTpSl::Tp
        );
        assert_eq!(
            determine_tpsl_type(OrderType::LimitIfTouched, false),
            HyperliquidTpSl::Tp
        );

        // Trailing stops should be SL
        assert_eq!(
            determine_tpsl_type(OrderType::TrailingStopMarket, true),
            HyperliquidTpSl::Sl
        );
        assert_eq!(
            determine_tpsl_type(OrderType::TrailingStopLimit, false),
            HyperliquidTpSl::Sl
        );
    }
}