nautilus_model/defi/data/
liquidity.rs

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

nautilus_model/defi/data/
liquidity.rs
