nautilus_polymarket/common/

models.rs

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Shared model types for the Polymarket adapter.

use std::fmt::Display;

use nautilus_common::cache::Cache;
use nautilus_model::{
    identifiers::InstrumentId,
    instruments::{Instrument, InstrumentAny},
};
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};
use ustr::Ustr;

use crate::common::{
    enums::{PolymarketOrderSide, PolymarketOutcome, PolymarketSignerType},
    parse::{deserialize_decimal_from_str, serialize_decimal_as_str},
};

/// Returns whether an execution payload belongs to the configured account.
#[must_use]
pub(crate) fn is_owned_by_account(
    maker_address: &str,
    owner: &str,
    user_address: &str,
    api_key: &str,
    signer_type: PolymarketSignerType,
) -> bool {
    (signer_type == PolymarketSignerType::Owner && maker_address.eq_ignore_ascii_case(user_address))
        || owner == api_key
}

/// A maker order included in trade messages.
///
/// Used by both REST trade reports and WebSocket user trade updates
/// to describe each maker-side fill in a match. The `side` field is
/// optional because some trade-event payloads (notably user-channel WS
/// fills) may omit it; CLOB V2 REST trade responses always include it.
///
/// `fee_rate_bps` is intentionally not modeled. The wire payload is unstable
/// (the user-channel WS sometimes sends `""`) and the field is unused: maker
/// fills always pay zero commission per Polymarket's fee policy. The official
/// `rs-clob-client-v2` `MakerOrder` shape also omits it.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct PolymarketMakerOrder {
    pub asset_id: Ustr,
    pub maker_address: String,
    #[serde(
        serialize_with = "serialize_decimal_as_str",
        deserialize_with = "deserialize_decimal_from_str"
    )]
    pub matched_amount: Decimal,
    pub order_id: String,
    pub outcome: PolymarketOutcome,
    pub owner: String,
    #[serde(
        serialize_with = "serialize_decimal_as_str",
        deserialize_with = "deserialize_decimal_from_str"
    )]
    pub price: Decimal,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub side: Option<PolymarketOrderSide>,
}

impl PolymarketMakerOrder {
    /// Returns whether this maker order belongs to the account identified by
    /// `user_address` and `api_key`.
    ///
    /// Session signers require an exact API-key match; the wallet can have other signers.
    /// For owner signers, the address comparison ignores ASCII case: hex letter case carries no
    /// account identity (EIP-55 checksumming encodes only a display checksum),
    /// and the two sides routinely disagree: recorded venue payloads carry
    /// checksummed maker addresses while configured funder addresses are
    /// commonly lowercase, or vice versa. The API-key comparison stays exact
    /// because keys are opaque credentials.
    #[must_use]
    pub(crate) fn is_owned_by(
        &self,
        user_address: &str,
        api_key: &str,
        signer_type: PolymarketSignerType,
    ) -> bool {
        is_owned_by_account(
            &self.maker_address,
            &self.owner,
            user_address,
            api_key,
            signer_type,
        )
    }
}

/// Human-readable label for a Polymarket instrument.
#[derive(Debug, Clone)]
pub struct PolymarketLabel {
    pub description: String,
    pub outcome: String,
}

impl Display for PolymarketLabel {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{} [{}]", self.description, self.outcome)
    }
}

impl PolymarketLabel {
    /// Build a label from an instrument reference.
    pub fn from_instrument(instrument: &InstrumentAny) -> Self {
        if let InstrumentAny::BinaryOption(opt) = instrument {
            Self {
                description: opt
                    .description
                    .map_or_else(|| instrument.id().to_string(), |d| d.to_string()),
                outcome: opt
                    .outcome
                    .map_or_else(|| "?".to_string(), |o| o.to_string()),
            }
        } else {
            Self {
                description: instrument.id().to_string(),
                outcome: "?".to_string(),
            }
        }
    }

    /// Look up an instrument by ID in the cache and build a label.
    /// Returns `None` if the instrument is not in the cache.
    pub fn from_cache(instrument_id: &InstrumentId, cache: &Cache) -> Option<Self> {
        cache.instrument(instrument_id).map(Self::from_instrument)
    }
}

