Skip to main content

nautilus_finfeed/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//! Checked outcome definitions from FinFeed, Polymarket conventions, and public Kalshi metadata.
17
18use indexmap::IndexMap;
19use jiff::Timestamp;
20use nautilus_core::{Params, UnixNanos};
21use nautilus_model::{
22    enums::AssetClass,
23    identifiers::InstrumentId,
24    instruments::BinaryOption,
25    types::{Currency, Price, Quantity},
26};
27use rust_decimal::Decimal;
28use serde::Deserialize;
29use serde_json::{Value, json};
30use strum::{AsRefStr, EnumString};
31
32use super::{
33    error::Error,
34    kalshi::{Event as KalshiEvent, Market as KalshiMarket, parse_definition},
35    models::{Market, MarketStatus, OutcomeType},
36};
37use crate::common::{consts::FINFEED, symbol::to_instrument_id};
38
39pub(crate) const TOKEN_ID_KEY: &str = "token_id";
40const PRICE_PRECISION: u8 = 4;
41const SIZE_PRECISION: u8 = 6;
42
43/// Parses a checked provider-owned Polymarket Yes/No definition.
44///
45/// Polymarket uses pUSD and six-decimal shares, matching the native adapter's conventions.
46/// Unavailable activation uses its zero timestamp convention. `EndDateIso` sets the simulated
47/// trading cutoff; it does not prove actual venue closure or authoritative settlement.
48/// `FinFeedDataLoader` fetches the public metadata needed for Kalshi definitions.
49/// Other venue families fail until their required field rules are verified.
50///
51/// # Errors
52///
53/// Returns an error if:
54/// - The venue or contract is unsupported.
55/// - Required identity or metadata is missing, invalid, or conflicting.
56/// - The tick is outside `(0, 1)` or the provider price is outside `[0, 1]`.
57/// - A price requires rounding or expiry is outside the supported timestamp range.
58pub fn parse_instrument(market: &Market, ts_init: UnixNanos) -> Result<BinaryOption, Error> {
59    let instrument_id = checked_identity(market)?;
60    if market.exchange_id.as_deref() != Some("POLYMARKET") {
61        return Err(definition_error(
62            market,
63            "source_specific_data",
64            "has no verified complete definition rules for this venue",
65        ));
66    }
67
68    let instrument = parse_polymarket(market, instrument_id, ts_init)?;
69
70    if market.status == MarketStatus::Unknown {
71        log::warn!(
72            "Unknown FinFeed market status for {instrument_id}, retaining metadata without settlement inference"
73        );
74    }
75
76    Ok(instrument)
77}
78
79fn parse_polymarket(
80    market: &Market,
81    instrument_id: InstrumentId,
82    ts_init: UnixNanos,
83) -> Result<BinaryOption, Error> {
84    let title = market
85        .title
86        .as_deref()
87        .filter(|title| !title.trim().is_empty())
88        .ok_or_else(|| definition_error(market, "title", "is missing or empty"))?;
89    let outcome = binary_outcome(market, instrument_id)?;
90    let condition_id = source_string(market, "ConditionId")?;
91    if condition_id.len() != 66
92        || !condition_id.starts_with("0x")
93        || !condition_id[2..]
94            .bytes()
95            .all(|byte| byte.is_ascii_hexdigit())
96    {
97        return Err(definition_error(market, "ConditionId", "is invalid"));
98    }
99
100    let token_id = outcome_token(market, outcome)?;
101    let tick_string = source_string(market, "MinimumTickSize")?;
102    let tick = Decimal::from_str_exact(&tick_string)
103        .map_err(|_| definition_error(market, "MinimumTickSize", "is not an exact decimal"))?;
104    if tick <= Decimal::ZERO || tick >= Decimal::ONE {
105        return Err(definition_error(
106            market,
107            "MinimumTickSize",
108            "must be in (0, 1)",
109        ));
110    }
111    let price_increment = exact_price(market, tick, "MinimumTickSize")?;
112    if market.price < Decimal::ZERO || market.price > Decimal::ONE {
113        return Err(definition_error(market, "price", "must be in [0, 1]"));
114    }
115    exact_price(market, market.price, "price")?;
116
117    let end_date = source_string(market, "EndDateIso")?;
118    let expiration = end_date
119        .parse::<Timestamp>()
120        .map_err(|_| definition_error(market, "EndDateIso", "is not a timestamp with an offset"))?;
121    let expiration_ns = u64::try_from(expiration.as_nanosecond())
122        .ok()
123        .filter(|time| *time > 0)
124        .ok_or_else(|| {
125            definition_error(
126                market,
127                "EndDateIso",
128                "is outside the supported positive nanosecond range",
129            )
130        })?;
131
132    let currency = Currency::pUSD();
133    let size_decimal = Decimal::new(1, u32::from(SIZE_PRECISION));
134    let size_increment = Quantity::from_decimal_dp(size_decimal, SIZE_PRECISION)
135        .map_err(|_| definition_error(market, "size_increment", "could not be represented"))?;
136    let description = match &market.description {
137        Some(description) => description.clone(),
138        None if market
139            .source_specific_data
140            .as_ref()
141            .is_some_and(|source| source.contains_key("Description")) =>
142        {
143            source_string(market, "Description")?
144        }
145        None => title.to_owned(),
146    };
147
148    let mut info: IndexMap<String, Value> = serde_json::from_value(json!({
149        "provider": FINFEED,
150        "exchange_id": market.exchange_id,
151        "market_id": market.market_id,
152        "title": title,
153        "status": market.status,
154        "outcome_type": market.outcome_type,
155        "mechanism": market.mechanism,
156        "condition_id": condition_id,
157        TOKEN_ID_KEY: token_id,
158        "activation_source": "native_unknown_zero",
159        "expiration_source": "EndDateIso",
160    }))
161    .map_err(|_| definition_error(market, "info", "could not be constructed"))?;
162    if market
163        .source_specific_data
164        .as_ref()
165        .is_some_and(|source| source.contains_key("QuestionId"))
166    {
167        info.insert(
168            "question_id".into(),
169            source_string(market, "QuestionId")?.into(),
170        );
171    }
172
173    if market
174        .source_specific_data
175        .as_ref()
176        .is_some_and(|source| source.contains_key("Tags"))
177    {
178        let tags: Vec<String> = serde_json::from_str(&source_string(market, "Tags")?)
179            .map_err(|_| definition_error(market, "Tags", "must contain a string array"))?;
180        info.insert("tags".into(), json!(tags));
181    }
182
183    let info = Params::new(info);
184    BinaryOption::builder()
185        .instrument_id(instrument_id)
186        .raw_symbol(instrument_id.symbol)
187        .asset_class(AssetClass::Alternative)
188        .currency(currency)
189        .activation_ns(UnixNanos::default())
190        .expiration_ns(UnixNanos::from(expiration_ns))
191        .price_precision(PRICE_PRECISION)
192        .size_precision(SIZE_PRECISION)
193        .price_increment(price_increment)
194        .size_increment(size_increment)
195        .outcome(outcome.as_ref().into())
196        .description(description.as_str().into())
197        .info(info)
198        .ts_event(ts_init)
199        .ts_init(ts_init)
200        .build()
201        .map_err(|_| definition_error(market, "instrument", "failed checked construction"))
202}
203
204pub(crate) fn parse_kalshi(
205    market: &Market,
206    native: &KalshiMarket,
207    event: &KalshiEvent,
208    ts_init: UnixNanos,
209) -> Result<BinaryOption, Error> {
210    let (ticker, event_ticker) = kalshi_identity(market)?;
211    if native.ticker != ticker
212        || native.event_ticker != event_ticker
213        || event.event_ticker != event_ticker
214    {
215        return Err(definition_error(
216            market,
217            "identity",
218            "conflicts with public Kalshi metadata",
219        ));
220    }
221
222    let id = to_instrument_id("KALSHI", market.market_id.as_deref().unwrap_or_default())?;
223    let outcome = binary_outcome(market, id)?;
224
225    let mut instrument = parse_definition(native, event, id, outcome == BinaryOutcome::No, ts_init)
226        .map_err(|_| {
227            definition_error(
228                market,
229                "Kalshi metadata",
230                "does not define a supported ordinary binary contract",
231            )
232        })?;
233
234    if market.price < Decimal::ZERO
235        || market.price > Decimal::ONE
236        || !Price::from_decimal_dp(market.price, instrument.price_precision)
237            .is_ok_and(|price| price.as_decimal() == market.price)
238    {
239        return Err(definition_error(
240            market,
241            "price",
242            "is outside the supported exact payout interval",
243        ));
244    }
245
246    instrument.outcome = Some(outcome.as_ref().into());
247    let title = market
248        .title
249        .as_deref()
250        .filter(|title| !title.trim().is_empty())
251        .ok_or_else(|| definition_error(market, "title", "is missing or empty"))?;
252    instrument.description = Some(market.description.as_deref().unwrap_or(title).into());
253    let status = if matches!(market.status, MarketStatus::Closed | MarketStatus::Resolved) {
254        market.status
255    } else {
256        match native.status.as_str() {
257            "closed" | "determined" | "disputed" | "amended" => MarketStatus::Closed,
258            "finalized" => MarketStatus::Resolved,
259            _ => market.status,
260        }
261    };
262
263    let native_info = instrument
264        .info
265        .take()
266        .expect("Kalshi definition retains metadata");
267    let mut info = (*native_info).clone();
268    info.insert("provider".into(), FINFEED.into());
269    info.insert("exchange_id".into(), "KALSHI".into());
270    info.insert("market_id".into(), id.symbol.as_str().into());
271    info.insert("title".into(), title.into());
272    info.insert("status".into(), json!(status));
273    info.insert("finfeed_status".into(), json!(market.status));
274    info.insert("outcome_type".into(), json!(market.outcome_type));
275    info.insert("metadata_source".into(), "KALSHI".into());
276    info.insert("activation_source".into(), "Kalshi.open_time".into());
277    info.insert(
278        "expiration_source".into(),
279        "Kalshi.latest_expiration_time".into(),
280    );
281    info.insert("close_time".into(), json!(native.close_time));
282    instrument.info = Some(Params::new(info));
283    Ok(instrument)
284}
285
286pub(crate) fn kalshi_identity(market: &Market) -> Result<(String, String), Error> {
287    if market.exchange_id.as_deref() != Some("KALSHI") || market.outcome_type != OutcomeType::Binary
288    {
289        return Err(definition_error(
290            market,
291            "outcome_type",
292            "is not a Kalshi binary contract",
293        ));
294    }
295
296    let id = checked_identity(market)?;
297    let outcome = binary_outcome(market, id)?;
298    let ticker = source_string(market, "Ticker")?;
299    let event = source_string(market, "EventTicker")?;
300
301    if id.symbol.as_str() != format!("{ticker}_{}", outcome.as_ref().to_uppercase()) {
302        return Err(definition_error(
303            market,
304            "Ticker",
305            "conflicts with the provider outcome ID",
306        ));
307    }
308
309    Ok((ticker, event))
310}
311
312fn checked_identity(market: &Market) -> Result<InstrumentId, Error> {
313    let exchange_id = market
314        .exchange_id
315        .as_deref()
316        .ok_or_else(|| definition_error(market, "exchange_id", "is missing"))?;
317    let market_id = market
318        .market_id
319        .as_deref()
320        .ok_or_else(|| definition_error(market, "market_id", "is missing"))?;
321    let instrument_id = to_instrument_id(exchange_id, market_id)?;
322
323    if market
324        .exchange
325        .as_ref()
326        .and_then(|exchange| exchange.exchange_id.as_deref())
327        .is_some_and(|nested| nested != exchange_id)
328    {
329        return Err(definition_error(
330            market,
331            "exchange_id",
332            "conflicts with nested exchange",
333        ));
334    }
335
336    if market.outcome_type != OutcomeType::Binary {
337        return Err(definition_error(market, "outcome_type", "is unsupported"));
338    }
339
340    Ok(instrument_id)
341}
342
343fn binary_outcome(market: &Market, instrument_id: InstrumentId) -> Result<BinaryOutcome, Error> {
344    let outcome = market
345        .outcome_name
346        .as_deref()
347        .and_then(|outcome| outcome.parse::<BinaryOutcome>().ok())
348        .ok_or_else(|| definition_error(market, "outcome_name", "must be Yes or No"))?;
349
350    let suffix = match outcome {
351        BinaryOutcome::Yes => "_YES",
352        BinaryOutcome::No => "_NO",
353    };
354
355    if !instrument_id.symbol.as_str().ends_with(suffix) {
356        return Err(definition_error(
357            market,
358            "outcome_name",
359            "conflicts with the provider outcome ID suffix",
360        ));
361    }
362
363    Ok(outcome)
364}
365
366#[derive(Debug, Clone, Copy, PartialEq, Eq, AsRefStr, EnumString)]
367enum BinaryOutcome {
368    Yes,
369    No,
370}
371
372#[derive(Deserialize)]
373struct OutcomeToken {
374    token_id: String,
375    outcome: String,
376}
377
378fn outcome_token(market: &Market, outcome: BinaryOutcome) -> Result<String, Error> {
379    let value = source_string(market, "Tokens")?;
380    let mut tokens: Vec<OutcomeToken> = serde_json::from_str(&value)
381        .map_err(|_| definition_error(market, "Tokens", "is not a valid token array"))?;
382    if tokens.len() != 2 {
383        return Err(definition_error(
384            market,
385            "Tokens",
386            "must contain exactly two binary outcomes",
387        ));
388    }
389
390    let outcomes =
391        [&tokens[0].outcome, &tokens[1].outcome].map(|label| label.parse::<BinaryOutcome>().ok());
392
393    if tokens[0].token_id == tokens[1].token_id
394        || outcomes[0] == outcomes[1]
395        || outcomes.iter().any(Option::is_none)
396        || tokens.iter().any(|token| {
397            token.token_id.is_empty() || !token.token_id.bytes().all(|byte| byte.is_ascii_digit())
398        })
399    {
400        return Err(definition_error(
401            market,
402            "Tokens",
403            "contains ambiguous or invalid identities",
404        ));
405    }
406
407    let index = usize::from(outcomes[0] != Some(outcome));
408    Ok(tokens.swap_remove(index).token_id)
409}
410
411fn source_string(market: &Market, field: &'static str) -> Result<String, Error> {
412    let value = market
413        .source_specific_data
414        .as_ref()
415        .and_then(|source| source.get(field))
416        .ok_or_else(|| definition_error(market, field, "is missing"))?;
417    let value: String = serde_json::from_str(value.get())
418        .map_err(|_| definition_error(market, field, "must be a string"))?;
419    if value.trim().is_empty() {
420        return Err(definition_error(market, field, "is empty"));
421    }
422    Ok(value)
423}
424
425fn exact_price(market: &Market, value: Decimal, field: &'static str) -> Result<Price, Error> {
426    let price = Price::from_decimal_dp(value, PRICE_PRECISION)
427        .map_err(|_| definition_error(market, field, "cannot be represented at price precision"))?;
428    if price.as_decimal() != value {
429        return Err(definition_error(
430            market,
431            field,
432            "would require rounding at price precision",
433        ));
434    }
435    Ok(price)
436}
437
438fn definition_error(market: &Market, field: &'static str, reason: &'static str) -> Error {
439    Error::Definition {
440        exchange_id: market.exchange_id.unwrap_or_default(),
441        market_id: market.market_id.unwrap_or_default(),
442        field,
443        reason,
444    }
445}
446
447#[cfg(test)]
448mod tests {
449    use nautilus_model::enums::CurrencyType;
450    use rstest::rstest;
451
452    use super::*;
453    use crate::http::models::MarketsPage;
454
455    const MARKET: &str = include_str!("../../test_data/polymarket-market.json");
456    const LISTINGS: &str = include_str!("../../test_data/polymarket-listings.json");
457
458    #[rstest]
459    fn binary_pair_preserves_every_instrument_field() {
460        let page: MarketsPage = serde_json::from_str(LISTINGS).unwrap();
461        let markets = page.data.unwrap();
462        let instruments: Vec<_> = markets
463            .iter()
464            .map(|market| parse_instrument(market, UnixNanos::from(123)).unwrap())
465            .collect();
466        let ids: Vec<_> = instruments
467            .iter()
468            .map(|instrument| instrument.id.to_string())
469            .collect();
470        assert_eq!(
471            ids,
472            [
473                "TEST-PAIR_NO.FINFEED_POLYMARKET",
474                "TEST-PAIR_YES.FINFEED_POLYMARKET"
475            ]
476        );
477
478        for (index, instrument) in instruments.iter().enumerate() {
479            let token_id = [
480                "404044040440404404044040440404404044040440404404044040440404404044040440404",
481                "303033030330303303033030330303303033030330303303033030330303303033030330303",
482            ][index];
483            assert_definition_fields(instrument, 123, "0.0010", 1_780_358_400_000_000_000);
484            assert_eq!(instrument.outcome.unwrap().as_str(), ["No", "Yes"][index]);
485            assert_eq!(
486                instrument.description.unwrap().as_str(),
487                markets[index].description.as_deref().unwrap()
488            );
489            let expected_info = serde_json::from_value::<Params>(json!({
490                "provider": "FINFEED", "exchange_id": "POLYMARKET", "market_id": markets[index].market_id,
491                "title": "Authored binary outcome", "status": "Closed",
492                "outcome_type": "Binary", "mechanism": markets[index].mechanism,
493                "condition_id": "0x3333333333333333333333333333333333333333333333333333333333333333",
494                "token_id": token_id,
495                "activation_source": "native_unknown_zero", "expiration_source": "EndDateIso",
496                "question_id": "0x4444444444444444444444444444444444444444444444444444444444444444",
497                "tags": ["Test", "Binary"]
498            })).unwrap();
499            assert_eq!(instrument.info.as_ref().unwrap(), &expected_info);
500        }
501    }
502
503    #[rstest]
504    fn full_metadata_preserves_description_and_question_tags() {
505        let market: Market = serde_json::from_str(MARKET).unwrap();
506        let instrument = parse_instrument(&market, UnixNanos::from(456)).unwrap();
507        assert_definition_fields(&instrument, 456, "0.0100", 1_798_761_600_000_000_000);
508        assert_eq!(
509            instrument.description.unwrap().as_str(),
510            market.description.unwrap()
511        );
512        assert_eq!(instrument.outcome.unwrap().as_str(), "No");
513        let info = instrument.info.unwrap();
514        assert_eq!(
515            info["question_id"],
516            "0x2222222222222222222222222222222222222222222222222222222222222222"
517        );
518        assert_eq!(info["tags"], json!(["Test", "Binary"]));
519        let encoded = serde_json::to_string(&instrument.currency).unwrap();
520        let decoded: Currency = serde_json::from_str(&encoded).unwrap();
521        assert_eq!(decoded, instrument.currency);
522        assert_eq!(decoded.precision, instrument.currency.precision);
523        assert_eq!(decoded.iso4217, instrument.currency.iso4217);
524        assert_eq!(decoded.name, instrument.currency.name);
525        assert_eq!(decoded.currency_type, instrument.currency.currency_type);
526    }
527
528    #[rstest]
529    #[case(include_str!("../../test_data/kalshi-listings.json"), "KALSHI")]
530    #[case(include_str!("../../test_data/myriad-listings.json"), "MYRIAD")]
531    #[case(include_str!("../../test_data/manifold-listings.json"), "MANIFOLD")]
532    #[case(include_str!("../../test_data/hyperliquidoutcome-listings.json"), "HYPERLIQUIDOUTCOME")]
533    #[case(include_str!("../../test_data/pascal-listings.json"), "PASCAL")]
534    #[case(include_str!("../../test_data/geminipm-listings.json"), "GEMINIPM")]
535    #[case(include_str!("../../test_data/cryptocompm-listings.json"), "CRYPTOCOMPM")]
536    #[case(include_str!("../../test_data/forecastex-listings.json"), "FORECASTEX")]
537    fn incomplete_venue_definitions_fail_with_identity_context(
538        #[case] fixture: &str,
539        #[case] exchange: &str,
540    ) {
541        let page: MarketsPage = serde_json::from_str(fixture).unwrap();
542        for market in page.data.unwrap() {
543            match parse_instrument(&market, UnixNanos::default()).unwrap_err() {
544                Error::Definition {
545                    exchange_id,
546                    market_id,
547                    field,
548                    reason,
549                } => {
550                    assert_eq!(exchange_id, exchange);
551                    assert_eq!(Some(market_id), market.market_id);
552                    assert_eq!(field, "source_specific_data");
553                    assert_eq!(
554                        reason,
555                        "has no verified complete definition rules for this venue"
556                    );
557                }
558                e => panic!("Unexpected error: {e}"),
559            }
560        }
561    }
562
563    #[rstest]
564    #[case("MinimumTickSize", json!("0"), "must be in (0, 1)")]
565    #[case("MinimumTickSize", json!("1"), "must be in (0, 1)")]
566    #[case("MinimumTickSize", json!("0.00001"), "would require rounding at price precision")]
567    #[case("MinimumTickSize", json!("0.1234567890123456789012345678901"), "is not an exact decimal")]
568    #[case("MinimumTickSize", json!(false), "must be a string")]
569    #[case("MinimumTickSize", json!(""), "is empty")]
570    #[case("EndDateIso", json!("2027-01-01"), "is not a timestamp with an offset")]
571    #[case("EndDateIso", json!("1960-01-01T00:00:00Z"), "is outside the supported positive nanosecond range")]
572    #[case("EndDateIso", json!("2600-01-01T00:00:00Z"), "is outside the supported positive nanosecond range")]
573    #[case("ConditionId", json!("not-a-condition"), "is invalid")]
574    #[case("Tokens", json!("[]"), "must contain exactly two binary outcomes")]
575    #[case("Tokens", json!("bad-array"), "is not a valid token array")]
576    #[case("Tags", json!("{}"), "must contain a string array")]
577    fn invalid_source_fields_fail_exactly(
578        #[case] field: &str,
579        #[case] value: Value,
580        #[case] reason: &str,
581    ) {
582        let mut value_market: Value = serde_json::from_str(MARKET).unwrap();
583        value_market["source_specific_data"][field] = value;
584        let market: Market = serde_json::from_value(value_market).unwrap();
585        match parse_instrument(&market, UnixNanos::default()).unwrap_err() {
586            Error::Definition {
587                exchange_id,
588                market_id,
589                field: actual_field,
590                reason: actual_reason,
591            } => {
592                assert_eq!(exchange_id, "POLYMARKET");
593                assert_eq!(Some(market_id), market.market_id);
594                assert_eq!(actual_field, field);
595                assert_eq!(actual_reason, reason);
596            }
597            e => panic!("Unexpected error: {e}"),
598        }
599    }
600
601    #[rstest]
602    #[case("ConditionId")]
603    #[case("Tokens")]
604    #[case("MinimumTickSize")]
605    #[case("EndDateIso")]
606    fn missing_source_fields_are_not_defaulted(#[case] field: &str) {
607        let mut market: Market = serde_json::from_str(MARKET).unwrap();
608        market.source_specific_data.as_mut().unwrap().remove(field);
609        assert!(
610            matches!(parse_instrument(&market, UnixNanos::default()), Err(Error::Definition { field: actual, reason: "is missing", .. }) if actual == field)
611        );
612    }
613
614    #[rstest]
615    #[case(OutcomeType::MultipleChoice)]
616    #[case(OutcomeType::Numeric)]
617    #[case(OutcomeType::Other)]
618    fn non_binary_outcomes_are_rejected(#[case] outcome_type: OutcomeType) {
619        let mut market: Market = serde_json::from_str(MARKET).unwrap();
620        market.outcome_type = outcome_type;
621        assert!(matches!(
622            parse_instrument(&market, UnixNanos::default()),
623            Err(Error::Definition {
624                exchange_id,
625                market_id,
626                field: "outcome_type",
627                reason: "is unsupported",
628            }) if exchange_id == "POLYMARKET" && Some(market_id.as_str()) == market.market_id.as_deref()
629        ));
630    }
631
632    #[rstest]
633    #[case("-0.0001")]
634    #[case("1.0001")]
635    #[case("0.12345")]
636    fn prices_outside_probability_or_exact_precision_are_rejected(#[case] price: &str) {
637        let mut market: Market = serde_json::from_str(MARKET).unwrap();
638        market.price = Decimal::from_str_exact(price).unwrap();
639        assert!(matches!(
640            parse_instrument(&market, UnixNanos::default()),
641            Err(Error::Definition { field: "price", .. })
642        ));
643    }
644
645    #[rstest]
646    #[case("0")]
647    #[case("1")]
648    #[case("0.1234")]
649    fn exact_probability_boundaries_are_supported(#[case] price: &str) {
650        let mut market: Market = serde_json::from_str(MARKET).unwrap();
651        market.price = Decimal::from_str_exact(price).unwrap();
652        let instrument = parse_instrument(&market, UnixNanos::from(1)).unwrap();
653        assert_eq!(instrument.price_precision, 4);
654        assert_eq!(
655            instrument.price_increment.as_decimal(),
656            Decimal::from_str_exact("0.01").unwrap()
657        );
658    }
659
660    #[rstest]
661    fn conflicting_exchange_or_outcome_cannot_change_identity() {
662        let mut market: Market = serde_json::from_str(MARKET).unwrap();
663        market.exchange.as_mut().unwrap().exchange_id = Some("KALSHI".into());
664        assert!(matches!(
665            parse_instrument(&market, UnixNanos::default()),
666            Err(Error::Definition {
667                field: "exchange_id",
668                ..
669            })
670        ));
671        market.exchange.as_mut().unwrap().exchange_id = Some("POLYMARKET".into());
672        market.outcome_name = Some("Yes".into());
673        assert!(matches!(
674            parse_instrument(&market, UnixNanos::default()),
675            Err(Error::Definition {
676                field: "outcome_name",
677                reason: "conflicts with the provider outcome ID suffix",
678                ..
679            })
680        ));
681    }
682
683    #[rstest]
684    #[case("duplicate-token")]
685    #[case("duplicate-outcome")]
686    #[case("unsupported-outcome")]
687    #[case("lowercase-outcome")]
688    #[case("empty-token")]
689    fn ambiguous_tokens_are_rejected(#[case] change: &str) {
690        let mut value: Value = serde_json::from_str(MARKET).unwrap();
691        let mut tokens: Value =
692            serde_json::from_str(value["source_specific_data"]["Tokens"].as_str().unwrap())
693                .unwrap();
694
695        match change {
696            "duplicate-token" => tokens[1]["token_id"] = tokens[0]["token_id"].clone(),
697            "duplicate-outcome" => tokens[1]["outcome"] = tokens[0]["outcome"].clone(),
698            "unsupported-outcome" => tokens[1]["outcome"] = "Maybe".into(),
699            "lowercase-outcome" => tokens[1]["outcome"] = "yes".into(),
700            "empty-token" => tokens[1]["token_id"] = "".into(),
701            _ => unreachable!(),
702        }
703
704        value["source_specific_data"]["Tokens"] = serde_json::to_string(&tokens).unwrap().into();
705        let market: Market = serde_json::from_value(value).unwrap();
706        assert!(matches!(
707            parse_instrument(&market, UnixNanos::default()),
708            Err(Error::Definition {
709                field: "Tokens",
710                reason: "contains ambiguous or invalid identities",
711                ..
712            })
713        ));
714    }
715
716    #[rstest]
717    #[case("yes")]
718    #[case("no")]
719    #[case("YES")]
720    #[case("NO")]
721    #[case("Maybe")]
722    #[case("")]
723    #[case(" Yes")]
724    fn native_outcomes_require_exact_binary_labels(#[case] label: &str) {
725        let mut market: Market = serde_json::from_str(MARKET).unwrap();
726        market.outcome_name = Some(label.to_owned());
727        let error = parse_instrument(&market, UnixNanos::default()).unwrap_err();
728
729        let Error::Definition {
730            exchange_id,
731            market_id,
732            field,
733            reason,
734        } = error
735        else {
736            panic!("expected invalid outcome definition");
737        };
738
739        assert_eq!(exchange_id, "POLYMARKET");
740        assert_eq!(Some(market_id), market.market_id);
741        assert_eq!(field, "outcome_name");
742        assert_eq!(reason, "must be Yes or No");
743    }
744
745    #[rstest]
746    #[case("exchange_id", "exchange_id")]
747    #[case("market_id", "market_id")]
748    #[case("title", "title")]
749    #[case("outcome_name", "outcome_name")]
750    #[case("source_specific_data", "ConditionId")]
751    fn missing_normalized_fields_fail_with_exact_context(
752        #[case] field: &str,
753        #[case] error_field: &str,
754    ) {
755        let mut value: Value = serde_json::from_str(MARKET).unwrap();
756        value[field] = Value::Null;
757        let market: Market = serde_json::from_value(value).unwrap();
758        match parse_instrument(&market, UnixNanos::default()).unwrap_err() {
759            Error::Definition {
760                exchange_id,
761                market_id,
762                field: actual_field,
763                ..
764            } => {
765                assert_eq!(actual_field, error_field);
766                assert_eq!(exchange_id, market.exchange_id.unwrap_or_default());
767                assert_eq!(market_id, market.market_id.unwrap_or_default());
768            }
769            e => panic!("Unexpected error: {e}"),
770        }
771    }
772
773    #[rstest]
774    fn absent_optional_description_and_event_fields_do_not_invent_metadata() {
775        let mut market: Market = serde_json::from_str(MARKET).unwrap();
776        market.description = None;
777        let source = market.source_specific_data.as_mut().unwrap();
778        source.remove("QuestionId");
779        source.remove("Tags");
780        source.remove("Description");
781        let instrument = parse_instrument(&market, UnixNanos::default()).unwrap();
782        assert_eq!(
783            instrument.description.unwrap().as_str(),
784            market.title.unwrap()
785        );
786        assert_eq!(instrument.event_id, None);
787        let info = instrument.info.unwrap();
788        assert_eq!(info.get("question_id"), None);
789        assert_eq!(info.get("tags"), None);
790        assert_eq!(info.get_str("outcome_type"), Some("Binary"));
791        assert_eq!(info.get("mechanism"), Some(&serde_json::Value::Null));
792        assert_eq!(info.len(), 11);
793    }
794
795    #[rstest]
796    fn source_description_fills_missing_normalized_description() {
797        let mut market: Market = serde_json::from_str(MARKET).unwrap();
798        let expected = market.description.take().unwrap();
799        let instrument = parse_instrument(&market, UnixNanos::default()).unwrap();
800        assert_eq!(instrument.description.unwrap().as_str(), expected);
801    }
802
803    fn assert_definition_fields(instrument: &BinaryOption, ts: u64, tick: &str, expiry: u64) {
804        assert_eq!(instrument.raw_symbol, instrument.id.symbol);
805        assert_eq!(instrument.asset_class, AssetClass::Alternative);
806        assert_eq!(instrument.currency.code.as_str(), "pUSD");
807        assert_eq!(instrument.currency.precision, 6);
808        assert_eq!(instrument.currency.iso4217, 0);
809        assert_eq!(instrument.currency.name.as_str(), "Polymarket USD");
810        assert_eq!(instrument.currency.currency_type, CurrencyType::Crypto);
811        assert_eq!(instrument.price_precision, 4);
812        assert_eq!(instrument.size_precision, 6);
813        assert_eq!(instrument.price_increment.precision, 4);
814        assert_eq!(
815            instrument.price_increment.as_decimal(),
816            Decimal::from_str_exact(tick).unwrap()
817        );
818        assert_eq!(instrument.size_increment.precision, 6);
819        assert_eq!(
820            instrument.size_increment.as_decimal(),
821            Decimal::from_str_exact("0.000001").unwrap()
822        );
823        assert_eq!(instrument.activation_ns, UnixNanos::default());
824        assert_eq!(instrument.expiration_ns, UnixNanos::from(expiry));
825        assert_eq!(instrument.margin_init, Decimal::ZERO);
826        assert_eq!(instrument.margin_maint, Decimal::ZERO);
827        assert_eq!(instrument.event_id, None);
828        assert_eq!(instrument.min_quantity, None);
829        assert_eq!(instrument.max_quantity, None);
830        assert_eq!(instrument.min_notional, None);
831        assert_eq!(instrument.max_notional, None);
832        assert_eq!(instrument.min_price, None);
833        assert_eq!(instrument.max_price, None);
834        assert_eq!(instrument.tick_scheme, None);
835        assert_eq!(instrument.ts_event, UnixNanos::from(ts));
836        assert_eq!(instrument.ts_init, UnixNanos::from(ts));
837    }
838}