nautilus_polymarket/execution/

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

//! Parsing functions for Polymarket execution reports.

use anyhow::Context;
use jiff::Timestamp;
use nautilus_core::{
    UUID4, UnixNanos,
    datetime::{NANOSECONDS_IN_MILLISECOND, NANOSECONDS_IN_SECOND},
};
use nautilus_model::{
    enums::{LiquiditySide, OrderSide, OrderStatus, OrderType, TimeInForce},
    identifiers::{AccountId, ClientOrderId, InstrumentId, TradeId, VenueOrderId},
    instruments::InstrumentAny,
    reports::{FillReport, OrderStatusReport},
    types::{AccountBalance, Currency, Money, Price, Quantity},
};
use rust_decimal::{Decimal, RoundingStrategy, prelude::ToPrimitive};
use thiserror::Error;

use crate::{
    common::{
        consts::{DUST_SNAP_THRESHOLD_DEC, USDC_DECIMALS},
        enums::{
            PolymarketEventType, PolymarketLiquiditySide, PolymarketOrderSide,
            PolymarketOrderStatus,
        },
        models::PolymarketMakerOrder,
        parse::parse_decimal_exact,
    },
    http::models::{ClobBookLevel, PolymarketOpenOrder, PolymarketTradeReport},
};

/// Converts a [`PolymarketLiquiditySide`] to a Nautilus [`LiquiditySide`].
pub const fn parse_liquidity_side(side: PolymarketLiquiditySide) -> LiquiditySide {
    match side {
        PolymarketLiquiditySide::Maker => LiquiditySide::Maker,
        PolymarketLiquiditySide::Taker => LiquiditySide::Taker,
    }
}

/// Resolves the Nautilus order status from Polymarket status and event type.
///
/// Venue-initiated cancellations arrive as `status=Invalid, event_type=Cancellation`
/// (e.g. sport market resolution). These map to `Canceled`, not `Rejected`.
pub fn resolve_order_status(
    status: PolymarketOrderStatus,
    event_type: PolymarketEventType,
) -> OrderStatus {
    if status == PolymarketOrderStatus::Invalid && event_type == PolymarketEventType::Cancellation {
        OrderStatus::Canceled
    } else {
        OrderStatus::from(status)
    }
}

/// Determines the order side for a fill based on trader role and asset matching.
///
/// Polymarket uses a unified order book where complementary tokens (YES/NO) can match
/// across assets. A BUY YES can match with a BUY NO (cross-asset), not just SELL YES
/// (same-asset). For takers, the trade side is used directly. For makers, the side
/// depends on whether the match is cross-asset or same-asset.
pub fn determine_order_side(
    trader_side: PolymarketLiquiditySide,
    trade_side: PolymarketOrderSide,
    taker_asset_id: &str,
    maker_asset_id: &str,
) -> OrderSide {
    let order_side = OrderSide::from(trade_side);

    if trader_side == PolymarketLiquiditySide::Taker {
        return order_side;
    }

    let is_cross_asset = maker_asset_id != taker_asset_id;

    if is_cross_asset {
        order_side
    } else {
        match order_side {
            OrderSide::Buy => OrderSide::Sell,
            OrderSide::Sell => OrderSide::Buy,
        }
    }
}

/// Creates a composite trade ID bounded to 36 characters.
///
/// When multiple orders are filled by a single market order, Polymarket sends one
/// trade message with a single ID for all fills. This creates a unique trade ID
/// per fill by combining the trade ID with part of the venue order ID.
///
/// Format: `{trade_id[..27]}-{venue_order_id[last 8]}` = 36 chars.
pub fn make_composite_trade_id(trade_id: &str, venue_order_id: &str) -> TradeId {
    TradeId::from(composite_trade_id_value(trade_id, venue_order_id).as_str())
}

pub(super) fn composite_trade_id_value(trade_id: &str, venue_order_id: &str) -> String {
    let prefix_len = trade_id.len().min(27);
    let suffix_len = venue_order_id.len().min(8);
    let suffix_start = venue_order_id.len().saturating_sub(suffix_len);
    format!(
        "{}-{}",
        &trade_id[..prefix_len],
        &venue_order_id[suffix_start..]
    )
}

/// Parses a [`PolymarketOpenOrder`] into an [`OrderStatusReport`].
///
/// # Errors
///
/// Returns an error if a price or quantity cannot be represented by its domain type.
pub fn parse_order_status_report(
    order: &PolymarketOpenOrder,
    instrument_id: InstrumentId,
    account_id: AccountId,
    client_order_id: Option<ClientOrderId>,
    price_precision: u8,
    size_precision: u8,
    ts_init: UnixNanos,
) -> anyhow::Result<OrderStatusReport> {
    let expire_time = order
        .expiration
        .as_deref()
        .and_then(parse_expiration_nanos)
        .map(UnixNanos::from);
    parse_validated_order_status_report(
        order,
        OrderReportParseContext {
            instrument_id,
            account_id,
            client_order_id,
            venue_order_id: VenueOrderId::from(order.id.as_str()),
            price_precision,
            size_precision,
            ts_accepted: UnixNanos::from(order.created_at * NANOSECONDS_IN_SECOND),
            expire_time,
            ts_init,
        },
    )
}

#[derive(Clone, Copy, Debug)]
pub(super) struct OrderReportParseContext {
    pub instrument_id: InstrumentId,
    pub account_id: AccountId,
    pub client_order_id: Option<ClientOrderId>,
    pub venue_order_id: VenueOrderId,
    pub price_precision: u8,
    pub size_precision: u8,
    pub ts_accepted: UnixNanos,
    pub expire_time: Option<UnixNanos>,
    pub ts_init: UnixNanos,
}

pub(super) fn parse_validated_order_status_report(
    order: &PolymarketOpenOrder,
    ctx: OrderReportParseContext,
) -> anyhow::Result<OrderStatusReport> {
    let order_side = OrderSide::from(order.side);
    let time_in_force = TimeInForce::from(order.order_type);
    let quantity = Quantity::from_decimal_dp(order.original_size, ctx.size_precision)?;
    let raw_filled_qty = Quantity::from_decimal_dp(order.size_matched, ctx.size_precision)?;
    // `Matched` does not mean fully filled, so resolve the status from the filled quantity.
    let order_status = if order.status == PolymarketOrderStatus::Matched {
        recovered_terminal_order_status(time_in_force, quantity, raw_filled_qty)
    } else {
        OrderStatus::from(order.status)
    };
    let filled_qty = snap_filled_qty_to_quantity(quantity, raw_filled_qty, order_status);
    let price = Price::from_decimal_dp(order.price, ctx.price_precision)?;

    let mut report = OrderStatusReport::new(
        ctx.account_id,
        ctx.instrument_id,
        ctx.client_order_id,
        ctx.venue_order_id,
        order_side.into(),
        OrderType::Limit,
        time_in_force,
        order_status,
        quantity,
        filled_qty,
        ctx.ts_accepted,
        ctx.ts_accepted, // ts_last
        ctx.ts_init,
        None, // report_id
    );
    report.price = Some(price);
    report.expire_time = ctx.expire_time;
    Ok(report)
}

/// Parses a CLOB V2 `expiration` string into a Unix-nanos value. Returns
/// `None` for `"0"`, missing values, unparsable input, or values that
/// overflow `u64` when scaled to nanoseconds (e.g. accidentally-passed
/// millisecond timestamps that exceed Unix-seconds bounds).
pub(crate) fn parse_expiration_nanos(value: &str) -> Option<u64> {
    let secs: u64 = value.parse().ok()?;
    if secs == 0 {
        return None;
    }
    secs.checked_mul(NANOSECONDS_IN_SECOND)
}

// panics-doc-ok (transitive via validating identifier constructors)
/// Parses a [`PolymarketTradeReport`] into a [`FillReport`].
///
/// Produces one fill report for the overall trade. The `trade_id` is
/// derived from the Polymarket trade ID. Commission is computed from the
/// instrument's effective taker fee rate, fee exponent, and fill notional.
///
/// # Errors
///
/// Returns an error if the price or quantity cannot be represented by its domain type,
/// fee inputs are invalid, fee arithmetic overflows, or commission cannot be represented
/// as [`Money`].
///
/// # Panics
///
/// Panics if the trade identifiers are invalid.
#[expect(clippy::too_many_arguments)]
pub fn parse_fill_report(
    trade: &PolymarketTradeReport,
    instrument_id: InstrumentId,
    account_id: AccountId,
    client_order_id: Option<ClientOrderId>,
    price_precision: u8,
    size_precision: u8,
    currency: Currency,
    taker_fee_rate: Decimal,
    fee_exponent: Decimal,
    ts_init: UnixNanos,
) -> anyhow::Result<FillReport> {
    parse_validated_fill_report(
        trade,
        TakerFillParseContext {
            instrument_id,
            account_id,
            client_order_id,
            venue_order_id: VenueOrderId::from(trade.taker_order_id.as_str()),
            trade_id: TradeId::from(trade.id.as_str()),
            price_precision,
            size_precision,
            currency,
            taker_fee_rate,
            fee_exponent,
            ts_event: parse_timestamp(&trade.match_time).unwrap_or(ts_init),
            ts_init,
        },
    )
}

#[derive(Clone, Copy, Debug)]
pub(super) struct TakerFillParseContext {
    pub instrument_id: InstrumentId,
    pub account_id: AccountId,
    pub client_order_id: Option<ClientOrderId>,
    pub venue_order_id: VenueOrderId,
    pub trade_id: TradeId,
    pub price_precision: u8,
    pub size_precision: u8,
    pub currency: Currency,
    pub taker_fee_rate: Decimal,
    pub fee_exponent: Decimal,
    pub ts_event: UnixNanos,
    pub ts_init: UnixNanos,
}

pub(super) fn parse_validated_fill_report(
    trade: &PolymarketTradeReport,
    ctx: TakerFillParseContext,
) -> anyhow::Result<FillReport> {
    let order_side = OrderSide::from(trade.side);
    let last_qty = Quantity::from_decimal_dp(trade.size, ctx.size_precision)?;
    let last_px = Price::from_decimal_dp(trade.price, ctx.price_precision)?;
    let liquidity_side = parse_liquidity_side(trade.trader_side);

    let commission_value = compute_commission(
        ctx.taker_fee_rate,
        ctx.fee_exponent,
        trade.size,
        trade.price,
        liquidity_side,
    )?;
    let commission = Money::from_decimal(commission_value, ctx.currency).with_context(|| {
        format!(
            "failed to represent commission {commission_value} for {} as Money",
            ctx.instrument_id
        )
    })?;

    Ok(FillReport {
        account_id: ctx.account_id,
        instrument_id: ctx.instrument_id,
        venue_order_id: ctx.venue_order_id,
        trade_id: ctx.trade_id,
        order_side,
        last_qty,
        last_px,
        commission,
        liquidity_side,
        avg_px: None,
        report_id: UUID4::new(),
        ts_event: ctx.ts_event,
        ts_init: ctx.ts_init,
        client_order_id: ctx.client_order_id,
        venue_position_id: None,
    })
}

// panics-doc-ok (transitive via validating identifier constructors)
/// Builds a [`FillReport`] from a [`PolymarketMakerOrder`] and trade-level context.
///
/// Maker fills never pay commission per Polymarket's fee rules.
///
/// # Errors
///
/// Returns an error if the price or quantity cannot be represented by its domain type,
/// fee inputs are invalid, fee arithmetic overflows, or commission cannot be represented
/// as [`Money`].
///
/// # Panics
///
/// Panics if the maker order or generated trade identifier is invalid.
#[expect(clippy::too_many_arguments)]
pub fn build_maker_fill_report(
    mo: &PolymarketMakerOrder,
    trade_id: &str,
    trader_side: PolymarketLiquiditySide,
    trade_side: PolymarketOrderSide,
    taker_asset_id: &str,
    account_id: AccountId,
    instrument_id: InstrumentId,
    price_precision: u8,
    size_precision: u8,
    currency: Currency,
    liquidity_side: LiquiditySide,
    ts_event: UnixNanos,
    ts_init: UnixNanos,
) -> anyhow::Result<FillReport> {
    parse_validated_maker_fill_report(
        mo,
        trader_side,
        trade_side,
        taker_asset_id,
        MakerFillParseContext {
            account_id,
            instrument_id,
            venue_order_id: VenueOrderId::from(mo.order_id.as_str()),
            trade_id: make_composite_trade_id(trade_id, &mo.order_id),
            price_precision,
            size_precision,
            currency,
            liquidity_side,
            ts_event,
            ts_init,
        },
    )
}

