Skip to main content

nautilus_lighter/common/
symbol.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//! Bidirectional mapping between Nautilus `InstrumentId` and Lighter `market_index`.
17//!
18//! Lighter identifies markets by a 64-bit `market_index`. Legacy markets keep
19//! their range-partitioned ids (perpetuals `0..=254`, spot `2048..=4094`);
20//! markets listed after the September 2026 upgrade take the next free index
21//! from `4095` for either product type, so product type must come from the
22//! venue's `market_type` field, never from the id. The mapping is populated
23//! at bootstrap from `GET /api/v1/orderBookDetails` and subsequently
24//! consulted on every WebSocket frame and outbound transaction.
25
26use dashmap::DashMap;
27use nautilus_model::{
28    identifiers::{InstrumentId, Symbol, Venue},
29    types::Currency,
30};
31use ustr::Ustr;
32
33use super::{consts::LIGHTER_VENUE, enums::LighterProductType};
34
35/// Suffix applied to perpetual instrument symbols on the Nautilus side.
36pub const PERP_SUFFIX: &str = "-PERP";
37
38/// Suffix applied to spot instrument symbols on the Nautilus side.
39pub const SPOT_SUFFIX: &str = "-SPOT";
40
41/// Builds a Nautilus [`InstrumentId`] from a venue symbol and product type.
42///
43/// The venue symbol is upper-cased and combined with the product suffix
44/// (`-PERP` or `-SPOT`) before being qualified by the Lighter venue.
45/// Unsupported product types get no suffix.
46#[must_use]
47pub fn format_instrument_id(venue_symbol: &str, product_type: LighterProductType) -> InstrumentId {
48    format_instrument_id_with_venue(venue_symbol, product_type, *LIGHTER_VENUE)
49}
50
51/// Builds a Nautilus [`InstrumentId`] for a specific venue.
52#[must_use]
53pub fn format_instrument_id_with_venue(
54    venue_symbol: &str,
55    product_type: LighterProductType,
56    venue: Venue,
57) -> InstrumentId {
58    let suffix = product_suffix(product_type);
59    let trimmed = venue_symbol.trim();
60    let upper = trimmed.to_ascii_uppercase();
61    let symbol = format!("{upper}{suffix}");
62    InstrumentId::new(Symbol::from_str_unchecked(&symbol), venue)
63}
64
65/// Returns the venue-native symbol for an instrument id by stripping any
66/// known product suffix. Returns the raw symbol unchanged when no suffix
67/// is present.
68#[must_use]
69pub fn format_venue_symbol(instrument_id: &InstrumentId) -> &str {
70    let s = instrument_id.symbol.as_str();
71    s.strip_suffix(PERP_SUFFIX)
72        .or_else(|| s.strip_suffix(SPOT_SUFFIX))
73        .unwrap_or(s)
74}
75
76/// Returns the [`LighterProductType`] implied by the instrument id's suffix,
77/// or `None` if the symbol carries neither suffix.
78#[must_use]
79pub fn product_type_from_instrument_id(instrument_id: &InstrumentId) -> Option<LighterProductType> {
80    let s = instrument_id.symbol.as_str();
81    if s.ends_with(PERP_SUFFIX) {
82        Some(LighterProductType::Perp)
83    } else if s.ends_with(SPOT_SUFFIX) {
84        Some(LighterProductType::Spot)
85    } else {
86        None
87    }
88}
89
90const fn product_suffix(product_type: LighterProductType) -> &'static str {
91    match product_type {
92        LighterProductType::Perp => PERP_SUFFIX,
93        LighterProductType::Spot => SPOT_SUFFIX,
94        LighterProductType::BinaryOptions | LighterProductType::Other => "",
95    }
96}
97
98fn canonical_symbol_key(venue_symbol: &str) -> Ustr {
99    Ustr::from(&venue_symbol.trim().to_ascii_uppercase())
100}
101
102/// Registry mapping `market_index` to `InstrumentId` and back.
103///
104/// Indexed for `O(1)` lookup by all three keys the adapter switches between:
105/// the venue's numeric `market_index` (used in transaction encoding and
106/// WebSocket subscriptions), the Nautilus [`InstrumentId`] (used by the
107/// engine), and the raw venue symbol scoped by product type (used when
108/// parsing REST list responses). Designed to be shared across the HTTP and
109/// WebSocket clients via `Arc`.
110///
111/// The registry is intended for write-once bootstrap followed by read-only
112/// consumption: each individual lookup is lock-free, but a single `insert`
113/// is not transactional across the three indexes. Rare write events such
114/// as relists must be coordinated by the caller (e.g. quiesce consumers
115/// before reinserting) to avoid concurrent readers observing partial
116/// state.
117#[derive(Debug)]
118pub struct MarketRegistry {
119    venue: Venue,
120    settlement_currency: Currency,
121    by_index: DashMap<i64, InstrumentId>,
122    by_id: DashMap<InstrumentId, i64>,
123    by_raw_symbol: DashMap<(Ustr, LighterProductType), InstrumentId>,
124}
125
126impl Default for MarketRegistry {
127    fn default() -> Self {
128        Self::new_with_venue_and_settlement_currency(
129            *LIGHTER_VENUE,
130            Currency::get_or_create_crypto("USDC"),
131        )
132    }
133}
134
135impl MarketRegistry {
136    /// Returns a new empty registry.
137    #[must_use]
138    pub fn new() -> Self {
139        Self::default()
140    }
141
142    /// Returns a new empty registry for a venue and settlement currency.
143    #[must_use]
144    pub fn new_with_venue_and_settlement_currency(
145        venue: Venue,
146        settlement_currency: Currency,
147    ) -> Self {
148        Self {
149            venue,
150            settlement_currency,
151            by_index: DashMap::new(),
152            by_id: DashMap::new(),
153            by_raw_symbol: DashMap::new(),
154        }
155    }
156
157    /// Returns the venue assigned to registered instruments.
158    #[must_use]
159    pub const fn venue(&self) -> Venue {
160        self.venue
161    }
162
163    /// Returns the deployment settlement currency.
164    #[must_use]
165    pub const fn settlement_currency(&self) -> Currency {
166        self.settlement_currency
167    }
168
169    /// Registers a market and returns the resulting [`InstrumentId`].
170    ///
171    /// Re-inserting the same `market_index` overwrites the previous mapping;
172    /// callers may use this to handle venue rename or relisting events. Stale
173    /// entries in the inverse indexes are evicted before the new mapping is
174    /// installed so all three lookups stay consistent.
175    pub fn insert(
176        &self,
177        market_index: i64,
178        venue_symbol: &str,
179        product_type: LighterProductType,
180    ) -> InstrumentId {
181        let instrument_id = format_instrument_id_with_venue(venue_symbol, product_type, self.venue);
182        let canonical = canonical_symbol_key(venue_symbol);
183
184        // Evict any prior mapping that shared this market_index but pointed
185        // at a different InstrumentId.
186        if let Some((_, prior_id)) = self.by_index.remove(&market_index)
187            && prior_id != instrument_id
188        {
189            self.by_id
190                .remove_if(&prior_id, |_, idx| *idx == market_index);
191            if let Some(prior_pt) = product_type_from_instrument_id(&prior_id) {
192                let prior_key = Ustr::from(format_venue_symbol(&prior_id));
193                self.by_raw_symbol
194                    .remove_if(&(prior_key, prior_pt), |_, id| *id == prior_id);
195            }
196        }
197
198        // Evict any prior mapping that shared this InstrumentId but pointed
199        // at a different market_index.
200        if let Some((_, prior_index)) = self.by_id.remove(&instrument_id)
201            && prior_index != market_index
202        {
203            self.by_index
204                .remove_if(&prior_index, |_, id| *id == instrument_id);
205        }
206
207        self.by_index.insert(market_index, instrument_id);
208        self.by_id.insert(instrument_id, market_index);
209        self.by_raw_symbol
210            .insert((canonical, product_type), instrument_id);
211        instrument_id
212    }
213
214    /// Returns the [`InstrumentId`] for a given `market_index`.
215    #[must_use]
216    pub fn instrument_id(&self, market_index: i64) -> Option<InstrumentId> {
217        self.by_index.get(&market_index).map(|e| *e)
218    }
219
220    /// Returns every registered `market_index`.
221    ///
222    /// Callers iterating across all venue markets (e.g. the mass-status
223    /// reconciliation path) use this to bound the per-market REST fan-out.
224    #[must_use]
225    pub fn all_market_indices(&self) -> Vec<i64> {
226        self.by_index.iter().map(|e| *e.key()).collect()
227    }
228
229    /// Returns the venue `market_index` for a given [`InstrumentId`].
230    #[must_use]
231    pub fn market_index(&self, instrument_id: &InstrumentId) -> Option<i64> {
232        self.by_id.get(instrument_id).map(|e| *e)
233    }
234
235    /// Returns the [`InstrumentId`] for a raw venue symbol scoped by product.
236    ///
237    /// The raw symbol on its own is ambiguous when the venue lists the same
238    /// asset on both perpetual and spot; the product discriminant resolves it.
239    #[must_use]
240    pub fn instrument_id_by_symbol(
241        &self,
242        venue_symbol: &str,
243        product_type: LighterProductType,
244    ) -> Option<InstrumentId> {
245        let key = canonical_symbol_key(venue_symbol);
246        self.by_raw_symbol.get(&(key, product_type)).map(|e| *e)
247    }
248
249    /// Removes all registered markets.
250    pub fn clear(&self) {
251        self.by_index.clear();
252        self.by_id.clear();
253        self.by_raw_symbol.clear();
254    }
255
256    /// Returns the number of registered markets.
257    #[must_use]
258    pub fn len(&self) -> usize {
259        self.by_index.len()
260    }
261
262    /// Returns whether the registry has no entries.
263    #[must_use]
264    pub fn is_empty(&self) -> bool {
265        self.by_index.is_empty()
266    }
267}
268
269#[cfg(test)]
270mod tests {
271    use proptest::prelude::*;
272    use rstest::rstest;
273
274    use super::*;
275
276    #[rstest]
277    fn format_instrument_id_perp_uppercases_and_suffixes() {
278        let id = format_instrument_id("eth", LighterProductType::Perp);
279        assert_eq!(id.symbol.as_str(), "ETH-PERP");
280        assert_eq!(id.venue, *LIGHTER_VENUE);
281    }
282
283    #[rstest]
284    fn format_instrument_id_spot_uppercases_and_suffixes() {
285        let id = format_instrument_id("usdc", LighterProductType::Spot);
286        assert_eq!(id.symbol.as_str(), "USDC-SPOT");
287    }
288
289    #[rstest]
290    #[case::leading("  ETH", "ETH-PERP")]
291    #[case::trailing("ETH  ", "ETH-PERP")]
292    #[case::both_sides("  eth  ", "ETH-PERP")]
293    #[case::tab("\tBTC\n", "BTC-PERP")]
294    fn format_instrument_id_trims_whitespace(#[case] input: &str, #[case] expected_symbol: &str) {
295        let id = format_instrument_id(input, LighterProductType::Perp);
296        assert_eq!(id.symbol.as_str(), expected_symbol);
297        assert_eq!(id.venue, *LIGHTER_VENUE);
298    }
299
300    #[rstest]
301    fn format_venue_symbol_strips_known_suffixes() {
302        let perp = format_instrument_id("BTC", LighterProductType::Perp);
303        assert_eq!(format_venue_symbol(&perp), "BTC");
304        let spot = format_instrument_id("SOL", LighterProductType::Spot);
305        assert_eq!(format_venue_symbol(&spot), "SOL");
306    }
307
308    #[rstest]
309    fn format_venue_symbol_returns_unsuffixed_unchanged() {
310        let id = InstrumentId::new(Symbol::from_str_unchecked("ETH"), *LIGHTER_VENUE);
311        assert_eq!(format_venue_symbol(&id), "ETH");
312    }
313
314    #[rstest]
315    fn product_type_from_instrument_id_dispatches_on_suffix() {
316        let perp = format_instrument_id("BTC", LighterProductType::Perp);
317        let spot = format_instrument_id("BTC", LighterProductType::Spot);
318        let none = InstrumentId::new(Symbol::from_str_unchecked("BTC"), *LIGHTER_VENUE);
319        assert_eq!(
320            product_type_from_instrument_id(&perp),
321            Some(LighterProductType::Perp),
322        );
323        assert_eq!(
324            product_type_from_instrument_id(&spot),
325            Some(LighterProductType::Spot),
326        );
327        assert_eq!(product_type_from_instrument_id(&none), None);
328    }
329
330    #[rstest]
331    fn registry_round_trip_by_all_keys() {
332        let registry = MarketRegistry::new();
333        let id = registry.insert(0, "ETH", LighterProductType::Perp);
334
335        assert_eq!(registry.instrument_id(0), Some(id));
336        assert_eq!(registry.market_index(&id), Some(0));
337        assert_eq!(
338            registry.instrument_id_by_symbol("ETH", LighterProductType::Perp),
339            Some(id),
340        );
341        assert_eq!(registry.len(), 1);
342        assert!(!registry.is_empty());
343    }
344
345    #[rstest]
346    fn registry_round_trip_widened_market_ids() {
347        let registry = MarketRegistry::new();
348        let perp = registry.insert(4095, "ETH", LighterProductType::Perp);
349        let future_perp = registry.insert(40_000, "FUTURE", LighterProductType::Perp);
350        let future_spot = registry.insert(50_000, "FUTURE/USDC", LighterProductType::Spot);
351
352        assert_eq!(registry.instrument_id(4095), Some(perp));
353        assert_eq!(registry.instrument_id(40_000), Some(future_perp));
354        assert_eq!(registry.instrument_id(50_000), Some(future_spot));
355        assert_eq!(registry.market_index(&perp), Some(4095));
356        assert_eq!(registry.market_index(&future_perp), Some(40_000));
357        assert_eq!(registry.market_index(&future_spot), Some(50_000));
358        assert_eq!(registry.len(), 3);
359    }
360
361    #[rstest]
362    fn registry_scopes_instruments_to_configured_venue() {
363        let venue = Venue::from("LIGHTER_CUSTOM");
364        let settlement_currency = Currency::USDG();
365        let registry =
366            MarketRegistry::new_with_venue_and_settlement_currency(venue, settlement_currency);
367
368        let instrument_id = registry.insert(0, "ETH", LighterProductType::Perp);
369
370        assert_eq!(instrument_id.venue, venue);
371        assert_eq!(registry.venue(), venue);
372        assert_eq!(registry.settlement_currency(), settlement_currency);
373    }
374
375    #[rstest]
376    fn registry_idempotent_reinsert_is_stable() {
377        let registry = MarketRegistry::new();
378        let first = registry.insert(0, "ETH", LighterProductType::Perp);
379        let second = registry.insert(0, "ETH", LighterProductType::Perp);
380
381        assert_eq!(first, second);
382        assert_eq!(registry.instrument_id(0), Some(first));
383        assert_eq!(registry.market_index(&first), Some(0));
384        assert_eq!(
385            registry.instrument_id_by_symbol("ETH", LighterProductType::Perp),
386            Some(first),
387        );
388        assert_eq!(registry.len(), 1);
389    }
390
391    #[rstest]
392    fn registry_disambiguates_perp_and_spot_for_same_symbol() {
393        let registry = MarketRegistry::new();
394        let perp = registry.insert(1, "BTC", LighterProductType::Perp);
395        let spot = registry.insert(2049, "BTC", LighterProductType::Spot);
396
397        assert_ne!(perp, spot);
398        assert_eq!(
399            registry.instrument_id_by_symbol("BTC", LighterProductType::Perp),
400            Some(perp),
401        );
402        assert_eq!(
403            registry.instrument_id_by_symbol("BTC", LighterProductType::Spot),
404            Some(spot),
405        );
406        assert_eq!(registry.market_index(&perp), Some(1));
407        assert_eq!(registry.market_index(&spot), Some(2049));
408    }
409
410    #[rstest]
411    fn registry_insert_overwrites_existing_index() {
412        let registry = MarketRegistry::new();
413        let old_id = registry.insert(5, "OLD", LighterProductType::Perp);
414        let new_id = registry.insert(5, "NEW", LighterProductType::Perp);
415
416        assert_eq!(registry.instrument_id(5), Some(new_id));
417        assert_eq!(
418            registry.instrument_id_by_symbol("NEW", LighterProductType::Perp),
419            Some(new_id),
420        );
421
422        // Stale entries for the displaced InstrumentId must not survive.
423        assert_eq!(registry.market_index(&old_id), None);
424        assert_eq!(
425            registry.instrument_id_by_symbol("OLD", LighterProductType::Perp),
426            None,
427        );
428        assert_eq!(registry.len(), 1);
429    }
430
431    #[rstest]
432    fn registry_insert_canonicalizes_symbol_case() {
433        let registry = MarketRegistry::new();
434        let lower = registry.insert(5, "eth", LighterProductType::Perp);
435        let _new_id = registry.insert(5, "NEW", LighterProductType::Perp);
436
437        // Lookup with the lowercased form must miss because the prior entry
438        // was evicted from the canonical (uppercased) by_raw_symbol slot.
439        assert_eq!(
440            registry.instrument_id_by_symbol("eth", LighterProductType::Perp),
441            None,
442        );
443        assert_eq!(
444            registry.instrument_id_by_symbol("ETH", LighterProductType::Perp),
445            None,
446        );
447        assert_eq!(registry.market_index(&lower), None);
448        assert_eq!(registry.len(), 1);
449    }
450
451    #[rstest]
452    fn registry_lookup_is_case_insensitive() {
453        let registry = MarketRegistry::new();
454        let id = registry.insert(0, "btc", LighterProductType::Perp);
455        assert_eq!(
456            registry.instrument_id_by_symbol("BTC", LighterProductType::Perp),
457            Some(id),
458        );
459        assert_eq!(
460            registry.instrument_id_by_symbol("  btc ", LighterProductType::Perp),
461            Some(id),
462        );
463    }
464
465    #[rstest]
466    fn registry_insert_remaps_symbol_to_new_index() {
467        let registry = MarketRegistry::new();
468        let original = registry.insert(0, "ETH", LighterProductType::Perp);
469        let remapped = registry.insert(7, "ETH", LighterProductType::Perp);
470
471        assert_eq!(original, remapped);
472        assert_eq!(registry.market_index(&original), Some(7));
473        assert_eq!(registry.instrument_id(7), Some(original));
474
475        // The previous market_index slot must no longer point at this id.
476        assert_eq!(registry.instrument_id(0), None);
477        assert_eq!(registry.len(), 1);
478    }
479
480    #[rstest]
481    fn registry_clear_empties_all_indices() {
482        let registry = MarketRegistry::new();
483        registry.insert(0, "ETH", LighterProductType::Perp);
484        registry.insert(2048, "USDC", LighterProductType::Spot);
485        assert_eq!(registry.len(), 2);
486
487        registry.clear();
488        assert!(registry.is_empty());
489        assert_eq!(registry.instrument_id(0), None);
490    }
491
492    #[rstest]
493    fn registry_lookup_misses_return_none() {
494        let registry = MarketRegistry::new();
495        let unknown = InstrumentId::new(Symbol::from_str_unchecked("XYZ-PERP"), *LIGHTER_VENUE);
496        assert_eq!(registry.instrument_id(99), None);
497        assert_eq!(registry.market_index(&unknown), None);
498        assert_eq!(
499            registry.instrument_id_by_symbol("XYZ", LighterProductType::Perp),
500            None,
501        );
502    }
503
504    proptest! {
505        /// Round-tripping a canonical (uppercase) venue symbol through
506        /// `format_instrument_id` and `format_venue_symbol` returns the
507        /// same string, and the suffix encodes the original product type.
508        #[rstest]
509        fn prop_instrument_id_roundtrips_through_venue_symbol(
510            symbol in "[A-Z][A-Z0-9]{0,7}",
511            is_perp in any::<bool>(),
512        ) {
513            let product = if is_perp {
514                LighterProductType::Perp
515            } else {
516                LighterProductType::Spot
517            };
518            let id = format_instrument_id(&symbol, product);
519            prop_assert_eq!(format_venue_symbol(&id), symbol.as_str());
520            prop_assert_eq!(product_type_from_instrument_id(&id), Some(product));
521        }
522    }
523}