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                // Subscribers receive events immediately; keep a copy for profiler hydration
276                // while the snapshot is pending.
277                if self.pool_snapshot_pending.contains_key(&instrument_id) {
278                    log::debug!("Buffering swap event for {instrument_id} (waiting for snapshot)");
279                    self.pool_event_buffers
280                        .entry(instrument_id)
281                        .or_default()
282                        .push(DefiData::PoolSwap(swap.clone()));
283                }
284
285                let topic = defi::switchboard::get_defi_pool_swaps_topic(instrument_id);
286                msgbus::publish_defi_swap(topic, &swap);
287            }
288            DefiData::PoolLiquidityUpdate(update) => {
289                let instrument_id = update.instrument_id;
290                // Subscribers receive events immediately; keep a copy for profiler hydration
291                // while the snapshot is pending.
292                if self.pool_snapshot_pending.contains_key(&instrument_id) {
293                    log::debug!(
294                        "Buffering liquidity update event for {instrument_id} (waiting for snapshot)"
295                    );
296                    self.pool_event_buffers
297                        .entry(instrument_id)
298                        .or_default()
299                        .push(DefiData::PoolLiquidityUpdate(update.clone()));
300                }
301
302                let topic = defi::switchboard::get_defi_liquidity_topic(instrument_id);
303                msgbus::publish_defi_liquidity(topic, &update);
304            }
305            DefiData::PoolFeeCollect(collect) => {
306                let instrument_id = collect.instrument_id;
307                // Subscribers receive events immediately; keep a copy for profiler hydration
308                // while the snapshot is pending.
309                if self.pool_snapshot_pending.contains_key(&instrument_id) {
310                    log::debug!(
311                        "Buffering fee collect event for {instrument_id} (waiting for snapshot)"
312                    );
313                    self.pool_event_buffers
314                        .entry(instrument_id)
315                        .or_default()
316                        .push(DefiData::PoolFeeCollect(collect.clone()));
317                }
318
319                let topic = defi::switchboard::get_defi_collect_topic(instrument_id);
320                msgbus::publish_defi_collect(topic, &collect);
321            }
322            DefiData::PoolFeeProtocolUpdate(update) => {
323                let instrument_id = update.instrument_id;
324                // A protocol-fee change is profiler infrastructure, not a subscriber data stream:
325                // it only needs to keep the profiler's `fee_protocol` consistent for swap and flash
326                // fee splitting. Buffer until the snapshot lands, otherwise apply in place.
327                if self.pool_snapshot_pending.contains_key(&instrument_id) {
328                    log::debug!(
329                        "Buffering fee protocol update for {instrument_id} (waiting for snapshot)"
330                    );
331                    self.pool_event_buffers
332                        .entry(instrument_id)
333                        .or_default()
334                        .push(DefiData::PoolFeeProtocolUpdate(update));
335                } else if let Some(profiler) =
336                    self.cache().borrow_mut().pool_profiler_mut(&instrument_id)
337                    && let Err(e) = profiler.process_fee_protocol_update(&update)
338                {
339                    log::error!("Failed to process pool fee protocol update: {e}");
340                }
341            }
342            DefiData::PoolFeeProtocolCollect(collect) => {
343                let instrument_id = collect.instrument_id;
344                // A protocol-fee withdrawal is profiler infrastructure, not a subscriber data
345                // stream: it only decrements the profiler's accrued protocol-fee balances. Buffer
346                // until the snapshot lands, otherwise apply in place.
347                if self.pool_snapshot_pending.contains_key(&instrument_id) {
348                    log::debug!(
349                        "Buffering fee protocol collect event for {instrument_id} (waiting for snapshot)"
350                    );
351                    self.pool_event_buffers
352                        .entry(instrument_id)
353                        .or_default()
354                        .push(DefiData::PoolFeeProtocolCollect(collect));
355                } else if let Some(profiler) =
356                    self.cache().borrow_mut().pool_profiler_mut(&instrument_id)
357                    && let Err(e) = profiler.process_fee_protocol_collect(&collect)
358                {
359                    log::error!("Failed to process pool fee protocol collect event: {e}");
360                }
361            }
362            DefiData::PoolFlash(flash) => {
363                let instrument_id = flash.instrument_id;
364                // Subscribers receive events immediately; keep a copy for profiler hydration
365                // while the snapshot is pending.
366                if self.pool_snapshot_pending.contains_key(&instrument_id) {
367                    log::debug!("Buffering flash event for {instrument_id} (waiting for snapshot)");
368                    self.pool_event_buffers
369                        .entry(instrument_id)
370                        .or_default()
371                        .push(DefiData::PoolFlash(flash.clone()));
372                }
373
374                let topic = defi::switchboard::get_defi_flash_topic(instrument_id);
375                msgbus::publish_defi_flash(topic, &flash);
376            }
377        }
378    }
379
380    fn handle_pool(&mut self, pool: &Pool) {
381        let instrument = match CurrencyPair::try_from(pool) {
382            Ok(instrument) => InstrumentAny::CurrencyPair(instrument),
383            Err(e) => {
384                log::error!(
385                    "Failed to create instrument for Pool {}: {e}",
386                    pool.instrument_id
387                );
388                return;
389            }
390        };
391
392        if !self.cache_instrument(&instrument) {
393            return;
394        }
395
396        if let Err(e) = self.cache().borrow_mut().add_pool(pool.clone()) {
397            log::error!("Failed to add Pool to cache: {e}");
398            return;
399        }
400
401        self.publish_instrument(&instrument);
402
403        let topic = defi::switchboard::get_defi_pool_topic(pool.instrument_id);
404        msgbus::publish_defi_pool(topic, pool);
405    }
406
407    pub(crate) fn handle_pool_snapshot_response(&mut self, response: &PoolSnapshotResponse) {
408        let instrument_id = response.data.instrument_id;
409
410        if self.pool_snapshot_pending.get(&instrument_id) != Some(&response.correlation_id) {
411            log::warn!(
412                "Discarding pool snapshot for {instrument_id} from stale request {}",
413                response.correlation_id
414            );
415            return;
416        }
417
418        self.hydrate_pool_profiler(&response.data);
419    }
420
421    fn hydrate_pool_profiler(&mut self, snapshot: &PoolSnapshot) {
422        let instrument_id = snapshot.instrument_id;
423        log::info!(
424            "Received pool snapshot for {instrument_id} at block {} with {} positions and {} ticks",
425            snapshot.block_position.number,
426            snapshot.positions.len(),
427            snapshot.ticks.len()
428        );
429
430        // Get pool from cache
431        let pool = self
432            .cache()
433            .borrow()
434            .pool(&instrument_id)
435            .map(|pool| Arc::new(pool.clone()));
436
437        let Some(pool) = pool else {
438            log::error!("Pool {instrument_id} not found in cache when processing snapshot");
439            self.abandon_pool_snapshot(&instrument_id);
440            return;
441        };
442
443        // Defensive: refuse stub snapshots that slipped past the bootstrap-side
444        // guards. Installing one would leave Python actors observing an initialized
445        // profiler with zero liquidity; better to leave the pool without a profiler
446        // so the bad state is visible.
447        if snapshot.positions.is_empty()
448            && snapshot.ticks.is_empty()
449            && snapshot.block_position.number == pool.creation_block
450        {
451            log::warn!(
452                "Refusing empty stub snapshot for {instrument_id} at pool creation block {}; pool will remain without profiler",
453                snapshot.block_position.number,
454            );
455            self.abandon_pool_snapshot(&instrument_id);
456            return;
457        }
458
459        // Create profiler and restore from snapshot
460        let mut profiler = PoolProfiler::new(pool);
461        if let Err(e) = profiler.restore_from_snapshot(snapshot.clone()) {
462            log::error!("Failed to restore profiler from snapshot for {instrument_id}: {e}");
463            self.abandon_pool_snapshot(&instrument_id);
464            return;
465        }
466
467        log::debug!("Restored pool profiler for {instrument_id} from snapshot");
468
469        // Process buffered events
470        let buffered_events = self
471            .pool_event_buffers
472            .remove(&instrument_id)
473            .unwrap_or_default();
474
475        if !buffered_events.is_empty() {
476            log::info!(
477                "Processing {} buffered events for {instrument_id}",
478                buffered_events.len()
479            );
480
481            let events_to_apply = convert_and_sort_buffered_events(buffered_events);
482            let applied_count = Self::apply_buffered_events_to_profiler(
483                &mut profiler,
484                events_to_apply,
485                &snapshot.block_position,
486                instrument_id,
487            );
488
489            log::info!("Applied {applied_count} buffered events to profiler for {instrument_id}");
490        }
491
492        // Add profiler to cache
493        let result = self.cache().borrow_mut().add_pool_profiler(profiler);
494        if let Err(e) = result {
495            log::error!("Failed to add pool profiler to cache for {instrument_id}: {e}");
496            self.abandon_pool_snapshot(&instrument_id);
497            return;
498        }
499
500        // Create updater and subscribe to topics
501        self.pool_snapshot_pending.remove(&instrument_id);
502        let updater = Rc::new(PoolUpdater::new(&instrument_id, Rc::clone(self.cache())));
503
504        self.subscribe_pool_updater_topics(instrument_id, Rc::clone(&updater));
505        self.pool_updaters.insert(instrument_id, updater);
506
507        log::info!("Pool profiler setup completed for {instrument_id}, now processing live events");
508    }
509
510    fn abandon_pool_snapshot(&mut self, instrument_id: &InstrumentId) {
511        self.pool_snapshot_pending.remove(instrument_id);
512        self.pool_event_buffers.remove(instrument_id);
513    }
514
515    /// Subscribes a pool updater to all relevant pool data topics using typed handlers.
516    fn subscribe_pool_updater_topics(&self, instrument_id: InstrumentId, updater: Rc<PoolUpdater>) {
517        let priority = Some(self.msgbus_priority());
518
519        // Subscribe swap handler
520        let swap_topic = defi::switchboard::get_defi_pool_swaps_topic(instrument_id);
521        let swap_handler = TypedHandler(Rc::new(PoolSwapHandler::new(Rc::clone(&updater))));
522        msgbus::subscribe_defi_swaps(swap_topic.into(), swap_handler, priority);
523
524        // Subscribe liquidity handler
525        let liq_topic = defi::switchboard::get_defi_liquidity_topic(instrument_id);
526        let liq_handler = TypedHandler(Rc::new(PoolLiquidityHandler::new(Rc::clone(&updater))));
527        msgbus::subscribe_defi_liquidity(liq_topic.into(), liq_handler, priority);
528
529        // Subscribe collect handler
530        let collect_topic = defi::switchboard::get_defi_collect_topic(instrument_id);
531        let collect_handler = TypedHandler(Rc::new(PoolCollectHandler::new(Rc::clone(&updater))));
532        msgbus::subscribe_defi_collects(collect_topic.into(), collect_handler, priority);
533
534        // Subscribe flash handler
535        let flash_topic = defi::switchboard::get_defi_flash_topic(instrument_id);
536        let flash_handler = TypedHandler(Rc::new(PoolFlashHandler::new(updater)));
537        msgbus::subscribe_defi_flash(flash_topic.into(), flash_handler, priority);
538    }
539
540    /// Applies buffered events to a pool profiler, filtering to events after the snapshot.
541    ///
542    /// Returns the count of successfully applied events.
543    fn apply_buffered_events_to_profiler(
544        profiler: &mut PoolProfiler,
545        events: Vec<DexPoolData>,
546        snapshot_block: &BlockPosition,
547        instrument_id: InstrumentId,
548    ) -> usize {
549        let mut applied_count = 0;
550
551        for event in events {
552            let event_block = get_event_block_position(&event);
553
554            // Only apply events that occurred after the snapshot
555            let is_after_snapshot = event_block.0 > snapshot_block.number
556                || (event_block.0 == snapshot_block.number
557                    && event_block.1 > snapshot_block.transaction_index)
558                || (event_block.0 == snapshot_block.number
559                    && event_block.1 == snapshot_block.transaction_index
560                    && event_block.2 > snapshot_block.log_index);
561
562            if is_after_snapshot {
563                if let Err(e) = profiler.process(&event) {
564                    log::error!(
565                        "Failed to apply buffered event to profiler for {instrument_id}: {e}"
566                    );
567                } else {
568                    applied_count += 1;
569                }
570            }
571        }
572
573        applied_count
574    }
575
576    fn setup_pool_updater(&mut self, instrument_id: &InstrumentId, client_id: Option<&ClientId>) {
577        // Early return if updater already exists or we are in the middle of setting it up.
578        if self.pool_updaters.contains_key(instrument_id)
579            || self.pool_snapshot_pending.contains_key(instrument_id)
580        {
581            log::debug!("Pool updater for {instrument_id} already exists");
582            return;
583        }
584
585        log::info!("Setting up pool updater for {instrument_id}");
586
587        // Check cache state and ensure profiler exists
588        {
589            let mut cache = self.cache().borrow_mut();
590
591            if cache.pool_profiler(instrument_id).is_some() {
592                // Profiler already exists, proceed to create updater
593                log::debug!("Pool profiler already exists for {instrument_id}");
594            } else if let Some(pool) = cache.pool(instrument_id) {
595                // Pool exists but no profiler, create profiler from pool
596                let pool = Arc::new(pool.clone());
597                let mut pool_profiler = PoolProfiler::new(Arc::clone(&pool));
598
599                if let Some(initial_sqrt_price_x96) = pool.initial_sqrt_price_x96 {
600                    if let Err(e) = pool_profiler.initialize(initial_sqrt_price_x96) {
601                        log::error!("Failed to initialize pool profiler for {instrument_id}: {e}");
602                        drop(cache);
603                        return;
604                    }
605                    log::debug!(
606                        "Initialized pool profiler for {instrument_id} with sqrt_price {initial_sqrt_price_x96}"
607                    );
608                } else {
609                    log::debug!("Created pool profiler for {instrument_id}");
610                }
611
612                if let Err(e) = cache.add_pool_profiler(pool_profiler) {
613                    log::error!("Failed to add pool profiler for {instrument_id}: {e}");
614                    drop(cache);
615                    return;
616                }
617                drop(cache);
618            } else {
619                // Neither profiler nor pool exists, request snapshot
620                drop(cache);
621
622                let request_id = UUID4::new();
623                let ts_init = self.clock().borrow().timestamp_ns();
624
625                let request = RequestPoolSnapshot::new(
626                    *instrument_id,
627                    client_id.copied(),
628                    request_id,
629                    ts_init,
630                    None,
631                );
632
633                if let Err(e) = self.execute_defi_request(DefiRequestCommand::PoolSnapshot(request))
634                {
635                    log::warn!("Failed to request pool snapshot for {instrument_id}: {e}");
636                } else {
637                    log::debug!("Requested pool snapshot for {instrument_id}");
638                    self.pool_snapshot_pending
639                        .insert(*instrument_id, request_id);
640                    self.pool_event_buffers.entry(*instrument_id).or_default();
641                }
642                return;
643            }
644        }
645
646        // Profiler exists, create updater and subscribe to topics
647        let updater = Rc::new(PoolUpdater::new(instrument_id, Rc::clone(self.cache())));
648
649        self.subscribe_pool_updater_topics(*instrument_id, Rc::clone(&updater));
650        self.pool_updaters.insert(*instrument_id, updater);
651
652        log::debug!("Created PoolUpdater for instrument ID {instrument_id}");
653    }
654
655    fn release_pool_updater(&mut self, instrument_id: &InstrumentId) {
656        if let Some(updater) = self.pool_updaters.remove(instrument_id) {
657            Self::unsubscribe_pool_updater_topics(*instrument_id, updater);
658            log::debug!("Removed PoolUpdater for instrument ID {instrument_id}");
659        }
660
661        self.abandon_pool_snapshot(instrument_id);
662    }
663
664    pub(crate) fn clear_pool_updaters(&mut self) {
665        let updaters: Vec<_> = self.pool_updaters.drain().collect();
666        for (instrument_id, updater) in updaters {
667            Self::unsubscribe_pool_updater_topics(instrument_id, updater);
668        }
669
670        self.abandon_pool_snapshots();
671    }
672
673    pub(crate) fn abandon_pool_snapshots(&mut self) {
674        self.pool_snapshot_pending.clear();
675        self.pool_event_buffers.clear();
676    }
677
678    fn unsubscribe_pool_updater_topics(instrument_id: InstrumentId, updater: Rc<PoolUpdater>) {
679        let swap_topic = defi::switchboard::get_defi_pool_swaps_topic(instrument_id);
680        let swap_handler = TypedHandler(Rc::new(PoolSwapHandler::new(Rc::clone(&updater))));
681        msgbus::unsubscribe_defi_swaps(swap_topic.into(), &swap_handler);
682
683        let liq_topic = defi::switchboard::get_defi_liquidity_topic(instrument_id);
684        let liq_handler = TypedHandler(Rc::new(PoolLiquidityHandler::new(Rc::clone(&updater))));
685        msgbus::unsubscribe_defi_liquidity(liq_topic.into(), &liq_handler);
686
687        let collect_topic = defi::switchboard::get_defi_collect_topic(instrument_id);
688        let collect_handler = TypedHandler(Rc::new(PoolCollectHandler::new(Rc::clone(&updater))));
689        msgbus::unsubscribe_defi_collects(collect_topic.into(), &collect_handler);
690
691        let flash_topic = defi::switchboard::get_defi_flash_topic(instrument_id);
692        let flash_handler = TypedHandler(Rc::new(PoolFlashHandler::new(updater)));
693        msgbus::unsubscribe_defi_flash(flash_topic.into(), &flash_handler);
694    }
695}
696
697#[cfg(test)]
698mod tests {
699    use std::sync::Arc;
700
701    use alloy_primitives::{Address, I256, U160, U256};
702    use nautilus_core::UnixNanos;
703    use nautilus_model::{
704        defi::{
705            Chain, DefiData, PoolFeeCollect, PoolFeeProtocolUpdate, PoolFlash, PoolIdentifier,
706            PoolLiquidityUpdate, PoolLiquidityUpdateType, PoolSwap,
707            chain::chains,
708            data::DexPoolData,
709            dex::{AmmType, Dex, DexType},
710        },
711        identifiers::{InstrumentId, Symbol, Venue},
712    };
713    use rstest::*;
714
715    use super::*;
716
717    #[fixture]
718    fn test_instrument_id() -> InstrumentId {
719        InstrumentId::new(Symbol::from("ETH/USDC"), Venue::from("UNISWAPV3"))
720    }
721
722    #[fixture]
723    fn test_chain() -> Arc<Chain> {
724        Arc::new(chains::ETHEREUM.clone())
725    }
726
727    #[fixture]
728    fn test_dex(test_chain: Arc<Chain>) -> Arc<Dex> {
729        Arc::new(Dex::new(
730            (*test_chain).clone(),
731            DexType::UniswapV3,
732            "0x1F98431c8aD98523631AE4a59f267346ea31F984",
733            12369621,
734            AmmType::CLAMM,
735            "PoolCreated(address,address,uint24,int24,address)",
736            "Swap(address,address,int256,int256,uint160,uint128,int24)",
737            "Mint(address,address,int24,int24,uint128,uint256,uint256)",
738            "Burn(address,int24,int24,uint128,uint256,uint256)",
739            "Collect(address,address,int24,int24,uint128,uint128)",
740        ))
741    }
742
743    fn create_test_swap(
744        test_instrument_id: InstrumentId,
745        test_chain: Arc<Chain>,
746        test_dex: Arc<Dex>,
747        block: u64,
748        tx_index: u32,
749        log_index: u32,
750    ) -> PoolSwap {
751        PoolSwap::new(
752            test_chain,
753            test_dex,
754            test_instrument_id,
755            PoolIdentifier::from_address(Address::ZERO),
756            block,
757            format!("0x{block:064x}"),
758            tx_index,
759            log_index,
760            UnixNanos::default(),
761            UnixNanos::default(),
762            Address::ZERO,
763            Address::ZERO,
764            I256::ZERO,
765            I256::ZERO,
766            U160::ZERO,
767            0,
768            0,
769        )
770    }
771
772    fn create_test_liquidity_update(
773        test_instrument_id: InstrumentId,
774        test_chain: Arc<Chain>,
775        test_dex: Arc<Dex>,
776        block: u64,
777        tx_index: u32,
778        log_index: u32,
779    ) -> PoolLiquidityUpdate {
780        PoolLiquidityUpdate::new(
781            test_chain,
782            test_dex,
783            test_instrument_id,
784            PoolIdentifier::from_address(Address::ZERO),
785            PoolLiquidityUpdateType::Mint,
786            block,
787            format!("0x{block:064x}"),
788            tx_index,
789            log_index,
790            None,
791            Address::ZERO,
792            0,
793            U256::ZERO,
794            U256::ZERO,
795            0,
796            0,
797            UnixNanos::default(),
798            UnixNanos::default(),
799        )
800    }
801
802    fn create_test_fee_collect(
803        test_instrument_id: InstrumentId,
804        test_chain: Arc<Chain>,
805        test_dex: Arc<Dex>,
806        block: u64,
807        tx_index: u32,
808        log_index: u32,
809    ) -> PoolFeeCollect {
810        PoolFeeCollect::new(
811            test_chain,
812            test_dex,
813            test_instrument_id,
814            PoolIdentifier::from_address(Address::ZERO),
815            block,
816            format!("0x{block:064x}"),
817            tx_index,
818            log_index,
819            Address::ZERO,
820            0,
821            0,
822            0,
823            0,
824            UnixNanos::default(),
825            UnixNanos::default(),
826        )
827    }
828
829    fn create_test_flash(
830        test_instrument_id: InstrumentId,
831        test_chain: Arc<Chain>,
832        test_dex: Arc<Dex>,
833        block: u64,
834        tx_index: u32,
835        log_index: u32,
836    ) -> PoolFlash {
837        PoolFlash::new(
838            test_chain,
839            test_dex,
840            test_instrument_id,
841            PoolIdentifier::from_address(Address::ZERO),
842            block,
843            format!("0x{block:064x}"),
844            tx_index,
845            log_index,
846            UnixNanos::default(),
847            UnixNanos::default(),
848            Address::ZERO,
849            Address::ZERO,
850            U256::ZERO,
851            U256::ZERO,
852            U256::ZERO,
853            U256::ZERO,
854        )
855    }
856
857    fn create_test_fee_protocol_update(
858        test_instrument_id: InstrumentId,
859        test_chain: Arc<Chain>,
860        test_dex: Arc<Dex>,
861        block: u64,
862        tx_index: u32,
863        log_index: u32,
864    ) -> PoolFeeProtocolUpdate {
865        PoolFeeProtocolUpdate::new(
866            test_chain,
867            test_dex,
868            test_instrument_id,
869            PoolIdentifier::from_address(Address::ZERO),
870            block,
871            format!("0x{block:064x}"),
872            tx_index,
873            log_index,
874            4,
875            4,
876            UnixNanos::default(),
877            UnixNanos::default(),
878        )
879    }
880
881    #[rstest]
882    fn test_get_event_block_position_swap(
883        test_instrument_id: InstrumentId,
884        test_chain: Arc<Chain>,
885        test_dex: Arc<Dex>,
886    ) {
887        let swap = create_test_swap(test_instrument_id, test_chain, test_dex, 100, 5, 3);
888        let pos = get_event_block_position(&DexPoolData::Swap(swap));
889        assert_eq!(pos, (100, 5, 3));
890    }
891
892    #[rstest]
893    fn test_get_event_block_position_liquidity_update(
894        test_instrument_id: InstrumentId,
895        test_chain: Arc<Chain>,
896        test_dex: Arc<Dex>,
897    ) {
898        let update =
899            create_test_liquidity_update(test_instrument_id, test_chain, test_dex, 200, 10, 7);
900        let pos = get_event_block_position(&DexPoolData::LiquidityUpdate(update));
901        assert_eq!(pos, (200, 10, 7));
902    }
903
904    #[rstest]
905    fn test_get_event_block_position_fee_collect(
906        test_instrument_id: InstrumentId,
907        test_chain: Arc<Chain>,
908        test_dex: Arc<Dex>,
909    ) {
910        let collect = create_test_fee_collect(test_instrument_id, test_chain, test_dex, 300, 15, 2);
911        let pos = get_event_block_position(&DexPoolData::FeeCollect(collect));
912        assert_eq!(pos, (300, 15, 2));
913    }
914
915    #[rstest]
916    fn test_get_event_block_position_flash(
917        test_instrument_id: InstrumentId,
918        test_chain: Arc<Chain>,
919        test_dex: Arc<Dex>,
920    ) {
921        let flash = create_test_flash(test_instrument_id, test_chain, test_dex, 400, 20, 8);
922        let pos = get_event_block_position(&DexPoolData::Flash(flash));
923        assert_eq!(pos, (400, 20, 8));
924    }
925
926    #[rstest]
927    fn test_get_event_block_position_fee_protocol_update(
928        test_instrument_id: InstrumentId,
929        test_chain: Arc<Chain>,
930        test_dex: Arc<Dex>,
931    ) {
932        let update =
933            create_test_fee_protocol_update(test_instrument_id, test_chain, test_dex, 500, 25, 4);
934        let pos = get_event_block_position(&DexPoolData::FeeProtocolUpdate(update));
935        assert_eq!(pos, (500, 25, 4));
936    }
937
938    #[rstest]
939    fn test_convert_and_sort_empty_events() {
940        let events = convert_and_sort_buffered_events(vec![]);
941        assert!(events.is_empty());
942    }
943
944    #[rstest]
945    fn test_convert_and_sort_filters_non_pool_events(
946        test_instrument_id: InstrumentId,
947        test_chain: Arc<Chain>,
948        test_dex: Arc<Dex>,
949    ) {
950        let events = vec![
951            DefiData::PoolSwap(create_test_swap(
952                test_instrument_id,
953                test_chain,
954                test_dex,
955                100,
956                0,
957                0,
958            )),
959            // Block events would be filtered out
960        ];
961        let sorted = convert_and_sort_buffered_events(events);
962        assert_eq!(sorted.len(), 1);
963    }
964
965    #[rstest]
966    fn test_convert_and_sort_single_event(
967        test_instrument_id: InstrumentId,
968        test_chain: Arc<Chain>,
969        test_dex: Arc<Dex>,
970    ) {
971        let swap = create_test_swap(test_instrument_id, test_chain, test_dex, 100, 5, 3);
972        let events = vec![DefiData::PoolSwap(swap)];
973        let sorted = convert_and_sort_buffered_events(events);
974        assert_eq!(sorted.len(), 1);
975        assert_eq!(get_event_block_position(&sorted[0]), (100, 5, 3));
976    }
977
978    #[rstest]
979    fn test_convert_and_sort_already_sorted(
980        test_instrument_id: InstrumentId,
981        test_chain: Arc<Chain>,
982        test_dex: Arc<Dex>,
983    ) {
984        let events = vec![
985            DefiData::PoolSwap(create_test_swap(
986                test_instrument_id,
987                Arc::clone(&test_chain),
988                Arc::clone(&test_dex),
989                100,
990                0,
991                0,
992            )),
993            DefiData::PoolSwap(create_test_swap(
994                test_instrument_id,
995                Arc::clone(&test_chain),
996                Arc::clone(&test_dex),
997                100,
998                0,
999                1,
1000            )),
1001            DefiData::PoolSwap(create_test_swap(
1002                test_instrument_id,
1003                test_chain,
1004                test_dex,
1005                100,
1006                1,
1007                0,
1008            )),
1009        ];
1010        let sorted = convert_and_sort_buffered_events(events);
1011        assert_eq!(sorted.len(), 3);
1012        assert_eq!(get_event_block_position(&sorted[0]), (100, 0, 0));
1013        assert_eq!(get_event_block_position(&sorted[1]), (100, 0, 1));
1014        assert_eq!(get_event_block_position(&sorted[2]), (100, 1, 0));
1015    }
1016
1017    #[rstest]
1018    fn test_convert_and_sort_reverse_order(
1019        test_instrument_id: InstrumentId,
1020        test_chain: Arc<Chain>,
1021        test_dex: Arc<Dex>,
1022    ) {
1023        let events = vec![
1024            DefiData::PoolSwap(create_test_swap(
1025                test_instrument_id,
1026                Arc::clone(&test_chain),
1027                Arc::clone(&test_dex),
1028                100,
1029                2,
1030                5,
1031            )),
1032            DefiData::PoolSwap(create_test_swap(
1033                test_instrument_id,
1034                Arc::clone(&test_chain),
1035                Arc::clone(&test_dex),
1036                100,
1037                1,
1038                3,
1039            )),
1040            DefiData::PoolSwap(create_test_swap(
1041                test_instrument_id,
1042                test_chain,
1043                test_dex,
1044                100,
1045                0,
1046                1,
1047            )),
1048        ];
1049        let sorted = convert_and_sort_buffered_events(events);
1050        assert_eq!(sorted.len(), 3);
1051        assert_eq!(get_event_block_position(&sorted[0]), (100, 0, 1));
1052        assert_eq!(get_event_block_position(&sorted[1]), (100, 1, 3));
1053        assert_eq!(get_event_block_position(&sorted[2]), (100, 2, 5));
1054    }
1055
1056    #[rstest]
1057    fn test_convert_and_sort_mixed_blocks(
1058        test_instrument_id: InstrumentId,
1059        test_chain: Arc<Chain>,
1060        test_dex: Arc<Dex>,
1061    ) {
1062        let events = vec![
1063            DefiData::PoolSwap(create_test_swap(
1064                test_instrument_id,
1065                Arc::clone(&test_chain),
1066                Arc::clone(&test_dex),
1067                102,
1068                0,
1069                0,
1070            )),
1071            DefiData::PoolSwap(create_test_swap(
1072                test_instrument_id,
1073                Arc::clone(&test_chain),
1074                Arc::clone(&test_dex),
1075                100,
1076                5,
1077                2,
1078            )),
1079            DefiData::PoolSwap(create_test_swap(
1080                test_instrument_id,
1081                test_chain,
1082                test_dex,
1083                101,
1084                3,
1085                1,
1086            )),
1087        ];
1088        let sorted = convert_and_sort_buffered_events(events);
1089        assert_eq!(sorted.len(), 3);
1090        assert_eq!(get_event_block_position(&sorted[0]), (100, 5, 2));
1091        assert_eq!(get_event_block_position(&sorted[1]), (101, 3, 1));
1092        assert_eq!(get_event_block_position(&sorted[2]), (102, 0, 0));
1093    }
1094
1095    #[rstest]
1096    fn test_convert_and_sort_mixed_event_types(
1097        test_instrument_id: InstrumentId,
1098        test_chain: Arc<Chain>,
1099        test_dex: Arc<Dex>,
1100    ) {
1101        let events = vec![
1102            DefiData::PoolSwap(create_test_swap(
1103                test_instrument_id,
1104                Arc::clone(&test_chain),
1105                Arc::clone(&test_dex),
1106                100,
1107                2,
1108                0,
1109            )),
1110            DefiData::PoolLiquidityUpdate(create_test_liquidity_update(
1111                test_instrument_id,
1112                Arc::clone(&test_chain),
1113                Arc::clone(&test_dex),
1114                100,
1115                0,
1116                0,
1117            )),
1118            DefiData::PoolFeeCollect(create_test_fee_collect(
1119                test_instrument_id,
1120                Arc::clone(&test_chain),
1121                Arc::clone(&test_dex),
1122                100,
1123                1,
1124                0,
1125            )),
1126            DefiData::PoolFlash(create_test_flash(
1127                test_instrument_id,
1128                Arc::clone(&test_chain),
1129                Arc::clone(&test_dex),
1130                100,
1131                3,
1132                0,
1133            )),
1134            DefiData::PoolFeeProtocolUpdate(create_test_fee_protocol_update(
1135                test_instrument_id,
1136                test_chain,
1137                test_dex,
1138                100,
1139                4,
1140                0,
1141            )),
1142        ];
1143        let sorted = convert_and_sort_buffered_events(events);
1144        assert_eq!(sorted.len(), 5);
1145        assert_eq!(get_event_block_position(&sorted[0]), (100, 0, 0));
1146        assert_eq!(get_event_block_position(&sorted[1]), (100, 1, 0));
1147        assert_eq!(get_event_block_position(&sorted[2]), (100, 2, 0));
1148        assert_eq!(get_event_block_position(&sorted[3]), (100, 3, 0));
1149        assert_eq!(get_event_block_position(&sorted[4]), (100, 4, 0));
1150        assert!(matches!(sorted[4], DexPoolData::FeeProtocolUpdate(_)));
1151    }
1152
1153    #[rstest]
1154    fn test_convert_and_sort_same_block_and_tx_different_log_index(
1155        test_instrument_id: InstrumentId,
1156        test_chain: Arc<Chain>,
1157        test_dex: Arc<Dex>,
1158    ) {
1159        let events = vec![
1160            DefiData::PoolSwap(create_test_swap(
1161                test_instrument_id,
1162                Arc::clone(&test_chain),
1163                Arc::clone(&test_dex),
1164                100,
1165                5,
1166                10,
1167            )),
1168            DefiData::PoolSwap(create_test_swap(
1169                test_instrument_id,
1170                Arc::clone(&test_chain),
1171                Arc::clone(&test_dex),
1172                100,
1173                5,
1174                5,
1175            )),
1176            DefiData::PoolSwap(create_test_swap(
1177                test_instrument_id,
1178                test_chain,
1179                test_dex,
1180                100,
1181                5,
1182                1,
1183            )),
1184        ];
1185        let sorted = convert_and_sort_buffered_events(events);
1186        assert_eq!(sorted.len(), 3);
1187        assert_eq!(get_event_block_position(&sorted[0]), (100, 5, 1));
1188        assert_eq!(get_event_block_position(&sorted[1]), (100, 5, 5));
1189        assert_eq!(get_event_block_position(&sorted[2]), (100, 5, 10));
1190    }
1191}