#[derive(Clone, Copy, Debug)]
pub(super) struct MakerFillParseContext {
    pub account_id: AccountId,
    pub instrument_id: InstrumentId,
    pub venue_order_id: VenueOrderId,
    pub trade_id: TradeId,
    pub price_precision: u8,
    pub size_precision: u8,
    pub currency: Currency,
    pub liquidity_side: LiquiditySide,
    pub ts_event: UnixNanos,
    pub ts_init: UnixNanos,
}

pub(super) fn parse_validated_maker_fill_report(
    mo: &PolymarketMakerOrder,
    trader_side: PolymarketLiquiditySide,
    trade_side: PolymarketOrderSide,
    taker_asset_id: &str,
    ctx: MakerFillParseContext,
) -> anyhow::Result<FillReport> {
    let order_side = determine_order_side(
        trader_side,
        trade_side,
        taker_asset_id,
        mo.asset_id.as_str(),
    );
    let last_qty = Quantity::from_decimal_dp(mo.matched_amount, ctx.size_precision)?;
    let last_px = Price::from_decimal_dp(mo.price, ctx.price_precision)?;
    let commission_value = compute_commission(
        Decimal::ZERO,
        Decimal::ONE,
        mo.matched_amount,
        mo.price,
        ctx.liquidity_side,
    )?;
    let commission = Money::from_decimal(commission_value, ctx.currency).with_context(|| {
        format!(
            "failed to represent commission {commission_value} for {} as Money",
            ctx.instrument_id
        )
    })?;

    Ok(FillReport {
        account_id: ctx.account_id,
        instrument_id: ctx.instrument_id,
        venue_order_id: ctx.venue_order_id,
        trade_id: ctx.trade_id,
        order_side,
        last_qty,
        last_px,
        commission,
        liquidity_side: ctx.liquidity_side,
        avg_px: None,
        report_id: UUID4::new(),
        ts_event: ctx.ts_event,
        ts_init: ctx.ts_init,
        client_order_id: None,
        venue_position_id: None,
    })
}

/// Returns the effective taker fee rate for a Polymarket instrument.
///
/// Reads `info.fee_schedule.rate` written from the Gamma market at parse time.
/// This reader also accepts legacy numeric metadata. Defaults to `0` when the
/// schedule is absent so markets without fees charge no taker commission.
///
/// # Errors
///
/// Returns an error if a present schedule has a missing, invalid, or negative rate.
pub fn instrument_taker_fee(instrument: &InstrumentAny) -> anyhow::Result<Decimal> {
    let Some(schedule) = instrument_fee_schedule(instrument) else {
        return Ok(Decimal::ZERO);
    };
    fee_schedule_decimal(schedule, "rate")
}

/// Returns the fee-schedule exponent for a Polymarket instrument. Polymarket
/// stores the exponent as a decimal string in `info.fee_schedule.exponent` at parse
/// time. This reader also accepts legacy numeric metadata. Defaults to `1` when the schedule
/// is absent so the fee curve degenerates to the simple `fee = C * rate * p * (1 - p)` form
/// used by [`compute_commission`].
///
/// # Errors
///
/// Returns an error if a present schedule has a missing, invalid, or negative exponent.
pub fn instrument_fee_exponent(instrument: &InstrumentAny) -> anyhow::Result<Decimal> {
    let Some(schedule) = instrument_fee_schedule(instrument) else {
        return Ok(Decimal::ONE);
    };
    fee_schedule_decimal(schedule, "exponent")
}

fn instrument_fee_schedule(instrument: &InstrumentAny) -> Option<&serde_json::Value> {
    match instrument {
        InstrumentAny::BinaryOption(bo) => {
            bo.info.as_ref().and_then(|info| info.get("fee_schedule"))
        }
        _ => None,
    }
}

fn fee_schedule_decimal(schedule: &serde_json::Value, field: &str) -> anyhow::Result<Decimal> {
    let value = schedule
        .get(field)
        .with_context(|| format!("fee schedule is missing {field}"))?;
    let decimal = match value {
        serde_json::Value::String(value) => parse_decimal_exact(value)?,
        serde_json::Value::Number(value) => parse_decimal_exact(&value.to_string())?,
        _ => anyhow::bail!("fee {field} must be a decimal number or numeric string"),
    };
    anyhow::ensure!(decimal >= Decimal::ZERO, "fee {field} must be non-negative");
    Ok(decimal)
}

/// Adjusts a market-BUY pUSD amount to fit within the user's pUSD balance once
/// platform and builder taker fees are deducted. Mirrors `adjust_market_buy_amount`
/// in `polymarket-rs-clob-client-v2`'s `clob/utilities.rs`.
///
/// Returns `amount` unchanged when the balance already covers `amount + fees`.
/// Otherwise solves for the principal that, with fees, exactly consumes the
/// balance, then truncates to `USDC_DECIMALS` (the on-chain pUSD scale).
///
/// The fee curve `(p * (1 - p))^exponent` uses exact decimal arithmetic, so the
/// exponent must be a whole number.
///
/// `price` must be strictly inside `(0, 1)`. The SDK relies on its
/// order-builder pipeline to enforce this. Because [`adjust_market_buy_amount`]
/// is public, it repeats the precondition here.
///
/// # Errors
///
/// Returns an error if `price` is outside the open `(0, 1)` interval, or if
/// amount or balance is non-positive, a fee input is negative, the exponent is not
/// a whole number, arithmetic overflows, or the adjusted amount truncates to zero.
pub fn adjust_market_buy_amount(
    amount: Decimal,
    user_pusd_balance: Decimal,
    price: Decimal,
    fee_rate: Decimal,
    fee_exponent: Decimal,
    builder_taker_fee_rate: Decimal,
) -> anyhow::Result<Decimal> {
    if price <= Decimal::ZERO || price >= Decimal::ONE {
        anyhow::bail!(
            "invalid market-buy price {price}: must satisfy 0 < price < 1 for fee adjustment",
        );
    }

    let platform_fee_rate = fee_curve_rate(fee_rate, price, fee_exponent)?;

    anyhow::ensure!(amount > Decimal::ZERO, "market-buy amount must be positive");
    anyhow::ensure!(
        user_pusd_balance > Decimal::ZERO,
        "market-buy balance must be positive"
    );
    anyhow::ensure!(
        builder_taker_fee_rate >= Decimal::ZERO,
        "builder fee rate must be non-negative"
    );
    let platform_fee = amount
        .checked_div(price)
        .and_then(|shares| shares.checked_mul(platform_fee_rate))
        .context("market-buy platform fee overflow")?;
    let builder_fee = amount
        .checked_mul(builder_taker_fee_rate)
        .context("market-buy builder fee overflow")?;
    let total_cost = amount
        .checked_add(platform_fee)
        .and_then(|cost| cost.checked_add(builder_fee))
        .context("market-buy total cost overflow")?;

    let raw = if user_pusd_balance <= total_cost {
        let divisor = platform_fee_rate
            .checked_div(price)
            .and_then(|rate| Decimal::ONE.checked_add(rate))
            .and_then(|rate| rate.checked_add(builder_taker_fee_rate))
            .context("market-buy fee divisor overflow")?;
        user_pusd_balance
            .checked_div(divisor)
            .context("market-buy adjustment overflow")?
    } else {
        amount
    };

    let adjusted = raw.trunc_with_scale(USDC_DECIMALS);
    if adjusted.is_zero() {
        anyhow::bail!(
            "user_pusd_balance {user_pusd_balance} too small to cover fees at price {price}; \
             fee-adjusted amount truncated to zero"
        );
    }
    Ok(adjusted)
}

/// Computes a pUSD commission using Polymarket's platform fee formula.
///
/// `fee = C * feeRate * (p * (1 - p))^exponent`, paid only by takers.
/// The fee is floored to 5 decimal places, matching the venue charge.
///
/// The `fee_rate` here is the effective rate from `feeSchedule.rate` (e.g. 0.03 for
/// 3%), not the `fee_rate_bps` field on a V2 trade response. The response field is
/// the post-trade rate that actually applied; under V2 the fee is no longer carried
/// in the signed order, so we compute commissions from the instrument's fee schedule
/// rather than reading any cap off the order body.
///
/// # Errors
///
/// Returns an error if rates or sizes are negative, the exponent is not a whole number, prices fall
/// outside `[0, 1]`, or a calculation cannot be represented.
///
/// # References
/// <https://docs.polymarket.com/trading/fees>
pub fn compute_commission(
    fee_rate: Decimal,
    fee_exponent: Decimal,
    size: Decimal,
    price: Decimal,
    liquidity_side: LiquiditySide,
) -> anyhow::Result<Decimal> {
    anyhow::ensure!(size >= Decimal::ZERO, "fee quantity must be non-negative");
    let rate = fee_curve_rate(fee_rate, price, fee_exponent)?;

    if liquidity_side != LiquiditySide::Taker {
        return Ok(Decimal::ZERO);
    }
    let commission = size
        .checked_mul(rate)
        .context("commission calculation overflow")?;
    Ok(commission.round_dp_with_strategy(5, RoundingStrategy::ToZero))
}

fn fee_curve_rate(
    fee_rate: Decimal,
    price: Decimal,
    fee_exponent: Decimal,
) -> anyhow::Result<Decimal> {
    anyhow::ensure!(fee_rate >= Decimal::ZERO, "fee rate must be non-negative");

    let Some(mut exponent) = fee_exponent
        .to_u64()
        .filter(|_| fee_exponent.fract().is_zero())
    else {
        anyhow::bail!("fee exponent must be a non-negative whole number, was {fee_exponent}");
    };

    anyhow::ensure!(
        (Decimal::ZERO..=Decimal::ONE).contains(&price),
        "fee price must be in [0, 1]"
    );

    if fee_rate.is_zero() {
        return Ok(Decimal::ZERO);
    }

    // Exponentiation by squaring bounds the loop by the exponent's bit length
    let mut base = price * (Decimal::ONE - price);
    let mut curve = Decimal::ONE;

    while exponent > 0 {
        if exponent & 1 == 1 {
            curve *= base;
        }

        exponent >>= 1;
        base *= base;
    }

    fee_rate
        .checked_mul(curve)
        .context("fee curve calculation overflow")
}

/// Sums `last_qty` across fills as a decimal.
pub(crate) fn sum_filled_quantity(fills: &[FillReport]) -> Decimal {
    fills.iter().map(|f| f.last_qty.as_decimal()).sum()
}

/// Quantity-weighted average price across fills, or `None` when total filled
/// is zero (avoids divide-by-zero on empty/all-zero fill lists).
pub(crate) fn weighted_average_price(
    fills: &[FillReport],
    total_filled: Decimal,
) -> Option<Decimal> {
    if total_filled.is_zero() {
        return None;
    }
    let weighted: Decimal = fills
        .iter()
        .map(|f| f.last_qty.as_decimal() * f.last_px.as_decimal())
        .sum();
    Some(weighted / total_filled)
}

/// Resolves the terminal status of a venue-terminal order from its filled quantity.
///
/// Polymarket reports a terminated order as `MATCHED` whether or not it filled completely: an IOC
/// underfill was killed, any other non-dust remainder was canceled. Dust remainders stay `Filled`.
pub(crate) fn recovered_terminal_order_status(
    time_in_force: TimeInForce,
    quantity: Quantity,
    filled_qty: Quantity,
) -> OrderStatus {
    if time_in_force == TimeInForce::Ioc && filled_qty < quantity {
        return OrderStatus::Canceled;
    }

    let dust_diff = (quantity.as_decimal() - filled_qty.as_decimal()).abs();
    if filled_qty >= quantity || dust_diff < DUST_SNAP_THRESHOLD_DEC {
        OrderStatus::Filled
    } else {
        OrderStatus::Canceled
    }
}

/// At terminal `Filled` status, snap `filled_qty` up to `quantity` when the
/// shortfall is within `DUST_SNAP_THRESHOLD_DEC`. Polymarket reports `size_matched`
/// after CLOB cent-tick rounding, so without this snap an order at `MATCHED` can
/// show non-zero leaves to the engine. An overfill keeps the venue quantity.
///
/// See `docs/integrations/polymarket.md` (Fill quantity normalization).
pub(crate) fn snap_filled_qty_to_quantity(
    quantity: Quantity,
    filled_qty: Quantity,
    order_status: OrderStatus,
) -> Quantity {
    if order_status != OrderStatus::Filled {
        return filled_qty;
    }
    let diff = quantity.as_decimal() - filled_qty.as_decimal();
    if diff > Decimal::ZERO && diff < DUST_SNAP_THRESHOLD_DEC {
        quantity
    } else {
        filled_qty
    }
}

