tycho-simulation 0.527.5

Provides tools for interacting with protocol states, calculating spot prices, and quoting token swaps.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
use std::collections::HashMap;

use alloy::primitives::{address, Address};
use serde::{Deserialize, Serialize};
use tycho_common::{simulation::errors::SimulationError, Bytes};

use crate::evm::protocol::utils::slipstreams::observations::{Observations, ObserveError};

pub const ZERO_FEE_INDICATOR: u32 = 420;
/// The `secondsAgo` the dynamic fee modules are deployed with, and the one a config serialized
/// before it became per module takes. `SUPPORTED_DYNAMIC_FEE_MODULES` holds each module's own.
const DEFAULT_SECONDS_AGO: u32 = 600;
pub const MIN_SECONDS_AGO: u32 = 2;
pub const DEFAULT_SCALING_FACTOR: u64 = 0;
// The upgraded DynamicSwapFeeModule deployments use 30_000 as their default fee cap.
pub const DEFAULT_FEE_CAP: u32 = 30_000;
const SCALING_PRECISION: u128 = 1_000_000;
const DYNAMIC_FEE_MODULE_ATTRIBUTE: &str = "dynamic_fee_module";

/// A deployed fee module whose `getFee` `get_dynamic_fee` reproduces.
struct SupportedModule {
    address: Address,
    /// The module's `secondsAgo`: the TWAP window, which also sets the minimum observation
    /// cardinality (`secondsAgo / MIN_SECONDS_AGO`) below which the module adds no dynamic fee.
    /// A snapshot of state the swap fee manager can change with `setSecondsAgo`, which emits
    /// `SecondsAgoSet`; nothing indexes it, so a change needs a code change here.
    seconds_ago: u32,
}

const SUPPORTED_DYNAMIC_FEE_MODULES: [SupportedModule; 4] = [
    // The three Base modules moved from 600 to 480 in block 52,307,488, tx
    // 0x42122c80d854f0f4705f0f93d2a16c4d67a631d04359c50066328b47a2857550, and 0x87D8 again to 30
    // in block 53,228,614, tx 0x1aeb7f17c557c571a008797cc214f2d2c4d46d98fc3847855ac88f1889f92ae4.
    SupportedModule {
        address: address!("090b2A6bb475c00e2256e2095A60887cD710803b"),
        seconds_ago: 480,
    },
    SupportedModule {
        address: address!("F4Ecd78EBEB6d36CF7f80B5B6B41453515fe2785"),
        seconds_ago: 480,
    },
    SupportedModule {
        address: address!("87D8f999BBa9343E8099552426775B51C338E8CB"),
        seconds_ago: 30,
    },
    // UP on Robinhood Chain. Same module code as the Base deployments above, so the fee resolution
    // below applies unchanged; only its `factory` immutable and the name of its base-fee event
    // differ.
    SupportedModule {
        address: address!("a8Bdc945bE050E451C97f935d7c0D6B0087cF94c"),
        seconds_ago: 600,
    },
];

fn supported_dynamic_fee_module(fee_module: &[u8]) -> Option<&'static SupportedModule> {
    SUPPORTED_DYNAMIC_FEE_MODULES
        .iter()
        .find(|supported| supported.address.as_slice() == fee_module)
}

#[derive(Copy, Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct DynamicFeeConfig {
    base_fee: u32,
    fee_cap: u32,
    scaling_factor: u64,
    initial_fee_enabled: bool,
    initial_fee: u32,
    /// The pool's fee module's `secondsAgo`.
    #[serde(default = "default_seconds_ago")]
    seconds_ago: u32,
}

fn default_seconds_ago() -> u32 {
    DEFAULT_SECONDS_AGO
}

impl Default for DynamicFeeConfig {
    fn default() -> Self {
        Self::new(0, 0, 0, false, 0)
    }
}

impl DynamicFeeConfig {
    pub fn new(
        base_fee: u32,
        fee_cap: u32,
        scaling_factor: u64,
        initial_fee_enabled: bool,
        initial_fee: u32,
    ) -> Self {
        Self {
            base_fee,
            fee_cap,
            scaling_factor,
            initial_fee_enabled,
            initial_fee,
            seconds_ago: DEFAULT_SECONDS_AGO,
        }
    }

    /// The same config under a module whose `secondsAgo` is `seconds_ago`.
    #[cfg(test)]
    pub(crate) fn with_seconds_ago(self, seconds_ago: u32) -> Self {
        Self { seconds_ago, ..self }
    }

