Skip to main content

nautilus_polymarket/common/
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//! Parsing utilities for the Polymarket adapter.
17
18use alloy_primitives::{U256, hex::Buffer};
19pub(crate) use nautilus_core::serialization::decimal::parse as parse_decimal_exact;
20pub use nautilus_core::serialization::{
21    decimal::{
22        deserialize_json as deserialize_decimal_from_json,
23        deserialize_optional_json as deserialize_optional_decimal_from_json,
24    },
25    serialize_decimal_as_str, serialize_optional_decimal_as_str,
26};
27use nautilus_model::identifiers::TradeId;
28use rust_decimal::Decimal;
29use serde::{Deserialize, Deserializer, Serialize, Serializer, de::Error};
30use serde_json::{Number, value::RawValue};
31
32use crate::common::{
33    consts::{MARKET_VERSION_V2, SUPPORTED_MARKET_VERSION},
34    enums::PolymarketOrderSide,
35};
36
37pub(crate) fn validate_market_version(version: Option<&str>) -> anyhow::Result<()> {
38    anyhow::ensure!(
39        version == Some(SUPPORTED_MARKET_VERSION),
40        "Unsupported Polymarket market protocol {}; only {SUPPORTED_MARKET_VERSION} CTF markets are supported",
41        version.unwrap_or("missing"),
42    );
43    Ok(())
44}
45
46pub(crate) fn validate_data_market_version(version: Option<&str>) -> anyhow::Result<&str> {
47    match version {
48        Some(version @ (SUPPORTED_MARKET_VERSION | MARKET_VERSION_V2)) => Ok(version),
49        _ => anyhow::bail!(
50            "Unsupported Polymarket data protocol {}; expected v1 or v2",
51            version.unwrap_or("missing"),
52        ),
53    }
54}
55
56pub(crate) fn validate_execution_market(
57    version: Option<&str>,
58    asset_id: &str,
59) -> anyhow::Result<()> {
60    if validate_data_market_version(version)? == MARKET_VERSION_V2 {
61        let position_id = U256::from_str_radix(asset_id, 10)?;
62        anyhow::ensure!(
63            position_id.to_be_bytes::<32>()[0] != 3,
64            "Unsupported Polymarket Combo execution",
65        );
66    }
67
68    Ok(())
69}
70
71pub(crate) fn validate_outcome_ids(ids: &[String]) -> anyhow::Result<()> {
72    anyhow::ensure!(
73        ids.len() == 2,
74        "Expected 2 asset IDs, received {}",
75        ids.len()
76    );
77    let mut parsed = Vec::with_capacity(2);
78
79    for id in ids {
80        anyhow::ensure!(
81            !id.is_empty() && id.bytes().all(|byte| byte.is_ascii_digit()),
82            "Invalid Polymarket asset ID '{id}': expected decimal uint256",
83        );
84        parsed.push(U256::from_str_radix(id, 10)?);
85    }
86
87    anyhow::ensure!(parsed[0] != parsed[1], "Duplicate Polymarket asset IDs");
88    Ok(())
89}
90
91pub(crate) fn validate_outcomes(outcomes: &[String]) -> anyhow::Result<()> {
92    anyhow::ensure!(
93        outcomes.len() == 2
94            && outcomes.iter().all(|outcome| !outcome.trim().is_empty())
95            && outcomes[0] != outcomes[1],
96        "Expected 2 distinct nonempty Polymarket outcomes",
97    );
98    Ok(())
99}
100
101/// Deserializes a decimal directly from its JSON number token without an `f64` conversion.
102pub fn deserialize_decimal_from_json_number<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
103where
104    D: Deserializer<'de>,
105{
106    let raw = Box::<RawValue>::deserialize(deserializer)?;
107    parse_decimal_exact(raw.get()).map_err(D::Error::custom)
108}
109
110/// Deserializes an optional decimal directly from its JSON number token.
111pub fn deserialize_optional_decimal_from_json_number<'de, D>(
112    deserializer: D,
113) -> Result<Option<Decimal>, D::Error>
114where
115    D: Deserializer<'de>,
116{
117    Option::<Box<RawValue>>::deserialize(deserializer)?
118        .map(|raw| parse_decimal_exact(raw.get()).map_err(D::Error::custom))
119        .transpose()
120}
121
122pub(crate) fn decimal_from_json(raw: &RawValue) -> anyhow::Result<Decimal> {
123    Ok(deserialize_decimal_from_json(raw)?)
124}
125
126/// Deserializes an exact decimal from a numeric string.
127///
128/// # Errors
129///
130/// Returns an error if the JSON shape is unsupported or a value cannot be represented exactly.
131pub fn deserialize_decimal_from_str<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
132where
133    D: Deserializer<'de>,
134{
135    let value = std::borrow::Cow::<'de, str>::deserialize(deserializer)?;
136    parse_decimal_exact(&value).map_err(D::Error::custom)
137}
138
139/// Deserializes an optional exact decimal, treating empty strings as absent.
140///
141/// # Errors
142///
143/// Returns an error if the JSON shape is unsupported or a value cannot be represented exactly.
144pub fn deserialize_optional_decimal_from_str<'de, D>(
145    deserializer: D,
146) -> Result<Option<Decimal>, D::Error>
147where
148    D: Deserializer<'de>,
149{
150    Option::<String>::deserialize(deserializer)?
151        .filter(|value| !value.is_empty())
152        .map(|value| parse_decimal_exact(&value).map_err(D::Error::custom))
153        .transpose()
154}
155
156/// Deserializes the required PolyBolt crypto TWAP display `value` as a finite decimal.
157///
158/// Accepts JSON numbers and numeric strings in plain or scientific notation. Rejects missing,
159/// null, non-finite numbers, and every non-decimal JSON shape.
160pub(crate) fn deserialize_crypto_twap_value<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
161where
162    D: Deserializer<'de>,
163{
164    nautilus_core::serialization::decimal::deserialize_json(deserializer)
165        .map_err(|e| D::Error::custom(format!("invalid decimal-like `value`: {e}")))
166}
167
168/// Serializes a decimal as an exact JSON number token.
169pub fn serialize_decimal_as_json_number<S>(
170    value: &Decimal,
171    serializer: S,
172) -> Result<S::Ok, S::Error>
173where
174    S: Serializer,
175{
176    let raw = RawValue::from_string(value.to_string()).map_err(serde::ser::Error::custom)?;
177    raw.serialize(serializer)
178}
179
180/// Serializes an optional decimal as an exact JSON number token or `null`.
181pub fn serialize_optional_decimal_as_json_number<S>(
182    value: &Option<Decimal>,
183    serializer: S,
184) -> Result<S::Ok, S::Error>
185where
186    S: Serializer,
187{
188    match value {
189        Some(value) => serialize_decimal_as_json_number(value, serializer),
190        None => serializer.serialize_none(),
191    }
192}
193
194/// Deserializes a Polymarket game ID as an opaque identifier.
195///
196/// The Gamma API returns the field in several shapes: an integer on
197/// `GammaEvent`, a numeric string on most `GammaMarket` records, and a
198/// composite `<uuid>:<away>:<home>` string on some sports markets. The value
199/// identifies a venue-side fixture and is never used for arithmetic, so it is
200/// kept verbatim rather than parsed into a number. Both `null` and `-1` (or
201/// `"-1"`) are the "no game" sentinel and map to `None`.
202pub fn deserialize_optional_polymarket_game_id<'de, D>(
203    deserializer: D,
204) -> Result<Option<String>, D::Error>
205where
206    D: Deserializer<'de>,
207{
208    #[derive(Deserialize)]
209    #[serde(untagged)]
210    enum Raw {
211        Str(String),
212        Num(Number),
213    }
214
215    let game_id = match Option::<Raw>::deserialize(deserializer)? {
216        None => return Ok(None),
217        Some(Raw::Str(value)) => value,
218        Some(Raw::Num(value)) => value.to_string(),
219    };
220
221    if game_id.is_empty() || game_id == "-1" {
222        return Ok(None);
223    }
224
225    Ok(Some(game_id))
226}
227
228// FNV-1a 64-bit constants (see http://www.isthe.com/chongo/tech/comp/fnv/).
229const FNV_OFFSET_BASIS: u64 = 0xcbf2_9ce4_8422_2325;
230const FNV_PRIME: u64 = 0x0100_0000_01b3;
231
232/// Derives a deterministic [`TradeId`] for a Polymarket market data trade.
233///
234/// Polymarket does not publish a trade ID with `last_trade_price` events, so
235/// one is derived from the trade's identifying fields. FNV-1a is stable across
236/// architectures and crate versions, and the 0x1f delimiter prevents
237/// variable-length fields from colliding (e.g. `"0.12"` + `"34"` vs `"0.1"` +
238/// `"234"`).
239#[must_use]
240pub fn determine_trade_id(
241    asset_id: &str,
242    side: PolymarketOrderSide,
243    price: &str,
244    size: &str,
245    timestamp: &str,
246) -> TradeId {
247    let side_byte: &[u8] = match side {
248        PolymarketOrderSide::Buy => b"B",
249        PolymarketOrderSide::Sell => b"S",
250    };
251    let mut h: u64 = FNV_OFFSET_BASIS;
252
253    for bytes in [
254        asset_id.as_bytes(),
255        b"\x1f",
256        side_byte,
257        b"\x1f",
258        price.as_bytes(),
259        b"\x1f",
260        size.as_bytes(),
261        b"\x1f",
262        timestamp.as_bytes(),
263    ] {
264        for &b in bytes {
265            h ^= u64::from(b);
266            h = h.wrapping_mul(FNV_PRIME);
267        }
268    }
269
270    let encoded = Buffer::<8>::new().const_format(&h.to_be_bytes());
271    TradeId::new(encoded.as_str())
272}
273
274#[cfg(test)]
275mod tests {
276    use rstest::rstest;
277    use serde::{Deserialize, Serialize};
278
279    use super::*;
280
281    #[rstest]
282    fn test_raw_decimal_shapes_and_twap_value() {
283        let tokens: Vec<Box<RawValue>> =
284            serde_json::from_str(include_str!("../../test_data/decimal_tokens.json")).unwrap();
285        let expected = [
286            Decimal::from_str_exact("0.1234567890123456789012345678").unwrap(),
287            Decimal::from_str_exact("123456789.1234567890123456789").unwrap(),
288        ];
289
290        for (token, expected) in tokens.iter().zip(expected) {
291            assert_eq!(
292                deserialize_decimal_from_json(token.as_ref()).unwrap(),
293                expected
294            );
295            assert_eq!(
296                deserialize_crypto_twap_value(token.as_ref()).unwrap(),
297                expected
298            );
299            assert_eq!(
300                deserialize_optional_decimal_from_json(token.as_ref()).unwrap(),
301                Some(expected)
302            );
303        }
304
305        assert_eq!(
306            deserialize_decimal_from_json_number(tokens[0].as_ref()).unwrap(),
307            expected[0]
308        );
309        assert!(deserialize_decimal_from_json_number(tokens[1].as_ref()).is_err());
310        assert_eq!(
311            deserialize_optional_decimal_from_json(tokens[3].as_ref()).unwrap(),
312            None
313        );
314
315        for token in &tokens[2..] {
316            assert!(deserialize_decimal_from_json(token.as_ref()).is_err());
317            assert!(
318                deserialize_crypto_twap_value(token.as_ref())
319                    .unwrap_err()
320                    .to_string()
321                    .contains("`value`")
322            );
323        }
324    }
325
326    #[rstest]
327    #[case("1e-28", "0.0000000000000000000000000001")]
328    #[case("0.00000000000000000000000000001e1", "0.0000000000000000000000000001")]
329    #[case("792281625142643375935439503350e-1", "79228162514264337593543950335")]
330    #[case("-12345e-4", "-1.2345")]
331    #[case("1.234567890123456789012345678e-1", "0.1234567890123456789012345678")]
332    fn test_parse_decimal_exact_scientific(#[case] raw: &str, #[case] expected: &str) {
333        assert_eq!(
334            parse_decimal_exact(raw).unwrap(),
335            Decimal::from_str_exact(expected).unwrap()
336        );
337    }
338
339    #[rstest]
340    #[case("0.12345678901234567890123456789e0")]
341    #[case("0.12345678901234567890123456789")]
342    #[case("1e-29")]
343    #[case("79228162514264337593543950336")]
344    #[case("NaN")]
345    #[case("Infinity")]
346    #[case("--1e0")]
347    #[case("1e9223372036854775808")]
348    fn test_parse_decimal_exact_rejects_invalid_or_inexact(#[case] raw: &str) {
349        assert!(parse_decimal_exact(raw).is_err(), "accepted {raw}");
350    }
351
352    #[derive(Debug, Deserialize)]
353    struct GameIdHolder {
354        #[serde(default, deserialize_with = "deserialize_optional_polymarket_game_id")]
355        game_id: Option<String>,
356    }
357
358    #[derive(Debug, Deserialize, Serialize)]
359    struct JsonDecimalHolder {
360        #[serde(
361            deserialize_with = "deserialize_decimal_from_json_number",
362            serialize_with = "serialize_decimal_as_json_number"
363        )]
364        value: Decimal,
365        #[serde(
366            default,
367            deserialize_with = "deserialize_optional_decimal_from_json_number",
368            serialize_with = "serialize_optional_decimal_as_json_number"
369        )]
370        optional: Option<Decimal>,
371    }
372
373    #[rstest]
374    fn test_json_decimal_number_preserves_precision() {
375        let json =
376            r#"{"value":0.1234567890123456789012345678,"optional":123456789.1234567890123456789}"#;
377        let holder: JsonDecimalHolder = serde_json::from_str(json).unwrap();
378
379        assert_eq!(
380            holder.value,
381            Decimal::from_str_exact("0.1234567890123456789012345678").unwrap()
382        );
383        assert_eq!(
384            holder.optional,
385            Some(Decimal::from_str_exact("123456789.1234567890123456789").unwrap())
386        );
387        assert_eq!(serde_json::to_string(&holder).unwrap(), json);
388    }
389
390    #[rstest]
391    fn test_optional_json_decimal_number_accepts_null_and_missing() {
392        let null: JsonDecimalHolder =
393            serde_json::from_str(r#"{"value":1,"optional":null}"#).unwrap();
394        let missing: JsonDecimalHolder = serde_json::from_str(r#"{"value":1}"#).unwrap();
395
396        assert_eq!(null.value, Decimal::ONE);
397        assert!(null.optional.is_none());
398        assert_eq!(missing.value, Decimal::ONE);
399        assert!(missing.optional.is_none());
400    }
401
402    #[rstest]
403    #[case::null(r#"{"game_id": null}"#, None)]
404    #[case::missing("{}", None)]
405    #[case::empty_string(r#"{"game_id": ""}"#, None)]
406    #[case::int_neg_one(r#"{"game_id": -1}"#, None)]
407    #[case::str_neg_one(r#"{"game_id": "-1"}"#, None)]
408    #[case::int_zero(r#"{"game_id": 0}"#, Some("0"))]
409    #[case::str_zero(r#"{"game_id": "0"}"#, Some("0"))]
410    #[case::int_value(r#"{"game_id": 1427074}"#, Some("1427074"))]
411    #[case::str_value(r#"{"game_id": "1427074"}"#, Some("1427074"))]
412    // Some sports markets carry a composite `<uuid>:<away>:<home>` game ID.
413    #[case::composite(
414        r#"{"game_id": "dd80aae9-52f9-4c7b-a1cf-7b4ab63cd281:STL:TEX"}"#,
415        Some("dd80aae9-52f9-4c7b-a1cf-7b4ab63cd281:STL:TEX")
416    )]
417    #[case::composite_rematch(
418        r#"{"game_id": "dd80aae9-52f9-4c7b-a1cf-7b4ab63cd281:DAL:LA:m2"}"#,
419        Some("dd80aae9-52f9-4c7b-a1cf-7b4ab63cd281:DAL:LA:m2")
420    )]
421    // Only -1 is the no-game sentinel, so other negatives stay verbatim
422    // rather than collapsing to "no game".
423    #[case::int_neg_other(r#"{"game_id": -2}"#, Some("-2"))]
424    #[case::str_neg_other(r#"{"game_id": "-2"}"#, Some("-2"))]
425    // A numeric ID beyond `i64` must not fail the record it arrived on.
426    #[case::int_beyond_i64(r#"{"game_id": 18446744073709551615}"#, Some("18446744073709551615"))]
427    fn test_deserialize_optional_polymarket_game_id(
428        #[case] payload: &str,
429        #[case] expected: Option<&str>,
430    ) {
431        let holder: GameIdHolder = serde_json::from_str(payload).unwrap();
432        assert_eq!(holder.game_id.as_deref(), expected);
433    }
434
435    #[rstest]
436    fn test_determine_trade_id_is_deterministic() {
437        let id1 = determine_trade_id("asset-1", PolymarketOrderSide::Buy, "0.5", "10", "1700000");
438        let id2 = determine_trade_id("asset-1", PolymarketOrderSide::Buy, "0.5", "10", "1700000");
439        assert_eq!(id1, id2);
440    }
441
442    #[rstest]
443    fn test_determine_trade_id_differentiates_sides() {
444        let buy = determine_trade_id("asset-1", PolymarketOrderSide::Buy, "0.5", "10", "1700000");
445        let sell = determine_trade_id("asset-1", PolymarketOrderSide::Sell, "0.5", "10", "1700000");
446        assert_ne!(buy, sell);
447    }
448
449    #[rstest]
450    fn test_determine_trade_id_field_delimiter_prevents_collision() {
451        // "0.12" + "34" would collide with "0.1" + "234" if fields were concatenated
452        let a = determine_trade_id("asset-1", PolymarketOrderSide::Buy, "0.12", "34", "1700000");
453        let b = determine_trade_id("asset-1", PolymarketOrderSide::Buy, "0.1", "234", "1700000");
454        assert_ne!(a, b);
455    }
456
457    #[rstest]
458    fn test_determine_trade_id_format() {
459        let side = PolymarketOrderSide::Sell;
460        let id = determine_trade_id("asset-225", side, "0.01", "123.45", "1700000000000");
461        assert_eq!(id.as_str(), "007f43ec998548a8");
462    }
463
464    #[rstest]
465    #[case(
466        Some("v1"),
467        "1356938545749799165119972480570561420155507632800475359837393562592731987968",
468        true
469    )]
470    #[case(
471        Some("v2"),
472        "452312848583266388373324160190187140051835877600158453279131187530910662656",
473        true
474    )]
475    #[case(
476        Some("v2"),
477        "904625697166532776746648320380374280103671755200316906558262375061821325312",
478        true
479    )]
480    #[case(
481        Some("v2"),
482        "1356938545749799165119972480570561420155507632800475359837393562592731987968",
483        false
484    )]
485    #[case(Some("v2"), "invalid", false)]
486    #[case(None, "1", false)]
487    #[case(Some("unknown"), "1", false)]
488    fn test_execution_protocol_and_product_boundary(
489        #[case] version: Option<&str>,
490        #[case] asset_id: &str,
491        #[case] supported: bool,
492    ) {
493        assert_eq!(
494            validate_execution_market(version, asset_id).is_ok(),
495            supported
496        );
497    }
498}