1use derive_builder::Builder;
22use nautilus_core::string::secret::SecretString;
23use serde::{Deserialize, Serialize};
24use zeroize::Zeroize;
25
26use crate::common::enums::{
27 LighterCandleResolution, LighterFundingResolution, LighterOrderBookFilter, LighterTradeType,
28};
29
30#[derive(Copy, Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
31#[serde(rename_all = "snake_case")]
32pub enum LighterTxLookup {
33 Hash,
34 SequenceIndex,
35}
36
37#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
38pub struct LighterTxQuery {
39 pub by: LighterTxLookup,
40 pub value: String,
41}
42
43#[derive(Clone, Debug, Default, Deserialize, Serialize, Builder, PartialEq, Eq)]
44#[builder(setter(strip_option), default)]
45pub struct LighterOrderBooksQuery {
46 #[serde(skip_serializing_if = "Option::is_none")]
47 pub market_id: Option<i64>,
48 #[serde(skip_serializing_if = "Option::is_none")]
49 pub filter: Option<LighterOrderBookFilter>,
50}
51
52#[derive(Clone, Debug, Default, Deserialize, Serialize, Builder, PartialEq, Eq)]
53#[builder(setter(strip_option), default)]
54pub struct LighterOrderBookDetailsQuery {
55 #[serde(skip_serializing_if = "Option::is_none")]
56 pub market_id: Option<i64>,
57 #[serde(skip_serializing_if = "Option::is_none")]
58 pub filter: Option<LighterOrderBookFilter>,
59}
60
61#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
62pub struct LighterOrderBookOrdersQuery {
63 pub market_id: i64,
64 pub limit: u16,
65}
66
67#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
68pub struct LighterRecentTradesQuery {
69 pub market_id: i64,
70 pub limit: u16,
71}
72
73#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
74#[builder(setter(strip_option))]
75pub struct LighterCandlesQuery {
76 pub market_id: i64,
77 pub resolution: LighterCandleResolution,
78 pub start_timestamp: i64,
79 pub end_timestamp: i64,
80 pub count_back: i64,
81 #[builder(default)]
82 #[serde(skip_serializing_if = "Option::is_none")]
83 pub set_timestamp_to_end: Option<bool>,
84}
85
86#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
87#[builder(setter(strip_option))]
88pub struct LighterFundingsQuery {
89 pub market_id: i64,
90 pub resolution: LighterFundingResolution,
91 pub start_timestamp: i64,
92 pub end_timestamp: i64,
93 pub count_back: i64,
94}
95
96#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
97#[builder(setter(strip_option))]
98pub struct LighterTradesQuery {
99 #[builder(default)]
100 #[builder(setter(into, strip_option))]
101 #[serde(skip_serializing)]
102 pub authorization: Option<SecretString>,
103 #[builder(default)]
104 #[builder(setter(into, strip_option))]
105 #[serde(skip_serializing)]
106 pub auth: Option<SecretString>,
107 #[builder(default)]
108 #[serde(skip_serializing_if = "Option::is_none")]
109 pub market_id: Option<i64>,
110 #[builder(default)]
111 #[serde(skip_serializing_if = "Option::is_none")]
112 pub account_index: Option<i64>,
113 #[builder(default)]
114 #[serde(skip_serializing_if = "Option::is_none")]
115 pub order_index: Option<i64>,
116 #[builder(default)]
118 #[builder(setter(into, strip_option))]
119 #[serde(skip_serializing_if = "Option::is_none")]
120 pub order_index_str: Option<String>,
121 #[builder(default)]
122 #[serde(skip_serializing_if = "Option::is_none")]
123 pub integrator_account_index: Option<i64>,
124 #[builder(default)]
125 pub sort_by: LighterTradeSortBy,
126 #[builder(default)]
127 #[serde(skip_serializing_if = "Option::is_none")]
128 pub sort_dir: Option<LighterSortDirection>,
129 #[builder(default)]
130 #[builder(setter(into, strip_option))]
131 #[serde(skip_serializing_if = "Option::is_none")]
132 pub cursor: Option<String>,
133 #[builder(default)]
134 #[serde(rename = "from")]
135 #[serde(skip_serializing_if = "Option::is_none")]
136 pub from_timestamp: Option<i64>,
137 #[builder(default)]
138 #[serde(skip_serializing_if = "Option::is_none")]
139 pub ask_filter: Option<i8>,
140 #[builder(default)]
141 #[serde(skip_serializing_if = "Option::is_none")]
142 pub role: Option<LighterTradeRole>,
143 #[builder(default)]
144 #[serde(rename = "type")]
145 #[serde(skip_serializing_if = "Option::is_none")]
146 pub trade_type: Option<LighterTradeQueryType>,
147 #[builder(default = "100")]
148 pub limit: u16,
149 #[builder(default)]
150 #[serde(skip_serializing_if = "Option::is_none")]
151 pub aggregate: Option<bool>,
152}
153
154#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
155#[builder(setter(strip_option))]
156pub struct LighterAccountOrdersQuery {
157 #[builder(default)]
158 #[builder(setter(into, strip_option))]
159 #[serde(skip_serializing)]
160 pub authorization: Option<SecretString>,
161 #[builder(default)]
162 #[builder(setter(into, strip_option))]
163 #[serde(skip_serializing)]
164 pub auth: Option<SecretString>,
165 pub account_index: i64,
166 #[serde(
168 serialize_with = "serialize_client_order_indexes",
169 deserialize_with = "deserialize_client_order_indexes"
170 )]
171 pub client_order_indexes: Vec<i64>,
172}
173
174#[derive(Clone, Debug, Default, Deserialize, Serialize, Builder, PartialEq, Eq)]
175pub struct LighterNextNonceQuery {
176 pub account_index: i64,
177 pub api_key_index: u8,
178}
179
180#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
181#[builder(setter(strip_option))]
182pub struct LighterMakerOnlyApiKeysQuery {
183 #[builder(default)]
184 #[builder(setter(into, strip_option))]
185 #[serde(skip_serializing_if = "Option::is_none")]
186 pub authorization: Option<SecretString>,
187 #[builder(default)]
188 #[builder(setter(into, strip_option))]
189 #[serde(skip_serializing_if = "Option::is_none")]
190 pub auth: Option<SecretString>,
191 pub account_index: i64,
192}
193
194#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
195#[serde(rename_all = "snake_case")]
196pub enum LighterAccountLookup {
197 #[default]
198 Index,
199 L1Address,
200}
201
202#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
203pub struct LighterAccountQuery {
204 pub by: LighterAccountLookup,
205 pub value: String,
206}
207
208#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
209#[builder(setter(strip_option))]
210pub struct LighterAccountActiveOrdersQuery {
211 #[builder(default)]
212 #[builder(setter(into, strip_option))]
213 #[serde(skip_serializing)]
214 pub authorization: Option<SecretString>,
215 #[builder(default)]
216 #[builder(setter(into, strip_option))]
217 #[serde(skip_serializing)]
218 pub auth: Option<SecretString>,
219 pub account_index: i64,
220 pub market_id: i64,
221}
222
223#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
224#[builder(setter(strip_option))]
225pub struct LighterAccountInactiveOrdersQuery {
226 #[builder(default)]
227 #[builder(setter(into, strip_option))]
228 #[serde(skip_serializing)]
229 pub authorization: Option<SecretString>,
230 #[builder(default)]
231 #[builder(setter(into, strip_option))]
232 #[serde(skip_serializing)]
233 pub auth: Option<SecretString>,
234 pub account_index: i64,
235 #[builder(default)]
236 #[serde(skip_serializing_if = "Option::is_none")]
237 pub market_id: Option<i64>,
238 #[builder(default)]
239 #[serde(skip_serializing_if = "Option::is_none")]
240 pub ask_filter: Option<i8>,
241 #[builder(default)]
242 #[builder(setter(into, strip_option))]
243 #[serde(skip_serializing_if = "Option::is_none")]
244 pub between_timestamps: Option<String>,
245 #[builder(default)]
246 #[builder(setter(into, strip_option))]
247 #[serde(skip_serializing_if = "Option::is_none")]
248 pub cursor: Option<String>,
249 pub limit: u16,
250}
251
252macro_rules! impl_auth_query_zeroize {
253 ($type:ident) => {
254 impl Zeroize for $type {
255 fn zeroize(&mut self) {
256 self.authorization.zeroize();
257 self.auth.zeroize();
258 }
259 }
260 };
261}
262
263impl_auth_query_zeroize!(LighterTradesQuery);
264impl_auth_query_zeroize!(LighterMakerOnlyApiKeysQuery);
265impl_auth_query_zeroize!(LighterAccountActiveOrdersQuery);
266impl_auth_query_zeroize!(LighterAccountInactiveOrdersQuery);
267impl_auth_query_zeroize!(LighterAccountOrdersQuery);
268
269#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
270#[serde(rename_all = "snake_case")]
271pub enum LighterTradeSortBy {
272 BlockHeight,
273 Timestamp,
274 #[default]
275 TradeId,
276}
277
278#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
279#[serde(rename_all = "lowercase")]
280pub enum LighterSortDirection {
281 #[default]
282 Desc,
283 Asc,
284}
285
286#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
287#[serde(rename_all = "lowercase")]
288pub enum LighterTradeRole {
289 #[default]
290 All,
291 Maker,
292 Taker,
293}
294
295#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
296#[serde(rename_all = "kebab-case")]
297pub enum LighterTradeQueryType {
298 #[default]
299 All,
300 Trade,
301 Liquidation,
302 Deleverage,
303 MarketSettlement,
304}
305
306impl TryFrom<LighterTradeType> for LighterTradeQueryType {
307 type Error = anyhow::Error;
308
309 fn try_from(value: LighterTradeType) -> Result<Self, Self::Error> {
310 match value {
311 LighterTradeType::Trade => Ok(Self::Trade),
312 LighterTradeType::Liquidation => Ok(Self::Liquidation),
313 LighterTradeType::Deleverage => Ok(Self::Deleverage),
314 LighterTradeType::MarketSettlement => Ok(Self::MarketSettlement),
315 LighterTradeType::Other => Err(anyhow::anyhow!(
316 "Lighter trade type `{value}` has no trade query filter",
317 )),
318 }
319 }
320}
321
322impl Default for LighterTradesQuery {
323 fn default() -> Self {
324 Self {
325 authorization: None,
326 auth: None,
327 market_id: None,
328 account_index: None,
329 order_index: None,
330 order_index_str: None,
331 integrator_account_index: None,
332 sort_by: LighterTradeSortBy::default(),
333 sort_dir: None,
334 cursor: None,
335 from_timestamp: None,
336 ask_filter: None,
337 role: None,
338 trade_type: None,
339 limit: 100,
340 aggregate: None,
341 }
342 }
343}
344
345fn serialize_client_order_indexes<S>(values: &[i64], serializer: S) -> Result<S::Ok, S::Error>
346where
347 S: serde::Serializer,
348{
349 validate_client_order_indexes(values).map_err(serde::ser::Error::custom)?;
350 let joined = values
351 .iter()
352 .map(i64::to_string)
353 .collect::<Vec<_>>()
354 .join(",");
355 serializer.serialize_str(&joined)
356}
357
358fn deserialize_client_order_indexes<'de, D>(deserializer: D) -> Result<Vec<i64>, D::Error>
359where
360 D: serde::Deserializer<'de>,
361{
362 let value = String::deserialize(deserializer)?;
363 let values = value
364 .split(',')
365 .map(str::parse::<i64>)
366 .collect::<Result<Vec<_>, _>>()
367 .map_err(serde::de::Error::custom)?;
368 validate_client_order_indexes(&values).map_err(serde::de::Error::custom)?;
369 Ok(values)
370}
371
372pub(crate) fn validate_client_order_indexes(values: &[i64]) -> Result<(), String> {
373 if (1..=20).contains(&values.len()) {
374 Ok(())
375 } else {
376 Err(format!(
377 "client_order_indexes must contain between 1 and 20 values, was {}",
378 values.len()
379 ))
380 }
381}
382
383#[cfg(test)]
384mod tests {
385
386 use rstest::rstest;
387
388 use super::*;
389
390 #[rstest]
391 fn test_order_books_query_serializes_filter() {
392 let query = LighterOrderBooksQuery {
393 market_id: Some(0),
394 filter: Some(LighterOrderBookFilter::Perp),
395 };
396
397 let value = serde_json::to_value(query).unwrap();
398
399 assert_eq!(value["market_id"], 0);
400 assert_eq!(value["filter"], "perp");
401 }
402
403 #[rstest]
404 fn test_order_book_orders_query_serializes_widened_market_id() {
405 let query = LighterOrderBookOrdersQueryBuilder::default()
406 .market_id(40_000)
407 .limit(10)
408 .build()
409 .unwrap();
410
411 let value = serde_json::to_value(query).unwrap();
412
413 assert_eq!(value["market_id"], 40_000);
414 assert_eq!(value["limit"], 10);
415 }
416
417 #[rstest]
418 fn test_order_book_details_query_serializes_filter() {
419 let query = LighterOrderBookDetailsQueryBuilder::default()
420 .market_id(1)
421 .filter(LighterOrderBookFilter::Spot)
422 .build()
423 .unwrap();
424
425 let value = serde_json::to_value(query).unwrap();
426
427 assert_eq!(value["market_id"], 1);
428 assert_eq!(value["filter"], "spot");
429 }
430
431 #[rstest]
432 fn test_trades_query_renames_type_and_from() {
433 let query = LighterTradesQueryBuilder::default()
434 .market_id(0)
435 .from_timestamp(1_700_000_000_000)
436 .trade_type(LighterTradeQueryType::MarketSettlement)
437 .limit(50)
438 .build()
439 .unwrap();
440
441 let value = serde_json::to_value(query).unwrap();
442
443 assert_eq!(value["sort_by"], "trade_id");
444 assert_eq!(value["from"], 1_700_000_000_000_i64);
445 assert_eq!(value["type"], "market-settlement");
446 assert_eq!(value["limit"], 50);
447 }
448
449 #[rstest]
450 fn test_candles_query_serializes_resolution_and_timestamp_mode() {
451 let query = LighterCandlesQueryBuilder::default()
452 .market_id(0)
453 .resolution(LighterCandleResolution::OneMinute)
454 .start_timestamp(1_700_000_000_000)
455 .end_timestamp(1_700_000_060_000)
456 .count_back(500)
457 .set_timestamp_to_end(false)
458 .build()
459 .unwrap();
460
461 let value = serde_json::to_value(query).unwrap();
462
463 assert_eq!(value["market_id"], 0);
464 assert_eq!(value["resolution"], "1m");
465 assert_eq!(value["start_timestamp"], 1_700_000_000_000_i64);
466 assert_eq!(value["end_timestamp"], 1_700_000_060_000_i64);
467 assert_eq!(value["count_back"], 500);
468 assert_eq!(value["set_timestamp_to_end"], false);
469 }
470
471 #[rstest]
472 fn test_fundings_query_serializes_resolution() {
473 let query = LighterFundingsQueryBuilder::default()
474 .market_id(0)
475 .resolution(LighterFundingResolution::OneHour)
476 .start_timestamp(1_700_000_000_000)
477 .end_timestamp(1_700_003_600_000)
478 .count_back(100)
479 .build()
480 .unwrap();
481
482 let value = serde_json::to_value(query).unwrap();
483
484 assert_eq!(value["market_id"], 0);
485 assert_eq!(value["resolution"], "1h");
486 assert_eq!(value["start_timestamp"], 1_700_000_000_000_i64);
487 assert_eq!(value["end_timestamp"], 1_700_003_600_000_i64);
488 assert_eq!(value["count_back"], 100);
489 }
490
491 #[rstest]
492 fn test_order_book_orders_query_serializes_required_fields() {
493 let query = LighterOrderBookOrdersQuery {
494 market_id: 0,
495 limit: 25,
496 };
497
498 let value = serde_json::to_value(query).unwrap();
499
500 assert_eq!(value["market_id"], 0);
501 assert_eq!(value["limit"], 25);
502 }
503
504 #[rstest]
505 fn test_recent_trades_query_serializes_required_fields() {
506 let query = LighterRecentTradesQueryBuilder::default()
507 .market_id(1)
508 .limit(10)
509 .build()
510 .unwrap();
511
512 let value = serde_json::to_value(query).unwrap();
513
514 assert_eq!(value["market_id"], 1);
515 assert_eq!(value["limit"], 10);
516 }
517
518 #[rstest]
519 fn test_trades_query_serializes_optional_filters() {
520 let mut query = LighterTradesQuery {
521 authorization: Some(SecretString::from("bearer-token")),
522 auth: Some(SecretString::from("auth-token")),
523 market_id: Some(0),
524 account_index: Some(1234),
525 order_index: Some(5678),
526 order_index_str: Some("18446744073709551615".to_string()),
527 integrator_account_index: Some(723_813),
528 sort_by: LighterTradeSortBy::Timestamp,
529 sort_dir: Some(LighterSortDirection::Desc),
530 cursor: Some("cursor-1".to_string()),
531 from_timestamp: Some(1_700_000_000_000),
532 ask_filter: Some(1),
533 role: Some(LighterTradeRole::Maker),
534 trade_type: Some(
535 LighterTradeQueryType::try_from(LighterTradeType::Liquidation).unwrap(),
536 ),
537 limit: 75,
538 aggregate: Some(true),
539 };
540
541 let value = serde_json::to_value(&query).unwrap();
542 let debug = format!("{query:?}");
543
544 assert!(value.get("authorization").is_none());
545 assert!(value.get("auth").is_none());
546 assert_eq!(value["market_id"], 0);
547 assert_eq!(value["account_index"], 1234);
548 assert_eq!(value["order_index"], 5678);
549 assert_eq!(value["order_index_str"], "18446744073709551615");
550 assert_eq!(value["integrator_account_index"], 723_813);
551 assert_eq!(value["sort_by"], "timestamp");
552 assert_eq!(value["sort_dir"], "desc");
553 assert_eq!(
554 serde_json::to_value(LighterSortDirection::Asc).unwrap(),
555 "asc",
556 );
557 assert_eq!(value["cursor"], "cursor-1");
558 assert_eq!(value["from"], 1_700_000_000_000_i64);
559 assert_eq!(value["ask_filter"], 1);
560 assert_eq!(value["role"], "maker");
561 assert_eq!(value["type"], "liquidation");
562 assert_eq!(value["limit"], 75);
563 assert_eq!(value["aggregate"], true);
564 assert!(!debug.contains("bearer-token"));
565 assert!(!debug.contains("auth-token"));
566
567 query.zeroize();
568 assert!(query.authorization.is_none());
569 assert!(query.auth.is_none());
570 }
571
572 #[rstest]
573 fn test_trades_query_omits_announced_filters_when_unset() {
574 let query = LighterTradesQuery::default();
575
576 let value = serde_json::to_value(query).unwrap();
577
578 assert!(value.get("integrator_account_index").is_none());
579 assert!(value.get("order_index_str").is_none());
580 }
581
582 #[rstest]
583 #[case::single(vec![42], "42")]
584 #[case::multiple(vec![42, 43, 44], "42,43,44")]
585 fn test_account_orders_query_serializes_client_order_indexes(
586 #[case] indexes: Vec<i64>,
587 #[case] expected: &str,
588 ) {
589 let query = LighterAccountOrdersQueryBuilder::default()
590 .authorization("bearer-token")
591 .account_index(123)
592 .client_order_indexes(indexes.clone())
593 .build()
594 .unwrap();
595
596 let value = serde_json::to_value(&query).unwrap();
597 let decoded: LighterAccountOrdersQuery = serde_json::from_value(value.clone()).unwrap();
598
599 assert!(value.get("authorization").is_none());
600 assert_eq!(value["account_index"], 123);
601 assert_eq!(value["client_order_indexes"], expected);
602 assert!(value.get("auth").is_none());
603 assert_eq!(decoded.client_order_indexes, indexes);
604 }
605
606 #[rstest]
607 #[case::empty(vec![])]
608 #[case::too_many((1..=21).collect::<Vec<i64>>())]
609 fn test_account_orders_query_rejects_invalid_index_counts(#[case] indexes: Vec<i64>) {
610 let query = LighterAccountOrdersQueryBuilder::default()
611 .account_index(123)
612 .client_order_indexes(indexes)
613 .build()
614 .unwrap();
615
616 assert!(serde_json::to_value(query).is_err());
617 }
618
619 #[rstest]
620 #[case::empty("")]
621 #[case::too_many((1..=21).map(|index| index.to_string()).collect::<Vec<_>>().join(","))]
622 fn test_account_orders_query_rejects_invalid_index_count_deserialization(
623 #[case] indexes: String,
624 ) {
625 let value = serde_json::json!({
626 "account_index": 123,
627 "client_order_indexes": indexes,
628 });
629
630 assert!(serde_json::from_value::<LighterAccountOrdersQuery>(value).is_err());
631 }
632
633 #[rstest]
634 fn test_account_active_orders_query_serializes_required_fields() {
635 let query = LighterAccountActiveOrdersQueryBuilder::default()
636 .auth("auth-token")
637 .account_index(123)
638 .market_id(0)
639 .build()
640 .unwrap();
641
642 let value = serde_json::to_value(query).unwrap();
643
644 assert!(value.get("auth").is_none());
645 assert_eq!(value["account_index"], 123);
646 assert_eq!(value["market_id"], 0);
647 assert!(value.get("authorization").is_none());
648 }
649
650 #[rstest]
651 fn test_account_inactive_orders_query_serializes_optional_filters() {
652 let query = LighterAccountInactiveOrdersQueryBuilder::default()
653 .authorization("bearer-token")
654 .account_index(123)
655 .market_id(0)
656 .ask_filter(1)
657 .between_timestamps("1700000000-1700003600")
658 .cursor("cursor-1")
659 .limit(50)
660 .build()
661 .unwrap();
662
663 let value = serde_json::to_value(query).unwrap();
664
665 assert!(value.get("authorization").is_none());
666 assert_eq!(value["account_index"], 123);
667 assert_eq!(value["market_id"], 0);
668 assert_eq!(value["ask_filter"], 1);
669 assert_eq!(value["between_timestamps"], "1700000000-1700003600",);
670 assert_eq!(value["cursor"], "cursor-1");
671 assert_eq!(value["limit"], 50);
672 assert!(value.get("auth").is_none());
673 }
674
675 #[rstest]
676 #[case::trade(LighterTradeType::Trade, Some(LighterTradeQueryType::Trade))]
677 #[case::liquidation(
678 LighterTradeType::Liquidation,
679 Some(LighterTradeQueryType::Liquidation)
680 )]
681 #[case::deleverage(LighterTradeType::Deleverage, Some(LighterTradeQueryType::Deleverage))]
682 #[case::market_settlement(
683 LighterTradeType::MarketSettlement,
684 Some(LighterTradeQueryType::MarketSettlement)
685 )]
686 #[case::other(LighterTradeType::Other, None)]
687 fn test_trade_query_type_try_from_trade_type(
688 #[case] trade_type: LighterTradeType,
689 #[case] expected: Option<LighterTradeQueryType>,
690 ) {
691 assert_eq!(LighterTradeQueryType::try_from(trade_type).ok(), expected);
692 }
693}