    /// Builds a config from a full snapshot's attributes.
    ///
    /// An absent or unsupported `dynamic_fee_module` marker yields the default config, whose
    /// `base_fee == 0` makes `get_dynamic_fee` fall back to the pool's static `default_fee`. Only
    /// errors when a supported marker is present but a dynamic-fee attribute is missing.
    pub(crate) fn from_attributes(attributes: &HashMap<String, Bytes>) -> Result<Self, String> {
        let Some(module) = attributes
            .get(DYNAMIC_FEE_MODULE_ATTRIBUTE)
            .and_then(|module| supported_dynamic_fee_module(module))
        else {
            return Ok(Self::default());
        };

        Ok(Self {
            base_fee: u32::try_from(
                attributes
                    .get("dfc_baseFee")
                    .ok_or("missing dynamic fee attribute `dfc_baseFee`")?
                    .clone(),
            )
            .map_err(|err| err.to_string())?,
            fee_cap: u32::try_from(
                attributes
                    .get("dfc_feeCap")
                    .ok_or("missing dynamic fee attribute `dfc_feeCap`")?
                    .clone(),
            )
            .map_err(|err| err.to_string())?,
            scaling_factor: u64::try_from(
                attributes
                    .get("dfc_scalingFactor")
                    .ok_or("missing dynamic fee attribute `dfc_scalingFactor`")?
                    .clone(),
            )
            .map_err(|err| err.to_string())?,
            initial_fee_enabled: attributes
                .get("dfc_initialFeeEnabled")
                .is_some_and(|value| value.iter().any(|byte| *byte != 0)),
            initial_fee: attributes
                .get("dfc_initialFee")
                .cloned()
                .map(u32::try_from)
                .transpose()
                .map_err(|err| err.to_string())?
                .unwrap_or_default(),
            seconds_ago: module.seconds_ago,
        })
    }

    /// Applies a delta's attribute updates.
    ///
    /// A delta carrying the `dynamic_fee_module` marker fully re-initializes the config; markerless
    /// deltas apply only the dynamic-fee fields they contain, leaving the rest untouched.
    pub(crate) fn update_from_attributes(
        &mut self,
        attributes: &HashMap<String, Bytes>,
    ) -> Result<(), String> {
        if attributes.contains_key(DYNAMIC_FEE_MODULE_ATTRIBUTE) {
            *self = Self::from_attributes(attributes)?;
            return Ok(());
        }

        if let Some(base_fee) = attributes.get("dfc_baseFee") {
            self.base_fee = u32::try_from(base_fee.clone()).map_err(|err| err.to_string())?;
        }
        if let Some(fee_cap) = attributes.get("dfc_feeCap") {
            self.fee_cap = u32::try_from(fee_cap.clone()).map_err(|err| err.to_string())?;
        }
        if let Some(scaling_factor) = attributes.get("dfc_scalingFactor") {
            self.scaling_factor =
                u64::try_from(scaling_factor.clone()).map_err(|err| err.to_string())?;
        }
        if let Some(initial_fee_enabled) = attributes.get("dfc_initialFeeEnabled") {
            self.initial_fee_enabled = initial_fee_enabled
                .iter()
                .any(|byte| *byte != 0);
        }
        if let Some(initial_fee) = attributes.get("dfc_initialFee") {
            self.initial_fee = u32::try_from(initial_fee.clone()).map_err(|err| err.to_string())?;
        }
        Ok(())
    }

    pub fn scaling_factor(&self) -> u64 {
        self.scaling_factor
    }

    /// The scaling factor and fee cap the module prices with: the pool's own once it has set a
    /// scaling factor, the module defaults otherwise.
    fn scaling(&self) -> (u64, u32) {
        if self.scaling_factor != 0 {
            (self.scaling_factor, self.fee_cap)
        } else {
            (DEFAULT_SCALING_FACTOR, DEFAULT_FEE_CAP)
        }
    }
}

/// A resolved swap fee, in pips, plus whether resolving it required a TWAP `observe`.
///
/// Under the first-in-block assumption the module short-circuits to the initial fee before
/// touching the oracle, so such a swap does not pay for the observation reads either. Under the
/// worst-case default the oracle read is charged whenever the dynamic branch evaluated it, even
/// when the initial fee wins the max — conservative on both fee and gas.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub struct ResolvedFee {
    pub(crate) fee: u32,
    pub(crate) observed_twap: bool,
}

impl ResolvedFee {
    fn flat(fee: u32) -> Self {
        Self { fee, observed_twap: false }
    }
}