/// pUSD scale factor: the Polymarket API returns balances in micro-pUSD (10^6 units).
const USDC_SCALE: Decimal = Decimal::from_parts(1_000_000, 0, 0, false, 0);

/// Converts a raw micro-pUSD balance from the Polymarket API into an [`AccountBalance`].
///
/// The API returns balances as integer micro-pUSD (e.g. `20000000` = 20 pUSD).
/// This divides by 10^6 and constructs Money via `Money::from_decimal`.
pub fn parse_balance_allowance(
    balance_raw: Decimal,
    currency: Currency,
) -> anyhow::Result<AccountBalance> {
    let balance_pusd = balance_raw / USDC_SCALE;
    AccountBalance::from_total_and_locked(balance_pusd, Decimal::ZERO, currency)
        .map_err(|e| anyhow::anyhow!("Failed to convert balance: {e}"))
}

/// Result of walking the order book to compute market order parameters.
#[derive(Debug)]
pub struct MarketPriceResult {
    /// The crossing price (worst level reached) for the signed CLOB order.
    pub crossing_price: Decimal,
    /// Expected base quantity (shares) computed by walking levels at actual prices.
    pub expected_base_qty: Decimal,
}

/// Calculates the market-crossing price and expected base quantity by walking the order book.
///
/// Sorts levels deterministically before walking:
/// - BUY (asks): ascending by price, best (lowest) ask first
/// - SELL (bids): descending by price, best (highest) bid first
///
/// This ensures correct results regardless of the CLOB API's response ordering.
///
/// For BUY: walks asks best-first, accumulates `size * price` (pUSD) until >= amount.
///          Also accumulates the exact shares at each level for precise base qty.
/// For SELL: walks bids best-first, accumulates `size` (shares) until >= amount.
///
/// Returns the crossing price and expected base quantity. If insufficient liquidity,
/// uses all available levels. If the book side is empty, returns an error.
pub fn calculate_market_price(
    book_levels: &[ClobBookLevel],
    amount: Decimal,
    side: PolymarketOrderSide,
) -> anyhow::Result<MarketPriceResult> {
    if book_levels.is_empty() {
        anyhow::bail!("Empty order book: no liquidity available for market order");
    }

    // Parse and sort levels deterministically so we never depend on API ordering.
    // BUY: asks ascending (best/lowest first). SELL: bids descending (best/highest first).
    anyhow::ensure!(amount > Decimal::ZERO, "market amount must be positive");
    let mut parsed_levels = Vec::with_capacity(book_levels.len());
    for level in book_levels {
        let price = parse_decimal_exact(&level.price).context("invalid market-book price")?;
        let size = parse_decimal_exact(&level.size).context("invalid market-book size")?;
        anyhow::ensure!(
            price > Decimal::ZERO && price < Decimal::ONE,
            InvalidMarketPriceError("market-book price must be in (0, 1)".to_string())
        );
        anyhow::ensure!(
            size >= Decimal::ZERO,
            "market-book size must be non-negative"
        );

        if !size.is_zero() {
            parsed_levels.push((price, size));
        }
    }

    if parsed_levels.is_empty() {
        anyhow::bail!("Empty order book: no valid price levels for market order");
    }

    match side {
        PolymarketOrderSide::Buy => parsed_levels.sort_by_key(|a| a.0),
        PolymarketOrderSide::Sell => parsed_levels.sort_by_key(|b| std::cmp::Reverse(b.0)),
    }

    let mut remaining = amount;
    let mut last_price = Decimal::ZERO;
    let mut total_base_qty = Decimal::ZERO;

    for &(price, size) in &parsed_levels {
        last_price = price;

        match side {
            PolymarketOrderSide::Buy => {
                let level_usdc = size
                    .checked_mul(price)
                    .context("market-book notional overflow")?;
                let consumed_usdc = level_usdc.min(remaining);
                let shares_at_level = consumed_usdc
                    .checked_div(price)
                    .context("market-book quantity overflow")?;
                total_base_qty = total_base_qty
                    .checked_add(shares_at_level)
                    .context("market-book quantity overflow")?;
                remaining -= consumed_usdc;
            }
            PolymarketOrderSide::Sell => {
                let consumed_shares = size.min(remaining);
                total_base_qty = total_base_qty
                    .checked_add(consumed_shares)
                    .context("market-book quantity overflow")?;
                remaining -= consumed_shares;
            }
        }

        if remaining <= Decimal::ZERO {
            return Ok(MarketPriceResult {
                crossing_price: last_price,
                expected_base_qty: total_base_qty,
            });
        }
    }

    // Insufficient liquidity: return what we have. FOK may reject at the venue;
    // FAK can fill the immediately available size and cancel the remainder.
    Ok(MarketPriceResult {
        crossing_price: last_price,
        expected_base_qty: total_base_qty,
    })
}

#[derive(Debug, Error)]
#[error("{0}")]
pub(crate) struct InvalidMarketPriceError(pub(super) String);

/// Parses a timestamp string into [`UnixNanos`].
///
/// Accepts millisecond integers ("1703875200000"), second integers ("1703875200"),
/// and RFC3339 strings ("2024-01-01T00:00:00Z").
pub fn parse_timestamp(ts_str: &str) -> Option<UnixNanos> {
    if let Ok(n) = ts_str.parse::<u64>() {
        return if n > 1_000_000_000_000 {
            n.checked_mul(NANOSECONDS_IN_MILLISECOND)
                .map(UnixNanos::from)
        } else {
            n.checked_mul(NANOSECONDS_IN_SECOND).map(UnixNanos::from)
        };
    }
    let dt = ts_str.parse::<Timestamp>().ok()?;
    Some(UnixNanos::from(u64::try_from(dt.as_nanosecond()).ok()?))
}

#[cfg(test)]
mod tests {
    use nautilus_execution::models::fee::{FeeModel, ProbabilityPriceFeeModel};
    use nautilus_model::{
        enums::{OrderSide, OrderType},
        instruments::{Instrument, InstrumentAny, stubs::binary_option},
        orders::{OrderAny, builder::OrderTestBuilder, stubs::TestOrderStubs},
    };
    use rstest::rstest;
    use rust_decimal_macros::dec;
    use ustr::Ustr;

    use super::*;
    use crate::common::enums::{
        PolymarketOrderSide, PolymarketOrderStatus, PolymarketOrderType, PolymarketOutcome,
    };

    // Underfill dust band: at terminal Filled, snap filled_qty up to quantity
    // when within 0.01 shares. Other statuses (Accepted, Canceled, etc.)
    // pass through unchanged so partial fills remain visible.
    #[rstest]
    // CLOB cent-tick underfill at MATCHED: snap UP to quantity.
    #[case::filled_underfill_dust(100.000000, 99.995000, OrderStatus::Filled, 100.000000)]
    // V2 BUY USDC-scale overfill at MATCHED: keeps the venue quantity.
    #[case::filled_overfill_dust(714.285710, 714.285714, OrderStatus::Filled, 714.285714)]
    // Underfill at exactly the band: NOT dust, leave alone.
    #[case::filled_underfill_at_band(100.000000, 99.990000, OrderStatus::Filled, 99.990000)]
    // Underfill above the band: real partial leaves, leave alone.
    #[case::filled_underfill_above_band(100.000000, 99.000000, OrderStatus::Filled, 99.000000)]
    // Exact match at MATCHED: identity.
    #[case::filled_exact(100.000000, 100.000000, OrderStatus::Filled, 100.000000)]
    // Same dust gap at non-Filled status: leave alone (live partial fill).
    #[case::accepted_underfill_dust(100.000000, 99.995000, OrderStatus::Accepted, 99.995000)]
    // Same dust gap at Canceled: leave alone (legitimate partial fill before cancel).
    #[case::canceled_underfill_dust(100.000000, 99.995000, OrderStatus::Canceled, 99.995000)]
    fn test_snap_filled_qty_to_quantity(
        #[case] quantity: f64,
        #[case] filled: f64,
        #[case] status: OrderStatus,
        #[case] expected: f64,
    ) {
        let snapped = snap_filled_qty_to_quantity(
            Quantity::new(quantity, 6),
            Quantity::new(filled, 6),
            status,
        );
        assert_eq!(snapped, Quantity::new(expected, 6));
    }

    fn make_test_fill(qty: f64, px: f64) -> FillReport {
        FillReport::new(
            AccountId::from("POLY-001"),
            InstrumentId::from("TEST-TOKEN.POLYMARKET"),
            VenueOrderId::from("0xabc"),
            TradeId::from("trade-1"),
            OrderSide::Buy,
            Quantity::new(qty, 4),
            Price::new(px, 4),
            Money::zero(Currency::pUSD()),
            LiquiditySide::Taker,
            None,
            None,
            UnixNanos::default(),
            UnixNanos::default(),
            None,
        )
    }

    fn binary_option_fill_order(
        instrument: &InstrumentAny,
        liquidity_side: LiquiditySide,
        price: &str,
    ) -> OrderAny {
        let limit_order = OrderTestBuilder::new(OrderType::Limit)
            .instrument_id(instrument.id())
            .side(OrderSide::Buy)
            .price(Price::from(price))
            .quantity(Quantity::from("100.00"))
            .build();

        TestOrderStubs::make_filled_order(&limit_order, instrument, liquidity_side)
    }

    #[rstest]
    fn test_sum_filled_quantity_empty() {
        assert_eq!(sum_filled_quantity(&[]), Decimal::ZERO);
    }

    #[rstest]
    fn test_sum_filled_quantity_multiple() {
        let fills = vec![
            make_test_fill(2.5, 0.50),
            make_test_fill(1.0, 0.60),
            make_test_fill(3.0, 0.55),
        ];
        assert_eq!(sum_filled_quantity(&fills), dec!(6.5));
    }

    #[rstest]
    fn test_weighted_average_price_zero_total_returns_none() {
        assert!(weighted_average_price(&[], Decimal::ZERO).is_none());
    }

    #[rstest]
    fn test_weighted_average_price_single_fill() {
        let fills = vec![make_test_fill(10.0, 0.5)];
        let total = sum_filled_quantity(&fills);
        assert_eq!(weighted_average_price(&fills, total), Some(dec!(0.5)));
    }

    #[rstest]
    fn test_weighted_average_price_weighted_by_quantity() {
        // 2 @ 0.40 + 8 @ 0.60 -> (0.8 + 4.8) / 10 = 0.56
        let fills = vec![make_test_fill(2.0, 0.40), make_test_fill(8.0, 0.60)];
        let total = sum_filled_quantity(&fills);
        assert_eq!(weighted_average_price(&fills, total), Some(dec!(0.56)));
    }

    #[rstest]
    #[case(dec!(20_000_000), dec!(20))] // 20 pUSD
    #[case(dec!(1_000_000), dec!(1))] // 1 pUSD
    #[case(dec!(500_000), dec!(0.5))] // 0.5 pUSD
    #[case(dec!(0), dec!(0))]
    #[case(dec!(123_456_789), dec!(123.456789))]
    #[case(dec!(12345678901123456), dec!(12345678901.123456))]
    fn test_parse_balance_allowance(#[case] raw: Decimal, #[case] expected: Decimal) {
        let currency = Currency::pUSD();
        let balance = parse_balance_allowance(raw, currency).unwrap();
        assert_eq!(
            balance.total,
            Money::from_decimal(expected, currency).unwrap()
        );
        assert_eq!(balance.free, balance.total);
        assert_eq!(
            balance.locked,
            Money::from_decimal(Decimal::ZERO, currency).unwrap()
        );
    }

