Skip to main content

nautilus_finfeed/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//! Provider outcome IDs retain their spelling under separate FinFeed venues.
17
18use nautilus_model::identifiers::{InstrumentId, Symbol, Venue};
19use ustr::Ustr;
20
21use crate::{common::enums::Exchange, http::error::Error};
22
23const VENUE_PREFIX: &str = "FINFEED_";
24
25/// Maps an exact exchange and outcome ID to a provider-owned instrument ID.
26///
27/// Native adapters use separate venues and remain independent definition sources.
28///
29/// # Errors
30///
31/// Returns an error if the exchange is unknown or the outcome ID is invalid.
32pub fn to_instrument_id(exchange_id: &str, market_id: &str) -> Result<InstrumentId, Error> {
33    exchange_id
34        .parse::<Exchange>()
35        .map_err(|_| Error::Validation(format!("unknown exchange {exchange_id}")))?;
36
37    if matches!(market_id, "." | "..") {
38        return Err(Error::Validation("invalid outcome ID".into()));
39    }
40
41    let symbol = Symbol::new_checked(market_id)
42        .map_err(|_| Error::Validation("invalid outcome ID".into()))?;
43    let venue = Venue::new_checked(format!("{VENUE_PREFIX}{exchange_id}"))
44        .map_err(|_| Error::Validation("invalid FinFeed venue".into()))?;
45    Ok(InstrumentId::new(symbol, venue))
46}
47
48/// Returns the exact provider exchange and outcome ID for a FinFeed instrument.
49///
50/// # Errors
51///
52/// Returns an error if the instrument does not use a known FinFeed venue or valid outcome ID.
53pub fn from_instrument_id(instrument_id: InstrumentId) -> Result<(Ustr, Ustr), Error> {
54    let exchange_id = instrument_id
55        .venue
56        .as_str()
57        .strip_prefix(VENUE_PREFIX)
58        .ok_or_else(|| Error::Validation("instrument does not use a FinFeed venue".into()))?;
59    let market_id = instrument_id.symbol.as_str();
60    to_instrument_id(exchange_id, market_id)?;
61    Ok((exchange_id.into(), market_id.into()))
62}
63
64#[cfg(test)]
65mod tests {
66    use rstest::rstest;
67
68    use super::*;
69    use crate::http::models::MarketsPage;
70
71    #[rstest]
72    #[case("KALSHI", include_str!("../../test_data/kalshi-listings.json"))]
73    #[case("POLYMARKET", include_str!("../../test_data/polymarket-listings.json"))]
74    #[case("MYRIAD", include_str!("../../test_data/myriad-listings.json"))]
75    #[case("MANIFOLD", include_str!("../../test_data/manifold-listings.json"))]
76    #[case("HYPERLIQUIDOUTCOME", include_str!("../../test_data/hyperliquidoutcome-listings.json"))]
77    #[case("PASCAL", include_str!("../../test_data/pascal-listings.json"))]
78    #[case("GEMINIPM", include_str!("../../test_data/geminipm-listings.json"))]
79    #[case("CRYPTOCOMPM", include_str!("../../test_data/cryptocompm-listings.json"))]
80    #[case("FORECASTEX", include_str!("../../test_data/forecastex-listings.json"))]
81    fn outcome_identity_round_trips_every_known_venue(
82        #[case] exchange: &str,
83        #[case] fixture: &str,
84    ) {
85        let page: MarketsPage = serde_json::from_str(fixture).unwrap();
86        for market in page.data.unwrap() {
87            let market_id = market.market_id.unwrap();
88            let id = to_instrument_id(exchange, &market_id).unwrap();
89            let serialized = id.to_string();
90            let reparsed: InstrumentId = serialized.parse().unwrap();
91            assert_eq!(id.symbol.as_str(), market_id);
92            assert_eq!(id.venue.as_str(), format!("FINFEED_{exchange}"));
93            assert_eq!(reparsed, id);
94            assert_eq!(
95                from_instrument_id(reparsed).unwrap(),
96                (exchange.into(), market_id)
97            );
98        }
99    }
100
101    #[rstest]
102    #[case("UNKNOWN", "contract_NO")]
103    #[case("polymarket", "contract_NO")]
104    #[case("POLYMARKET", "")]
105    #[case("POLYMARKET", " ")]
106    #[case("POLYMARKET", "..")]
107    fn invalid_identity_is_rejected(#[case] exchange: &str, #[case] market_id: &str) {
108        assert!(matches!(
109            to_instrument_id(exchange, market_id),
110            Err(Error::Validation(_))
111        ));
112    }
113
114    #[rstest]
115    fn native_venue_cannot_claim_a_finfeed_definition() {
116        let native = InstrumentId::from("condition-token.POLYMARKET");
117        assert!(matches!(
118            from_instrument_id(native),
119            Err(Error::Validation(_))
120        ));
121        let provider = to_instrument_id("POLYMARKET", "condition-token").unwrap();
122        assert_ne!(provider, native);
123    }
124}