Skip to main content

nautilus_backtest/modules/
fx_rollover.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//! FX rollover interest simulation module.
17
18use 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/// A single interest rate data entry.
70#[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    /// OECD location code using ISO 3166 alpha-3 (e.g., "AUS", "USA") or "EA19".
81    /// Records with unsupported codes are ignored.
82    pub location: String,
83    /// Time period key (e.g., "2024-01" for monthly, "2024-Q1" for quarterly).
84    pub time: String,
85    /// Interest rate value as a percentage (e.g., 5.25 means 5.25%).
86    pub value: Decimal,
87}
88
89/// Calculates overnight rollover interest rates for FX currency pairs.
90///
91/// Uses short-term interest rate data (OECD format) to compute the daily
92/// differential between base and quote currency rates.
93#[derive(Debug, Clone)]
94pub struct RolloverInterestCalculator {
95    // currency code -> {time_key -> rate_percentage}
96    rates: AHashMap<String, AHashMap<String, Decimal>>,
97}
98
99impl RolloverInterestCalculator {
100    /// Creates a new calculator from interest rate records.
101    ///
102    /// Records with unsupported location codes are ignored. "CHN" supplies both CNY and CNH;
103    /// later records replace earlier records for the same currency and time.
104    #[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            // CHN maps to both CNY and CNH
113            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(&currency) = 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    /// Calculates the overnight interest rate differential for a currency pair.
132    ///
133    /// Returns `(base_rate - quote_rate) / 365 / 100` as a daily decimal rate.
134    ///
135    /// # Errors
136    ///
137    /// Returns an error if the symbol is malformed, rate data is missing, or arithmetic overflows.
138    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        // Try monthly key first
167        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        // Fall back to quarterly key
173        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/// Simulates FX rollover (swap) interest applied at 5 PM US/Eastern daily.
184///
185/// When holding FX positions overnight, the interest rate differential
186/// between the two currencies is credited or debited. Wednesday and Friday
187/// rollovers are tripled (Wednesday for T+2 settlement, Friday for the weekend).
188#[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    /// Creates a new FX rollover interest module.
296    ///
297    /// Records with unsupported location codes are ignored.
298    #[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    /// Logs a calculation failure at warn level once per (booking date, instrument,
348    /// kind), demoting repeats to debug: a `Retry` outcome re-runs the calculation
349    /// on every process call until it completes, and repeating the identical
350    /// warning per attempt would flood the log. The booking date is part of the key
351    /// because one catch-up batch spans many dates, and a permanent per-instrument
352    /// skip must stay visible for each date it drops rather than warning only for
353    /// the first. The set is cleared on a new day, on completion, and on reset.
354    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        // Look up the immutable rate data before any transient market
424        // inputs: a permanently missing rate must skip the instrument
425        // even when the engine or price would first retry the day.
426        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        // Drain every due weekday so sparse data cannot leave the booking cursor behind.
583        // This is complete by booked-day count, but uses the current positions, prices, and
584        // exchange rates for every date because historical cutoff snapshots are unavailable.
585        // Work is proportional to the gap length times the instrument count. This is a weekday
586        // calendar rather than a pair-specific business-day calendar. The existing Wednesday
587        // and Friday triple multipliers are retained for parity, even though standard spot FX
588        // usually applies the weekend triple on Wednesday only.
589        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        // (0.75 - 1.50) / 365 / 100 = -0.00002054...
967        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        // Monthly USD rate (1.55) preferred over quarterly (1.50)
980        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        // A catch-up batch calculates many booking dates before the state is
1025        // replaced, so a permanent per-instrument skip must stay visible for
1026        // every date it drops rather than warning only for the first.
1027        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}