    #[rstest]
    #[case::crypto_p50("0.07", "0.50", dec!(1.75))]
    #[case::crypto_p01("0.07", "0.01", dec!(0.0693))]
    #[case::crypto_p05("0.07", "0.05", dec!(0.3325))]
    #[case::crypto_p10("0.07", "0.10", dec!(0.63))]
    #[case::crypto_p30("0.07", "0.30", dec!(1.47))]
    #[case::crypto_p70("0.07", "0.70", dec!(1.47))]
    #[case::crypto_p90("0.07", "0.90", dec!(0.63))]
    #[case::crypto_p99("0.07", "0.99", dec!(0.0693))]
    #[case::sports_p50("0.05", "0.50", dec!(1.25))]
    #[case::sports_p30("0.05", "0.30", dec!(1.05))]
    #[case::sports_p70("0.05", "0.70", dec!(1.05))]
    #[case::politics_p50("0.04", "0.50", dec!(1.0))]
    #[case::politics_p30("0.04", "0.30", dec!(0.84))]
    #[case::economics_p50("0.05", "0.50", dec!(1.25))]
    #[case::economics_p30("0.05", "0.30", dec!(1.05))]
    #[case::geopolitics_p50("0", "0.50", dec!(0.0))]
    fn test_compute_commission_docs_table(
        #[case] fee_rate: &str,
        #[case] price: &str,
        #[case] expected: Decimal,
    ) {
        let commission = compute_commission(
            Decimal::from_str_exact(fee_rate).unwrap(),
            dec!(1),
            dec!(100),
            Decimal::from_str_exact(price).unwrap(),
            LiquiditySide::Taker,
        )
        .unwrap();
        assert_eq!(commission, expected);
    }

    #[rstest]
    fn test_compute_commission_issue_3860_strategy_buy() {
        // Issue #3860: strategy BUY fill
        // qty=15.463900, price=0.97, fee_rate=0.072
        // 15.4639 * 0.97 * 0.072 * (1 - 0.97) = 0.03239996328, floored to 0.03239
        let commission = compute_commission(
            dec!(0.072),
            dec!(1),
            Decimal::from_str_exact("15.463900").unwrap(),
            dec!(0.97),
            LiquiditySide::Taker,
        )
        .unwrap();
        assert_eq!(commission, dec!(0.03239));
    }

    #[rstest]
    fn test_compute_commission_issue_3860_reconciliation_sell() {
        // Issue #3860: reconciliation EXTERNAL SELL fill
        // qty=0.033400, price=0.98, fee_rate=0.072
        // Was 0.002357 with old generic formula (qty * price * fee_rate)
        // Correct: 0.0334 * 0.98 * 0.072 * (1 - 0.98) = 0.00004713408, floored to 0.00004
        let commission = compute_commission(
            dec!(0.072),
            dec!(1),
            Decimal::from_str_exact("0.033400").unwrap(),
            dec!(0.98),
            LiquiditySide::Taker,
        )
        .unwrap();
        assert_eq!(commission, dec!(0.00004));
    }

    // p * (1 - p) = 0.10817244 at p = 0.1234; its cube needs more digits than an f64 carries
    #[rstest]
    #[case::exponent_zero(dec!(0), dec!(0.07))]
    #[case::exponent_one(dec!(1), dec!(0.0075720708))]
    #[case::exponent_two(dec!(2), dec!(0.000819089374288752))]
    #[case::exponent_three(dec!(3), dec!(0.00008860289619488756839488))]
    fn test_fee_curve_rate_is_exact(#[case] exponent: Decimal, #[case] expected: Decimal) {
        let rate = fee_curve_rate(dec!(0.07), dec!(0.1234), exponent).unwrap();

        assert_eq!(rate, expected);
    }

    #[rstest]
    fn test_adjust_market_buy_amount_uses_exact_fee_curve() {
        // curve = (0.0625 * 0.9375)^3 = 0.000201165676116943359375, which an f64 rounds up
        // divisor = 1 + 0.07 * curve / 0.0625 = 1.0002253055572509765625
        // raw = balance / divisor = 1 exactly, which a larger divisor truncates to 0.999999
        let adjusted = adjust_market_buy_amount(
            dec!(2),
            dec!(1.0002253055572509765625),
            dec!(0.0625),
            dec!(0.07),
            dec!(3),
            dec!(0),
        )
        .unwrap();

        assert_eq!(adjusted, dec!(1.000000));
    }

    #[rstest]
    fn test_compute_commission_maker_is_zero() {
        let commission = compute_commission(
            Decimal::from_str_exact("0.072").unwrap(),
            dec!(1),
            dec!(100),
            Decimal::from_str_exact("0.50").unwrap(),
            LiquiditySide::Maker,
        )
        .unwrap();
        assert_eq!(commission, dec!(0));
    }

    #[rstest]
    fn test_compute_commission_uses_fee_exponent() {
        let commission = compute_commission(
            dec!(0.04),
            dec!(2),
            dec!(10),
            dec!(0.5),
            LiquiditySide::Taker,
        )
        .unwrap();
        assert_eq!(commission, dec!(0.025));
    }

    #[rstest]
    #[case::crypto_taker("0.07", "0.970", LiquiditySide::Taker)]
    #[case::sports_taker("0.05", "0.500", LiquiditySide::Taker)]
    #[case::politics_taker("0.04", "0.300", LiquiditySide::Taker)]
    #[case::maker_zero("0.03", "0.500", LiquiditySide::Maker)]
    fn test_probability_price_fee_model_matches_polymarket_commission(
        #[case] taker_fee: &str,
        #[case] price: &str,
        #[case] liquidity_side: LiquiditySide,
    ) {
        let binary = binary_option();
        let instrument = InstrumentAny::BinaryOption(binary);
        let order = binary_option_fill_order(&instrument, liquidity_side, price);

        let fee_model = ProbabilityPriceFeeModel::new(
            Decimal::ZERO,
            Decimal::from_str_exact(taker_fee).unwrap(),
        );

        let commission = fee_model
            .get_commission(
                &order,
                Quantity::from("100.00"),
                Price::from(price),
                &instrument,
            )
            .unwrap();

        let expected = compute_commission(
            Decimal::from_str_exact(taker_fee).unwrap(),
            dec!(1),
            dec!(100),
            Decimal::from_str_exact(price).unwrap(),
            liquidity_side,
        )
        .unwrap();

        assert_eq!(commission.as_decimal(), expected);
    }

    /// Reference computations for `adjust_market_buy_amount` follow the SDK
    /// formula:
    ///   platform_fee_rate = fee_rate * (p * (1 - p))^exp
    ///   platform_fee     = (amount / p) * platform_fee_rate
    ///   total_cost       = amount + platform_fee + amount * builder_taker_fee_rate
    ///   if balance <= total_cost:
    ///     adjusted = balance / (1 + platform_fee_rate / p + builder_taker_fee_rate)
    ///   else:
    ///     adjusted = amount
    ///   adjusted = trunc_with_scale(adjusted, USDC_DECIMALS)
    #[rstest]
    fn test_adjust_market_buy_amount_balance_covers_returns_unchanged() {
        // amount=10, balance=20, price=0.5, fee_rate=0.04, exp=1, builder=0
        // platform_fee = 10/0.5 * 0.04 * 0.25 = 0.2; total_cost = 10.2
        // balance(20) > 10.2 -> unchanged
        let adjusted =
            adjust_market_buy_amount(dec!(10), dec!(20), dec!(0.5), dec!(0.04), dec!(1), dec!(0))
                .unwrap();
        assert_eq!(adjusted, dec!(10.000000));
    }

    #[rstest]
    fn test_adjust_market_buy_amount_balance_equals_total_cost_at_boundary() {
        // SDK uses `<=` on the balance vs total_cost test, so an exact
        // balance == total_cost should still go through the divisor branch.
        // amount=10, total_cost=10.2 with the params below.
        let adjusted = adjust_market_buy_amount(
            dec!(10),
            dec!(10.2),
            dec!(0.5),
            dec!(0.04),
            dec!(1),
            dec!(0),
        )
        .unwrap();
        // raw = 10.2 / 1.02 = 10.0; truncated to 6dp = 10.000000.
        assert_eq!(adjusted, dec!(10.000000));
    }

    #[rstest]
    fn test_adjust_market_buy_amount_balance_below_total_cost_shrinks() {
        // amount=10, balance=5.1, price=0.5, fee_rate=0.04, exp=1, builder=0
        // total_cost = 10.2; balance < total_cost
        // divisor = 1 + 0.04*0.25/0.5 = 1.02; raw = 5.1/1.02 = 5.0
        let adjusted =
            adjust_market_buy_amount(dec!(10), dec!(5.1), dec!(0.5), dec!(0.04), dec!(1), dec!(0))
                .unwrap();
        assert_eq!(adjusted, dec!(5.000000));
    }

    #[rstest]
    fn test_adjust_market_buy_amount_with_builder_fee() {
        // amount=10, balance=10, price=0.5, fee_rate=0.04, exp=1, builder=0.001
        // platform_fee_rate = 0.01; platform_fee = 0.2
        // total_cost = 10 + 0.2 + 10*0.001 = 10.21; balance < total_cost
        // divisor = 1 + 0.01/0.5 + 0.001 = 1.021
        // raw = 10/1.021 = 9.79431928..., trunc(6) = 9.794319
        let adjusted = adjust_market_buy_amount(
            dec!(10),
            dec!(10),
            dec!(0.5),
            dec!(0.04),
            dec!(1),
            dec!(0.001),
        )
        .unwrap();
        assert_eq!(adjusted, dec!(9.794319));
    }

    #[rstest]
    fn test_adjust_market_buy_amount_crypto_fee_rate() {
        // Polymarket "Crypto" tier uses fee_rate = 0.07.
        // amount=100, balance=100, price=0.5, fee_rate=0.07, exp=1, builder=0
        // platform_fee_rate = 0.07 * 0.25 = 0.0175
        // platform_fee = 100/0.5 * 0.0175 = 3.5; total_cost = 103.5
        // divisor = 1 + 0.0175/0.5 = 1.035; raw = 100/1.035
        let adjusted = adjust_market_buy_amount(
            dec!(100),
            dec!(100),
            dec!(0.5),
            dec!(0.07),
            dec!(1),
            dec!(0),
        )
        .unwrap();
        // 100 / 1.035 == 96.6183574...; truncate to 6dp.
        assert_eq!(adjusted, dec!(96.618357));
    }

    #[rstest]
    fn test_adjust_market_buy_amount_extreme_low_price() {
        // Boundary of the price domain. Fees become tiny relative to spend.
        // amount=10, balance=10, price=0.001, fee_rate=0.04, exp=1
        // base = 0.001 * 0.999 = 0.000999
        // platform_fee_rate = 0.04 * 0.000999 = 0.00003996
        // divisor = 1 + 0.00003996/0.001 = 1.03996
        // raw = 10 / 1.03996 = 9.61575...
        let adjusted = adjust_market_buy_amount(
            dec!(10),
            dec!(10),
            dec!(0.001),
            dec!(0.04),
            dec!(1),
            dec!(0),
        )
        .unwrap();
        // 10 / 1.03996 = 9.6157544520..., truncated to 6dp.
        assert_eq!(adjusted, dec!(9.615754));
    }

    #[rstest]
    fn test_adjust_market_buy_amount_integer_exponent_two() {
        // Hypothetical exp=2 -- the curve gets steeper.
        // amount=10, balance=10, price=0.5, fee_rate=0.04, exp=2, builder=0
        // base^2 = 0.25^2 = 0.0625
        // platform_fee_rate = 0.04 * 0.0625 = 0.0025
        // divisor = 1 + 0.0025/0.5 = 1.005
        // raw = 10 / 1.005 = 9.95024876...
        let adjusted =
            adjust_market_buy_amount(dec!(10), dec!(10), dec!(0.5), dec!(0.04), dec!(2), dec!(0))
                .unwrap();
        assert_eq!(adjusted, dec!(9.950248));
    }

    #[rstest]
    #[case::fractional(dec!(0.5))]
    #[case::negative(dec!(-1))]
    fn test_adjust_market_buy_amount_rejects_non_whole_exponent(#[case] exponent: Decimal) {
        let err =
            adjust_market_buy_amount(dec!(10), dec!(10), dec!(0.5), dec!(0.04), exponent, dec!(0))
                .unwrap_err();

        assert_eq!(
            err.to_string(),
            format!("fee exponent must be a non-negative whole number, was {exponent}")
        );
    }

    #[rstest]
    fn test_adjust_market_buy_amount_zero_fee_rate_returns_unchanged() {
        // No platform fee + no builder fee + balance >= amount -> unchanged.
        let adjusted =
            adjust_market_buy_amount(dec!(10), dec!(20), dec!(0.5), dec!(0), dec!(1), dec!(0))
                .unwrap();
        assert_eq!(adjusted, dec!(10.000000));
    }

