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