/// Resolves the fee a swap executing at `execution_timestamp` would pay.
///
/// When no observation has been written in the execution block yet, the swap's position within
/// the block is unknown: `assume_first_in_block` quotes the initial fee (betting the swap lands
/// before any other on the pool), while the default quotes the worse of the initial and dynamic
/// fees so the output is never over-quoted. Once the pool has been touched in the execution
/// block, position is a known fact and the flag has no effect.
#[expect(
    clippy::too_many_arguments,
    reason = "inputs mirror the on-chain dynamic fee module and pool state"
)]
pub fn get_dynamic_fee(
    dfc: &DynamicFeeConfig,
    default_base_fee: u32,
    current_tick: i32,
    liquidity: u128,
    observation_index: u16,
    observation_cardinality: u16,
    observations: &Observations,
    execution_timestamp: u32,
    assume_first_in_block: bool,
) -> Result<ResolvedFee, SimulationError> {
    if dfc.base_fee == ZERO_FEE_INDICATOR {
        return Ok(ResolvedFee::flat(0));
    }
    let base_fee = if dfc.base_fee != 0 { dfc.base_fee } else { default_base_fee };

    if dfc.initial_fee_enabled &&
        observations.timestamp_at(observation_index, observation_cardinality)? !=
            execution_timestamp
    {
        let initial = match dfc.initial_fee {
            0 => base_fee,
            ZERO_FEE_INDICATOR => 0,
            initial_fee => initial_fee,
        };
        if assume_first_in_block {
            // First in block: the module returns before touching the oracle.
            return Ok(ResolvedFee::flat(initial));
        }
        // Position unknown: quote the worse of the two branches, since nothing stops a pool from
        // configuring `initialFee` above its dynamic fee. Gas stays conservative too: the oracle
        // read is charged whenever the dynamic branch evaluated it.
        let dynamic = resolve_dynamic_fee(
            dfc,
            base_fee,
            current_tick,
            liquidity,
            observation_index,
            observation_cardinality,
            observations,
            execution_timestamp,
        )?;
        return Ok(ResolvedFee { fee: initial.max(dynamic.fee), ..dynamic });
    }

    resolve_dynamic_fee(
        dfc,
        base_fee,
        current_tick,
        liquidity,
        observation_index,
        observation_cardinality,
        observations,
        execution_timestamp,
    )
}

/// The dynamic branch of the module: base fee plus the TWAP-deviation component, capped.
#[expect(
    clippy::too_many_arguments,
    reason = "inputs mirror the on-chain dynamic fee module and pool state"
)]
fn resolve_dynamic_fee(
    dfc: &DynamicFeeConfig,
    base_fee: u32,
    current_tick: i32,
    liquidity: u128,
    observation_index: u16,
    observation_cardinality: u16,
    observations: &Observations,
    execution_timestamp: u32,
) -> Result<ResolvedFee, SimulationError> {
    let (dynamic_component, observed_twap) = calculate_dynamic_fee(
        dfc,
        current_tick,
        liquidity,
        observation_index,
        observation_cardinality,
        observations,
        execution_timestamp,
    )?;
    let (_, fee_cap) = dfc.scaling();
    Ok(ResolvedFee { fee: (base_fee + dynamic_component).min(fee_cap), observed_twap })
}

fn calculate_dynamic_fee(
    dfc: &DynamicFeeConfig,
    current_tick: i32,
    liquidity: u128,
    observation_index: u16,
    observation_cardinality: u16,
    observations: &Observations,
    blocktime: u32,
) -> Result<(u32, bool), SimulationError> {
    let seconds_ago = dfc.seconds_ago;
    if u32::from(observation_cardinality) < seconds_ago / MIN_SECONDS_AGO {
        // The module returns before reaching the oracle: no observe gas.
        return Ok((0, false));
    }
    // The module runs the TWAP computation for any scaling factor, so the observe gas is paid
    // whenever the guard passes (debug_traceCall of fee() on a zero-scaling pool: the observe
    // subcall burns ~50k gas). A zero factor multiplies the deviation away, so the fee does not
    // depend on what the oracle answers, and a ring this copy cannot read does not fail the quote.
    let (scaling_factor, _) = dfc.scaling();
    if scaling_factor == 0 {
        return Ok((0, true));
    }
    // The module wraps `observe` in try/catch and adds no dynamic component when it reverts,
    // which the oracle does with `OLD` when the window reaches past the oldest observation. Any
    // other failure is missing or inconsistent data in this copy of the oracle, which the chain
    // never sees, so the quote fails rather than drop a fee the pool charges.
    let (tick_cumulatives, _) = match observations.observe(
        blocktime,
        &[seconds_ago, 0],
        current_tick,
        observation_index,
        liquidity,
        observation_cardinality,
    ) {
        Ok(observed) => observed,
        Err(ObserveError::TooOld) => return Ok((0, true)),
        Err(ObserveError::Data(err)) => return Err(err),
    };
    let average = (tick_cumulatives[1] - tick_cumulatives[0]) / i64::from(seconds_ago);
    let tw_avg_tick = i32::try_from(average).map_err(|e| {
        SimulationError::FatalError(format!("Time-weighted average tick {average}: {e}"))
    })?;

    let abs_tick_delta = (current_tick - tw_avg_tick).unsigned_abs();

    let dynamic_fee = (u128::from(abs_tick_delta) * u128::from(scaling_factor)) / SCALING_PRECISION;
    let dynamic_fee = u32::try_from(dynamic_fee).map_err(|e| {
        SimulationError::FatalError(format!("Dynamic fee component {dynamic_fee}: {e}"))
    })?;
    Ok((dynamic_fee, true))
}

