tycho_common/simulation/swap.rs
1use std::{collections::HashMap, fmt, fmt::Debug, sync::Arc};
2
3use itertools::Itertools;
4use num_bigint::BigUint;
5
6use crate::{
7 dto::ProtocolStateDelta,
8 models::{protocol::ProtocolComponent, token::Token},
9 simulation::{
10 errors::{SimulationError, TransitionError},
11 indicatively_priced::IndicativelyPriced,
12 protocol_sim::{Balances, BlockContext, Price, ProtocolSim},
13 },
14 Bytes,
15};
16
17/// Result type for swap simulation operations that may fail with a `SimulationError`.
18pub type SimulationResult<T> = Result<T, SimulationError>;
19
20/// Type alias for token addresses, represented as raw bytes.
21pub type TokenAddress = Bytes;
22
23/// Macro that generates parameter structs with embedded blockchain context.
24///
25/// This macro creates structs that automatically include a `Context` field and provides
26/// methods for managing blockchain context (block number and timestamp). All parameter
27/// structs used in swap simulations should be created with this macro to ensure consistent
28/// context handling.
29///
30/// # Generated Methods
31/// - `with_context(context: Context) -> Self` - Sets the blockchain context
32/// - `context() -> &Context` - Gets a reference to the current context
33///
34/// # Example
35/// ```rust
36/// params_with_context! {
37/// pub struct MyParams {
38/// token: TokenAddress,
39/// amount: BigUint,
40/// }
41/// }
42/// ```
43macro_rules! params_with_context {
44 (
45 $(#[$meta:meta])*
46 $vis:vis struct $name:ident $(<$($gen:tt),*>)? {
47 $($field:ident: $ty:ty),* $(,)?
48 }
49 ) => {
50 $(#[$meta])*
51 #[derive(Debug, Clone)]
52 $vis struct $name $(<$($gen),*>)? {
53 context: Context,
54 $($field: $ty,)*
55 }
56
57 impl $(<$($gen),*>)? $name $(<$($gen),*>)? {
58
59 pub fn with_context(mut self, context: Context) -> Self {
60 self.context = context;
61 self
62 }
63
64 pub fn context(&self) -> &Context {
65 &self.context
66 }
67 }
68 };
69}
70
71/// Blockchain context information used in swap simulations.
72///
73/// Carries the block a quote is expected to execute in. `None` means the caller did not state one,
74/// and time-sensitive protocols fall back to whatever the state was last pointed at.
75#[derive(Debug, Clone, Default)]
76pub struct Context {
77 block: Option<BlockContext>,
78}
79
80impl Context {
81 /// Targets the quote at `block`.
82 pub fn with_block(mut self, block: BlockContext) -> Self {
83 self.block = Some(block);
84 self
85 }
86
87 /// The block a quote is expected to execute in, if the caller stated one.
88 pub fn block(&self) -> Option<&BlockContext> {
89 self.block.as_ref()
90 }
91}
92
93params_with_context! {
94/// Parameters for requesting a swap quote from a pool.
95///
96/// Contains the tokens to swap between, the input amount, and whether the
97/// simulation should return a modified state to reflect the swap execution.
98pub struct QuoteParams<'a>{
99 token_in: &'a TokenAddress,
100 token_out: &'a TokenAddress,
101 amount: QuoteAmount,
102 return_new_state: bool,
103 }
104}
105
106#[derive(Debug, Clone)]
107pub enum QuoteAmount {
108 FixedIn(BigUint),
109 FixedOut(BigUint),
110}
111
112impl<'a> QuoteParams<'a> {
113 /// Creates new fixed input parameters with default settings (no state modification).
114 ///
115 /// # Arguments
116 /// * `token_in` - The token to sell
117 /// * `token_out` - The token to buy
118 /// * `amount` - The amount of input token to sell
119 pub fn fixed_in(
120 token_in: &'a TokenAddress,
121 token_out: &'a TokenAddress,
122 amount: BigUint,
123 ) -> SimulationResult<Self> {
124 if token_out == token_in {
125 return Err(SimulationError::InvalidInput(
126 "Quote tokens have to differ!".to_string(),
127 None,
128 ));
129 }
130 Ok(Self {
131 context: Context::default(),
132 token_in,
133 token_out,
134 amount: QuoteAmount::FixedIn(amount),
135 return_new_state: false,
136 })
137 }
138
139 /// Creates new fixed output parameters with default settings (no state modification).
140 ///
141 /// # Arguments
142 /// * `token_in` - The token to sell
143 /// * `token_out` - The token to buy
144 /// * `amount` - The amount of output token to buy
145 pub fn fixed_out(
146 token_in: &'a TokenAddress,
147 token_out: &'a TokenAddress,
148 amount: BigUint,
149 ) -> SimulationResult<Self> {
150 if token_out == token_in {
151 return Err(SimulationError::InvalidInput(
152 "Quote tokens have to differ!".to_string(),
153 None,
154 ));
155 }
156
157 Ok(Self {
158 context: Context::default(),
159 token_in,
160 token_out,
161 amount: QuoteAmount::FixedOut(amount),
162 return_new_state: false,
163 })
164 }
165
166 pub fn amount(&self) -> &QuoteAmount {
167 &self.amount
168 }
169
170 /// Configures the quote to modify the state during simulation.
171 ///
172 /// When enabled, the quote simulation will return an updated state
173 /// as if the swap was actually executed.
174 pub fn with_new_state(mut self) -> Self {
175 self.return_new_state = true;
176 self
177 }
178
179 /// Returns the input token address.
180 pub fn token_in(&self) -> &TokenAddress {
181 self.token_in
182 }
183
184 /// Returns the output token address.
185 pub fn token_out(&self) -> &TokenAddress {
186 self.token_out
187 }
188
189 /// Returns whether the simulation should return the post-swap state.
190 pub fn should_return_new_state(&self) -> bool {
191 self.return_new_state
192 }
193}
194
195params_with_context! {
196/// Parameters for querying swap limits from a pool.
197///
198/// Used to determine the minimum and maximum amounts that can be traded
199/// between two tokens in the pool.
200pub struct LimitsParams<'a> {
201 token_in: &'a TokenAddress,
202 token_out: &'a TokenAddress,
203}
204}
205
206impl<'a> LimitsParams<'a> {
207 /// Creates new parameters for querying swap limits.
208 ///
209 /// # Arguments
210 /// * `token_in` - The input token address
211 /// * `token_out` - The output token address
212 pub fn new(token_in: &'a TokenAddress, token_out: &'a TokenAddress) -> Self {
213 Self { context: Context::default(), token_in, token_out }
214 }
215
216 pub fn token_in(&self) -> &TokenAddress {
217 self.token_in
218 }
219
220 pub fn token_out(&self) -> &TokenAddress {
221 self.token_out
222 }
223}
224
225params_with_context! {
226/// Parameters for querying the spot price between two tokens.
227///
228/// Used to get the current marginal price for infinitesimally small trades
229/// between two tokens in a pool.
230pub struct MarginalPriceParams<'a> {
231 token_in: &'a TokenAddress,
232 token_out: &'a TokenAddress,
233}
234}
235
236impl<'a> MarginalPriceParams<'a> {
237 /// Creates new parameters for querying marginal price.
238 ///
239 /// # Arguments
240 /// * `token_in` - The input token address
241 /// * `token_out` - The output token address
242 pub fn new(token_in: &'a TokenAddress, token_out: &'a TokenAddress) -> Self {
243 Self { context: Context::default(), token_in, token_out }
244 }
245 pub fn token_in(&self) -> &TokenAddress {
246 self.token_in
247 }
248
249 pub fn token_out(&self) -> &TokenAddress {
250 self.token_out
251 }
252}
253
254/// Represents a swap fee as a fraction.
255///
256/// The fee is typically expressed as a decimal (e.g., 0.003 for 0.3%).
257pub struct SwapFee {
258 fee: f64,
259}
260
261impl SwapFee {
262 /// Creates a new swap fee.
263 ///
264 /// # Arguments
265 /// * `fee` - The fee as a decimal fraction (e.g., 0.003 for 0.3%)
266 pub fn new(fee: f64) -> Self {
267 Self { fee }
268 }
269
270 /// Returns the fee as a decimal fraction.
271 pub fn fee(&self) -> f64 {
272 self.fee
273 }
274}
275
276/// Represents the marginal price at which the next infinitesimal trade would execute.
277///
278/// This is the instantaneous price for very small trades at the current pool state,
279/// often different from the effective price of larger trades due to slippage.
280pub struct MarginalPrice {
281 price: f64,
282}
283
284impl MarginalPrice {
285 /// Creates a new marginal price.
286 ///
287 /// # Arguments
288 /// * `price` - The marginal price as token_out/token_in ratio
289 pub fn new(price: f64) -> Self {
290 Self { price }
291 }
292
293 /// Returns the marginal price value.
294 pub fn price(&self) -> f64 {
295 self.price
296 }
297}
298
299/// Result of a swap quote calculation.
300///
301/// Contains the expected output amount, gas cost, and optionally the new pool state
302/// if the quote was requested with state modification enabled.
303pub struct Quote {
304 amount_out: BigUint,
305 gas: BigUint,
306 new_state: Option<Arc<dyn SwapQuoter>>,
307}
308
309impl Quote {
310 /// Creates a new quote result.
311 ///
312 /// # Arguments
313 /// * `amount_out` - The amount of output tokens that would be received
314 /// * `gas` - The estimated gas cost for executing this swap, excluding token transfers cost
315 /// * `new_state` - The new pool state after the swap (if state modification was requested)
316 pub fn new(amount_out: BigUint, gas: BigUint, new_state: Option<Arc<dyn SwapQuoter>>) -> Self {
317 Self { amount_out, gas, new_state }
318 }
319
320 /// Returns the amount of output tokens.
321 pub fn amount_out(&self) -> &BigUint {
322 &self.amount_out
323 }
324
325 /// Returns the estimated swap gas cost excluding including token transfer cost.
326 pub fn gas(&self) -> &BigUint {
327 &self.gas
328 }
329
330 /// Returns the new pool state after the swap, if available.
331 pub fn new_state(&self) -> Option<Arc<dyn SwapQuoter>> {
332 self.new_state.clone()
333 }
334}
335
336/// Represents a numeric range with lower and upper bounds.
337///
338/// Used for specifying trading limits and constraints.
339pub struct Range {
340 lower: BigUint,
341 upper: BigUint,
342}
343
344impl Range {
345 /// Creates a new range with validation.
346 ///
347 /// # Arguments
348 /// * `lower` - The lower bound (must be <= upper)
349 /// * `upper` - The upper bound (must be >= lower)
350 ///
351 /// # Errors
352 /// Returns `SimulationError::InvalidInput` if lower > upper.
353 pub fn new(lower: BigUint, upper: BigUint) -> SimulationResult<Self> {
354 if lower > upper {
355 return Err(SimulationError::InvalidInput(
356 "Invalid range! Argument lower > upper".to_string(),
357 None,
358 ));
359 }
360 Ok(Self { lower, upper })
361 }
362
363 /// Returns the lower bound.
364 pub fn lower(&self) -> &BigUint {
365 &self.lower
366 }
367
368 /// Returns the upper bound.
369 pub fn upper(&self) -> &BigUint {
370 &self.upper
371 }
372}
373
374/// Defines the trading limits for input and output amounts in a swap.
375///
376/// Specifies the minimum and maximum amounts that can be traded through a pool
377/// for both input and output tokens.
378pub struct SwapLimits {
379 range_in: Range,
380 range_out: Range,
381}
382
383impl SwapLimits {
384 /// Creates new swap limits.
385 ///
386 /// # Arguments
387 /// * `range_in` - The valid range for input token amounts
388 /// * `range_out` - The valid range for output token amounts
389 pub fn new(range_in: Range, range_out: Range) -> Self {
390 Self { range_in, range_out }
391 }
392
393 /// Returns the input amount limits.
394 pub fn range_in(&self) -> &Range {
395 &self.range_in
396 }
397
398 /// Returns the output amount limits.
399 pub fn range_out(&self) -> &Range {
400 &self.range_out
401 }
402}
403
404params_with_context! {
405/// Parameters for applying protocol state transitions.
406///
407/// Contains the state delta and associated data needed to transition
408/// a pool's state in response to blockchain events.
409pub struct TransitionParams<'a> {
410 delta: ProtocolStateDelta,
411 tokens: &'a HashMap<Bytes, Token>,
412 balances: &'a Balances,
413 }
414}
415
416impl<'a> TransitionParams<'a> {
417 /// Creates new parameters for state transition.
418 ///
419 /// # Arguments
420 /// * `delta` - The protocol state change to apply
421 /// * `tokens` - Map of token addresses to token metadata
422 /// * `balances` - Current token balances in the system
423 pub fn new(
424 delta: ProtocolStateDelta,
425 tokens: &'a HashMap<Bytes, Token>,
426 balances: &'a Balances,
427 ) -> Self {
428 Self { context: Context::default(), delta, tokens, balances }
429 }
430
431 pub fn delta(&self) -> &ProtocolStateDelta {
432 &self.delta
433 }
434
435 pub fn tokens(&self) -> &HashMap<Bytes, Token> {
436 self.tokens
437 }
438
439 pub fn balances(&self) -> &Balances {
440 self.balances
441 }
442}
443
444/// Result of applying a state transition to a pool.
445///
446/// Currently, a placeholder struct that may be extended in the future
447/// to contain transition metadata or validation results.
448pub struct Transition {}
449
450impl Default for Transition {
451 /// Creates a new transition result.
452 fn default() -> Self {
453 Self {}
454 }
455}
456
457/// Defines constraints for advanced quote calculations.
458///
459/// These constraints allow sophisticated trading strategies by limiting swaps
460/// based on price thresholds or targeting specific pool states.
461#[derive(Debug, Clone, PartialEq)]
462pub enum SwapConstraint {
463 /// This mode will calculate the maximum trade that this pool can execute while respecting a
464 /// trade limit price.
465 #[non_exhaustive]
466 TradeLimitPrice {
467 /// The minimum acceptable price for the resulting trade, as a [Price] struct. The
468 /// resulting amount_out / amount_in must be >= trade_limit_price
469 limit: Price,
470 /// The tolerance as a fraction to be applied on top of (increasing) the trade
471 /// limit price, raising the acceptance threshold. This is used to loosen the acceptance
472 /// criteria for implementations of this method, but will never allow violating the trade
473 /// limit price itself.
474 tolerance: f64,
475 /// The minimum amount of token_in that must be used for this trade.
476 min_amount_in: Option<BigUint>,
477 /// The maximum amount of token_in that can be used for this trade.
478 max_amount_in: Option<BigUint>,
479 },
480
481 /// This mode will calculate the amount of token_in required to move the pool's marginal price
482 /// down to a target price, and the amount of token_out received.
483 ///
484 /// # Edge Cases and Limitations
485 ///
486 /// Computing the exact amount to move a pool's marginal price to a target has several
487 /// challenges:
488 /// - The definition of marginal price varies between protocols. It is usually not an attribute
489 /// of the pool but a consequence of its liquidity distribution and current state.
490 /// - For protocols with concentrated liquidity, the marginal price is discrete, meaning we
491 /// can't always find an exact trade amount to reach the target price.
492 /// - Not all protocols support analytical solutions for this problem, requiring numerical
493 /// methods.
494 #[non_exhaustive]
495 PoolTargetPrice {
496 /// The marginal price we want the pool to be after the trade, as a [Price] struct. The
497 /// pool's price will move down to this level as token_in is sold into it
498 target: Price,
499 /// The tolerance as a fraction of the resulting pool marginal price. After trading, the
500 /// pool's price will decrease to the interval `[target, target * (1 +
501 /// tolerance)]`.
502 tolerance: f64,
503 /// The lower bound for searching algorithms.
504 min_amount_in: Option<BigUint>,
505 /// The upper bound for searching algorithms.
506 max_amount_in: Option<BigUint>,
507 },
508}
509
510impl SwapConstraint {
511 /// Creates a trade limit price constraint.
512 ///
513 /// This constraint finds the maximum trade size while respecting a minimum price
514 /// threshold. See `SwapConstraint::TradeLimitPrice` for details.
515 ///
516 /// # Arguments
517 /// * `limit` - The minimum acceptable price for the trade
518 /// * `tolerance` - Additional tolerance as a fraction to loosen the constraint
519 pub fn trade_limit_price(limit: Price, tolerance: f64) -> Self {
520 SwapConstraint::TradeLimitPrice {
521 limit,
522 tolerance,
523 min_amount_in: None,
524 max_amount_in: None,
525 }
526 }
527
528 /// Creates a pool target price constraint.
529 ///
530 /// This constraint calculates the trade needed to move the pool's price to a
531 /// target level. See `SwapConstraint::PoolTargetPrice` for details.`
532 ///
533 /// # Arguments
534 /// * `target` - The desired final marginal price of the pool
535 /// * `tolerance` - Acceptable variance from the target price as a fraction
536 pub fn pool_target_price(target: Price, tolerance: f64) -> Self {
537 SwapConstraint::PoolTargetPrice {
538 target,
539 tolerance,
540 min_amount_in: None,
541 max_amount_in: None,
542 }
543 }
544
545 /// Adds a lower bound to the constraint's search range.
546 ///
547 /// # Arguments
548 /// * `lower` - The minimum amount_in to consider
549 ///
550 /// # Returns
551 /// The modified constraint with the lower bound applied.
552 #[expect(
553 clippy::unnecessary_wraps,
554 reason = "public API; changing the signature is a breaking change"
555 )]
556 pub fn with_lower_bound(mut self, lower: BigUint) -> SimulationResult<Self> {
557 match &mut self {
558 SwapConstraint::PoolTargetPrice { min_amount_in, .. } => {
559 *min_amount_in = Some(lower);
560 Ok(self)
561 }
562 SwapConstraint::TradeLimitPrice { min_amount_in, .. } => {
563 *min_amount_in = Some(lower);
564 Ok(self)
565 }
566 }
567 }
568
569 /// Adds an upper bound to the constraint's search range.
570 ///
571 /// # Arguments
572 /// * `upper` - The maximum amount_in to consider
573 ///
574 /// # Returns
575 /// The modified constraint with the upper bound applied.
576 #[expect(
577 clippy::unnecessary_wraps,
578 reason = "public API; changing the signature is a breaking change"
579 )]
580 pub fn with_upper_bound(mut self, upper: BigUint) -> SimulationResult<Self> {
581 match &mut self {
582 SwapConstraint::PoolTargetPrice { max_amount_in, .. } => {
583 *max_amount_in = Some(upper);
584 Ok(self)
585 }
586 SwapConstraint::TradeLimitPrice { max_amount_in, .. } => {
587 *max_amount_in = Some(upper);
588 Ok(self)
589 }
590 }
591 }
592}
593
594params_with_context! {
595/// Parameters for advanced swap queries with constraints.
596///
597/// Used for sophisticated swap calculations that respect price limits or target
598/// prices instead of given amount values.
599pub struct QuerySwapParams<'a> {
600 token_in: &'a TokenAddress,
601 token_out: &'a TokenAddress,
602 swap_constraint: SwapConstraint,
603}
604}
605
606impl<'a> QuerySwapParams<'a> {
607 /// Creates new parameters for constrained swap queries.
608 ///
609 /// # Arguments
610 /// * `token_in` - The input token address
611 /// * `token_out` - The output token metadata
612 /// * `swap_constraint` - The constraint to apply to the swap calculation
613 pub fn new(
614 token_in: &'a TokenAddress,
615 token_out: &'a TokenAddress,
616 swap_constraint: SwapConstraint,
617 ) -> Self {
618 Self { context: Context::default(), token_in, token_out, swap_constraint }
619 }
620
621 pub fn token_in(&self) -> &'a TokenAddress {
622 self.token_in
623 }
624
625 pub fn token_out(&self) -> &'a TokenAddress {
626 self.token_out
627 }
628
629 pub fn swap_constraint(&self) -> &SwapConstraint {
630 &self.swap_constraint
631 }
632}
633
634/// Result of an advanced swap calculation with constraints.
635///
636/// Contains the calculated swap amounts, optionally the new pool state,
637/// and price points traversed during calculation for optimization purposes.
638pub struct Swap {
639 /// The amount of token_in sold to the component
640 amount_in: BigUint,
641 /// The amount of token_out bought from the component
642 amount_out: BigUint,
643 /// The new state of the component after the swap
644 new_state: Option<Arc<dyn SwapQuoter>>,
645 /// Optional price points that the pool was transitioned through while computing this swap.
646 /// The values are tuples of (amount_in, amount_out, price). This is useful for repeated calls
647 /// by providing good bounds for the next call.
648 price_points: Option<Vec<PricePoint>>,
649}
650
651/// A point on the AMM price curve.
652///
653/// Collected during iterative numerical search algorithms.
654/// These points can be reused as bounds for subsequent searches, improving convergence speed.
655#[derive(Debug, Clone)]
656pub struct PricePoint {
657 /// The amount of token_in in atomic units (wei).
658 amount_in: BigUint,
659 /// The amount of token_out in atomic units (wei).
660 amount_out: BigUint,
661 /// The price in units of `[token_out/token_in]` scaled by decimals.
662 ///
663 /// Computed as `(amount_out / 10^token_out_decimals) / (amount_in / 10^token_in_decimals)`.
664 price: f64,
665}
666
667impl PricePoint {
668 pub fn amount_in(&self) -> &BigUint {
669 &self.amount_in
670 }
671
672 pub fn amount_out(&self) -> &BigUint {
673 &self.amount_out
674 }
675
676 pub fn price(&self) -> f64 {
677 self.price
678 }
679}
680
681impl Swap {
682 /// Creates a new swap result.
683 ///
684 /// # Arguments
685 /// * `amount_in` - The amount of input tokens used
686 /// * `amount_out` - The amount of output tokens received
687 /// * `new_state` - The new pool state after the swap (if calculated)
688 /// * `price_points` - Optional price trajectory data for optimization
689 pub fn new(
690 amount_in: BigUint,
691 amount_out: BigUint,
692 new_state: Option<Arc<dyn SwapQuoter>>,
693 price_points: Option<Vec<PricePoint>>,
694 ) -> Self {
695 Self { amount_in, amount_out, new_state, price_points }
696 }
697
698 /// Returns the amount of input tokens used.
699 pub fn amount_in(&self) -> &BigUint {
700 &self.amount_in
701 }
702
703 /// Returns the amount of output tokens received.
704 pub fn amount_out(&self) -> &BigUint {
705 &self.amount_out
706 }
707
708 /// Returns the new pool state after the swap, if calculated.
709 pub fn new_state(&self) -> Option<Arc<dyn SwapQuoter>> {
710 self.new_state.clone()
711 }
712
713 /// Returns the price points traversed during calculation.
714 ///
715 /// Each tuple contains (amount_in, amount_out, price) at various points
716 /// during the swap calculation, useful for optimizing subsequent calls.
717 #[expect(
718 clippy::ref_option,
719 reason = "public API; changing the signature is a breaking change"
720 )]
721 pub fn price_points(&self) -> &Option<Vec<PricePoint>> {
722 &self.price_points
723 }
724}
725
726/// Core trait for implementing swap quote functionality.
727///
728/// This trait defines the interface that all liquidity sources must implement
729/// to participate in swap quotes. It provides methods for price discovery,
730/// quote calculation, state transitions, and advanced swap queries.
731///
732/// Implementations should be thread-safe and support cloning for parallel simulations.
733#[typetag::serde(tag = "protocol", content = "state")]
734pub trait SwapQuoter: fmt::Debug + Send + Sync + 'static {
735 /// Returns the [`ProtocolComponent`] describing the protocol instance this quoter
736 /// is associated with.
737 ///
738 /// The component provides **structural and descriptive metadata** about the protocol,
739 /// such as the set of involved tokens and protocol-specific configuration, but does not
740 /// represent a mutable simulation state.
741 ///
742 /// # Semantics
743 ///
744 /// - The returned component is expected to be **stable for the lifetime of the quoter**.
745 /// - Multiple quoter instances may share the same component instance; callers should not assume
746 /// unique ownership (e.g. quoter instances may represent the state at different points in
747 /// time)
748 /// - The component is used for discovery and introspection (e.g. determining supported tokens
749 /// or deriving default quotable pairs), not for executing swaps.
750 ///
751 /// # Ownership
752 ///
753 /// This method returns an `Arc` to allow cheap cloning and shared access without
754 /// constraining the internal storage strategy of the implementation.
755 ///
756 /// # Intended use
757 ///
758 /// Typical uses include:
759 /// - Inspecting the tokens and configuration exposed by the protocol
760 /// - Deriving default [`quotable_pairs`](Self::quotable_pairs)
761 /// - Identifying or grouping quoters by protocol metadata
762 fn component(&self) -> Arc<ProtocolComponent<Arc<Token>>>;
763
764 /// Returns the set of **directed token pairs** for which this quoter can produce swap quotes.
765 ///
766 /// Each `(base, quote)` pair indicates that a swap from `base` to `quote` is supported.
767 /// Direction matters: `(A, B)` and `(B, A)` are considered distinct pairs and might not
768 /// both be present.
769 ///
770 /// # Semantics
771 ///
772 /// - The returned set represents **capability**, not liquidity or pricing guarantees. A pair
773 /// being present does not imply that a quote will be favorable or even currently executable,
774 /// only that the quoter understands how to price it.
775 /// - The set may be **computed dynamically** and is not required to be stable across calls,
776 /// though most implementations are expected to return the same result unless the underlying
777 /// protocol configuration changes.
778 ///
779 /// # Default behavior
780 ///
781 /// The default implementation derives the pairs from the tokens exposed by
782 /// [`component()`](Self::component), returning all ordered pairs `(a, b)` where `a != b`.
783 /// Protocols with restricted or asymmetric support (e.g. RFQ-based or single-sided
784 /// designs) should override this method.
785 ///
786 ///
787 /// # Intended use
788 ///
789 /// This method is primarily intended for routing, discovery, and validation logic,
790 /// allowing callers to determine whether a quote request is meaningful before invoking
791 /// [`quote()`](Self::quote).
792 fn quotable_pairs(&self) -> Vec<(Arc<Token>, Arc<Token>)> {
793 let component = self.component();
794 component
795 .tokens
796 .iter()
797 .permutations(2)
798 .map(|token| (token[0].clone(), token[1].clone()))
799 .collect()
800 }
801
802 /// Computes the protocol fee applicable to a prospective swap described by `params`.
803 ///
804 /// This method evaluates the fee that would be charged by the protocol for the given
805 /// swap parameters, without performing the swap or mutating any internal state.
806 ///
807 /// # Semantics
808 ///
809 /// - The returned [`SwapFee`] represents the **protocol-defined fee component** of the swap
810 /// (e.g. LP fee, protocol fee, or RFQ spread), as understood by this quoter.
811 /// - Fee computation is **pure and side-effect free**; calling this method must not modify the
812 /// internal state of the quoter.
813 /// - The fee may depend on the full set of quote parameters (including direction, amount, or
814 /// other protocol-specific inputs).
815 ///
816 /// # Relation to quoting
817 ///
818 /// Implementations may internally reuse logic from [`quote()`](Self::quote), but this method
819 /// exists to allow callers to:
820 /// - Inspect or decompose pricing components
821 /// - Perform fee-aware routing or optimization
822 /// - Estimate costs without requesting a full quote
823 ///
824 /// # Errors
825 ///
826 /// Returns an error if the fee cannot be determined for the given parameters (e.g. the
827 /// pair is not quotable or required inputs are missing)
828 fn fee(&self, params: QuoteParams) -> SimulationResult<SwapFee>;
829
830 /// Computes the **marginal (infinitesimal) price** for a swap described by `params`,
831 /// with **all protocol fees included**.
832 ///
833 /// The marginal price represents the instantaneous exchange rate at the current
834 /// protocol state, evaluated at an infinitesimally small trade size. It reflects the
835 /// derivative of output amount with respect to input amount for the specified swap
836 /// direction, inclusive of any protocol-defined fees or spreads.
837 ///
838 /// # Semantics
839 ///
840 /// - Fees are **always included** in the returned [`MarginalPrice`].
841 /// - The price is evaluated **at the margin** and does not represent an executable price for a
842 /// finite trade.
843 /// - This method is **pure and side-effect free**; it must not mutate internal state.
844 /// - For sufficiently small trade sizes, the marginal price should be consistent with
845 /// [`quote()`](Self::quote), up to numerical precision.
846 ///
847 /// # Use cases
848 ///
849 /// Typical uses include:
850 /// - Price display and monitoring
851 /// - Slippage estimation and sensitivity analysis
852 /// - Routing heuristics and initial path selection
853 ///
854 /// # Errors
855 ///
856 /// Returns an error if the marginal price is undefined or cannot be computed for the
857 /// given parameters (e.g. unsupported pair, zero liquidity, or missing inputs).
858 fn marginal_price(&self, params: MarginalPriceParams) -> SimulationResult<MarginalPrice>;
859
860 /// Produces a swap quote for the trade described by `params`, with **all protocol fees
861 /// included**.
862 ///
863 /// The returned [`Quote`] represents the effective execution terms of the swap as
864 /// understood by this quoter, including any protocol-defined fees, spreads, or
865 /// adjustments. Calling this method does not perform the swap and does not mutate
866 /// internal state.
867 ///
868 /// # Semantics
869 ///
870 /// - Fees are **always included** in the quoted price and amounts. Callers should not apply
871 /// additional protocol fees on top of the returned quote.
872 /// - Fees mentioned above **do not include** chain fees such as gas costs.
873 /// - The quote reflects a **finite-size trade** and therefore accounts for price impact where
874 /// applicable.
875 /// - This method is **pure and side-effect free**; it must not mutate internal state.
876 /// - For sufficiently small trade sizes, the quote should be consistent with
877 /// [`marginal_price()`](Self::marginal_price), up to numerical precision.
878 ///
879 /// # Intended use
880 ///
881 /// This method is the primary entry point for consumers of [`SwapQuoter`] and is
882 /// intended for:
883 /// - User-facing price discovery
884 /// - Routing and optimization across multiple quoters
885 /// - Simulation and what-if analysis
886 ///
887 /// # Errors
888 ///
889 /// Returns an error if a quote cannot be produced for the given parameters (e.g. the
890 /// pair is not quotable, required inputs are missing, or the quote is undefined).
891 fn quote(&self, params: QuoteParams) -> SimulationResult<Quote>;
892
893 /// Returns the valid execution limits for a prospective quote
894 ///
895 /// The returned [`SwapLimits`] describes the bounds within which a swap can be quoted or
896 /// simulated, such as minimum and maximum input or output amounts, given the current
897 /// protocol state.
898 ///
899 /// # Semantics
900 ///
901 /// - Limits are evaluated **at the current state** of the quoter and do not imply that a quote
902 /// will succeed outside the returned bounds.
903 /// - The limits may depend on swap direction, fees, liquidity constraints, or protocol-specific
904 /// rules.
905 /// - This method is **pure and side-effect free**; it must not mutate internal state.
906 /// - Limits are expressed in **fee-inclusive terms**, consistent with [`quote()`](Self::quote)
907 /// and [`marginal_price()`](Self::marginal_price).
908 ///
909 /// # Intended use
910 ///
911 /// Typical uses include:
912 /// - Pre-validating quote requests before quoting
913 /// - Bounding search spaces for routing and optimization
914 /// - UI validation and input clamping
915 ///
916 /// # Errors
917 ///
918 /// Returns an error if limits cannot be determined for the given parameters (e.g. the
919 /// pair is not quotable or required inputs are missing).
920 fn swap_limits(&self, params: LimitsParams) -> SimulationResult<SwapLimits>;
921
922 /// Produces an **advanced, price-constraint-based quote**
923 ///
924 /// Unlike [`quote()`](Self::quote), which prices a swap for a fixed input or output amount,
925 /// `query_swap` solves for a swap that satisfies a higher-level [`SwapConstraint`],
926 /// such as a minimum execution price or a target post-trade pool price.
927 ///
928 /// The returned [`Swap`] describes the swap that best satisfies the given constraint
929 /// under the current protocol state, with **all protocol fees included**.
930 ///
931 /// # Semantics
932 ///
933 /// - The method is **read-only** and does not mutate internal state.
934 /// - All amounts and prices in the returned [`Swap`] are **fee-inclusive**, consistent with
935 /// [`quote()`](Self::quote) and [`marginal_price()`](Self::marginal_price).
936 /// - The constraint defines *what is solved for* (e.g. maximum trade size, target price),
937 /// rather than supplying an explicit trade amount.
938 /// - Implementations may use analytical or numerical methods to satisfy the constraint, subject
939 /// to the provided tolerances and bounds.
940 ///
941 /// # Supported constraints
942 ///
943 /// The behavior of this method is defined by the [`SwapConstraint`] provided in
944 /// `params`, including:
945 ///
946 /// - **Trade limit price**: computes the maximum executable trade size whose effective price
947 /// (amount_out / amount_in) meets or exceeds a specified limit.
948 /// - **Pool target price**: computes the trade required to move the pool’s marginal price down
949 /// to a target level, within a specified tolerance.
950 ///
951 /// Bounds on the search space (minimum and maximum `amount_in`) are respected when
952 /// provided.
953 ///
954 /// # Intended use
955 ///
956 /// Typical uses include:
957 /// - Price-impact-aware execution planning
958 /// - Strategy-driven routing (e.g. price-capped or price-targeting trades)
959 /// - Liquidity probing and pool sensitivity analysis
960 ///
961 /// # Errors
962 ///
963 /// Returns an error if:
964 /// - The constraint cannot be satisfied within the provided bounds or tolerances
965 /// - The token pair is not quotable
966 /// - The swap is undefined under the current protocol state
967 fn query_swap(&self, params: QuerySwapParams) -> SimulationResult<Swap>;
968
969 /// Applies a **protocol state delta**
970 ///
971 /// This method updates the internal protocol state of the quoter by applying the
972 /// incremental changes described by `params`, typically derived from an external
973 /// indexer or on-chain data source. It is used to keep the quoter’s local view of the
974 /// protocol state in sync with the latest block.
975 ///
976 /// # Semantics
977 ///
978 /// - The provided delta is assumed to represent a **valid, externally observed state
979 /// transition** (e.g. from an indexer service) and is not re-validated as a swap.
980 /// - Calling this method **mutates internal state**; all subsequent quotes, prices, and limits
981 /// will reflect the updated state.
982 /// - The transition is applied **incrementally** and is expected to be composable with previous
983 /// deltas.
984 ///
985 /// # Intended use
986 ///
987 /// Typical uses include:
988 /// - Applying per-block protocol updates received from an indexer
989 /// - Advancing local state during historical replay or backfilling
990 /// - Keeping multiple quoters synchronized with chain state
991 ///
992 /// # Errors
993 ///
994 /// Returns an error if the delta cannot be applied to the current state (e.g. it is
995 /// incompatible, malformed, or violates protocol invariants).
996 fn delta_transition(&mut self, params: TransitionParams)
997 -> Result<Transition, TransitionError>;
998
999 /// Clones the protocol state as a trait object.
1000 ///
1001 /// This method enables cloning when the pool is used as a boxed trait object,
1002 /// which is necessary for parallel simulations and state management.
1003 ///
1004 /// # Returns
1005 /// A new boxed instance with the same state as this pool.
1006 fn clone_box(&self) -> Box<dyn SwapQuoter>;
1007
1008 /// Attempts to cast this pool to an indicatively priced pool.
1009 ///
1010 /// This is used for RFQ (Request for Quote) protocols that provide
1011 /// indicative pricing rather than deterministic calculations.
1012 ///
1013 /// # Returns
1014 /// A reference to the `IndicativelyPriced` implementation, or an error
1015 /// if this pool type doesn't support indicative pricing.
1016 ///
1017 /// # Default Implementation
1018 /// Returns an error indicating that indicative pricing is not supported.
1019 fn as_indicatively_priced(&self) -> Result<&dyn IndicativelyPriced, SimulationError> {
1020 Err(SimulationError::FatalError("Pool State does not implement IndicativelyPriced".into()))
1021 }
1022
1023 #[deprecated(note = "ProtocolSim is deprecated. This method will be removed in v1.0.0")]
1024 fn to_protocol_sim(&self) -> Box<dyn ProtocolSim>;
1025}
1026
1027/// Testing extension trait for SwapQuoter implementations.
1028///
1029/// Provides additional methods needed for testing and validation
1030/// that are not part of the main SwapQuoter interface.
1031#[cfg(test)]
1032pub trait SwapQuoterTestExt {
1033 /// Compares this pool state with another for equality.
1034 ///
1035 /// This method is used in tests to verify that pool states
1036 /// are equivalent after various operations.
1037 ///
1038 /// # Arguments
1039 /// * `other` - Another SwapQuoter to compare against
1040 ///
1041 /// # Returns
1042 /// `true` if the pool states are equivalent, `false` otherwise.
1043 fn eq(&self, other: &dyn SwapQuoter) -> bool;
1044}