#[cfg(test)]
mod tests {
    use rstest::rstest;
    use rust_decimal_macros::dec;

    use super::*;
    use crate::{common::enums::PolymarketOutcome, http::models::PolymarketTradeReport};

    fn load<T: serde::de::DeserializeOwned>(filename: &str) -> T {
        let path = format!("test_data/{filename}");
        let content = std::fs::read_to_string(path).expect("Failed to read test data");
        serde_json::from_str(&content).expect("Failed to parse test data")
    }

    fn sample_maker_order_json() -> &'static str {
        r#"{
            "asset_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
            "fee_rate_bps": "10",
            "maker_address": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
            "matched_amount": "50.0000",
            "order_id": "0xorder001",
            "outcome": "Yes",
            "owner": "00000000-0000-0000-0000-000000000002",
            "price": "0.6000"
        }"#
    }

    #[rstest]
    fn test_maker_order_deserialization() {
        let order: PolymarketMakerOrder = serde_json::from_str(sample_maker_order_json()).unwrap();

        assert_eq!(
            order.asset_id.as_str(),
            "71321045679252212594626385532706912750332728571942532289631379312455583992563"
        );
        assert_eq!(
            order.maker_address.as_str(),
            "0x70997970c51812dc3a010c7d01b50e0d17dc79c8"
        );
        assert_eq!(order.matched_amount, dec!(50.0000));
        assert_eq!(order.order_id, "0xorder001");
        assert_eq!(order.outcome, PolymarketOutcome::yes());
        assert_eq!(order.price, dec!(0.6000));
    }

    #[rstest]
    fn test_maker_order_roundtrip() {
        let order: PolymarketMakerOrder = serde_json::from_str(sample_maker_order_json()).unwrap();
        let json = serde_json::to_string(&order).unwrap();
        let order2: PolymarketMakerOrder = serde_json::from_str(&json).unwrap();
        assert_eq!(order, order2);
    }

    #[rstest]
    fn test_maker_order_ownership_ignores_address_case() {
        let mut order: PolymarketMakerOrder =
            serde_json::from_str(sample_maker_order_json()).unwrap();
        let lowercase_address = order.maker_address.clone();
        // All-uppercase hex stands in for the mixed-case checksummed form the
        // venue sends; any case difference exercises the same comparison.
        let uppercase_variant_address = lowercase_address
            .to_ascii_uppercase()
            .replacen("0X", "0x", 1);
        assert_ne!(uppercase_variant_address, lowercase_address);

        // Production direction: venue payloads carry checksummed maker
        // addresses while configured funder addresses are commonly lowercase.
        order.maker_address = uppercase_variant_address.clone();
        assert!(order.is_owned_by(
            &lowercase_address,
            "no-such-key",
            PolymarketSignerType::Owner
        ));

        // Reverse direction: lowercase payload, mixed-case configuration.
        order.maker_address = lowercase_address;
        assert!(order.is_owned_by(
            &uppercase_variant_address,
            "no-such-key",
            PolymarketSignerType::Owner
        ));
    }

    #[rstest]
    fn test_maker_order_ownership_matches_exact_api_key() {
        let order: PolymarketMakerOrder = serde_json::from_str(sample_maker_order_json()).unwrap();
        let owner = order.owner.clone();

        assert!(order.is_owned_by("0xother", &owner, PolymarketSignerType::Owner));
    }

    #[rstest]
    fn test_maker_order_ownership_requires_exact_api_key() {
        let mut order: PolymarketMakerOrder =
            serde_json::from_str(sample_maker_order_json()).unwrap();
        order.owner = "abcdefab-0000-0000-0000-000000000002".to_string();
        let case_variant_key = order.owner.to_ascii_uppercase();
        assert_ne!(case_variant_key, order.owner);

        assert!(!order.is_owned_by("0xother", &case_variant_key, PolymarketSignerType::Owner));
    }

    #[rstest]
    fn test_maker_order_ownership_rejects_foreign_identity() {
        let order: PolymarketMakerOrder = serde_json::from_str(sample_maker_order_json()).unwrap();

        assert!(!order.is_owned_by("0xother", "no-such-key", PolymarketSignerType::Owner));
    }

    #[rstest]
    fn test_maker_order_outcome_no() {
        let json = r#"{
            "asset_id": "12345",
            "fee_rate_bps": "0",
            "maker_address": "0xaddr",
            "matched_amount": "10.0",
            "order_id": "order-1",
            "outcome": "No",
            "owner": "owner-1",
            "price": "0.4"
        }"#;
        let order: PolymarketMakerOrder = serde_json::from_str(json).unwrap();
        assert_eq!(order.outcome, PolymarketOutcome::no());
    }

    #[rstest]
    fn test_maker_order_decimal_precision() {
        // Verifies Decimal fields are serialized as strings (not floats)
        let order: PolymarketMakerOrder = serde_json::from_str(sample_maker_order_json()).unwrap();
        let json = serde_json::to_string(&order).unwrap();
        // Decimals must appear as quoted strings, not bare numbers
        assert!(
            json.contains("\"matched_amount\":\"50.0000\"")
                || json.contains("\"matched_amount\": \"50.0000\"")
        );
    }

    // Tests for embedded maker orders from the trade report fixture
    #[rstest]
    fn test_maker_orders_from_trade_report() {
        let trade: PolymarketTradeReport = load("http_trade_report.json");

        assert_eq!(trade.maker_orders.len(), 2);
        let m0 = &trade.maker_orders[0];
        assert_eq!(m0.matched_amount, dec!(25.0000));
        assert_eq!(m0.outcome, PolymarketOutcome::yes());
        assert_eq!(m0.side, Some(PolymarketOrderSide::Sell));

        let m1 = &trade.maker_orders[1];
        assert_eq!(m1.matched_amount, dec!(5.0000));
        assert_eq!(m1.side, Some(PolymarketOrderSide::Sell));
    }

    #[rstest]
    fn test_maker_order_without_side_is_accepted() {
        // The legacy/WS payload shape that omits `side` must still parse,
        // since the field is optional on `PolymarketMakerOrder`.
        let order: PolymarketMakerOrder = serde_json::from_str(sample_maker_order_json()).unwrap();
        assert!(order.side.is_none());
    }

    #[rstest]
    fn test_maker_order_with_side_is_parsed() {
        let json = r#"{
            "asset_id": "12345",
            "fee_rate_bps": "0",
            "maker_address": "0xaddr",
            "matched_amount": "10.0",
            "order_id": "order-1",
            "outcome": "Yes",
            "owner": "owner-1",
            "price": "0.4",
            "side": "BUY"
        }"#;
        let order: PolymarketMakerOrder = serde_json::from_str(json).unwrap();
        assert_eq!(order.side, Some(PolymarketOrderSide::Buy));
    }

    #[rstest]
    fn test_maker_order_with_empty_fee_rate_bps_is_accepted() {
        // Production user-channel WS sometimes emits `"fee_rate_bps": ""` on
        // maker orders. The field is unmodeled, so the empty string must not
        // break parsing. Mirrors the official `rs-clob-client-v2` shape.
        let json = r#"{
            "asset_id": "12345",
            "fee_rate_bps": "",
            "maker_address": "0xaddr",
            "matched_amount": "10.0",
            "order_id": "order-1",
            "outcome": "Yes",
            "owner": "owner-1",
            "price": "0.4"
        }"#;
        let order: PolymarketMakerOrder = serde_json::from_str(json).unwrap();
        assert_eq!(order.matched_amount, dec!(10.0));
    }

    #[rstest]
    #[case(PolymarketSignerType::Owner, "other", true)]
    #[case(PolymarketSignerType::Session, "other", false)]
    #[case(PolymarketSignerType::Session, "session-api", true)]
    #[case(PolymarketSignerType::Session, "SESSION-API", false)]
    fn test_shared_wallet_session_ownership(
        #[case] signer_type: PolymarketSignerType,
        #[case] owner: &str,
        #[case] expected: bool,
    ) {
        assert_eq!(
            is_owned_by_account("0xwallet", owner, "0xwallet", "session-api", signer_type),
            expected
        );
    }
}