    #[rstest]
    fn test_adjust_market_buy_amount_zero_fee_rate_balance_below_principal() {
        // Even with no fees, if balance < amount we shrink to the balance.
        let adjusted =
            adjust_market_buy_amount(dec!(10), dec!(7.5), dec!(0.5), dec!(0), dec!(1), dec!(0))
                .unwrap();
        assert_eq!(adjusted, dec!(7.500000));
    }

    #[rstest]
    fn test_adjust_market_buy_amount_balance_too_small_errors() {
        // Balance below the 6dp truncation threshold for the fee-adjusted
        // amount surfaces as a domain error instead of silently submitting a
        // zero-value order.
        let err = adjust_market_buy_amount(
            dec!(10),
            dec!(0.0000001),
            dec!(0.5),
            dec!(0.04),
            dec!(1),
            dec!(0),
        )
        .unwrap_err();
        assert!(err.to_string().contains("too small"));
    }

    #[rstest]
    #[case::zero_price(dec!(0))]
    #[case::one_price(dec!(1))]
    #[case::negative_price(dec!(-0.1))]
    #[case::above_one_price(dec!(1.5))]
    fn test_adjust_market_buy_amount_rejects_invalid_price(#[case] price: Decimal) {
        let err = adjust_market_buy_amount(dec!(10), dec!(20), price, dec!(0.04), dec!(1), dec!(0))
            .unwrap_err();
        assert!(
            err.to_string().contains("invalid market-buy price"),
            "expected price-domain error, was {err}",
        );
    }

    #[rstest]
    fn test_adjust_market_buy_amount_truncates_to_six_decimals() {
        // amount=10, balance=9.123456789, price=0.5, fee_rate=0.04
        // raw = 9.123456789 / 1.02 = 8.944565479...; trunc(6) = 8.944565
        let adjusted = adjust_market_buy_amount(
            dec!(10),
            dec!(9.123456789),
            dec!(0.5),
            dec!(0.04),
            dec!(1),
            dec!(0),
        )
        .unwrap();
        assert_eq!(adjusted, dec!(8.944565));
        assert_eq!(adjusted.scale(), 6);
    }

    // SDK-ported parity tests for `adjust_market_buy_amount`. These mirror the
    // tests in `polymarket-rs-clob-client-v2`'s `clob/utilities.rs` so that any
    // drift from the reference SDK is caught locally.

    /// `platform_fee = (amount / price) * rate * (price * (1 - price))^exponent`
    /// Pure-Decimal port of the SDK's test-only fee calculation, matching its
    /// integer-exponent path so the conservation tests below stay exact.
    fn calc_platform_fee_sdk(
        amount: Decimal,
        price: Decimal,
        rate: Decimal,
        exponent: u32,
    ) -> Decimal {
        let base = price * (Decimal::ONE - price);
        let curve = (0..exponent).fold(Decimal::ONE, |curve, _| curve * base);
        (amount / price) * rate * curve
    }

    /// `builder_fee = amount * rate` (flat percentage on notional).
    fn calc_builder_fee_sdk(amount: Decimal, rate: Decimal) -> Decimal {
        amount * rate
    }

    fn close_to(actual: Decimal, expected: Decimal, tol: Decimal) {
        let diff = (actual - expected).abs();
        assert!(
            diff <= tol,
            "|{actual} - {expected}| = {diff} exceeds tolerance {tol}"
        );
    }

    #[rstest]
    fn test_sdk_adjust_market_buy_no_adjustment_when_balance_sufficient() {
        // Verbatim from SDK utilities.rs::adjust_market_buy_no_adjustment_when_balance_sufficient.
        let result = adjust_market_buy_amount(
            dec!(100),
            dec!(1000),
            dec!(0.5),
            dec!(0.02),
            dec!(1),
            dec!(0),
        )
        .unwrap();
        assert_eq!(result, dec!(100));
    }

    #[rstest]
    fn test_sdk_adjust_market_buy_adjusts_when_balance_insufficient() {
        // Verbatim from SDK::adjust_market_buy_adjusts_when_balance_insufficient.
        let result = adjust_market_buy_amount(
            dec!(100),
            dec!(100),
            dec!(0.5),
            dec!(0.02),
            dec!(1),
            dec!(0),
        )
        .unwrap();
        assert!(result < dec!(100));
        assert!(result > dec!(0));
    }

    #[rstest]
    fn test_sdk_adjust_market_buy_with_builder_fee() {
        // Verbatim from SDK::adjust_market_buy_with_builder_fee.
        let result = adjust_market_buy_amount(
            dec!(100),
            dec!(100),
            dec!(0.5),
            dec!(0),
            dec!(1),
            dec!(0.005),
        )
        .unwrap();
        // effective * 1.005 = 100, truncated to 6 USDC decimals.
        let expected = (dec!(100) / dec!(1.005)).trunc_with_scale(USDC_DECIMALS);
        assert_eq!(result, expected);
    }

    #[rstest]
    fn test_sdk_adjust_market_buy_errors_when_balance_truncates_to_zero() {
        // Verbatim from SDK::adjust_market_buy_errors_when_balance_truncates_to_zero.
        let err = adjust_market_buy_amount(
            dec!(100),
            dec!(0.0000001),
            dec!(0.5),
            dec!(0.02),
            dec!(1),
            dec!(0.005),
        )
        .unwrap_err();
        assert!(err.to_string().contains("truncated to zero"));
    }

    #[rstest]
    fn test_sdk_adjust_buy_balance_strictly_greater_returns_amount_unchanged() {
        // Ported from SDK::adjust_buy_balance_strictly_greater_returns_amount_unchanged.
        // Uses calc_platform_fee_sdk to build a balance comfortably above total cost.
        let amount = dec!(50);
        let price = dec!(0.5);
        let fee = calc_platform_fee_sdk(amount, price, dec!(0.25), 2);
        let balance = amount + fee + dec!(1);
        let result =
            adjust_market_buy_amount(amount, balance, price, dec!(0.25), dec!(2), dec!(0)).unwrap();
        assert_eq!(result, amount);
    }

    #[rstest]
    fn test_sdk_adjust_buy_balance_equal_to_total_cost_matches_divide_path() {
        // Ported from SDK::adjust_buy_balance_equal_to_total_cost_matches_divide_path.
        // At `balance == total_cost` the `<=` check fires and the divisor branch
        // reconstitutes the original amount.
        let amount = dec!(50);
        let price = dec!(0.5);
        let fee = calc_platform_fee_sdk(amount, price, dec!(0.25), 2);
        let total_cost = amount + fee;
        let result =
            adjust_market_buy_amount(amount, total_cost, price, dec!(0.25), dec!(2), dec!(0))
                .unwrap();
        close_to(result, amount, dec!(0.000001));
    }

    #[rstest]
    fn test_sdk_adjust_buy_conserves_notional_platform_only() {
        // Ported from SDK::adjust_buy_conserves_notional_platform_only.
        // balance = amount: adjusted + fee must reconstitute `amount`.
        let amount = dec!(50);
        let price = dec!(0.5);
        let adjusted =
            adjust_market_buy_amount(amount, amount, price, dec!(0.25), dec!(2), dec!(0)).unwrap();
        let fee = calc_platform_fee_sdk(adjusted, price, dec!(0.25), 2);
        close_to(adjusted + fee, amount, dec!(0.000001));
        assert!(adjusted < amount);
    }

    #[rstest]
    fn test_sdk_adjust_buy_conserves_notional_builder_only() {
        // Ported from SDK::adjust_buy_conserves_notional_builder_only.
        let amount = dec!(50);
        let price = dec!(0.5);
        let builder_rate = dec!(0.01);
        let adjusted = adjust_market_buy_amount(
            amount,
            amount,
            price,
            dec!(0),
            Decimal::from(0u32),
            builder_rate,
        )
        .unwrap();
        let fee = calc_builder_fee_sdk(adjusted, builder_rate);
        close_to(adjusted + fee, amount, dec!(0.000001));
    }

    #[rstest]
    fn test_sdk_adjust_buy_conserves_notional_platform_and_builder() {
        // Ported from SDK::adjust_buy_conserves_notional_platform_and_builder.
        let amount = dec!(50);
        let price = dec!(0.5);
        let builder_rate = dec!(0.01);
        let adjusted =
            adjust_market_buy_amount(amount, amount, price, dec!(0.25), dec!(2), builder_rate)
                .unwrap();
        let platform = calc_platform_fee_sdk(adjusted, price, dec!(0.25), 2);
        let builder = calc_builder_fee_sdk(adjusted, builder_rate);
        close_to(adjusted + platform + builder, amount, dec!(0.000001));
    }

    #[rstest]
    fn test_sdk_adjust_buy_conserves_notional_at_price_0_3() {
        // Ported from SDK::adjust_buy_conserves_notional_at_price_0_3.
        let amount = dec!(30);
        let price = dec!(0.3);
        let builder_rate = dec!(0.02);
        let adjusted =
            adjust_market_buy_amount(amount, amount, price, dec!(0.25), dec!(2), builder_rate)
                .unwrap();
        let platform = calc_platform_fee_sdk(adjusted, price, dec!(0.25), 2);
        let builder = calc_builder_fee_sdk(adjusted, builder_rate);
        close_to(adjusted + platform + builder, amount, dec!(0.000001));
    }

    #[rstest]
    fn test_parse_timestamp_ms() {
        let ts = parse_timestamp("1703875200000").unwrap();
        assert_eq!(ts, UnixNanos::from(1_703_875_200_000_000_000u64));
    }

    #[rstest]
    fn test_parse_timestamp_secs() {
        let ts = parse_timestamp("1703875200").unwrap();
        assert_eq!(ts, UnixNanos::from(1_703_875_200_000_000_000u64));
    }

    #[rstest]
    fn test_parse_timestamp_rfc3339() {
        let ts = parse_timestamp("2024-01-01T00:00:00Z").unwrap();
        assert_eq!(ts, UnixNanos::from(1_704_067_200_000_000_000u64));
    }

    #[rstest]
    fn test_parse_liquidity_side_maker() {
        assert_eq!(
            parse_liquidity_side(PolymarketLiquiditySide::Maker),
            LiquiditySide::Maker
        );
    }

    #[rstest]
    fn test_parse_liquidity_side_taker() {
        assert_eq!(
            parse_liquidity_side(PolymarketLiquiditySide::Taker),
            LiquiditySide::Taker
        );
    }

    #[rstest]
    fn test_parse_order_status_report_from_fixture() {
        let path = "test_data/http_open_order.json";
        let content = std::fs::read_to_string(path).expect("Failed to read test data");
        let order: PolymarketOpenOrder =
            serde_json::from_str(&content).expect("Failed to parse test data");

        let instrument_id = InstrumentId::from("TEST-TOKEN.POLYMARKET");
        let account_id = AccountId::from("POLYMARKET-001");

        let report = parse_order_status_report(
            &order,
            instrument_id,
            account_id,
            None,
            4,
            6,
            UnixNanos::from(1_000_000_000u64),
        )
        .unwrap();

        assert_eq!(report.account_id, account_id);
        assert_eq!(report.instrument_id, instrument_id);
        assert_eq!(report.client_order_id, None);
        assert_eq!(
            report.venue_order_id,
            VenueOrderId::from(
                "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12"
            )
        );
        assert_eq!(report.order_side, Some(OrderSide::Buy));
        assert_eq!(report.order_type, OrderType::Limit);
        assert_eq!(report.time_in_force, TimeInForce::Gtc);
        assert_eq!(report.order_status, OrderStatus::Accepted);
        assert_eq!(report.price, Some(Price::from("0.5000")));
        assert_eq!(report.price.unwrap().precision, 4);
        assert_eq!(report.quantity, Quantity::from("100.000000"));
        assert_eq!(report.quantity.precision, 6);
        assert_eq!(report.filled_qty, Quantity::from("25.000000"));
        assert_eq!(report.filled_qty.precision, 6);
        assert_eq!(
            report.ts_accepted,
            UnixNanos::from(1_703_875_200_000_000_000u64)
        );
        assert_eq!(
            report.ts_last,
            UnixNanos::from(1_703_875_200_000_000_000u64)
        );
        assert_eq!(report.ts_init, UnixNanos::from(1_000_000_000u64));
        // Fixture has expiration=null which must surface as no expire_time.
        assert_eq!(report.expire_time, None);
    }

