nautilus_model/defi/data/liquidity.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
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::{PoolIdentifier, 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(
46 frozen,
47 eq,
48 eq_int,
49 module = "nautilus_trader.model",
50 from_py_object,
51 rename_all = "SCREAMING_SNAKE_CASE",
52 )
53)]
54#[cfg_attr(
55 feature = "python",
56 pyo3_stub_gen::derive::gen_stub_pyclass_enum(module = "nautilus_trader.model")
57)]
58/// Represents the type of liquidity update operation in a DEX pool.
59#[non_exhaustive]
60pub enum PoolLiquidityUpdateType {
61 /// Liquidity is being added to the pool
62 Mint,
63 /// Liquidity is being removed from the pool
64 Burn,
65}
66
67/// Represents a liquidity update event in a decentralized exchange (DEX) pool.
68#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
69#[cfg_attr(
70 feature = "python",
71 pyo3::pyclass(module = "nautilus_trader.model", from_py_object)
72)]
73#[cfg_attr(
74 feature = "python",
75 pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.model")
76)]
77pub struct PoolLiquidityUpdate {
78 /// The blockchain network where the liquidity update occurred.
79 pub chain: SharedChain,
80 /// The decentralized exchange where the liquidity update was executed.
81 pub dex: SharedDex,
82 /// The instrument ID for this pool's trading pair.
83 pub instrument_id: InstrumentId,
84 /// The unique identifier for this pool (could be an address or other protocol-specific hex string).
85 pub pool_identifier: PoolIdentifier,
86 /// The type of the pool liquidity update.
87 pub kind: PoolLiquidityUpdateType,
88 /// The blockchain block number where the liquidity update occurred.
89 pub block: u64,
90 /// The hash of the block observed when this update was ingested.
91 #[serde(default, skip_serializing_if = "Option::is_none")]
92 pub block_hash: Option<String>,
93 /// The unique hash identifier of the blockchain transaction containing the liquidity update.
94 pub transaction_hash: String,
95 /// The index position of the transaction within the block.
96 pub transaction_index: u32,
97 /// The index position of the liquidity update event log within the transaction.
98 pub log_index: u32,
99 /// The blockchain address that initiated the liquidity update transaction.
100 pub sender: Option<Address>,
101 /// The blockchain address that owns the liquidity position.
102 pub owner: Address,
103 /// The amount of liquidity tokens affected in the position.
104 pub position_liquidity: u128,
105 /// The amount of the first token in the pool pair.
106 pub amount0: U256,
107 /// The amount of the second token in the pool pair.
108 pub amount1: U256,
109 /// The lower price tick boundary of the liquidity position.
110 pub tick_lower: i32,
111 /// The upper price tick boundary of the liquidity position.
112 pub tick_upper: i32,
113 /// UNIX timestamp (nanoseconds) when the liquidity update event occurred.
114 pub ts_event: UnixNanos,
115 /// UNIX timestamp (nanoseconds) when the instance was created.
116 pub ts_init: UnixNanos,
117}
118
119impl PoolLiquidityUpdate {
120 /// Creates a new [`PoolLiquidityUpdate`] instance with the specified properties.
121 #[must_use]
122 #[expect(clippy::too_many_arguments)]
123 pub const fn new(
124 chain: SharedChain,
125 dex: SharedDex,
126 instrument_id: InstrumentId,
127 pool_identifier: PoolIdentifier,
128 kind: PoolLiquidityUpdateType,
129 block: u64,
130 transaction_hash: String,
131 transaction_index: u32,
132 log_index: u32,
133 sender: Option<Address>,
134 owner: Address,
135 position_liquidity: u128,
136 amount0: U256,
137 amount1: U256,
138 tick_lower: i32,
139 tick_upper: i32,
140 ts_event: UnixNanos,
141 ts_init: UnixNanos,
142 ) -> Self {
143 Self {
144 chain,
145 dex,
146 instrument_id,
147 pool_identifier,
148 kind,
149 block,
150 block_hash: None,
151 transaction_hash,
152 transaction_index,
153 log_index,
154 sender,
155 owner,
156 position_liquidity,
157 amount0,
158 amount1,
159 tick_lower,
160 tick_upper,
161 ts_event,
162 ts_init,
163 }
164 }
165}
166
167impl Display for PoolLiquidityUpdate {
168 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
169 write!(
170 f,
171 "PoolLiquidityUpdate(instrument_id={}, kind={}, amount0={}, amount1={}, liquidity={})",
172 self.instrument_id, self.kind, self.amount0, self.amount1, self.position_liquidity
173 )
174 }
175}