Skip to main content

nautilus_data/defi/
engine.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//! DeFi-specific data engine functionality.
17//!
18//! This module provides DeFi processing methods for the `DataEngine`.
19//! All code in this module requires the `defi` feature flag.
20
21use std::{rc::Rc, sync::Arc};
22
23use nautilus_common::{
24    defi,
25    messages::defi::{
26        DefiRequestCommand, DefiSubscribeCommand, DefiUnsubscribeCommand, PoolSnapshotResponse,
27        RequestPoolSnapshot,
28    },
29    msgbus::{self, TypedHandler},
30};
31use nautilus_core::UUID4;
32use nautilus_model::{
33    defi::{
34        Blockchain, DefiData, Pool, PoolProfiler,
35        data::{DexPoolData, block::BlockPosition},
36        pool_analysis::PoolSnapshot,
37    },
38    identifiers::{ClientId, InstrumentId},
39    instruments::{CurrencyPair, InstrumentAny},
40};
41
42use crate::engine::{
43    DataEngine,
44    pool::{
45        PoolCollectHandler, PoolFlashHandler, PoolLiquidityHandler, PoolSwapHandler, PoolUpdater,
46    },
47};
48
49/// Extracts the block position tuple from a `DexPoolData` event.
50fn get_event_block_position(event: &DexPoolData) -> (u64, u32, u32) {
51    match event {
52        DexPoolData::Swap(s) => (s.block, s.transaction_index, s.log_index),
53        DexPoolData::LiquidityUpdate(u) => (u.block, u.transaction_index, u.log_index),
54        DexPoolData::FeeCollect(c) => (c.block, c.transaction_index, c.log_index),
55        DexPoolData::FeeProtocolUpdate(u) => (u.block, u.transaction_index, u.log_index),
56        DexPoolData::FeeProtocolCollect(c) => (c.block, c.transaction_index, c.log_index),
57        DexPoolData::Flash(f) => (f.block, f.transaction_index, f.log_index),
58    }
59}
60
61/// Converts buffered `DefiData` events to `DexPoolData` and sorts by block position.
62fn convert_and_sort_buffered_events(buffered_events: Vec<DefiData>) -> Vec<DexPoolData> {
63    let mut events: Vec<DexPoolData> = buffered_events
64        .into_iter()
65        .filter_map(|event| match event {
66            DefiData::PoolSwap(swap) => Some(DexPoolData::Swap(swap)),
67            DefiData::PoolLiquidityUpdate(update) => Some(DexPoolData::LiquidityUpdate(update)),
68            DefiData::PoolFeeCollect(collect) => Some(DexPoolData::FeeCollect(collect)),
69            DefiData::PoolFeeProtocolUpdate(update) => Some(DexPoolData::FeeProtocolUpdate(update)),
70            DefiData::PoolFeeProtocolCollect(collect) => {
71                Some(DexPoolData::FeeProtocolCollect(collect))
72            }
73            DefiData::PoolFlash(flash) => Some(DexPoolData::Flash(flash)),
74            _ => None,
75        })
76        .collect();
77
78    events.sort_by(|a, b| {
79        let pos_a = get_event_block_position(a);
80        let pos_b = get_event_block_position(b);
81        pos_a.cmp(&pos_b)
82    });
83
84    events
85}
86
87impl DataEngine {
88    /// Returns all blockchains for which blocks subscriptions exist.
89    #[must_use]
90    pub fn subscribed_blocks(&self) -> Vec<Blockchain> {
91        self.collect_subscriptions(|client| &client.subscriptions_blocks)
92    }
93
94    /// Returns all instrument IDs for which pool subscriptions exist.
95    #[must_use]
96    pub fn subscribed_pools(&self) -> Vec<InstrumentId> {
97        self.collect_subscriptions(|client| &client.subscriptions_pools)
98    }
99
100    /// Returns all instrument IDs for which swap subscriptions exist.
101    #[must_use]
102    pub fn subscribed_pool_swaps(&self) -> Vec<InstrumentId> {
103        self.collect_subscriptions(|client| &client.subscriptions_pool_swaps)
104    }
105
106    /// Returns all instrument IDs for which liquidity update subscriptions exist.
107    #[must_use]
108    pub fn subscribed_pool_liquidity_updates(&self) -> Vec<InstrumentId> {
109        self.collect_subscriptions(|client| &client.subscriptions_pool_liquidity_updates)
110    }
111
112    /// Returns all instrument IDs for which fee collect subscriptions exist.
113    #[must_use]
114    pub fn subscribed_pool_fee_collects(&self) -> Vec<InstrumentId> {
115        self.collect_subscriptions(|client| &client.subscriptions_pool_fee_collects)
116    }
117
118    /// Returns all instrument IDs for which flash loan subscriptions exist.
119    #[must_use]
120    pub fn subscribed_pool_flash(&self) -> Vec<InstrumentId> {
121        self.collect_subscriptions(|client| &client.subscriptions_pool_flash)
122    }
123
124    /// Handles a subscribe command, updating internal state and forwarding to the client.
125    ///
126    /// # Errors
127    ///
128    /// Returns an error if the subscription is invalid (e.g., synthetic instrument for book data),
129    /// or if the underlying client operation fails.
130    pub fn execute_defi_subscribe(&mut self, cmd: DefiSubscribeCommand) -> anyhow::Result<()> {
131        if let Some(client_id) = cmd.client_id()
132            && self.is_external_client(*client_id)
133        {
134            if self.config().debug {
135                log::debug!("Skipping defi subscribe for external client {client_id}: {cmd:?}");
136            }
137            return Ok(());
138        }
139
140        let Some(client) = self.get_client(cmd.client_id(), cmd.venue()) else {
141            log::error!(
142                "Cannot handle command: no client found for client_id={:?}, venue={:?}",
143                cmd.client_id(),
144                cmd.venue(),
145            );
146            return Ok(());
147        };
148
149        #[rustfmt::skip]
150        let pool = match &cmd {
151            DefiSubscribeCommand::Pool(cmd) => Some((cmd.instrument_id, cmd.client_id)),
152            DefiSubscribeCommand::PoolSwaps(cmd) => Some((cmd.instrument_id, cmd.client_id)),
153            DefiSubscribeCommand::PoolLiquidityUpdates(cmd) => Some((cmd.instrument_id, cmd.client_id)),
154            DefiSubscribeCommand::PoolFeeCollects(cmd) => Some((cmd.instrument_id, cmd.client_id)),
155            DefiSubscribeCommand::PoolFlashEvents(cmd) => Some((cmd.instrument_id, cmd.client_id)),
156            DefiSubscribeCommand::Blocks(_) => None, // No pool setup needed for blocks
157        };
158
159        log::info!("Forwarding subscription to client {}", client.client_id);
160        client.execute_defi_subscribe_with_retained(cmd, true);
161
162        if let Some((instrument_id, client_id)) = pool {
163            self.setup_pool_updater(&instrument_id, client_id.as_ref());
164        }
165
166        Ok(())
167    }
168
169    /// Handles an unsubscribe command, updating internal state and forwarding to the client.
170    ///
171    /// # Errors
172    ///
173    /// Returns an error if the underlying client operation fails.
174    pub fn execute_defi_unsubscribe(&mut self, cmd: &DefiUnsubscribeCommand) -> anyhow::Result<()> {
175        if let Some(client_id) = cmd.client_id()
176            && self.is_external_client(*client_id)
177        {
178            if self.config().debug {
179                log::debug!("Skipping defi unsubscribe for external client {client_id}: {cmd:?}");
180            }
181            return Ok(());
182        }
183
184        let Some(client) = self.get_client(cmd.client_id(), cmd.venue()) else {
185            log::error!(
186                "Cannot handle command: no client found for client_id={:?}, venue={:?}",
187                cmd.client_id(),
188                cmd.venue(),
189            );
190            return Ok(());
191        };
192
193        client.execute_defi_unsubscribe(cmd);
194
195        #[rustfmt::skip]
196        let instrument_id = match cmd {
197            DefiUnsubscribeCommand::Pool(cmd) => cmd.instrument_id,
198            DefiUnsubscribeCommand::PoolSwaps(cmd) => cmd.instrument_id,
199            DefiUnsubscribeCommand::PoolLiquidityUpdates(cmd) => cmd.instrument_id,
200            DefiUnsubscribeCommand::PoolFeeCollects(cmd) => cmd.instrument_id,
201            DefiUnsubscribeCommand::PoolFlashEvents(cmd) => cmd.instrument_id,
202            DefiUnsubscribeCommand::Blocks(_) => return Ok(()),
203        };
204
205        // The updater serves every pool subscription shape on every client
206        if !self
207            .get_clients()
208            .iter()
209            .any(|client| client.has_defi_pool_demand(&instrument_id))
210        {
211            self.release_pool_updater(&instrument_id);
212        }
213
214        Ok(())
215    }
216
217    /// Sends a [`DefiRequestCommand`] to a suitable data client implementation.
218    ///
219    /// # Errors
220    ///
221    /// Returns an error if no client is found for the given client ID or venue,
222    /// or if the client fails to process the request.
223    pub fn execute_defi_request(&mut self, req: DefiRequestCommand) -> anyhow::Result<()> {
224        // Skip requests for external clients
225        if let Some(cid) = req.client_id()
226            && self.is_external_client(*cid)
227        {
228            if self.config().debug {
229                log::debug!("Skipping defi data request for external client {cid}: {req:?}");
230            }
231            return Ok(());
232        }
233
234        if let Some(client) = self.get_client(req.client_id(), req.venue()) {
235            let client_id = client.client_id();
236            client
237                .execute_defi_request(req)
238                .map_err(|e| e.context(format!("Data client {client_id} request failed")))
239        } else {
240            anyhow::bail!(
241                "Cannot handle request: no client found for {:?} {:?}",
242                req.client_id(),
243                req.venue()
244            );
245        }
246    }
247
248    /// Processes DeFi-specific data events.
249    pub fn process_defi_data(&mut self, data: DefiData) {
250        self.increment_data_count();
251
252        match data {
253            DefiData::Block(block) => {
254                let topic = defi::switchboard::get_defi_blocks_topic(block.chain());
255                msgbus::publish_defi_block(topic, &block);
256            }
257            DefiData::Pool(pool) => self.handle_pool(&pool),
258            DefiData::PoolSnapshot(snapshot) => {
259                // Replayed snapshots carry no request identity, so any pending bootstrap accepts them
260                if !self
261                    .pool_snapshot_pending
262                    .contains_key(&snapshot.instrument_id)
263                {
264                    log::warn!(
265                        "Received unexpected pool snapshot for {} (not in pending set)",
266                        snapshot.instrument_id
267                    );
268                    return;
269                }
270
271                self.hydrate_pool_profiler(&snapshot);
272            }
273            DefiData::PoolSwap(swap) => {
274                let instrument_id = swap.instrument_id;
275                self.buffer_pool_event(instrument_id, "swap event", || {
276                    DefiData::PoolSwap(swap.clone())
277                });
278
279                let topic = defi::switchboard::get_defi_pool_swaps_topic(instrument_id);
280                msgbus::publish_defi_swap(topic, &swap);
281            }
282            DefiData::PoolLiquidityUpdate(update) => {
283                let instrument_id = update.instrument_id;
284                self.buffer_pool_event(instrument_id, "liquidity update event", || {
285                    DefiData::PoolLiquidityUpdate(update.clone())
286                });
287
288                let topic = defi::switchboard::get_defi_liquidity_topic(instrument_id);
289                msgbus::publish_defi_liquidity(topic, &update);
290            }
291            DefiData::PoolFeeCollect(collect) => {
292                let instrument_id = collect.instrument_id;
293                self.buffer_pool_event(instrument_id, "fee collect event", || {
294                    DefiData::PoolFeeCollect(collect.clone())
295                });
296
297                let topic = defi::switchboard::get_defi_collect_topic(instrument_id);
298                msgbus::publish_defi_collect(topic, &collect);
299            }
300            DefiData::PoolFeeProtocolUpdate(update) => {
301                let instrument_id = update.instrument_id;
302                // A protocol-fee change is profiler infrastructure, not a subscriber data stream:
303                // it only needs to keep the profiler's `fee_protocol` consistent for swap and flash
304                // fee splitting. Buffer until the snapshot lands, otherwise apply in place.
305                if self.pool_snapshot_pending.contains_key(&instrument_id) {
306                    log::debug!(
307                        "Buffering fee protocol update for {instrument_id} (waiting for snapshot)"
308                    );
309                    self.pool_event_buffers
310                        .entry(instrument_id)
311                        .or_default()
312                        .push(DefiData::PoolFeeProtocolUpdate(update));
313                } else if let Some(profiler) =
314                    self.cache().borrow_mut().pool_profiler_mut(&instrument_id)
315                    && let Err(e) = profiler.process_fee_protocol_update(&update)
316                {
317                    log::error!("Failed to process pool fee protocol update: {e}");
318                }
319            }
320            DefiData::PoolFeeProtocolCollect(collect) => {
321                let instrument_id = collect.instrument_id;
322                // A protocol-fee withdrawal is profiler infrastructure, not a subscriber data
323                // stream: it only decrements the profiler's accrued protocol-fee balances. Buffer
324                // until the snapshot lands, otherwise apply in place.
325                if self.pool_snapshot_pending.contains_key(&instrument_id) {
326                    log::debug!(
327                        "Buffering fee protocol collect event for {instrument_id} (waiting for snapshot)"
328                    );
329                    self.pool_event_buffers
330                        .entry(instrument_id)
331                        .or_default()
332                        .push(DefiData::PoolFeeProtocolCollect(collect));
333                } else if let Some(profiler) =
334                    self.cache().borrow_mut().pool_profiler_mut(&instrument_id)
335                    && let Err(e) = profiler.process_fee_protocol_collect(&collect)
336                {
337                    log::error!("Failed to process pool fee protocol collect event: {e}");
338                }
339            }
340            DefiData::PoolFlash(flash) => {
341                let instrument_id = flash.instrument_id;
342                self.buffer_pool_event(instrument_id, "flash event", || {
343                    DefiData::PoolFlash(flash.clone())
344                });
345
346                let topic = defi::switchboard::get_defi_flash_topic(instrument_id);
347                msgbus::publish_defi_flash(topic, &flash);
348            }
349        }
350    }
351
352    fn buffer_pool_event(
353        &mut self,
354        instrument_id: InstrumentId,
355        event_name: &str,
356        event: impl FnOnce() -> DefiData,
357    ) {
358        // Subscribers receive events immediately; only hydration needs the buffered copy
359        if self.pool_snapshot_pending.contains_key(&instrument_id) {
360            log::debug!("Buffering {event_name} for {instrument_id} (waiting for snapshot)");
361            self.pool_event_buffers
362                .entry(instrument_id)
363                .or_default()
364                .push(event());
365        }
366    }
367
368    fn handle_pool(&mut self, pool: &Pool) {
369        let instrument = match CurrencyPair::try_from(pool) {
370            Ok(instrument) => InstrumentAny::CurrencyPair(instrument),
371            Err(e) => {
372                log::error!(
373                    "Failed to create instrument for Pool {}: {e}",
374                    pool.instrument_id
375                );
376                return;
377            }
378        };
379
380        if !self.cache_instrument(&instrument) {
381            return;
382        }
383
384        if let Err(e) = self.cache().borrow_mut().add_pool(pool.clone()) {
385            log::error!("Failed to add Pool to cache: {e}");
386            return;
387        }
388
389        self.publish_instrument(&instrument);
390
391        let topic = defi::switchboard::get_defi_pool_topic(pool.instrument_id);
392        msgbus::publish_defi_pool(topic, pool);
393    }
394
395    pub(crate) fn handle_pool_snapshot_response(&mut self, response: &PoolSnapshotResponse) {
396        let instrument_id = response.data.instrument_id;
397
398        if self.pool_snapshot_pending.get(&instrument_id) != Some(&response.correlation_id) {
399            log::warn!(
400                "Discarding pool snapshot for {instrument_id} from stale request {}",
401                response.correlation_id
402            );
403            return;
404        }
405
406        self.hydrate_pool_profiler(&response.data);
407    }
408
409    fn hydrate_pool_profiler(&mut self, snapshot: &PoolSnapshot) {
410        let instrument_id = snapshot.instrument_id;
411        log::info!(
412            "Received pool snapshot for {instrument_id} at block {} with {} positions and {} ticks",
413            snapshot.block_position.number,
414            snapshot.positions.len(),
415            snapshot.ticks.len()
416        );
417
418        // Get pool from cache
419        let pool = self
420            .cache()
421            .borrow()
422            .pool(&instrument_id)
423            .map(|pool| Arc::new(pool.clone()));
424
425        let Some(pool) = pool else {
426            log::error!("Pool {instrument_id} not found in cache when processing snapshot");
427            self.abandon_pool_snapshot(&instrument_id);
428            return;
429        };
430
431        // Defensive: refuse stub snapshots that slipped past the bootstrap-side
432        // guards. Installing one would leave Python actors observing an initialized
433        // profiler with zero liquidity; better to leave the pool without a profiler
434        // so the bad state is visible.
435        if snapshot.positions.is_empty()
436            && snapshot.ticks.is_empty()
437            && snapshot.block_position.number == pool.creation_block
438        {
439            log::warn!(
440                "Refusing empty stub snapshot for {instrument_id} at pool creation block {}; pool will remain without profiler",
441                snapshot.block_position.number,
442            );
443            self.abandon_pool_snapshot(&instrument_id);
444            return;
445        }
446
447        // Create profiler and restore from snapshot
448        let mut profiler = PoolProfiler::new(pool);
449        if let Err(e) = profiler.restore_from_snapshot(snapshot.clone()) {
450            log::error!("Failed to restore profiler from snapshot for {instrument_id}: {e}");
451            self.abandon_pool_snapshot(&instrument_id);
452            return;
453        }
454
455        log::debug!("Restored pool profiler for {instrument_id} from snapshot");
456
457        // Process buffered events
458        let buffered_events = self
459            .pool_event_buffers
460            .remove(&instrument_id)
461            .unwrap_or_default();
462
463        if !buffered_events.is_empty() {
464            log::info!(
465                "Processing {} buffered events for {instrument_id}",
466                buffered_events.len()
467            );
468
469            let events_to_apply = convert_and_sort_buffered_events(buffered_events);
470            let applied_count = Self::apply_buffered_events_to_profiler(
471                &mut profiler,
472                events_to_apply,
473                &snapshot.block_position,
474                instrument_id,
475            );
476
477            log::info!("Applied {applied_count} buffered events to profiler for {instrument_id}");
478        }
479
480        // Add profiler to cache
481        let result = self.cache().borrow_mut().add_pool_profiler(profiler);
482        if let Err(e) = result {
483            log::error!("Failed to add pool profiler to cache for {instrument_id}: {e}");
484            self.abandon_pool_snapshot(&instrument_id);
485            return;
486        }
487
488        // Create updater and subscribe to topics
489        self.pool_snapshot_pending.remove(&instrument_id);
490        let updater = Rc::new(PoolUpdater::new(&instrument_id, Rc::clone(self.cache())));
491
492        self.subscribe_pool_updater_topics(instrument_id, Rc::clone(&updater));
493        self.pool_updaters.insert(instrument_id, updater);
494
495        log::info!("Pool profiler setup completed for {instrument_id}, now processing live events");
496    }
497
498    fn abandon_pool_snapshot(&mut self, instrument_id: &InstrumentId) {
499        self.pool_snapshot_pending.remove(instrument_id);
500        self.pool_event_buffers.remove(instrument_id);
501    }
502
503    /// Subscribes a pool updater to all relevant pool data topics using typed handlers.
504    fn subscribe_pool_updater_topics(&self, instrument_id: InstrumentId, updater: Rc<PoolUpdater>) {
505        let priority = Some(self.msgbus_priority());
506
507        // Subscribe swap handler
508        let swap_topic = defi::switchboard::get_defi_pool_swaps_topic(instrument_id);
509        let swap_handler = TypedHandler(Rc::new(PoolSwapHandler::new(Rc::clone(&updater))));
510        msgbus::subscribe_defi_swaps(swap_topic.into(), swap_handler, priority);
511
512        // Subscribe liquidity handler
513        let liq_topic = defi::switchboard::get_defi_liquidity_topic(instrument_id);
514        let liq_handler = TypedHandler(Rc::new(PoolLiquidityHandler::new(Rc::clone(&updater))));
515        msgbus::subscribe_defi_liquidity(liq_topic.into(), liq_handler, priority);
516
517        // Subscribe collect handler
518        let collect_topic = defi::switchboard::get_defi_collect_topic(instrument_id);
519        let collect_handler = TypedHandler(Rc::new(PoolCollectHandler::new(Rc::clone(&updater))));
520        msgbus::subscribe_defi_collects(collect_topic.into(), collect_handler, priority);
521
522        // Subscribe flash handler
523        let flash_topic = defi::switchboard::get_defi_flash_topic(instrument_id);
524        let flash_handler = TypedHandler(Rc::new(PoolFlashHandler::new(updater)));
525        msgbus::subscribe_defi_flash(flash_topic.into(), flash_handler, priority);
526    }
527
528    /// Applies buffered events to a pool profiler, filtering to events after the snapshot.
529    ///
530    /// Returns the count of successfully applied events.
531    fn apply_buffered_events_to_profiler(
532        profiler: &mut PoolProfiler,
533        events: Vec<DexPoolData>,
534        snapshot_block: &BlockPosition,
535        instrument_id: InstrumentId,
536    ) -> usize {
537        let mut applied_count = 0;
538
539        for event in events {
540            let event_block = get_event_block_position(&event);
541
542            // Only apply events that occurred after the snapshot
543            let is_after_snapshot = event_block.0 > snapshot_block.number
544                || (event_block.0 == snapshot_block.number
545                    && event_block.1 > snapshot_block.transaction_index)
546                || (event_block.0 == snapshot_block.number
547                    && event_block.1 == snapshot_block.transaction_index
548                    && event_block.2 > snapshot_block.log_index);
549
550            if is_after_snapshot {
551                if let Err(e) = profiler.process(&event) {
552                    log::error!(
553                        "Failed to apply buffered event to profiler for {instrument_id}: {e}"
554                    );
555                } else {
556                    applied_count += 1;
557                }
558            }
559        }
560
561        applied_count
562    }
563
564    fn setup_pool_updater(&mut self, instrument_id: &InstrumentId, client_id: Option<&ClientId>) {
565        // Early return if updater already exists or we are in the middle of setting it up.
566        if self.pool_updaters.contains_key(instrument_id)
567            || self.pool_snapshot_pending.contains_key(instrument_id)
568        {
569            log::debug!("Pool updater for {instrument_id} already exists");
570            return;
571        }
572
573        log::info!("Setting up pool updater for {instrument_id}");
574
575        // Check cache state and ensure profiler exists
576        {
577            let mut cache = self.cache().borrow_mut();
578
579            if cache.pool_profiler(instrument_id).is_some() {
580                // Profiler already exists, proceed to create updater
581                log::debug!("Pool profiler already exists for {instrument_id}");
582            } else if let Some(pool) = cache.pool(instrument_id) {
583                // Pool exists but no profiler, create profiler from pool
584                let pool = Arc::new(pool.clone());
585                let mut pool_profiler = PoolProfiler::new(Arc::clone(&pool));
586
587                if let Some(initial_sqrt_price_x96) = pool.initial_sqrt_price_x96 {
588                    if let Err(e) = pool_profiler.initialize(initial_sqrt_price_x96) {
589                        log::error!("Failed to initialize pool profiler for {instrument_id}: {e}");
590                        drop(cache);
591                        return;
592                    }
593                    log::debug!(
594                        "Initialized pool profiler for {instrument_id} with sqrt_price {initial_sqrt_price_x96}"
595                    );
596                } else {
597                    log::debug!("Created pool profiler for {instrument_id}");
598                }
599
600                if let Err(e) = cache.add_pool_profiler(pool_profiler) {
601                    log::error!("Failed to add pool profiler for {instrument_id}: {e}");
602                    drop(cache);
603                    return;
604                }
605                drop(cache);
606            } else {
607                // Neither profiler nor pool exists, request snapshot
608                drop(cache);
609
610                self.request_pool_snapshot(instrument_id, client_id);
611                return;
612            }
613        }
614
615        // Profiler exists, create updater and subscribe to topics
616        let updater = Rc::new(PoolUpdater::new(instrument_id, Rc::clone(self.cache())));
617
618        self.subscribe_pool_updater_topics(*instrument_id, Rc::clone(&updater));
619        self.pool_updaters.insert(*instrument_id, updater);
620
621        log::debug!("Created PoolUpdater for instrument ID {instrument_id}");
622    }
623
624    fn request_pool_snapshot(
625        &mut self,
626        instrument_id: &InstrumentId,
627        client_id: Option<&ClientId>,
628    ) {
629        let request_id = UUID4::new();
630        let ts_init = self.clock().borrow().timestamp_ns();
631
632        let request = RequestPoolSnapshot::new(
633            *instrument_id,
634            client_id.copied(),
635            request_id,
636            ts_init,
637            None,
638        );
639
640        if let Err(e) = self.execute_defi_request(DefiRequestCommand::PoolSnapshot(request)) {
641            log::warn!("Failed to request pool snapshot for {instrument_id}: {e}");
642        } else {
643            log::debug!("Requested pool snapshot for {instrument_id}");
644            self.pool_snapshot_pending
645                .insert(*instrument_id, request_id);
646            self.pool_event_buffers.entry(*instrument_id).or_default();
647        }
648    }
649
650    fn release_pool_updater(&mut self, instrument_id: &InstrumentId) {
651        if let Some(updater) = self.pool_updaters.remove(instrument_id) {
652            Self::unsubscribe_pool_updater_topics(*instrument_id, updater);
653            log::debug!("Removed PoolUpdater for instrument ID {instrument_id}");
654        }
655
656        self.abandon_pool_snapshot(instrument_id);
657    }
658
659    pub(crate) fn clear_pool_updaters(&mut self) {
660        let updaters: Vec<_> = self.pool_updaters.drain().collect();
661        for (instrument_id, updater) in updaters {
662            Self::unsubscribe_pool_updater_topics(instrument_id, updater);
663        }
664
665        self.abandon_pool_snapshots();
666    }
667
668    pub(crate) fn abandon_pool_snapshots(&mut self) {
669        self.pool_snapshot_pending.clear();
670        self.pool_event_buffers.clear();
671    }
672
673    fn unsubscribe_pool_updater_topics(instrument_id: InstrumentId, updater: Rc<PoolUpdater>) {
674        let swap_topic = defi::switchboard::get_defi_pool_swaps_topic(instrument_id);
675        let swap_handler = TypedHandler(Rc::new(PoolSwapHandler::new(Rc::clone(&updater))));
676        msgbus::unsubscribe_defi_swaps(swap_topic.into(), &swap_handler);
677
678        let liq_topic = defi::switchboard::get_defi_liquidity_topic(instrument_id);
679        let liq_handler = TypedHandler(Rc::new(PoolLiquidityHandler::new(Rc::clone(&updater))));
680        msgbus::unsubscribe_defi_liquidity(liq_topic.into(), &liq_handler);
681
682        let collect_topic = defi::switchboard::get_defi_collect_topic(instrument_id);
683        let collect_handler = TypedHandler(Rc::new(PoolCollectHandler::new(Rc::clone(&updater))));
684        msgbus::unsubscribe_defi_collects(collect_topic.into(), &collect_handler);
685
686        let flash_topic = defi::switchboard::get_defi_flash_topic(instrument_id);
687        let flash_handler = TypedHandler(Rc::new(PoolFlashHandler::new(updater)));
688        msgbus::unsubscribe_defi_flash(flash_topic.into(), &flash_handler);
689    }
690}
691
692#[cfg(test)]
693mod tests {
694    use std::{cell::RefCell, sync::Arc};
695
696    use alloy_primitives::{Address, I256, U160, U256};
697    use nautilus_common::{cache::Cache, clock::VirtualClock};
698    use nautilus_core::UnixNanos;
699    use nautilus_model::{
700        defi::{
701            Chain, DefiData, PoolFeeCollect, PoolFeeProtocolUpdate, PoolFlash, PoolIdentifier,
702            PoolLiquidityUpdate, PoolLiquidityUpdateType, PoolSwap,
703            chain::chains,
704            data::DexPoolData,
705            dex::{AmmType, Dex, DexType},
706        },
707        identifiers::{InstrumentId, Symbol, Venue},
708    };
709    use rstest::*;
710
711    use super::*;
712
713    #[fixture]
714    fn test_instrument_id() -> InstrumentId {
715        InstrumentId::new(Symbol::from("ETH/USDC"), Venue::from("UNISWAPV3"))
716    }
717
718    #[fixture]
719    fn test_chain() -> Arc<Chain> {
720        Arc::new(chains::ETHEREUM.clone())
721    }
722
723    #[fixture]
724    fn test_dex(test_chain: Arc<Chain>) -> Arc<Dex> {
725        Arc::new(Dex::new(
726            (*test_chain).clone(),
727            DexType::UniswapV3,
728            "0x1F98431c8aD98523631AE4a59f267346ea31F984",
729            12369621,
730            AmmType::CLAMM,
731            "PoolCreated(address,address,uint24,int24,address)",
732            "Swap(address,address,int256,int256,uint160,uint128,int24)",
733            "Mint(address,address,int24,int24,uint128,uint256,uint256)",
734            "Burn(address,int24,int24,uint128,uint256,uint256)",
735            "Collect(address,address,int24,int24,uint128,uint128)",
736        ))
737    }
738
739    fn create_test_swap(
740        test_instrument_id: InstrumentId,
741        test_chain: Arc<Chain>,
742        test_dex: Arc<Dex>,
743        block: u64,
744        tx_index: u32,
745        log_index: u32,
746    ) -> PoolSwap {
747        PoolSwap::new(
748            test_chain,
749            test_dex,
750            test_instrument_id,
751            PoolIdentifier::from_address(Address::ZERO),
752            block,
753            format!("0x{block:064x}"),
754            tx_index,
755            log_index,
756            UnixNanos::default(),
757            UnixNanos::default(),
758            Address::ZERO,
759            Address::ZERO,
760            I256::ZERO,
761            I256::ZERO,
762            U160::ZERO,
763            0,
764            0,
765        )
766    }
767
768    fn create_test_liquidity_update(
769        test_instrument_id: InstrumentId,
770        test_chain: Arc<Chain>,
771        test_dex: Arc<Dex>,
772        block: u64,
773        tx_index: u32,
774        log_index: u32,
775    ) -> PoolLiquidityUpdate {
776        PoolLiquidityUpdate::new(
777            test_chain,
778            test_dex,
779            test_instrument_id,
780            PoolIdentifier::from_address(Address::ZERO),
781            PoolLiquidityUpdateType::Mint,
782            block,
783            format!("0x{block:064x}"),
784            tx_index,
785            log_index,
786            None,
787            Address::ZERO,
788            0,
789            U256::ZERO,
790            U256::ZERO,
791            0,
792            0,
793            UnixNanos::default(),
794            UnixNanos::default(),
795        )
796    }
797
798    fn create_test_fee_collect(
799        test_instrument_id: InstrumentId,
800        test_chain: Arc<Chain>,
801        test_dex: Arc<Dex>,
802        block: u64,
803        tx_index: u32,
804        log_index: u32,
805    ) -> PoolFeeCollect {
806        PoolFeeCollect::new(
807            test_chain,
808            test_dex,
809            test_instrument_id,
810            PoolIdentifier::from_address(Address::ZERO),
811            block,
812            format!("0x{block:064x}"),
813            tx_index,
814            log_index,
815            Address::ZERO,
816            0,
817            0,
818            0,
819            0,
820            UnixNanos::default(),
821            UnixNanos::default(),
822        )
823    }
824
825    fn create_test_flash(
826        test_instrument_id: InstrumentId,
827        test_chain: Arc<Chain>,
828        test_dex: Arc<Dex>,
829        block: u64,
830        tx_index: u32,
831        log_index: u32,
832    ) -> PoolFlash {
833        PoolFlash::new(
834            test_chain,
835            test_dex,
836            test_instrument_id,
837            PoolIdentifier::from_address(Address::ZERO),
838            block,
839            format!("0x{block:064x}"),
840            tx_index,
841            log_index,
842            UnixNanos::default(),
843            UnixNanos::default(),
844            Address::ZERO,
845            Address::ZERO,
846            U256::ZERO,
847            U256::ZERO,
848            U256::ZERO,
849            U256::ZERO,
850        )
851    }
852
853    fn create_test_fee_protocol_update(
854        test_instrument_id: InstrumentId,
855        test_chain: Arc<Chain>,
856        test_dex: Arc<Dex>,
857        block: u64,
858        tx_index: u32,
859        log_index: u32,
860    ) -> PoolFeeProtocolUpdate {
861        PoolFeeProtocolUpdate::new(
862            test_chain,
863            test_dex,
864            test_instrument_id,
865            PoolIdentifier::from_address(Address::ZERO),
866            block,
867            format!("0x{block:064x}"),
868            tx_index,
869            log_index,
870            4,
871            4,
872            UnixNanos::default(),
873            UnixNanos::default(),
874        )
875    }
876
877    #[rstest]
878    #[case::snapshot_pending(true)]
879    #[case::no_snapshot_pending(false)]
880    fn test_pool_subscriber_events_buffer_only_for_pending_snapshot(
881        test_instrument_id: InstrumentId,
882        test_chain: Arc<Chain>,
883        test_dex: Arc<Dex>,
884        #[case] pending: bool,
885    ) {
886        let clock = Rc::new(RefCell::new(VirtualClock::new()));
887        let cache = Rc::new(RefCell::new(Cache::default()));
888        let mut engine = DataEngine::new(clock, cache, None);
889        if pending {
890            engine
891                .pool_snapshot_pending
892                .insert(test_instrument_id, UUID4::new());
893        }
894
895        let events = vec![
896            DefiData::PoolSwap(create_test_swap(
897                test_instrument_id,
898                Arc::clone(&test_chain),
899                Arc::clone(&test_dex),
900                104,
901                3,
902                2,
903            )),
904            DefiData::PoolLiquidityUpdate(create_test_liquidity_update(
905                test_instrument_id,
906                Arc::clone(&test_chain),
907                Arc::clone(&test_dex),
908                102,
909                1,
910                4,
911            )),
912            DefiData::PoolFeeCollect(create_test_fee_collect(
913                test_instrument_id,
914                Arc::clone(&test_chain),
915                Arc::clone(&test_dex),
916                103,
917                2,
918                1,
919            )),
920            DefiData::PoolFlash(create_test_flash(
921                test_instrument_id,
922                test_chain,
923                test_dex,
924                101,
925                4,
926                3,
927            )),
928        ];
929
930        for event in &events {
931            engine.process_defi_data(event.clone());
932        }
933
934        assert_eq!(
935            engine.pool_event_buffers.remove(&test_instrument_id),
936            pending.then_some(events),
937        );
938    }
939
940    #[rstest]
941    fn test_get_event_block_position_swap(
942        test_instrument_id: InstrumentId,
943        test_chain: Arc<Chain>,
944        test_dex: Arc<Dex>,
945    ) {
946        let swap = create_test_swap(test_instrument_id, test_chain, test_dex, 100, 5, 3);
947        let pos = get_event_block_position(&DexPoolData::Swap(swap));
948        assert_eq!(pos, (100, 5, 3));
949    }
950
951    #[rstest]
952    fn test_get_event_block_position_liquidity_update(
953        test_instrument_id: InstrumentId,
954        test_chain: Arc<Chain>,
955        test_dex: Arc<Dex>,
956    ) {
957        let update =
958            create_test_liquidity_update(test_instrument_id, test_chain, test_dex, 200, 10, 7);
959        let pos = get_event_block_position(&DexPoolData::LiquidityUpdate(update));
960        assert_eq!(pos, (200, 10, 7));
961    }
962
963    #[rstest]
964    fn test_get_event_block_position_fee_collect(
965        test_instrument_id: InstrumentId,
966        test_chain: Arc<Chain>,
967        test_dex: Arc<Dex>,
968    ) {
969        let collect = create_test_fee_collect(test_instrument_id, test_chain, test_dex, 300, 15, 2);
970        let pos = get_event_block_position(&DexPoolData::FeeCollect(collect));
971        assert_eq!(pos, (300, 15, 2));
972    }
973
974    #[rstest]
975    fn test_get_event_block_position_flash(
976        test_instrument_id: InstrumentId,
977        test_chain: Arc<Chain>,
978        test_dex: Arc<Dex>,
979    ) {
980        let flash = create_test_flash(test_instrument_id, test_chain, test_dex, 400, 20, 8);
981        let pos = get_event_block_position(&DexPoolData::Flash(flash));
982        assert_eq!(pos, (400, 20, 8));
983    }
984
985    #[rstest]
986    fn test_get_event_block_position_fee_protocol_update(
987        test_instrument_id: InstrumentId,
988        test_chain: Arc<Chain>,
989        test_dex: Arc<Dex>,
990    ) {
991        let update =
992            create_test_fee_protocol_update(test_instrument_id, test_chain, test_dex, 500, 25, 4);
993        let pos = get_event_block_position(&DexPoolData::FeeProtocolUpdate(update));
994        assert_eq!(pos, (500, 25, 4));
995    }
996
997    #[rstest]
998    fn test_convert_and_sort_empty_events() {
999        let events = convert_and_sort_buffered_events(vec![]);
1000        assert!(events.is_empty());
1001    }
1002
1003    #[rstest]
1004    fn test_convert_and_sort_filters_non_pool_events(
1005        test_instrument_id: InstrumentId,
1006        test_chain: Arc<Chain>,
1007        test_dex: Arc<Dex>,
1008    ) {
1009        let events = vec![
1010            DefiData::PoolSwap(create_test_swap(
1011                test_instrument_id,
1012                test_chain,
1013                test_dex,
1014                100,
1015                0,
1016                0,
1017            )),
1018            // Block events would be filtered out
1019        ];
1020        let sorted = convert_and_sort_buffered_events(events);
1021        assert_eq!(sorted.len(), 1);
1022    }
1023
1024    #[rstest]
1025    fn test_convert_and_sort_single_event(
1026        test_instrument_id: InstrumentId,
1027        test_chain: Arc<Chain>,
1028        test_dex: Arc<Dex>,
1029    ) {
1030        let swap = create_test_swap(test_instrument_id, test_chain, test_dex, 100, 5, 3);
1031        let events = vec![DefiData::PoolSwap(swap)];
1032        let sorted = convert_and_sort_buffered_events(events);
1033        assert_eq!(sorted.len(), 1);
1034        assert_eq!(get_event_block_position(&sorted[0]), (100, 5, 3));
1035    }
1036
1037    #[rstest]
1038    fn test_convert_and_sort_already_sorted(
1039        test_instrument_id: InstrumentId,
1040        test_chain: Arc<Chain>,
1041        test_dex: Arc<Dex>,
1042    ) {
1043        let events = vec![
1044            DefiData::PoolSwap(create_test_swap(
1045                test_instrument_id,
1046                Arc::clone(&test_chain),
1047                Arc::clone(&test_dex),
1048                100,
1049                0,
1050                0,
1051            )),
1052            DefiData::PoolSwap(create_test_swap(
1053                test_instrument_id,
1054                Arc::clone(&test_chain),
1055                Arc::clone(&test_dex),
1056                100,
1057                0,
1058                1,
1059            )),
1060            DefiData::PoolSwap(create_test_swap(
1061                test_instrument_id,
1062                test_chain,
1063                test_dex,
1064                100,
1065                1,
1066                0,
1067            )),
1068        ];
1069        let sorted = convert_and_sort_buffered_events(events);
1070        assert_eq!(sorted.len(), 3);
1071        assert_eq!(get_event_block_position(&sorted[0]), (100, 0, 0));
1072        assert_eq!(get_event_block_position(&sorted[1]), (100, 0, 1));
1073        assert_eq!(get_event_block_position(&sorted[2]), (100, 1, 0));
1074    }
1075
1076    #[rstest]
1077    fn test_convert_and_sort_reverse_order(
1078        test_instrument_id: InstrumentId,
1079        test_chain: Arc<Chain>,
1080        test_dex: Arc<Dex>,
1081    ) {
1082        let events = vec![
1083            DefiData::PoolSwap(create_test_swap(
1084                test_instrument_id,
1085                Arc::clone(&test_chain),
1086                Arc::clone(&test_dex),
1087                100,
1088                2,
1089                5,
1090            )),
1091            DefiData::PoolSwap(create_test_swap(
1092                test_instrument_id,
1093                Arc::clone(&test_chain),
1094                Arc::clone(&test_dex),
1095                100,
1096                1,
1097                3,
1098            )),
1099            DefiData::PoolSwap(create_test_swap(
1100                test_instrument_id,
1101                test_chain,
1102                test_dex,
1103                100,
1104                0,
1105                1,
1106            )),
1107        ];
1108        let sorted = convert_and_sort_buffered_events(events);
1109        assert_eq!(sorted.len(), 3);
1110        assert_eq!(get_event_block_position(&sorted[0]), (100, 0, 1));
1111        assert_eq!(get_event_block_position(&sorted[1]), (100, 1, 3));
1112        assert_eq!(get_event_block_position(&sorted[2]), (100, 2, 5));
1113    }
1114
1115    #[rstest]
1116    fn test_convert_and_sort_mixed_blocks(
1117        test_instrument_id: InstrumentId,
1118        test_chain: Arc<Chain>,
1119        test_dex: Arc<Dex>,
1120    ) {
1121        let events = vec![
1122            DefiData::PoolSwap(create_test_swap(
1123                test_instrument_id,
1124                Arc::clone(&test_chain),
1125                Arc::clone(&test_dex),
1126                102,
1127                0,
1128                0,
1129            )),
1130            DefiData::PoolSwap(create_test_swap(
1131                test_instrument_id,
1132                Arc::clone(&test_chain),
1133                Arc::clone(&test_dex),
1134                100,
1135                5,
1136                2,
1137            )),
1138            DefiData::PoolSwap(create_test_swap(
1139                test_instrument_id,
1140                test_chain,
1141                test_dex,
1142                101,
1143                3,
1144                1,
1145            )),
1146        ];
1147        let sorted = convert_and_sort_buffered_events(events);
1148        assert_eq!(sorted.len(), 3);
1149        assert_eq!(get_event_block_position(&sorted[0]), (100, 5, 2));
1150        assert_eq!(get_event_block_position(&sorted[1]), (101, 3, 1));
1151        assert_eq!(get_event_block_position(&sorted[2]), (102, 0, 0));
1152    }
1153
1154    #[rstest]
1155    fn test_convert_and_sort_mixed_event_types(
1156        test_instrument_id: InstrumentId,
1157        test_chain: Arc<Chain>,
1158        test_dex: Arc<Dex>,
1159    ) {
1160        let events = vec![
1161            DefiData::PoolSwap(create_test_swap(
1162                test_instrument_id,
1163                Arc::clone(&test_chain),
1164                Arc::clone(&test_dex),
1165                100,
1166                2,
1167                0,
1168            )),
1169            DefiData::PoolLiquidityUpdate(create_test_liquidity_update(
1170                test_instrument_id,
1171                Arc::clone(&test_chain),
1172                Arc::clone(&test_dex),
1173                100,
1174                0,
1175                0,
1176            )),
1177            DefiData::PoolFeeCollect(create_test_fee_collect(
1178                test_instrument_id,
1179                Arc::clone(&test_chain),
1180                Arc::clone(&test_dex),
1181                100,
1182                1,
1183                0,
1184            )),
1185            DefiData::PoolFlash(create_test_flash(
1186                test_instrument_id,
1187                Arc::clone(&test_chain),
1188                Arc::clone(&test_dex),
1189                100,
1190                3,
1191                0,
1192            )),
1193            DefiData::PoolFeeProtocolUpdate(create_test_fee_protocol_update(
1194                test_instrument_id,
1195                test_chain,
1196                test_dex,
1197                100,
1198                4,
1199                0,
1200            )),
1201        ];
1202        let sorted = convert_and_sort_buffered_events(events);
1203        assert_eq!(sorted.len(), 5);
1204        assert_eq!(get_event_block_position(&sorted[0]), (100, 0, 0));
1205        assert_eq!(get_event_block_position(&sorted[1]), (100, 1, 0));
1206        assert_eq!(get_event_block_position(&sorted[2]), (100, 2, 0));
1207        assert_eq!(get_event_block_position(&sorted[3]), (100, 3, 0));
1208        assert_eq!(get_event_block_position(&sorted[4]), (100, 4, 0));
1209        assert!(matches!(sorted[4], DexPoolData::FeeProtocolUpdate(_)));
1210    }
1211
1212    #[rstest]
1213    fn test_convert_and_sort_same_block_and_tx_different_log_index(
1214        test_instrument_id: InstrumentId,
1215        test_chain: Arc<Chain>,
1216        test_dex: Arc<Dex>,
1217    ) {
1218        let events = vec![
1219            DefiData::PoolSwap(create_test_swap(
1220                test_instrument_id,
1221                Arc::clone(&test_chain),
1222                Arc::clone(&test_dex),
1223                100,
1224                5,
1225                10,
1226            )),
1227            DefiData::PoolSwap(create_test_swap(
1228                test_instrument_id,
1229                Arc::clone(&test_chain),
1230                Arc::clone(&test_dex),
1231                100,
1232                5,
1233                5,
1234            )),
1235            DefiData::PoolSwap(create_test_swap(
1236                test_instrument_id,
1237                test_chain,
1238                test_dex,
1239                100,
1240                5,
1241                1,
1242            )),
1243        ];
1244        let sorted = convert_and_sort_buffered_events(events);
1245        assert_eq!(sorted.len(), 3);
1246        assert_eq!(get_event_block_position(&sorted[0]), (100, 5, 1));
1247        assert_eq!(get_event_block_position(&sorted[1]), (100, 5, 5));
1248        assert_eq!(get_event_block_position(&sorted[2]), (100, 5, 10));
1249    }
1250}