    // Verifies parse_order_status_report wires `snap_filled_qty_to_quantity`
    // correctly. Unit-level cases live above; this guards the integration.
    #[rstest]
    // CLOB cent-tick underfill at MATCHED: snap UP to original_size.
    #[case::matched_underfill_dust(PolymarketOrderStatus::Matched, dec!(100.000000), dec!(99.995000), dec!(100.000000), dec!(100.000000))]
    // V2 BUY USDC-scale overfill at MATCHED: keeps the venue fill for the evidence cap.
    #[case::matched_overfill_dust(PolymarketOrderStatus::Matched, dec!(714.285710), dec!(714.285714), dec!(714.285710), dec!(714.285714))]
    // Same dust gap at LIVE: not snapped (legitimate partial fill in flight).
    #[case::live_underfill_dust(PolymarketOrderStatus::Live, dec!(100.000000), dec!(99.995000), dec!(100.000000), dec!(99.995000))]
    // Real partial leaves (above band) at MATCHED stay visible to the engine.
    #[case::matched_real_partial(PolymarketOrderStatus::Matched, dec!(100.000000), dec!(99.000000), dec!(100.000000), dec!(99.000000))]
    fn test_parse_order_status_report_snaps_dust_filled_qty(
        #[case] status: PolymarketOrderStatus,
        #[case] original_size: Decimal,
        #[case] size_matched: Decimal,
        #[case] expected_qty: Decimal,
        #[case] expected_filled: Decimal,
    ) {
        let order = PolymarketOpenOrder {
            associate_trades: None,
            id: "0xid".to_string(),
            status,
            market: Ustr::from("0xm"),
            original_size,
            outcome: PolymarketOutcome::yes(),
            maker_address: "0xmaker".to_string(),
            owner: "owner".to_string(),
            price: dec!(0.5),
            side: PolymarketOrderSide::Buy,
            size_matched,
            asset_id: Ustr::from("token"),
            expiration: None,
            order_type: PolymarketOrderType::GTC,
            created_at: 1_703_875_200,
        };

        let report = parse_order_status_report(
            &order,
            InstrumentId::from("TEST-TOKEN.POLYMARKET"),
            AccountId::from("POLYMARKET-001"),
            None,
            3,
            6,
            UnixNanos::from(1_000_000_000u64),
        )
        .unwrap();

        assert_eq!(report.quantity.as_decimal(), expected_qty);
        assert_eq!(report.filled_qty.as_decimal(), expected_filled);
    }

    /// A `MATCHED` underfill must reach a terminal status, and `Filled` must never carry
    /// `filled_qty < quantity`. Dust remainders still resolve as `Filled` (see #3728).
    #[rstest]
    // Partially filled then canceled: terminal, not `Filled`.
    #[case::gtc_real_partial(PolymarketOrderType::GTC, dec!(10), dec!(7), OrderStatus::Canceled)]
    // Dust underfill: stays `Filled`, `filled_qty` snaps up to `quantity`.
    #[case::gtc_dust_underfill(PolymarketOrderType::GTC, dec!(100), dec!(99.997714), OrderStatus::Filled)]
    // GTC exact fill.
    #[case::gtc_exact(PolymarketOrderType::GTC, dec!(10), dec!(10), OrderStatus::Filled)]
    // FAK underfill is killed by the venue: unchanged.
    #[case::fak_partial(PolymarketOrderType::FAK, dec!(30), dec!(20), OrderStatus::Canceled)]
    fn test_parse_order_status_report_matched_resolves_terminal_status(
        #[case] order_type: PolymarketOrderType,
        #[case] original_size: Decimal,
        #[case] size_matched: Decimal,
        #[case] expected_status: OrderStatus,
    ) {
        let order = PolymarketOpenOrder {
            associate_trades: None,
            id: "0xterminal".to_string(),
            status: PolymarketOrderStatus::Matched,
            market: Ustr::from("0xmarket"),
            original_size,
            outcome: PolymarketOutcome::yes(),
            maker_address: "0xmaker".to_string(),
            owner: "owner".to_string(),
            price: dec!(0.5),
            side: PolymarketOrderSide::Buy,
            size_matched,
            asset_id: Ustr::from("token"),
            expiration: None,
            order_type,
            created_at: 1_784_118_677,
        };

        let report = parse_order_status_report(
            &order,
            InstrumentId::from("TEST-TOKEN.POLYMARKET"),
            AccountId::from("POLYMARKET-001"),
            None,
            3,
            6,
            UnixNanos::from(1_000_000_000u64),
        )
        .unwrap();

        assert_eq!(report.order_status, expected_status);
        if report.order_status == OrderStatus::Filled {
            assert!(
                report.filled_qty >= report.quantity,
                "a Filled report must not carry filled_qty < quantity, was filled_qty={} quantity={}",
                report.filled_qty,
                report.quantity
            );
        }
    }

    #[rstest]
    fn test_parse_order_status_report_maps_partial_fak_match_to_canceled() {
        let order = PolymarketOpenOrder {
            associate_trades: Some(vec!["trade-partial-fak".to_string()]),
            id: "0xpartial-fak".to_string(),
            status: PolymarketOrderStatus::Matched,
            market: Ustr::from("0xmarket"),
            original_size: dec!(30),
            outcome: PolymarketOutcome::yes(),
            maker_address: "0xmaker".to_string(),
            owner: "owner".to_string(),
            price: dec!(0.093),
            side: PolymarketOrderSide::Buy,
            size_matched: dec!(20),
            asset_id: Ustr::from("token"),
            expiration: Some("0".to_string()),
            order_type: PolymarketOrderType::FAK,
            created_at: 1_784_118_677,
        };

        let report = parse_order_status_report(
            &order,
            InstrumentId::from("TEST-TOKEN.POLYMARKET"),
            AccountId::from("POLYMARKET-001"),
            None,
            3,
            6,
            UnixNanos::from(1_000_000_000u64),
        )
        .unwrap();

        assert_eq!(report.order_status, OrderStatus::Canceled);
        assert_eq!(report.time_in_force, TimeInForce::Ioc);
        assert_eq!(report.quantity, Quantity::from("30.000000"));
        assert_eq!(report.filled_qty, Quantity::from("20.000000"));
    }

