Skip to main content

nautilus_lighter/http/
parse.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Parsers from Lighter REST payloads to Nautilus domain types.
17
18use anyhow::Context;
19use nautilus_core::UnixNanos;
20use nautilus_model::{
21    data::{
22        Bar, BarType, BookOrder, FundingRateUpdate, OrderBookDelta, OrderBookDeltas, TradeTick,
23    },
24    enums::{AggressorSide, BookAction, BookType, OrderSide, RecordFlag},
25    identifiers::{InstrumentId, Symbol, TradeId},
26    instruments::{CryptoPerpetual, CurrencyPair, Instrument, InstrumentAny},
27    orderbook::OrderBook,
28    types::{Currency, Money, Price, Quantity},
29};
30use rust_decimal::Decimal;
31
32use crate::{
33    common::{
34        enums::{LighterMarketStatus, LighterProductType},
35        parse::{
36            funding_rate_from_percent, parse_millis_to_nanos, parse_secs_to_nanos,
37            price_from_decimal, quantity_from_decimal,
38        },
39        symbol::{MarketRegistry, format_instrument_id_with_venue},
40    },
41    http::models::{
42        LighterCandle, LighterFunding, LighterFundingDirection, LighterOrderBook,
43        LighterOrderBookOrders, LighterPerpOrderBookDetail, LighterSimpleOrder,
44        LighterSpotOrderBookDetail, LighterTrade,
45    },
46};
47
48pub fn register_order_books(registry: &MarketRegistry, order_books: &[LighterOrderBook]) {
49    for order_book in order_books {
50        register_order_book(registry, order_book);
51    }
52}
53
54pub fn register_perp_order_book_details(
55    registry: &MarketRegistry,
56    details: &[LighterPerpOrderBookDetail],
57) {
58    for detail in details {
59        register_order_book(registry, &detail.order_book);
60    }
61}
62
63pub fn register_spot_order_book_details(
64    registry: &MarketRegistry,
65    details: &[LighterSpotOrderBookDetail],
66) {
67    for detail in details {
68        register_order_book(registry, &detail.order_book);
69    }
70}
71
72/// Parses Lighter order book metadata into Nautilus instruments and registers their market ids.
73///
74/// Skips markets with an unsupported market type.
75///
76/// # Errors
77///
78/// Returns an error if supported markets are present but no instrument definition can be converted.
79pub fn parse_order_book_details_instruments(
80    registry: &MarketRegistry,
81    perp_details: &[LighterPerpOrderBookDetail],
82    spot_details: &[LighterSpotOrderBookDetail],
83    ts_init: UnixNanos,
84) -> anyhow::Result<Vec<InstrumentAny>> {
85    parse_order_book_details_instruments_with_status(registry, perp_details, spot_details, ts_init)
86        .map(|instruments| {
87            instruments
88                .into_iter()
89                .map(|(instrument, _)| instrument)
90                .collect()
91        })
92}
93
94/// Parses Lighter order book metadata into Nautilus instruments and market statuses.
95///
96/// Skips markets with an unsupported market type.
97///
98/// # Errors
99///
100/// Returns an error if supported markets are present but no instrument definition can be converted.
101pub fn parse_order_book_details_instruments_with_status(
102    registry: &MarketRegistry,
103    perp_details: &[LighterPerpOrderBookDetail],
104    spot_details: &[LighterSpotOrderBookDetail],
105    ts_init: UnixNanos,
106) -> anyhow::Result<Vec<(InstrumentAny, LighterMarketStatus)>> {
107    let mut instruments = Vec::with_capacity(perp_details.len() + spot_details.len());
108    let mut first_error = None;
109    let mut supported_len = 0_usize;
110
111    for detail in perp_details {
112        if !is_supported_product(&detail.order_book) {
113            continue;
114        }
115
116        supported_len += 1;
117
118        match parse_perp_instrument(registry, detail, ts_init) {
119            Ok(instrument) => instruments.push((instrument, detail.order_book.status)),
120            Err(e) => {
121                log::warn!(
122                    "Skipping invalid Lighter perpetual instrument `{}`: {e}",
123                    detail.order_book.symbol,
124                );
125                first_error.get_or_insert_with(|| e.to_string());
126            }
127        }
128    }
129
130    for detail in spot_details {
131        if !is_supported_product(&detail.order_book) {
132            continue;
133        }
134
135        supported_len += 1;
136
137        match parse_spot_instrument(registry, detail, ts_init) {
138            Ok(instrument) => instruments.push((instrument, detail.order_book.status)),
139            Err(e) => {
140                log::warn!(
141                    "Skipping invalid Lighter spot instrument `{}`: {e}",
142                    detail.order_book.symbol,
143                );
144                first_error.get_or_insert_with(|| e.to_string());
145            }
146        }
147    }
148
149    if supported_len > 0 && instruments.is_empty() {
150        anyhow::bail!(
151            "failed to parse any of {supported_len} Lighter instruments: {}",
152            first_error.as_deref().unwrap_or("unknown parse error"),
153        );
154    }
155
156    Ok(instruments)
157}
158
159/// Parses a Lighter trade into a Nautilus [`TradeTick`].
160///
161/// # Errors
162///
163/// Returns an error if the price, size, timestamp, or trade id is invalid.
164pub fn parse_trade_tick(
165    trade: &LighterTrade,
166    instrument: &InstrumentAny,
167    ts_init: UnixNanos,
168) -> anyhow::Result<TradeTick> {
169    let price = price_from_decimal(trade.price, instrument.price_precision())?;
170    let size = quantity_from_decimal(trade.size, instrument.size_precision())?;
171    let aggressor_side = aggressor_side_from_is_maker_ask(trade.is_maker_ask);
172    let trade_id = match trade.trade_id_str.as_deref() {
173        Some(s) => TradeId::new_checked(s),
174        None => TradeId::new_checked(trade.trade_id.to_string()),
175    }
176    .context("invalid Lighter trade identifier")?;
177    let timestamp_ms =
178        u64::try_from(trade.timestamp).context("negative Lighter trade timestamp")?;
179    let ts_event = parse_millis_to_nanos(timestamp_ms)?;
180
181    TradeTick::new_checked(
182        instrument.id(),
183        price,
184        size,
185        aggressor_side,
186        trade_id,
187        ts_event,
188        ts_init,
189    )
190    .context("failed to construct TradeTick from Lighter trade")
191}
192
193/// Parses a Lighter candle into a Nautilus [`Bar`].
194///
195/// # Errors
196///
197/// Returns an error if any price, volume, or timestamp field cannot be converted.
198pub fn parse_candle_bar(
199    candle: &LighterCandle,
200    bar_type: BarType,
201    instrument: &InstrumentAny,
202    ts_init: UnixNanos,
203) -> anyhow::Result<Bar> {
204    anyhow::ensure!(
205        candle.open > Decimal::ZERO,
206        "non-positive candle open `{}`",
207        candle.open
208    );
209    anyhow::ensure!(
210        candle.high > Decimal::ZERO,
211        "non-positive candle high `{}`",
212        candle.high
213    );
214    anyhow::ensure!(
215        candle.low > Decimal::ZERO,
216        "non-positive candle low `{}`",
217        candle.low
218    );
219    anyhow::ensure!(
220        candle.close > Decimal::ZERO,
221        "non-positive candle close `{}`",
222        candle.close
223    );
224
225    let timestamp_ms =
226        u64::try_from(candle.timestamp).context("negative Lighter candle timestamp")?;
227    let ts_event = parse_millis_to_nanos(timestamp_ms)?;
228    let price_precision = instrument.price_precision();
229    let size_precision = instrument.size_precision();
230
231    let open = Price::from_decimal_dp(candle.open, price_precision)
232        .map_err(|e| anyhow::anyhow!("invalid candle open: {e}"))?;
233    let high = Price::from_decimal_dp(candle.high, price_precision)
234        .map_err(|e| anyhow::anyhow!("invalid candle high: {e}"))?;
235    let low = Price::from_decimal_dp(candle.low, price_precision)
236        .map_err(|e| anyhow::anyhow!("invalid candle low: {e}"))?;
237    let close = Price::from_decimal_dp(candle.close, price_precision)
238        .map_err(|e| anyhow::anyhow!("invalid candle close: {e}"))?;
239    anyhow::ensure!(
240        candle.volume_base.is_sign_positive(),
241        "negative candle volume `{}`",
242        candle.volume_base,
243    );
244    let volume = Quantity::from_decimal_dp(candle.volume_base, size_precision)
245        .map_err(|e| anyhow::anyhow!("invalid candle volume: {e}"))?;
246
247    Bar::new_checked(bar_type, open, high, low, close, volume, ts_event, ts_init)
248        .context("failed to construct Bar from Lighter candle")
249}
250
251/// Parses a Lighter historical funding row into a Nautilus [`FundingRateUpdate`].
252///
253/// Lighter returns `rate` as a magnitude and `direction` as the side paying
254/// the funding. Nautilus uses the conventional signed rate: positive when
255/// longs pay shorts and negative when shorts pay longs.
256///
257/// # Errors
258///
259/// Returns an error if the timestamp cannot be converted.
260pub fn parse_funding_rate_update(
261    funding: &LighterFunding,
262    instrument_id: InstrumentId,
263    interval: Option<u16>,
264    ts_init: UnixNanos,
265) -> anyhow::Result<FundingRateUpdate> {
266    let timestamp =
267        u64::try_from(funding.timestamp).context("negative Lighter funding timestamp")?;
268    let ts_event = parse_secs_to_nanos(timestamp)?;
269    let magnitude = funding_rate_from_percent(funding.rate);
270    let rate = match funding.direction {
271        LighterFundingDirection::Long => magnitude,
272        LighterFundingDirection::Short => -magnitude,
273    };
274
275    Ok(FundingRateUpdate::new(
276        instrument_id,
277        rate,
278        interval,
279        None,
280        ts_event,
281        ts_init,
282    ))
283}
284
285/// Parses an HTTP order book snapshot response into Nautilus order book deltas.
286///
287/// # Errors
288///
289/// Returns an error if any price or size cannot be converted.
290pub fn parse_order_book_snapshot(
291    snapshot: &LighterOrderBookOrders,
292    instrument_id: InstrumentId,
293    price_precision: u8,
294    size_precision: u8,
295    ts_event: UnixNanos,
296    ts_init: UnixNanos,
297) -> anyhow::Result<OrderBookDeltas> {
298    let total_levels = snapshot.bids.len() + snapshot.asks.len();
299    let mut deltas = Vec::with_capacity(total_levels + 1);
300    let mut clear = OrderBookDelta::clear(instrument_id, 0, ts_event, ts_init);
301
302    if total_levels == 0 {
303        clear.flags |= RecordFlag::F_LAST as u8;
304    }
305    deltas.push(clear);
306
307    let mut processed = 0_usize;
308
309    for bid in &snapshot.bids {
310        let price = price_from_decimal(bid.price, price_precision)?;
311        let size = quantity_from_decimal(bid.remaining_base_amount, size_precision)?;
312        let order_id =
313            u64::try_from(bid.order_index).context("negative Lighter bid order index")?;
314        let order = BookOrder::new(OrderSide::Buy, price, size, order_id);
315        processed += 1;
316        let sequence = processed as u64;
317        let delta = OrderBookDelta::new_checked(
318            instrument_id,
319            BookAction::Add,
320            order,
321            snapshot_flags(processed, total_levels),
322            sequence,
323            ts_event,
324            ts_init,
325        )
326        .context("failed to construct Lighter bid snapshot delta")?;
327        deltas.push(delta);
328    }
329
330    for ask in &snapshot.asks {
331        let price = price_from_decimal(ask.price, price_precision)?;
332        let size = quantity_from_decimal(ask.remaining_base_amount, size_precision)?;
333        let order_id =
334            u64::try_from(ask.order_index).context("negative Lighter ask order index")?;
335        let order = BookOrder::new(OrderSide::Sell, price, size, order_id);
336        processed += 1;
337        let sequence = processed as u64;
338        let delta = OrderBookDelta::new_checked(
339            instrument_id,
340            BookAction::Add,
341            order,
342            snapshot_flags(processed, total_levels),
343            sequence,
344            ts_event,
345            ts_init,
346        )
347        .context("failed to construct Lighter ask snapshot delta")?;
348        deltas.push(delta);
349    }
350
351    OrderBookDeltas::new_checked(instrument_id, deltas)
352        .context("failed to construct OrderBookDeltas from Lighter order book snapshot")
353}
354
355/// Parses an HTTP `orderBookOrders` snapshot into an aggregated [`OrderBook`].
356///
357/// The REST endpoint returns each resting order separately, while WebSocket
358/// `order_book` updates carry already-aggregated price levels. To keep
359/// snapshot semantics consistent with the live feed, sizes are summed per
360/// price on each side and added as a single L2 entry per level.
361///
362/// The snapshot itself carries no venue timestamp (Lighter's `LighterSimpleOrder`
363/// `transaction_time` is `0` for resting orders), so the constructed book's
364/// `ts_last` is left at [`UnixNanos::default`]. The first WebSocket delta
365/// applied after the snapshot will install a real venue timestamp and avoid
366/// spurious "out-of-order" warnings against a wall-clock placeholder.
367#[must_use]
368pub fn parse_l2_order_book_snapshot(
369    snapshot: &LighterOrderBookOrders,
370    instrument_id: InstrumentId,
371    price_precision: u8,
372    size_precision: u8,
373) -> OrderBook {
374    let mut book = OrderBook::new(instrument_id, BookType::L2_MBP);
375    let mut sequence: u64 = 0;
376    let ts_event = UnixNanos::default();
377
378    let bid_levels = aggregate_order_levels(&snapshot.bids, price_precision, size_precision);
379    let ask_levels = aggregate_order_levels(&snapshot.asks, price_precision, size_precision);
380
381    sequence += 1;
382    book.clear(sequence, ts_event);
383
384    for (price, size) in bid_levels {
385        sequence += 1;
386        let order = BookOrder::new(OrderSide::Buy, price, size, 0);
387        book.add(order, BookAction::Add as u8, sequence, ts_event);
388    }
389
390    for (price, size) in ask_levels {
391        sequence += 1;
392        let order = BookOrder::new(OrderSide::Sell, price, size, 0);
393        book.add(order, BookAction::Add as u8, sequence, ts_event);
394    }
395
396    book
397}
398
399fn aggregate_order_levels(
400    orders: &[LighterSimpleOrder],
401    price_precision: u8,
402    size_precision: u8,
403) -> Vec<(Price, Quantity)> {
404    use std::collections::BTreeMap;
405
406    let mut levels: BTreeMap<Decimal, Decimal> = BTreeMap::new();
407
408    for order in orders {
409        if !order.remaining_base_amount.is_sign_positive() || order.remaining_base_amount.is_zero()
410        {
411            continue;
412        }
413        *levels.entry(order.price).or_insert(Decimal::ZERO) += order.remaining_base_amount;
414    }
415
416    levels
417        .into_iter()
418        .filter_map(|(price, size)| {
419            let price = match Price::from_decimal_dp(price, price_precision) {
420                Ok(p) => p,
421                Err(e) => {
422                    log::warn!("Skipping Lighter snapshot price `{price}`: {e}");
423                    return None;
424                }
425            };
426            let size = match Quantity::from_decimal_dp(size, size_precision) {
427                Ok(q) => q,
428                Err(e) => {
429                    log::warn!("Skipping Lighter snapshot size `{size}`: {e}");
430                    return None;
431                }
432            };
433            Some((price, size))
434        })
435        .collect()
436}
437
438fn aggressor_side_from_is_maker_ask(is_maker_ask: bool) -> AggressorSide {
439    if is_maker_ask {
440        AggressorSide::Buy
441    } else {
442        AggressorSide::Sell
443    }
444}
445
446fn snapshot_flags(processed: usize, total_levels: usize) -> u8 {
447    let mut flags = RecordFlag::F_SNAPSHOT as u8;
448    if processed == total_levels {
449        flags |= RecordFlag::F_LAST as u8;
450    }
451    flags
452}
453
454fn register_order_book(registry: &MarketRegistry, order_book: &LighterOrderBook) {
455    if !is_supported_product(order_book) {
456        return;
457    }
458
459    registry.insert(
460        order_book.market_id,
461        order_book.symbol.as_str(),
462        order_book.market_type,
463    );
464}
465
466fn is_supported_product(order_book: &LighterOrderBook) -> bool {
467    let market_type = order_book.market_type;
468    if market_type.is_supported() {
469        return true;
470    }
471
472    let symbol = order_book.symbol;
473    let market_id = order_book.market_id;
474
475    if market_type == LighterProductType::Other {
476        log::warn!(
477            "Skipping Lighter market `{symbol}` (market_id={market_id}): unfamiliar market type"
478        );
479    } else {
480        log::debug!(
481            "Skipping Lighter market `{symbol}` (market_id={market_id}): unsupported market type `{market_type}`"
482        );
483    }
484
485    false
486}
487
488fn parse_perp_instrument(
489    registry: &MarketRegistry,
490    detail: &LighterPerpOrderBookDetail,
491    ts_init: UnixNanos,
492) -> anyhow::Result<InstrumentAny> {
493    let order_book = &detail.order_book;
494
495    let instrument_id = format_instrument_id_with_venue(
496        order_book.symbol.as_str(),
497        order_book.market_type,
498        registry.venue(),
499    );
500
501    let raw_symbol = Symbol::from_ustr_unchecked(order_book.symbol);
502    let settlement_currency = registry.settlement_currency();
503
504    let (base_currency, quote_currency) = symbol_currencies(
505        order_book.symbol.as_str(),
506        settlement_currency.code.as_str(),
507    );
508
509    let price_increment = price_increment(detail.price_decimals)?;
510    let size_increment = quantity_increment(detail.size_decimals)?;
511
512    let instrument = CryptoPerpetual::builder()
513        .instrument_id(instrument_id)
514        .raw_symbol(raw_symbol)
515        .base_currency(base_currency)
516        .quote_currency(quote_currency)
517        .settlement_currency(settlement_currency)
518        .is_inverse(false)
519        .price_precision(detail.price_decimals)
520        .size_precision(detail.size_decimals)
521        .price_increment(price_increment)
522        .size_increment(size_increment)
523        .maybe_min_quantity(min_quantity(order_book, detail.size_decimals)?)
524        .maybe_max_notional(max_notional(order_book, quote_currency)?)
525        .maybe_min_notional(min_notional(order_book, quote_currency)?)
526        .margin_init(margin_fraction(detail.default_initial_margin_fraction))
527        .margin_maint(margin_fraction(detail.maintenance_margin_fraction))
528        .ts_event(ts_init)
529        .ts_init(ts_init)
530        .build()
531        .map_err(|e| anyhow::anyhow!("{e}"))?;
532
533    registry.insert(
534        order_book.market_id,
535        order_book.symbol.as_str(),
536        order_book.market_type,
537    );
538
539    Ok(InstrumentAny::CryptoPerpetual(instrument))
540}
541
542fn parse_spot_instrument(
543    registry: &MarketRegistry,
544    detail: &LighterSpotOrderBookDetail,
545    ts_init: UnixNanos,
546) -> anyhow::Result<InstrumentAny> {
547    let order_book = &detail.order_book;
548
549    let instrument_id = format_instrument_id_with_venue(
550        order_book.symbol.as_str(),
551        order_book.market_type,
552        registry.venue(),
553    );
554
555    let raw_symbol = Symbol::from_ustr_unchecked(order_book.symbol);
556    let (base_currency, quote_currency) = spot_symbol_currencies(order_book.symbol.as_str())?;
557    let price_increment = price_increment(detail.price_decimals)?;
558    let size_increment = quantity_increment(detail.size_decimals)?;
559
560    let instrument = CurrencyPair::builder()
561        .instrument_id(instrument_id)
562        .raw_symbol(raw_symbol)
563        .base_currency(base_currency)
564        .quote_currency(quote_currency)
565        .price_precision(detail.price_decimals)
566        .size_precision(detail.size_decimals)
567        .price_increment(price_increment)
568        .size_increment(size_increment)
569        .maybe_min_quantity(min_quantity(order_book, detail.size_decimals)?)
570        .maybe_max_notional(max_notional(order_book, quote_currency)?)
571        .maybe_min_notional(min_notional(order_book, quote_currency)?)
572        .ts_event(ts_init)
573        .ts_init(ts_init)
574        .build()
575        .map_err(|e| anyhow::anyhow!("{e}"))?;
576
577    registry.insert(
578        order_book.market_id,
579        order_book.symbol.as_str(),
580        order_book.market_type,
581    );
582
583    Ok(InstrumentAny::CurrencyPair(instrument))
584}
585
586fn spot_symbol_currencies(symbol: &str) -> anyhow::Result<(Currency, Currency)> {
587    let (base, quote) = symbol
588        .split_once('/')
589        .context("Lighter spot symbol must use BASE/QUOTE format")?;
590    let base = base.trim();
591    let quote = quote.trim();
592    anyhow::ensure!(
593        !base.is_empty() && !quote.is_empty() && !quote.contains('/'),
594        "Lighter spot symbol must contain one nonempty BASE/QUOTE pair",
595    );
596
597    Ok((
598        Currency::get_or_create_crypto(base),
599        Currency::get_or_create_crypto(quote),
600    ))
601}
602
603fn symbol_currencies(symbol: &str, default_quote: &str) -> (Currency, Currency) {
604    let (base, quote) = symbol.split_once('/').unwrap_or((symbol, default_quote));
605    (
606        Currency::get_or_create_crypto(base),
607        Currency::get_or_create_crypto(quote),
608    )
609}
610
611fn price_increment(decimals: u8) -> anyhow::Result<Price> {
612    Price::from_decimal_dp(decimal_increment(decimals), decimals)
613        .map_err(|e| anyhow::anyhow!("{e}"))
614}
615
616fn quantity_increment(decimals: u8) -> anyhow::Result<Quantity> {
617    Quantity::from_decimal_dp(decimal_increment(decimals), decimals)
618        .map_err(|e| anyhow::anyhow!("{e}"))
619}
620
621// `10^-decimals` as an exact decimal (e.g. 3 -> 0.001, 0 -> 1).
622fn decimal_increment(decimals: u8) -> Decimal {
623    Decimal::new(1, u32::from(decimals))
624}
625
626fn min_quantity(
627    order_book: &LighterOrderBook,
628    size_decimals: u8,
629) -> anyhow::Result<Option<Quantity>> {
630    quantity_from_decimal(order_book.min_base_amount, size_decimals).map(Some)
631}
632
633fn min_notional(
634    order_book: &LighterOrderBook,
635    currency: Currency,
636) -> anyhow::Result<Option<Money>> {
637    money_from_decimal(order_book.min_quote_amount, currency).map(Some)
638}
639
640fn max_notional(
641    order_book: &LighterOrderBook,
642    currency: Currency,
643) -> anyhow::Result<Option<Money>> {
644    money_from_decimal(order_book.order_quote_limit, currency).map(Some)
645}
646
647fn money_from_decimal(value: Decimal, currency: Currency) -> anyhow::Result<Money> {
648    Money::from_decimal(value, currency).map_err(|e| anyhow::anyhow!("{e}"))
649}
650
651fn margin_fraction(value: u16) -> Decimal {
652    Decimal::from(value) / Decimal::from(10_000)
653}
654
655#[cfg(test)]
656mod tests {
657    use std::str::FromStr;
658
659    use nautilus_model::{
660        data::{BarSpecification, BarType},
661        enums::{AggregationSource, BarAggregation, PriceType},
662        identifiers::{InstrumentId, Symbol, Venue},
663        instruments::CryptoPerpetual,
664        types::{Money, Price, Quantity, currency::Currency},
665    };
666    use rstest::rstest;
667    use rust_decimal::Decimal;
668    use ustr::Ustr;
669
670    use super::*;
671    use crate::{
672        common::enums::{LighterMarketStatus, LighterPositionMarginMode, LighterTradeType},
673        http::models::{
674            LighterCandles, LighterFunding, LighterFundingDirection, LighterMarketConfig,
675            LighterOrderBookDetails, LighterSimpleOrder,
676        },
677    };
678
679    const HTTP_CANDLES: &str = include_str!("../../test_data/http_candles.json");
680    const HTTP_ORDER_BOOK_DETAILS_WIDENED_IDS: &str =
681        include_str!("../../test_data/http_order_book_details_widened_ids.json");
682
683    fn create_test_instrument() -> InstrumentAny {
684        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), Venue::new("LIGHTER"));
685
686        InstrumentAny::CryptoPerpetual(
687            CryptoPerpetual::builder()
688                .instrument_id(instrument_id)
689                .raw_symbol(Symbol::new("ETH-PERP"))
690                .base_currency(Currency::from("ETH"))
691                .quote_currency(Currency::from("USDC"))
692                .settlement_currency(Currency::from("USDC"))
693                .is_inverse(false)
694                .price_precision(2)
695                .size_precision(4)
696                .price_increment(Price::from("0.01"))
697                .size_increment(Quantity::from("0.0001"))
698                .ts_event(UnixNanos::default())
699                .ts_init(UnixNanos::default())
700                .build()
701                .unwrap(),
702        )
703    }
704
705    fn stub_trade(is_maker_ask: bool) -> LighterTrade {
706        LighterTrade {
707            trade_id: 19209006902,
708            trade_id_str: Some("19209006902".to_string()),
709            tx_hash: "000000128b1ee814".to_string(),
710            trade_type: LighterTradeType::Trade,
711            market_id: 0,
712            size: Decimal::from_str("0.1336").unwrap(),
713            price: Decimal::from_str("2352.73").unwrap(),
714            usd_amount: Decimal::from_str("314.343").unwrap(),
715            ask_id: 281476929510102,
716            ask_id_str: Some("281476929510102".to_string()),
717            bid_id: 562947905631053,
718            bid_id_str: Some("562947905631053".to_string()),
719            ask_client_id: 0,
720            ask_client_id_str: Some("0".to_string()),
721            bid_client_id: 7001011966,
722            bid_client_id_str: Some("7001011966".to_string()),
723            ask_account_id: 91249,
724            bid_account_id: 281474976618239,
725            is_maker_ask,
726            block_height: 227535535,
727            timestamp: 1777941384181,
728            taker_fee: Some(238),
729            taker_position_size_before: Some(Decimal::from_str("-31.5754").unwrap()),
730            taker_entry_quote_before: Some(Decimal::from_str("72515.683629").unwrap()),
731            taker_initial_margin_fraction_before: Some(200),
732            taker_position_sign_changed: None,
733            maker_fee: Some(34),
734            maker_position_size_before: Some(Decimal::from_str("-1.4442").unwrap()),
735            maker_entry_quote_before: Some(Decimal::from_str("3399.343032").unwrap()),
736            maker_initial_margin_fraction_before: Some(500),
737            maker_position_sign_changed: None,
738            transaction_time: 1777941384181586,
739            ask_account_pnl: None,
740            bid_account_pnl: None,
741        }
742    }
743
744    fn stub_order_book(
745        symbol: &str,
746        market_id: i64,
747        market_type: LighterProductType,
748    ) -> LighterOrderBook {
749        LighterOrderBook {
750            symbol: Ustr::from(symbol),
751            market_id,
752            market_type,
753            base_asset_id: 0,
754            quote_asset_id: 0,
755            status: LighterMarketStatus::Active,
756            taker_fee: Decimal::ZERO,
757            maker_fee: Decimal::ZERO,
758            liquidation_fee: Decimal::from_str("1.0000").unwrap(),
759            min_base_amount: Decimal::from_str("0.0050").unwrap(),
760            min_quote_amount: Decimal::from_str("10.000000").unwrap(),
761            order_quote_limit: Decimal::from_str("281474976.710655").unwrap(),
762            supported_size_decimals: 4,
763            supported_price_decimals: 2,
764            supported_quote_decimals: 6,
765        }
766    }
767
768    fn stub_perp_detail(symbol: &str, market_id: i64) -> LighterPerpOrderBookDetail {
769        LighterPerpOrderBookDetail {
770            order_book: stub_order_book(symbol, market_id, LighterProductType::Perp),
771            size_decimals: 4,
772            price_decimals: 2,
773            quote_multiplier: 1,
774            default_initial_margin_fraction: 500,
775            min_initial_margin_fraction: 200,
776            maintenance_margin_fraction: 120,
777            closeout_margin_fraction: 80,
778            last_trade_price: Decimal::new(235_273, 2),
779            daily_trades_count: 0,
780            daily_base_token_volume: Decimal::ZERO,
781            daily_quote_token_volume: Decimal::ZERO,
782            daily_price_low: Decimal::ZERO,
783            daily_price_high: Decimal::ZERO,
784            daily_price_change: Decimal::ZERO,
785            open_interest: Decimal::ZERO,
786            daily_chart: Default::default(),
787            market_config: LighterMarketConfig {
788                market_margin_mode: LighterPositionMarginMode::Cross,
789                insurance_fund_account_index: 281474976710655,
790                liquidation_mode: 0,
791                force_reduce_only: false,
792                trading_hours: String::new(),
793                funding_fee_discounts_enabled: Some(false),
794                hidden: false,
795                rfq_enabled: true,
796            },
797            strategy_index: 2,
798        }
799    }
800
801    fn stub_spot_detail(symbol: &str, market_id: i64) -> LighterSpotOrderBookDetail {
802        LighterSpotOrderBookDetail {
803            order_book: stub_order_book(symbol, market_id, LighterProductType::Spot),
804            size_decimals: 6,
805            price_decimals: 6,
806            last_trade_price: Decimal::ONE,
807            daily_trades_count: 0,
808            daily_base_token_volume: Decimal::ZERO,
809            daily_quote_token_volume: Decimal::ZERO,
810            daily_price_low: Decimal::ZERO,
811            daily_price_high: Decimal::ZERO,
812            daily_price_change: Decimal::ZERO,
813            daily_chart: Default::default(),
814        }
815    }
816
817    #[rstest]
818    fn test_parse_trade_tick_maps_aggressor_from_maker_side() {
819        let instrument = create_test_instrument();
820        let ts_init = UnixNanos::from(1);
821
822        let seller = parse_trade_tick(&stub_trade(false), &instrument, ts_init).unwrap();
823        let buyer = parse_trade_tick(&stub_trade(true), &instrument, ts_init).unwrap();
824
825        assert_eq!(seller.aggressor_side, AggressorSide::Sell);
826        assert_eq!(buyer.aggressor_side, AggressorSide::Buy);
827        assert_eq!(seller.price, Price::from("2352.73"));
828        assert_eq!(seller.size, Quantity::from("0.1336"));
829        assert_eq!(seller.trade_id.to_string(), "19209006902");
830        assert_eq!(seller.ts_event, UnixNanos::from(1_777_941_384_181_000_000),);
831    }
832
833    #[rstest]
834    fn test_parse_trade_tick_uses_numeric_trade_id_when_string_missing() {
835        let instrument = create_test_instrument();
836        let mut trade = stub_trade(false);
837        trade.trade_id_str = None;
838
839        let tick = parse_trade_tick(&trade, &instrument, UnixNanos::from(1)).unwrap();
840
841        assert_eq!(tick.trade_id.to_string(), "19209006902");
842    }
843
844    #[rstest]
845    fn test_parse_trade_tick_rejects_negative_timestamp() {
846        let instrument = create_test_instrument();
847        let mut trade = stub_trade(false);
848        trade.timestamp = -1;
849
850        let err = parse_trade_tick(&trade, &instrument, UnixNanos::from(1)).unwrap_err();
851
852        assert!(err.to_string().contains("negative Lighter trade timestamp"));
853    }
854
855    #[rstest]
856    fn test_parse_trade_tick_propagates_invalid_price() {
857        // With the Decimal model field invalid wire data is rejected at JSON
858        // deserialize time, before parse_trade_tick ever runs. This guards
859        // that a malformed `price` in the venue payload surfaces a parse error
860        // rather than silently constructing a zero-priced tick.
861        let payload = serde_json::json!({
862            "trade_id": 1,
863            "tx_hash": "deadbeef",
864            "type": "trade",
865            "market_id": 0,
866            "size": "1.0",
867            "price": "not-a-price",
868            "usd_amount": "0",
869            "ask_id": 0,
870            "bid_id": 0,
871            "ask_client_id": 0,
872            "bid_client_id": 0,
873            "ask_account_id": 0,
874            "bid_account_id": 0,
875            "is_maker_ask": false,
876            "block_height": 0,
877            "timestamp": 1,
878            "transaction_time": 1,
879        });
880
881        let err = serde_json::from_value::<LighterTrade>(payload).unwrap_err();
882        assert!(err.to_string().to_lowercase().contains("decimal"));
883    }
884
885    #[rstest]
886    fn test_parse_funding_rate_update_maps_direction_to_signed_rate() {
887        let instrument = create_test_instrument();
888        let ts_init = UnixNanos::from(1);
889        let long_pays = LighterFunding {
890            timestamp: 1_778_702_400,
891            value: Decimal::ZERO,
892            rate: Decimal::new(12, 4),
893            direction: LighterFundingDirection::Long,
894        };
895        let short_pays = LighterFunding {
896            direction: LighterFundingDirection::Short,
897            ..long_pays
898        };
899
900        let positive =
901            parse_funding_rate_update(&long_pays, instrument.id(), Some(60), ts_init).unwrap();
902        let negative =
903            parse_funding_rate_update(&short_pays, instrument.id(), Some(60), ts_init).unwrap();
904
905        assert_eq!(positive.instrument_id, instrument.id());
906        assert_eq!(positive.rate, Decimal::new(12, 6));
907        assert_eq!(positive.interval, Some(60));
908        assert_eq!(
909            positive.ts_event,
910            UnixNanos::from(1_778_702_400_000_000_000)
911        );
912        assert_eq!(negative.rate, Decimal::new(-12, 6));
913    }
914
915    #[rstest]
916    fn test_parse_funding_rate_update_rejects_negative_timestamp() {
917        let instrument = create_test_instrument();
918        let funding = LighterFunding {
919            timestamp: -1,
920            value: Decimal::ZERO,
921            rate: Decimal::new(12, 4),
922            direction: LighterFundingDirection::Long,
923        };
924
925        let err = parse_funding_rate_update(&funding, instrument.id(), None, UnixNanos::from(1))
926            .unwrap_err();
927
928        assert!(
929            err.to_string()
930                .contains("negative Lighter funding timestamp")
931        );
932    }
933
934    fn test_bar_type(instrument_id: InstrumentId) -> BarType {
935        BarType::new(
936            instrument_id,
937            BarSpecification::new(1, BarAggregation::Minute, PriceType::Last),
938            AggregationSource::External,
939        )
940    }
941
942    #[rstest]
943    fn test_parse_candle_bar_loads_fixture() {
944        let instrument = create_test_instrument();
945        let bar_type = test_bar_type(instrument.id());
946        let candles: LighterCandles = serde_json::from_str(HTTP_CANDLES).unwrap();
947        let candle = &candles.candles[0];
948
949        let bar = parse_candle_bar(candle, bar_type, &instrument, UnixNanos::from(42)).unwrap();
950
951        assert_eq!(bar.bar_type, bar_type);
952        assert_eq!(bar.open, Price::from("2361.11"));
953        assert_eq!(bar.high, Price::from("2362.22"));
954        assert_eq!(bar.low, Price::from("2360.00"));
955        assert_eq!(bar.close, Price::from("2361.31"));
956        assert_eq!(bar.volume, Quantity::from("1.2345"));
957        assert_eq!(bar.ts_event, UnixNanos::from(1_700_000_000_000_000_000));
958        assert_eq!(bar.ts_init, UnixNanos::from(42));
959    }
960
961    #[rstest]
962    fn test_parse_candle_bar_rejects_negative_timestamp() {
963        let instrument = create_test_instrument();
964        let bar_type = test_bar_type(instrument.id());
965        let candles: LighterCandles = serde_json::from_str(HTTP_CANDLES).unwrap();
966        let mut candle = candles.candles[0].clone();
967        candle.timestamp = -1;
968
969        let err = parse_candle_bar(&candle, bar_type, &instrument, UnixNanos::from(1)).unwrap_err();
970
971        assert!(
972            err.to_string()
973                .contains("negative Lighter candle timestamp")
974        );
975    }
976
977    #[rstest]
978    #[case("open", Decimal::ZERO)]
979    #[case("open", Decimal::NEGATIVE_ONE)]
980    #[case("high", Decimal::ZERO)]
981    #[case("high", Decimal::NEGATIVE_ONE)]
982    #[case("low", Decimal::ZERO)]
983    #[case("low", Decimal::NEGATIVE_ONE)]
984    #[case("close", Decimal::ZERO)]
985    #[case("close", Decimal::NEGATIVE_ONE)]
986    fn test_parse_candle_bar_rejects_non_positive_ohlc(
987        #[case] field: &str,
988        #[case] value: Decimal,
989    ) {
990        let instrument = create_test_instrument();
991        let bar_type = test_bar_type(instrument.id());
992        let candles: LighterCandles = serde_json::from_str(HTTP_CANDLES).unwrap();
993        let mut candle = candles.candles[0].clone();
994        match field {
995            "open" => candle.open = value,
996            "high" => candle.high = value,
997            "low" => candle.low = value,
998            "close" => candle.close = value,
999            _ => unreachable!(),
1000        }
1001
1002        let error =
1003            parse_candle_bar(&candle, bar_type, &instrument, UnixNanos::from(1)).unwrap_err();
1004
1005        assert!(
1006            error
1007                .to_string()
1008                .contains(&format!("non-positive candle {field}")),
1009        );
1010    }
1011
1012    // The previous string-roundtrip implementation rejected negative volume
1013    // implicitly via `parse_quantity`'s decimal sign check. The current
1014    // direct-Decimal implementation enforces the same constraint with an
1015    // explicit `is_sign_positive` ensure-clause; without this test a future
1016    // refactor could drop the guard silently and produce a malformed bar.
1017    #[rstest]
1018    fn test_parse_candle_bar_rejects_negative_volume() {
1019        let instrument = create_test_instrument();
1020        let bar_type = test_bar_type(instrument.id());
1021        let candles: LighterCandles = serde_json::from_str(HTTP_CANDLES).unwrap();
1022        let mut candle = candles.candles[0].clone();
1023        candle.volume_base = Decimal::new(-1, 0);
1024
1025        let err = parse_candle_bar(&candle, bar_type, &instrument, UnixNanos::from(1)).unwrap_err();
1026
1027        assert!(
1028            err.to_string().contains("negative candle volume"),
1029            "expected negative-volume error, was: {err}",
1030        );
1031    }
1032
1033    #[rstest]
1034    fn test_parse_order_book_snapshot_includes_clear_and_last_flag() {
1035        let instrument = create_test_instrument();
1036        let snapshot = LighterOrderBookOrders {
1037            code: 200,
1038            message: None,
1039            total_asks: 1,
1040            asks: vec![LighterSimpleOrder {
1041                order_index: 281476929510110,
1042                order_id: "281476929510110".to_string(),
1043                owner_account_index: 712440,
1044                initial_base_amount: Decimal::from_str("0.0050").unwrap(),
1045                remaining_base_amount: Decimal::from_str("0.0050").unwrap(),
1046                price: Decimal::from_str("2352.74").unwrap(),
1047                order_expiry: 1780360584479,
1048                transaction_time: 0,
1049            }],
1050            total_bids: 1,
1051            bids: vec![LighterSimpleOrder {
1052                order_index: 562947905631047,
1053                order_id: "562947905631047".to_string(),
1054                owner_account_index: 281474976619400,
1055                initial_base_amount: Decimal::from_str("0.2125").unwrap(),
1056                remaining_base_amount: Decimal::from_str("0.2125").unwrap(),
1057                price: Decimal::from_str("2352.71").unwrap(),
1058                order_expiry: 1780360585134,
1059                transaction_time: 0,
1060            }],
1061        };
1062        let ts_event = UnixNanos::from(10);
1063        let ts_init = UnixNanos::from(20);
1064
1065        let deltas = parse_order_book_snapshot(
1066            &snapshot,
1067            instrument.id(),
1068            instrument.price_precision(),
1069            instrument.size_precision(),
1070            ts_event,
1071            ts_init,
1072        )
1073        .unwrap();
1074
1075        assert_eq!(deltas.deltas.len(), 3);
1076        assert_eq!(deltas.deltas[0].action, BookAction::Clear);
1077        assert_eq!(deltas.deltas[1].order.side, OrderSide::Buy.into());
1078        assert_eq!(deltas.deltas[1].order.price, Price::from("2352.71"));
1079        assert_eq!(deltas.deltas[1].order.size, Quantity::from("0.2125"));
1080        assert_eq!(deltas.deltas[2].order.side, OrderSide::Sell.into());
1081        assert_eq!(deltas.deltas[2].order.price, Price::from("2352.74"));
1082        assert_eq!(deltas.deltas[2].order.size, Quantity::from("0.0050"));
1083        assert_eq!(deltas.deltas[0].sequence, 0);
1084        assert_eq!(deltas.deltas[1].sequence, 1);
1085        assert_eq!(deltas.deltas[2].sequence, 2);
1086        assert_eq!(deltas.sequence, 2);
1087        assert_eq!(
1088            deltas.deltas[2].flags & RecordFlag::F_LAST as u8,
1089            RecordFlag::F_LAST as u8
1090        );
1091    }
1092
1093    #[rstest]
1094    fn test_parse_order_book_snapshot_marks_empty_clear_as_last() {
1095        let instrument = create_test_instrument();
1096        let snapshot = LighterOrderBookOrders {
1097            code: 200,
1098            message: None,
1099            total_asks: 0,
1100            asks: vec![],
1101            total_bids: 0,
1102            bids: vec![],
1103        };
1104
1105        let deltas = parse_order_book_snapshot(
1106            &snapshot,
1107            instrument.id(),
1108            instrument.price_precision(),
1109            instrument.size_precision(),
1110            UnixNanos::from(10),
1111            UnixNanos::from(20),
1112        )
1113        .unwrap();
1114
1115        assert_eq!(deltas.deltas.len(), 1);
1116        assert_eq!(deltas.deltas[0].action, BookAction::Clear);
1117        assert_eq!(
1118            deltas.deltas[0].flags & RecordFlag::F_LAST as u8,
1119            RecordFlag::F_LAST as u8,
1120        );
1121    }
1122
1123    #[rstest]
1124    fn test_parse_order_book_snapshot_rejects_negative_order_index() {
1125        let instrument = create_test_instrument();
1126        let snapshot = LighterOrderBookOrders {
1127            code: 200,
1128            message: None,
1129            total_asks: 0,
1130            asks: vec![],
1131            total_bids: 1,
1132            bids: vec![LighterSimpleOrder {
1133                order_index: -1,
1134                order_id: "-1".to_string(),
1135                owner_account_index: 281474976619400,
1136                initial_base_amount: Decimal::from_str("0.2125").unwrap(),
1137                remaining_base_amount: Decimal::from_str("0.2125").unwrap(),
1138                price: Decimal::from_str("2352.71").unwrap(),
1139                order_expiry: 1780360585134,
1140                transaction_time: 0,
1141            }],
1142        };
1143
1144        let err = parse_order_book_snapshot(
1145            &snapshot,
1146            instrument.id(),
1147            instrument.price_precision(),
1148            instrument.size_precision(),
1149            UnixNanos::from(10),
1150            UnixNanos::from(20),
1151        )
1152        .unwrap_err();
1153
1154        assert!(err.to_string().contains("negative Lighter bid order index"));
1155    }
1156
1157    #[rstest]
1158    fn test_parse_order_book_snapshot_rejects_zero_size_level() {
1159        let instrument = create_test_instrument();
1160        let snapshot = LighterOrderBookOrders {
1161            code: 200,
1162            message: None,
1163            total_asks: 0,
1164            asks: vec![],
1165            total_bids: 1,
1166            bids: vec![LighterSimpleOrder {
1167                order_index: 562947905631047,
1168                order_id: "562947905631047".to_string(),
1169                owner_account_index: 281474976619400,
1170                initial_base_amount: Decimal::from_str("0.2125").unwrap(),
1171                remaining_base_amount: Decimal::ZERO,
1172                price: Decimal::from_str("2352.71").unwrap(),
1173                order_expiry: 1780360585134,
1174                transaction_time: 0,
1175            }],
1176        };
1177
1178        let err = parse_order_book_snapshot(
1179            &snapshot,
1180            instrument.id(),
1181            instrument.price_precision(),
1182            instrument.size_precision(),
1183            UnixNanos::from(10),
1184            UnixNanos::from(20),
1185        )
1186        .unwrap_err();
1187
1188        assert!(
1189            err.to_string()
1190                .contains("failed to construct Lighter bid snapshot delta")
1191        );
1192    }
1193
1194    fn stub_simple_order(price: &str, remaining_base_amount: &str) -> LighterSimpleOrder {
1195        let amount = Decimal::from_str(remaining_base_amount).unwrap();
1196        let price = Decimal::from_str(price).unwrap();
1197        LighterSimpleOrder {
1198            order_index: 0,
1199            order_id: "0".to_string(),
1200            owner_account_index: 0,
1201            initial_base_amount: amount,
1202            remaining_base_amount: amount,
1203            price,
1204            order_expiry: 0,
1205            transaction_time: 0,
1206        }
1207    }
1208
1209    #[rstest]
1210    fn test_parse_l2_order_book_snapshot_two_sided_aggregates_per_price() {
1211        let instrument = create_test_instrument();
1212        let snapshot = LighterOrderBookOrders {
1213            code: 200,
1214            message: None,
1215            total_asks: 3,
1216            asks: vec![
1217                stub_simple_order("2352.74", "0.0050"),
1218                stub_simple_order("2353.00", "1.0000"),
1219                stub_simple_order("2354.00", "2.0000"),
1220            ],
1221            total_bids: 2,
1222            // Two orders at the same bid price must aggregate into one level.
1223            bids: vec![
1224                stub_simple_order("2000.00", "0.0100"),
1225                stub_simple_order("2000.00", "0.0200"),
1226            ],
1227        };
1228
1229        let book = parse_l2_order_book_snapshot(
1230            &snapshot,
1231            instrument.id(),
1232            instrument.price_precision(),
1233            instrument.size_precision(),
1234        );
1235
1236        assert_eq!(book.book_type, BookType::L2_MBP);
1237        assert_eq!(book.instrument_id, instrument.id());
1238        assert_eq!(book.best_bid_price(), Some(Price::from("2000.00")));
1239        assert_eq!(book.best_bid_size(), Some(Quantity::from("0.0300")));
1240        assert_eq!(book.best_ask_price(), Some(Price::from("2352.74")));
1241        assert_eq!(book.best_ask_size(), Some(Quantity::from("0.0050")));
1242        // Snapshot must not stamp a wall-clock ts_event so the first WS delta
1243        // can install a real venue timestamp without tripping the model's
1244        // out-of-order guard.
1245        assert_eq!(book.ts_last, UnixNanos::default());
1246    }
1247
1248    #[rstest]
1249    fn test_parse_l2_order_book_snapshot_one_sided_only_populates_asks() {
1250        let instrument = create_test_instrument();
1251        let snapshot = LighterOrderBookOrders {
1252            code: 200,
1253            message: None,
1254            total_asks: 1,
1255            asks: vec![stub_simple_order("2352.74", "0.0050")],
1256            total_bids: 0,
1257            bids: vec![],
1258        };
1259
1260        let book = parse_l2_order_book_snapshot(
1261            &snapshot,
1262            instrument.id(),
1263            instrument.price_precision(),
1264            instrument.size_precision(),
1265        );
1266
1267        assert_eq!(book.best_bid_price(), None);
1268        assert_eq!(book.best_ask_price(), Some(Price::from("2352.74")));
1269        assert_eq!(book.best_ask_size(), Some(Quantity::from("0.0050")));
1270    }
1271
1272    #[rstest]
1273    fn test_parse_l2_order_book_snapshot_empty_book_yields_empty_book() {
1274        let instrument = create_test_instrument();
1275        let snapshot = LighterOrderBookOrders {
1276            code: 200,
1277            message: None,
1278            total_asks: 0,
1279            asks: vec![],
1280            total_bids: 0,
1281            bids: vec![],
1282        };
1283
1284        let book = parse_l2_order_book_snapshot(
1285            &snapshot,
1286            instrument.id(),
1287            instrument.price_precision(),
1288            instrument.size_precision(),
1289        );
1290
1291        assert_eq!(book.best_bid_price(), None);
1292        assert_eq!(book.best_ask_price(), None);
1293        assert_eq!(book.ts_last, UnixNanos::default());
1294    }
1295
1296    #[rstest]
1297    #[case::zero_size("0")]
1298    #[case::negative_size("-1.0")]
1299    fn test_parse_l2_order_book_snapshot_skips_unusable_orders(#[case] remaining: &str) {
1300        // The L2 snapshot aggregator drops orders whose size is zero or
1301        // negative (still constructable as `Decimal`) and keeps the remaining
1302        // valid orders; contrast with `parse_order_book_snapshot` (the deltas
1303        // variant) which errs. Non-numeric wire values are now rejected at
1304        // JSON deserialize time, so the whole `LighterOrderBookOrders`
1305        // payload errors before the aggregator runs. The Decimal model field
1306        // chose typed correctness over per-order resilience to garbage from
1307        // the venue.
1308        let instrument = create_test_instrument();
1309        let snapshot = LighterOrderBookOrders {
1310            code: 200,
1311            message: None,
1312            total_asks: 1,
1313            asks: vec![stub_simple_order("2400.00", "1.0000")],
1314            total_bids: 2,
1315            bids: vec![
1316                stub_simple_order("2000.00", remaining),
1317                stub_simple_order("1999.50", "0.5000"),
1318            ],
1319        };
1320
1321        let book = parse_l2_order_book_snapshot(
1322            &snapshot,
1323            instrument.id(),
1324            instrument.price_precision(),
1325            instrument.size_precision(),
1326        );
1327
1328        // Bad bid is dropped; the second valid bid still seeds the bid side.
1329        assert_eq!(book.best_bid_price(), Some(Price::from("1999.50")));
1330        assert_eq!(book.best_ask_price(), Some(Price::from("2400.00")));
1331    }
1332
1333    #[rstest]
1334    fn test_parse_l2_order_book_snapshot_loads_fixture() {
1335        // End-to-end against the venue fixture: 1 bid + 1 ask, cross-checks
1336        // that the two-sided shape exercised by the rest of the test suite
1337        // round-trips through the L2 snapshot parser.
1338        const HTTP_ORDER_BOOK_ORDERS: &str =
1339            include_str!("../../test_data/http_order_book_orders.json");
1340
1341        let instrument = create_test_instrument();
1342        let snapshot: LighterOrderBookOrders =
1343            serde_json::from_str(HTTP_ORDER_BOOK_ORDERS).expect("fixture deserializes");
1344
1345        let book = parse_l2_order_book_snapshot(
1346            &snapshot,
1347            instrument.id(),
1348            instrument.price_precision(),
1349            instrument.size_precision(),
1350        );
1351
1352        assert_eq!(book.best_bid_price(), Some(Price::from("2361.17")));
1353        assert_eq!(book.best_bid_size(), Some(Quantity::from("3.4125")));
1354        assert_eq!(book.best_ask_price(), Some(Price::from("2361.32")));
1355        assert_eq!(book.best_ask_size(), Some(Quantity::from("0.0317")));
1356    }
1357
1358    #[rstest]
1359    fn test_register_order_books_populates_market_registry() {
1360        let registry = MarketRegistry::new();
1361        let order_books = vec![stub_order_book("ETH", 0, LighterProductType::Perp)];
1362
1363        register_order_books(&registry, &order_books);
1364
1365        assert_eq!(registry.market_index(&instrument_id("ETH-PERP")), Some(0));
1366    }
1367
1368    #[rstest]
1369    fn test_register_perp_order_book_details_populates_market_registry() {
1370        let registry = MarketRegistry::new();
1371        let details = vec![LighterPerpOrderBookDetail {
1372            order_book: stub_order_book("ETH", 0, LighterProductType::Perp),
1373            size_decimals: 4,
1374            price_decimals: 2,
1375            quote_multiplier: 1,
1376            default_initial_margin_fraction: 500,
1377            min_initial_margin_fraction: 200,
1378            maintenance_margin_fraction: 120,
1379            closeout_margin_fraction: 80,
1380            last_trade_price: Decimal::new(235_273, 2),
1381            daily_trades_count: 0,
1382            daily_base_token_volume: Decimal::ZERO,
1383            daily_quote_token_volume: Decimal::ZERO,
1384            daily_price_low: Decimal::ZERO,
1385            daily_price_high: Decimal::ZERO,
1386            daily_price_change: Decimal::ZERO,
1387            open_interest: Decimal::ZERO,
1388            daily_chart: Default::default(),
1389            market_config: LighterMarketConfig {
1390                market_margin_mode: LighterPositionMarginMode::Cross,
1391                insurance_fund_account_index: 281474976710655,
1392                liquidation_mode: 0,
1393                force_reduce_only: false,
1394                trading_hours: String::new(),
1395                funding_fee_discounts_enabled: Some(false),
1396                hidden: false,
1397                rfq_enabled: true,
1398            },
1399            strategy_index: 2,
1400        }];
1401
1402        register_perp_order_book_details(&registry, &details);
1403
1404        assert_eq!(registry.market_index(&instrument_id("ETH-PERP")), Some(0));
1405    }
1406
1407    #[rstest]
1408    fn test_parse_order_book_details_instruments_rejects_invalid_min_quantity() {
1409        // A negative `min_base_amount` is unreachable from the wire (the venue
1410        // never sends one) but the parser must still reject it rather than
1411        // panic inside `Quantity::from_decimal_dp`.
1412        let registry = MarketRegistry::new();
1413        let mut order_book = stub_order_book("ETH", 0, LighterProductType::Perp);
1414        order_book.min_base_amount = Decimal::from_str("-0.0050").unwrap();
1415        let details = vec![LighterPerpOrderBookDetail {
1416            order_book,
1417            size_decimals: 4,
1418            price_decimals: 2,
1419            quote_multiplier: 1,
1420            default_initial_margin_fraction: 500,
1421            min_initial_margin_fraction: 200,
1422            maintenance_margin_fraction: 120,
1423            closeout_margin_fraction: 80,
1424            last_trade_price: Decimal::new(235_273, 2),
1425            daily_trades_count: 0,
1426            daily_base_token_volume: Decimal::ZERO,
1427            daily_quote_token_volume: Decimal::ZERO,
1428            daily_price_low: Decimal::ZERO,
1429            daily_price_high: Decimal::ZERO,
1430            daily_price_change: Decimal::ZERO,
1431            open_interest: Decimal::ZERO,
1432            daily_chart: Default::default(),
1433            market_config: LighterMarketConfig {
1434                market_margin_mode: LighterPositionMarginMode::Cross,
1435                insurance_fund_account_index: 281474976710655,
1436                liquidation_mode: 0,
1437                force_reduce_only: false,
1438                trading_hours: String::new(),
1439                funding_fee_discounts_enabled: Some(false),
1440                hidden: false,
1441                rfq_enabled: true,
1442            },
1443            strategy_index: 2,
1444        }];
1445
1446        let err =
1447            parse_order_book_details_instruments(&registry, &details, &[], UnixNanos::from(1))
1448                .unwrap_err();
1449
1450        assert!(err.to_string().contains("negative quantity"));
1451        assert!(registry.is_empty());
1452    }
1453
1454    #[rstest]
1455    fn test_parse_order_book_details_instruments_skips_invalid_row_without_registry_pollution() {
1456        let registry = MarketRegistry::new();
1457        let mut invalid = stub_perp_detail("ETH", 0);
1458        invalid.order_book.min_base_amount = Decimal::NEGATIVE_ONE;
1459        let valid = stub_perp_detail("BTC", 1);
1460
1461        let instruments = parse_order_book_details_instruments(
1462            &registry,
1463            &[invalid, valid],
1464            &[],
1465            UnixNanos::from(1),
1466        )
1467        .unwrap();
1468
1469        assert_eq!(instruments.len(), 1);
1470        assert_eq!(instruments[0].id(), instrument_id("BTC-PERP"));
1471        assert_eq!(registry.market_index(&instrument_id("BTC-PERP")), Some(1));
1472        assert_eq!(registry.market_index(&instrument_id("ETH-PERP")), None);
1473    }
1474
1475    #[rstest]
1476    fn test_parse_order_book_details_instruments_skips_invalid_spot_row() {
1477        let registry = MarketRegistry::new();
1478        let mut invalid = stub_spot_detail("ETH/USDC", 2048);
1479        invalid.order_book.min_base_amount = Decimal::NEGATIVE_ONE;
1480        let valid = stub_spot_detail("BTC/USDC", 2049);
1481
1482        let instruments = parse_order_book_details_instruments(
1483            &registry,
1484            &[],
1485            &[invalid, valid],
1486            UnixNanos::from(1),
1487        )
1488        .unwrap();
1489
1490        assert_eq!(instruments.len(), 1);
1491        assert_eq!(instruments[0].id(), instrument_id("BTC/USDC-SPOT"));
1492        assert_eq!(
1493            registry.market_index(&instrument_id("BTC/USDC-SPOT")),
1494            Some(2049),
1495        );
1496        assert_eq!(registry.market_index(&instrument_id("ETH/USDC-SPOT")), None);
1497    }
1498
1499    #[rstest]
1500    fn test_parse_order_book_details_instruments_parses_spot_pair() {
1501        let registry = MarketRegistry::new();
1502        let details = vec![stub_spot_detail("ETH/USDC", 2048)];
1503        let instrument_id = instrument_id("ETH/USDC-SPOT");
1504
1505        let instruments =
1506            parse_order_book_details_instruments(&registry, &[], &details, UnixNanos::from(1))
1507                .unwrap();
1508
1509        assert_eq!(instruments.len(), 1);
1510        assert_eq!(registry.market_index(&instrument_id), Some(2048));
1511
1512        match &instruments[0] {
1513            InstrumentAny::CurrencyPair(pair) => {
1514                assert_eq!(pair.id, instrument_id);
1515                assert_eq!(pair.raw_symbol.as_str(), "ETH/USDC");
1516                assert_eq!(pair.base_currency, Currency::from("ETH"));
1517                assert_eq!(pair.quote_currency, Currency::from("USDC"));
1518                assert_eq!(pair.price_precision, 6);
1519                assert_eq!(pair.size_precision, 6);
1520                assert_eq!(pair.price_increment, Price::from("0.000001"));
1521                assert_eq!(pair.size_increment, Quantity::from("0.000001"));
1522                assert_eq!(pair.min_quantity, Some(Quantity::from("0.005000")));
1523                assert_eq!(
1524                    pair.max_notional,
1525                    Some(Money::from("281474976.710655 USDC"))
1526                );
1527                assert_eq!(pair.min_notional, Some(Money::from("10.000000 USDC")));
1528            }
1529            other => panic!("expected currency pair, was {other:?}"),
1530        }
1531    }
1532
1533    #[rstest]
1534    fn test_parse_perp_uses_registry_venue_and_settlement_currency() {
1535        let venue = Venue::new("LIGHTER_ROBINHOOD");
1536        let settlement_currency = Currency::USDG();
1537        let registry =
1538            MarketRegistry::new_with_venue_and_settlement_currency(venue, settlement_currency);
1539
1540        let details = vec![stub_perp_detail("ETH", 0)];
1541
1542        let instruments =
1543            parse_order_book_details_instruments(&registry, &details, &[], UnixNanos::from(1))
1544                .unwrap();
1545
1546        assert_eq!(instruments.len(), 1);
1547        match &instruments[0] {
1548            InstrumentAny::CryptoPerpetual(perp) => {
1549                assert_eq!(perp.id.venue, venue);
1550                assert_eq!(perp.base_currency, Currency::from("ETH"));
1551                assert_eq!(perp.quote_currency, settlement_currency);
1552                assert_eq!(perp.settlement_currency, settlement_currency);
1553            }
1554            other => panic!("expected crypto perpetual, was {other:?}"),
1555        }
1556    }
1557
1558    #[rstest]
1559    #[case::missing_quote_separator("ETH")]
1560    #[case::missing_base("/USDC")]
1561    #[case::missing_quote("ETH/")]
1562    #[case::extra_component("ETH/USDC/EXTRA")]
1563    fn test_parse_order_book_details_instruments_rejects_invalid_spot_pair(#[case] symbol: &str) {
1564        let registry = MarketRegistry::new();
1565        let details = vec![stub_spot_detail(symbol, 2048)];
1566
1567        let error =
1568            parse_order_book_details_instruments(&registry, &[], &details, UnixNanos::from(1))
1569                .unwrap_err();
1570
1571        assert!(error.to_string().contains("BASE/QUOTE"));
1572        assert!(registry.is_empty());
1573    }
1574
1575    #[rstest]
1576    fn test_register_spot_order_book_details_populates_market_registry() {
1577        let registry = MarketRegistry::new();
1578        let details = vec![stub_spot_detail("ETH/USDC", 2048)];
1579
1580        register_spot_order_book_details(&registry, &details);
1581
1582        assert_eq!(
1583            registry.market_index(&instrument_id("ETH/USDC-SPOT")),
1584            Some(2048)
1585        );
1586    }
1587
1588    fn instrument_id(symbol: &str) -> InstrumentId {
1589        InstrumentId::new(Symbol::new(symbol), Venue::new("LIGHTER"))
1590    }
1591
1592    #[rstest]
1593    fn test_parse_order_book_details_instruments_routes_widened_ids_by_market_type() {
1594        let registry = MarketRegistry::new();
1595        let details: LighterOrderBookDetails =
1596            serde_json::from_str(HTTP_ORDER_BOOK_DETAILS_WIDENED_IDS).unwrap();
1597
1598        let instruments = parse_order_book_details_instruments(
1599            &registry,
1600            &details.order_book_details,
1601            &details.spot_order_book_details,
1602            UnixNanos::from(1),
1603        )
1604        .unwrap();
1605
1606        assert_eq!(instruments.len(), 4);
1607
1608        let eth_perp = instrument_id("ETH-PERP");
1609        let future_perp = instrument_id("FUTURE-PERP");
1610        let eth_spot = instrument_id("ETH/USDC-SPOT");
1611        let future_spot = instrument_id("FUTURE/USDC-SPOT");
1612
1613        assert_eq!(registry.market_index(&eth_perp), Some(4095));
1614        assert_eq!(registry.market_index(&future_perp), Some(40_000));
1615        assert_eq!(registry.market_index(&eth_spot), Some(4098));
1616        assert_eq!(registry.market_index(&future_spot), Some(50_000));
1617
1618        let mut kinds: Vec<(&str, &str)> = instruments
1619            .iter()
1620            .map(|instrument| match instrument {
1621                InstrumentAny::CryptoPerpetual(perp) => (perp.id.symbol.as_str(), "perp"),
1622                InstrumentAny::CurrencyPair(pair) => (pair.id.symbol.as_str(), "spot"),
1623                other => panic!("unexpected instrument kind, was {other:?}"),
1624            })
1625            .collect();
1626
1627        kinds.sort_unstable();
1628        assert_eq!(
1629            kinds,
1630            vec![
1631                ("ETH-PERP", "perp"),
1632                ("ETH/USDC-SPOT", "spot"),
1633                ("FUTURE-PERP", "perp"),
1634                ("FUTURE/USDC-SPOT", "spot"),
1635            ],
1636        );
1637    }
1638
1639    #[rstest]
1640    #[case::binary_options(LighterProductType::BinaryOptions)]
1641    #[case::other(LighterProductType::Other)]
1642    fn test_register_order_books_skips_unsupported_market_type(
1643        #[case] market_type: LighterProductType,
1644    ) {
1645        let registry = MarketRegistry::new();
1646        let order_books = vec![
1647            stub_order_book("BTC-UPDOWN", 7001, market_type),
1648            stub_order_book("ETH", 0, LighterProductType::Perp),
1649        ];
1650
1651        register_order_books(&registry, &order_books);
1652
1653        assert_eq!(registry.len(), 1);
1654        assert_eq!(registry.instrument_id(7001), None);
1655        assert_eq!(registry.market_index(&instrument_id("ETH-PERP")), Some(0));
1656    }
1657
1658    #[rstest]
1659    #[case::binary_options("binary_options")]
1660    #[case::unfamiliar("future_kind")]
1661    fn test_parse_order_book_details_instruments_skips_unsupported_market_type(
1662        #[case] market_type: &str,
1663    ) {
1664        let registry = MarketRegistry::new();
1665        let mut payload: serde_json::Value =
1666            serde_json::from_str(HTTP_ORDER_BOOK_DETAILS_WIDENED_IDS).unwrap();
1667        payload["order_book_details"][1]["market_type"] = serde_json::json!(market_type);
1668        payload["spot_order_book_details"][1]["market_type"] = serde_json::json!(market_type);
1669        let details: LighterOrderBookDetails = serde_json::from_value(payload).unwrap();
1670
1671        let instruments = parse_order_book_details_instruments(
1672            &registry,
1673            &details.order_book_details,
1674            &details.spot_order_book_details,
1675            UnixNanos::from(1),
1676        )
1677        .unwrap();
1678
1679        let mut ids: Vec<InstrumentId> = instruments.iter().map(InstrumentAny::id).collect();
1680        ids.sort_unstable();
1681        assert_eq!(
1682            ids,
1683            vec![instrument_id("ETH-PERP"), instrument_id("ETH/USDC-SPOT")]
1684        );
1685        assert_eq!(registry.len(), 2);
1686        assert_eq!(registry.instrument_id(40_000), None);
1687        assert_eq!(registry.instrument_id(50_000), None);
1688    }
1689
1690    #[rstest]
1691    fn test_parse_order_book_details_instruments_returns_empty_for_only_unsupported_markets() {
1692        let registry = MarketRegistry::new();
1693        let mut payload: serde_json::Value =
1694            serde_json::from_str(HTTP_ORDER_BOOK_DETAILS_WIDENED_IDS).unwrap();
1695
1696        for key in ["order_book_details", "spot_order_book_details"] {
1697            for detail in payload[key].as_array_mut().unwrap() {
1698                detail["market_type"] = serde_json::json!("binary_options");
1699            }
1700        }
1701
1702        let details: LighterOrderBookDetails = serde_json::from_value(payload).unwrap();
1703
1704        let instruments = parse_order_book_details_instruments(
1705            &registry,
1706            &details.order_book_details,
1707            &details.spot_order_book_details,
1708            UnixNanos::from(1),
1709        )
1710        .unwrap();
1711
1712        assert!(instruments.is_empty());
1713        assert!(registry.is_empty());
1714    }
1715
1716    #[rstest]
1717    fn test_parse_trade_tick_keeps_unfamiliar_trade_type() {
1718        let instrument = create_test_instrument();
1719        let mut trade = stub_trade(true);
1720        let expected = parse_trade_tick(&trade, &instrument, UnixNanos::from(1)).unwrap();
1721        trade.trade_type = LighterTradeType::Other;
1722
1723        let tick = parse_trade_tick(&trade, &instrument, UnixNanos::from(1)).unwrap();
1724
1725        assert_eq!(tick, expected);
1726    }
1727}