@paraswap/dex-lib 4.8.36 → 4.8.37-native-dex-math.1

package/native/src/math/tick.rs

@@ -0,0 +1,239 @@
+use ethnum::{I256, U256};
+use std::collections::HashMap;
+use super::liquidity_math;
+
+/// Information stored for each initialized individual tick.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TickInfo {
+    pub liquidity_gross: U256,
+    pub liquidity_net: I256,
+    pub initialized: bool,
+}
+
+impl Default for TickInfo {
+    fn default() -> Self {
+        TickInfo {
+            liquidity_gross: U256::ZERO,
+            liquidity_net: I256::ZERO,
+            initialized: false,
+        }
+    }
+}
+
+/// Truncate an I256 to signed 128-bit range, matching `BigInt.asIntN(128, x)`.
+fn as_int128(val: I256) -> I256 {
+    // Mask to 128 bits, then sign-extend from bit 127
+    let mask: I256 = (I256::ONE << 128) - I256::ONE;
+    let masked = val & mask;
+    if masked & (I256::ONE << 127) != I256::ZERO {
+        masked | !mask
+    } else {
+        masked
+    }
+}
+
+/// Updates a tick and returns whether the tick was flipped from initialized to uninitialized,
+/// or vice versa.
+///
+/// Parameters:
+/// - `ticks`: mutable reference to tick storage
+/// - `tick`: the tick to update
+/// - `tick_current`: the current tick
+/// - `liquidity_delta`: signed liquidity change
+/// - `upper`: true if this is the upper tick of a position being modified
+/// - `max_liquidity`: maximum liquidity per tick
+///
+/// Returns `true` if the tick was flipped (transitioned between zero and non-zero gross liquidity).
+pub fn update(
+    ticks: &mut HashMap<i32, TickInfo>,
+    tick: i32,
+    _tick_current: I256,
+    liquidity_delta: I256,
+    upper: bool,
+    max_liquidity: U256,
+) -> bool {
+    let info = ticks.entry(tick).or_insert_with(TickInfo::default);
+
+    let liquidity_gross_before = info.liquidity_gross;
+    let liquidity_gross_after = liquidity_math::add_delta(liquidity_gross_before, liquidity_delta);
+
+    assert!(
+        liquidity_gross_after <= max_liquidity,
+        "LO"
+    );
+
+    let flipped = (liquidity_gross_after == U256::ZERO) != (liquidity_gross_before == U256::ZERO);
+
+    if liquidity_gross_before == U256::ZERO {
+        info.initialized = true;
+    }
+
+    info.liquidity_gross = liquidity_gross_after;
+
+    // info.liquidityNet = upper
+    //   ? BigInt.asIntN(128, BigInt.asIntN(256, info.liquidityNet) - liquidityDelta)
+    //   : BigInt.asIntN(128, BigInt.asIntN(256, info.liquidityNet) + liquidityDelta)
+    let net_i256 = info.liquidity_net; // already I256 (256-bit signed)
+    info.liquidity_net = if upper {
+        as_int128(net_i256 - liquidity_delta)
+    } else {
+        as_int128(net_i256 + liquidity_delta)
+    };
+
+    flipped
+}
+
+/// Clears tick data. Equivalent to `delete state.ticks[tick]`.
+pub fn clear(ticks: &mut HashMap<i32, TickInfo>, tick: i32) {
+    ticks.remove(&tick);
+}
+
+/// Transitions to the next tick as needed by crossing an initialized tick.
+/// Returns the `liquidity_net` of the crossed tick.
+pub fn cross(ticks: &HashMap<i32, TickInfo>, tick: i32) -> I256 {
+    let info = ticks.get(&tick).expect("tick not found in cross");
+    info.liquidity_net
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_update_new_tick() {
+        let mut ticks = HashMap::new();
+        let flipped = update(
+            &mut ticks,
+            100,
+            I256::from(50i64),
+            I256::from(1000i64),
+            false,
+            U256::from(1_000_000u64),
+        );
+        assert!(flipped);
+        let info = ticks.get(&100).unwrap();
+        assert_eq!(info.liquidity_gross, U256::from(1000u64));
+        assert_eq!(info.liquidity_net, I256::from(1000i64));
+        assert!(info.initialized);
+    }
+
+    #[test]
+    fn test_update_existing_tick() {
+        let mut ticks = HashMap::new();
+        update(
+            &mut ticks,
+            100,
+            I256::from(50i64),
+            I256::from(1000i64),
+            false,
+            U256::from(1_000_000u64),
+        );
+        let flipped = update(
+            &mut ticks,
+            100,
+            I256::from(50i64),
+            I256::from(500i64),
+            false,
+            U256::from(1_000_000u64),
+        );
+        assert!(!flipped); // Not flipped because it was already initialized
+        let info = ticks.get(&100).unwrap();
+        assert_eq!(info.liquidity_gross, U256::from(1500u64));
+        assert_eq!(info.liquidity_net, I256::from(1500i64));
+    }
+
+    #[test]
+    fn test_update_upper_tick() {
+        let mut ticks = HashMap::new();
+        let flipped = update(
+            &mut ticks,
+            200,
+            I256::from(50i64),
+            I256::from(1000i64),
+            true,
+            U256::from(1_000_000u64),
+        );
+        assert!(flipped);
+        let info = ticks.get(&200).unwrap();
+        assert_eq!(info.liquidity_gross, U256::from(1000u64));
+        // Upper tick: liquidityNet = -liquidityDelta
+        assert_eq!(info.liquidity_net, I256::from(-1000i64));
+    }
+
+    #[test]
+    fn test_update_removes_liquidity_flips() {
+        let mut ticks = HashMap::new();
+        update(
+            &mut ticks,
+            100,
+            I256::from(50i64),
+            I256::from(1000i64),
+            false,
+            U256::from(1_000_000u64),
+        );
+        let flipped = update(
+            &mut ticks,
+            100,
+            I256::from(50i64),
+            I256::from(-1000i64),
+            false,
+            U256::from(1_000_000u64),
+        );
+        assert!(flipped);
+        let info = ticks.get(&100).unwrap();
+        assert_eq!(info.liquidity_gross, U256::ZERO);
+        assert_eq!(info.liquidity_net, I256::ZERO);
+    }
+
+    #[test]
+    #[should_panic(expected = "LO")]
+    fn test_update_exceeds_max_liquidity() {
+        let mut ticks = HashMap::new();
+        update(
+            &mut ticks,
+            100,
+            I256::from(50i64),
+            I256::from(2000i64),
+            false,
+            U256::from(1000u64), // max is 1000
+        );
+    }
+
+    #[test]
+    fn test_clear() {
+        let mut ticks = HashMap::new();
+        update(
+            &mut ticks,
+            100,
+            I256::from(50i64),
+            I256::from(1000i64),
+            false,
+            U256::from(1_000_000u64),
+        );
+        assert!(ticks.contains_key(&100));
+        clear(&mut ticks, 100);
+        assert!(!ticks.contains_key(&100));
+    }
+
+    #[test]
+    fn test_cross() {
+        let mut ticks = HashMap::new();
+        update(
+            &mut ticks,
+            100,
+            I256::from(50i64),
+            I256::from(1000i64),
+            false,
+            U256::from(1_000_000u64),
+        );
+        let net = cross(&ticks, 100);
+        assert_eq!(net, I256::from(1000i64));
+    }
+
+    #[test]
+    #[should_panic]
+    fn test_cross_nonexistent_tick() {
+        let ticks = HashMap::new();
+        cross(&ticks, 100);
+    }
+}

