Skip to main content

nautilus_finfeed/common/
enums.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//! FinFeed classifications and OHLCV aggregation labels.
17
18use serde::{Deserialize, Serialize};
19use strum::{AsRefStr, Display, EnumString};
20use ustr::Ustr;
21
22/// Provider market mechanisms, retaining unfamiliar labels.
23#[derive(
24    Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, AsRefStr, Display, EnumString,
25)]
26pub enum MarketMechanism {
27    /// Constant product market maker.
28    #[serde(rename = "CPMM")]
29    #[strum(serialize = "CPMM")]
30    Cpmm,
31    /// Central limit order book.
32    #[serde(rename = "CLOB")]
33    #[strum(serialize = "CLOB")]
34    Clob,
35    /// Unrecognized provider label, retained verbatim.
36    #[serde(untagged)]
37    #[strum(default, transparent)]
38    Other(Ustr),
39}
40
41/// Provider OHLCV aggregation intervals, retaining newly added periods.
42#[derive(
43    Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, AsRefStr, Display, EnumString,
44)]
45pub enum OhlcvInterval {
46    /// 1 second.
47    #[serde(rename = "1SEC")]
48    #[strum(serialize = "1SEC")]
49    Second1,
50    /// 2 seconds.
51    #[serde(rename = "2SEC")]
52    #[strum(serialize = "2SEC")]
53    Second2,
54    /// 3 seconds.
55    #[serde(rename = "3SEC")]
56    #[strum(serialize = "3SEC")]
57    Second3,
58    /// 4 seconds.
59    #[serde(rename = "4SEC")]
60    #[strum(serialize = "4SEC")]
61    Second4,
62    /// 5 seconds.
63    #[serde(rename = "5SEC")]
64    #[strum(serialize = "5SEC")]
65    Second5,
66    /// 6 seconds.
67    #[serde(rename = "6SEC")]
68    #[strum(serialize = "6SEC")]
69    Second6,
70    /// 10 seconds.
71    #[serde(rename = "10SEC")]
72    #[strum(serialize = "10SEC")]
73    Second10,
74    /// 15 seconds.
75    #[serde(rename = "15SEC")]
76    #[strum(serialize = "15SEC")]
77    Second15,
78    /// 20 seconds.
79    #[serde(rename = "20SEC")]
80    #[strum(serialize = "20SEC")]
81    Second20,
82    /// 30 seconds.
83    #[serde(rename = "30SEC")]
84    #[strum(serialize = "30SEC")]
85    Second30,
86    /// 1 minute.
87    #[serde(rename = "1MIN")]
88    #[strum(serialize = "1MIN")]
89    Minute1,
90    /// 2 minutes.
91    #[serde(rename = "2MIN")]
92    #[strum(serialize = "2MIN")]
93    Minute2,
94    /// 3 minutes.
95    #[serde(rename = "3MIN")]
96    #[strum(serialize = "3MIN")]
97    Minute3,
98    /// 4 minutes.
99    #[serde(rename = "4MIN")]
100    #[strum(serialize = "4MIN")]
101    Minute4,
102    /// 5 minutes.
103    #[serde(rename = "5MIN")]
104    #[strum(serialize = "5MIN")]
105    Minute5,
106    /// 6 minutes.
107    #[serde(rename = "6MIN")]
108    #[strum(serialize = "6MIN")]
109    Minute6,
110    /// 10 minutes.
111    #[serde(rename = "10MIN")]
112    #[strum(serialize = "10MIN")]
113    Minute10,
114    /// 15 minutes.
115    #[serde(rename = "15MIN")]
116    #[strum(serialize = "15MIN")]
117    Minute15,
118    /// 20 minutes.
119    #[serde(rename = "20MIN")]
120    #[strum(serialize = "20MIN")]
121    Minute20,
122    /// 30 minutes.
123    #[serde(rename = "30MIN")]
124    #[strum(serialize = "30MIN")]
125    Minute30,
126    /// 1 hour.
127    #[serde(rename = "1HRS")]
128    #[strum(serialize = "1HRS")]
129    Hour1,
130    /// 2 hours.
131    #[serde(rename = "2HRS")]
132    #[strum(serialize = "2HRS")]
133    Hour2,
134    /// 3 hours.
135    #[serde(rename = "3HRS")]
136    #[strum(serialize = "3HRS")]
137    Hour3,
138    /// 4 hours.
139    #[serde(rename = "4HRS")]
140    #[strum(serialize = "4HRS")]
141    Hour4,
142    /// 6 hours.
143    #[serde(rename = "6HRS")]
144    #[strum(serialize = "6HRS")]
145    Hour6,
146    /// 8 hours.
147    #[serde(rename = "8HRS")]
148    #[strum(serialize = "8HRS")]
149    Hour8,
150    /// 12 hours.
151    #[serde(rename = "12HRS")]
152    #[strum(serialize = "12HRS")]
153    Hour12,
154    /// 1 day.
155    #[serde(rename = "1DAY")]
156    #[strum(serialize = "1DAY")]
157    Day1,
158    /// 2 days.
159    #[serde(rename = "2DAY")]
160    #[strum(serialize = "2DAY")]
161    Day2,
162    /// 3 days.
163    #[serde(rename = "3DAY")]
164    #[strum(serialize = "3DAY")]
165    Day3,
166    /// 5 days.
167    #[serde(rename = "5DAY")]
168    #[strum(serialize = "5DAY")]
169    Day5,
170    /// 7 days.
171    #[serde(rename = "7DAY")]
172    #[strum(serialize = "7DAY")]
173    Day7,
174    /// 10 days.
175    #[serde(rename = "10DAY")]
176    #[strum(serialize = "10DAY")]
177    Day10,
178    /// 1 calendar month.
179    #[serde(rename = "1MTH")]
180    #[strum(serialize = "1MTH")]
181    Month1,
182    /// 2 calendar months.
183    #[serde(rename = "2MTH")]
184    #[strum(serialize = "2MTH")]
185    Month2,
186    /// 3 calendar months.
187    #[serde(rename = "3MTH")]
188    #[strum(serialize = "3MTH")]
189    Month3,
190    /// 4 calendar months.
191    #[serde(rename = "4MTH")]
192    #[strum(serialize = "4MTH")]
193    Month4,
194    /// 6 calendar months.
195    #[serde(rename = "6MTH")]
196    #[strum(serialize = "6MTH")]
197    Month6,
198    /// 1 calendar year.
199    #[serde(rename = "1YRS")]
200    #[strum(serialize = "1YRS")]
201    Year1,
202    /// 2 calendar years.
203    #[serde(rename = "2YRS")]
204    #[strum(serialize = "2YRS")]
205    Year2,
206    /// 3 calendar years.
207    #[serde(rename = "3YRS")]
208    #[strum(serialize = "3YRS")]
209    Year3,
210    /// 4 calendar years.
211    #[serde(rename = "4YRS")]
212    #[strum(serialize = "4YRS")]
213    Year4,
214    /// 5 calendar years.
215    #[serde(rename = "5YRS")]
216    #[strum(serialize = "5YRS")]
217    Year5,
218    /// Unrecognized provider label, retained verbatim.
219    #[serde(untagged)]
220    #[strum(default, transparent)]
221    Other(Ustr),
222}
223
224/// Provider OHLCV time units, retaining unfamiliar labels.
225#[derive(
226    Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, AsRefStr, Display, EnumString,
227)]
228pub enum OhlcvUnit {
229    /// Second.
230    #[serde(rename = "second")]
231    #[strum(serialize = "second")]
232    Second,
233    /// Minute.
234    #[serde(rename = "minute")]
235    #[strum(serialize = "minute")]
236    Minute,
237    /// Hour.
238    #[serde(rename = "hour")]
239    #[strum(serialize = "hour")]
240    Hour,
241    /// Day.
242    #[serde(rename = "day")]
243    #[strum(serialize = "day")]
244    Day,
245    /// Month.
246    #[serde(rename = "month")]
247    #[strum(serialize = "month")]
248    Month,
249    /// Year.
250    #[serde(rename = "year")]
251    #[strum(serialize = "year")]
252    Year,
253    /// Unrecognized provider label, retained verbatim.
254    #[serde(untagged)]
255    #[strum(default, transparent)]
256    Other(Ustr),
257}
258
259#[derive(Debug, Clone, Copy, PartialEq, Eq, EnumString)]
260pub(crate) enum Exchange {
261    #[strum(serialize = "KALSHI")]
262    Kalshi,
263    #[strum(serialize = "POLYMARKET")]
264    Polymarket,
265    #[strum(serialize = "MYRIAD")]
266    Myriad,
267    #[strum(serialize = "MANIFOLD")]
268    Manifold,
269    #[strum(serialize = "HYPERLIQUIDOUTCOME")]
270    HyperliquidOutcome,
271    #[strum(serialize = "PASCAL")]
272    Pascal,
273    #[strum(serialize = "GEMINIPM")]
274    GeminiPm,
275    #[strum(serialize = "CRYPTOCOMPM")]
276    CryptocomPm,
277    #[strum(serialize = "FORECASTEX")]
278    Forecastex,
279}
280
281#[cfg(test)]
282mod tests {
283    use rstest::rstest;
284
285    use super::*;
286    use crate::http::models::OhlcvPeriod;
287
288    #[rstest]
289    #[case("KALSHI", Exchange::Kalshi)]
290    #[case("POLYMARKET", Exchange::Polymarket)]
291    #[case("MYRIAD", Exchange::Myriad)]
292    #[case("MANIFOLD", Exchange::Manifold)]
293    #[case("HYPERLIQUIDOUTCOME", Exchange::HyperliquidOutcome)]
294    #[case("PASCAL", Exchange::Pascal)]
295    #[case("GEMINIPM", Exchange::GeminiPm)]
296    #[case("CRYPTOCOMPM", Exchange::CryptocomPm)]
297    #[case("FORECASTEX", Exchange::Forecastex)]
298    fn exchange_labels_preserve_exact_identity(#[case] label: &str, #[case] expected: Exchange) {
299        assert_eq!(label.parse::<Exchange>().unwrap(), expected);
300        assert!(label.to_ascii_lowercase().parse::<Exchange>().is_err());
301    }
302
303    #[rstest]
304    fn every_documented_interval_decodes_and_serializes_verbatim() {
305        let periods: Vec<OhlcvPeriod> =
306            serde_json::from_str(include_str!("../../test_data/periods.json")).unwrap();
307        assert_eq!(periods.len(), 43);
308
309        for period in periods {
310            let interval = period.period_id.unwrap();
311            assert!(!matches!(interval, OhlcvInterval::Other(_)));
312            let label = interval.as_ref();
313            assert_eq!(OhlcvInterval::from(label), interval);
314            assert_eq!(interval.to_string(), label);
315            let encoded = serde_json::to_string(&interval).unwrap();
316            assert_eq!(serde_json::from_str::<String>(&encoded).unwrap(), label);
317            assert_eq!(
318                serde_json::from_str::<OhlcvInterval>(&encoded).unwrap(),
319                interval
320            );
321        }
322    }
323
324    #[rstest]
325    #[case("second", OhlcvUnit::Second)]
326    #[case("minute", OhlcvUnit::Minute)]
327    #[case("hour", OhlcvUnit::Hour)]
328    #[case("day", OhlcvUnit::Day)]
329    #[case("month", OhlcvUnit::Month)]
330    #[case("year", OhlcvUnit::Year)]
331    fn units_preserve_wire_labels(#[case] label: &str, #[case] expected: OhlcvUnit) {
332        assert_eq!(OhlcvUnit::from(label), expected);
333        let encoded = serde_json::to_string(label).unwrap();
334        assert_eq!(
335            serde_json::from_str::<OhlcvUnit>(&encoded).unwrap(),
336            expected
337        );
338        assert_eq!(serde_json::to_string(&expected).unwrap(), encoded);
339        assert_eq!(expected.as_ref(), label);
340        assert_eq!(expected.to_string(), label);
341    }
342
343    #[rstest]
344    #[case("CPMM", MarketMechanism::Cpmm)]
345    #[case("CLOB", MarketMechanism::Clob)]
346    fn mechanisms_preserve_wire_labels(#[case] label: &str, #[case] expected: MarketMechanism) {
347        assert_eq!(MarketMechanism::from(label), expected);
348        let encoded = serde_json::to_string(label).unwrap();
349        assert_eq!(
350            serde_json::from_str::<MarketMechanism>(&encoded).unwrap(),
351            expected
352        );
353        assert_eq!(serde_json::to_string(&expected).unwrap(), encoded);
354        assert_eq!(expected.as_ref(), label);
355        assert_eq!(expected.to_string(), label);
356    }
357
358    #[rstest]
359    #[case("future-provider-label")]
360    #[case("")]
361    fn unfamiliar_labels_retain_exact_spelling(#[case] label: &str) {
362        let encoded = serde_json::to_string(label).unwrap();
363        let mechanism: MarketMechanism = serde_json::from_str(&encoded).unwrap();
364        let interval: OhlcvInterval = serde_json::from_str(&encoded).unwrap();
365        let unit: OhlcvUnit = serde_json::from_str(&encoded).unwrap();
366        assert_eq!(mechanism, MarketMechanism::Other(label.into()));
367        assert_eq!(interval, OhlcvInterval::Other(label.into()));
368        assert_eq!(unit, OhlcvUnit::Other(label.into()));
369        assert_eq!(mechanism.as_ref(), label);
370        assert_eq!(interval.as_ref(), label);
371        assert_eq!(unit.as_ref(), label);
372        assert_eq!(mechanism.to_string(), label);
373        assert_eq!(interval.to_string(), label);
374        assert_eq!(unit.to_string(), label);
375        assert_eq!(MarketMechanism::from(label), mechanism);
376        assert_eq!(OhlcvInterval::from(label), interval);
377        assert_eq!(OhlcvUnit::from(label), unit);
378        assert_eq!(serde_json::to_string(&mechanism).unwrap(), encoded);
379        assert_eq!(serde_json::to_string(&interval).unwrap(), encoded);
380        assert_eq!(serde_json::to_string(&unit).unwrap(), encoded);
381    }
382}