    #[rstest]
    #[case::null(None, None)]
    #[case::zero_string(Some("0"), None)]
    #[case::empty_string(Some(""), None)]
    #[case::garbage(Some("not-a-number"), None)]
    #[case::positive_seconds(
        Some("1735689600"),
        Some(UnixNanos::from(1_735_689_600_000_000_000u64))
    )]
    fn test_parse_order_status_report_expiration(
        #[case] raw: Option<&str>,
        #[case] expected: Option<UnixNanos>,
    ) {
        let order = PolymarketOpenOrder {
            associate_trades: None,
            id: "0xid".to_string(),
            status: PolymarketOrderStatus::Live,
            market: Ustr::from("0xm"),
            original_size: dec!(100),
            outcome: PolymarketOutcome::yes(),
            maker_address: "0xmaker".to_string(),
            owner: "owner".to_string(),
            price: dec!(0.5),
            side: PolymarketOrderSide::Buy,
            size_matched: dec!(0),
            asset_id: Ustr::from("token"),
            expiration: raw.map(|s| s.to_string()),
            order_type: PolymarketOrderType::GTD,
            created_at: 1_703_875_200,
        };

        let report = parse_order_status_report(
            &order,
            InstrumentId::from("TEST-TOKEN.POLYMARKET"),
            AccountId::from("POLYMARKET-001"),
            None,
            4,
            6,
            UnixNanos::from(1_000_000_000u64),
        )
        .unwrap();

        assert_eq!(report.expire_time, expected);
    }

    #[rstest]
    #[case::price(Decimal::MAX, dec!(10), dec!(0))]
    #[case::quantity(dec!(0.5), Decimal::MAX, dec!(0))]
    #[case::filled(dec!(0.5), dec!(10), Decimal::MAX)]
    fn test_order_report_rejects_unrepresentable_values(
        #[case] price: Decimal,
        #[case] quantity: Decimal,
        #[case] filled: Decimal,
    ) {
        let mut order: PolymarketOpenOrder =
            serde_json::from_str(include_str!("../../test_data/http_open_order.json")).unwrap();
        order.price = price;
        order.original_size = quantity;
        order.size_matched = filled;
        assert!(
            parse_order_status_report(
                &order,
                InstrumentId::from("TEST.POLYMARKET"),
                AccountId::from("POLY-001"),
                None,
                4,
                6,
                UnixNanos::default()
            )
            .is_err()
        );
    }

    #[rstest]
    #[case::negative_rate(dec!(-0.1), dec!(1), dec!(10), dec!(0.5), "fee rate must be non-negative")]
    #[case::negative_exponent(dec!(0.1), dec!(-1), dec!(10), dec!(0.5), "fee exponent must be a non-negative whole number, was -1")]
    #[case::fractional_exponent(dec!(0.1), dec!(1.5), dec!(10), dec!(0.5), "fee exponent must be a non-negative whole number, was 1.5")]
    #[case::negative_size(dec!(0.1), dec!(1), dec!(-10), dec!(0.5), "fee quantity must be non-negative")]
    #[case::invalid_price(dec!(0.1), dec!(1), dec!(10), dec!(1.1), "fee price must be in [0, 1]")]
    #[case::overflow(Decimal::MAX, dec!(0), dec!(10), dec!(0.5), "commission calculation overflow")]
    fn test_commission_rejects_invalid_values(
        #[case] rate: Decimal,
        #[case] exponent: Decimal,
        #[case] size: Decimal,
        #[case] price: Decimal,
        #[case] expected: &str,
    ) {
        let error =
            compute_commission(rate, exponent, size, price, LiquiditySide::Taker).unwrap_err();

        assert_eq!(error.to_string(), expected);
    }

    #[rstest]
    #[case::negative_amount(dec!(-1), dec!(10), dec!(0), "market-buy amount must be positive")]
    #[case::zero_amount(dec!(0), dec!(10), dec!(0), "market-buy amount must be positive")]
    #[case::negative_balance(dec!(1), dec!(-10), dec!(0), "market-buy balance must be positive")]
    #[case::zero_balance(dec!(1), dec!(0), dec!(0), "market-buy balance must be positive")]
    #[case::negative_builder(dec!(1), dec!(10), dec!(-0.1), "builder fee rate must be non-negative")]
    #[case::overflow(Decimal::MAX, Decimal::MAX, dec!(1), "market-buy platform fee overflow")]
    fn test_market_buy_rejects_invalid_values(
        #[case] amount: Decimal,
        #[case] balance: Decimal,
        #[case] builder: Decimal,
        #[case] expected: &str,
    ) {
        let error = adjust_market_buy_amount(
            amount,
            balance,
            dec!(0.5),
            dec!(0.07),
            Decimal::ONE,
            builder,
        )
        .unwrap_err();

        assert_eq!(error.to_string(), expected);
    }

    #[rstest]
    fn test_fee_exponent_preserves_exact_metadata_and_rejects_invalid_metadata() {
        let mut binary = binary_option();
        let mut info = nautilus_core::Params::new();
        info.insert(
            "fee_schedule".into(),
            serde_json::json!({"exponent": "1.234567890123456789012345678"}),
        );
        binary.info = Some(info.clone());
        assert_eq!(
            instrument_fee_exponent(&InstrumentAny::BinaryOption(binary.clone())).unwrap(),
            dec!(1.234567890123456789012345678)
        );

        for value in [
            serde_json::Value::Null,
            serde_json::json!("bad"),
            serde_json::json!(-1),
        ] {
            info.insert(
                "fee_schedule".into(),
                serde_json::json!({"exponent": value}),
            );
            binary.info = Some(info.clone());
            assert!(instrument_fee_exponent(&InstrumentAny::BinaryOption(binary.clone())).is_err());
        }
        info.insert("fee_schedule".into(), serde_json::json!({"exponent": 2}));
        binary.info = Some(info);
        assert_eq!(
            instrument_fee_exponent(&InstrumentAny::BinaryOption(binary)).unwrap(),
            dec!(2)
        );
    }

    #[rstest]
    fn test_parse_fill_report_errors_when_commission_is_unrepresentable() {
        let path = "test_data/http_trade_report.json";
        let content = std::fs::read_to_string(path).expect("Failed to read test data");
        let trade: PolymarketTradeReport =
            serde_json::from_str(&content).expect("Failed to parse test data");

        let result = parse_fill_report(
            &trade,
            InstrumentId::from("TEST-TOKEN.POLYMARKET"),
            AccountId::from("POLYMARKET-001"),
            None,
            4,
            6,
            Currency::pUSD(),
            // Large enough that the commission exceeds Money's fixed-point range, while the
            // Decimal arithmetic itself stays well inside its own limits
            Decimal::from_i128_with_scale(100_000_000_000_000_000_000_000_000i128, 0),
            Decimal::ONE,
            UnixNanos::from(1_000_000_000u64),
        );

        assert!(
            result.is_err(),
            "an unrepresentable commission must surface as an error rather than panicking"
        );
    }

    #[rstest]
    fn test_parse_fill_report_from_fixture() {
        let path = "test_data/http_trade_report.json";
        let content = std::fs::read_to_string(path).expect("Failed to read test data");
        let trade: PolymarketTradeReport =
            serde_json::from_str(&content).expect("Failed to parse test data");

        let instrument_id = InstrumentId::from("TEST-TOKEN.POLYMARKET");
        let account_id = AccountId::from("POLYMARKET-001");
        let currency = Currency::pUSD();

        let report = parse_fill_report(
            &trade,
            instrument_id,
            account_id,
            None,
            4,
            6,
            currency,
            Decimal::ZERO,
            dec!(1),
            UnixNanos::from(1_000_000_000u64),
        )
        .expect("fixture commission is representable");

        assert_eq!(report.account_id, account_id);
        assert_eq!(report.instrument_id, instrument_id);
        assert_eq!(report.order_side, OrderSide::Buy);
        assert_eq!(report.liquidity_side, LiquiditySide::Taker);
        assert_eq!(report.commission.as_decimal(), dec!(0.0));
    }

    #[rstest]
    fn test_parse_fill_report_forwards_fee_schedule() {
        let path = "test_data/http_trade_report.json";
        let content = std::fs::read_to_string(path).expect("Failed to read test data");
        let trade: PolymarketTradeReport =
            serde_json::from_str(&content).expect("Failed to parse test data");

        let instrument_id = InstrumentId::from("TEST-TOKEN.POLYMARKET");
        let account_id = AccountId::from("POLYMARKET-001");
        let currency = Currency::pUSD();

        // Expected: 25 * 0.03 * (0.5 * 0.5)^2 = 0.046875, floored to 0.04687 pUSD.
        let report = parse_fill_report(
            &trade,
            instrument_id,
            account_id,
            None,
            4,
            6,
            currency,
            dec!(0.03),
            dec!(2),
            UnixNanos::from(1_000_000_000u64),
        )
        .expect("fixture commission is representable");

        assert_eq!(report.liquidity_side, LiquiditySide::Taker);
        assert_eq!(report.commission.as_decimal(), dec!(0.04687));
    }

    // Taker legs of on-chain `OrderFilled` events; see `chain_order_filled_taker_fees.source.md`
    #[rstest]
    fn test_parse_fill_report_matches_chain_taker_fills() {
        let content = std::fs::read_to_string("test_data/chain_order_filled_taker_fees.json")
            .expect("Failed to read test data");
        let vectors: Vec<serde_json::Value> =
            serde_json::from_str(&content).expect("Failed to parse test data");
        let content = std::fs::read_to_string("test_data/http_trade_report.json")
            .expect("Failed to read test data");
        let base_trade: PolymarketTradeReport =
            serde_json::from_str(&content).expect("Failed to parse test data");
        let wire_scale = dec!(1_000_000);

        for vector in &vectors {
            let field =
                |name: &str| Decimal::from_str_exact(vector[name].as_str().unwrap()).unwrap();

            let (side, shares) = match vector["side"].as_str().unwrap() {
                "BUY" => (
                    PolymarketOrderSide::Buy,
                    field("taker_amount_filled") / wire_scale,
                ),
                _ => (
                    PolymarketOrderSide::Sell,
                    field("maker_amount_filled") / wire_scale,
                ),
            };

            let mut trade = base_trade.clone();
            trade.side = side;
            trade.size = shares;
            trade.price = field("price");
            trade.trader_side = PolymarketLiquiditySide::Taker;

            let report = parse_fill_report(
                &trade,
                InstrumentId::from("TEST-TOKEN.POLYMARKET"),
                AccountId::from("POLYMARKET-001"),
                None,
                2,
                6,
                Currency::pUSD(),
                field("fee_rate"),
                dec!(1),
                UnixNanos::from(1_000_000_000u64),
            )
            .unwrap();

            assert_eq!(report.last_qty.as_decimal(), shares, "{vector}");
            assert_eq!(
                report.commission.as_decimal(),
                field("fee") / wire_scale,
                "{vector}"
            );
        }
    }

    #[rstest]
    fn test_instrument_taker_fee_reads_schedule_rate() {
        use crate::http::parse::{create_instrument_from_def, parse_gamma_market};

        let path = "test_data/gamma_market_sports_market_money_line.json";
        let content = std::fs::read_to_string(path).expect("Failed to read test data");
        let market = serde_json::from_str(&content).expect("Failed to parse test data");
        let defs = parse_gamma_market(&market).unwrap();
        let instrument =
            create_instrument_from_def(&defs[0], UnixNanos::from(1_000_000_000u64)).unwrap();

        assert_eq!(instrument_taker_fee(&instrument).unwrap(), dec!(0.03));
        assert_eq!(instrument_fee_exponent(&instrument).unwrap(), Decimal::ONE);

        let bare = InstrumentAny::BinaryOption(binary_option());
        assert_eq!(instrument_taker_fee(&bare).unwrap(), Decimal::ZERO);

        let mut binary = binary_option();
        let mut info = nautilus_core::Params::new();
        info.insert("fee_schedule".into(), serde_json::json!({"exponent": "1"}));
        binary.info = Some(info.clone());
        let missing = instrument_taker_fee(&InstrumentAny::BinaryOption(binary.clone()))
            .expect_err("a present schedule must include a rate");
        assert!(missing.to_string().contains("missing rate"), "{missing}");

        info.insert(
            "fee_schedule".into(),
            serde_json::json!({"rate": "-0.01", "exponent": "1"}),
        );
        binary.info = Some(info);
        let negative = instrument_taker_fee(&InstrumentAny::BinaryOption(binary))
            .expect_err("a negative rate must be rejected");
        assert!(
            negative.to_string().contains("must be non-negative"),
            "{negative}"
        );
    }

    #[rstest]
    #[case(
        PolymarketLiquiditySide::Taker,
        PolymarketOrderSide::Buy,
        "token_a",
        "token_b",
        OrderSide::Buy
    )]
    #[case(
        PolymarketLiquiditySide::Taker,
        PolymarketOrderSide::Sell,
        "token_a",
        "token_b",
        OrderSide::Sell
    )]
    #[case(
        PolymarketLiquiditySide::Maker,
        PolymarketOrderSide::Buy,
        "token_a",
        "token_b",
        OrderSide::Buy
    )]
    #[case(
        PolymarketLiquiditySide::Maker,
        PolymarketOrderSide::Buy,
        "token_a",
        "token_a",
        OrderSide::Sell
    )]
    #[case(
        PolymarketLiquiditySide::Maker,
        PolymarketOrderSide::Sell,
        "token_a",
        "token_a",
        OrderSide::Buy
    )]
    fn test_determine_order_side(
        #[case] trader_side: PolymarketLiquiditySide,
        #[case] trade_side: PolymarketOrderSide,
        #[case] taker_asset: &str,
        #[case] maker_asset: &str,
        #[case] expected: OrderSide,
    ) {
        let result = determine_order_side(trader_side, trade_side, taker_asset, maker_asset);
        assert_eq!(result, expected);
    }

    #[rstest]
    fn test_make_composite_trade_id_basic() {
        let trade_id = "trade-abc123";
        let venue_order_id = "order-xyz789";
        let result = make_composite_trade_id(trade_id, venue_order_id);
        assert_eq!(result.as_str(), "trade-abc123-r-xyz789");
    }

    #[rstest]
    fn test_make_composite_trade_id_truncates_long_ids() {
        let trade_id = "a]".repeat(30);
        let venue_order_id = "b".repeat(20);
        let result = make_composite_trade_id(&trade_id, &venue_order_id);
        assert!(result.as_str().len() <= 36);
    }

    #[rstest]
    fn test_make_composite_trade_id_short_venue_id() {
        let trade_id = "t123";
        let venue_order_id = "ab";
        let result = make_composite_trade_id(trade_id, venue_order_id);
        assert_eq!(result.as_str(), "t123-ab");
    }

    #[rstest]
    fn test_make_composite_trade_id_uniqueness() {
        let id_a = make_composite_trade_id("same-trade", "order-aaa");
        let id_b = make_composite_trade_id("same-trade", "order-bbb");
        assert_ne!(id_a, id_b);
    }

    // Tests use various input orderings to prove the function sorts deterministically.

    #[rstest]
    fn test_calculate_market_price_buy_single_level() {
        let levels = vec![ClobBookLevel {
            price: "0.55".to_string(),
            size: "200.0".to_string(),
        }];
        let result = calculate_market_price(&levels, dec!(50), PolymarketOrderSide::Buy).unwrap();
        assert_eq!(result.crossing_price, dec!(0.55));
        // 50 pUSD / 0.55 per share = ~90.909 shares
        assert!(result.expected_base_qty > dec!(90));
    }

    #[rstest]
    fn test_calculate_market_price_buy_walks_multiple_levels() {
        // Asks in arbitrary order, function sorts ascending for BUY
        let levels = vec![
            ClobBookLevel {
                price: "0.55".to_string(),
                size: "100.0".to_string(),
            },
            ClobBookLevel {
                price: "0.50".to_string(),
                size: "10.0".to_string(),
            },
            ClobBookLevel {
                price: "0.60".to_string(),
                size: "200.0".to_string(),
            },
        ];
        // Sorted ascending: 0.50/10, 0.55/100, 0.60/200
        // Walk: 0.50/10 → 5 pUSD (10 shares), 0.55/100 → 15 pUSD (27.27 shares)
        let result = calculate_market_price(&levels, dec!(20), PolymarketOrderSide::Buy).unwrap();
        assert_eq!(result.crossing_price, dec!(0.55));
        let expected = dec!(10) + dec!(15) / dec!(0.55);
        assert_eq!(result.expected_base_qty, expected);
    }

    #[rstest]
    fn test_calculate_market_price_buy_small_order_uses_best_ask() {
        // Asks in mixed order, function sorts to find best (0.20) first
        let levels = vec![
            ClobBookLevel {
                price: "0.50".to_string(),
                size: "50.0".to_string(),
            },
            ClobBookLevel {
                price: "0.999".to_string(),
                size: "100.0".to_string(),
            },
            ClobBookLevel {
                price: "0.20".to_string(),
                size: "72.0".to_string(),
            },
        ];
        // Sorted ascending: 0.20/72, 0.50/50, 0.999/100
        // 5 pUSD at best ask 0.20: 72 * 0.20 = 14.4 pUSD available, fills entirely
        let result = calculate_market_price(&levels, dec!(5), PolymarketOrderSide::Buy).unwrap();
        assert_eq!(result.crossing_price, dec!(0.20));
        assert_eq!(result.expected_base_qty, dec!(25)); // 5 / 0.20 = 25 shares
    }

    #[rstest]
    fn test_calculate_market_price_sell_walks_levels() {
        // Bids in ascending order, function sorts descending for SELL (best bid first)
        let levels = vec![
            ClobBookLevel {
                price: "0.48".to_string(),
                size: "100.0".to_string(),
            },
            ClobBookLevel {
                price: "0.50".to_string(),
                size: "50.0".to_string(),
            },
        ];
        // Sorted descending: 0.50/50, 0.48/100
        // Walk: 0.50 gives 50, need 30 more from 0.48 → fills
        let result = calculate_market_price(&levels, dec!(80), PolymarketOrderSide::Sell).unwrap();
        assert_eq!(result.crossing_price, dec!(0.48));
        assert_eq!(result.expected_base_qty, dec!(80));
    }

    #[rstest]
    fn test_calculate_market_price_empty_book() {
        let levels: Vec<ClobBookLevel> = vec![];
        let result = calculate_market_price(&levels, dec!(50), PolymarketOrderSide::Buy);
        assert!(result.is_err());
    }

    #[rstest]
    #[case("bad", "10", "invalid market-book price")]
    #[case("0.5", "bad", "invalid market-book size")]
    #[case("0.5", "-10", "market-book size must be non-negative")]
    #[case("1.1", "10", "market-book price must be in (0, 1)")]
    fn test_market_book_rejects_invalid_values(
        #[case] price: &str,
        #[case] size: &str,
        #[case] expected: &str,
    ) {
        let levels = [ClobBookLevel {
            price: price.into(),
            size: size.into(),
        }];
        assert_eq!(
            calculate_market_price(&levels, dec!(1), PolymarketOrderSide::Buy)
                .unwrap_err()
                .to_string(),
            expected
        );
    }

    #[rstest]
    fn test_calculate_market_price_all_zero_levels_returns_error() {
        let levels = vec![
            ClobBookLevel {
                price: "0".to_string(),
                size: "100.0".to_string(),
            },
            ClobBookLevel {
                price: "0.50".to_string(),
                size: "0".to_string(),
            },
        ];
        let result = calculate_market_price(&levels, dec!(50), PolymarketOrderSide::Buy);
        assert!(result.is_err());
    }

    #[rstest]
    fn test_calculate_market_price_insufficient_liquidity_returns_worst() {
        let levels = vec![ClobBookLevel {
            price: "0.55".to_string(),
            size: "10.0".to_string(),
        }];
        // 10 * 0.55 = 5.5 pUSD < 50 pUSD needed, returns what's available
        let result = calculate_market_price(&levels, dec!(50), PolymarketOrderSide::Buy).unwrap();
        assert_eq!(result.crossing_price, dec!(0.55));
        assert_eq!(result.expected_base_qty, dec!(10)); // only 10 shares available
    }

    #[rstest]
    fn test_calculate_market_price_buy_order_independent_of_input_ordering() {
        let levels_ascending = vec![
            ClobBookLevel {
                price: "0.20".to_string(),
                size: "72.0".to_string(),
            },
            ClobBookLevel {
                price: "0.50".to_string(),
                size: "50.0".to_string(),
            },
            ClobBookLevel {
                price: "0.999".to_string(),
                size: "100.0".to_string(),
            },
        ];
        let levels_descending = vec![
            ClobBookLevel {
                price: "0.999".to_string(),
                size: "100.0".to_string(),
            },
            ClobBookLevel {
                price: "0.50".to_string(),
                size: "50.0".to_string(),
            },
            ClobBookLevel {
                price: "0.20".to_string(),
                size: "72.0".to_string(),
            },
        ];
        let levels_shuffled = vec![
            ClobBookLevel {
                price: "0.50".to_string(),
                size: "50.0".to_string(),
            },
            ClobBookLevel {
                price: "0.20".to_string(),
                size: "72.0".to_string(),
            },
            ClobBookLevel {
                price: "0.999".to_string(),
                size: "100.0".to_string(),
            },
        ];

        let r1 =
            calculate_market_price(&levels_ascending, dec!(20), PolymarketOrderSide::Buy).unwrap();
        let r2 =
            calculate_market_price(&levels_descending, dec!(20), PolymarketOrderSide::Buy).unwrap();
        let r3 =
            calculate_market_price(&levels_shuffled, dec!(20), PolymarketOrderSide::Buy).unwrap();

        assert_eq!(r1.crossing_price, r2.crossing_price);
        assert_eq!(r2.crossing_price, r3.crossing_price);
        assert_eq!(r1.expected_base_qty, r2.expected_base_qty);
        assert_eq!(r2.expected_base_qty, r3.expected_base_qty);
    }

    #[rstest]
    fn test_calculate_market_price_sell_order_independent_of_input_ordering() {
        let levels_a = vec![
            ClobBookLevel {
                price: "0.48".to_string(),
                size: "100.0".to_string(),
            },
            ClobBookLevel {
                price: "0.50".to_string(),
                size: "50.0".to_string(),
            },
        ];
        let levels_b = vec![
            ClobBookLevel {
                price: "0.50".to_string(),
                size: "50.0".to_string(),
            },
            ClobBookLevel {
                price: "0.48".to_string(),
                size: "100.0".to_string(),
            },
        ];

        let r1 = calculate_market_price(&levels_a, dec!(80), PolymarketOrderSide::Sell).unwrap();
        let r2 = calculate_market_price(&levels_b, dec!(80), PolymarketOrderSide::Sell).unwrap();

        assert_eq!(r1.crossing_price, r2.crossing_price);
        assert_eq!(r1.expected_base_qty, r2.expected_base_qty);
    }

    mod adjust_market_buy_amount_property_tests {
        use proptest::prelude::*;
        use rstest::rstest;

        use super::*;

        // Generate a Decimal in [1e-6, 1_000_000] at USDC scale by sampling
        // micro-units. Avoids zero so we never hit the truncate-to-zero error
        // path on the input itself.
        fn decimal_at_usdc_scale(micros: u64) -> Decimal {
            Decimal::new(micros as i64, USDC_DECIMALS)
        }

        // Generate a Decimal rate from basis points: bps / 10_000.
        fn decimal_from_bps(bps: u32) -> Decimal {
            Decimal::new(i64::from(bps), 4)
        }

        // Recomputes total_cost the same way `adjust_market_buy_amount` does so
        // tests use the same formula they're verifying (no weak re-derivation).
        fn compute_total_cost(
            amount: Decimal,
            price: Decimal,
            fee_rate: Decimal,
            exponent: u32,
            builder: Decimal,
        ) -> Decimal {
            let base = price * (Decimal::ONE - price);
            let curve = (0..exponent).fold(Decimal::ONE, |curve, _| curve * base);
            let platform_fee_rate = fee_rate * curve;
            let platform_fee = amount / price * platform_fee_rate;
            amount + platform_fee + amount * builder
        }

        proptest! {
            // Deterministic over arbitrary valid inputs: same args produce
            // the same Result (Ok or Err) and equal Ok values.
            #[rstest]
            fn prop_adjust_market_buy_amount_is_deterministic(
                amount_micros in 1u64..=1_000_000_000_000u64,
                balance_micros in 1u64..=1_000_000_000_000u64,
                price_milli in 1u32..=999u32,
                fee_rate_bps in 0u32..=1_000u32,
                exponent in 0u32..=3u32,
                builder_bps in 0u32..=500u32,
            ) {
                let amount = decimal_at_usdc_scale(amount_micros);
                let balance = decimal_at_usdc_scale(balance_micros);
                let price = Decimal::new(i64::from(price_milli), 3);
                let fee_rate = decimal_from_bps(fee_rate_bps);
                let builder = decimal_from_bps(builder_bps);
                let fee_exponent = Decimal::from(exponent);

                let r1 = adjust_market_buy_amount(amount, balance, price, fee_rate, fee_exponent, builder);
                let r2 = adjust_market_buy_amount(amount, balance, price, fee_rate, fee_exponent, builder);
                prop_assert_eq!(r1.is_ok(), r2.is_ok());
                if let (Ok(a), Ok(b)) = (r1, r2) {
                    prop_assert_eq!(a, b);
                }
            }

            // Non-binding branch: balance is always large enough to cover
            // total_cost. Function MUST return Ok and the result MUST equal
            // the input amount (already at USDC scale). A regression that
            // bails on valid inputs would fail this property.
            #[rstest]
            fn prop_adjust_market_buy_amount_non_binding_returns_amount(
                amount_micros in 1u64..=1_000_000_000u64,
                price_milli in 1u32..=999u32,
                fee_rate_bps in 0u32..=1_000u32,
                exponent in 0u32..=3u32,
                builder_bps in 0u32..=500u32,
            ) {
                let amount = decimal_at_usdc_scale(amount_micros);
                let price = Decimal::new(i64::from(price_milli), 3);
                let fee_rate = decimal_from_bps(fee_rate_bps);
                let builder = decimal_from_bps(builder_bps);
                let fee_exponent = Decimal::from(exponent);

                // Balance covers total_cost with margin. Use 10x as a generous
                // upper bound on cost-vs-amount even at extreme p, fee, and
                // builder values within the generator bounds.
                let total_cost =
                    compute_total_cost(amount, price, fee_rate, exponent, builder);
                let balance = total_cost * Decimal::from(10);

                let adjusted = adjust_market_buy_amount(
                    amount, balance, price, fee_rate, fee_exponent, builder,
                )
                .expect("non-binding balance must yield Ok");
                prop_assert_eq!(
                    adjusted, amount,
                    "non-binding branch must return the input amount unchanged",
                );
            }

            // Binding branch: balance < total_cost(amount). Function MUST
            // return Ok (assuming the divisor produces something >= 1 micro)
            // and the result MUST be strictly less than amount, at USDC scale,
            // and total_cost(adjusted) MUST fit inside balance.
            #[rstest]
            fn prop_adjust_market_buy_amount_binding_shrinks_into_balance(
                amount_micros in 1_000u64..=1_000_000_000u64,
                price_milli in 10u32..=990u32,
                fee_rate_bps in 0u32..=1_000u32,
                exponent in 0u32..=3u32,
                builder_bps in 0u32..=500u32,
                fraction_thousandths in 100u32..=900u32,
            ) {
                let amount = decimal_at_usdc_scale(amount_micros);
                let price = Decimal::new(i64::from(price_milli), 3);
                let fee_rate = decimal_from_bps(fee_rate_bps);
                let builder = decimal_from_bps(builder_bps);
                let fee_exponent = Decimal::from(exponent);

                // Balance set to a fraction (0.1 .. 0.9) of total_cost so the
                // shrink branch is always exercised with non-trivial values.
                let total_cost =
                    compute_total_cost(amount, price, fee_rate, exponent, builder);
                let fraction = Decimal::new(i64::from(fraction_thousandths), 3);
                let balance = (total_cost * fraction).trunc_with_scale(USDC_DECIMALS);
                if balance.is_zero() {
                    return Ok(()); // sub-micro balance hits the bail path; skip.
                }

                let adjusted = adjust_market_buy_amount(
                    amount, balance, price, fee_rate, fee_exponent, builder,
                )
                .expect("non-zero balance fraction must yield Ok in binding branch");

                prop_assert!(
                    adjusted < amount,
                    "binding branch must strictly shrink (adjusted={adjusted}, amount={amount})",
                );
                prop_assert!(
                    adjusted > Decimal::ZERO,
                    "adjusted must be strictly positive",
                );
                prop_assert_eq!(
                    adjusted,
                    adjusted.trunc_with_scale(USDC_DECIMALS),
                    "adjusted must be at USDC_DECIMALS scale",
                );
                let recomputed_cost =
                    compute_total_cost(adjusted, price, fee_rate, exponent, builder);
                prop_assert!(
                    recomputed_cost <= balance,
                    "total_cost {recomputed_cost} must fit balance {balance}",
                );
            }

            // Truncation property: when the input amount has sub-USDC
            // precision (e.g. amount derived from f64 math elsewhere in the
            // pipeline), the result is rounded down to USDC scale, never up.
            #[rstest]
            fn prop_adjust_market_buy_amount_truncates_subusdc_precision(
                amount_pico in 1_000_000u64..=1_000_000_000_000u64,
                price_milli in 1u32..=999u32,
                fee_rate_bps in 0u32..=1_000u32,
                exponent in 0u32..=3u32,
                builder_bps in 0u32..=500u32,
            ) {
                // Sample at 9 dp (pico-USDC) so amounts have 3 dp beyond the
                // USDC on-chain scale.
                let amount = Decimal::new(amount_pico as i64, 9);
                let price = Decimal::new(i64::from(price_milli), 3);
                let fee_rate = decimal_from_bps(fee_rate_bps);
                let builder = decimal_from_bps(builder_bps);
                let fee_exponent = Decimal::from(exponent);

                // Non-binding so we exercise the trunc-on-amount path.
                let total_cost =
                    compute_total_cost(amount, price, fee_rate, exponent, builder);
                let balance = total_cost * Decimal::from(10);

                if let Ok(adjusted) = adjust_market_buy_amount(
                    amount, balance, price, fee_rate, fee_exponent, builder,
                ) {
                    prop_assert_eq!(
                        adjusted,
                        adjusted.trunc_with_scale(USDC_DECIMALS),
                        "result must be at USDC_DECIMALS scale",
                    );
                    prop_assert!(
                        adjusted <= amount,
                        "truncation must round DOWN, never up (adjusted={adjusted}, amount={amount})",
                    );
                }
            }
        }
    }
}