Skip to main content

nautilus_kraken/websocket/dispatch/
futures.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//! WebSocket execution dispatch for the Kraken Futures API.
17//!
18//! Routes `OpenOrdersDelta`, `OpenOrdersCancel`, and `FillsDelta` messages to
19//! typed order events (for tracked orders) or status / fill reports (for
20//! external orders) under the two-tier dispatch contract.
21
22use std::sync::Arc;
23
24use ahash::AHashMap;
25use nautilus_core::{AtomicMap, UUID4, UnixNanos};
26use nautilus_live::ExecutionEventEmitter;
27use nautilus_model::{
28    enums::{OrderStatus, OrderType, TimeInForce},
29    events::{OrderCanceled, OrderEventAny, OrderUpdated},
30    identifiers::{AccountId, ClientOrderId, InstrumentId, VenueOrderId},
31    instruments::{Instrument, InstrumentAny},
32    reports::OrderStatusReport,
33    types::{Price, Quantity},
34};
35use ustr::Ustr;
36
37use super::{
38    DeltaSnapshot, OrderIdentity, PendingRemoval, WsDispatchState, ensure_accepted_emitted,
39    fill_report_to_order_filled, resolve_client_order_id,
40};
41use crate::{
42    common::{lookup_instrument_in_snapshot, parse::parse_venue_order_id},
43    websocket::futures::{
44        messages::{
45            KrakenFuturesFill, KrakenFuturesFillsDelta, KrakenFuturesOpenOrdersCancel,
46            KrakenFuturesOpenOrdersDelta,
47        },
48        parse::{parse_futures_ws_fill_report, parse_futures_ws_order_status_report},
49    },
50};
51
52/// Dispatches a Kraken Futures `OpenOrdersDelta` message.
53///
54/// Fill-driven cancel deltas (`is_cancel=true` with reason `full_fill`) are
55/// skipped - the corresponding `FillsDelta` carries the real fill, so emitting
56/// a synthetic Canceled here would race with the genuine `OrderFilled`.
57/// Tracked cancellations close the order only once the fills feed has accounted
58/// the removal's cumulative filled, so a fill still in flight is never orphaned.
59#[expect(clippy::too_many_arguments)]
60pub fn open_orders_delta(
61    delta: &KrakenFuturesOpenOrdersDelta,
62    state: &WsDispatchState,
63    emitter: &ExecutionEventEmitter,
64    instruments: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
65    truncated_id_map: &Arc<AtomicMap<String, ClientOrderId>>,
66    order_instrument_map: &Arc<AtomicMap<String, InstrumentId>>,
67    venue_client_map: &Arc<AtomicMap<String, ClientOrderId>>,
68    venue_order_qty: &Arc<AtomicMap<String, Quantity>>,
69    account_id: AccountId,
70    ts_init: UnixNanos,
71) {
72    if delta.is_fill_driven_cancel() && !delta.is_partial_fill_removal() {
73        log::debug!(
74            "Skipping fill-driven open_orders delta: order_id={}, reason={:?}",
75            delta.order.order_id,
76            delta.reason,
77        );
78        return;
79    }
80
81    let product_id = delta.order.instrument.as_str();
82    let instruments = instruments.load();
83    let Some(instrument) = lookup_instrument_in_snapshot(&instruments, product_id) else {
84        log::warn!("No instrument for product_id: {product_id}");
85        return;
86    };
87
88    let Ok(venue_order_id) = parse_venue_order_id(
89        &delta.order.order_id,
90        format_args!(
91            "futures order delta, cli_ord_id={:?}, is_cancel={}",
92            delta.order.cli_ord_id, delta.is_cancel
93        ),
94    )
95    .inspect_err(|e| log::error!("{e}")) else {
96        return;
97    };
98
99    // Cache instrument and qty by venue order id so cancel-only messages
100    // (which arrive without the order body) can be reconstructed for the
101    // external fallback path.
102    order_instrument_map.insert(delta.order.order_id.clone(), instrument.id());
103    let Ok(qty) = Quantity::from_decimal_dp(delta.order.qty, instrument.size_precision()) else {
104        log::error!("Failed to parse order quantity: {}", delta.order.qty);
105        return;
106    };
107    venue_order_qty.insert(delta.order.order_id.clone(), qty);
108
109    let resolved_id = delta
110        .order
111        .cli_ord_id
112        .as_ref()
113        .map(|id| resolve_client_order_id(id, truncated_id_map));
114
115    // Stale-report suppression: an order that already reached the filled
116    // terminal state should not produce more events even if a late delta
117    // arrives. `filled_orders` persists past `cleanup_terminal` precisely
118    // for this check.
119    if let Some(cid) = resolved_id
120        && state.filled_orders.contains(&cid)
121    {
122        log::debug!(
123            "Skipping stale open_orders delta for filled order: cid={cid}, order_id={}",
124            delta.order.order_id,
125        );
126        return;
127    }
128
129    if let Some(client_order_id) = resolved_id {
130        venue_client_map.insert(delta.order.order_id.clone(), client_order_id);
131        if let Some(identity) = state.lookup_identity(&client_order_id) {
132            if delta.is_cancel {
133                cancel_tracked(
134                    delta,
135                    client_order_id,
136                    venue_order_id,
137                    &identity,
138                    instrument,
139                    state,
140                    emitter,
141                    account_id,
142                    ts_init,
143                );
144                return;
145            }
146
147            delta_tracked(
148                delta,
149                client_order_id,
150                venue_order_id,
151                &identity,
152                instrument,
153                state,
154                emitter,
155                account_id,
156                ts_init,
157            );
158
159            return;
160        }
161    }
162
163    if delta.is_partial_fill_removal() {
164        log::debug!(
165            "Skipping untracked partial-fill removal: order_id={}",
166            delta.order.order_id,
167        );
168        return;
169    }
170
171    // External / untracked: fall back to a status report.
172    match parse_futures_ws_order_status_report(
173        &delta.order,
174        delta.is_cancel,
175        delta.reason.as_deref(),
176        instrument,
177        account_id,
178        ts_init,
179    ) {
180        Ok(mut report) => {
181            if let Some(cid) = resolved_id {
182                report = report.with_client_order_id(cid);
183            }
184            emitter.send_order_status_report(report);
185        }
186        Err(e) => log::error!("Failed to parse futures order status report: {e}"),
187    }
188}
189
190#[expect(clippy::too_many_arguments)]
191fn delta_tracked(
192    delta: &KrakenFuturesOpenOrdersDelta,
193    client_order_id: ClientOrderId,
194    venue_order_id: VenueOrderId,
195    identity: &OrderIdentity,
196    instrument: &InstrumentAny,
197    state: &WsDispatchState,
198    emitter: &ExecutionEventEmitter,
199    account_id: AccountId,
200    ts_init: UnixNanos,
201) {
202    let ts_event = millis_to_nanos(delta.order.last_update_time);
203    let Ok(new_filled) = Quantity::from_decimal_dp(delta.order.filled, instrument.size_precision())
204    else {
205        log::error!("Failed to parse filled quantity: {}", delta.order.filled);
206        return;
207    };
208
209    let already_accepted = state.emitted_accepted.contains(&client_order_id);
210    ensure_accepted_emitted(
211        client_order_id,
212        venue_order_id,
213        account_id,
214        identity,
215        state,
216        emitter,
217        ts_event,
218        ts_init,
219    );
220
221    let Ok(qty) = Quantity::from_decimal_dp(delta.order.qty, instrument.size_precision()) else {
222        log::error!("Failed to parse order quantity: {}", delta.order.qty);
223        return;
224    };
225    let snapshot = DeltaSnapshot::new(
226        qty,
227        new_filled,
228        delta.order.limit_price,
229        delta.order.stop_price,
230    );
231
232    if !already_accepted {
233        // First delta seen for this order: the placement Accepted is enough.
234        state.record_delta_snapshot(client_order_id, snapshot);
235        return;
236    }
237
238    // Follow-up delta. The two emission-relevant signals are independent:
239    //   * filled increased       -> partial-fill notification (FillsDelta has it,
240    //                               nothing to emit from here)
241    //   * non-fill field changed -> modify acknowledgement (emit OrderUpdated)
242    // Both can be true simultaneously when a user amends a partially filled
243    // order, so check the modify branch regardless of fill movement.
244    let previous = state.previous_delta_snapshot(&client_order_id);
245    state.record_delta_snapshot(client_order_id, snapshot);
246
247    let non_fill_changed = previous.is_some_and(|prev| !snapshot.non_fill_fields_match(&prev));
248    if !non_fill_changed {
249        return;
250    }
251
252    // Modify ack: refresh tracked quantity (size may have changed) and emit
253    // OrderUpdated so the engine clears PendingUpdate.
254    state.update_identity_quantity(&client_order_id, qty);
255    let price = match delta
256        .order
257        .limit_price
258        .map(|p| Price::from_decimal_dp(p, instrument.price_precision()))
259        .transpose()
260    {
261        Ok(price) => price,
262        Err(e) => {
263            log::error!("Failed to parse limit price: {e}");
264            return;
265        }
266    };
267    let trigger_price = match delta
268        .order
269        .stop_price
270        .map(|p| Price::from_decimal_dp(p, instrument.price_precision()))
271        .transpose()
272    {
273        Ok(price) => price,
274        Err(e) => {
275            log::error!("Failed to parse stop price: {e}");
276            return;
277        }
278    };
279
280    let updated = OrderUpdated::new(
281        emitter.trader_id(),
282        identity.strategy_id,
283        identity.instrument_id,
284        client_order_id,
285        qty,
286        UUID4::new(),
287        ts_event,
288        ts_init,
289        false,
290        Some(venue_order_id),
291        Some(account_id),
292        price,
293        trigger_price,
294        None,
295        false,
296    );
297    emitter.send_order_event(OrderEventAny::Updated(updated));
298}
299
300#[expect(clippy::too_many_arguments)]
301fn cancel_tracked(
302    delta: &KrakenFuturesOpenOrdersDelta,
303    client_order_id: ClientOrderId,
304    venue_order_id: VenueOrderId,
305    identity: &OrderIdentity,
306    instrument: &InstrumentAny,
307    state: &WsDispatchState,
308    emitter: &ExecutionEventEmitter,
309    account_id: AccountId,
310    ts_init: UnixNanos,
311) {
312    let ts_event = millis_to_nanos(delta.order.last_update_time);
313
314    let Ok(venue_filled) =
315        Quantity::from_decimal_dp(delta.order.filled, instrument.size_precision())
316    else {
317        log::error!("Failed to parse filled quantity: {}", delta.order.filled);
318        return;
319    };
320
321    let recorded_filled = state
322        .previous_filled_qty(&client_order_id)
323        .unwrap_or_else(|| Quantity::zero(instrument.size_precision()));
324
325    if recorded_filled < venue_filled {
326        log::debug!(
327            "Deferring cancellation for {client_order_id}: filled={recorded_filled}, \
328             venue_filled={venue_filled}",
329        );
330        state.insert_pending_removal(
331            client_order_id,
332            PendingRemoval {
333                venue_filled,
334                reason: delta.reason.clone(),
335                ts_event,
336            },
337        );
338
339        return;
340    }
341
342    ensure_accepted_emitted(
343        client_order_id,
344        venue_order_id,
345        account_id,
346        identity,
347        state,
348        emitter,
349        ts_event,
350        ts_init,
351    );
352
353    let canceled = OrderCanceled::new(
354        emitter.trader_id(),
355        identity.strategy_id,
356        identity.instrument_id,
357        client_order_id,
358        UUID4::new(),
359        ts_event,
360        ts_init,
361        false,
362        Some(venue_order_id),
363        Some(account_id),
364        delta.reason.as_deref().map(Ustr::from),
365    );
366    emitter.send_order_event(OrderEventAny::Canceled(canceled));
367    state.cleanup_terminal(&client_order_id);
368}
369
370/// Dispatches a Kraken Futures `OpenOrdersCancel` (cancel-only) message.
371#[expect(clippy::too_many_arguments)]
372pub fn open_orders_cancel(
373    cancel: &KrakenFuturesOpenOrdersCancel,
374    state: &WsDispatchState,
375    emitter: &ExecutionEventEmitter,
376    truncated_id_map: &Arc<AtomicMap<String, ClientOrderId>>,
377    order_instrument_map: &Arc<AtomicMap<String, InstrumentId>>,
378    venue_client_map: &Arc<AtomicMap<String, ClientOrderId>>,
379    venue_order_qty: &Arc<AtomicMap<String, Quantity>>,
380    account_id: AccountId,
381    ts_init: UnixNanos,
382) {
383    // Skip fill-driven removals (the FillsDelta carries the real fill).
384    if let Some(ref reason) = cancel.reason
385        && (reason == "full_fill" || reason == "partial_fill")
386    {
387        log::debug!(
388            "Skipping fill-driven cancel: order_id={}, reason={reason}",
389            cancel.order_id,
390        );
391        return;
392    }
393
394    let Ok(venue_order_id) = parse_venue_order_id(
395        &cancel.order_id,
396        format_args!(
397            "futures open orders cancel, cli_ord_id={:?}",
398            cancel.cli_ord_id
399        ),
400    )
401    .inspect_err(|e| log::error!("{e}")) else {
402        return;
403    };
404    let resolved_id = cancel
405        .cli_ord_id
406        .as_ref()
407        .map(|id| resolve_client_order_id(id, truncated_id_map))
408        .or_else(|| venue_client_map.load().get(&cancel.order_id).copied());
409
410    if let Some(client_order_id) = resolved_id
411        && let Some(identity) = state.lookup_identity(&client_order_id)
412    {
413        let ts_event = ts_init;
414        ensure_accepted_emitted(
415            client_order_id,
416            venue_order_id,
417            account_id,
418            &identity,
419            state,
420            emitter,
421            ts_event,
422            ts_init,
423        );
424        let canceled = OrderCanceled::new(
425            emitter.trader_id(),
426            identity.strategy_id,
427            identity.instrument_id,
428            client_order_id,
429            UUID4::new(),
430            ts_event,
431            ts_init,
432            false,
433            Some(venue_order_id),
434            Some(account_id),
435            cancel.reason.as_deref().map(Ustr::from),
436        );
437        emitter.send_order_event(OrderEventAny::Canceled(canceled));
438        state.cleanup_terminal(&client_order_id);
439        return;
440    }
441
442    // External fallback: build a status report from the side caches.
443    let Some(instrument_id) = order_instrument_map.load().get(&cancel.order_id).copied() else {
444        log::warn!(
445            "Cannot resolve instrument for cancel: order_id={}, \
446             order not seen in previous delta",
447            cancel.order_id
448        );
449        return;
450    };
451
452    let Some(quantity) = venue_order_qty.load().get(&cancel.order_id).copied() else {
453        log::warn!(
454            "Cannot resolve quantity for cancel: order_id={}, skipping",
455            cancel.order_id
456        );
457        return;
458    };
459
460    let report = OrderStatusReport::new(
461        account_id,
462        instrument_id,
463        resolved_id,
464        venue_order_id,
465        None,
466        OrderType::Limit,
467        TimeInForce::Gtc,
468        OrderStatus::Canceled,
469        quantity,
470        Quantity::zero(0),
471        ts_init,
472        ts_init,
473        ts_init,
474        None,
475    );
476    let report = if let Some(ref reason) = cancel.reason
477        && !reason.is_empty()
478    {
479        report.with_cancel_reason(reason.clone())
480    } else {
481        report
482    };
483    emitter.send_order_status_report(report);
484}
485
486/// Dispatches a Kraken Futures `FillsDelta` message.
487#[expect(clippy::too_many_arguments)]
488pub fn fills_delta(
489    fills_delta: &KrakenFuturesFillsDelta,
490    state: &WsDispatchState,
491    emitter: &ExecutionEventEmitter,
492    instruments: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
493    truncated_id_map: &Arc<AtomicMap<String, ClientOrderId>>,
494    venue_client_map: &Arc<AtomicMap<String, ClientOrderId>>,
495    account_id: AccountId,
496    ts_init: UnixNanos,
497) {
498    let instruments = instruments.load();
499    let venue_clients = venue_client_map.load();
500
501    for fill in &fills_delta.fills {
502        single_fill(
503            fill,
504            state,
505            emitter,
506            &instruments,
507            truncated_id_map,
508            &venue_clients,
509            account_id,
510            ts_init,
511        );
512    }
513}
514
515#[expect(clippy::too_many_arguments)]
516fn single_fill(
517    fill: &KrakenFuturesFill,
518    state: &WsDispatchState,
519    emitter: &ExecutionEventEmitter,
520    instruments: &AHashMap<InstrumentId, InstrumentAny>,
521    truncated_id_map: &Arc<AtomicMap<String, ClientOrderId>>,
522    venue_client_map: &AHashMap<String, ClientOrderId>,
523    account_id: AccountId,
524    ts_init: UnixNanos,
525) {
526    let product_id = match &fill.instrument {
527        Some(id) => id.as_str(),
528        None => {
529            log::warn!("Fill missing instrument field: fill_id={}", fill.fill_id);
530            return;
531        }
532    };
533
534    let Some(instrument) = lookup_instrument_in_snapshot(instruments, product_id) else {
535        log::warn!("No instrument for product_id: {product_id}");
536        return;
537    };
538
539    let mut report = match parse_futures_ws_fill_report(fill, instrument, account_id, ts_init) {
540        Ok(report) => report,
541        Err(e) => {
542            log::error!("Failed to parse futures fill report: {e}");
543            return;
544        }
545    };
546
547    let resolved_id = fill
548        .cli_ord_id
549        .as_deref()
550        .filter(|s| !s.is_empty())
551        .map(|id| resolve_client_order_id(id, truncated_id_map))
552        .or_else(|| venue_client_map.get(&fill.order_id).copied());
553
554    if let Some(cid) = resolved_id
555        && state.filled_orders.contains(&cid)
556    {
557        log::debug!(
558            "Skipping stale fill for filled order: cid={cid}, order_id={}",
559            fill.order_id,
560        );
561        return;
562    }
563
564    if let Some(client_order_id) = resolved_id {
565        report.client_order_id = Some(client_order_id);
566
567        if let Some(identity) = state.lookup_identity(&client_order_id) {
568            if state.check_and_insert_trade(report.trade_id) {
569                log::debug!(
570                    "Skipping duplicate fill for {client_order_id}: trade_id={}",
571                    report.trade_id
572                );
573                return;
574            }
575            ensure_accepted_emitted(
576                client_order_id,
577                report.venue_order_id,
578                account_id,
579                &identity,
580                state,
581                emitter,
582                report.ts_event,
583                ts_init,
584            );
585            let filled = fill_report_to_order_filled(
586                &report,
587                emitter.trader_id(),
588                &identity,
589                instrument.quote_currency(),
590                client_order_id,
591            );
592            emitter.send_order_event(OrderEventAny::Filled(filled));
593
594            // Update cumulative filled and cleanup on terminal fill.
595            let previous = state
596                .previous_filled_qty(&client_order_id)
597                .unwrap_or_else(|| Quantity::zero(instrument.size_precision()));
598            let cumulative = previous + report.last_qty;
599            state.record_filled_qty(client_order_id, cumulative);
600
601            if cumulative >= identity.quantity {
602                state.insert_filled(client_order_id);
603                state.cleanup_terminal(&client_order_id);
604                return;
605            }
606
607            if let Some(pending) = state.pending_removal(&client_order_id)
608                && cumulative >= pending.venue_filled
609            {
610                state.remove_pending_removal(&client_order_id);
611
612                let canceled = OrderCanceled::new(
613                    emitter.trader_id(),
614                    identity.strategy_id,
615                    identity.instrument_id,
616                    client_order_id,
617                    UUID4::new(),
618                    pending.ts_event,
619                    ts_init,
620                    false,
621                    Some(report.venue_order_id),
622                    Some(account_id),
623                    pending.reason.as_deref().map(Ustr::from),
624                );
625                emitter.send_order_event(OrderEventAny::Canceled(canceled));
626                state.cleanup_terminal(&client_order_id);
627            }
628            return;
629        }
630    }
631
632    // External fallback.
633    if state.check_and_insert_trade(report.trade_id) {
634        log::debug!(
635            "Skipping duplicate external fill: trade_id={}",
636            report.trade_id
637        );
638        return;
639    }
640    emitter.send_fill_report(report);
641}
642
643#[inline]
644fn millis_to_nanos(millis: i64) -> UnixNanos {
645    UnixNanos::from((millis as u64) * 1_000_000)
646}