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

nautilus_model/defi/data/
liquidity.rs