package/native/src/math/tick_bitmap.rs

@@ -0,0 +1,312 @@
+use ethnum::{I256, U256};
+use std::collections::HashMap;
+use super::bit_math;
+
+/// Computes the word position and bit position within that word for a given tick.
+///
+/// Equivalent to: `[BigInt.asIntN(16, tick >> 8), BigInt.asUintN(8, tick % 256)]`
+///
+/// Returns `(word_pos, bit_pos)` where `word_pos` is an i16 and `bit_pos` is a u8.
+pub fn position(tick: I256) -> (i16, u8) {
+    // word_pos = asIntN(16, tick >> 8)
+    let shifted = tick >> 8u32;
+    // Take the low 16 bits and sign-extend from bit 15
+    let word_pos = shifted.0[0] as i16;
+
+    // bit_pos = asUintN(8, tick % 256)
+    // BigInt.asUintN(8, x) takes the low 8 bits of the two's complement representation.
+    let bit_pos = tick.0[0] as u8;
+
+    (word_pos, bit_pos)
+}
+
+/// Flips the tick's initialized state in the bitmap.
+///
+/// `tick` must be divisible by `tick_spacing`.
+pub fn flip_tick(bitmap: &mut HashMap<i16, U256>, tick: I256, tick_spacing: I256) {
+    assert!(
+        tick % tick_spacing == I256::ZERO,
+        "tick % tick_spacing == 0"
+    );
+    let (word_pos, bit_pos) = position(tick / tick_spacing);
+    let mask = U256::ONE << bit_pos;
+
+    let entry = bitmap.entry(word_pos).or_insert(U256::ZERO);
+    *entry ^= mask;
+}
+
+/// Returns the next initialized tick within one word of the current tick.
+///
+/// `lte` indicates whether we're searching to the left (less-than-or-equal) or right.
+/// `is_price_query` controls whether bounds are checked against bitmap range.
+/// `bitmap_range` is (lower, upper) inclusive bounds for valid wordPos values.
+///
+/// Returns `Ok((next_tick, initialized))` or `Err` if out of bitmap range.
+pub fn next_initialized_tick_within_one_word(
+    bitmap: &HashMap<i16, U256>,
+    tick: I256,
+    tick_spacing: I256,
+    lte: bool,
+    is_price_query: bool,
+    bitmap_range: Option<(i16, i16)>,
+) -> Result<(I256, bool), &'static str> {
+    let mut compressed = tick / tick_spacing;
+    if tick < I256::ZERO && tick % tick_spacing != I256::ZERO {
+        compressed = compressed - I256::ONE;
+    }
+
+    if lte {
+        let (word_pos, bit_pos) = position(compressed);
+
+        // Bounds check — mirrors TS isWordPosOut
+        if is_price_query {
+            if let Some((lower, upper)) = bitmap_range {
+                if word_pos < lower || word_pos > upper {
+                    return Err("INVALID_TICK_BIT_MAP_RANGES");
+                }
+            }
+        }
+
+        let mask = (U256::ONE << bit_pos) - U256::ONE + (U256::ONE << bit_pos);
+        let tick_bitmap_value = bitmap.get(&word_pos).copied().unwrap_or(U256::ZERO);
+        let masked = tick_bitmap_value & mask;
+
+        let initialized = masked != U256::ZERO;
+        let next = if initialized {
+            let msb = bit_math::most_significant_bit(masked);
+            let diff = I256::from(bit_pos as i32) - I256::from(msb as i32);
+            let diff_i24 = sign_extend_i24(diff);
+            (compressed - diff_i24) * tick_spacing
+        } else {
+            let bp = I256::from(bit_pos as i32);
+            let bp_i24 = sign_extend_i24(bp);
+            (compressed - bp_i24) * tick_spacing
+        };
+
+        Ok((next, initialized))
+    } else {
+        let (word_pos, bit_pos) = position(compressed + I256::ONE);
+
+        // Bounds check
+        if is_price_query {
+            if let Some((lower, upper)) = bitmap_range {
+                if word_pos < lower || word_pos > upper {
+                    return Err("INVALID_TICK_BIT_MAP_RANGES");
+                }
+            }
+        }
+
+        let mask = !((U256::ONE << bit_pos) - U256::ONE);
+        let tick_bitmap_value = bitmap.get(&word_pos).copied().unwrap_or(U256::ZERO);
+        let masked = tick_bitmap_value & mask;
+
+        let initialized = masked != U256::ZERO;
+        let next = if initialized {
+            let lsb = bit_math::least_significant_bit(masked);
+            let diff = I256::from(lsb as i32) - I256::from(bit_pos as i32);
+            let diff_i24 = sign_extend_i24(diff);
+            (compressed + I256::ONE + diff_i24) * tick_spacing
+        } else {
+            let diff = I256::from(255i32) - I256::from(bit_pos as i32);
+            let diff_i24 = sign_extend_i24(diff);
+            (compressed + I256::ONE + diff_i24) * tick_spacing
+        };
+
+        Ok((next, initialized))
+    }
+}
+
+/// Convenience wrapper without bounds checking (for tests and non-pricing calls).
+#[allow(dead_code)]
+fn next_initialized_tick_within_one_word_unchecked(
+    bitmap: &HashMap<i16, U256>,
+    tick: I256,
+    tick_spacing: I256,
+    lte: bool,
+    is_price_query: bool,
+) -> (I256, bool) {
+    next_initialized_tick_within_one_word(bitmap, tick, tick_spacing, lte, is_price_query, None).unwrap()
+}
+
+/// Sign-extend a value to 24-bit signed (equivalent to BigInt.asIntN(24, x)).
+fn sign_extend_i24(val: I256) -> I256 {
+    let mask = I256::new(0x00FFFFFF);
+    let masked = val & mask;
+    if masked & I256::new(0x00800000) != I256::ZERO {
+        masked | !mask
+    } else {
+        masked
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_position_zero() {
+        let (word, bit) = position(I256::ZERO);
+        assert_eq!(word, 0);
+        assert_eq!(bit, 0);
+    }
+
+    #[test]
+    fn test_position_positive() {
+        // tick = 256 => word_pos = 256 >> 8 = 1, bit_pos = 256 % 256 = 0
+        let (word, bit) = position(I256::from(256i64));
+        assert_eq!(word, 1);
+        assert_eq!(bit, 0);
+
+        // tick = 257 => word_pos = 257 >> 8 = 1, bit_pos = 257 % 256 = 1
+        let (word, bit) = position(I256::from(257i64));
+        assert_eq!(word, 1);
+        assert_eq!(bit, 1);
+    }
+
+    #[test]
+    fn test_position_negative() {
+        // tick = -1 => in two's complement, tick >> 8 = -1 => word_pos = -1
+        // bit_pos = low 8 bits of -1 = 0xFF = 255
+        let (word, bit) = position(I256::from(-1i64));
+        assert_eq!(word, -1);
+        assert_eq!(bit, 255);
+
+        // tick = -256 => tick >> 8 = -1, bit_pos = low 8 bits of -256 = 0
+        let (word, bit) = position(I256::from(-256i64));
+        assert_eq!(word, -1);
+        assert_eq!(bit, 0);
+    }
+
+    #[test]
+    fn test_flip_tick() {
+        let mut bitmap = HashMap::new();
+        let tick_spacing = I256::ONE;
+
+        // Flip tick 0
+        flip_tick(&mut bitmap, I256::ZERO, tick_spacing);
+        let (word, bit) = position(I256::ZERO);
+        assert_eq!(*bitmap.get(&word).unwrap() & (U256::ONE << bit), U256::ONE);
+
+        // Flip tick 0 again (should toggle back to 0)
+        flip_tick(&mut bitmap, I256::ZERO, tick_spacing);
+        assert_eq!(
+            *bitmap.get(&word).unwrap() & (U256::ONE << bit),
+            U256::ZERO
+        );
+    }
+
+    #[test]
+    fn test_flip_tick_with_spacing() {
+        let mut bitmap = HashMap::new();
+        let tick_spacing = I256::from(60i64);
+
+        flip_tick(&mut bitmap, I256::from(120i64), tick_spacing);
+        // 120 / 60 = 2, position(2) = (0, 2)
+        let val = *bitmap.get(&0i16).unwrap_or(&U256::ZERO);
+        assert_eq!(val & (U256::ONE << 2), U256::from(4u64));
+    }
+
+    #[test]
+    #[should_panic]
+    fn test_flip_tick_not_aligned() {
+        let mut bitmap = HashMap::new();
+        flip_tick(&mut bitmap, I256::from(1i64), I256::from(60i64));
+    }
+
+    #[test]
+    fn test_next_initialized_tick_lte() {
+        let mut bitmap = HashMap::new();
+        let tick_spacing = I256::ONE;
+
+        // Set tick 10 as initialized
+        flip_tick(&mut bitmap, I256::from(10i64), tick_spacing);
+
+        // Search from tick 15, going left (lte=true)
+        let (next, initialized) = next_initialized_tick_within_one_word_unchecked(
+            &bitmap,
+            I256::from(15i64),
+            tick_spacing,
+            true,
+            false,
+        );
+        assert!(initialized);
+        assert_eq!(next, I256::from(10i64));
+    }
+
+    #[test]
+    fn test_next_initialized_tick_gt() {
+        let mut bitmap = HashMap::new();
+        let tick_spacing = I256::ONE;
+
+        // Set tick 20 as initialized
+        flip_tick(&mut bitmap, I256::from(20i64), tick_spacing);
+
+        // Search from tick 10, going right (lte=false)
+        let (next, initialized) = next_initialized_tick_within_one_word_unchecked(
+            &bitmap,
+            I256::from(10i64),
+            tick_spacing,
+            false,
+            false,
+        );
+        assert!(initialized);
+        assert_eq!(next, I256::from(20i64));
+    }
+
+    #[test]
+    fn test_next_initialized_tick_not_found_lte() {
+        let bitmap = HashMap::new();
+        let tick_spacing = I256::ONE;
+
+        // No ticks initialized; searching left from tick 100
+        let (next, initialized) = next_initialized_tick_within_one_word_unchecked(
+            &bitmap,
+            I256::from(100i64),
+            tick_spacing,
+            true,
+            false,
+        );
+        assert!(!initialized);
+        // Should return the leftmost tick in this word
+        // compressed = 100, position(100) = (0, 100), next = (100 - 100) * 1 = 0
+        assert_eq!(next, I256::ZERO);
+    }
+
+    #[test]
+    fn test_next_initialized_tick_not_found_gt() {
+        let bitmap = HashMap::new();
+        let tick_spacing = I256::ONE;
+
+        // No ticks initialized; searching right from tick 0
+        let (next, initialized) = next_initialized_tick_within_one_word_unchecked(
+            &bitmap,
+            I256::ZERO,
+            tick_spacing,
+            false,
+            false,
+        );
+        assert!(!initialized);
+        // compressed = 0, position(1) = (0, 1), next = (0 + 1 + (255 - 1)) * 1 = 255
+        assert_eq!(next, I256::from(255i64));
+    }
+
+    #[test]
+    fn test_next_initialized_tick_negative_range() {
+        let mut bitmap = HashMap::new();
+        let tick_spacing = I256::ONE;
+
+        // Set tick -10 as initialized
+        flip_tick(&mut bitmap, I256::from(-10i64), tick_spacing);
+
+        // Search from tick -5, going left
+        let (next, initialized) = next_initialized_tick_within_one_word_unchecked(
+            &bitmap,
+            I256::from(-5i64),
+            tick_spacing,
+            true,
+            false,
+        );
+        assert!(initialized);
+        assert_eq!(next, I256::from(-10i64));
+    }
+}