#[cfg(test)]
mod tests {
    use alloy::primitives::U256;
    use hex_literal::hex;
    use rstest::rstest;

    use super::*;
    use crate::evm::protocol::utils::slipstreams::observations::Observation;

    #[test]
    fn returns_initial_fee_before_first_observation_in_block() {
        let dfc = DynamicFeeConfig::new(150, 400, 6_000_000, true, 30);
        let observations = Observations::new(vec![Observation {
            block_timestamp: 99,
            initialized: true,
            ..Default::default()
        }]);

        let fee = get_dynamic_fee(&dfc, 500, 0, 1, 0, 1, &observations, 100, true)
            .expect("Failed to calculate dynamic fee");

        assert_eq!(fee, ResolvedFee::flat(30));
    }

    #[test]
    fn uses_dynamic_fee_after_observation_is_written_in_block() {
        let dfc = DynamicFeeConfig::new(150, 400, 0, true, 30);
        let observations = Observations::new(vec![Observation {
            block_timestamp: 100,
            initialized: true,
            ..Default::default()
        }]);

        let fee = get_dynamic_fee(&dfc, 500, 0, 1, 0, 1, &observations, 100, true)
            .expect("Failed to calculate dynamic fee");

        assert_eq!(fee, ResolvedFee::flat(150));
    }

    #[rstest]
    #[case::base_fee_fallback(0, 150)]
    #[case::zero_fee_indicator(ZERO_FEE_INDICATOR, 0)]
    fn interprets_initial_fee_sentinel_values(#[case] initial_fee: u32, #[case] expected_fee: u32) {
        let observations = Observations::new(vec![Observation {
            block_timestamp: 99,
            initialized: true,
            ..Default::default()
        }]);

        let dfc = DynamicFeeConfig::new(150, 400, 0, true, initial_fee);
        let fee = get_dynamic_fee(&dfc, 500, 0, 1, 0, 1, &observations, 100, true)
            .expect("Failed to calculate dynamic fee");

        assert_eq!(fee.fee, expected_fee);
    }

    #[test]
    fn test_get_dynamic_fee() {
        let dfc = DynamicFeeConfig::new(350, 550, 3000000, false, 0);

        let items: &[(u16, [u8; 32])] = &[
            (534, hex!("01000006a0000001485073e3b9c1b1ba599e933717fff778eb3ff056690b05a1")),
            (535, hex!("01000006a0000001485072f3c785d8212da7414577fff77952e1b5ec690ae2d7")),
            (2039, hex!("01000006a00000014850737217b73678a71c3a98fdfff7791d60d77e690af4cd")),
            (2040, hex!("01000006a00000014850737239d75dce70d02120fffff7791d5ae25e690af4cf")),
            (2792, hex!("01000006a0000001485073a83aca03f518567293a7fff779047fd580690afd27")),
            (2793, hex!("01000006a0000001485073a84425ed86707cf3426afff7790473eae0690afd2b")),
            (158, hex!("01000006a0000001485073c3bd34f1a8b1e3595ef2fff778f7fab090690b015b")),
            (159, hex!("01000006a0000001485073c3bfcaf719d5a10d1babfff778f7f4bb8c690b015d")),
            (346, hex!("01000006a0000001485073d0992e1120d6162dec08fff778f1d01820690b036d")),
            (347, hex!("01000006a0000001485073d0a6e39cdb5daeb0b3dcfff778f1be390e690b0373")),
            (252, hex!("01000006a0000001485073ca9b84bedd861255f8f6fff778f4ca8f18690b026d")),
            (253, hex!("01000006a0000001485073caa9f9acbba60b0ac592fff778f4c49a22690b026f")),
            (299, hex!("01000006a0000001485073cc668d277afc9908bf5afff778f35f3120690b02e7")),
            (300, hex!("01000006a0000001485073cc6cec51a251dcd597a7fff778f3593c34690b02e9")),
            (322, hex!("01000006a0000001485073ce6eb2883c6b9c109292fff778f2a688ec690b0325")),
            (323, hex!("01000006a0000001485073ce7c9a63260beda5874ffff778f2a09414690b0327")),
            (334, hex!("01000006a0000001485073cf5c7f6da6dee6f54694fff778f21d8926690b0353")),
            (335, hex!("01000006a0000001485073cf7b9869740c05f0bf44fff778f2179430690b0355")),
            (328, hex!("01000006a0000001485073cecedc4b2732bd3fb882fff778f24d3044690b0343")),
            (329, hex!("01000006a0000001485073ced7e92fc61bfda7ccd4fff778f2414694690b0347")),
            (331, hex!("01000006a0000001485073cee01b7e722a6b0763d3fff778f2355ce2690b034b")),
            (332, hex!("01000006a0000001485073ceff347a3f578a02dc83fff778f22f67f6690b034d")),
        ];
        let mut obs = Observations::new(vec![]);
        for (idx, bytes) in items.iter().copied() {
            assert!(obs
                .upsert_observation(idx, &bytes)
                .is_ok());
        }

        let dynamic_fee = get_dynamic_fee(
            &dfc,
            362,
            -195239,
            1102101691356476042,
            534,
            3010,
            &obs,
            1762330021,
            true,
        )
        .expect("Failed to calculate dynamic fee");

        assert_eq!(dynamic_fee, ResolvedFee { fee: 380, observed_twap: true });
    }

