nautilus_model/defi/data/
liquidity.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2025 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
16use std::fmt::Display;
17
18use alloy_primitives::{Address, U256};
19use nautilus_core::UnixNanos;
20use serde::{Deserialize, Serialize};
21use strum::{Display, EnumIter, EnumString};
22
23use crate::{
24    defi::{SharedChain, SharedDex},
25    identifiers::InstrumentId,
26};
27
28#[derive(
29    Debug,
30    Clone,
31    Copy,
32    Hash,
33    PartialOrd,
34    PartialEq,
35    Ord,
36    Eq,
37    Display,
38    EnumIter,
39    EnumString,
40    Serialize,
41    Deserialize,
42)]
43#[cfg_attr(
44    feature = "python",
45    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.model")
46)]
47/// Represents the type of liquidity update operation in a DEX pool.
48#[non_exhaustive]
49pub enum PoolLiquidityUpdateType {
50    /// Liquidity is being added to the pool
51    Mint,
52    /// Liquidity is being removed from the pool
53    Burn,
54}
55
56/// Represents a liquidity update event in a decentralized exchange (DEX) pool.
57#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
58#[cfg_attr(
59    feature = "python",
60    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.model")
61)]
62pub struct PoolLiquidityUpdate {
63    /// The blockchain network where the liquidity update occurred.
64    pub chain: SharedChain,
65    /// The decentralized exchange where the liquidity update was executed.
66    pub dex: SharedDex,
67    /// The instrument ID for this pool's trading pair.
68    pub instrument_id: InstrumentId,
69    /// The blockchain address of the pool smart contract.
70    pub pool_address: Address,
71    /// The type of the pool liquidity update.
72    pub kind: PoolLiquidityUpdateType,
73    /// The blockchain block number where the liquidity update occurred.
74    pub block: u64,
75    /// The unique hash identifier of the blockchain transaction containing the liquidity update.
76    pub transaction_hash: String,
77    /// The index position of the transaction within the block.
78    pub transaction_index: u32,
79    /// The index position of the liquidity update event log within the transaction.
80    pub log_index: u32,
81    /// The blockchain address that initiated the liquidity update transaction.
82    pub sender: Option<Address>,
83    /// The blockchain address that owns the liquidity position.
84    pub owner: Address,
85    /// The amount of liquidity tokens affected in the position.
86    pub position_liquidity: u128,
87    /// The amount of the first token in the pool pair.
88    pub amount0: U256,
89    /// The amount of the second token in the pool pair.
90    pub amount1: U256,
91    /// The lower price tick boundary of the liquidity position.
92    pub tick_lower: i32,
93    /// The upper price tick boundary of the liquidity position.
94    pub tick_upper: i32,
95    /// The timestamp of the liquidity update in Unix nanoseconds.
96    pub timestamp: Option<UnixNanos>,
97    /// UNIX timestamp (nanoseconds) when the instance was created.
98    pub ts_init: Option<UnixNanos>,
99}
100
101impl PoolLiquidityUpdate {
102    /// Creates a new [`PoolLiquidityUpdate`] instance with the specified properties.
103    #[must_use]
104    #[allow(clippy::too_many_arguments)]
105    pub const fn new(
106        chain: SharedChain,
107        dex: SharedDex,
108        instrument_id: InstrumentId,
109        pool_address: Address,
110        kind: PoolLiquidityUpdateType,
111        block: u64,
112        transaction_hash: String,
113        transaction_index: u32,
114        log_index: u32,
115        sender: Option<Address>,
116        owner: Address,
117        position_liquidity: u128,
118        amount0: U256,
119        amount1: U256,
120        tick_lower: i32,
121        tick_upper: i32,
122        timestamp: Option<UnixNanos>,
123    ) -> Self {
124        Self {
125            chain,
126            dex,
127            instrument_id,
128            pool_address,
129            kind,
130            block,
131            transaction_hash,
132            transaction_index,
133            log_index,
134            sender,
135            owner,
136            position_liquidity,
137            amount0,
138            amount1,
139            tick_lower,
140            tick_upper,
141            timestamp,
142            ts_init: timestamp,
143        }
144    }
145
146    /// Returns the instrument ID for this pool's trading pair.
147    #[must_use]
148    pub const fn instrument_id(&self) -> InstrumentId {
149        self.instrument_id
150    }
151}
152
153impl Display for PoolLiquidityUpdate {
154    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
155        write!(
156            f,
157            "PoolLiquidityUpdate(instrument_id={}, kind={}, amount0={}, amount1={}, liquidity={})",
158            self.instrument_id, self.kind, self.amount0, self.amount1, self.position_liquidity
159        )
160    }
161}
nautilus_model/defi/data/liquidity.rs

nautilus_model/defi/data/
liquidity.rs
