Skip to main content

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}