    #[test]
    fn applies_partial_config_updates_without_replacing_unchanged_fields() {
        let mut config = DynamicFeeConfig::new(100, 1_000, 5_000_000, true, 50);

        config
            .update_from_attributes(&HashMap::from([(
                "dfc_baseFee".to_string(),
                Bytes::from(200_u32.to_be_bytes()),
            )]))
            .expect("partial dynamic fee update should be valid");

        assert_eq!(config, DynamicFeeConfig::new(200, 1_000, 5_000_000, true, 50));
    }

    #[rstest]
    #[case::missing_module(None)]
    #[case::unsupported_module(Some(Bytes::from([0x11; 20])))]
    fn from_attributes_defaults_for_missing_or_unsupported_module(#[case] module: Option<Bytes>) {
        // Attributes are present but untrusted without a supported marker: fall back to default.
        let mut attributes = HashMap::from([
            ("dfc_baseFee".to_string(), Bytes::from(200_u32.to_be_bytes())),
            ("dfc_feeCap".to_string(), Bytes::from(1_000_u32.to_be_bytes())),
            ("dfc_scalingFactor".to_string(), Bytes::from(5_000_000_u64.to_be_bytes())),
        ]);
        if let Some(module) = module {
            attributes.insert(DYNAMIC_FEE_MODULE_ATTRIBUTE.to_string(), module);
        }

        assert_eq!(DynamicFeeConfig::from_attributes(&attributes), Ok(DynamicFeeConfig::default()));
    }

    #[test]
    fn default_config_falls_back_to_static_default_fee() {
        // base_fee == 0 must resolve to the pool's static default fee (3000 here).
        let dfc = DynamicFeeConfig::default();
        let observations = Observations::new(vec![Observation {
            block_timestamp: 100,
            initialized: true,
            ..Default::default()
        }]);

        let fee = get_dynamic_fee(&dfc, 3000, 0, 1, 0, 1, &observations, 100, true)
            .expect("Failed to calculate dynamic fee");

        assert_eq!(fee, ResolvedFee::flat(3000));
    }

    /// A ring of `cardinality` slots holding the given `(index, timestamp, tick cumulative,
    /// seconds-per-liquidity cumulative)` observations; every other slot is unwritten.
    fn ring(cardinality: usize, written: &[(usize, u32, i64, &str)]) -> Observations {
        let mut slots = vec![Observation::default(); cardinality];
        for &(index, block_timestamp, tick_cumulative, seconds_per_liquidity) in written {
            slots[index] = Observation {
                block_timestamp,
                tick_cumulative,
                seconds_per_liquidity_cumulative_x128: U256::from_str_radix(
                    seconds_per_liquidity,
                    10,
                )
                .expect("decimal cumulative"),
                initialized: true,
            };
        }
        Observations::new(slots)
    }

    #[test]
    fn observe_reverting_old_charges_no_dynamic_fee() {
        // The only observation is younger than the 600 s window, so `observe` reverts `OLD`. The
        // module catches it: base fee only, and the attempted observe still costs gas.
        let dfc = DynamicFeeConfig::new(0, 10_000, 1_000_000, false, 0);
        let observations = ring(300, &[(0, 999_500, 0, "0")]);

        let fee = get_dynamic_fee(&dfc, 3000, 7, 1, 0, 300, &observations, 1_000_000, true)
            .expect("an OLD revert falls back to the base fee");

        assert_eq!(fee, ResolvedFee { fee: 3000, observed_twap: true });
    }

    #[test]
    fn observation_data_error_fails_the_quote() {
        // Slot 5 is the pool's current index but holds nothing: the chain cannot be in this
        // state, so it is missing data here, not an `OLD` revert to absorb.
        let dfc = DynamicFeeConfig::new(0, 10_000, 1_000_000, false, 0);
        let observations = Observations::new(vec![Observation {
            block_timestamp: 999_000,
            initialized: true,
            ..Default::default()
        }]);

        let result = get_dynamic_fee(&dfc, 3000, 7, 1, 5, 300, &observations, 1_000_000, true);

        assert!(result.is_err(), "got {result:?}");
    }

