1use std::{
19 cell::{Cell, RefCell},
20 sync::LazyLock,
21};
22
23use ahash::{AHashMap, AHashSet};
24use jiff::{
25 civil::{Date, Time},
26 tz::TimeZone,
27};
28use nautilus_core::{UnixNanos, datetime::get_timezone};
29use nautilus_model::{
30 data::Data,
31 enums::{AssetClass, PriceType},
32 identifiers::InstrumentId,
33 instruments::Instrument,
34 types::{Currency, Money, Price},
35};
36use rust_decimal::Decimal;
37use serde::Serialize;
38
39use super::{
40 AccountAdjustmentError, AccountAdjustmentOutcome, ExchangeContext, SimulationModule,
41 SimulationModuleResult,
42};
43#[cfg(feature = "python")]
44use crate::python::modules::PySimulationModule;
45
46const LOCATION_CURRENCY_MAP: &[(&str, &str)] = &[
47 ("AUS", "AUD"),
48 ("CAN", "CAD"),
49 ("CHE", "CHF"),
50 ("EA19", "EUR"),
51 ("USA", "USD"),
52 ("JPN", "JPY"),
53 ("NZL", "NZD"),
54 ("GBR", "GBP"),
55 ("RUS", "RUB"),
56 ("NOR", "NOK"),
57 ("CHN", "CNY"),
58 ("MEX", "MXN"),
59 ("ZAF", "ZAR"),
60];
61
62static EASTERN_TIMEZONE: LazyLock<TimeZone> =
63 LazyLock::new(|| get_timezone("America/New_York").expect("bundled America/New_York timezone"));
64
65fn eastern_timezone() -> &'static TimeZone {
66 &EASTERN_TIMEZONE
67}
68
69#[derive(Debug, Clone, Serialize)]
71#[cfg_attr(
72 feature = "python",
73 pyo3::pyclass(module = "nautilus_trader.backtest", from_py_object)
74)]
75#[cfg_attr(
76 feature = "python",
77 pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.backtest")
78)]
79pub struct InterestRateRecord {
80 pub location: String,
83 pub time: String,
85 pub value: Decimal,
87}
88
89#[derive(Debug, Clone)]
94pub struct RolloverInterestCalculator {
95 rates: AHashMap<String, AHashMap<String, Decimal>>,
97}
98
99impl RolloverInterestCalculator {
100 #[must_use]
105 pub fn new(records: Vec<InterestRateRecord>) -> Self {
106 let location_to_currency: AHashMap<&str, &str> =
107 LOCATION_CURRENCY_MAP.iter().copied().collect();
108
109 let mut rates: AHashMap<String, AHashMap<String, Decimal>> = AHashMap::new();
110
111 for record in records {
112 if record.location == "CHN" {
114 rates
115 .entry("CNH".to_string())
116 .or_default()
117 .insert(record.time.clone(), record.value);
118 }
119
120 if let Some(¤cy) = location_to_currency.get(record.location.as_str()) {
121 rates
122 .entry(currency.to_string())
123 .or_default()
124 .insert(record.time, record.value);
125 }
126 }
127
128 Self { rates }
129 }
130
131 pub fn calc_overnight_rate(
139 &self,
140 instrument_id: InstrumentId,
141 date: Date,
142 ) -> anyhow::Result<Decimal> {
143 let symbol = instrument_id.symbol.as_str();
144 if symbol.len() < 6 {
145 anyhow::bail!("FX symbol must be at least 6 characters: {symbol}");
146 }
147
148 let base_currency = &symbol[..3];
149 let quote_currency = &symbol[symbol.len() - 3..];
150
151 let base_rate = self.lookup_rate(base_currency, date)?;
152 let quote_rate = self.lookup_rate(quote_currency, date)?;
153
154 base_rate
155 .checked_sub(quote_rate)
156 .and_then(|rate| rate.checked_div(Decimal::from(36_500)))
157 .ok_or_else(|| anyhow::anyhow!("overnight interest rate calculation overflow"))
158 }
159
160 fn lookup_rate(&self, currency: &str, date: Date) -> anyhow::Result<Decimal> {
161 let currency_rates = self
162 .rates
163 .get(currency)
164 .ok_or_else(|| anyhow::anyhow!("No rate data for currency {currency}"))?;
165
166 let monthly_key = format!("{}-{:02}", date.year(), date.month());
168 if let Some(&rate) = currency_rates.get(&monthly_key) {
169 return Ok(rate);
170 }
171
172 let quarter = (date.month() - 1) / 3 + 1;
174 let quarterly_key = format!("{}-Q{quarter}", date.year());
175 if let Some(&rate) = currency_rates.get(&quarterly_key) {
176 return Ok(rate);
177 }
178
179 anyhow::bail!("No rate data for {currency} at {monthly_key} or {quarterly_key}")
180 }
181}
182
183#[derive(Debug, Clone)]
189#[cfg_attr(
190 feature = "python",
191 pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.backtest")
192)]
193#[cfg_attr(
194 feature = "python",
195 pyo3::pyclass(
196 module = "nautilus_trader.backtest",
197 extends = PySimulationModule,
198 unsendable,
199 )
200)]
201pub struct FXRolloverInterestModule {
202 calculator: RolloverInterestCalculator,
203 rollover_completed: Cell<bool>,
204 rollover_day: RefCell<Option<RolloverDayState>>,
205 rollover_totals: RefCell<AHashMap<Currency, Decimal>>,
206 unapplied_rollover_totals: RefCell<AHashMap<Currency, Decimal>>,
207}
208
209#[derive(Debug, Clone)]
210struct RolloverDayState {
211 date: Date,
212 warned_failures: AHashSet<(Date, InstrumentId, RolloverFailureKind)>,
213 warned_adjustment_failures: AHashSet<(Date, Currency, AccountAdjustmentFailureKind)>,
214 pending_adjustments: Option<Vec<RolloverAdjustment>>,
215 pending_end_date: Option<Date>,
216 attempt_time: Option<UnixNanos>,
217}
218
219#[derive(Debug, Clone, PartialEq, Eq)]
220struct RolloverAdjustment {
221 booking_date: Date,
222 amount: Money,
223}
224
225enum RolloverCalculationOutcome {
226 Completed(Vec<Money>),
227 Retry,
228}
229
230#[derive(Clone, Copy, Debug, PartialEq, Eq)]
231enum RolloverFailureDisposition {
232 RetryDay,
233 SkipInstrument,
234}
235
236#[derive(Clone, Copy, Debug, PartialEq, Eq)]
237enum AccountAdjustmentFailureDisposition {
238 Retry,
239 RecordUnapplied,
240}
241
242#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
243enum RolloverFailureKind {
244 Engine,
245 Money,
246 Price,
247 Rate,
248 Xrate,
249}
250
251impl RolloverFailureKind {
252 const fn disposition(self) -> RolloverFailureDisposition {
253 match self {
254 Self::Engine | Self::Price | Self::Xrate => RolloverFailureDisposition::RetryDay,
255 Self::Money | Self::Rate => RolloverFailureDisposition::SkipInstrument,
256 }
257 }
258}
259
260#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
261enum AccountAdjustmentFailureKind {
262 TotalOverflow,
263 FreeBalanceOverflow,
264 MissingBalance,
265 MissingAccount,
266 AccountStateGeneration,
267}
268
269impl From<&AccountAdjustmentError> for AccountAdjustmentFailureKind {
270 fn from(error: &AccountAdjustmentError) -> Self {
271 match error {
272 AccountAdjustmentError::TotalOverflow(_) => Self::TotalOverflow,
273 AccountAdjustmentError::FreeBalanceOverflow(_) => Self::FreeBalanceOverflow,
274 AccountAdjustmentError::MissingBalance(_) => Self::MissingBalance,
275 AccountAdjustmentError::MissingAccount(_) => Self::MissingAccount,
276 AccountAdjustmentError::AccountStateGeneration(_) => Self::AccountStateGeneration,
277 }
278 }
279}
280
281impl AccountAdjustmentFailureKind {
282 const fn disposition(self) -> AccountAdjustmentFailureDisposition {
283 match self {
284 Self::TotalOverflow | Self::FreeBalanceOverflow | Self::AccountStateGeneration => {
285 AccountAdjustmentFailureDisposition::Retry
286 }
287 Self::MissingBalance | Self::MissingAccount => {
288 AccountAdjustmentFailureDisposition::RecordUnapplied
289 }
290 }
291 }
292}
293
294impl FXRolloverInterestModule {
295 #[must_use]
299 pub fn new(records: Vec<InterestRateRecord>) -> Self {
300 Self {
301 calculator: RolloverInterestCalculator::new(records),
302 rollover_completed: Cell::new(false),
303 rollover_day: RefCell::new(None),
304 rollover_totals: RefCell::new(AHashMap::new()),
305 unapplied_rollover_totals: RefCell::new(AHashMap::new()),
306 }
307 }
308
309 fn initialize_rollover_day(&self, date: Date) {
310 self.rollover_day.replace(Some(RolloverDayState {
311 date,
312 warned_failures: AHashSet::new(),
313 warned_adjustment_failures: AHashSet::new(),
314 pending_adjustments: None,
315 pending_end_date: None,
316 attempt_time: None,
317 }));
318 self.rollover_completed.set(false);
319 }
320
321 fn rollover_time_ns(date: Date) -> u64 {
322 let rollover_eastern = date.to_datetime(Time::constant(17, 0, 0, 0));
323 let timestamp = eastern_timezone()
324 .to_ambiguous_timestamp(rollover_eastern)
325 .unambiguous()
326 .expect("unambiguous rollover time")
327 .as_nanosecond();
328 u64::try_from(timestamp).expect("rollover timestamp in range")
329 }
330
331 fn weekday_on_or_before(mut date: Date) -> Date {
332 while date.weekday().to_monday_one_offset() > 5 {
333 date = date.yesterday().expect("previous rollover date in range");
334 }
335 date
336 }
337
338 fn next_weekday(mut date: Date) -> Date {
339 loop {
340 date = date.tomorrow().expect("next rollover date in range");
341 if date.weekday().to_monday_one_offset() <= 5 {
342 return date;
343 }
344 }
345 }
346
347 fn log_calculation_failure(
355 &self,
356 booking_date: Date,
357 instrument_id: InstrumentId,
358 kind: RolloverFailureKind,
359 message: &str,
360 ) {
361 let first_failure = self
362 .rollover_day
363 .borrow_mut()
364 .as_mut()
365 .expect("rollover day initialized")
366 .warned_failures
367 .insert((booking_date, instrument_id, kind));
368
369 if first_failure {
370 log::warn!("{message}");
371 } else {
372 log::debug!("{message}");
373 }
374 }
375
376 fn calculate_rollover_interest(
377 &self,
378 date: Date,
379 iso_weekday: i8,
380 ctx: &ExchangeContext,
381 ) -> RolloverCalculationOutcome {
382 let mut instrument_ids = ctx.instruments.keys().copied().collect::<Vec<_>>();
383 instrument_ids.sort_unstable();
384 let mut adjustments = Vec::new();
385
386 for instrument_id in instrument_ids {
387 match self.calculate_instrument_rollover(date, iso_weekday, ctx, instrument_id) {
388 Ok(Some(adjustment)) => adjustments.push(adjustment),
389 Ok(None) => {}
390 Err(kind) => match kind.disposition() {
391 RolloverFailureDisposition::RetryDay => {
392 return RolloverCalculationOutcome::Retry;
393 }
394 RolloverFailureDisposition::SkipInstrument => {}
395 },
396 }
397 }
398
399 RolloverCalculationOutcome::Completed(adjustments)
400 }
401
402 fn calculate_instrument_rollover(
403 &self,
404 date: Date,
405 iso_weekday: i8,
406 ctx: &ExchangeContext,
407 instrument_id: InstrumentId,
408 ) -> Result<Option<Money>, RolloverFailureKind> {
409 let instrument = &ctx.instruments[&instrument_id];
410
411 if instrument.asset_class() != AssetClass::FX {
412 return Ok(None);
413 }
414
415 let positions =
416 ctx.cache
417 .positions_open(Some(&ctx.venue), Some(&instrument_id), None, None, None);
418
419 if positions.is_empty() {
420 return Ok(None);
421 }
422
423 let interest_rate = match self.calculator.calc_overnight_rate(instrument_id, date) {
427 Ok(rate) => rate,
428 Err(e) => {
429 let kind = RolloverFailureKind::Rate;
430 self.log_calculation_failure(
431 date,
432 instrument_id,
433 kind,
434 &format!("Skipping rollover for {instrument_id} on {date}: {e}"),
435 );
436
437 return Err(kind);
438 }
439 };
440
441 let Some(matching_engine) = ctx.matching_engines.get(&instrument_id) else {
442 self.log_calculation_failure(
443 date,
444 instrument_id,
445 RolloverFailureKind::Engine,
446 &format!("Cannot calculate rollover for {instrument_id}: no matching engine"),
447 );
448 return Err(RolloverFailureKind::Engine);
449 };
450
451 let book = matching_engine.get_book();
452
453 let mid = rollover_midpoint(book.best_bid_price(), book.best_ask_price());
454
455 let mid = match mid {
456 Ok(mid) => mid,
457 Err(e) => {
458 self.log_calculation_failure(
459 date,
460 instrument_id,
461 RolloverFailureKind::Price,
462 &format!("Cannot calculate rollover for {instrument_id}: {e}"),
463 );
464 return Err(RolloverFailureKind::Price);
465 }
466 };
467
468 let net_qty = positions.iter().try_fold(Decimal::ZERO, |total, position| {
469 total.checked_add(position.signed_qty)
470 });
471
472 let mut rollover = net_qty
473 .and_then(|qty| qty.checked_mul(mid))
474 .and_then(|value| value.checked_mul(interest_rate));
475
476 if iso_weekday == 3 || iso_weekday == 5 {
477 rollover = rollover.and_then(|value| value.checked_mul(Decimal::from(3)));
478 }
479
480 let currency = if let Some(base) = ctx.base_currency {
481 let xrate = self
482 .rollover_xrate(date, instrument_id, instrument.quote_currency(), base, ctx)
483 .ok_or(RolloverFailureKind::Xrate)?;
484
485 rollover = rollover.and_then(|value| value.checked_mul(xrate));
486 base
487 } else {
488 instrument.quote_currency()
489 };
490
491 let adjustment = rollover
492 .ok_or_else(|| anyhow::anyhow!("rollover interest arithmetic overflow"))
493 .and_then(|value| Money::from_decimal(value, currency).map_err(Into::into));
494
495 let adjustment = match adjustment {
496 Ok(adjustment) => adjustment,
497 Err(e) => {
498 let kind = RolloverFailureKind::Money;
499 self.log_calculation_failure(
500 date,
501 instrument_id,
502 kind,
503 &format!(
504 "Skipping rollover for {instrument_id} on {date}: invalid adjustment: {e}"
505 ),
506 );
507
508 return Err(kind);
509 }
510 };
511
512 Ok(Some(adjustment))
513 }
514
515 fn rollover_xrate(
516 &self,
517 date: Date,
518 instrument_id: InstrumentId,
519 quote_currency: Currency,
520 base: Currency,
521 ctx: &ExchangeContext,
522 ) -> Option<Decimal> {
523 let xrate_result = ctx
524 .cache
525 .try_get_xrate(ctx.venue, quote_currency, base, PriceType::Mid);
526
527 let xrate = match xrate_result {
528 Ok(Some(rate)) => Some(rate),
529 Ok(None) => None,
530 Err(e) => {
531 self.log_calculation_failure(
532 date,
533 instrument_id,
534 RolloverFailureKind::Xrate,
535 &format!(
536 "Cannot calculate rollover for {instrument_id}: exchange rate from {quote_currency} to {base}: {e}"
537 ),
538 );
539 return None;
540 }
541 };
542
543 let Some(xrate) = xrate else {
544 self.log_calculation_failure(
545 date,
546 instrument_id,
547 RolloverFailureKind::Xrate,
548 &format!(
549 "Cannot calculate rollover for {instrument_id}: no exchange rate from {quote_currency} to {base}"
550 ),
551 );
552 return None;
553 };
554
555 Some(xrate)
556 }
557
558 fn prepare_rollover_day(&self, observed_date: Date) {
559 let initialize_date = {
560 let day = self.rollover_day.borrow();
561 match day.as_ref() {
562 None => Some(Self::weekday_on_or_before(observed_date)),
563 Some(day) if self.rollover_completed.get() && day.date < observed_date => {
564 Some(Self::next_weekday(day.date))
565 }
566 Some(_) => None,
567 }
568 };
569
570 if let Some(date) = initialize_date {
571 self.initialize_rollover_day(date);
572 }
573 }
574
575 fn stage_rollover_batch(
576 &self,
577 ts_now: UnixNanos,
578 observed_date: Date,
579 date: Date,
580 ctx: &ExchangeContext,
581 ) -> SimulationModuleResult {
582 let mut booking_date = date;
590 let mut batch = Vec::new();
591 let batch_end_date = loop {
592 if booking_date > observed_date
593 || (booking_date == observed_date
594 && ts_now.as_u64() < Self::rollover_time_ns(booking_date))
595 {
596 return SimulationModuleResult::NotReady;
597 }
598
599 let iso_weekday = booking_date.weekday().to_monday_one_offset();
600 match self.calculate_rollover_interest(booking_date, iso_weekday, ctx) {
601 RolloverCalculationOutcome::Completed(adjustments) => {
602 batch.extend(adjustments.into_iter().map(|amount| RolloverAdjustment {
603 booking_date,
604 amount,
605 }));
606 }
607 RolloverCalculationOutcome::Retry => {
608 return SimulationModuleResult::NotReady;
609 }
610 }
611
612 let next = Self::next_weekday(booking_date);
613 if next > observed_date
614 || (next == observed_date && ts_now.as_u64() < Self::rollover_time_ns(next))
615 {
616 break booking_date;
617 }
618 booking_date = next;
619 };
620
621 let adjustments = batch.iter().map(|adjustment| adjustment.amount).collect();
622 let mut day = self.rollover_day.borrow_mut();
623 let day = day.as_mut().expect("rollover day initialized");
624 day.pending_adjustments = Some(batch);
625 day.pending_end_date = Some(batch_end_date);
626 day.attempt_time = Some(ts_now);
627 SimulationModuleResult::Completed(adjustments)
628 }
629
630 fn record_adjustment_failure(
631 &self,
632 adjustment: &RolloverAdjustment,
633 error: &AccountAdjustmentError,
634 ) -> AccountAdjustmentFailureDisposition {
635 let kind = AccountAdjustmentFailureKind::from(error);
636 let first_failure = self
637 .rollover_day
638 .borrow_mut()
639 .as_mut()
640 .expect("rollover day initialized")
641 .warned_adjustment_failures
642 .insert((adjustment.booking_date, adjustment.amount.currency, kind));
643
644 match kind.disposition() {
645 AccountAdjustmentFailureDisposition::Retry => {
646 if first_failure {
647 log::warn!(
648 "Cannot apply rollover adjustment for {} on {}: {error}",
649 adjustment.amount.currency,
650 adjustment.booking_date
651 );
652 } else {
653 log::debug!(
654 "Cannot apply rollover adjustment for {} on {}: {error}",
655 adjustment.amount.currency,
656 adjustment.booking_date
657 );
658 }
659 }
660 AccountAdjustmentFailureDisposition::RecordUnapplied => {
661 if first_failure {
662 log::warn!(
663 "Rollover adjustment for {} on {} failed with {kind:?} and is recorded as unapplied: {error}",
664 adjustment.amount,
665 adjustment.booking_date
666 );
667 } else {
668 log::debug!(
669 "Rollover adjustment for {} on {} failed with {kind:?} and is recorded as unapplied: {error}",
670 adjustment.amount,
671 adjustment.booking_date
672 );
673 }
674 }
675 }
676
677 kind.disposition()
678 }
679
680 fn complete_rollover_batch(&self, attempt_time: UnixNanos, batch_end_date: Date) {
681 self.rollover_completed.set(true);
682 let mut day = self.rollover_day.borrow_mut();
683 let day = day.as_mut().expect("rollover day initialized");
684 day.date = batch_end_date;
685 day.pending_end_date = None;
686 day.warned_failures.clear();
687
688 let attempt_eastern = attempt_time
689 .to_datetime_utc()
690 .to_zoned(eastern_timezone().clone());
691
692 if attempt_eastern.date() != batch_end_date {
693 log::warn!(
694 "Rollover batch through {batch_end_date}, scheduled through {}, booked late at {attempt_time}",
695 UnixNanos::from(Self::rollover_time_ns(batch_end_date))
696 );
697 }
698 }
699}
700
701impl RolloverDayState {
702 fn take_adjustments(
703 &mut self,
704 outcome_count: usize,
705 ) -> anyhow::Result<(Vec<RolloverAdjustment>, UnixNanos, Date)> {
706 let adjustment_count = self
707 .pending_adjustments
708 .as_ref()
709 .ok_or_else(|| anyhow::anyhow!("no completed FX rollover batch to acknowledge"))?
710 .len();
711 anyhow::ensure!(
712 outcome_count == adjustment_count,
713 "FX rollover acknowledgement count {outcome_count}, expected {adjustment_count}"
714 );
715 let adjustments = self
716 .pending_adjustments
717 .take()
718 .ok_or_else(|| anyhow::anyhow!("no completed FX rollover batch to acknowledge"))?;
719 Ok((
720 adjustments,
721 self.attempt_time
722 .take()
723 .ok_or_else(|| anyhow::anyhow!("FX rollover attempt time was not recorded"))?,
724 self.pending_end_date
725 .ok_or_else(|| anyhow::anyhow!("FX rollover batch end date was not recorded"))?,
726 ))
727 }
728}
729
730fn add_rollover_total(
731 totals: &mut AHashMap<Currency, Decimal>,
732 amount: Money,
733) -> anyhow::Result<()> {
734 let total = totals.entry(amount.currency).or_insert(Decimal::ZERO);
735 *total = total
736 .checked_add(amount.as_decimal())
737 .ok_or_else(|| anyhow::anyhow!("rollover diagnostic total overflow"))?;
738 Ok(())
739}
740
741fn rollover_midpoint(bid: Option<Price>, ask: Option<Price>) -> anyhow::Result<Decimal> {
742 match (bid, ask) {
743 (Some(bid), Some(ask)) => price_decimal(bid).and_then(|bid| {
744 let ask = price_decimal(ask)?;
745 bid.checked_add(ask)
746 .and_then(|sum| sum.checked_div(Decimal::TWO))
747 .ok_or_else(|| anyhow::anyhow!("rollover midpoint overflow"))
748 }),
749 (Some(price), None) | (None, Some(price)) => price_decimal(price),
750 (None, None) => Err(anyhow::anyhow!("no market price")),
751 }
752}
753
754fn price_decimal(price: Price) -> anyhow::Result<Decimal> {
755 let value = price.as_decimal();
756 anyhow::ensure!(
757 Price::from_decimal_dp(value, price.precision)?.raw() == price.raw(),
758 "rollover price exceeds exact Decimal representation"
759 );
760 Ok(value)
761}
762
763impl SimulationModule for FXRolloverInterestModule {
764 fn pre_process(&self, _data: &Data) -> anyhow::Result<()> {
765 Ok(())
766 }
767
768 fn process(
769 &self,
770 ts_now: UnixNanos,
771 ctx: &ExchangeContext,
772 ) -> anyhow::Result<SimulationModuleResult> {
773 let eastern_dt = ts_now
774 .to_datetime_utc()
775 .to_zoned(eastern_timezone().clone());
776 let observed_date = eastern_dt.date();
777
778 self.prepare_rollover_day(observed_date);
779
780 if self.rollover_completed.get() {
781 return Ok(SimulationModuleResult::NotReady);
782 }
783
784 {
785 let mut day = self.rollover_day.borrow_mut();
786 let day = day.as_mut().expect("rollover day initialized");
787 if let Some(adjustments) = &day.pending_adjustments {
788 let adjustments = adjustments
789 .iter()
790 .map(|adjustment| adjustment.amount)
791 .collect();
792 day.attempt_time = Some(ts_now);
793 return Ok(SimulationModuleResult::Completed(adjustments));
794 }
795 }
796
797 let date = {
798 let day = self.rollover_day.borrow();
799 let day = day.as_ref().expect("rollover day initialized");
800 day.date
801 };
802
803 if ts_now.as_u64() < Self::rollover_time_ns(date) {
804 return Ok(SimulationModuleResult::NotReady);
805 }
806
807 Ok(self.stage_rollover_batch(ts_now, observed_date, date, ctx))
808 }
809
810 fn acknowledge(&self, outcomes: &[AccountAdjustmentOutcome]) -> anyhow::Result<()> {
811 let (adjustments, attempt_time, batch_end_date) = self
812 .rollover_day
813 .borrow_mut()
814 .as_mut()
815 .ok_or_else(|| anyhow::anyhow!("FX rollover day is not initialized"))?
816 .take_adjustments(outcomes.len())?;
817
818 let mut failed = Vec::new();
819 {
820 let mut totals = self.rollover_totals.borrow_mut();
821 let mut unapplied_totals = self.unapplied_rollover_totals.borrow_mut();
822
823 for (adjustment, outcome) in adjustments.into_iter().zip(outcomes) {
824 match outcome {
825 AccountAdjustmentOutcome::Applied => {
826 add_rollover_total(&mut totals, adjustment.amount)?;
827 }
828 AccountAdjustmentOutcome::Failed(error) => {
829 match self.record_adjustment_failure(&adjustment, error) {
830 AccountAdjustmentFailureDisposition::Retry => failed.push(adjustment),
831 AccountAdjustmentFailureDisposition::RecordUnapplied => {
832 add_rollover_total(&mut unapplied_totals, adjustment.amount)?;
833 }
834 }
835 }
836 }
837 }
838 }
839
840 if failed.is_empty() {
841 self.complete_rollover_batch(attempt_time, batch_end_date);
842 } else {
843 self.rollover_day
844 .borrow_mut()
845 .as_mut()
846 .ok_or_else(|| anyhow::anyhow!("FX rollover day is not initialized"))?
847 .pending_adjustments = Some(failed);
848 }
849 Ok(())
850 }
851
852 fn log_diagnostics(&self) -> anyhow::Result<()> {
853 let totals = self.rollover_totals.borrow();
854
855 let parts: Vec<String> = totals
856 .iter()
857 .map(|(currency, total)| {
858 Money::from_decimal_exact(*total, *currency).map(|money| money.to_string())
859 })
860 .collect::<Result<_, _>>()?;
861 log::info!("Rollover interest (totals): {}", parts.join(", "));
862
863 let unapplied_totals = self.unapplied_rollover_totals.borrow();
864
865 let unapplied_parts: Vec<String> = unapplied_totals
866 .iter()
867 .map(|(currency, total)| {
868 Money::from_decimal_exact(*total, *currency).map(|money| money.to_string())
869 })
870 .collect::<Result<_, _>>()?;
871 log::info!(
872 "Rollover interest (unapplied totals): {}",
873 unapplied_parts.join(", ")
874 );
875 Ok(())
876 }
877
878 fn reset(&self) -> anyhow::Result<()> {
879 self.rollover_completed.set(false);
880 self.rollover_day.replace(None);
881 self.rollover_totals.borrow_mut().clear();
882 self.unapplied_rollover_totals.borrow_mut().clear();
883 Ok(())
884 }
885}
886
887#[cfg(test)]
888mod tests {
889 use indexmap::IndexMap;
890 use jiff::tz::Offset;
891 use nautilus_common::cache::Cache;
892 use nautilus_model::identifiers::{InstrumentId, Venue};
893 use rstest::rstest;
894 use rust_decimal_macros::dec;
895 use serde_json::json;
896
897 use super::*;
898
899 fn sample_records() -> Vec<InterestRateRecord> {
900 vec![
901 InterestRateRecord {
902 location: "AUS".into(),
903 time: "2020-Q1".into(),
904 value: dec!(0.75),
905 },
906 InterestRateRecord {
907 location: "USA".into(),
908 time: "2020-Q1".into(),
909 value: dec!(1.50),
910 },
911 InterestRateRecord {
912 location: "JPN".into(),
913 time: "2020-Q1".into(),
914 value: dec!(-0.10),
915 },
916 InterestRateRecord {
917 location: "USA".into(),
918 time: "2020-01".into(),
919 value: dec!(1.55),
920 },
921 ]
922 }
923
924 fn rollover_adjustment(booking_date: Date, amount: &str) -> RolloverAdjustment {
925 RolloverAdjustment {
926 booking_date,
927 amount: Money::from(amount),
928 }
929 }
930
931 fn utc_nanos(date: Date, hour: i8, minute: i8) -> UnixNanos {
932 let timestamp = Offset::UTC
933 .to_timestamp(date.at(hour, minute, 0, 0))
934 .unwrap();
935 UnixNanos::from(u64::try_from(timestamp.as_nanosecond()).unwrap())
936 }
937
938 #[rstest]
939 fn test_interest_rate_record_serializes_to_json() {
940 let record = InterestRateRecord {
941 location: "AUS".into(),
942 time: "2020-Q1".into(),
943 value: dec!(0.75),
944 };
945
946 let value = serde_json::to_value(&record).unwrap();
947
948 assert_eq!(
949 value,
950 json!({
951 "location": "AUS",
952 "time": "2020-Q1",
953 "value": "0.75",
954 })
955 );
956 }
957
958 #[rstest]
959 fn test_calculator_quarterly_lookup() {
960 let calc = RolloverInterestCalculator::new(sample_records());
961 let date = Date::new(2020, 2, 15).unwrap();
962 let instrument_id = InstrumentId::from("AUDUSD.SIM");
963
964 let rate = calc.calc_overnight_rate(instrument_id, date).unwrap();
965
966 let expected = (dec!(0.75) - dec!(1.50)) / dec!(36500);
968 assert_eq!(rate, expected);
969 }
970
971 #[rstest]
972 fn test_calculator_monthly_preferred_over_quarterly() {
973 let calc = RolloverInterestCalculator::new(sample_records());
974 let date = Date::new(2020, 1, 15).unwrap();
975 let instrument_id = InstrumentId::from("USDJPY.SIM");
976
977 let rate = calc.calc_overnight_rate(instrument_id, date).unwrap();
978
979 let expected = (dec!(1.55) - (dec!(-0.10))) / dec!(36500);
981 assert_eq!(rate, expected);
982 }
983
984 #[rstest]
985 fn test_calculator_missing_currency() {
986 let calc = RolloverInterestCalculator::new(sample_records());
987 let date = Date::new(2020, 1, 15).unwrap();
988 let instrument_id = InstrumentId::from("EURGBP.SIM");
989
990 let result = calc.calc_overnight_rate(instrument_id, date);
991 assert!(result.is_err());
992 }
993
994 #[rstest]
995 fn test_module_reset() {
996 let module = FXRolloverInterestModule::new(sample_records());
997 module.initialize_rollover_day(Date::new(2020, 1, 15).unwrap());
998 module.rollover_completed.set(true);
999 module
1000 .rollover_totals
1001 .borrow_mut()
1002 .insert(Currency::USD(), dec!(100.0));
1003 module
1004 .unapplied_rollover_totals
1005 .borrow_mut()
1006 .insert(Currency::AUD(), dec!(20.0));
1007
1008 module.reset().unwrap();
1009
1010 assert!(module.rollover_day.borrow().is_none());
1011 assert!(!module.rollover_completed.get());
1012 assert!(module.rollover_totals.borrow().is_empty());
1013 assert!(module.unapplied_rollover_totals.borrow().is_empty());
1014 }
1015
1016 #[rstest]
1017 fn test_calculation_failure_dedupe_is_keyed_per_booking_date() {
1018 let module = FXRolloverInterestModule::new(sample_records());
1019 let date = Date::new(2020, 1, 15).unwrap();
1020 let next_date = Date::new(2020, 1, 16).unwrap();
1021 let instrument_id = InstrumentId::from("AUDUSD.SIM");
1022 module.initialize_rollover_day(date);
1023
1024 module.log_calculation_failure(date, instrument_id, RolloverFailureKind::Rate, "first");
1028 module.log_calculation_failure(date, instrument_id, RolloverFailureKind::Rate, "repeat");
1029 module.log_calculation_failure(next_date, instrument_id, RolloverFailureKind::Rate, "next");
1030
1031 assert_eq!(
1032 module
1033 .rollover_day
1034 .borrow()
1035 .as_ref()
1036 .unwrap()
1037 .warned_failures,
1038 AHashSet::from([
1039 (date, instrument_id, RolloverFailureKind::Rate),
1040 (next_date, instrument_id, RolloverFailureKind::Rate),
1041 ])
1042 );
1043 }
1044
1045 #[rstest]
1046 #[case("CAN", "CADUSD.SIM")]
1047 #[case("ZAF", "ZARUSD.SIM")]
1048 fn test_calculator_maps_oecd_location_code(#[case] location: &str, #[case] symbol: &str) {
1049 let records = vec![
1050 InterestRateRecord {
1051 location: location.to_string(),
1052 time: "2020-Q1".to_string(),
1053 value: dec!(2.0),
1054 },
1055 InterestRateRecord {
1056 location: "USA".to_string(),
1057 time: "2020-Q1".to_string(),
1058 value: dec!(1.5),
1059 },
1060 ];
1061 let calc = RolloverInterestCalculator::new(records);
1062 let date = Date::new(2020, 2, 15).unwrap();
1063
1064 let rate = calc
1065 .calc_overnight_rate(InstrumentId::from(symbol), date)
1066 .unwrap();
1067 let expected = (dec!(2.0) - dec!(1.5)) / dec!(36500);
1068
1069 assert_eq!(rate, expected);
1070 }
1071
1072 #[rstest]
1073 fn test_calculator_rejects_rate_difference_overflow() {
1074 let records = vec![
1075 InterestRateRecord {
1076 location: "AUS".to_string(),
1077 time: "2020-Q1".to_string(),
1078 value: Decimal::MAX,
1079 },
1080 InterestRateRecord {
1081 location: "USA".to_string(),
1082 time: "2020-Q1".to_string(),
1083 value: Decimal::MIN,
1084 },
1085 ];
1086 let calculator = RolloverInterestCalculator::new(records);
1087 let error = calculator
1088 .calc_overnight_rate(
1089 InstrumentId::from("AUDUSD.SIM"),
1090 Date::new(2020, 1, 15).unwrap(),
1091 )
1092 .unwrap_err();
1093 assert_eq!(
1094 error.to_string(),
1095 "overnight interest rate calculation overflow"
1096 );
1097 }
1098
1099 #[rstest]
1100 fn test_transient_adjustment_failure_retries_only_failed_adjustments() {
1101 let module = FXRolloverInterestModule::new(sample_records());
1102 let date = Date::new(2020, 1, 15).unwrap();
1103 let attempt_time = utc_nanos(date, 22, 1);
1104 module.initialize_rollover_day(date);
1105 {
1106 let mut day = module.rollover_day.borrow_mut();
1107 let day = day.as_mut().unwrap();
1108 day.pending_adjustments = Some(vec![
1109 rollover_adjustment(date, "10.00 USD"),
1110 rollover_adjustment(date, "20.00 AUD"),
1111 ]);
1112 day.pending_end_date = Some(date);
1113 day.attempt_time = Some(attempt_time);
1114 }
1115
1116 module
1117 .acknowledge(&[
1118 AccountAdjustmentOutcome::Applied,
1119 AccountAdjustmentOutcome::Failed(AccountAdjustmentError::TotalOverflow(
1120 Currency::AUD(),
1121 )),
1122 ])
1123 .unwrap();
1124
1125 assert!(!module.rollover_completed.get());
1126 assert_eq!(
1127 module
1128 .rollover_day
1129 .borrow()
1130 .as_ref()
1131 .unwrap()
1132 .pending_adjustments,
1133 Some(vec![rollover_adjustment(date, "20.00 AUD")])
1134 );
1135 assert_eq!(
1136 module.rollover_totals.borrow().get(&Currency::USD()),
1137 Some(&dec!(10.0))
1138 );
1139 assert!(
1140 !module
1141 .rollover_totals
1142 .borrow()
1143 .contains_key(&Currency::AUD())
1144 );
1145 assert_eq!(
1146 module
1147 .rollover_day
1148 .borrow()
1149 .as_ref()
1150 .unwrap()
1151 .warned_adjustment_failures
1152 .len(),
1153 1
1154 );
1155
1156 let instruments = AHashMap::new();
1157 let matching_engines = IndexMap::new();
1158 let cache = Cache::default();
1159 let ctx = ExchangeContext {
1160 venue: Venue::new("SIM"),
1161 base_currency: None,
1162 instruments: &instruments,
1163 matching_engines: &matching_engines,
1164 cache: &cache,
1165 };
1166 assert_eq!(
1167 module.process(attempt_time, &ctx).unwrap(),
1168 SimulationModuleResult::Completed(vec![Money::from("20.00 AUD")])
1169 );
1170 module
1171 .acknowledge(&[AccountAdjustmentOutcome::Failed(
1172 AccountAdjustmentError::TotalOverflow(Currency::AUD()),
1173 )])
1174 .unwrap();
1175 assert_eq!(
1176 module
1177 .rollover_day
1178 .borrow()
1179 .as_ref()
1180 .unwrap()
1181 .warned_adjustment_failures
1182 .len(),
1183 1
1184 );
1185 assert_eq!(
1186 module.process(attempt_time, &ctx).unwrap(),
1187 SimulationModuleResult::Completed(vec![Money::from("20.00 AUD")])
1188 );
1189 module
1190 .acknowledge(&[AccountAdjustmentOutcome::Applied])
1191 .unwrap();
1192
1193 assert!(module.rollover_completed.get());
1194 assert_eq!(
1195 module.rollover_totals.borrow().get(&Currency::USD()),
1196 Some(&dec!(10.0))
1197 );
1198 assert_eq!(
1199 module.rollover_totals.borrow().get(&Currency::AUD()),
1200 Some(&dec!(20.0))
1201 );
1202 assert_eq!(
1203 module
1204 .rollover_day
1205 .borrow()
1206 .as_ref()
1207 .unwrap()
1208 .warned_adjustment_failures
1209 .len(),
1210 1
1211 );
1212 }
1213
1214 #[rstest]
1215 fn test_permanent_adjustment_failure_completes_batch() {
1216 let module = FXRolloverInterestModule::new(sample_records());
1217 let date = Date::new(2020, 1, 15).unwrap();
1218 let attempt_time = utc_nanos(date, 22, 1);
1219 module.initialize_rollover_day(date);
1220 let second_date = date.tomorrow().unwrap();
1221 {
1222 let mut day = module.rollover_day.borrow_mut();
1223 let day = day.as_mut().unwrap();
1224 day.pending_adjustments = Some(vec![
1225 rollover_adjustment(date, "20.00 AUD"),
1226 rollover_adjustment(second_date, "30.00 AUD"),
1227 ]);
1228 day.pending_end_date = Some(second_date);
1229 day.attempt_time = Some(attempt_time);
1230 }
1231
1232 module
1233 .acknowledge(&[
1234 AccountAdjustmentOutcome::Failed(AccountAdjustmentError::MissingBalance(
1235 Currency::AUD(),
1236 )),
1237 AccountAdjustmentOutcome::Failed(AccountAdjustmentError::MissingBalance(
1238 Currency::AUD(),
1239 )),
1240 ])
1241 .unwrap();
1242
1243 assert!(module.rollover_completed.get());
1244 assert!(
1245 module
1246 .rollover_day
1247 .borrow()
1248 .as_ref()
1249 .unwrap()
1250 .pending_adjustments
1251 .is_none()
1252 );
1253 assert_eq!(
1254 module
1255 .unapplied_rollover_totals
1256 .borrow()
1257 .get(&Currency::AUD()),
1258 Some(&dec!(50.0))
1259 );
1260 assert!(
1261 !module
1262 .rollover_totals
1263 .borrow()
1264 .contains_key(&Currency::AUD())
1265 );
1266 assert_eq!(
1267 module
1268 .rollover_day
1269 .borrow()
1270 .as_ref()
1271 .unwrap()
1272 .warned_adjustment_failures,
1273 AHashSet::from([
1274 (
1275 date,
1276 Currency::AUD(),
1277 AccountAdjustmentFailureKind::MissingBalance,
1278 ),
1279 (
1280 second_date,
1281 Currency::AUD(),
1282 AccountAdjustmentFailureKind::MissingBalance,
1283 ),
1284 ])
1285 );
1286 let instruments = AHashMap::new();
1287 let matching_engines = IndexMap::new();
1288 let cache = Cache::default();
1289 let ctx = ExchangeContext {
1290 venue: Venue::new("SIM"),
1291 base_currency: None,
1292 instruments: &instruments,
1293 matching_engines: &matching_engines,
1294 cache: &cache,
1295 };
1296 let next_attempt = utc_nanos(second_date.tomorrow().unwrap(), 22, 1);
1297 assert_eq!(
1298 module.process(next_attempt, &ctx).unwrap(),
1299 SimulationModuleResult::Completed(Vec::new())
1300 );
1301 }
1302
1303 #[rstest]
1304 fn test_acknowledgement_count_error_preserves_pending_batch() {
1305 let module = FXRolloverInterestModule::new(sample_records());
1306 let date = Date::new(2020, 1, 15).unwrap();
1307 module.initialize_rollover_day(date);
1308 {
1309 let mut day = module.rollover_day.borrow_mut();
1310 let day = day.as_mut().unwrap();
1311 day.pending_adjustments = Some(vec![rollover_adjustment(date, "10.00 USD")]);
1312 day.pending_end_date = Some(date);
1313 day.attempt_time = Some(UnixNanos::from(1));
1314 }
1315
1316 let error = module.acknowledge(&[]).unwrap_err();
1317
1318 assert_eq!(
1319 error.to_string(),
1320 "FX rollover acknowledgement count 0, expected 1"
1321 );
1322 assert_eq!(
1323 module
1324 .rollover_day
1325 .borrow()
1326 .as_ref()
1327 .unwrap()
1328 .pending_adjustments,
1329 Some(vec![rollover_adjustment(date, "10.00 USD")])
1330 );
1331 module
1332 .acknowledge(&[AccountAdjustmentOutcome::Applied])
1333 .unwrap();
1334 assert!(module.rollover_completed.get());
1335 assert_eq!(
1336 *module.rollover_totals.borrow(),
1337 AHashMap::from([(Currency::USD(), dec!(10.00))]),
1338 );
1339 assert_eq!(module.rollover_day.borrow().as_ref().unwrap().date, date);
1340 }
1341}