    #[rstest]
    #[case::dynamic_fee(DynamicFeeConfig::new(0, 10_000, 1_000_000, false, 0), None)]
    #[case::zero_scaling(
        DynamicFeeConfig::default(),
        Some(ResolvedFee { fee: 3000, observed_twap: true })
    )]
    fn ring_missing_the_slots_around_the_target(
        #[case] dfc: DynamicFeeConfig,
        #[case] expected: Option<ResolvedFee>,
    ) {
        // Cardinality 300 passes the 600 s guard. The current slot (5) and the oldest (6) are
        // here, so a swap can still write the next observation, but the slots that bracket the
        // target (999,400) are missing: the binary search cannot answer. Only a zero scaling
        // factor, which makes the fee independent of the oracle, still quotes.
        let observations = ring(300, &[(5, 999_990, 0, "0"), (6, 999_000, 0, "0")]);

        let result = get_dynamic_fee(&dfc, 3000, 7, 1, 5, 300, &observations, 1_000_000, false);

        match expected {
            Some(fee) => assert_eq!(result.expect("quotes"), fee),
            None => assert!(result.is_err(), "got {result:?}"),
        }
    }

    #[test]
    fn young_ring_reads_unwritten_slots_as_uninitialized() {
        // Robinhood pool 0x8132252bd65e7c03f7b57739e1db1c58d6ee792f at block 61,011,933: slots
        // 0-2 written, cardinality 500, the rest prefilled but unwritten. Its module, Topaz's
        // 0x0Dca13b1039277d82B27ADd86d06195B8E9BBfDb, has `secondsAgo` 600 and returns
        // `dynamicFeeConfig` (50, 500, 1e7); `getFee` returns 110 on chain, 50 base plus 6 ticks
        // of TWAP deviation at 1e7 / 1e6.
        let dfc = DynamicFeeConfig::new(50, 500, 10_000_000, false, 0);
        let observations = ring(
            500,
            &[
                (0, 1_789_205_466, -3_753_782_792, "4871078707023353428616415205"),
                (1, 1_789_206_050, -3_869_381_504, "4943578347386704671325331035"),
                (2, 1_789_206_560, -3_970_336_004, "5006891389484836749718391092"),
            ],
        );

        let fee = get_dynamic_fee(
            &dfc,
            500,
            -197_954,
            2_741_046_731_899_156,
            2,
            500,
            &observations,
            1_789_206_560,
            true,
        )
        .expect("fee");

        assert_eq!(fee, ResolvedFee { fee: 110, observed_twap: true });
    }

    #[test]
    fn twap_window_is_the_modules_seconds_ago() {
        // Base pool 0x3fe04a59ebd38cf06080a6f60a98d124eb59392a at block 53,246,841 (ts
        // 1,793,283,029), on module 0x87D8 whose `secondsAgo` is 30: config (250, 10_000, 1.25e8),
        // tick -198,816, index 35 of 1,801. The slots are the ones both windows' binary searches
        // read on chain. `getFee` returns 625: a 3-tick deviation over 30 s. A 600 s window
        // deviates by 9 ticks and would charge 1,375.
        let attributes = HashMap::from([
            (
                DYNAMIC_FEE_MODULE_ATTRIBUTE.to_string(),
                Bytes::from(hex!("87D8f999BBa9343E8099552426775B51C338E8CB")),
            ),
            ("dfc_baseFee".to_string(), Bytes::from(250_u32.to_be_bytes())),
            ("dfc_feeCap".to_string(), Bytes::from(10_000_u32.to_be_bytes())),
            ("dfc_scalingFactor".to_string(), Bytes::from(125_000_000_u64.to_be_bytes())),
        ]);
        let dfc = DynamicFeeConfig::from_attributes(&attributes).expect("supported module");
        let observations = ring(
            1801,
            &[
                (0, 1793282575, -3275662076386, "4825203962939739569257789745571497048595234"),
                (7, 1793282623, -3275671619302, "4825203962939739569276893739575444000335090"),
                (8, 1793282633, -3275673607392, "4825203962939739569280873738326266281947560"),
                (21, 1793282821, -3275710982996, "4825203962939739569355697714841725176262000"),
                (22, 1793282845, -3275715754508, "4825203962939739569365249711843698652131929"),
                (28, 1793282925, -3275731659364, "4825203962939739569397089714845879783423417"),
                (29, 1793282931, -3275732852212, "4825203962939739569399477720594174591586762"),
                (30, 1793282943, -3275735237920, "4825203962939739569404253732090764207913453"),
                (31, 1793282975, -3275741599840, "4825203962939739569416989762748336518117962"),
                (32, 1793283009, -3275748359448, "4825203962939739569430521795322007097710253"),
                (33, 1793283013, -3275749154700, "4825203962939739569432113799154203636485816"),
                (35, 1793283025, -3275751540474, "4825203962939739569436889810650793252812506"),
                (36, 1793244467, -3268084691080, "4825203962939739551051757126085317697368620"),
                (936, 1793265129, -3272193430366, "4825203962939739562297101138547303077297501"),
                (937, 1793265139, -3272195418466, "4825203962939739562301084452370714260727039"),
                (1386, 1793276999, -3274553455060, "4825203962939739567024672774306500132937332"),
                (1387, 1793277003, -3274554250332, "4825203962939739567026265905404686576486673"),
                (1611, 1793280663, -3275281921370, "4825203962939739568483314884286832984753085"),
                (1612, 1793280665, -3275282318968, "4825203962939739568484112377091106362391932"),
                (1724, 1793281749, -3275497853804, "4825203962939739568928959549000027675629456"),
                (1725, 1793281759, -3275499842184, "4825203962939739568932939571799223800243474"),
                (1780, 1793282351, -3275617544942, "4825203962939739569168558897552147796963386"),
                (1781, 1793282359, -3275619135318, "4825203962939739569171748849458536199122231"),
                (1787, 1793282393, -3275625894320, "4825203962939739569185306145060686908297322"),
                (1788, 1793282399, -3275627087114, "4825203962939739569187698608990478209916456"),
                (1790, 1793282417, -3275630665516, "4825203962939739569194874512553419470556641"),
                (1791, 1793282427, -3275632653536, "4825203962939739569198854511304241752169111"),
                (1792, 1793282457, -3275638617626, "4825203962939739569210794507556708597006522"),
                (1793, 1793282459, -3275639015230, "4825203962939739569211590507306873053329016"),
                (1794, 1793282485, -3275644184004, "4825203962939739569221957851002635360345264"),
                (1795, 1793282501, -3275647364804, "4825203962939739569228337754815412164662955"),
            ],
        );
        let fee_over = |dfc: &DynamicFeeConfig| {
            get_dynamic_fee(
                dfc,
                3000,
                -198_816,
                854_978_763_339_884_583,
                35,
                1801,
                &observations,
                1_793_283_029,
                true,
            )
            .expect("fee")
            .fee
        };

        assert_eq!(fee_over(&dfc), 625);
        assert_eq!(fee_over(&dfc.with_seconds_ago(DEFAULT_SECONDS_AGO)), 1375);
    }

    #[test]
    fn base_module_at_480_seconds_prices_like_the_chain() {
        // Base cbETH/cbBTC pool 0x8bb9eaf3c5a906d20c4cc10ea2f73a3ac2d5d41a at block 52,513,105
        // (ts 1,791,815,557), on module 0xF4Ec whose `secondsAgo` is 480: config (300, 1_000,
        // 7.5e6), tick -263,836, index 507 of 901. The slots are the ones both windows' binary
        // searches read on chain. `getFee` returns 337: a 5-tick deviation over 480 s. The 600 s
        // window of #1591 deviates by 3 ticks and would charge 322.
        let attributes = HashMap::from([
            (
                DYNAMIC_FEE_MODULE_ATTRIBUTE.to_string(),
                Bytes::from(hex!("F4Ecd78EBEB6d36CF7f80B5B6B41453515fe2785")),
            ),
            ("dfc_baseFee".to_string(), Bytes::from(300_u32.to_be_bytes())),
            ("dfc_feeCap".to_string(), Bytes::from(1_000_u32.to_be_bytes())),
            ("dfc_scalingFactor".to_string(), Bytes::from(7_500_000_u64.to_be_bytes())),
        ]);
        let dfc = DynamicFeeConfig::from_attributes(&attributes).expect("supported module");
        let observations = ring(
            901,
            &[
                (0, 1791813651, -6225184870600, "113129906854949101032879245043523"),
                (57, 1791813765, -6225214944102, "113129907753944480580933266810112"),
                (58, 1791813767, -6225215471708, "113129907765759262023836511478038"),
                (282, 1791814395, -6225381145240, "113129912581052882935536344536600"),
                (283, 1791814397, -6225381672874, "113129912590323418798144005406647"),
                (310, 1791814943, -6225525721148, "113129918593435750256585310503962"),
                (311, 1791814949, -6225527304146, "113129918657527784950822346558541"),
                (312, 1791814951, -6225527831812, "113129918695528193026047911919658"),
                (313, 1791814969, -6225532580824, "113129919037531865703078000169719"),
                (314, 1791815031, -6225548938532, "113129919618017995603094449920883"),
                (317, 1791815061, -6225556853654, "113129920149474018639092377018715"),
                (318, 1791815063, -6225557381332, "113129920187474426714317942379832"),
                (319, 1791815081, -6225562130434, "113129920360160083856200526206862"),
                (320, 1791815121, -6225572684034, "113129921120168245360711833429220"),
                (321, 1791815129, -6225574794762, "113129921272169877661614094873691"),
                (324, 1791815173, -6225586403852, "113129922092981882988410931414424"),
                (325, 1791815175, -6225586931538, "113129922115785318735470895371682"),
                (338, 1791815201, -6225593791456, "113129922347791103808755751604466"),
                (339, 1791815203, -6225594319144, "113129922360966754226491149631315"),
                (395, 1791815315, -6225623869672, "113129923098193053933160913001926"),
                (396, 1791815317, -6225624397360, "113129923110345310044020478962282"),
                (507, 1791815557, -6225687718770, "113129925012933844598717895315471"),
                (508, 1791812851, -6224973825442, "113129901198660329442281974110815"),
            ],
        );
        let fee_over = |dfc: &DynamicFeeConfig| {
            get_dynamic_fee(
                dfc,
                300,
                -263_836,
                63_195_507_905_080_230,
                507,
                901,
                &observations,
                1_791_815_557,
                true,
            )
            .expect("fee")
            .fee
        };

        assert_eq!(dfc.seconds_ago, 480);
        assert_eq!(fee_over(&dfc), 337);
        assert_eq!(fee_over(&dfc.with_seconds_ago(DEFAULT_SECONDS_AGO)), 322);
    }

    #[rstest]
    #[case::window_480_above_240(hex!("090b2A6bb475c00e2256e2095A60887cD710803b"), 250, 1000, true)]
    #[case::window_30_above_15(hex!("87D8f999BBa9343E8099552426775B51C338E8CB"), 20, 1000, true)]
    #[case::window_30_below_15(hex!("87D8f999BBa9343E8099552426775B51C338E8CB"), 14, 500, false)]
    #[case::window_600_below_300(hex!("a8Bdc945bE050E451C97f935d7c0D6B0087cF94c"), 250, 500, false)]
    fn minimum_cardinality_is_half_the_modules_seconds_ago(
        #[case] module: [u8; 20],
        #[case] cardinality: u16,
        #[case] expected_fee: u32,
        #[case] expected_observed_twap: bool,
    ) {
        // A full ring with one observation every 2 s at tick -500 against a current tick of 0:
        // when the module reads the oracle, a scaling factor of 1e6 adds 500 to the 500 base fee.
        // Below `secondsAgo / 2` it returns before reading it, so a fixed 600 s threshold would
        // skip the first two cases.
        let attributes = HashMap::from([
            (DYNAMIC_FEE_MODULE_ATTRIBUTE.to_string(), Bytes::from(module)),
            ("dfc_baseFee".to_string(), Bytes::from(500_u32.to_be_bytes())),
            ("dfc_feeCap".to_string(), Bytes::from(10_000_u32.to_be_bytes())),
            ("dfc_scalingFactor".to_string(), Bytes::from(1_000_000_u64.to_be_bytes())),
        ]);
        let dfc = DynamicFeeConfig::from_attributes(&attributes).expect("supported module");
        let mut written = Vec::new();
        for slot in 0..cardinality {
            written.push((
                usize::from(slot),
                1_000 + 2 * u32::from(slot),
                -1_000 * i64::from(slot),
                "0",
            ));
        }
        let observations = ring(usize::from(cardinality), &written);
        let newest = cardinality - 1;

        let fee = get_dynamic_fee(
            &dfc,
            3000,
            0,
            1,
            newest,
            cardinality,
            &observations,
            1_000 + 2 * u32::from(newest),
            true,
        )
        .expect("fee");

        assert_eq!(fee, ResolvedFee { fee: expected_fee, observed_twap: expected_observed_twap });
    }

    #[test]
    fn zero_scaling_still_pays_for_the_observe() {
        // On chain the module runs `observe` at a zero scaling factor too, so the observe gas is
        // paid, and the factor multiplies the deviation away. Only the cardinality guard skips
        // the oracle.
        let dfc = DynamicFeeConfig::new(2700, 0, 0, false, 0);
        let observations = Observations::new(vec![
            Observation { block_timestamp: 999_000, initialized: true, ..Default::default() },
            Observation { block_timestamp: 999_500, initialized: true, ..Default::default() },
        ]);

        let fee = get_dynamic_fee(&dfc, 500, 0, 1, 1, 300, &observations, 1_000_000, true)
            .expect("fee should be computable");
        assert_eq!(fee, ResolvedFee { fee: 2700, observed_twap: true });

        let guarded = get_dynamic_fee(&dfc, 500, 0, 1, 0, 1, &observations, 1_000_000, true)
            .expect("fee should be computable");
        assert_eq!(guarded, ResolvedFee::flat(2700), "cardinality guard skips the oracle");
    }
}